First commit

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 127 insertions, 0 deletions

diff --git a/man3/libnormalform_variable.3 b/man3/libnormalform_variable.3
new file mode 100644
index 0000000..ad30a37
--- /dev/null
+++ b/man3/libnormalform_variable.3
@@ -0,0 +1,127 @@
+.TH LIBNORMALFORM_VARIABLE 3 LIBNORMALFORM
+.SH NAME
+libnormalform_variable \- Boolean variable
+
+.SH SYNOPSIS
+.nf
+#include <libnormalform.h>
+
+enum libnormalform_value {
+        \fILIBNORMALFORM_FALSE\fP = 0,
+        \fILIBNORMALFORM_TRUE\fP = 1
+};
+
+struct libnormalform_variable {
+        enum libnormalform_value \fIvalue\fP;
+        void *\fIuser_data\fP;
+        const char *\fIidentifier;
+        struct libnormalform_variable *\fIcopy_for_clone\fP;
+};
+
+LIBNORMALFORM_SENTENCE *libnormalform_variable(struct libnormalform_variable *\fIvariable\fP);
+.fi
+.PP
+Link with
+.IR -lnormalform .
+
+.SH DESCRIPTION
+The
+.BR libnormalform_variable ()
+function creates a sentence object out
+of an application-managed variable.
+.PP
+.I variable->value
+is used only be the
+.BR libnormalform_evaluate (3)
+function and must be set to either
+.I LIBNORMALFORM_FALSE
+or
+.I LIBNORMALFORM_TRUE
+before the
+.BR libnormalform_evaluate (3)
+function is called, to let the
+function know what value the
+variable has for that specific
+call to the
+.BR libnormalform_evaluate (3)
+function.
+.PP
+See
+.BR libnormalform_to_string (3)
+for the purpose of
+.IR variable->identifier ,
+it need not be set before the
+.BR libnormalform_to_string (3)
+function is called.
+.PP
+See
+.BR libnormalform_clone (3)
+for the purpose of
+.IR variable->copy_for_clone ,
+it need not be set before the
+.BR libnormalform_clone (3)
+function is called.
+.PP
+The application can set
+.I variable->user_data
+set freely, and can opt to leave it
+unset. It is never used or reference
+by the library, but it could be used
+by the application to identify the
+variable.
+.PP
+.I variable
+must not be
+.IR NULL .
+.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_variable ()
+function returns an sentence object of
+the variable; otherwise, the function
+returns
+.I NULL
+and sets
+.I errno
+to indicate the error.
+
+.SH ERRORS
+The
+.BR libnormalform_variable ()
+function fails if:
+.TP
+.I ENOMEM
+Insufficient memory was available to
+create 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_variable ()
+T}	Thread safety	MT-Safe
+T{
+.BR libnormalform_variable ()
+T}	Async-signal safety	AS-Unsafe heap
+T{
+.BR libnormalform_variable ()
+T}	Async-cancel safety	AC-Safe mem, AC-Unsafe heap
+.TE
+
+.SH SEE ALSO
+.BR libnormalform (7),
+.BR libnormalform_function (3)