# random(3)

    NAME
         random, srandom, initstate, setstate - better  random  number  generator;
         routines for changing generators

    SYNOPSIS
         #include <stdlib.h>

         long random(void)
         void srandom(unsigned seed)
         char *initstate(unsigned seed, char *state, int n)
         char *setstate(char *state)

    DESCRIPTION

         Random uses  a  non-linear  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).

         Random/srandom have (almost) the same calling sequence and initialization
         properties  as rand/srand. The difference is that rand(3) produces a much
         less random sequence -- in fact, the low dozen bits generated by rand  go
         through  a  cyclic pattern.  All the bits generated by random are usable.
         For example, ``random()&01'' will produce a random binary value.

         Unlike srand, srandom does not return the old seed; the reason  for  this
         is  that  the amount of state information used is much more than a single
         word.  (Two other routines are provided to deal with  restarting/changing
         random number generators).  Like rand(3), however, random will by default
         produce a sequence of numbers that can be duplicated by  calling  srandom
         with 1 as the seed.

         The initstate routine allows a state array, passed in as an argument,  to
         be initialized for future use.  The size of the state array (in bytes) is
         used by initstate to decide how sophisticated a random  number  generator
         it  should  use -- the more state, the better the random numbers will be.
         (Current "optimal" values for the amount of state information are 8,  32,
         64, 128, and 256 bytes; other amounts will be rounded down to the nearest
         known amount.  Using less than 8 bytes will cause an  error).   The  seed
         for  the  initialization (which specifies a starting point for the random
         number sequence, and provides for restarting at the same point)  is  also
         an   argument.   Initstate  returns  a  pointer  to  the  previous  state
         information array.

         Once a state has been initialized,  the  setstate  routine  provides  for
         rapid  switching  between  states.   Setstate  returns  a  pointer to the
         previous state array; its argument state array is used for further random
         number generation until the next call to initstate or setstate.

         Once a state array has  been  initialized,  it  may  be  restarted  at  a
         different  point  either by calling initstate (with the desired seed, the
         state array, and its size) or by calling both setstate  (with  the  state
         array)  and  srandom  (with  the desired seed).  The advantage of calling
         both setstate and srandom is that the size of the state  array  does  not
         have to be remembered after it is initialized.

         With 256 bytes of state information, the  period  of  the  random  number
         generator  is  greater  than  2**69  which  should be sufficient for most
         purposes.

    AUTHOR
         Earl T. Cohen

    DIAGNOSTICS

         If initstate is called with less than 8 bytes of state information, or if
         setstate  detects  that  the  state  information  has been garbled, error
         messages are printed on the standard error output.

    SEE ALSO
         rand(3).

    NOTES
         initstate and setstate are not declared in <stdlib.h>,  programmers  must
         provide their own declarations.

    BUGS
         About 2/3 the speed of rand(3).