Constant gmp_mpfr_sys::C::GMP::Random_Number_Functions[−][src]

pub const Random_Number_Functions: ();

This constant is a place-holder for documentation; do not use it in code.

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 Integer Random Numbers, and Miscellaneous Float 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 or 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 that 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.

• Random State Initialization
• Random State Seeding
• Random State Miscellaneous