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


SVID Random Number Function

The C library on SVID systems contains yet another kind of random number generator functions. They use a state of 48 bits of data. The user can choose among a collection of functions which return the random bits in different forms.

Generally there are two kinds of functions: those which use a state of the random number generator which is shared among several functions and by all threads of the process. The second group of functions require the user to handle the state.

All functions have in common that they use the same congruential formula with the same constants. The formula is

Y = (a * X + c) mod m

where X is the state of the generator at the beginning and Y the state at the end. a and c are constants determining the way the generator work. By default they are

a = 0x5DEECE66D = 25214903917
c = 0xb = 11

but they can also be changed by the user. m is of course 2^48 since the state consists of a 48 bit array.

Function: double drand48 (void)
This function returns a double value in the range of 0.0 to 1.0 (exclusive). The random bits are determined by the global state of the random number generator in the C library.

Since the double type according to IEEE 754 has a 52 bit mantissa this means 4 bits are not initialized by the random number generator. These are (of course) chosen to be the least significant bits and they are initialized to 0.

Function: double erand48 (unsigned short int xsubi[3])
This function returns a double value in the range of 0.0 to 1.0 (exclusive), similar to drand48. The argument is an array describing the state of the random number generator.

This function can be called subsequently since it updates the array to guarantee random numbers. The array should have been initialized before using to get reproducible results.

Function: long int lrand48 (void)
The lrand48 functions return an integer value in the range of 0 to 2^31 (exclusive). Even if the size of the long int type can take more than 32 bits no higher numbers are returned. The random bits are determined by the global state of the random number generator in the C library.

Function: long int nrand48 (unsigned short int xsubi[3])
This function is similar to the lrand48 function in that it returns a number in the range of 0 to 2^31 (exclusive) but the state of the random number generator used to produce the random bits is determined by the array provided as the parameter to the function.

The numbers in the array are afterwards updated so that subsequent calls to this function yield to different results (as it is expected by a random number generator). The array should have been initialized before the first call to get reproducible results.

Function: long int mrand48 (void)
The mrand48 function is similar to lrand48. The only difference is that the numbers returned are in the range -2^31 to 2^31 (exclusive).

Function: long int jrand48 (unsigned short int xsubi[3])
The jrand48 function is similar to nrand48. The only difference is that the numbers returned are in the range -2^31 to 2^31 (exclusive). For the xsubi parameter the same requirements are necessary.

The internal state of the random number generator can be initialized in several ways. The functions differ in the completeness of the information provided.

Function: void srand48 (long int seedval))
The srand48 function sets the most significant 32 bits of the state internal state of the random number generator to the least significant 32 bits of the seedval parameter. The lower 16 bits are initialized to the value 0x330E. Even if the long int type contains more the 32 bits only the lower 32 bits are used.

Due to this limitation the initialization of the state using this function of not very useful. But it makes it easy to use a construct like srand48 (time (0)).

A side-effect of this function is that the values a and c from the internal state, which are used in the congruential formula, are reset to the default values given above. This is of importance once the user called the lcong48 function (see below).

Function: unsigned short int * seed48 (unsigned short int seed16v[3])
The seed48 function initializes all 48 bits of the state of the internal random number generator from the content of the parameter seed16v. Here the lower 16 bits of the first element of see16v initialize the least significant 16 bits of the internal state, the lower 16 bits of seed16v[1] initialize the mid-order 16 bits of the state and the 16 lower bits of seed16v[2] initialize the most significant 16 bits of the state.

Unlike srand48 this function lets the user initialize all 48 bits of the state.

The value returned by seed48 is a pointer to an array containing the values of the internal state before the change. This might be useful to restart the random number generator at a certain state. Otherwise, the value can simply be ignored.

As for srand48, the values a and c from the congruential formula are reset to the default values.

There is one more function to initialize the random number generator which allows to specify even more information by allowing to change the parameters in the congruential formula.

Function: void lcong48 (unsigned short int param[7])
The lcong48 function allows the user to change the complete state of the random number generator. Unlike srand48 and seed48, this function also changes the constants in the congruential formula.

From the seven elements in the array param the least significant 16 bits of the entries param[0] to param[2] determine the initial state, the least 16 bits of param[3] to param[5] determine the 48 bit constant a and param[6] determines the 16 bit value c.

All the above functions have in common that they use the global parameters for the congruential formula. In multi-threaded programs it might sometimes be useful to have different parameters in different threads. For this reason all the above functions have a counterpart which works on a description of the random number generator in the user-supplied buffer instead of the global state.

