[BACK]Return to gmp.info-1 CVS log [TXT][DIR] Up to [local] / OpenXM_contrib / gmp

Diff for /OpenXM_contrib/gmp/Attic/gmp.info-1 between version 1.1.1.1 and 1.1.1.4

version 1.1.1.1, 2000/01/10 15:35:21 version 1.1.1.4, 2003/08/25 16:06:02
Line 1 
Line 1 
 This is Info file gmp.info, produced by Makeinfo-1.64 from the input  This is gmp.info, produced by makeinfo version 4.2 from gmp.texi.
 file gmp.texi.  
   
   This manual describes how to install and use the GNU multiple precision
   arithmetic library, version 4.1.2.
   
      Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
   2001, 2002 Free Software Foundation, Inc.
   
      Permission is granted to copy, distribute and/or modify this
   document under the terms of the GNU Free Documentation License, Version
   1.1 or any later version published by the Free Software Foundation;
   with no Invariant Sections, with the Front-Cover Texts being "A GNU
   Manual", and with the Back-Cover Texts being "You have freedom to copy
   and modify this GNU Manual, like GNU software".  A copy of the license
   is included in *Note GNU Free Documentation License::.
   INFO-DIR-SECTION GNU libraries
 START-INFO-DIR-ENTRY  START-INFO-DIR-ENTRY
 * gmp: (gmp.info).               GNU Multiple Precision Arithmetic Library.  * gmp: (gmp).                   GNU Multiple Precision Arithmetic Library.
 END-INFO-DIR-ENTRY  END-INFO-DIR-ENTRY
   
    This file documents GNU MP, a library for arbitrary-precision  
 arithmetic.  
   
    Copyright (C) 1991, 1993, 1994, 1995, 1996 Free Software Foundation,  
 Inc.  
   
    Permission is granted to make and distribute verbatim copies of this  
 manual provided the copyright notice and this permission notice are  
 preserved on all copies.  
   
    Permission is granted to copy and distribute modified versions of  
 this manual under the conditions for verbatim copying, provided that  
 the entire resulting derived work is distributed under the terms of a  
 permission notice identical to this one.  
   
    Permission is granted to copy and distribute translations of this  
 manual into another language, under the above conditions for modified  
 versions, except that this permission notice may be stated in a  
 translation approved by the Foundation.  
   
   
 File: gmp.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)  File: gmp.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)
   
 GNU MP  GNU MP
 ******  ******
   
    This manual documents how to install and use the GNU multiple  This manual describes how to install and use the GNU multiple precision
 precision arithmetic library, version 2.0.2.  arithmetic library, version 4.1.2.
   
      Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
   2001, 2002 Free Software Foundation, Inc.
   
      Permission is granted to copy, distribute and/or modify this
   document under the terms of the GNU Free Documentation License, Version
   1.1 or any later version published by the Free Software Foundation;
   with no Invariant Sections, with the Front-Cover Texts being "A GNU
   Manual", and with the Back-Cover Texts being "You have freedom to copy
   and modify this GNU Manual, like GNU software".  A copy of the license
   is included in *Note GNU Free Documentation License::.
   
 * Menu:  * Menu:
   
 * Copying::                   GMP Copying Conditions (LGPL).  * Copying::                    GMP Copying Conditions (LGPL).
 * Introduction to MP::        Brief introduction to GNU MP.  * Introduction to GMP::        Brief introduction to GNU MP.
 * Installing MP::             How to configure and compile the MP library.  * Installing GMP::             How to configure and compile the GMP library.
 * MP Basics::                 What every MP user should now.  * GMP Basics::                 What every GMP user should know.
 * Reporting Bugs::            How to usefully report bugs.  * Reporting Bugs::             How to usefully report bugs.
 * Integer Functions::         Functions for arithmetic on signed integers.  * Integer Functions::          Functions for arithmetic on signed integers.
 * Rational Number Functions:: Functions for arithmetic on rational numbers.  * Rational Number Functions::  Functions for arithmetic on rational numbers.
 * Floating-point Functions::  Functions for arithmetic on floats.  * Floating-point Functions::   Functions for arithmetic on floats.
 * Low-level Functions::       Fast functions for natural numbers.  * Low-level Functions::        Fast functions for natural numbers.
 * BSD Compatible Functions::  All functions found in BSD MP.  * Random Number Functions::    Functions for generating random numbers.
 * Custom Allocation::         How to customize the internal allocation.  * Formatted Output::           `printf' style output.
   * Formatted Input::            `scanf' style input.
   * C++ Class Interface::        Class wrappers around GMP types.
   * BSD Compatible Functions::   All functions found in BSD MP.
   * Custom Allocation::          How to customize the internal allocation.
   * Language Bindings::          Using GMP from other languages.
   * Algorithms::                 What happens behind the scenes.
   * Internals::                  How values are represented behind the scenes.
   
 * Contributors::  * Contributors::               Who brings your this library?
 * References::  * References::                 Some useful papers and books to read.
   * GNU Free Documentation License::
 * Concept Index::  * Concept Index::
 * Function Index::  * Function Index::
   
   
 File: gmp.info,  Node: Copying,  Next: Introduction to MP,  Prev: Top,  Up: Top  File: gmp.info,  Node: Copying,  Next: Introduction to GMP,  Prev: Top,  Up: Top
   
 GNU MP Copying Conditions  GNU MP Copying Conditions
 *************************  *************************
Line 85  know that what they have is not what we distributed, s
Line 97  know that what they have is not what we distributed, s
 problems introduced by others will not reflect on our reputation.  problems introduced by others will not reflect on our reputation.
   
    The precise conditions of the license for the GNU MP library are     The precise conditions of the license for the GNU MP library are
 found in the Library General Public License that accompany the source  found in the Lesser General Public License version 2.1 that accompanies
 code.  the source code, see `COPYING.LIB'.  Certain demonstration programs are
   provided under the terms of the plain General Public License version 2,
   see `COPYING'.
   
   
 File: gmp.info,  Node: Introduction to MP,  Next: Installing MP,  Prev: Copying,  Up: Top  File: gmp.info,  Node: Introduction to GMP,  Next: Installing GMP,  Prev: Copying,  Up: Top
   
 Introduction to GNU MP  Introduction to GNU MP
 **********************  **********************
