Basics

Basics
Prev	Chapter 1. Installing PBC	Next

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

Prev	Up	Next
Quick start	Home	Chapter 2. Tutorial