Please note that it is no problem if several threads use the global state if all threads use the functions which take a pointer to an array containing the state. The random numbers are computed following the same loop but if the state in the array is different all threads will get an individual random number generator.

The user supplied buffer must be of type struct drand48_data. This type should be regarded as opaque and no member should be used directly.

Function: int drand48_r (struct drand48_data *buffer, double *result)
This function is equivalent to the drand48 function with the difference it does not modify the global random number generator parameters but instead the parameters is the buffer supplied by the buffer through the pointer buffer. The random number is return in the variable pointed to by result.

The return value of the function indicate whether the call succeeded. If the value is less than 0 an error occurred and errno is set to indicate the problem.

This function is a GNU extension and should not be used in portable programs.

Function: int erand48_r (unsigned short int xsubi[3], struct drand48_data *buffer, double *result)
The erand48_r function works like the erand48 and it takes an argument buffer which describes the random number generator. The state of the random number generator is taken from the xsubi array, the parameters for the congruential formula from the global random number generator data. The random number is return in the variable pointed to by result.

The return value is non-negative is the call succeeded.

This function is a GNU extension and should not be used in portable programs.

Function: int lrand48_r (struct drand48_data *buffer, double *result)
This function is similar to lrand48 and it takes a pointer to a buffer describing the state of the random number generator as a parameter just like drand48.

If the return value of the function is non-negative the variable pointed to by result contains the result. Otherwise an error occurred.

This function is a GNU extension and should not be used in portable programs.

Function: int nrand48_r (unsigned short int xsubi[3], struct drand48_data *buffer, long int *result)
The nrand48_r function works like nrand48 in that it produces a random number in range 0 to 2^31. But instead of using the global parameters for the congruential formula it uses the information from the buffer pointed to by buffer. The state is described by the values in xsubi.

If the return value is non-negative the variable pointed to by result contains the result.

This function is a GNU extension and should not be used in portable programs.

Function: int mrand48_r (struct drand48_data *buffer, double *result)
This function is similar to mrand48 but as the other reentrant function it uses the random number generator described by the value in the buffer pointed to by buffer.

If the return value is non-negative the variable pointed to by result contains the result.

This function is a GNU extension and should not be used in portable programs.

Function: int jrand48_r (unsigned short int xsubi[3], struct drand48_data *buffer, long int *result)
The jrand48_r function is similar to jrand48. But as the other reentrant functions of this function family it uses the congruential formula parameters from the buffer pointed to by buffer.

If the return value is non-negative the variable pointed to by result contains the result.

This function is a GNU extension and should not be used in portable programs.

Before any of the above functions should be used the buffer of type struct drand48_data should initialized. The easiest way is to fill the whole buffer with null bytes, e.g., using

memset (buffer, '\0', sizeof (struct drand48_data));

Using any of the reentrant functions of this family now will automatically initialize the random number generator to the default values for the state and the parameters of the congruential formula.

The other possibility is too use any of the functions which explicitly initialize the buffer. Though it might be obvious how to initialize the buffer from the data given as parameter from the function it is highly recommended to use these functions since the result might not always be what you expect.

Function: int srand48_r (long int seedval, struct drand48_data *buffer)
The description of the random number generator represented by the information in buffer is initialized similar to what the function srand48 does. The state is initialized from the parameter seedval and the parameters for the congruential formula are initialized to the default values.

If the return value is non-negative the function call succeeded.

This function is a GNU extension and should not be used in portable programs.

Function: int seed48_r (unsigned short int seed16v[3], struct drand48_data *buffer)
This function is similar to srand48_r but like seed48 it initializes all 48 bits of the state from the parameter seed16v.

If the return value is non-negative the function call succeeded. It does not return a pointer to the previous state of the random number generator like the seed48 function does. if the user wants to preserve the state for a later rerun s/he can copy the whole buffer pointed to by buffer.

This function is a GNU extension and should not be used in portable programs.

Function: int lcong48_r (unsigned short int param[7], struct drand48_data *buffer)
This function initializes all aspects of the random number generator described in buffer by the data in param. Here it is especially true the function does more than just copying the contents of param of buffer. Some more actions are required and therefore it is important to use this function and not initialized the random number generator directly.

If the return value is non-negative the function call succeeded.

This function is a GNU extension and should not be used in portable programs.


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