1 files changed, 111 insertions, 0 deletions
diff --git a/man3/libnormalform_ref.3 b/man3/libnormalform_ref.3
new file mode 100644
index 0000000..5592e48
--- /dev/null
+++ b/man3/libnormalform_ref.3
@@ -0,0 +1,111 @@
+.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
+.I 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)