.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)