Return to README CVS log

Up to [local] / OpenXM / src / kan96xx / gmp-2.0.2-ssh-2

Annotation of OpenXM/src/kan96xx/gmp-2.0.2-ssh-2/README, Revision 1.1.1.1

1.1       takayama    1: THIS IS A MODIFIED VERSION OF GMP-2.0.2.  THE MODIFICATIONS WERE MADE
                      2: TO INTEGRATE THIS CODE TO THE SSH SOFTWARE PACKAGE.  PLEASE CONTACT
                      3: ssh-bugs@cs.hut.fi IF MORE INFORMATION IS NEEDED.
                      4: -------------------------------------------------------------------------
                      5:                        THE GNU MP LIBRARY
                      6:
                      7:
                      8: GNU MP is a library for arbitrary precision arithmetic, operating on signed
                      9: integers, rational numbers, and floating point numbers.  It has a rich set
                     10: of functions, and the functions have a regular interface.
                     11:
                     12: GNU MP is designed to be as fast as possible, both for small operands and for
                     13: huge operands.  The speed is achieved by using fullwords as the basic
                     14: arithmetic type, by using fast algorithms, by carefully optimized assembly
                     15: code for the most common inner loops for a lots of CPUs, and by a general
                     16: emphasis on speed (instead of simplicity or elegance).
                     17:
                     18: The speed of GNU MP is believed to be faster than any other similar library.
                     19: The advantage for GNU MP increases with the operand sizes for certain
                     20: operations, since GNU MP in many cases has asymptotically faster algorithms.
                     21:
                     22:
                     23:                        GETTING STARTED
                     24:
                     25: First, you have to configure and compiler GNU MP.  Simply typing
                     26:
                     27:        ./configure; make
                     28:
                     29: will normally do a reasonable job, but will not give optimal library
                     30: execution speed.  So unless you're very unpatient, please read the detailed
                     31: instructions in the file INSTALL or in gmp.texi.
                     32:
                     33: Once you have compiled the library, you should write some small example, and
                     34: make sure you can compile them.  A typical compilation command is this:
                     35:
                     36:        gcc -g your-file.c -I<gmp-source-dir> <gmp-bin-dir>libgmp.a -lm
                     37:
                     38: If you have installed the library, you can simply do:
                     39:
                     40:        gcc -g your-file.c -lgmp -lm
                     41:
                     42: The -lm is normally not needed, since only a few functions in GNU MP use the
                     43: math library.
                     44:
                     45: Here is a sample program that declares 2 variables, initializes them as
                     46: required, and sets one of them from a signed integer, and the other from a
                     47: string of digits.  It then prints the product of the two numbers in base 10.
                     48:
                     49:   #include <stdio.h>
                     50:   #include "gmp.h"
                     51:
                     52:   main ()
                     53:   {
                     54:     mpz_t a, b, p;
                     55:
                     56:     mpz_init (a);                      /* initialize variables */
                     57:     mpz_init (b);
                     58:     mpz_init (p);
                     59:
                     60:     mpz_set_si (a, 756839);            /* assign variables */
                     61:     mpz_set_str (b, "314159265358979323846", 0);
                     62:     mpz_mul (p, a, b);                 /* generate product */
                     63:     mpz_out_str (stdout, 10, p);       /* print number without newline */
                     64:     puts ("");                         /* print newline */
                     65:
                     66:     mpz_clear (a);                     /* clear out variables */
                     67:     mpz_clear (b);
                     68:     mpz_clear (p);
                     69:
                     70:     exit (0);
                     71:   }
                     72:
                     73: This might look tedious, with all initializing and clearing.  Fortunately
                     74: some of these operations can be combined, and other operations can often be
                     75: avoided.  The example above would be written differently by an experienced
                     76: GNU MP user:
                     77:
                     78:   #include <stdio.h>
                     79:   #include "gmp.h"
                     80:
                     81:   main ()
                     82:   {
                     83:     mpz_t b, p;
                     84:
                     85:     mpz_init (p);
                     86:
                     87:     mpz_init_set_str (b, "314159265358979323846", 0);
                     88:     mpz_mul_ui (p, b, 756839);         /* generate product */
                     89:     mpz_out_str (stdout, 10, p);       /* print number without newline */
                     90:     puts ("");                         /* print newline */
                     91:
                     92:     exit (0);
                     93:   }
                     94:
                     95:
                     96:                        OVERVIEW OF GNU MP
                     97:
                     98: There are five classes of functions in GNU MP.
                     99:
                    100:  1. Signed integer arithmetic functions, mpz_*.  These functions are intended
                    101:     to be easy to use, with their regular interface.  The associated type is
                    102:     `mpz_t'.
                    103:
                    104:  2. Rational arithmetic functions, mpq_*.  For now, just a small set of
                    105:     functions necessary for basic rational arithmetics.  The associated type
                    106:     is `mpq_t'.
                    107:
                    108:  3. Floating-point arithmetic functions, mpf_*.  If the C type `double'
                    109:     doesn't give enough precision for your application, declare your
                    110:     variables as `mpf_t' instead, set the precision to any number desired,
                    111:     and call the functions in the mpf class for the arithmetic operations.
                    112:
                    113:  4. Positive-integer, hard-to-use, very low overhead functions are in the
                    114:     mpn_* class.  No memory management is performed.  The caller must ensure
                    115:     enough space is available for the results.  The set of functions is not
                    116:     regular, nor is the calling interface.  These functions accept input
                    117:     arguments in the form of pairs consisting of a pointer to the least
                    118:     significant word, and a integral size telling how many limbs (= words)
                    119:     the pointer points to.
                    120:
                    121:     Almost all calculations, in the entire package, are made by calling these
                    122:     low-level functions.
                    123:
                    124:  5. Berkeley MP compatible functions.
                    125:
                    126:     To use these functions, include the file "mp.h".  You can test if you are
                    127:     using the GNU version by testing if the symbol __GNU_MP__ is defined.
                    128:
                    129: For more information on how to use GNU MP, please refer to the documentation.
                    130: It is composed from the file gmp.texi, and can be displayed on the screen or
                    131: printed.  How to do that, as well how to build the library, is described in
                    132: the INSTALL file in this directory.
                    133:
                    134:
                    135:                        REPORTING BUGS
                    136:
                    137: If you find a bug in the library, please make sure to tell us about it!
                    138:
                    139: Report bugs and propose modifications and enhancements to
                    140: bug-gmp@prep.ai.mit.edu.  What information is needed in a good bug report is
                    141: described in the manual.