First commit

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

1 files changed, 233 insertions, 0 deletions

diff --git a/man3/libnormalform_or.3 b/man3/libnormalform_or.3
new file mode 100644
index 0000000..9d57ee8
--- /dev/null
+++ b/man3/libnormalform_or.3
@@ -0,0 +1,233 @@
+.TH LIBNORMALFORM_OR 3 LIBNORMALFORM
+.SH NAME
+libnormalform_or \- Inclusive disjunction
+
+.SH SYNOPSIS
+.nf
+#include <libnormalform.h>
+
+LIBNORMALFORM_SENTENCE *libnormalform_or(LIBNORMALFORM_SENTENCE **\fIxs\fP);
+LIBNORMALFORM_SENTENCE *libnormalform_orl(LIBNORMALFORM_SENTENCE *\fIa\fP, ... /*, NULL */);
+LIBNORMALFORM_SENTENCE *libnormalform_vor(LIBNORMALFORM_SENTENCE *\fIa\fP, va_list \fPargs\fP);
+LIBNORMALFORM_SENTENCE *libnormalform_or_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE **\fIxs\fP);
+LIBNORMALFORM_SENTENCE *libnormalform_orl_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE *\fIa\fP, ... /*, NULL */);
+LIBNORMALFORM_SENTENCE *libnormalform_vor_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE *\fIa\fP, va_list \fPargs\fP);
+LIBNORMALFORM_SENTENCE *libnormalform_or2(LIBNORMALFORM_SENTENCE *\fIp\fP, LIBNORMALFORM_SENTENCE *\fIq\fP);
+#define LIBNORMALFORM_OR(...) /* ... */
+.fi
+.PP
+Link with
+.IR -lnormalform .
+
+.SH DESCRIPTION
+The
+.BR libnormalform_or ()
+function creates a sentence that is logically
+equivalent to the inclusive disjunction of the
+arguments, that is, a sentence that is true when
+and only when at least one subsentence is true.
+.PP
+The value of the
+.I xs
+parameter shall be a null-pointer terminated list
+of subsentences.
+.PP
+The
+.BR libnormalform_orl ()
+function is a variant of
+.BR libnormalform_or ()
+which uses variadic arguments instead of an array.
+.PP
+The
+.BR libnormalform_vor ()
+function is a variant of
+.BR libnormalform_orl ()
+which takes an
+.I va_list
+in place of variadic arguments.
+.PP
+The
+.BR libnormalform_or_checked (),
+.BR libnormalform_orl_checked (),
+and
+.BR libnormalform_vor_checked ()
+functions are variants of the
+.BR libnormalform_or (),
+.BR libnormalform_orl (),
+and
+.BR libnormalform_vor ()
+functions respectively which assumes
+that it is given
+.I n
+subsentances, and checks that all are
+.RI non- NULL .
+However, these functions still require
+the list of subsentences to be terminated
+using a null-pointer.
+.PP
+.I "libnormalform_or2(p, q)"
+is equivalent to
+.IR "libnormalform_orl_checked(2, p, q, NULL)" .
+.PP
+The
+.BR LIBNORMALFORM_OR
+macro is a wrapper for the
+.BR libnormalform_or_checked ()
+but is more similar to
+.BR libnormalform_orl ().
+Unlike
+.BR libnormalform_orl (),
+the argument list
+.I must not
+be terminated by a null-pointer, instead
+the macro automatically as the null-pointer.
+The macro will count the number of arguments
+it is given, therefore it will fail it the
+argument list is has an extra null-pointer.
+.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.
+.PP
+These functions adopt the ownership of any
+.I LIBNORMALFORM_SENTENCE *
+passed into it. Therefore, the user shall
+not attempt to deallocate input sentences.
+This holds even on failure: if the function
+fails, input sentences are deallocated.
+
+.SH RETURN VALUE
+Upon successful completion, the
+.BR libnormalform_or ()
+function and its variants return an object
+representing  the sentence; otherwise, the
+functions return
+.I NULL
+and set
+.I errno
+to indicate the error.
+
+.SH ERRORS
+These functions fails if:
+.TP
+.I ENOMEM
+Insufficient memory was available to
+create the sentence object.
+.PP
+The
+.BR libnormalform_or_checked (),
+.BR libnormalform_orl_checked (),
+and
+.BR libnormalform_vor_checked ()
+functions will also fail without setting
+.I errno
+if any of the first
+.I n
+.IR "LIBNORMALFORM_SENTENCE *" 's
+are
+.IR NULL .
+Likewise, the
+.BR libnormalform_or2 ()
+function will fail without setting
+.I errno
+if
+.I p
+or
+.I q
+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_or (),
+.br
+.BR libnormalform_or_checked ()
+T}	Thread safety	MT-Safe race:\fIxs\fP and elements in \fIxs\fP
+T{
+.BR libnormalform_orl (),
+.br
+.BR libnormalform_orl_checked (),
+.br
+.BR libnormalform_or2 (),
+.br
+.BR LIBNORMALFORM_OR ()
+T}	Thread safety	MT-Safe race:parameters
+T{
+.BR libnormalform_vor (),
+.br
+.BR libnormalform_vor_checked ()
+T}	Thread safety	MT-Safe race:parameters and arguments in \fIargs\fP
+T{
+.BR libnormalform_or (),
+.br
+.BR libnormalform_orl (),
+.br
+.BR libnormalform_vor (),
+.br
+.BR libnormalform_or_checked (),
+.br
+.BR libnormalform_orl_checked (),
+.br
+.BR libnormalform_vor_checked (),
+.br
+.BR libnormalform_vor2 (),
+.br
+.BR LIBNORMALFORM_OR ()
+T}	Async-signal safety	AS-Unsafe heap
+T{
+.BR libnormalform_or (),
+.br
+.BR libnormalform_orl (),
+.br
+.BR libnormalform_vor (),
+.br
+.BR libnormalform_or_checked (),
+.br
+.BR libnormalform_orl_checked (),
+.br
+.BR libnormalform_vor_checked (),
+.br
+.BR libnormalform_vor2 (),
+.br
+.BR LIBNORMALFORM_OR ()
+T}	Async-cancel safety	AC-Safe mem, AC-Unsafe heap
+.TE
+
+.SH NOTES
+If there are no subsentences, the resulting sentence is a contradiction.
+.PP
+The connective is commutative and associative. It's truthtable is (0111).
+.PP
+The
+.BR LIBNORMALFORM_OR ()
+macro requires ISO C23 support.
+.PP
+Using
+.BR libnormalform_or2 (),
+has greatest performance, however
+.BR libnormalform_or ()
+is better at simplifying the sentence.
+The other functions are just wrappers for the
+.BR libnormalform_or ()
+function.
+.PP
+Side-effects in the arguments of the macro
+.BR LIBNORMALFORM_OR ()
+are guaranteed to be applied exactly once.
+The side-effects in each macro are applied
+in no particular order.
+
+.SH SEE ALSO
+.BR libnormalform (7)