Line 101  that need higher precision than is directly supported 
Line 115  that need higher precision than is directly supported 
 types.  types.
   
    Many applications use just a few hundred bits of precision; but some     Many applications use just a few hundred bits of precision; but some
 applications may need thousands or even millions of bits.  MP is  applications may need thousands or even millions of bits.  GMP is
 designed to give good performance for both, by choosing algorithms  designed to give good performance for both, by choosing algorithms
 based on the sizes of the operands, and by carefully keeping the  based on the sizes of the operands, and by carefully keeping the
 overhead at a minimum.  overhead at a minimum.
   
    The speed of MP is achieved by using fullwords as the basic     The speed of GMP is achieved by using fullwords as the basic
 arithmetic type, by using sophisticated algorithms, by including  arithmetic type, by using sophisticated algorithms, by including
 carefully optimized assembly code for the most common inner loops for  carefully optimized assembly code for the most common inner loops for
 many different CPUs, and by a general emphasis on speed (as opposed to  many different CPUs, and by a general emphasis on speed (as opposed to
 simplicity or elegance).  simplicity or elegance).
   
    There is carefully optimized assembly code for these CPUs: DEC     There is carefully optimized assembly code for these CPUs: ARM, DEC
 Alpha, Amd 29000, HPPA 1.0 and 1.1, Intel Pentium and generic x86,  Alpha 21064, 21164, and 21264, AMD 29000, AMD K6, K6-2 and Athlon,
 Intel i960, Motorola MC68000, MC68020, MC88100, and MC88110,  Hitachi SuperH and SH-2, HPPA 1.0, 1.1 and 2.0, Intel Pentium, Pentium
 Motorola/IBM PowerPC, National NS32000, IBM POWER, MIPS R3000, R4000,  Pro/II/III, Pentium 4, generic x86, Intel IA-64, i960, Motorola
 SPARCv7, SuperSPARC, generic SPARCv8, and DEC VAX.  Some optimizations  MC68000, MC68020, MC88100, and MC88110, Motorola/IBM PowerPC 32 and 64,
 also for ARM, Clipper, IBM ROMP (RT), and Pyramid AP/XP.  National NS32000, IBM POWER, MIPS R3000, R4000, SPARCv7, SuperSPARC,
   generic SPARCv8, UltraSPARC, DEC VAX, and Zilog Z8000.  Some
   optimizations also for Cray vector systems, Clipper, IBM ROMP (RT), and
   Pyramid AP/XP.
   
    This version of MP is released under a more liberal license than     There are two public mailing lists of interest.  One for general
 previous versions.  It is now permitted to link MP to non-free  questions and discussions about usage of the GMP library and one for
 programs, as long as MP source code is provided when distributing the  discussions about development of GMP.  There's more information about
 non-free program.  the mailing lists at `http://swox.com/mailman/listinfo/'.  These lists
   are *not* for bug reports.
   
      The proper place for bug reports is <bug-gmp@gnu.org>.  See *Note
   Reporting Bugs:: for info about reporting bugs.
   
      For up-to-date information on GMP, please see the GMP web pages at
   
        `http://swox.com/gmp/'
   
      The latest version of the library is available at
   
        `ftp://ftp.gnu.org/gnu/gmp'
   
      Many sites around the world mirror `ftp.gnu.org', please use a mirror
   near you, see `http://www.gnu.org/order/ftp.html' for a full list.
   
 How to use this Manual  How to use this Manual
 ======================  ======================
   
    Everyone should read *Note MP Basics::.  If you need to install the     Everyone should read *Note GMP Basics::.  If you need to install the
 library yourself, you need to read *Note Installing MP::, too.  library yourself, then read *Note Installing GMP::.  If you have a
   system with multiple ABIs, then read *Note ABI and ISA::, for the
   compiler options that must be used on applications.
   
    The rest of the manual can be used for later reference, although it     The rest of the manual can be used for later reference, although it
 is probably a good idea to glance through it.  is probably a good idea to glance through it.
   
   
 File: gmp.info,  Node: Installing MP,  Next: MP Basics,  Prev: Introduction to MP,  Up: Top  File: gmp.info,  Node: Installing GMP,  Next: GMP Basics,  Prev: Introduction to GMP,  Up: Top
   
 Installing MP  Installing GMP
 *************  **************
   
    To build MP, you first have to configure it for your CPU and     GMP has an autoconf/automake/libtool based configuration system.  On
 operating system.  You need a C compiler, preferably GCC, but any  a Unix-like system a basic build can be done with
 reasonable compiler should work.  And you need a standard Unix `make'  
 program, plus some other standard Unix utility programs.  
   
    (If you're on an MS-DOS machine, your can build MP using `make.bat'.       ./configure
 It requires that djgpp is installed.  It does not require       make
 configuration, nor is `make' needed; `make.bat' both configures and  
 builds the library.)  
   
    Here are the steps needed to install the library on Unix systems:  Some self-tests can be run with
   
   1. In most cases, `./configure --target=cpu-vendor-os', should work       make check
      both for native and cross-compilation.  If you get error messages,  
      your machine might not be supported.  
   
      If you want to compile in a separate object directory, cd to that  And you can install (under `/usr/local' by default) with
      directory, and prefix the configure command with the path to the  
      MP source directory.  Not all `make' programs have the necessary  
      features to support this.  In particular, SunOS and Slowaris  
      `make' have bugs that makes them unable to build from a separate  
      object directory.  Use GNU `make' instead.  
   
      In addition to the standard cpu-vendor-os tuples, MP recognizes       make install
      sparc8 and supersparc as valid CPU names.  Specifying these CPU  
      names for relevant systems will improve performance significantly.  
   
      In general, if you want a library that runs as fast as possible,     If you experience problems, please report them to <bug-gmp@gnu.org>.
      you should make sure you configure MP for the exact CPU type your  See *Note Reporting Bugs::, for information on what to include in
      system uses.  useful bug reports.
   
      If you have `gcc' in your `PATH', it will be used by default.  To  * Menu:
      override this, pass `-with-gcc=no' to `configure'.  
   
   2. `make'  * Build Options::
   * ABI and ISA::
   * Notes for Package Builds::
   * Notes for Particular Systems::
   * Known Build Problems::
   
      This will compile MP, and create a library archive file `libgmp.a'  
      in the working directory.  File: gmp.info,  Node: Build Options,  Next: ABI and ISA,  Prev: Installing GMP,  Up: Installing GMP
   
   3. `make check'  Build Options
   =============
   
      This will make sure MP was built correctly.  If you get error     All the usual autoconf configure options are available, run
      messages, please report this to `bug-gmp@prep.ai.mit.edu'.  (*Note  `./configure --help' for a summary.  The file `INSTALL.autoconf' has
      Reporting Bugs::, for information on what to include in useful bug  some generic installation information too.
      reports.)  
   
   4. `make install'  Non-Unix Systems
        `configure' requires various Unix-like tools.  On an MS-DOS system
        DJGPP can be used, and on MS Windows Cygwin or MINGW can be used,
   
      This will copy the file `gmp.h' and `libgmp.a', as well as the info            `http://www.cygnus.com/cygwin'
      files, to `/usr/local' (or if you passed the `--prefix' option to            `http://www.delorie.com/djgpp'
      `configure', to the directory given as argument to `--prefix').            `http://www.mingw.org'
   
 If you wish to build and install the BSD MP compatible functions, use       Microsoft also publishes an Interix "Services for Unix" which can
 `make libmp.a' and `make install-bsdmp'.       be used to build GMP on Windows (with a normal `./configure'), but
        it's not free software.
   
    There are some other useful make targets:       The `macos' directory contains an unsupported port to MacOS 9 on
        Power Macintosh, see `macos/README'.  Note that MacOS X "Darwin"
        should use the normal Unix-style `./configure'.
   
    * `doc'       It might be possible to build without the help of `configure',
        certainly all the code is there, but unfortunately you'll be on
        your own.
   
      Create a DVI version of the manual, in `gmp.dvi' and a set of info  Build Directory
      files, in `gmp.info', `gmp.info-1', `gmp.info-2', etc.       To compile in a separate build directory, `cd' to that directory,
        and prefix the configure command with the path to the GMP source
        directory.  For example
   
    * `ps'            cd /my/build/dir
             /my/sources/gmp-4.1.2/configure
   
      Create a Postscript version of the manual, in `gmp.ps'.       Not all `make' programs have the necessary features (`VPATH') to
        support this.  In particular, SunOS and Slowaris `make' have bugs
        that make them unable to build in a separate directory.  Use GNU
        `make' instead.
   
    * `html'  `--disable-shared', `--disable-static'
        By default both shared and static libraries are built (where
        possible), but one or other can be disabled.  Shared libraries
        result in smaller executables and permit code sharing between
        separate running processes, but on some CPUs are slightly slower,
        having a small cost on each function call.
   
      Create a HTML version of the manual, in `gmp.html'.  Native Compilation, `--build=CPU-VENDOR-OS'
        For normal native compilation, the system can be specified with
        `--build'.  By default `./configure' uses the output from running
        `./config.guess'.  On some systems `./config.guess' can determine
        the exact CPU type, on others it will be necessary to give it
        explicitly.  For example,
   
    * `clean'            ./configure --build=ultrasparc-sun-solaris2.7
   
      Delete all object files and archive files, but not the       In all cases the `OS' part is important, since it controls how
      configuration files.       libtool generates shared libraries.  Running `./config.guess' is
        the simplest way to see what it should be, if you don't know
        already.
   
    * `distclean'  Cross Compilation, `--host=CPU-VENDOR-OS'
        When cross-compiling, the system used for compiling is given by
        `--build' and the system where the library will run is given by
        `--host'.  For example when using a FreeBSD Athlon system to build
        GNU/Linux m68k binaries,
   
      Delete all files not included in the distribution.            ./configure --build=athlon-pc-freebsd3.5 --host=m68k-mac-linux-gnu
   
    * `uninstall'       Compiler tools are sought first with the host system type as a
        prefix.  For example `m68k-mac-linux-gnu-ranlib' is tried, then
        plain `ranlib'.  This makes it possible for a set of
        cross-compiling tools to co-exist with native tools.  The prefix
        is the argument to `--host', and this can be an alias, such as
        `m68k-linux'.  But note that tools don't have to be setup this
        way, it's enough to just have a `PATH' with a suitable
        cross-compiling `cc' etc.
   
      Delete all files copied by `make install'.       Compiling for a different CPU in the same family as the build
        system is a form of cross-compilation, though very possibly this
        would merely be special options on a native compiler.  In any case
        `./configure' avoids depending on being able to run code on the
        build system, which is important when creating binaries for a
        newer CPU since they very possibly won't run on the build system.
   
 Known Build Problems       In all cases the compiler must be able to produce an executable
 ====================       (of whatever format) from a standard C `main'.  Although only
        object files will go to make up `libgmp', `./configure' uses
        linking tests for various purposes, such as determining what
        functions are available on the host system.
   
    GCC 2.7.2 (as well as 2.6.3) for the RS/6000 and PowerPC can not be       Currently a warning is given unless an explicit `--build' is used
 used to compile MP, due to a bug in GCC.  If you want to use GCC for       when cross-compiling, because it may not be possible to correctly
 these machines, you need to apply the patch below to GCC, or use a       guess the build system type if the `PATH' has only a
 later version of the compiler.       cross-compiling `cc'.
   
    If you are on a Sequent Symmetry, use the GNU assembler instead of       Note that the `--target' option is not appropriate for GMP.  It's
 the system's assembler, since the latter has serious bugs.       for use when building compiler tools, with `--host' being where
        they will run, and `--target' what they'll produce code for.
        Ordinary programs or libraries like GMP are only interested in the
        `--host' part, being where they'll run.  (Some past versions of
        GMP used `--target' incorrectly.)
   
    The system compiler on NeXT is a massacred and old gcc, even if the  CPU types
 compiler calls itself `cc'.  This compiler cannot be used to build MP.       In general, if you want a library that runs as fast as possible,
 You need to get a real gcc, and install that before you compile MP.       you should configure GMP for the exact CPU type your system uses.
 (NeXT might have fixed this in newer releases of their system.)       However, this may mean the binaries won't run on older members of
        the family, and might run slower on other members, older or newer.
        The best idea is always to build GMP for the exact machine type
        you intend to run it on.
   
    The system C compiler under SunOS 4 has a bug that makes it       The following CPUs have specific support.  See `configure.in' for
 miscompile mpq/get_d.c.  This will make `make check' fail.       details of what code and compiler options they select.
   
    Please report other problems to `bug-gmp@prep.ai.mit.edu'.  *Note          * Alpha: alpha, alphaev5, alphaev56, alphapca56, alphapca57,
 Reporting Bugs::.            alphaev6, alphaev67, alphaev68
   
    Patch to apply to GCC 2.6.3 and 2.7.2:          * Cray: c90, j90, t90, sv1
   
      *** config/rs6000/rs6000.md        Sun Feb 11 08:22:11 1996          * HPPA: hppa1.0, hppa1.1, hppa2.0, hppa2.0n, hppa2.0w
      --- config/rs6000/rs6000.md.new    Sun Feb 18 03:33:37 1996  
      ***************  
      *** 920,926 ****  
           (set (match_operand:SI 0 "gpc_reg_operand" "=r")  
         (not:SI (match_dup 1)))]  
          ""  
      !   "nor. %0,%2,%1"  
          [(set_attr "type" "compare")])  
   
        (define_insn ""  
      --- 920,926 ----  
           (set (match_operand:SI 0 "gpc_reg_operand" "=r")  
         (not:SI (match_dup 1)))]  
          ""  
      !   "nor. %0,%1,%1"  
          [(set_attr "type" "compare")])  
   
        (define_insn ""  
   
           * MIPS: mips, mips3, mips64
 File: gmp.info,  Node: MP Basics,  Next: Reporting Bugs,  Prev: Installing MP,  Up: Top  
   
 MP Basics          * Motorola: m68k, m68000, m68010, m68020, m68030, m68040,
 *********            m68060, m68302, m68360, m88k, m88110
   
    All declarations needed to use MP are collected in the include file          * POWER: power, power1, power2, power2sc
 `gmp.h'.  It is designed to work with both C and C++ compilers.  
   
 Nomenclature and Types          * PowerPC: powerpc, powerpc64, powerpc401, powerpc403,
 ======================            powerpc405, powerpc505, powerpc601, powerpc602, powerpc603,
             powerpc603e, powerpc604, powerpc604e, powerpc620, powerpc630,
             powerpc740, powerpc7400, powerpc7450, powerpc750, powerpc801,
             powerpc821, powerpc823, powerpc860,
   
 In this manual, "integer" usually means a multiple precision integer, as          * SPARC: sparc, sparcv8, microsparc, supersparc, sparcv9,
 defined by the MP library.  The C data type for such integers is            ultrasparc, ultrasparc2, ultrasparc2i, ultrasparc3, sparc64
 `mpz_t'.  Here are some examples of how to declare such integers:  
   
      mpz_t sum;          * 80x86 family: i386, i486, i586, pentium, pentiummmx,
             pentiumpro, pentium2, pentium3, pentium4, k6, k62, k63, athlon
      struct foo { mpz_t x, y; };  
   
      mpz_t vec[20];  
   
 "Rational number" means a multiple precision fraction.  The C data type          * Other: a29k, arm, clipper, i960, ns32k, pyramid, sh, sh2, vax,
 for these fractions is `mpq_t'.  For example:            z8k
   
      mpq_t quotient;       CPUs not listed will use generic C code.
   
 "Floating point number" or "Float" for short, is an arbitrary precision  Generic C Build
 mantissa with an limited precision exponent.  The C data type for such       If some of the assembly code causes problems, or if otherwise
 objects is `mpf_t'.       desired, the generic C code can be selected with CPU `none'.  For
        example,
   
 A "limb" means the part of a multi-precision number that fits in a            ./configure --host=none-unknown-freebsd3.5
 single word.  (We chose this word because a limb of the human body is  
 analogous to a digit, only larger, and containing several digits.)  
 Normally a limb contains 32 or 64 bits.  The C data type for a limb is  
 `mp_limb_t'.  
   
 Function Classes       Note that this will run quite slowly, but it should be portable
 ================       and should at least make it possible to get something running if
        all else fails.
   
    There are six classes of functions in the MP library:  `ABI'
        On some systems GMP supports multiple ABIs (application binary
        interfaces), meaning data type sizes and calling conventions.  By
        default GMP chooses the best ABI available, but a particular ABI
        can be selected.  For example
   
   1. Functions for signed integer arithmetic, with names beginning with            ./configure --host=mips64-sgi-irix6 ABI=n32
      `mpz_'.  The associated type is `mpz_t'.  There are about 100  
      functions in this class.  
   
   2. Functions for rational number arithmetic, with names beginning with       See *Note ABI and ISA::, for the available choices on relevant
      `mpq_'.  The associated type is `mpq_t'.  There are about 20       CPUs, and what applications need to do.
      functions in this class, but the functions in the previous class  
      can be used for performing arithmetic on the numerator and  
      denominator separately.  
   
   3. Functions for floating-point arithmetic, with names beginning with  `CC', `CFLAGS'
      `mpf_'.  The associated type is `mpf_t'.  There are about 50       By default the C compiler used is chosen from among some likely
      functions is this class.       candidates, with `gcc' normally preferred if it's present.  The
        usual `CC=whatever' can be passed to `./configure' to choose
        something different.
   
   4. Functions compatible with Berkeley MP, such as `itom', `madd', and       For some systems, default compiler flags are set based on the CPU
      `mult'.  The associated type is `MINT'.       and compiler.  The usual `CFLAGS="-whatever"' can be passed to
        `./configure' to use something different or to set good flags for
        systems GMP doesn't otherwise know.
   
   5. Fast low-level functions that operate on natural numbers.  These       The `CC' and `CFLAGS' used are printed during `./configure', and
      are used by the functions in the preceding groups, and you can       can be found in each generated `Makefile'.  This is the easiest way
      also call them directly from very time-critical user programs.       to check the defaults when considering changing or adding
      These functions' names begin with `mpn_'.  There are about 30       something.
      (hard-to-use) functions in this class.  
   
      The associated type is array of `mp_limb_t'.       Note that when `CC' and `CFLAGS' are specified on a system
        supporting multiple ABIs it's important to give an explicit
        `ABI=whatever', since GMP can't determine the ABI just from the
        flags and won't be able to select the correct assembler code.
   
   6. Miscellaneous functions.  Functions for setting up custom       If just `CC' is selected then normal default `CFLAGS' for that
      allocation.       compiler will be used (if GMP recognises it).  For example
        `CC=gcc' can be used to force the use of GCC, with default flags
        (and default ABI).
   
 MP Variable Conventions  `CPPFLAGS'
 =======================       Any flags like `-D' defines or `-I' includes required by the
        preprocessor should be set in `CPPFLAGS' rather than `CFLAGS'.
        Compiling is done with both `CPPFLAGS' and `CFLAGS', but
        preprocessing uses just `CPPFLAGS'.  This distinction is because
        most preprocessors won't accept all the flags the compiler does.
        Preprocessing is done separately in some configure tests, and in
        the `ansi2knr' support for K&R compilers.
   
    As a general rule, all MP functions expect output arguments before  C++ Support, `--enable-cxx'
 input arguments.  This notation is based on an analogy with the       C++ support in GMP can be enabled with `--enable-cxx', in which
 assignment operator.  (The BSD MP compatibility functions disobey this       case a C++ compiler will be required.  As a convenience
 rule, having the output argument(s) last.)       `--enable-cxx=detect' can be used to enable C++ support only if a
        compiler can be found.  The C++ support consists of a library
        `libgmpxx.la' and header file `gmpxx.h'.
   
    MP allows you to use the same variable for both input and output in       A separate `libgmpxx.la' has been adopted rather than having C++
 the same expression.  For example, the main function for integer       objects within `libgmp.la' in order to ensure dynamic linked C
 multiplication, `mpz_mul', can be used like this: `mpz_mul (x, x, x)'.       programs aren't bloated by a dependency on the C++ standard
 This computes the square of X and puts the result back in X.       library, and to avoid any chance that the C++ compiler could be
        required when linking plain C programs.
   
    Before you can assign to an MP variable, you need to initialize it       `libgmpxx.la' will use certain internals from `libgmp.la' and can
 by calling one of the special initialization functions.  When you're       only be expected to work with `libgmp.la' from the same GMP
 done with a variable, you need to clear it out, using one of the       version.  Future changes to the relevant internals will be
 functions for that purpose.  Which function to use depends on the type       accompanied by renaming, so a mismatch will cause unresolved
 of variable.  See the chapters on integer functions, rational number       symbols rather than perhaps mysterious misbehaviour.
 functions, and floating-point functions for details.  
   
    A variable should only be initialized once, or at least cleared out       In general `libgmpxx.la' will be usable only with the C++ compiler
 between each initialization.  After a variable has been initialized, it       that built it, since name mangling and runtime support are usually
 may be assigned to any number of times.       incompatible between different compilers.
   
    For efficiency reasons, avoid to initialize and clear out a variable  `CXX', `CXXFLAGS'
 in loops.  Instead, initialize it before entering the loop, and clear       When C++ support is enabled, the C++ compiler and its flags can be
 it out after the loop has exited.       set with variables `CXX' and `CXXFLAGS' in the usual way.  The
        default for `CXX' is the first compiler that works from a list of
        likely candidates, with `g++' normally preferred when available.
        The default for `CXXFLAGS' is to try `CFLAGS', `CFLAGS' without
        `-g', then for `g++' either `-g -O2' or `-O2', or for other
        compilers `-g' or nothing.  Trying `CFLAGS' this way is convenient
        when using `gcc' and `g++' together, since the flags for `gcc' will
        usually suit `g++'.
   
    You don't need to be concerned about allocating additional space for       It's important that the C and C++ compilers match, meaning their
 MP variables.  All functions in MP automatically allocate additional       startup and runtime support routines are compatible and that they
 space when a variable does not already have enough space.  They do not,       generate code in the same ABI (if there's a choice of ABIs on the
 however, reduce the space when a smaller number is stored in the       system).  `./configure' isn't currently able to check these things
 object.  Most of the time, this policy is best, since it avoids       very well itself, so for that reason `--disable-cxx' is the
 frequent re-allocation.       default, to avoid a build failure due to a compiler mismatch.
        Perhaps this will change in the future.
   
 Useful Macros and Constants       Incidentally, it's normally not good enough to set `CXX' to the
 ===========================       same as `CC'.  Although `gcc' for instance recognises `foo.cc' as
        C++ code, only `g++' will invoke the linker the right way when
        building an executable or shared library from object files.
   
  - Global Constant: const int mp_bits_per_limb  Temporary Memory, `--enable-alloca=<choice>'
      The number of bits per limb.       GMP allocates temporary workspace using one of the following three
        methods, which can be selected with for instance
        `--enable-alloca=malloc-reentrant'.
   
  - Macro: __GNU_MP_VERSION          * `alloca' - C library or compiler builtin.
  - Macro: __GNU_MP_VERSION_MINOR  
      The major and minor MP version, respectively, as integers.  
   
 Compatibility with Version 1.x          * `malloc-reentrant' - the heap, in a re-entrant fashion.
 ==============================  
   
    This version of MP is upward compatible with previous versions of          * `malloc-notreentrant' - the heap, with global variables.
 MP, with a few exceptions.  
   
   1. Integer division functions round the result differently.  The old       For convenience, the following choices are also available.
      functions (`mpz_div', `mpz_divmod', `mpz_mdiv', `mpz_mdivmod',       `--disable-alloca' is the same as `--enable-alloca=no'.
      etc) now all use floor rounding (i.e., they round the quotient to  
      -infinity).  There are a lot of new functions for integer  
      division, giving the user better control over the rounding.  
   
   2. The function `mpz_mod' now compute the true *mod* function.          * `yes' - a synonym for `alloca'.
   
   3. The functions `mpz_powm' and `mpz_powm_ui' now use *mod* for          * `no' - a synonym for `malloc-reentrant'.
      reduction.  
   
   4. The assignment functions for rational numbers do no longer          * `reentrant' - `alloca' if available, otherwise
      canonicalize their results.  In the case a non-canonical result            `malloc-reentrant'.  This is the default.
      could arise from an assignment, the user need to insert an  
      explicit call to `mpq_canonicalize'.  This change was made for  
      efficiency.  
   
   5. Output generated by `mpz_out_raw' in this release cannot be read          * `notreentrant' - `alloca' if available, otherwise
      by `mpz_inp_raw' in previous releases.  This change was made for            `malloc-notreentrant'.
      making the file format truly portable between machines with  
      different word sizes.  
   
   6. Several `mpn' functions have changed.  But they were intentionally       `alloca' is reentrant and fast, and is recommended, but when
      undocumented in previous releases.       working with large numbers it can overflow the available stack
        space, in which case one of the two malloc methods will need to be
        used.  Alternately it might be possible to increase available
        stack with `limit', `ulimit' or `setrlimit', or under DJGPP with
        `stubedit' or `_stklen'.  Note that depending on the system the
        only indication of stack overflow might be a segmentation
        violation.
   
   7. The functions `mpz_cmp_ui', `mpz_cmp_si', and `mpq_cmp_ui' are now       `malloc-reentrant' is, as the name suggests, reentrant and thread
      implementated as macros, and thereby sometimes evaluate their       safe, but `malloc-notreentrant' is faster and should be used if
      arguments multiple times.       reentrancy is not required.
   
   8. The functions `mpz_pow_ui' and `mpz_ui_pow_ui' now yield 1 for       The two malloc methods in fact use the memory allocation functions
      0^0.  (In version 1, they yielded 0.)       selected by `mp_set_memory_functions', these being `malloc' and
        friends by default.  *Note Custom Allocation::.
   
        An additional choice `--enable-alloca=debug' is available, to help
        when debugging memory related problems (*note Debugging::).
   
 Getting the Latest Version of MP  FFT Multiplication, `--disable-fft'
 ================================       By default multiplications are done using Karatsuba, 3-way
        Toom-Cook, and Fermat FFT.  The FFT is only used on large to very
        large operands and can be disabled to save code size if desired.
   
    The latest version of the MP library is available by anonymous ftp  Berkeley MP, `--enable-mpbsd'
 from from `prep.ai.mit.edu'.  The file name is       The Berkeley MP compatibility library (`libmp') and header file
 `/pub/gnu/gmp-M.N.tar.gz'.  Many sites around the world mirror `prep';       (`mp.h') are built and installed only if `--enable-mpbsd' is used.
 please use a mirror site near you.       *Note BSD Compatible Functions::.
   
   MPFR, `--enable-mpfr'
 File: gmp.info,  Node: Reporting Bugs,  Next: Integer Functions,  Prev: MP Basics,  Up: Top       The optional MPFR functions are built and installed only if
        `--enable-mpfr' is used.  These are in a separate library
        `libmpfr.a' and are documented separately too (*note Introduction
        to MPFR: (mpfr)Introduction to MPFR.).
   
 Reporting Bugs  Assertion Checking, `--enable-assert'
 **************       This option enables some consistency checking within the library.
        This can be of use while debugging, *note Debugging::.
   
    If you think you have found a bug in the MP library, please  Execution Profiling, `--enable-profiling=prof/gprof'
 investigate it and report it.  We have made this library available to       Profiling support can be enabled either for `prof' or `gprof'.
 you, and it is not to ask too much from you, to ask you to report the       This adds `-p' or `-pg' respectively to `CFLAGS', and for some
 bugs that you find.       systems adds corresponding `mcount' calls to the assembler code.
        *Note Profiling::.
   
    There are a few things you should think about when you put your bug  `MPN_PATH'
 report together.       Various assembler versions of each mpn subroutines are provided.
        For a given CPU, a search is made though a path to choose a
        version of each.  For example `sparcv8' has
   
    You have to send us a test case that makes it possible for us to            MPN_PATH="sparc32/v8 sparc32 generic"
 reproduce the bug.  Include instructions on how to run the test case.  
   
    You also have to explain what is wrong; if you get a crash, or if       which means look first for v8 code, then plain sparc32 (which is
 the results printed are incorrect and in that case, in what way.       v7), and finally fall back on generic C.  Knowledgeable users with
        special requirements can specify a different path.  Normally this
        is completely unnecessary.
   
    It is not uncommon that an observed problem is actually due to a bug  Documentation
 in the compiler used when building MP; the MP code tends to explore       The document you're now reading is `gmp.texi'.  The usual automake
 interesting corners in compilers.  Therefore, please include compiler       targets are available to make PostScript `gmp.ps' and/or DVI
 version information in your bug report.  This can be extracted using       `gmp.dvi'.
 `what `which cc`', or, if you're using gcc, `gcc -v'.  Also, include  
 the output from `uname -a'.  
   
    If your bug report is good, we will do our best to help you to get a       HTML can be produced with `makeinfo --html', see *Note Generating
 corrected version of the library; if the bug report is poor, we won't       HTML: (texinfo)makeinfo html.  Or alternately `texi2html', see
 do anything about it (aside of chiding you to send better bug reports).       *Note Texinfo to HTML: (texi2html)Top.
   
    Send your bug report to: `bug-gmp@prep.ai.mit.edu'.       PDF can be produced with `texi2dvi --pdf' (*note PDF: (texinfo)PDF
        Output.) or with `pdftex'.
   
    If you think something in this manual is unclear, or downright       Some supplementary notes can be found in the `doc' subdirectory.
 incorrect, or if the language needs to be improved, please send a note  
 to the same address.  
   
   
 File: gmp.info,  Node: Integer Functions,  Next: Rational Number Functions,  Prev: Reporting Bugs,  Up: Top  File: gmp.info,  Node: ABI and ISA,  Next: Notes for Package Builds,  Prev: Build Options,  Up: Installing GMP
   
 Integer Functions  ABI and ISA
 *****************  ===========
   
    This chapter describes the MP functions for performing integer     ABI (Application Binary Interface) refers to the calling conventions
 arithmetic.  These functions start with the prefix `mpz_'.  between functions, meaning what registers are used and what sizes the
   various C data types are.  ISA (Instruction Set Architecture) refers to
   the instructions and registers a CPU has available.
   
    Arbitrary precision integers are stored in objects of type `mpz_t'.     Some 64-bit ISA CPUs have both a 64-bit ABI and a 32-bit ABI
   defined, the latter for compatibility with older CPUs in the family.
   GMP supports some CPUs like this in both ABIs.  In fact within GMP
   `ABI' means a combination of chip ABI, plus how GMP chooses to use it.
   For example in some 32-bit ABIs, GMP may support a limb as either a
   32-bit `long' or a 64-bit `long long'.
   
 * Menu:     By default GMP chooses the best ABI available for a given system,
   and this generally gives significantly greater speed.  But an ABI can
   be chosen explicitly to make GMP compatible with other libraries, or
   particular application requirements.  For example,
   
 * Initializing Integers::       ./configure ABI=32
 * Assigning Integers::  
 * Simultaneous Integer Init & Assign::  
 * Converting Integers::  
 * Integer Arithmetic::  
 * Comparison Functions::  
 * Integer Logic and Bit Fiddling::  
 * I/O of Integers::  
 * Miscellaneous Integer Functions::  
   
      In all cases it's vital that all object code used in a given program
 File: gmp.info,  Node: Initializing Integers,  Next: Assigning Integers,  Up: Integer Functions  is compiled for the same ABI.
   
 Initialization and Assignment Functions     Usually a limb is implemented as a `long'.  When a `long long' limb
 =======================================  is used this is encoded in the generated `gmp.h'.  This is convenient
   for applications, but it does mean that `gmp.h' will vary, and can't be
   just copied around.  `gmp.h' remains compiler independent though, since
   all compilers for a particular ABI will be expected to use the same
   limb type.
   
    The functions for integer arithmetic assume that all integer objects     Currently no attempt is made to follow whatever conventions a system
 are initialized.  You do that by calling the function `mpz_init'.  has for installing library or header files built for a particular ABI.
   This will probably only matter when installing multiple builds of GMP,
   and it might be as simple as configuring with a special `libdir', or it
   might require more than that.  Note that builds for different ABIs need
   to done separately, with a fresh `./configure' and `make' each.
   
  - Function: void mpz_init (mpz_t INTEGER)  
      Initialize INTEGER with limb space and set the initial numeric  
      value to 0.  Each variable should normally only be initialized  
      once, or at least cleared out (using `mpz_clear') between each  
      initialization.  
   
    Here is an example of using `mpz_init':  HPPA 2.0 (`hppa2.0*')
   
      {      `ABI=2.0w'
        mpz_t integ;            The 2.0w ABI uses 64-bit limbs and pointers and is available
        mpz_init (integ);            on HP-UX 11 or up when using `cc'.  `gcc' support for this is
        ...            in progress.  Applications must be compiled with
        mpz_add (integ, ...);  
        ...  
        mpz_sub (integ, ...);  
   
        /* Unless the program is about to exit, do ... */  
        mpz_clear (integ);  
      }  
   
 As you can see, you can store new values any number of times, once an                 cc  +DD64
 object is initialized.  
   
  - Function: void mpz_clear (mpz_t INTEGER)      `ABI=2.0n'
      Free the limb space occupied by INTEGER.  Make sure to call this            The 2.0n ABI means the 32-bit HPPA 1.0 ABI but with a 64-bit
      function for all `mpz_t' variables when you are done with them.            limb using `long long'.  This is available on HP-UX 10 or up
             when using `cc'.  No `gcc' support is planned for this.
             Applications must be compiled with
   
  - Function: void * _mpz_realloc (mpz_t INTEGER, mp_size_t NEW_ALLOC)                 cc  +DA2.0 +e
      Change the limb space allocation to NEW_ALLOC limbs.  This  
      function is not normally called from user code, but it can be used  
      to give memory back to the heap, or to increase the space of a  
      variable to avoid repeated automatic re-allocation.  
   
  - Function: void mpz_array_init (mpz_t INTEGER_ARRAY[], size_t      `ABI=1.0'
           ARRAY_SIZE, mp_size_t FIXED_NUM_BITS)            HPPA 2.0 CPUs can run all HPPA 1.0 and 1.1 code in the 32-bit
      Allocate *fixed* limb space for all ARRAY_SIZE integers in            HPPA 1.0 ABI.  No special compiler options are needed for
      INTEGER_ARRAY.  The fixed allocation for each integer in the array            applications.
      is enough to store FIXED_NUM_BITS.  If the fixed space will be  
      insufficient for storing the result of a subsequent calculation,  
      the result is unpredictable.  
   
      This function is useful for decreasing the working set for some       All three ABIs are available for CPUs `hppa2.0w' and `hppa2.0', but
      algorithms that use large integer arrays.       for CPU `hppa2.0n' only 2.0n or 1.0 are allowed.
   
      There is no way to de-allocate the storage allocated by this  
      function.  Don't call `mpz_clear'!  
   
   MIPS under IRIX 6 (`mips*-*-irix[6789]')
 File: gmp.info,  Node: Assigning Integers,  Next: Simultaneous Integer Init & Assign,  Prev: Initializing Integers,  Up: Integer Functions       IRIX 6 supports the n32 and 64 ABIs and always has a 64-bit MIPS 3
        or better CPU.  In both these ABIs GMP uses a 64-bit limb.  A new
        enough `gcc' is required (2.95 for instance).
   
 Assignment Functions      `ABI=n32'
 --------------------            The n32 ABI is 32-bit pointers and integers, but with a
             64-bit limb using a `long long'.  Applications must be
             compiled with
   
    These functions assign new values to already initialized integers                 gcc  -mabi=n32
 (*note Initializing Integers::.).                 cc   -n32
   
  - Function: void mpz_set (mpz_t ROP, mpz_t OP)      `ABI=64'
  - Function: void mpz_set_ui (mpz_t ROP, unsigned long int OP)            The 64-bit ABI is 64-bit pointers and integers.  Applications
  - Function: void mpz_set_si (mpz_t ROP, signed long int OP)            must be compiled with
  - Function: void mpz_set_d (mpz_t ROP, double OP)  
  - Function: void mpz_set_q (mpz_t ROP, mpq_t OP)  
  - Function: void mpz_set_f (mpz_t ROP, mpf_t OP)  
      Set the value of ROP from OP.  
   
  - Function: int mpz_set_str (mpz_t ROP, char *STR, int BASE)                 gcc  -mabi=64
      Set the value of ROP from STR, a '\0'-terminated C string in base                 cc   -64
      BASE.  White space is allowed in the string, and is simply  
      ignored.  The base may vary from 2 to 36.  If BASE is 0, the  
      actual base is determined from the leading characters: if the  
      first two characters are `0x' or `0X', hexadecimal is assumed,  
      otherwise if the first character is `0', octal is assumed,  
      otherwise decimal is assumed.  
   
      This function returns 0 if the entire string up to the '\0' is a       Note that MIPS GNU/Linux, as of kernel version 2.2, doesn't have
      valid number in base BASE.  Otherwise it returns -1.       the necessary support for n32 or 64 and so only gets a 32-bit limb
        and the MIPS 2 code.
   
   
 File: gmp.info,  Node: Simultaneous Integer Init & Assign,  Next: Converting Integers,  Prev: Assigning Integers,  Up: Integer Functions  
   
 Combined Initialization and Assignment Functions  PowerPC 64 (`powerpc64', `powerpc620', `powerpc630')
 ------------------------------------------------  
   
    For convenience, MP provides a parallel series of initialize-and-set      `ABI=aix64'
 functions which initialize the output and then store the value there.            The AIX 64 ABI uses 64-bit limbs and pointers and is
 These functions' names have the form `mpz_init_set...'            available on systems `*-*-aix*'.  Applications must be
             compiled (and linked) with
   
    Here is an example of using one:                 gcc  -maix64
                  xlc  -q64
   
      {      `ABI=32'
        mpz_t pie;            This is the basic 32-bit PowerPC ABI.  No special compiler
        mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10);            options are needed for applications.
        ...  
        mpz_sub (pie, ...);  
        ...  
        mpz_clear (pie);  
      }  
   
 Once the integer has been initialized by any of the `mpz_init_set...'  
 functions, it can be used as the source or destination operand for the  
 ordinary integer functions.  Don't use an initialize-and-set function  
 on a variable already initialized!  
   
  - Function: void mpz_init_set (mpz_t ROP, mpz_t OP)  Sparc V9 (`sparcv9' and `ultrasparc*')
  - Function: void mpz_init_set_ui (mpz_t ROP, unsigned long int OP)  
  - Function: void mpz_init_set_si (mpz_t ROP, signed long int OP)  
  - Function: void mpz_init_set_d (mpz_t ROP, double OP)  
      Initialize ROP with limb space and set the initial numeric value  
      from OP.  
   
  - Function: int mpz_init_set_str (mpz_t ROP, char *STR, int BASE)      `ABI=64'
      Initialize ROP and set its value like `mpz_set_str' (see its            The 64-bit V9 ABI is available on Solaris 2.7 and up and
      documentation above for details).            GNU/Linux.  GCC 2.95 or up, or Sun `cc' is required.
             Applications must be compiled with
   
      If the string is a correct base BASE number, the function returns                 gcc  -m64 -mptr64 -Wa,-xarch=v9 -mcpu=v9
      0; if an error occurs it returns -1.  ROP is initialized even if                 cc   -xarch=v9
      an error occurs.  (I.e., you have to call `mpz_clear' for it.)  
   
       `ABI=32'
 File: gmp.info,  Node: Converting Integers,  Next: Integer Arithmetic,  Prev: Simultaneous Integer Init & Assign,  Up: Integer Functions            On Solaris 2.6 and earlier, and on Solaris 2.7 with the
             kernel in 32-bit mode, only the plain V8 32-bit ABI can be
             used, since the kernel doesn't save all registers.  GMP still
             uses as much of the V9 ISA as it can in these circumstances.
             No special compiler options are required for applications,
             though using something like the following requesting V9 code
             within the V8 ABI is recommended.
   
 Conversion Functions                 gcc  -mv8plus
 ====================                 cc   -xarch=v8plus
   
    This section describes functions for converting arbitrary precision            `gcc' 2.8 and earlier only supports `-mv8' though.
 integers to standard C types.  Functions for converting *to* arbitrary  
 precision integers are described in *Note Assigning Integers:: and  
 *Note I/O of Integers::.  
   
  - Function: unsigned long int mpz_get_ui (mpz_t OP)       Don't be confused by the names of these sparc `-m' and `-x'
      Return the least significant part from OP.  This function combined       options, they're called `arch' but they effectively control the
      with       ABI.
      `mpz_tdiv_q_2exp(..., OP, CHAR_BIT*sizeof(unsigned long int))' can  
      be used to extract the limbs of an integer.  
   
  - Function: signed long int mpz_get_si (mpz_t OP)       On Solaris 2.7 with the kernel in 32-bit-mode, a normal native
      If OP fits into a `signed long int' return the value of OP.       build will reject `ABI=64' because the resulting executables won't
      Otherwise return the least significant part of OP, with the same       run.  `ABI=64' can still be built if desired by making it look
      sign as OP.       like a cross-compile, for example
   
      If OP is too large to fit in a `signed long int', the returned            ./configure --build=none --host=sparcv9-sun-solaris2.7 ABI=64
      result is probably not very useful.  
   
  - Function: double mpz_get_d (mpz_t OP)  
      Convert OP to a double.  
   
  - Function: char * mpz_get_str (char *STR, int BASE, mpz_t OP)  
      Convert OP to a string of digits in base BASE.  The base may vary  
      from 2 to 36.  
   
      If STR is NULL, space for the result string is allocated using the  
      default allocation function, and a pointer to the string is  
      returned.  
   
      If STR is not NULL, it should point to a block of storage enough  
      large for the result.  To find out the right amount of space to  
      provide for STR, use `mpz_sizeinbase (OP, BASE) + 2'.  The two  
      extra bytes are for a possible minus sign, and for the terminating  
      null character.  
   
   
 File: gmp.info,  Node: Integer Arithmetic,  Next: Comparison Functions,  Prev: Converting Integers,  Up: Integer Functions  File: gmp.info,  Node: Notes for Package Builds,  Next: Notes for Particular Systems,  Prev: ABI and ISA,  Up: Installing GMP
   
 Arithmetic Functions  Notes for Package Builds
 ====================  ========================
   
  - Function: void mpz_add (mpz_t ROP, mpz_t OP1, mpz_t OP2)     GMP should present no great difficulties for packaging in a binary
  - Function: void mpz_add_ui (mpz_t ROP, mpz_t OP1, unsigned long int  distribution.
           OP2)  
      Set ROP to OP1 + OP2.  
   
  - Function: void mpz_sub (mpz_t ROP, mpz_t OP1, mpz_t OP2)     Libtool is used to build the library and `-version-info' is set
  - Function: void mpz_sub_ui (mpz_t ROP, mpz_t OP1, unsigned long int  appropriately, having started from `3:0:0' in GMP 3.0.  The GMP 4 series
           OP2)  will be upwardly binary compatible in each release and will be upwardly
      Set ROP to OP1 - OP2.  binary compatible with all of the GMP 3 series.  Additional function
   interfaces may be added in each release, so on systems where libtool
   versioning is not fully checked by the loader an auxiliary mechanism
   may be needed to express that a dynamic linked application depends on a
   new enough GMP.
   
  - Function: void mpz_mul (mpz_t ROP, mpz_t OP1, mpz_t OP2)     An auxiliary mechanism may also be needed to express that
  - Function: void mpz_mul_ui (mpz_t ROP, mpz_t OP1, unsigned long int  `libgmpxx.la' (from `--enable-cxx', *note Build Options::) requires
           OP2)  `libgmp.la' from the same GMP version, since this is not done by the
      Set ROP to OP1 times OP2.  libtool versioning, nor otherwise.  A mismatch will result in
   unresolved symbols from the linker, or perhaps the loader.
   
  - Function: void mpz_mul_2exp (mpz_t ROP, mpz_t OP1, unsigned long int     Using `DESTDIR' or a `prefix' override with `make install' and a
           OP2)  shared `libgmpxx' may run into a libtool relinking problem, see *Note
      Set ROP to OP1 times 2 raised to OP2.  This operation can also be  Known Build Problems::.
      defined as a left shift, OP2 steps.  
   
  - Function: void mpz_neg (mpz_t ROP, mpz_t OP)     When building a package for a CPU family, care should be taken to use
      Set ROP to -OP.  `--host' (or `--build') to choose the least common denominator among
   the CPUs which might use the package.  For example this might
   necessitate `i386' for x86s, or plain `sparc' (meaning V7) for SPARCs.
   
  - Function: void mpz_abs (mpz_t ROP, mpz_t OP)     Users who care about speed will want GMP built for their exact CPU
      Set ROP to the absolute value of OP.  type, to make use of the available optimizations.  Providing a way to
   suitably rebuild a package may be useful.  This could be as simple as
   making it possible for a user to omit `--build' (and `--host') so
   `./config.guess' will detect the CPU.  But a way to manually specify a
   `--build' will be wanted for systems where `./config.guess' is inexact.
   
  - Function: void mpz_fac_ui (mpz_t ROP, unsigned long int OP)     Note that `gmp.h' is a generated file, and will be architecture and
      Set ROP to OP!, the factorial of OP.  ABI dependent.
   
 Division functions  
 ------------------  File: gmp.info,  Node: Notes for Particular Systems,  Next: Known Build Problems,  Prev: Notes for Package Builds,  Up: Installing GMP
   
    Division is undefined if the divisor is zero, and passing a zero  Notes for Particular Systems
 divisor to the divide or modulo functions, as well passing a zero mod  ============================
 argument to the `mpz_powm' and `mpz_powm_ui' functions, will make these  
 functions intentionally divide by zero.  This gives the user the  
 possibility to handle arithmetic exceptions in these functions in the  
 same manner as other arithmetic exceptions.  
   
    There are three main groups of division functions:  AIX 3 and 4
    * Functions that truncate the quotient towards 0.  The names of these       On systems `*-*-aix[34]*' shared libraries are disabled by
      functions start with `mpz_tdiv'.  The `t' in the name is short for       default, since some versions of the native `ar' fail on the
      `truncate'.       convenience libraries used.  A shared build can be attempted with
   
    * Functions that round the quotient towards -infinity.  The names of            ./configure --enable-shared --disable-static
      these routines start with `mpz_fdiv'.  The `f' in the name is  
      short for `floor'.  
   
    * Functions that round the quotient towards +infinity.  The names of       Note that the `--disable-static' is necessary because in a shared
      these routines start with `mpz_cdiv'.  The `c' in the name is       build libtool makes `libgmp.a' a symlink to `libgmp.so',
      short for `ceil'.       apparently for the benefit of old versions of `ld' which only
        recognise `.a', but unfortunately this is done even if a fully
        functional `ld' is available.
   
    For each rounding mode, there are a couple of variants.  Here `q'  ARM
 means that the quotient is computed, while `r' means that the remainder       On systems `arm*-*-*', versions of GCC up to and including 2.95.3
 is computed.  Functions that compute both the quotient and remainder       have a bug in unsigned division, giving wrong results for some
 have `qr' in the name.       operands.  GMP `./configure' will demand GCC 2.95.4 or later.
   
  - Function: void mpz_tdiv_q (mpz_t ROP, mpz_t OP1, mpz_t OP2)  Compaq C++
  - Function: void mpz_tdiv_q_ui (mpz_t ROP, mpz_t OP1, unsigned long       Compaq C++ on OSF 5.1 has two flavours of `iostream', a standard
           int OP2)       one and an old pre-standard one (see `man iostream_intro').  GMP
      Set ROP to [OP1/OP2].  The quotient is truncated towards 0.       can only use the standard one, which unfortunately is not the
        default but must be selected by defining `__USE_STD_IOSTREAM'.
        Configure with for instance
   
  - Function: void mpz_tdiv_r (mpz_t ROP, mpz_t OP1, mpz_t OP2)            ./configure --enable-cxx CPPFLAGS=-D__USE_STD_IOSTREAM
  - Function: void mpz_tdiv_r_ui (mpz_t ROP, mpz_t OP1, unsigned long  
           int OP2)  
      Set ROP to (OP1 - [OP1/OP2] * OP2).  Unless the remainder is zero,  
      it has the same sign as the dividend.  
   
  - Function: void mpz_tdiv_qr (mpz_t ROP1, mpz_t ROP2, mpz_t OP1, mpz_t  Microsoft Windows
           OP2)       On systems `*-*-cygwin*', `*-*-mingw*' and `*-*-pw32*' by default
  - Function: void mpz_tdiv_qr_ui (mpz_t ROP1, mpz_t ROP2, mpz_t OP1,       GMP builds only a static library, but a DLL can be built instead
           unsigned long int OP2)       using
      Divide OP1 by OP2 and put the quotient in ROP1 and the remainder  
      in ROP2.  The quotient is rounded towards 0.  Unless the remainder  
      is zero, it has the same sign as the dividend.  
   
      If ROP1 and ROP2 are the same variable, the results are undefined.            ./configure --disable-static --enable-shared
   
  - Function: void mpz_fdiv_q (mpz_t ROP1, mpz_t OP1, mpz_t OP2)       Static and DLL libraries can't both be built, since certain export
  - Function: void mpz_fdiv_q_ui (mpz_t ROP, mpz_t OP1, unsigned long       directives in `gmp.h' must be different.  `--enable-cxx' cannot be
           int OP2)       used when building a DLL, since libtool doesn't currently support
      Set ROP to OP1/OP2.  The quotient is rounded towards -infinity.       C++ DLLs.  This might change in the future.
   
  - Function: void mpz_fdiv_r (mpz_t ROP, mpz_t OP1, mpz_t OP2)  Microsoft C
  - Function: unsigned long int mpz_fdiv_r_ui (mpz_t ROP, mpz_t OP1,       A MINGW DLL build of GMP can be used with Microsoft C.  Libtool
           unsigned long int OP2)       doesn't install `.lib' and `.exp' files, but they can be created
      Divide OP1 by OP2 and put the remainder in ROP.  Unless the       with the following commands, where `/my/inst/dir' is the install
      remainder is zero, it has the same sign as the divisor.       directory (with a `lib' subdirectory).
   
      For `mpz_fdiv_r_ui' the remainder is small enough to fit in an            lib /machine:IX86 /def:_libs/libgmp-3.dll-def
      `unsigned long int', and is therefore returned.            cp libgmp-3.lib /my/inst/dir/lib
             cp _libs/libgmp-3.dll-exp /my/inst/dir/lib/libgmp-3.exp
   
  - Function: void mpz_fdiv_qr (mpz_t ROP1, mpz_t ROP2, mpz_t OP1, mpz_t       MINGW uses `msvcrt.dll' for I/O, so applications wanting to use
           OP2)       the GMP I/O routines must be compiled with `cl /MD' to do the
  - Function: unsigned long int mpz_fdiv_qr_ui (mpz_t ROP1, mpz_t ROP2,       same.  If one of the other I/O choices provided by MS C is desired
           mpz_t OP1, unsigned long int OP2)       then the suggestion is to use the GMP string functions and confine
      Divide OP1 by OP2 and put the quotient in ROP1 and the remainder       I/O to the application.
      in ROP2.  The quotient is rounded towards -infinity.  Unless the  
      remainder is zero, it has the same sign as the divisor.  
   
      For `mpz_fdiv_qr_ui' the remainder is small enough to fit in an  Motorola 68k CPU Types
      `unsigned long int', and is therefore returned.       `m68k' is taken to mean 68000.  `m68020' or higher will give a
        performance boost on applicable CPUs.  `m68360' can be used for
        CPU32 series chips.  `m68302' can be used for "Dragonball" series
        chips, though this is merely a synonym for `m68000'.
   
      If ROP1 and ROP2 are the same variable, the results are undefined.  OpenBSD 2.6
        `m4' in this release of OpenBSD has a bug in `eval' that makes it
        unsuitable for `.asm' file processing.  `./configure' will detect
        the problem and either abort or choose another m4 in the `PATH'.
        The bug is fixed in OpenBSD 2.7, so either upgrade or use GNU m4.
   
  - Function: unsigned long int mpz_fdiv_ui (mpz_t OP1, unsigned long  Power CPU Types
           int OP2)       In GMP, CPU types `power*' and `powerpc*' will each use
      This function is similar to `mpz_fdiv_r_ui', but the remainder is       instructions not available on the other, so it's important to
      only returned; it is not stored anywhere.       choose the right one for the CPU that will be used.  Currently GMP
        has no assembler code support for using just the common
        instruction subset.  To get executables that run on both, the
        current suggestion is to use the generic C code (CPU `none'),
        possibly with appropriate compiler options (like `-mcpu=common' for
        `gcc').  CPU `rs6000' (which is not a CPU but a family of
        workstations) is accepted by `config.sub', but is currently
        equivalent to `none'.
   
  - Function: void mpz_cdiv_q (mpz_t ROP1, mpz_t OP1, mpz_t OP2)  Sparc CPU Types
  - Function: void mpz_cdiv_q_ui (mpz_t ROP, mpz_t OP1, unsigned long       `sparcv8' or `supersparc' on relevant systems will give a
           int OP2)       significant performance increase over the V7 code.
      Set ROP to OP1/OP2.  The quotient is rounded towards +infinity.  
   
  - Function: void mpz_cdiv_r (mpz_t ROP, mpz_t OP1, mpz_t OP2)  Sparc App Regs
  - Function: unsigned long int mpz_cdiv_r_ui (mpz_t ROP, mpz_t OP1,       The GMP assembler code for both 32-bit and 64-bit Sparc clobbers
           unsigned long int OP2)       the "application registers" `g2', `g3' and `g4', the same way that
      Divide OP1 by OP2 and put the remainder in ROP.  Unless the       the GCC default `-mapp-regs' does (*note SPARC Options: (gcc)SPARC
      remainder is zero, it has the opposite sign as the divisor.       Options.).
   
      For `mpz_cdiv_r_ui' the negated remainder is small enough to fit       This makes that code unsuitable for use with the special V9
      in an `unsigned long int', and it is therefore returned.       `-mcmodel=embmedany' (which uses `g4' as a data segment pointer),
        and for applications wanting to use those registers for special
        purposes.  In these cases the only suggestion currently is to
        build GMP with CPU `none' to avoid the assembler code.
   
  - Function: void mpz_cdiv_qr (mpz_t ROP1, mpz_t ROP2, mpz_t OP1, mpz_t  SunOS 4
           OP2)       `/usr/bin/m4' lacks various features needed to process `.asm'
  - Function: unsigned long int mpz_cdiv_qr_ui (mpz_t ROP1, mpz_t ROP2,       files, and instead `./configure' will automatically use
           mpz_t OP1, unsigned long int OP2)       `/usr/5bin/m4', which we believe is always available (if not then
      Divide OP1 by OP2 and put the quotient in ROP1 and the remainder       use GNU m4).
      in ROP2.  The quotient is rounded towards +infinity.  Unless the  
      remainder is zero, it has the opposite sign as the divisor.  
   
      For `mpz_cdiv_qr_ui' the negated remainder is small enough to fit  x86 CPU Types
      in an `unsigned long int', and it is therefore returned.       `i386' selects generic code which will run reasonably well on all
        x86 chips.
   
      If ROP1 and ROP2 are the same variable, the results are undefined.       `i586', `pentium' or `pentiummmx' code is good for the intended P5
        Pentium chips, but quite slow when run on Intel P6 class chips
        (PPro, P-II, P-III).  `i386' is a better choice when making
        binaries that must run on both.
   
  - Function: unsigned long int mpz_cdiv_ui (mpz_t OP1, unsigned long       `pentium4' and an SSE2 capable assembler are important for best
           int OP2)       results on Pentium 4.  The specific code is for instance roughly a
      Return the negated remainder, similar to `mpz_cdiv_r_ui'.  (The       2x to 3x speedup over the generic `i386' code.
      difference is that this function doesn't store the remainder  
      anywhere.)  
   
  - Function: void mpz_mod (mpz_t ROP, mpz_t OP1, mpz_t OP2)  x86 MMX and SSE2 Code
  - Function: unsigned long int mpz_mod_ui (mpz_t ROP, mpz_t OP1,       If the CPU selected has MMX code but the assembler doesn't support
           unsigned long int OP2)       it, a warning is given and non-MMX code is used instead.  This
      Set ROP to OP1 `mod' OP2.  The sign of the divisor is ignored, and       will be an inferior build, since the MMX code that's present is
      the result is always non-negative.       there because it's faster than the corresponding plain integer
        code.  The same applies to SSE2.
   
      For `mpz_mod_ui' the remainder is small enough to fit in an       Old versions of `gas' don't support MMX instructions, in particular
      `unsigned long int', and is therefore returned.       version 1.92.3 that comes with FreeBSD 2.2.8 doesn't (and
        unfortunately there's no newer assembler for that system).
   
  - Function: void mpz_divexact (mpz_t ROP, mpz_t OP1, mpz_t OP2)       Solaris 2.6 and 2.7 `as' generate incorrect object code for
      Set ROP to OP1/OP2.  This function produces correct results only       register to register `movq' instructions, and so can't be used for
      when it is known in advance that OP2 divides OP1.       MMX code.  Install a recent `gas' if MMX code is wanted on these
        systems.
   
      Since mpz_divexact is much faster than any of the other routines  
      that produce the quotient (*note References::. Jebelean), it is  
      the best choice for instances in which exact division is known to  
      occur, such as reducing a rational to lowest terms.  
   
  - Function: void mpz_tdiv_q_2exp (mpz_t ROP, mpz_t OP1, unsigned long  
           int OP2)  
      Set ROP to OP1 divided by 2 raised to OP2.  The quotient is  
      rounded towards 0.  
   
  - Function: void mpz_tdiv_r_2exp (mpz_t ROP, mpz_t OP1, unsigned long  
           int OP2)  
      Divide OP1 by (2 raised to OP2) and put the remainder in ROP.  
      Unless it is zero, ROP will have the same sign as OP1.  
   
  - Function: void mpz_fdiv_q_2exp (mpz_t ROP, mpz_t OP1, unsigned long  
           int OP2)  
      Set ROP to OP1 divided by 2 raised to OP2.  The quotient is  
      rounded towards -infinity.  
   
  - Function: void mpz_fdiv_r_2exp (mpz_t ROP, mpz_t OP1, unsigned long  
           int OP2)  
      Divide OP1 by (2 raised to OP2) and put the remainder in ROP.  The  
      sign of ROP will always be positive.  
   
      This operation can also be defined as masking of the OP2 least  
      significant bits.  
   
 Exponentialization Functions  
 ----------------------------  
   
  - Function: void mpz_powm (mpz_t ROP, mpz_t BASE, mpz_t EXP, mpz_t MOD)  
  - Function: void mpz_powm_ui (mpz_t ROP, mpz_t BASE, unsigned long int  
           EXP, mpz_t MOD)  
      Set ROP to (BASE raised to EXP) `mod' MOD.  If EXP is negative,  
      the result is undefined.  
   
  - Function: void mpz_pow_ui (mpz_t ROP, mpz_t BASE, unsigned long int  
           EXP)  
  - Function: void mpz_ui_pow_ui (mpz_t ROP, unsigned long int BASE,  
           unsigned long int EXP)  
      Set ROP to BASE raised to EXP.  The case of 0^0 yields 1.  
   
 Square Root Functions  
 ---------------------  
   
  - Function: void mpz_sqrt (mpz_t ROP, mpz_t OP)  
      Set ROP to the truncated integer part of the square root of OP.  
   
  - Function: void mpz_sqrtrem (mpz_t ROP1, mpz_t ROP2, mpz_t OP)  
      Set ROP1 to the truncated integer part of the square root of OP,  
      like `mpz_sqrt'.  Set ROP2 to OP-ROP1*ROP1, (i.e., zero if OP is a  
      perfect square).  
   
      If ROP1 and ROP2 are the same variable, the results are undefined.  
   
  - Function: int mpz_perfect_square_p (mpz_t OP)  
      Return non-zero if OP is a perfect square, i.e., if the square  
      root of OP is an integer.  Return zero otherwise.  
   
 Number Theoretic Functions  
 --------------------------  
   
  - Function: int mpz_probab_prime_p (mpz_t OP, int REPS)  
      If this function returns 0, OP is definitely not prime.  If it  
      returns 1, then OP is `probably' prime.  The probability of a  
      false positive is (1/4)**REPS.  A reasonable value of reps is 25.  
   
      An implementation of the probabilistic primality test found in  
      Seminumerical Algorithms (*note References::. Knuth).  
   
  - Function: void mpz_gcd (mpz_t ROP, mpz_t OP1, mpz_t OP2)  
      Set ROP to the greatest common divisor of OP1 and OP2.  
   
  - Function: unsigned long int mpz_gcd_ui (mpz_t ROP, mpz_t OP1,  
           unsigned long int OP2)  
      Compute the greatest common divisor of OP1 and OP2.  If ROP is not  
      NULL, store the result there.  
   
      If the result is small enough to fit in an `unsigned long int', it  
      is returned.  If the result does not fit, 0 is returned, and the  
      result is equal to the argument OP1.  Note that the result will  
      always fit if OP2 is non-zero.  
   
  - Function: void mpz_gcdext (mpz_t G, mpz_t S, mpz_t T, mpz_t A, mpz_t  
           B)  
      Compute G, S, and T, such that AS + BT = G = `gcd' (A, B).  If T is  
      NULL, that argument is not computed.  
   
  - Function: int mpz_invert (mpz_t ROP, mpz_t OP1, mpz_t OP2)  
      Compute the inverse of OP1 modulo OP2 and put the result in ROP.  
      Return non-zero if an inverse exist, zero otherwise.  When the  
      function returns zero, do not assume anything about the value in  
      ROP.  
   
  - Function: int mpz_jacobi (mpz_t OP1, mpz_t OP2)  
  - Function: int mpz_legendre (mpz_t OP1, mpz_t OP2)  
      Compute the Jacobi and Legendre symbols, respectively.  
   
   
 File: gmp.info,  Node: Comparison Functions,  Next: Integer Logic and Bit Fiddling,  Prev: Integer Arithmetic,  Up: Integer Functions  File: gmp.info,  Node: Known Build Problems,  Prev: Notes for Particular Systems,  Up: Installing GMP
   
 Comparison Functions  Known Build Problems
 ====================  ====================
   
  - Function: int mpz_cmp (mpz_t OP1, mpz_t OP2)     You might find more up-to-date information at `http://swox.com/gmp/'.
      Compare OP1 and OP2.  Return a positive value if OP1 > OP2, zero  
      if OP1 = OP2, and a negative value if OP1 < OP2.  
   
  - Macro: int mpz_cmp_ui (mpz_t OP1, unsigned long int OP2)  Compiler link options
  - Macro: int mpz_cmp_si (mpz_t OP1, signed long int OP2)       The version of libtool currently in use rather aggressively strips
      Compare OP1 and OP2.  Return a positive value if OP1 > OP2, zero       compiler options when linking a shared library.  This will
      if OP1 = OP2, and a negative value if OP1 < OP2.       hopefully be relaxed in the future, but for now if this is a
        problem the suggestion is to create a little script to hide them,
        and for instance configure with
   
      These functions are actually implemented as macros.  They evaluate            ./configure CC=gcc-with-my-options
      their arguments multiple times.  
   
  - Macro: int mpz_sgn (mpz_t OP)  DJGPP
      Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0.       The DJGPP port of `bash' 2.03 is unable to run the `configure'
        script, it exits silently, having died writing a preamble to
        `config.log'.  Use `bash' 2.04 or higher.
   
      This function is actually implemented as a macro.  It evaluates its       `make all' was found to run out of memory during the final
      arguments multiple times.       `libgmp.la' link on one system tested, despite having 64Mb
        available.  A separate `make libgmp.la' helped, perhaps recursing
        into the various subdirectories uses up memory.
   
   `DESTDIR' and shared `libgmpxx'
 File: gmp.info,  Node: Integer Logic and Bit Fiddling,  Next: I/O of Integers,  Prev: Comparison Functions,  Up: Integer Functions       `make install DESTDIR=/my/staging/area', or the same with a
        `prefix' override, to install to a temporary directory is not
        fully supported by current versions of libtool when building a
        shared version of a library which depends on another being built
        at the same time, like `libgmpxx' and `libgmp'.
   
 Logical and Bit Manipulation Functions       The problem is that `libgmpxx' is relinked at the install stage to
 ======================================       ensure that if the system puts a hard-coded path to `libgmp' within
        `libgmpxx' then that path will be correct.  Naturally the linker is
        directed to look only at the final location, not the staging area,
        so if `libgmp' is not already in that final location then the link
        will fail.
   
    These functions behave as if two's complement arithmetic were used       A workaround for this on SVR4 style systems, such as GNU/Linux,
 (although sign-magnitude is used by the actual implementation).       where paths are not hard-coded, is to include the staging area in
        the linker's search using `LD_LIBRARY_PATH'.  For example with
        `--prefix=/usr' but installing under `/my/staging/area',
   
  - Function: void mpz_and (mpz_t ROP, mpz_t OP1, mpz_t OP2)            LD_LIBRARY_PATH=/my/staging/area/usr/lib \
      Set ROP to OP1 logical-and OP2.              make install DESTDIR=/my/staging/area
   
  - Function: void mpz_ior (mpz_t ROP, mpz_t OP1, mpz_t OP2)  GNU binutils `strip' prior to 2.12
      Set ROP to OP1 inclusive-or OP2.       `strip' from GNU binutils 2.11 and earlier should not be used on
        the static libraries `libgmp.a' and `libmp.a' since it will
        discard all but the last of multiple archive members with the same
        name, like the three versions of `init.o' in `libgmp.a'.  Binutils
        2.12 or higher can be used successfully.
   
  - Function: void mpz_com (mpz_t ROP, mpz_t OP)       The shared libraries `libgmp.so' and `libmp.so' are not affected by
      Set ROP to the one's complement of OP.       this and any version of `strip' can be used on them.
   
  - Function: unsigned long int mpz_popcount (mpz_t OP)  `make' syntax error
      For non-negative numbers, return the population count of OP.  For       On certain versions of SCO OpenServer 5 and IRIX 6.5 the native
      negative numbers, return the largest possible value (MAX_ULONG).       `make' is unable to handle the long dependencies list for
        `libgmp.la'.  The symptom is a "syntax error" on the following
        line of the top-level `Makefile'.
   
  - Function: unsigned long int mpz_hamdist (mpz_t OP1, mpz_t OP2)            libgmp.la: $(libgmp_la_OBJECTS) $(libgmp_la_DEPENDENCIES)
      If OP1 and OP2 are both non-negative, return the hamming distance  
      between the two operands.  Otherwise, return the largest possible  
      value (MAX_ULONG).  
   
      It is possible to extend this function to return a useful value       Either use GNU Make, or as a workaround remove
      when the operands are both negative, but the current       `$(libgmp_la_DEPENDENCIES)' from that line (which will make the
      implementation returns MAX_ULONG in this case.  *Do not depend on       initial build work, but if any recompiling is done `libgmp.la'
      this behavior, since it will change in future versions of the       might not be rebuilt).
      library.*  
   
  - Function: unsigned long int mpz_scan0 (mpz_t OP, unsigned long int  MacOS X and GCC
           STARTING_BIT)       Libtool currently only knows how to create shared libraries on
      Scan OP, starting with bit STARTING_BIT, towards more significant       MacOS X using the native `cc' (which is a modified GCC), not a
      bits, until the first clear bit is found.  Return the index of the       plain GCC.  A static-only build should work though
      found bit.       (`--disable-shared').
   
  - Function: unsigned long int mpz_scan1 (mpz_t OP, unsigned long int       Also, libtool currently cannot build C++ shared libraries on MacOS
           STARTING_BIT)       X, so if `--enable-cxx' is desired then `--disable-shared' must be
      Scan OP, starting with bit STARTING_BIT, towards more significant       used.  Hopefully this will be fixed in the future.
      bits, until the first set bit is found.  Return the index of the  
      found bit.  
   
  - Function: void mpz_setbit (mpz_t ROP, unsigned long int BIT_INDEX)  NeXT prior to 3.3
      Set bit BIT_INDEX in OP1.       The system compiler on old versions of NeXT was a massacred and
        old GCC, even if it called itself `cc'.  This compiler cannot be
        used to build GMP, you need to get a real GCC, and install that.
        (NeXT may have fixed this in release 3.3 of their system.)
   
  - Function: void mpz_clrbit (mpz_t ROP, unsigned long int BIT_INDEX)  POWER and PowerPC
      Clear bit BIT_INDEX in OP1.       Bugs in GCC 2.7.2 (and 2.6.3) mean it can't be used to compile GMP
        on POWER or PowerPC.  If you want to use GCC for these machines,
        get GCC 2.7.2.1 (or later).
   
   Sequent Symmetry
 File: gmp.info,  Node: I/O of Integers,  Next: Miscellaneous Integer Functions,  Prev: Integer Logic and Bit Fiddling,  Up: Integer Functions       Use the GNU assembler instead of the system assembler, since the
        latter has serious bugs.
   
 Input and Output Functions  Solaris 2.6
 ==========================       The system `sed' prints an error "Output line too long" when
        libtool builds `libgmp.la'.  This doesn't seem to cause any
        obvious ill effects, but GNU `sed' is recommended, to avoid any
        doubt.
   
    Functions that perform input from a stdio stream, and functions that  Sparc Solaris 2.7 with gcc 2.95.2 in ABI=32
 output to a stdio stream.  Passing a NULL pointer for a STREAM argument       A shared library build of GMP seems to fail in this combination,
 to any of these functions will make them read from `stdin' and write to       it builds but then fails the tests, apparently due to some
 `stdout', respectively.       incorrect data relocations within `gmp_randinit_lc_2exp_size'.
        The exact cause is unknown, `--disable-shared' is recommended.
   
    When using any of these functions, it is a good idea to include  Windows DLL test programs
 `stdio.h' before `gmp.h', since that will allow `gmp.h' to define       When creating a DLL version of `libgmp', libtool creates wrapper
 prototypes for these functions.       scripts like `t-mul' for programs that would normally be
        `t-mul.exe', in order to setup the right library paths etc.  This
        works fine, but the absence of `t-mul.exe' etc causes `make' to
        think they need recompiling every time, which is an annoyance when
        re-running a `make check'.
   
  - Function: size_t mpz_out_str (FILE *STREAM, int BASE, mpz_t OP)  
      Output OP on stdio stream STREAM, as a string of digits in base  
      BASE.  The base may vary from 2 to 36.  
   
      Return the number of bytes written, or if an error occurred,  
      return 0.  
   
  - Function: size_t mpz_inp_str (mpz_t ROP, FILE *STREAM, int BASE)  
      Input a possibly white-space preceded string in base BASE from  
      stdio stream STREAM, and put the read integer in ROP.  The base  
      may vary from 2 to 36.  If BASE is 0, the actual base is  
      determined from the leading characters: if the first two  
      characters are `0x' or `0X', hexadecimal is assumed, otherwise if  
      the first character is `0', octal is assumed, otherwise decimal is  
      assumed.  
   
      Return the number of bytes read, or if an error occurred, return 0.  
   
  - Function: size_t mpz_out_raw (FILE *STREAM, mpz_t OP)  
      Output OP on stdio stream STREAM, in raw binary format.  The  
      integer is written in a portable format, with 4 bytes of size  
      information, and that many bytes of limbs.  Both the size and the  
      limbs are written in decreasing significance order (i.e., in  
      big-endian).  
   
      The output can be read with `mpz_inp_raw'.  
   
      Return the number of bytes written, or if an error occurred,  
      return 0.  
   
      The output of this can not be read by `mpz_inp_raw' from GMP 1,  
      because of changes necessary for compatibility between 32-bit and  
      64-bit machines.  
   
  - Function: size_t mpz_inp_raw (mpz_t ROP, FILE *STREAM)  
      Input from stdio stream STREAM in the format written by  
      `mpz_out_raw', and put the result in ROP.  Return the number of  
      bytes read, or if an error occurred, return 0.  
   
      This routine can read the output from `mpz_out_raw' also from GMP  
      1, in spite of changes necessary for compatibility between 32-bit  
      and 64-bit machines.  
   
   
 File: gmp.info,  Node: Miscellaneous Integer Functions,  Prev: I/O of Integers,  Up: Integer Functions  File: gmp.info,  Node: GMP Basics,  Next: Reporting Bugs,  Prev: Installing GMP,  Up: Top
   
 Miscellaneous Functions  GMP Basics
 =======================  **********
   
  - Function: void mpz_random (mpz_t ROP, mp_size_t MAX_SIZE)     *Using functions, macros, data types, etc. not documented in this
      Generate a random integer of at most MAX_SIZE limbs.  The generated  manual is strongly discouraged.  If you do so your application is
      random number doesn't satisfy any particular requirements of  guaranteed to be incompatible with future versions of GMP.*
      randomness.  Negative random numbers are generated when MAX_SIZE  
      is negative.  
   
  - Function: void mpz_random2 (mpz_t ROP, mp_size_t MAX_SIZE)  * Menu:
      Generate a random integer of at most MAX_SIZE limbs, with long  
      strings of zeros and ones in the binary representation.  Useful  
      for testing functions and algorithms, since this kind of random  
      numbers have proven to be more likely to trigger corner-case bugs.  
      Negative random numbers are generated when MAX_SIZE is negative.  
   
  - Function: size_t mpz_size (mpz_t OP)  * Headers and Libraries::
      Return the size of OP measured in number of limbs.  If OP is zero,  * Nomenclature and Types::
      the returned value will be zero.  * Function Classes::
   * Variable Conventions::
   * Parameter Conventions::
   * Memory Management::
   * Reentrancy::
   * Useful Macros and Constants::
   * Compatibility with older versions::
   * Demonstration Programs::
   * Efficiency::
   * Debugging::
   * Profiling::
   * Autoconf::
   * Emacs::
   
      *This function is obsolete.  It will disappear from future MP  
      releases.*  
   
  - Function: size_t mpz_sizeinbase (mpz_t OP, int BASE)  
      Return the size of OP measured in number of digits in base BASE.  
      The base may vary from 2 to 36.  The returned value will be exact  
      or 1 too big.  If BASE is a power of 2, the returned value will  
      always be exact.  
   
      This function is useful in order to allocate the right amount of  
      space before converting OP to a string.  The right amount of  
      allocation is normally two more than the value returned by  
      `mpz_sizeinbase' (one extra for a minus sign and one for the  
      terminating '\0').  
   
   
 File: gmp.info,  Node: Rational Number Functions,  Next: Floating-point Functions,  Prev: Integer Functions,  Up: Top  File: gmp.info,  Node: Headers and Libraries,  Next: Nomenclature and Types,  Prev: GMP Basics,  Up: GMP Basics
   
 Rational Number Functions  Headers and Libraries
 *************************  =====================
   
    This chapter describes the MP functions for performing arithmetic on     All declarations needed to use GMP are collected in the include file
 rational numbers.  These functions start with the prefix `mpq_'.  `gmp.h'.  It is designed to work with both C and C++ compilers.
   
    Rational numbers are stored in objects of type `mpq_t'.       #include <gmp.h>
   
    All rational arithmetic functions assume operands have a canonical     Note however that prototypes for GMP functions with `FILE *'
 form, and canonicalize their result.  The canonical from means that the  parameters are only provided if `<stdio.h>' is included too.
 denominator and the numerator have no common factors, and that the  
 denominator is positive.  Zero has the unique representation 0/1.  
   
    Pure assignment functions do not canonicalize the assigned variable.       #include <stdio.h>
 It is the responsibility of the user to canonicalize the assigned       #include <gmp.h>
 variable before any arithmetic operations are performed on that  
 variable.  *Note that this is an incompatible change from version 1 of  
 the library.*  
   
  - Function: void mpq_canonicalize (mpq_t OP)     Likewise `<stdarg.h>' (or `<varargs.h>') is required for prototypes
      Remove any factors that are common to the numerator and  with `va_list' parameters, such as `gmp_vprintf'.  And `<obstack.h>'
      denominator of OP, and make the denominator positive.  for prototypes with `struct obstack' parameters, such as
   `gmp_obstack_printf', when available.
   
 * Menu:     All programs using GMP must link against the `libgmp' library.  On a
   typical Unix-like system this can be done with `-lgmp', for example
   
 * Initializing Rationals::       gcc myprogram.c -lgmp
 * Assigning Rationals::  
 * Simultaneous Integer Init & Assign::  
 * Comparing Rationals::  
 * Applying Integer Functions::  
 * Miscellaneous Rational Functions::  
   
      GMP C++ functions are in a separate `libgmpxx' library.  This is
 File: gmp.info,  Node: Initializing Rationals,  Next: Assigning Rationals,  Prev: Rational Number Functions,  Up: Rational Number Functions  built and installed if C++ support has been enabled (*note Build
   Options::).  For example,
   
 Initialization and Assignment Functions       g++ mycxxprog.cc -lgmpxx -lgmp
 =======================================  
   
  - Function: void mpq_init (mpq_t DEST_RATIONAL)     GMP is built using Libtool and an application can use that to link
      Initialize DEST_RATIONAL and set it to 0/1.  Each variable should  if desired, *note Shared library support for GNU: (libtool)Top.
      normally only be initialized once, or at least cleared out (using  
      the function `mpq_clear') between each initialization.  
   
  - Function: void mpq_clear (mpq_t RATIONAL_NUMBER)     If GMP has been installed to a non-standard location then it may be
      Free the space occupied by RATIONAL_NUMBER.  Make sure to call this  necessary to use `-I' and `-L' compiler options to point to the right
      function for all `mpq_t' variables when you are done with them.  directories, and some sort of run-time path for a shared library.
   Consult your compiler documentation, for instance *Note Introduction:
   (gcc)Top.
   
  - Function: void mpq_set (mpq_t ROP, mpq_t OP)  
  - Function: void mpq_set_z (mpq_t ROP, mpz_t OP)  
      Assign ROP from OP.  
   
  - Function: void mpq_set_ui (mpq_t ROP, unsigned long int OP1,  
           unsigned long int OP2)  
  - Function: void mpq_set_si (mpq_t ROP, signed long int OP1, unsigned  
           long int OP2)  
      Set the value of ROP to OP1/OP2.  Note that if OP1 and OP2 have  
      common factors, ROP has to be passed to `mpq_canonicalize' before  
      any operations are performed on ROP.  
   
   
 File: gmp.info,  Node: Assigning Rationals,  Next: Comparing Rationals,  Prev: Initializing Rationals,  Up: Rational Number Functions  File: gmp.info,  Node: Nomenclature and Types,  Next: Function Classes,  Prev: Headers and Libraries,  Up: GMP Basics
   
 Arithmetic Functions  Nomenclature and Types
 ====================  ======================
   
  - Function: void mpq_add (mpq_t SUM, mpq_t ADDEND1, mpq_t ADDEND2)  In this manual, "integer" usually means a multiple precision integer, as
      Set SUM to ADDEND1 + ADDEND2.  defined by the GMP library.  The C data type for such integers is
   `mpz_t'.  Here are some examples of how to declare such integers:
   
  - Function: void mpq_sub (mpq_t DIFFERENCE, mpq_t MINUEND, mpq_t       mpz_t sum;
           SUBTRAHEND)  
      Set DIFFERENCE to MINUEND - SUBTRAHEND.       struct foo { mpz_t x, y; };
   
        mpz_t vec[20];
   
  - Function: void mpq_mul (mpq_t PRODUCT, mpq_t MULTIPLIER, mpq_t  "Rational number" means a multiple precision fraction.  The C data type
           MULTIPLICAND)  for these fractions is `mpq_t'.  For example:
      Set PRODUCT to MULTIPLIER times MULTIPLICAND.  
   
  - Function: void mpq_div (mpq_t QUOTIENT, mpq_t DIVIDEND, mpq_t       mpq_t quotient;
           DIVISOR)  
      Set QUOTIENT to DIVIDEND/DIVISOR.  
   
  - Function: void mpq_neg (mpq_t NEGATED_OPERAND, mpq_t OPERAND)  "Floating point number" or "Float" for short, is an arbitrary precision
      Set NEGATED_OPERAND to -OPERAND.  mantissa with a limited precision exponent.  The C data type for such
   objects is `mpf_t'.
   
  - Function: void mpq_inv (mpq_t INVERTED_NUMBER, mpq_t NUMBER)  A "limb" means the part of a multi-precision number that fits in a
      Set INVERTED_NUMBER to 1/NUMBER.  If the new denominator is zero,  single machine word.  (We chose this word because a limb of the human
      this routine will divide by zero.  body is analogous to a digit, only larger, and containing several
   digits.)  Normally a limb is 32 or 64 bits.  The C data type for a limb
   is `mp_limb_t'.
   
   
 File: gmp.info,  Node: Comparing Rationals,  Next: Applying Integer Functions,  Prev: Assigning Rationals,  Up: Rational Number Functions  File: gmp.info,  Node: Function Classes,  Next: Variable Conventions,  Prev: Nomenclature and Types,  Up: GMP Basics
   
 Comparison Functions  Function Classes
 ====================  ================
   
  - Function: int mpq_cmp (mpq_t OP1, mpq_t OP2)     There are six classes of functions in the GMP library:
      Compare OP1 and OP2.  Return a positive value if OP1 > OP2, zero  
      if OP1 = OP2, and a negative value if OP1 < OP2.  
   
      To determine if two rationals are equal, `mpq_equal' is faster than    1. Functions for signed integer arithmetic, with names beginning with
      `mpq_cmp'.       `mpz_'.  The associated type is `mpz_t'.  There are about 150
        functions in this class.
   
  - Macro: int mpq_cmp_ui (mpq_t OP1, unsigned long int NUM2, unsigned    2. Functions for rational number arithmetic, with names beginning with
           long int DEN2)       `mpq_'.  The associated type is `mpq_t'.  There are about 40
      Compare OP1 and NUM2/DEN2.  Return a positive value if OP1 >       functions in this class, but the integer functions can be used for
      NUM2/DEN2, zero if OP1 = NUM2/DEN2, and a negative value if OP1 <       arithmetic on the numerator and denominator separately.
      NUM2/DEN2.  
   
      This routine allows that NUM2 and DEN2 have common factors.    3. Functions for floating-point arithmetic, with names beginning with
        `mpf_'.  The associated type is `mpf_t'.  There are about 60
        functions is this class.
   
      This function is actually implemented as a macro.  It evaluates its    4. Functions compatible with Berkeley MP, such as `itom', `madd', and
      arguments multiple times.       `mult'.  The associated type is `MINT'.
   
  - Macro: int mpq_sgn (mpq_t OP)    5. Fast low-level functions that operate on natural numbers.  These
      Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0.       are used by the functions in the preceding groups, and you can
        also call them directly from very time-critical user programs.
        These functions' names begin with `mpn_'.  The associated type is
        array of `mp_limb_t'.  There are about 30 (hard-to-use) functions
        in this class.
   
      This function is actually implemented as a macro.  It evaluates its    6. Miscellaneous functions.  Functions for setting up custom
      arguments multiple times.       allocation and functions for generating random numbers.
   
  - Function: int mpq_equal (mpq_t OP1, mpq_t OP2)  
      Return non-zero if OP1 and OP2 are equal, zero if they are  
      non-equal.  Although `mpq_cmp' can be used for the same purpose,  
      this function is much faster.  
   
   
 File: gmp.info,  Node: Applying Integer Functions,  Next: Miscellaneous Rational Functions,  Prev: Comparing Rationals,  Up: Rational Number Functions  File: gmp.info,  Node: Variable Conventions,  Next: Parameter Conventions,  Prev: Function Classes,  Up: GMP Basics
   
 Applying Integer Functions to Rationals  Variable Conventions
 =======================================  ====================
   
    The set of `mpq' functions is quite small.  In particular, there are     GMP functions generally have output arguments before input
 no functions for either input or output.  But there are two macros that  arguments.  This notation is by analogy with the assignment operator.
 allow us to apply any `mpz' function on the numerator or denominator of  The BSD MP compatibility functions are exceptions, having the output
 a rational number.  If these macros are used to assign to the rational  arguments last.
 number, `mpq_canonicalize' normally need to be called afterwards.  
   
  - Macro: mpz_t mpq_numref (mpq_t OP)     GMP lets you use the same variable for both input and output in one
  - Macro: mpz_t mpq_denref (mpq_t OP)  call.  For example, the main function for integer multiplication,
      Return a reference to the numerator and denominator of OP,  `mpz_mul', can be used to square `x' and put the result back in `x' with
      respectively.  The `mpz' functions can be used on the result of  
      these macros.  
   
        mpz_mul (x, x, x);
 File: gmp.info,  Node: Miscellaneous Rational Functions,  Prev: Applying Integer Functions,  Up: Rational Number Functions  
   
 Miscellaneous Functions     Before you can assign to a GMP variable, you need to initialize it
 =======================  by calling one of the special initialization functions.  When you're
   done with a variable, you need to clear it out, using one of the
   functions for that purpose.  Which function to use depends on the type
   of variable.  See the chapters on integer functions, rational number
   functions, and floating-point functions for details.
   
  - Function: double mpq_get_d (mpq_t OP)     A variable should only be initialized once, or at least cleared
      Convert OP to a double.  between each initialization.  After a variable has been initialized, it
   may be assigned to any number of times.
   
    These functions assign between either the numerator or denominator     For efficiency reasons, avoid excessive initializing and clearing.
 of a rational, and an integer.  Instead of using these functions, it is  In general, initialize near the start of a function and clear near the
 preferable to use the more general mechanisms `mpq_numref' and  end.  For example,
 `mpq_denref', together with `mpz_set'.  
   
  - Function: void mpq_set_num (mpq_t RATIONAL, mpz_t NUMERATOR)       void
      Copy NUMERATOR to the numerator of RATIONAL.  When this risks to       foo (void)
      make the numerator and denominator of RATIONAL have common       {
      factors, you have to pass RATIONAL to `mpq_canonicalize' before         mpz_t  n;
      any operations are performed on RATIONAL.         int    i;
          mpz_init (n);
      This function is equivalent to `mpz_set (mpq_numref (RATIONAL),         for (i = 1; i < 100; i++)
      NUMERATOR)'.           {
              mpz_mul (n, ...);
  - Function: void mpq_set_den (mpq_t RATIONAL, mpz_t DENOMINATOR)             mpz_fdiv_q (n, ...);
      Copy DENOMINATOR to the denominator of RATIONAL.  When this risks             ...
      to make the numerator and denominator of RATIONAL have common           }
      factors, or if the denominator might be negative, you have to pass         mpz_clear (n);
      RATIONAL to `mpq_canonicalize' before any operations are performed       }
      on RATIONAL.  
   
      *In version 1 of the library, negative denominators were handled by  
      copying the sign to the numerator.  That is no longer done.*  
   
      This function is equivalent to `mpz_set (mpq_denref (RATIONAL),  
      DENOMINATORS)'.  
   
  - Function: void mpq_get_num (mpz_t NUMERATOR, mpq_t RATIONAL)  
      Copy the numerator of RATIONAL to the integer NUMERATOR, to  
      prepare for integer operations on the numerator.  
   
      This function is equivalent to `mpz_set (NUMERATOR, mpq_numref  
      (RATIONAL))'.  
   
  - Function: void mpq_get_den (mpz_t DENOMINATOR, mpq_t RATIONAL)  
      Copy the denominator of RATIONAL to the integer DENOMINATOR, to  
      prepare for integer operations on the denominator.  
   
      This function is equivalent to `mpz_set (DENOMINATOR, mpq_denref  
      (RATIONAL))'.  
   
Legend:
Removed from v.1.1.1.1  
changed lines
  Added in v.1.1.1.4
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>