commit 32b87c5979a0e70994e4db65415ec0a2349c5618
parent a1a1d9ed137c8e404e7f0bd41804099ef18b9267
Author: Mattias Andrée <maandree@kth.se>
Date: Tue, 1 Mar 2016 10:55:20 +0100
Add more man pages
Signed-off-by: Mattias Andrée <maandree@kth.se>
Diffstat:
20 files changed, 649 insertions(+), 1 deletion(-)
diff --git a/man/zand.3 b/man/zand.3
@@ -0,0 +1,31 @@
+.TH ZAND 3 libzahl
+.SH NAME
+zand - Calculates the bitwise AND of two big integers
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zand(z_t \fIa\fP, z_t \fIb\fP, z_t \fIc\fP);
+.fi
+.SH DESCRIPTION
+.B zand
+calculates the bitwise AND of
+.I b
+and
+.IR c ,
+and stores the result in
+.IR a .
+.P
+It is safe to call
+.B zand
+with non-unique parameters.
+.SH SEE ALSO
+.BR zor (3),
+.BR zxor (3),
+.BR znot (3),
+.BR zlsh (3),
+.BR zrsh (3),
+.BR zsplit (3),
+.BR zbtest (3),
+.BR zlsb (3),
+.BR zbits (3)
diff --git a/man/zbits.3 b/man/zbits.3
@@ -0,0 +1,30 @@
+.TH ZBITS 3 libzahl
+.SH NAME
+zbits - Count used bits in a big integer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+size_t zbits(z_t \fIa\fP);
+.fi
+.SH DESCRIPTION
+.B zbits
+calculates the bit-size of
+.IR a .
+If
+.I a
+is zero the bit-size is 1.
+.SH RETURN VALUE
+.B zbits
+returns the number of bits requires
+to represent
+.I a
+\(em 1 plus the floored binary logarithm of the
+absolute value of
+.I a
+\(em or 1 if
+.I a
+is zero.
+.SH SEE ALSO
+.BR zlsb (3),
+.BR zzero (3)
diff --git a/man/zbtest.3 b/man/zbtest.3
@@ -0,0 +1,28 @@
+.TH ZBTEST 3 libzahl
+.SH NAME
+zbtest - Test a bit in a big integer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+int zbtest(z_t \fIa\fP, size_t \fIindex\fP);
+.fi
+.SH DESCRIPTION
+.B zbtest
+returns whether the bit with the specified
+.I index
+is set in
+.IR a .
+.SH RETURN VALUE
+.B zbtest
+returns 1 if the bit is set, or 0 otherwise.
+.SH SEE ALSO
+.BR zand (3),
+.BR zor (3),
+.BR zxor (3),
+.BR znot (3),
+.BR zlsh (3),
+.BR zrsh (3),
+.BR zsplit (3),
+.BR zlsb (3),
+.BR zbits (3)
diff --git a/man/zgcd.3 b/man/zgcd.3
@@ -0,0 +1,20 @@
+.TH ZGCD 3 libzahl
+.SH NAME
+zgcd - Calculates the greatest common divisor
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zgcd(z_t \fIgcd\fP, z_t \fIa\fP, z_t \fIb\fP);
+.fi
+.SH DESCRIPTION
+.B zgcd
+calculates the greatest common divisor
+between
+.I a
+and
+.I b
+and stores the result in
+.IR gcd .
+.SH SEE ALSO
+.BR zdiv (3)
diff --git a/man/zinit.3 b/man/zinit.3
@@ -30,4 +30,17 @@ typedef struct {
.BR zsignum (3),
.BR zeven (3),
.BR zset (3),
-.BR zcmp (3)
+.BR zcmp (3),
+.BR zgcd (3),
+.BR zptest (3),
+.BR zrand (3),
+.BR zbits (3),
+.BR zlsb (3),
+.BR zbtest (3),
+.BR zand (3),
+.BR zor (3),
+.BR zxor (3),
+.BR znot (3),
+.BR zlsh (3),
+.BR zrsh (3),
+.BR zsplit (3)
diff --git a/man/zlsb.3 b/man/zlsb.3
@@ -0,0 +1,32 @@
+.TH ZLSB 3 libzahl
+.SH NAME
+zlsb - Get the least set bit.
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+size_t zlsb(z_t \fIa\fP);
+.fi
+.SH DESCRIPTION
+.B zlsb
+gets the index of the bit of
+lowest value that is set in
+.IR a .
+If
+.I a
+is zero,
+.B SIZE_MAX
+is returned.
+.SH RETURN VALUE
+The index of the least set bit in
+.IR a ,
+or
+.B SIZE_MAX
+if
+.I a
+is zero.
+.SH SEE ALSO
+.BR zbits (3),
+.BR zbtest (3),
+.BR znot (3),
+.BR zrsh (3)
diff --git a/man/zlsh.3 b/man/zlsh.3
@@ -0,0 +1,31 @@
+.TH ZLSH 3 libzahl
+.SH NAME
+zlsh - Perform a left shift on a big integer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zlsh(z_t \fIa\fP, z_t \fIb\fP, size_t \fIn\fP);
+.fi
+.SH DESCRIPTION
+.B zlsh
+shifts
+.I b
+.I n
+bits to the left and stores the result in
+.IR a .
+.P
+It is safe to call
+.B zlsh
+with
+.IR "(a==b)" .
+.SH SEE ALSO
+.BR zand (3),
+.BR zor (3),
+.BR zxor (3),
+.BR znot (3),
+.BR zrsh (3),
+.BR zsplit (3),
+.BR zbtest (3),
+.BR zlsb (3),
+.BR zbits (3)
diff --git a/man/znot.3 b/man/znot.3
@@ -0,0 +1,30 @@
+.TH ZNOT 3 libzahl
+.SH NAME
+znot - Calculates the bitwise complement of a big integer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void znot(z_t \fIa\fP, z_t \fIb\fP);
+.fi
+.SH DESCRIPTION
+.B znot
+calculates the bitwise complement of
+.I b
+and stores the result in
+.IR a .
+.P
+It is safe to call
+.B znot
+with
+.IR "(a==b)" .
+.SH SEE ALSO
+.BR zand (3),
+.BR zor (3),
+.BR zxor (3),
+.BR zlsh (3),
+.BR zrsh (3),
+.BR zsplit (3),
+.BR zbtest (3),
+.BR zlsb (3),
+.BR zbits (3)
diff --git a/man/zor.3 b/man/zor.3
@@ -0,0 +1,31 @@
+.TH ZOR 3 libzahl
+.SH NAME
+zor - Calculates the bitwise inclusive OR of two big integers
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zor(z_t \fIa\fP, z_t \fIb\fP, z_t \fIc\fP);
+.fi
+.SH DESCRIPTION
+.B zor
+calculates the bitwise OR of
+.I b
+and
+.IR c ,
+and stores the result in
+.IR a .
+.P
+It is safe to call
+.B zor
+with non-unique parameters.
+.SH SEE ALSO
+.BR zand (3),
+.BR zxor (3),
+.BR znot (3),
+.BR zlsh (3),
+.BR zrsh (3),
+.BR zsplit (3),
+.BR zbtest (3),
+.BR zlsb (3),
+.BR zbits (3)
diff --git a/man/zptest.3 b/man/zptest.3
@@ -0,0 +1,69 @@
+.TH ZPTEST 3 libzahl
+.SH NAME
+zptest - Test the primality of a big integer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+enum zprimality zptest(z_t \fIwitness\fP, z_t \fIquestioned\fP, z_t \fItries\fP);
+.fi
+.SH DESCRIPTION
+.B zptest
+tests whether
+.I questioned
+is a prime number. This is implemented using the
+Miller–Rabin primality test.
+.P
+If
+.I questioned
+is determined to be a composite, the witness if its
+compositeness is stored into
+.I witness
+unless
+.I witness
+is
+.BR 0 .
+.BR zgcd (3)
+can be used on
+.I questioned
+and
+.I witness
+to extract a factor of
+.IR questioned .
+This factor can be either composite, prime, or 1.
+.P
+The risk that a composite number is determined to be
+a probably prime is
+.IR (1-4↑-tries) .
+.SH RETURN VALUE
+This function will either return:
+.TP
+.B NONPRIME
+.I questioned
+is certainly a composite number.
+.TP
+.B PROBABLY_PRIME
+.I questioned
+is probably a prime number.
+.TP
+.B PRIME
+.I questioned
+is certainly a prime number.
+.SH NOTES
+If
+.I questioned
+is less than two
+.I questioned
+is copied into
+.P
+Increasing
+.I tries
+only reduces the chance that
+.B PROBABLY_PRIME
+is returned. It cannot increase
+the chance that
+.B PRIME
+is returned.
+.IR witness .
+.SH SEE ALSO
+.BR zgcd (3)
diff --git a/man/zrand.3 b/man/zrand.3
@@ -0,0 +1,54 @@
+.TH ZRAND 3 libzahl
+.SH NAME
+zrand - Generate random a number
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zrand(z_t \fIr\fP, enum zranddev \fIdev\fP, enum zranddist \fIdist\fP, z_t \fImax\fP);
+.fi
+.SH DESCRIPTION
+.B zrand
+generates a random number and stores it in
+.IR r .
+.P
+.I dev
+selects the device
+.B zrand
+uses to generate random bits.
+This value may be either of:
+.TP
+.B FAST_RANDOM
+The fast, non-blocking random number generator.
+This is /dev/urandom on Linux.
+.TP
+.B SECURE_RANDOM
+The secure, blocking random number generator.
+This is /dev/random on Linux.
+.P
+.I dist
+selects the probably distribution of the
+output
+.IR r :
+.TP
+.B QUASIUNIFORM
+Use the method of generation that is often
+recommended for generating uniformally random
+integers. This method has unnecessary
+computational overhead and is not properly
+uniform, but is is guaranteed to run in
+constant time assuming the underlying device
+for random bit generation does.
+
+The generated number if be in the inclusive
+range [0,
+.IR max ].
+.TP
+.B UNIFORM
+Generate a integer in the range [0,
+.IR max ]
+uniformally random.
+.P
+It is safe to call
+.B zrand
+with non-unique parameters.
diff --git a/man/zrsh.3 b/man/zrsh.3
@@ -0,0 +1,31 @@
+.TH ZRSH 3 libzahl
+.SH NAME
+zrsh - Perform a right shift on a big integer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zrsh(z_t \fIa\fP, z_t \fIb\fP, size_t \fIn\fP);
+.fi
+.SH DESCRIPTION
+.B zrsh
+shifts
+.I b
+.I n
+bits to the right and stores the result in
+.IR a .
+.P
+It is safe to call
+.B zrsh
+with
+.IR "(a==b)" .
+.SH SEE ALSO
+.BR zand (3),
+.BR zor (3),
+.BR zxor (3),
+.BR znot (3),
+.BR zlsh (3),
+.BR zsplit (3),
+.BR zbtest (3),
+.BR zlsb (3),
+.BR zbits (3)
diff --git a/man/zset.3 b/man/zset.3
@@ -0,0 +1,26 @@
+.TH ZSET 3 libzahl
+.SH NAME
+zset - Copy the value of a big integer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zset(z_t \fIa\fP, z_t \fIb\fP);
+.fi
+.SH DESCRIPTION
+.B zset
+stores the value of
+.I b
+into
+.IR a .
+.I a
+must already be initialized with
+.BR zinit (3).
+The value of
+.I b
+remains unchanged.
+.SH SEE ALSO
+.BR zseti (3),
+.BR zsetu (3),
+.BR zsets (3),
+.BR zswap (3)
diff --git a/man/zseti.3 b/man/zseti.3
@@ -0,0 +1,23 @@
+.TH ZSETI 3 libzahl
+.SH NAME
+zseti - Set the value of a big integer to a signed integer.
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zseti(z_t \fIa\fP, signed long long int \fIb\fP);
+.fi
+.SH DESCRIPTION
+.B zseti
+sets the value of
+.I a
+to
+.IR b .
+.I a
+must already be initialized with
+.BR zinit (3).
+.SH SEE ALSO
+.BR zset (3),
+.BR zsetu (3),
+.BR zsets (3),
+.BR zswap (3)
diff --git a/man/zsets.3 b/man/zsets.3
@@ -0,0 +1,41 @@
+.TH ZSETS 3 libzahl
+.SH NAME
+zsets - Parses a string to a big integer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+int zsets(z_t \fIa\fP, const char *\fIstr\fP);
+.fi
+.SH DESCRIPTION
+.B zsets
+parses the string
+.I str
+and stores the value in
+.IR a .
+.I a
+must already be initialized with
+.BR zinit (3).
+.I b
+must be a decimal integer. It may be
+prefixed with at most one ASCII minus
+sign or plus sign.
+.SH RETURN VALUE
+Upon successful completion, 0 is returned.
+On error -1 is returned an errno is appropriately.
+.SH ERRORS
+This function fails if:
+.TP
+.B EINVAL
+.B str
+is not a valid decimal ASCII integer.
+.P
+On other errors, the function performs a long jump
+using the jump buffer provided via
+.BR zsetup (3).
+.SH SEE ALSO
+.BR zset (3),
+.BR zsetu (3),
+.BR zseti (3),
+.BR zsave (3),
+.BR zstr (3)
diff --git a/man/zsetu.3 b/man/zsetu.3
@@ -0,0 +1,23 @@
+.TH ZSETU 3 libzahl
+.SH NAME
+zsetu - Set the value of a big integer to an unsigned integer.
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zsetu(z_t \fIa\fP, unsigned long long int \fIb\fP);
+.fi
+.SH DESCRIPTION
+.B zseti
+sets the value of
+.I a
+to
+.IR b .
+.I a
+must already be initialized with
+.BR zinit (3).
+.SH SEE ALSO
+.BR zset (3),
+.BR zseti (3),
+.BR zsets (3),
+.BR zswap (3)
diff --git a/man/zsplit.3 b/man/zsplit.3
@@ -0,0 +1,40 @@
+.TH ZSPLIT 3 libzahl
+.SH NAME
+zsplit - Split a big integer in two parts
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zsplit(z_t \fIhigh\fP, z_t \fIlow\fP, z_t \fIa\fP, size_t \fIn\fP);
+.fi
+.SH DESCRIPTION
+.B zsplits
+splits
+.I a
+into two parts. The lowest
+.I n
+bits are stored in
+.IR low ,
+and the rest of the bits are
+stored in
+.IR high .
+The result stored in
+.I high
+is shifted
+.I n
+bits to the right.
+.P
+It is safe to call
+.B zsplit
+with
+.I "(high==a)"
+and
+.IR "(low==a)" .
+.SH SEE ALSO
+.BR zand (3),
+.BR zor (3),
+.BR zxor (3),
+.BR znot (3),
+.BR zlsh (3),
+.BR zrsh (3),
+.BR zbits (3)
diff --git a/man/zstr.3 b/man/zstr.3
@@ -0,0 +1,36 @@
+.TH ZSTR 3 libzahl
+.SH NAME
+zstr - Create a string representation of a big integer
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+char *zstr(z_t \fIa\fP, char *\fIstr\fP);
+.fi
+.SH DESCRIPTION
+.B zstr
+writes the integer
+.I a
+in decimal form into
+.IR str .
+If
+.I str
+is is
+.BR 0 ,
+.B zstr
+create a new allocation.
+.SH RETURN VALUE
+.I str
+is returned unless
+.I str
+is
+.BR 0 .
+If
+.I str
+is
+.BR 0 ,
+the string allocated by the function is returned.
+.SH SEE ALSO
+.BR zstr_length_positive (3),
+.BR zsets (3),
+.BR zload (3)
diff --git a/man/zstr_length_positive.3 b/man/zstr_length_positive.3
@@ -0,0 +1,28 @@
+.TH ZSTR_LENGTH_POSITIVE 3 libzahl
+.SH NAME
+zstr_length_positive - Predict the length of a string
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+size_t zstr_length_positive(z_t \fIa\fP, unsigned long long int\fIradix\fP);
+.fi
+.SH DESCRIPTION
+.B zstr_length_positive
+calculates the number of digits required to
+to represent
+.I a
+in the selected
+.IR radix .
+.P
+.I a
+must be a positive integer. If it is zero or negative,
+undefined behaviour is invoked.
+.SH RETURN VALUE
+The number of digits requires to represent
+.I a
+i the selected
+.I radix
+is returned.
+.SH SEE ALSO
+.BR zstr (3)
diff --git a/man/zxor.3 b/man/zxor.3
@@ -0,0 +1,31 @@
+.TH ZXOR 3 libzahl
+.SH NAME
+zxor - Calculates the bitwise exclusive OR (XOR) of two big integers
+.SH SYNOPSIS
+.nf
+#include <zahl.h>
+
+void zxor(z_t \fIa\fP, z_t \fIb\fP, z_t \fIc\fP);
+.fi
+.SH DESCRIPTION
+.B zxor
+calculates the bitwise XOR of
+.I b
+and
+.IR c ,
+and stores the result in
+.IR a .
+.P
+It is safe to call
+.B zxor
+with non-unique parameters.
+.SH SEE ALSO
+.BR zand (3),
+.BR zor (3),
+.BR znot (3),
+.BR zlsh (3),
+.BR zrsh (3),
+.BR zsplit (3),
+.BR zbtest (3),
+.BR zlsb (3),
+.BR zbits (3)
