# random

## NAME



           random, srandom, initstate, setstate - random number generator
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <stdlib.h>**
    
           **long random(void);**
           **void srandom(unsigned int** _seed_**);**
    
           **char *initstate(** size_t n;
                           **unsigned int** _seed_**, char** _state_**[**_n_**], size_t** _n_**);**
           **char *setstate(char ***_state_**);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **random**(), **srandom**(), **initstate**(), **setstate**():
               _XOPEN_SOURCE >= 500
                   || /* glibc >= 2.19: */ _DEFAULT_SOURCE
                   || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
    


## DESCRIPTION



           The **random**() function uses a nonlinear additive feedback random
           number generator employing a default table of size 31 long
           integers to return successive pseudo-random numbers in the range
           from 0 to 2^31 - 1.  The period of this random number generator is
           very large, approximately _16 * ((2^31) - 1)_.
    
           The **srandom**() function sets its argument as the seed for a new
           sequence of pseudo-random integers to be returned by **random**().
           These sequences are repeatable by calling **srandom**() with the same
           seed value.  If no seed value is provided, the **random**() function
           is automatically seeded with a value of 1.
    
           The **initstate**() function allows a state array _state_ to be
           initialized for use by **random**().  The size of the state array _n_ is
           used by **initstate**() to decide how sophisticated a random number
           generator it should use—the larger the state array, the better the
           random numbers will be.  Current "optimal" values for the size of
           the state array _n_ are 8, 32, 64, 128, and 256 bytes; other amounts
           will be rounded down to the nearest known amount.  Using less than
           8 bytes results in an error.  _seed_ is the seed for the
           initialization, which specifies a starting point for the random
           number sequence, and provides for restarting at the same point.
    
           The **setstate**() function changes the state array used by the
           **random**() function.  The state array _state_ is used for random
           number generation until the next call to **initstate**() or
           **setstate**().  _state_ must first have been initialized using
           **initstate**() or be the result of a previous call of **setstate**().
    


## RETURN VALUE



           The **random**() function returns a value between 0 and _(2^31) - 1_.
           The **srandom**() function returns no value.
    
           The **initstate**() function returns a pointer to the previous state
           array.  On failure, it returns NULL, and _errno_ is set to indicate
           the error.
    
           On success, **setstate**() returns a pointer to the previous state
           array.  On failure, it returns NULL, and _errno_ is set to indicate
           the error.
    


## ERRORS



           **EINVAL** The _state_ argument given to **setstate**() was NULL.
    
           **EINVAL** A state array of less than 8 bytes was specified to
                  **initstate**().
    


## ATTRIBUTES



           For an explanation of the terms used in this section, see
           attributes(7).
           ┌──────────────────────────────────────┬───────────────┬─────────┐
           │ **Interface** │ **Attribute** │ **Value** │
           ├──────────────────────────────────────┼───────────────┼─────────┤
           │ **random**(), **srandom**(), **initstate**(),    │ Thread safety │ MT-Safe │
           │ **setstate**()                           │               │         │
           └──────────────────────────────────────┴───────────────┴─────────┘
    


## STANDARDS



           POSIX.1-2008.
    


## NOTES



           Random-number generation is a complex topic.  _Numerical Recipes in_
           _C: The Art of Scientific Computing_ (William H. Press, Brian P.
           Flannery, Saul A. Teukolsky, William T. Vetterling; New York:
           Cambridge University Press, 2007, 3rd ed.)  provides an excellent
           discussion of practical random-number generation issues in Chapter
           7 (Random Numbers).
    
           For a more theoretical discussion which also covers many practical
           issues in depth, see Chapter 3 (Random Numbers) in Donald E.
           Knuth's _The Art of Computer Programming_ , volume 2 (Seminumerical
           Algorithms), 2nd ed.; Reading, Massachusetts: Addison-Wesley
           Publishing Company, 1981.
    


## CAVEATS



           The **random**() function should not be used in multithreaded programs
           where reproducible behavior is required.  Use random_r(3) for that
           purpose.
    


## BUGS



           According to POSIX, **initstate**() should return NULL on error.  In
           the glibc implementation, _errno_ is (as specified) set on error,
           but the function does not return NULL.
    


* * *