GNU Info

(libc.info)BSD Random

---

Next: SVID Random Prev: ISO Random Up: Pseudo-Random Numbers

---

Enter node , (file) or (file)node

BSD Random Number Functions
---------------------------

   This section describes a set of random number generation functions
that are derived from BSD.  There is no advantage to using these
functions with the GNU C library; we support them for BSD compatibility
only.

   The prototypes for these functions are in `stdlib.h'.

 - Function: long int random (void)
     This function returns the next pseudo-random number in the
     sequence.  The value returned ranges from `0' to `RAND_MAX'.

     *Note:* Temporarily this function was defined to return a
     `int32_t' value to indicate that the return value always contains
     32 bits even if `long int' is wider.  The standard demands it
     differently.  Users must always be aware of the 32-bit limitation,
     though.

 - Function: void srandom (unsigned int SEED)
     The `srandom' function sets the state of the random number
     generator based on the integer SEED.  If you supply a SEED value
     of `1', this will cause `random' to reproduce the default set of
     random numbers.

     To produce a different set of pseudo-random numbers each time your
     program runs, do `srandom (time (0))'.

 - Function: void * initstate (unsigned int SEED, void *STATE, size_t
          SIZE)
     The `initstate' function is used to initialize the random number
     generator state.  The argument STATE is an array of SIZE bytes,
     used to hold the state information.  It is initialized based on
     SEED.  The size must be between 8 and 256 bytes, and should be a
     power of two.  The bigger the STATE array, the better.

     The return value is the previous value of the state information
     array.  You can use this value later as an argument to `setstate'
     to restore that state.

 - Function: void * setstate (void *STATE)
     The `setstate' function restores the random number state
     information STATE.  The argument must have been the result of a
     previous call to INITSTATE or SETSTATE.

     The return value is the previous value of the state information
     array.  You can use this value later as an argument to `setstate'
     to restore that state.

     If the function fails the return value is `NULL'.

   The four functions described so far in this section all work on a
state which is shared by all threads.  The state is not directly
accessible to the user and can only be modified by these functions.
This makes it hard to deal with situations where each thread should
have its own pseudo-random number generator.

   The GNU C library contains four additional functions which contain
the state as an explicit parameter and therefore make it possible to
handle thread-local PRNGs.  Beside this there are no difference.  In
fact, the four functions already discussed are implemented internally
using the following interfaces.

   The `stdlib.h' header contains a definition of the following type:

 - Data Type: struct random_data
     Objects of type `struct random_data' contain the information
     necessary to represent the state of the PRNG.  Although a complete
     definition of the type is present the type should be treated as
     opaque.

   The functions modifying the state follow exactly the already
described functions.

 - Function: int random_r (struct random_data *restrict BUF, int32_t
          *restrict RESULT)
     The `random_r' function behaves exactly like the `random' function
     except that it uses and modifies the state in the object pointed
     to by the first parameter instead of the global state.

 - Function: int srandom_r (unsigned int SEED, struct random_data *BUF)
     The `srandom_r' function behaves exactly like the `srandom'
     function except that it uses and modifies the state in the object
     pointed to by the second parameter instead of the global state.

 - Function: int initstate_r (unsigned int SEED, char *restrict
          STATEBUF, size_t STATELEN, struct random_data *restrict BUF)
     The `initstate_r' function behaves exactly like the `initstate'
     function except that it uses and modifies the state in the object
     pointed to by the fourth parameter instead of the global state.

 - Function: int setstate_r (char *restrict STATEBUF, struct
          random_data *restrict BUF)
     The `setstate_r' function behaves exactly like the `setstate'
     function except that it uses and modifies the state in the object
     pointed to by the first parameter instead of the global state.