=== Basics === 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 the +param+ subdirectory. - +pbc_param_t+: used to generate pairing parameters. - +pbc_cm_t+: parameters for constructing curves via the CM method; sometimes required by +pbc_param_t+. - +field_t+: algebraic structures: groups, rings and fields; used internally by +pairing_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_+.