aboutsummaryrefslogtreecommitdiffstats
path: root/moon-abe/pbc-0.5.14/doc/basics.txt
blob: c9549f7239c2074900f2d2acc4ef625f224c600b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
=== 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_+.