Programs using the PBC library should include the file
pbc.h
:
#include <pbc.h>
and linked against the PBC library and the GMP library, e.g.
$ gcc program.c -L. -lpbc -lgmp
The file pbc.h
already includes
gmp.h
.
PBC follows GMP in several respects:
- Output arguments generally precede input arguments.
- The same variable can be used as input and output in one call.
- Before a variable may be used it must be initialized exactly once. When no longer needed it must be cleared. For efficiency, unnecessary initializating and clearing should be avoided.
- PBC variables ending with
_t
behave the same as GMP variables in function calls: effectively as call-by references. In other words, as in GMP, if a function that modifies an input variable, that variable remains modified when control return is returned to the caller. - Like GMP, variables automatically
allocate memory when needed. By default,
malloc()
and friends are called but this can be changed. - PBC functions are mostly reentrant.
Since the PBC library is built on top of GMP, the GMP types
are available. PBC types are similar to GMP types. The
following example is paraphrased from an example in the GMP
manual, and shows how to declare the PBC data type element_t
.
element_t sum; struct foo { element_t x, y; }; element_t vec[20];
GMP has the mpz_t
type for
integers, mpq_t
for rationals and
so on. In contrast, PBC uses the element_t
data type for elements of different
algebraic structures, such as elliptic curve groups, polynomial
rings and finite fields. Functions assume their inputs come
from appropriate algebraic structures.
PBC data types and functions can be categorized as follows. The first two alone suffice for a range of applications.
element_t
: elements of an algebraic structure.pairing_t
: pairings where elements belong; can initialize from sample pairing parameters bundled with PBC in theparam
subdirectory.pbc_param_t
: used to generate pairing parameters.pbc_cm_t
: parameters for constructing curves via the CM method; sometimes required bypbc_param_t
.field_t
: algebraic structures: groups, rings and fields; used internally bypairing_t
.- a few miscellaneous functions, such as ones controlling how random bits are generated.
Functions operating on a given data type usually have the
same prefix, e.g. those involving element_t
objects begin with element_
.