.TH LIBNORMALFORM_REF 3 LIBNORMALFORM
.SH NAME
libnormalform_ref \- Acquire new reference

.SH SYNOPSIS
.nf
#include <libnormalform.h>

LIBNORMALFORM_SENTENCE *libnormalform_ref(LIBNORMALFORM_SENTENCE *\fIx\fP);
.fi
.PP
Link with
.IR -lnormalform .

.SH DESCRIPTION
The
.BR libnormalform_ref ()
function increases the reference count of
.I x
by one and returns
.I x
(it is advisable to treat the return pointer
as unique but that it must be used in the
same thread as the input pointer),
letting the application input the sentence
object to multiple sentences or multiple
times in the same sentence.
.PP
The returned pointer shall either be
deallocated with the
.BR libnormalform_free (3)
function or be relinquished by being
used as part of another sentence.

.SH RETURN VALUE
Upon successful completion, the
.BR libnormalform_ref ()
function returns
.IR x ;
otherwise, the function returns
.I NULL
and sets
.I errno
to indicate the error.

.SH ERRORS
The
.BR libnormalform_ref ()
function fails if:
.TP
.B ENOMEM
The reference count of
.I x
was already maximised (at
.IR SIZE_MAX );
this would imply that something is wrong in the
application, and it might as well abort.
.PP
The
.BR libnormalform_ref ()
function also fails without setting
.I errno
if
.I x
is
.IR NULL .

.SH ATTRIBUTES
For an explanation of the terms used in this
section, see
.BR attributes (7)
and
.IR "info \(dq(libc)POSIX Safety Concepts\(dq" .
.TS
allbox;
lb lb lb
l l l.
Interface	Attribute	Value
T{
.BR libnormalform_ref ()
T}	Thread safety	MT-Safe race:\fIx\fP
T{
.BR libnormalform_ref ()
T}	Async-signal safety	AS-Unsafe heap
T{
.BR libnormalform_ref ()
T}	Async-cancel safety	AC-Unsafe heap
.TE

.SH APPLICATION USAGE
The
.B LIBNORMALFORM_SENTENCE
type is not thread-safe. If you want to use an
instance of it from two or more threads concurrently,
you need to use the
.BR libnormalform_clone (3)
function to create a deep clone of the instance.
Additionally applications shall assume that any
.B LIBNORMALFORM_SENTENCE
constructed using an instance of this type contains
that instance and cannot be used concurrently, from
another thread, with that instance or any other
instance created with it, appart from instances
created with the
.BR libnormalform_clone (3)
function.

.SH SEE ALSO
.BR libnormalform (7),
.BR libnormalform_clone (3),
.BR libnormalform_free (3)