## 9 Random Number Functions ¶

Sequences of pseudo-random numbers in GMP are generated using a variable of type `gmp_randstate_t`, which holds an algorithm selection and a current state. Such a variable must be initialized by a call to one of the `gmp_randinit` functions, and can be seeded with one of the `gmp_randseed` functions.

The functions actually generating random numbers are described in Random Number Functions, and Miscellaneous Functions.

The older style random number functions don’t accept a `gmp_randstate_t` parameter but instead share a global variable of that type. They use a default algorithm and are currently not seeded (though perhaps that will change in the future). The new functions accepting a `gmp_randstate_t` are recommended for applications that care about randomness.

### 9.1 Random State Initialization ¶

Function: `void` gmp_randinit_default `(gmp_randstate_t state)` ¶

  Initialize state with a default algorithm. This will be a compromise between speed and randomness, and is recommended for applications with no special requirements. Currently this is `gmp_randinit_mt`.

Function: `void` gmp_randinit_mt `(gmp_randstate_t state)` ¶

  Initialize state for a Mersenne Twister algorithm. This algorithm is fast and has good randomness properties.

Function: `void` gmp_randinit_lc_2exp `(gmp_randstate_t state, const mpz_t a, unsigned long c, mp_bitcnt_t m2exp)` ¶

  Initialize state with a linear congruential algorithm X = (a*X + c) mod 2^m2exp.

  The low bits of X in this algorithm are not very random. The least significant bit will have a period no more than 2, and the second bit no more than 4, etc. For this reason only the high half of each X is actually used.

  When a random number of more than m2exp/2 bits is to be generated, multiple iterations of the recurrence are used and the results concatenated.

Function: `int` gmp_randinit_lc_2exp_size `(gmp_randstate_t state, mp_bitcnt_t size)` ¶

  Initialize state for a linear congruential algorithm as per `gmp_randinit_lc_2exp`. a, c and m2exp are selected from a table, chosen so that size bits (or more) of each X will be used, i.e. m2exp/2 >= size.

  If successful the return value is non-zero. If size is bigger than the table data provides then the return value is zero. The maximum size currently supported is 128.

Function: `void` gmp_randinit_set `(gmp_randstate_t rop, gmp_randstate_t op)` ¶

  Initialize rop with a copy of the algorithm and state from op.

Function: `void` gmp_randinit `(gmp_randstate_t state, gmp_randalg_t alg, …)` ¶

  This function is obsolete.

  Initialize state with an algorithm selected by alg. The only choice is `GMP_RAND_ALG_LC`, which is `gmp_randinit_lc_2exp_size` described above. A third parameter of type `unsigned long` is required, this is the size for that function. `GMP_RAND_ALG_DEFAULT` and 0 are the same as `GMP_RAND_ALG_LC`.

  `gmp_randinit` sets bits in the global variable `gmp_errno` to indicate an error. `GMP_ERROR_UNSUPPORTED_ARGUMENT` if alg is unsupported, or `GMP_ERROR_INVALID_ARGUMENT` if the size parameter is too big. It may be noted this error reporting is not thread safe (a good reason to use `gmp_randinit_lc_2exp_size` instead).

Function: `void` gmp_randclear `(gmp_randstate_t state)` ¶

  Free all memory occupied by state.

### 9.2 Random State Seeding ¶

Function: `void` gmp_randseed `(gmp_randstate_t state, const mpz_t seed)` ¶
Function: `void` gmp_randseed_ui `(gmp_randstate_t state, unsigned long int seed)` ¶

  Set an initial seed value into state.

  The size of a seed determines how many different sequences of random numbers it’s possible to generate. The “quality” of the seed is the randomness of a given seed compared to the previous seed used, and this affects the randomness of separate number sequences. The method for choosing a seed is critical if the generated numbers are to be used for important applications, such as generating cryptographic keys.

  Traditionally the system time has been used to seed, but care needs to be taken with this. If an application seeds often and the resolution of the system clock is low, then the same sequence of numbers might be repeated. Also, the system time is quite easy to guess, so if unpredictability is required then it should definitely not be the only source for the seed value. On some systems there’s a special device `/dev/random` which provides random data better suited for use as a seed.

### 9.3 Random State Miscellaneous ¶

Function: `unsigned long` gmp_urandomb_ui `(gmp_randstate_t state, unsigned long n)` ¶

  Return a uniformly distributed random number of n bits, i.e. in the range 0 to 2^n-1 inclusive. n must be less than or equal to the number of bits in an `unsigned long`.

Function: `unsigned long` gmp_urandomm_ui `(gmp_randstate_t state, unsigned long n)` ¶

  Return a uniformly distributed random number in the range 0 to n-1, inclusive.