1 files changed, 58 insertions, 0 deletions
diff --git a/moon-abe/pbc-0.5.14/doc/basics.txt b/moon-abe/pbc-0.5.14/doc/basics.txt
new file mode 100644
index 00000000..c9549f72
--- /dev/null
+++ b/moon-abe/pbc-0.5.14/doc/basics.txt
@@ -0,0 +1,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_+.