commit a1a1d9ed137c8e404e7f0bd41804099ef18b9267
parent 236cb277ffbc8bec4bdeb714da6d14d9e3a115dc
Author: Mattias Andrée <maandree@kth.se>
Date: Mon, 29 Feb 2016 15:34:38 +0100
Add a number of man pages
Signed-off-by: Mattias Andrée <maandree@kth.se>
Diffstat:
19 files changed, 587 insertions(+), 3 deletions(-)
diff --git a/README b/README
@@ -1,8 +1,8 @@
NAME
- libzahl - big integer library
+ libzahl - Big integer library
ETYMOLOGY
- The bold uppercase Z which represents the set of
+ The bold uppercase 'Z' which represents the set of
all integers is derived from the german word 'zahlen',
whose singular is 'zahl'.
@@ -15,7 +15,7 @@ DESCRIPTION
when an error is detected, rather than letting the
caller also perform a check. This shall make the
code in the user program cleaner too. libzahl will
- use dedicated temporary bitnum integers whether
+ use dedicated temporary bignum integers whether
possible, and necessary, for its internal calculations.
libzahl will not deallocate allocations, but rather
cache them for reuse.
diff --git a/man/libzahl.7 b/man/libzahl.7
@@ -0,0 +1,37 @@
+.TH LIBZAHL 7 libzahl
+.SH NAME
+libzahl - Big integer library
+.SH ETYMOLOGY
+The bold uppercase \(aqZ\(aq which represents the
+set of all integers is derived from the german word
+\(aqzahlen\(aq, whose singular is \(aqzahl\(aq.
+.SH DESCRIPTION
+.B libzahl
+is a C library for arbitrary size integers, that
+aims to be usable for rubust programs, and be
+fast.
+.P
+.B libzahl
+will accomplish this by using long jumps when an
+error is detected, rather than letting the caller
+also perform a check. This shall make the code in
+the user program cleaner too.
+.B libzahl
+will use dedicated temporary bignum integers whether
+possible, and necessary, for its internal calculations.
+.B libzahl
+will not deallocate allocations, but rather cache
+them for reuse.
+.P
+With the exception of functions working with strings,
+all output parameters are before the input parameters.
+.SH RATIONALE
+GMP MP cannot be used for rubust programs. LibTomMath
+is too slow, probably because of all memory allocations,
+and has an nonintuitive API. Hebimath is promising, but
+I think it can be done better.
+.SH NOTES
+.B libzahl
+is currently not thread-safe.
+.SH SEE ALSO
+.BR zsetup (3)
diff --git a/man/zcmp.3 b/man/zcmp.3
@@ -0,0 +1,33 @@
+.TH ZCMP 3 libzahl
+.SH NAME
+zcmp - Compare two big integer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+int zcmp(z_t \fIa\fP, z_t \fIb\fP);
+.fi
+.SH DESCRIPTION
+.B zcmp
+compares
+.I a
+and
+.IR b .
+.SH RETURN VALUE
+.B zcmp
+returns -1 if
+.I a
+is less than
+.IR b ,
+0 if
+.I a
+is equal to
+.IR b ,
+and +1 if
+.I a
+is greater than
+.IR b .
+.SH SEE ALSO
+.BR zcmpi (3),
+.BR zcmpu (3),
+.BR zcmpmag (3)
diff --git a/man/zcmpi.3 b/man/zcmpi.3
@@ -0,0 +1,33 @@
+.TH ZCMPI 3 libzahl
+.SH NAME
+zcmpi - Compare a big integer and a signed integer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+int zcmpi(z_t \fIa\fP, signed long long int \fIb\fP);
+.fi
+.SH DESCRIPTION
+.B zcmpi
+compares
+.I a
+and
+.IR b .
+.SH RETURN VALUE
+.B zcmpi
+returns -1 if
+.I a
+is less than
+.IR b ,
+0 if
+.I a
+is equal to
+.IR b ,
+and +1 if
+.I a
+is greater than
+.IR b .
+.SH SEE ALSO
+.BR zcmp (3),
+.BR zcmpu (3),
+.BR zcmpmag (3)
diff --git a/man/zcmpmag.3 b/man/zcmpmag.3
@@ -0,0 +1,33 @@
+.TH ZCMPMAG 3 libzahl
+.SH NAME
+zcmpmag - Compare the absolute values of two big integer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+int zcmpmag(z_t \fIa\fP, z_t \fIb\fP);
+.fi
+.SH DESCRIPTION
+.B zcmpmag
+compares the absolute value of
+.I a
+and the absolute value of
+.IR b .
+.SH RETURN VALUE
+.B zcmpmag
+returns -1 if
+.RI | a |
+is less than
+.RI | b |,
+0 if
+.RI | a |
+is equal to
+.RI | b |,
+and +1 qif
+.RI | a |
+is greater than
+.RI | b |.
+.SH SEE ALSO
+.BR zcmp (3),
+.BR zcmpi (3),
+.BR zcmpu (3)
diff --git a/man/zcmpu.3 b/man/zcmpu.3
@@ -0,0 +1,33 @@
+.TH ZCMPU 3 libzahl
+.SH NAME
+zcmpu - Compare a big integer and an unsigned integer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+int zcmpu(z_t \fIa\fP, unsigned long long int \fIb\fP);
+.fi
+.SH DESCRIPTION
+.B zcmpu
+compares
+.I a
+and
+.IR b .
+.SH RETURN VALUE
+.B zcmpu
+returns -1 if
+.I a
+is less than
+.IR b ,
+0 if
+.I a
+is equal to
+.IR b ,
+and +1 if
+.I a
+is greater than
+.IR b .
+.SH SEE ALSO
+.BR zcmp (3),
+.BR zcmpi (3),
+.BR zcmpmag (3)
diff --git a/man/zeven.3 b/man/zeven.3
@@ -0,0 +1,25 @@
+.TH ZEVEN 3 libzahl
+.SH NAME
+zeven - Check whether a big integer is even
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+int zeven(z_t \fIa\fP);
+.fi
+.SH DESCRIPTION
+.B zeven
+checks whether
+.I a
+is even.
+.SH RETURN VALUE
+.B zeven
+returns 1 if
+.I a
+is even, and 0 otherwise.
+.SH SEE ALSO
+.BR zodd (3),
+.BR zeven_nonzero (3),
+.BR zzero (3),
+.BR zsignum (3),
+.BR zcmp (3)
diff --git a/man/zeven_nonzero.3 b/man/zeven_nonzero.3
@@ -0,0 +1,29 @@
+.TH ZEVEN_NONZERO 3 libzahl
+.SH NAME
+zeven_nonzero - Check whether a non-zero big integer is even
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+int zeven_nonzero(z_t \fIa\fP);
+.fi
+.SH DESCRIPTION
+.B zeven_nonzero
+checks whether
+.I a
+is even.
+.P
+Undefined behaviour is invoked if
+.I a
+is zero.
+.SH RETURN VALUE
+.B zeven_nonzero
+returns 1 if
+.I a
+is even, and 0 otherwise.
+.SH SEE ALSO
+.BR zeven (3),
+.BR zodd_nonzero (3),
+.BR zzero (3),
+.BR zsignum (3),
+.BR zcmp (3)
diff --git a/man/zfree.3 b/man/zfree.3
@@ -0,0 +1,21 @@
+.TH ZFREE 3 libzahl
+.SH NAME
+zfree - Cache an allocation for reuse
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zfree(z_t \fIa\fP);
+.fi
+.SH DESCRIPTION
+.B zfree
+caches the memory stored in
+.I a
+for reuse.
+.I a
+must not be used again until
+.BR zinit (3),
+is called for it again.
+.SH SEE ALSO
+.BR zinit (3),
+.BR zswap (3)
diff --git a/man/zinit.3 b/man/zinit.3
@@ -0,0 +1,33 @@
+.TH ZINIT 3 libzahl
+.SH NAME
+zinit - Prepare a bit integer for use.
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zinit(z_t \fIa\fP);
+.fi
+.SH DESCRIPTION
+.B zinit
+initializes the big integer
+.I a
+so that it can be used in other function calls.
+.P
+.B z_t
+is defined as
+.P
+.nf
+typedef struct {
+ /* You should not care about what is
+ * inside this struct. It could change
+ * in the future. */
+} z_t[1];
+.fi
+.SH SEE ALSO
+.BR zfree (3),
+.BR zswap (3),
+.BR zsave (3),
+.BR zsignum (3),
+.BR zeven (3),
+.BR zset (3),
+.BR zcmp (3)
diff --git a/man/zload.3 b/man/zload.3
@@ -0,0 +1,34 @@
+.TH ZLOAD 3 libzahl
+.SH NAME
+zload - Unmarshal a big integer from a buffer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+size_t zload(z_t \fIa\fP, const void *\fIbuf\fP);
+.fi
+.SH DESCRIPTION
+.B zload
+unmarshals a big integer from
+.I buf
+into
+.IR a .
+The big integer should have be saved using
+.BR zsave (3),
+with the same version of libzahl
+and on the processor architecture.
+.P
+.I a
+must have been initialized with
+.BR zinit (3).
+.SH RETURN VALUE
+The number of bytes read from
+.IR buf .
+On failure, 0 is returned.
+.SH ERRORS
+This function may failure for any reason specified for
+.BR realloc (3).
+.SH SEE ALSO
+.BR zinit (3),
+.BR zsave (3),
+.BR zsets (3)
diff --git a/man/zodd.3 b/man/zodd.3
@@ -0,0 +1,25 @@
+.TH ZODD 3 libzahl
+.SH NAME
+zodd - Check whether a big integer is odd
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+int zodd(z_t \fIa\fP);
+.fi
+.SH DESCRIPTION
+.B zodd
+checks whether
+.I a
+is odd.
+.SH RETURN VALUE
+.B zeven
+returns 1 if
+.I a
+is odd, and 0 otherwise.
+.SH SEE ALSO
+.BR zeven (3),
+.BR zodd_nonzero (3),
+.BR zzero (3),
+.BR zsignum (3),
+.BR zcmp (3)
diff --git a/man/zodd_nonzero.3 b/man/zodd_nonzero.3
@@ -0,0 +1,29 @@
+.TH ZODD_NONZERO 3 libzahl
+.SH NAME
+zodd_nonzero - Check whether a non-zero big integer is odd
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+int zodd_nonzero(z_t \fIa\fP);
+.fi
+.SH DESCRIPTION
+.B zodd_nonzero
+checks whether
+.I a
+is odd.
+.P
+Undefined behaviour is invoked if
+.I a
+is zero.
+.SH RETURN VALUE
+.B zodd_nonzero
+returns 1 if
+.I a
+is odd, and 0 otherwise.
+.SH SEE ALSO
+.BR zodd (3),
+.BR zeven_nonzero (3),
+.BR zzero (3),
+.BR zsignum (3),
+.BR zcmp (3)
diff --git a/man/zsave.3 b/man/zsave.3
@@ -0,0 +1,65 @@
+.TH ZSAVE 3 libzahl
+.SH NAME
+zsave - Marshal a big integer into a buffer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+size_t zsave(z_t \fIa\fP, void *\fIbuf\fP);
+.fi
+.SH DESCRIPTION
+.B zsave
+marshals
+.I a
+into the buffer
+.IR buf
+unless
+.IR buf
+is
+.IR 0 .
+The data stored is not necessarily transferable
+between machines or between different versions
+of libzahl. For such use,
+use
+.BR zstr (3)
+instead.
+.P
+Upon successful completion,
+.I (*(int*)buf)
+will always be either -1, 0, or 1.
+.SH RETURN VALUE
+The number of bytes written to
+.IR buf ,
+or the number bytes that would have been written if
+.IR buf
+was not
+.IR 0 .
+.SH ERRORS
+This function cannot detect failure.
+.SH EXAMPLE
+.nf
+#include <zahl.h>
+#include <stdlib.h>
+
+int buffer_z(z_t num, char **buf, size_t *off) {
+ size_t n = zsave(num, 0);
+ char *new = realloc(*buf, *off + n);
+ if (!new) {
+ return -1;
+ }
+ *buf = new;
+ assert(zsave(num, *buf + *off) == n);
+ *off += n;
+ return 0;
+}
+.fi
+.SH RATIONALE
+This makes it possible to fork a process and send
+result between the parent and the child, as long as
+none of the process re-execute themself.
+.B zsave
+is much faster than
+.BR zstr (3).
+.SH SEE ALSO
+.BR zload (3),
+.BR zstr (3)
diff --git a/man/zsetup.3 b/man/zsetup.3
@@ -0,0 +1,59 @@
+.TH ZSETUP 3 libzahl
+.SH NAME
+zsetup - Prepare libzahl for use
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zsetup(jmp_buf \fIenv\fP);
+.fi
+.SH DESCRIPTION
+.B zsetup
+initializes all memory that is used internally by
+libzahl.
+.B zsetup
+is also used to specify where to return in case
+an error occurs.
+You must call this function before using libzahl.
+.P
+.B zsetup
+can be used multiple times, the
+.I env
+from the last call is in effect.
+.SH EXAMPLE
+.nf
+#include <zahl.h>
+#include <setjmp.h>
+
+int
+main(void)
+{
+ jmp_buf env;
+
+ if (setjmp(env)) {
+ perror(0);
+ zunsetup();
+ return 1;
+ }
+ zsetup(env);
+
+ /* Use libzahl ... */
+
+ zunsetup();
+ return 0;
+}
+.fi
+.SH RATIONALE
+To increase the performance of libzahl, it uses
+dedicated memory for temporary storage.
+.PP
+libzahl performs checks internally, this is
+necessary. It would decrease the performance
+of the program that uses libzahl, if it had
+to check that libzahl's functions returned
+successfully, it would also produce cluttered
+code. Instead libzahl goes directly to the
+part of the program that handles the error.
+.SH SEE ALSO
+.BR zunsetup (3),
+.BR zinit (3)
diff --git a/man/zsignum.3 b/man/zsignum.3
@@ -0,0 +1,29 @@
+.TH ZSIGNUM 3 libzahl
+.SH NAME
+zsignum - Get the sign of a big integer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+int zsignum(z_t \fIa\fP);
+.fi
+.SH DESCRIPTION
+.B zsignum
+returns signum of
+.I
+a ;
+the sign.
+.SH RETURN VALUE
+.B zsignum
+returns -1 if
+.I a
+is negative, 0 if
+.I a
+is zero, and +1 if
+.I a
+is positive.
+.SH SEE ALSO
+.BR zzero (3),
+.BR zeven (3),
+.BR zodd (3),
+.BR zcmp (3)
diff --git a/man/zswap.3 b/man/zswap.3
@@ -0,0 +1,22 @@
+.TH ZSWAP 3 libzahl
+.SH NAME
+zswap - Exchanges the value of two big integers
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zswap(z_t \fIa\fP, z_t \fIb\fP);
+.fi
+.SH DESCRIPTION
+.B zswap
+exchanges all information stored in
+.I a
+with the information stored in
+.IR b .
+.P
+It is safe to call
+.B zswap
+with
+.IR "(a==b)" .
+.SH SEE ALSO
+.BR zset (3)
diff --git a/man/zunsetup.3 b/man/zunsetup.3
@@ -0,0 +1,20 @@
+.TH ZUNSETUP 3 libzahl
+.SH NAME
+zsetup - Release all memory used internally by libzahl.
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zunsetup(void);
+.fi
+.SH DESCRIPTION
+.B zunsetup
+release all memory used internally or cached by libzahl.
+You should run this function when you are done using libzahl.
+.P
+It is possible to call
+.B zunsetup
+directly followed by
+.BR zsetup (3).
+.SH SEE ALSO
+.BR zsetup (3)
diff --git a/man/zzero.3 b/man/zzero.3
@@ -0,0 +1,24 @@
+.TH ZZERO 3 libzahl
+.SH NAME
+zzero - Check whether a big integer is zero
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+int zzero(z_t \fIa\fP);
+.fi
+.SH DESCRIPTION
+.B zzero
+checks whether
+.I a
+is zero.
+.SH RETURN VALUE
+.B zzero
+returns 1 if
+.I a
+is zero, and 0 otherwise.
+.SH SEE ALSO
+.BR zsignum (3),
+.BR zeven (3),
+.BR zodd (3),
+.BR zcmp (3)
