Go to the first, previous, next, last section, table of contents.

GMP Basics

All declarations needed to use GMP are collected in the include file `gmp.h'. It is designed to work with both C and C++ compilers.

Using functions, macros, data types, etc. not documented in this manual is strongly discouraged. If you do so your application is guaranteed to be incompatible with future versions of GMP.

Nomenclature and Types

In this manual, integer usually means a multiple precision integer, as 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:

mpz_t sum;

struct foo { mpz_t x, y; };

mpz_t vec[20];

Rational number means a multiple precision fraction. The C data type for these fractions is mpq_t. For example:

mpq_t quotient;

Floating point number or Float for short, is an arbitrary precision mantissa with a limited precision exponent. The C data type for such objects is mpf_t.

A limb means the part of a multi-precision number that fits in a 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

There are six classes of functions in the GMP library:

  1. Functions for signed integer arithmetic, with names beginning with 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 mpq_. The associated type is mpq_t. There are about 20 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 mpf_. The associated type is mpf_t. There are about 50 functions is this class.
  4. Functions compatible with Berkeley GMP, such as itom, madd, and mult. The associated type is MINT.
  5. Fast low-level functions that operate on natural numbers. These 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_. There are about 30 (hard-to-use) functions in this class. The associated type is array of mp_limb_t.
  6. Miscellaneous functions. Functions for setting up custom allocation and functions for generating random numbers.

GMP Variable Conventions

As a general rule, all GMP functions expect output arguments before input arguments. This notation is based on an analogy with the assignment operator. (The BSD MP compatibility functions disobey this rule, having the output argument(s) last.)

GMP lets you use the same variable for both input and output in one call. For example, the main function for integer multiplication, mpz_mul, can be used to square x and put the result back in x with

mpz_mul (x, x, x);

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.

A variable should only be initialized once, or at least cleared out between each initialization. After a variable has been initialized, it may be assigned to any number of times.

For efficiency reasons, avoid initializing and clearing out a GMP variable in a loop. Instead, initialize it before entering the loop, and clear it out after the loop has exited.

GMP variables are small, containing only a couple of sizes, and pointers to allocated data. Once you have initialized a GMP variable, you don't need to worry about space allocation. All functions in GMP automatically allocate additional space when a variable does not already have enough. They do not, however, reduce the space when a smaller value is stored. Most of the time this policy is best, since it avoids frequent re-allocation.

When a variable of type mpz_t is used as a function parameter, it's effectively a call-by-reference, meaning anything the function does to it will be be done to the original in the caller. When a function is going to return an mpz_t result, it should provide a separate parameter or parameters that it sets, like the GMP library functions do. A return of an mpz_t doesn't return the object, only a pointer to it, and this is almost certainly not what you want. All this applies to mpq_t and mpf_t too.

Here's an example function accepting an mpz_t parameter, doing a certain calculation, and returning a result.

myfunction (mpz_t result, mpz_t param, unsigned long n)
  unsigned long  i;
  mpz_mul_ui (result, param, n);
  for (i = 1; i < n; i++)
    mpz_add_ui (result, result, i*7);

main (void)
  mpz_t  r, n;
  mpz_init (r);
  mpz_init_set_str (n, "123456", 0);

  myfunction (r, n, 20L);
  mpz_out_str (stdout, 10, r); printf ("\n");

  return 0;

This example will work if result and param are the same variable, just like the library functions. But sometimes this is tricky to arrange, and an application might not want to bother for its own subroutines.

mpz_t is actually implemented as a one-element array of a certain structure type. This is why using it to declare a variable gives an object with the fields GMP needs, but then using it as a parameter passes a pointer to the object. Note that the actual contents of an mpz_t are for internal use only and you should not access them directly if you want your code to be compatible with future GMP releases.

GMP and Reentrancy

The GMP code is reentrant and thread-safe, with some exceptions:

Useful Macros and Constants

Global Constant: const int mp_bits_per_limb
The number of bits per limb.

The major and minor GMP version, and patch level, respectively, as integers. For GMP i.j, these numbers will be i, j, and 0, respectively. For GMP i.j.k, these numbers will be i, j, and k, respectively.

Compatibility with older versions

This version of GMP is upwardly binary compatible with versions 3.0 and 3.0.1, and upwardly compatible at the source level with versions 2.0, 2.0.1, and 2.0.2, with the following exceptions.

There are a number of compatibility issues between GMP 1 and GMP 2 that of course also apply when porting applications from GMP 1 to GMP 3. Please see the GMP 2 manual for details.

Getting the Latest Version of GMP

The latest version of the GMP library is available at ftp://ftp.gnu.org/pub/gnu/gmp. Many sites around the world mirror `ftp.gnu.org'; please use a mirror site near you, see http://www.gnu.org/order/ftp.html.

Go to the first, previous, next, last section, table of contents.