random, srandom, initstate, setstate

Purpose

     Generates pseudo-random numbers and changes number gener-
     ators.

Library

     Berkeley Library (libbsd.a)

Syntax

     long random ( )                           char *initstate (seed, state, bytes)
                                               unsigned int seed;
     void srandom (seed);                      char *state;
     int seed;                                 int bytes;

     char *setstate (state)
     char *state;
     Description

     The random  subroutine generates  random numbers  using a
     non-linear  additive  feedback  random-number  generator.
     This generator uses a default table size of 31 long inte-
     gers 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  16S
     (2(31)-1).

     The srandom subroutine resets the random-number generator
     to a random  starting point when used  after the setstate
     subroutine.  Like the rand  subroutine, the random gener-
     ator is initially seeded with a value of 1.

     The srandom subroutine, unlike the srand subroutine, does
     not  return the  old  seed because  the  amount of  state
     information used is  more than a single  word.  Two other
     subroutines,  initstate and  setstate, handle  restarting
     and changing random-number generators.

     The initstate subroutine allows  a state array, passed in
     by the state parameter, to be initialized for future use.
     The size  of the state  array (in bytes) is  contained in
     the bytes parameter, which is  used by the initstate sub-
     routine to decide how complex the random-number generator
     should  be.  When  more  bytes of  state information  are
     used, the numbers are more random.  Values for the amount
     of state information are:  8, 32, 64, 128, and 256 bytes.
     Amounts less than 8 bytes  generate an error, while other
     amounts are rounded down to the nearest known value.  The
     seed parameter specifies a starting point for the random-
     number sequence  and provides for restarting  at the same
     point.  The initstate subroutine returns a pointer to the
     previous state information array.

     Once a  state has been initialized,  the setstate subrou-
     tine allows  rapid switching  between states.   The array
     defined by  state parameter  is used for  further random-
     number  generation  until  the  initstate  subroutine  is
     called or  the setstate subroutine is  called again.  The
     setstate  subroutine returns  a pointer  to the  previous
     state array.

     After initialization, a state array can be restarted at a
     different point in one of two ways:

     o   The  initstate  subroutine  can  be  used,  with  the
         desired seed, state array, and size of the array, or

     o   The setstate subroutine, with  the desired state, can
         be used, followed by  the srandom subroutine with the
         desired seed.   The advantage of using  both of these
         subroutines is that the size  of the state array does
         not have to be saved once it is initialized.

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

     Diagnostics

     If the  initstate subroutine is  called with less  than 8
     bytes of state information, or if the setstate subroutine
     detects  that the  state  information  has been  damaged,
     error messages are sent to the standard output.

     Related Information

     In this book:  "drand48" and "rand, srand."