First commit

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

1 files changed, 239 insertions, 0 deletions

diff --git a/man3/libnormalform_nif.3 b/man3/libnormalform_nif.3
new file mode 100644
index 0000000..174b9d4
--- /dev/null
+++ b/man3/libnormalform_nif.3
@@ -0,0 +1,239 @@
+.TH LIBNORMALFORM_NIF 3 LIBNORMALFORM
+.SH NAME
+libnormalform_nif \- Converse abjunction
+
+.SH SYNOPSIS
+.nf
+#include <libnormalform.h>
+
+LIBNORMALFORM_SENTENCE *libnormalform_nif(LIBNORMALFORM_SENTENCE **\fIxs\fP);
+LIBNORMALFORM_SENTENCE *libnormalform_nifl(LIBNORMALFORM_SENTENCE *\fIa\fP, ... /*, NULL */);
+LIBNORMALFORM_SENTENCE *libnormalform_vnif(LIBNORMALFORM_SENTENCE *\fIa\fP, va_list \fPargs\fP);
+LIBNORMALFORM_SENTENCE *libnormalform_nif_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE **\fIxs\fP);
+LIBNORMALFORM_SENTENCE *libnormalform_nifl_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE *\fIa\fP, ... /*, NULL */);
+LIBNORMALFORM_SENTENCE *libnormalform_vnif_checked(size_t \fIn\fP, LIBNORMALFORM_SENTENCE *\fIa\fP, va_list \fPargs\fP);
+LIBNORMALFORM_SENTENCE *libnormalform_nif2(LIBNORMALFORM_SENTENCE *\fIp\fP, LIBNORMALFORM_SENTENCE *\fIq\fP);
+#define LIBNORMALFORM_NIF(...) /* ... */
+.fi
+.PP
+Link with
+.IR -lnormalform .
+
+.SH DESCRIPTION
+The
+.BR libnormalform_nif ()
+function creates a sentence that is logically
+equivalent to the converse abjunction of the
+arguments.
+.PP
+The value of the
+.I xs
+parameter shall be a null-pointer terminated list
+of subsentences.
+.PP
+The
+.BR libnormalform_nifl ()
+function is a variant of
+.BR libnormalform_nif ()
+which uses variadic arguments instead of an array.
+.PP
+The
+.BR libnormalform_vnif ()
+function is a variant of
+.BR libnormalform_nifl ()
+which takes an
+.I va_list
+in place of variadic arguments.
+.PP
+The
+.BR libnormalform_nif_checked (),
+.BR libnormalform_nifl_checked (),
+and
+.BR libnormalform_vnif_checked ()
+functions are variants of the
+.BR libnormalform_nif (),
+.BR libnormalform_nifl (),
+and
+.BR libnormalform_vnif ()
+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_nif2(p, q)"
+is equivalent to
+.IR "libnormalform_nifl_checked(2, p, q, NULL)" .
+.PP
+The
+.BR LIBNORMALFORM_NIF
+macro is a wrapper for the
+.BR libnormalform_nif_checked ()
+but is more similar to
+.BR libnormalform_nifl ().
+Unlike
+.BR libnormalform_nifl (),
+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_nif ()
+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_nif_checked (),
+.BR libnormalform_nifl_checked (),
+and
+.BR libnormalform_vnif_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_nif2 ()
+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_nif (),
+.br
+.BR libnormalform_nif_checked ()
+T}	Thread safety	MT-Safe race:\fIxs\fP and elements in \fIxs\fP
+T{
+.BR libnormalform_nifl (),
+.br
+.BR libnormalform_nifl_checked (),
+.br
+.BR libnormalform_nif2 (),
+.br
+.BR LIBNORMALFORM_NIF ()
+T}	Thread safety	MT-Safe race:parameters
+T{
+.BR libnormalform_vnif (),
+.br
+.BR libnormalform_vnif_checked ()
+T}	Thread safety	MT-Safe race:parameters and arguments in \fIargs\fP
+T{
+.BR libnormalform_nif (),
+.br
+.BR libnormalform_nifl (),
+.br
+.BR libnormalform_vnif (),
+.br
+.BR libnormalform_nif_checked (),
+.br
+.BR libnormalform_nifl_checked (),
+.br
+.BR libnormalform_vnif_checked (),
+.br
+.BR libnormalform_vnif2 (),
+.br
+.BR LIBNORMALFORM_NIF ()
+T}	Async-signal safety	AS-Unsafe heap
+T{
+.BR libnormalform_nif (),
+.br
+.BR libnormalform_nifl (),
+.br
+.BR libnormalform_vnif (),
+.br
+.BR libnormalform_nif_checked (),
+.br
+.BR libnormalform_nifl_checked (),
+.br
+.BR libnormalform_vnif_checked (),
+.br
+.BR libnormalform_vnif2 (),
+.br
+.BR LIBNORMALFORM_NIF ()
+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 non-commutative and left-associative. It's truthtable is (0010).
+.PP
+The
+.BR LIBNORMALFORM_NIF ()
+macro requires ISO C23 support.
+.PP
+The
+.BR libnormalform_nif ()
+is primary function, the other functions are
+just wrappers for the
+.BR libnormalform_nif ()
+function.
+.PP
+These functions creates a clause where each term is
+connected with the NIF connective. There is
+unfortunately no generally meaningful interpretation:
+adding a false term on the left does not change the
+result but adding a true term on the left inverts the
+result only if all terms are true, whereas adding false
+term on the right creates a contradiction, while adding
+a true term on the right inverts the original clause.
+.PP
+Side-effects in the arguments of the macro
+.BR LIBNORMALFORM_NIF ()
+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)