1 files changed, 105 insertions, 0 deletions
diff --git a/man3/libnormalform_to_string.3 b/man3/libnormalform_to_string.3
new file mode 100644
index 0000000..7008990
--- /dev/null
+++ b/man3/libnormalform_to_string.3
@@ -0,0 +1,105 @@
+.TH LIBNORMALFORM_TO_STRING 3 LIBNORMALFORM
+.SH NAME
+libnormalform_to_string \- Serialise into a string
+
+.SH SYNOPSIS
+.nf
+#include <libnormalform.h>
+
+char *libnormalform_to_string(LIBNORMALFORM_SENTENCE *\fIx\fP);
+.fi
+.PP
+Link with
+.IR -lnormalform .
+
+.SH DESCRIPTION
+The
+.BR libnormalform_to_string ()
+function creates a string representation if
+.I x
+designed for machine parsing, but can also be
+read by sufficiently literate humans.
+.PP
+Before calling the
+.BR libnormalform_to_string ()
+function, application provided objects in
+.I x
+must be configured for serialisation:
+.I .identifier
+in each
+.IR "struct libnormalform_variable" ,
+.IR "struct libnormalform_function" ,
+.IR "struct libnormalform_map" ,
+and
+.IR "struct libnormalform_transformer" ,
+shall either be set to the string representation,
+of the object, that can be parsed by the application
+without it being terminated by a null byte.
+.PP
+The returned pointer shall either be
+deallocated with the
+.BR free (3)
+function.
+.PP
+.I x
+must not be
+.IR NULL .
+
+.SH RETURN VALUE
+Upon successful completion, the
+.BR libnormalform_to_string ()
+function returns a null-byte terminated
+non-empty, ASCII string representation of
+.IR x ;
+otherwise, the function returns
+.I NULL
+and sets
+.I errno
+to indicate the error.
+
+.SH ERRORS
+The
+.BR libnormalform_to_string ()
+function fails if:
+.TP
+.I ENOMEM
+Insufficient memory was available to
+serialise the sentence object.
+
+.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_to_string ()
+T}	Thread safety	MT-Safe race:\fIx\fP
+T{
+.BR libnormalform_to_string ()
+T}	Async-signal safety	AS-Unsafe heap
+T{
+.BR libnormalform_to_string ()
+T}	Async-cancel safety	AC-Safe mem, AC-Unsafe heap
+.TE
+
+.SH NOTES
+When a
+.I LIBNORMALFORM_SENTENCE
+is created, it is optimised (this includes eliminiation
+of redundant information and reordering) and reduced to
+into fewer types of connetives (it's reducted into negation
+normal form, except with XOR allowed, but not necessarily
+to any canonical form) during construction, so the
+.BR libnormalform_to_string ()
+function will not necessarily reproduce the sentence
+as it was specified when it was constructed.
+
+.SH SEE ALSO
+.BR libnormalform (7),
+.BR libnormalform_from_string (3)