NAME
	  random, random_r, srandom, srandom_r,	initstate,
	  initstate_r, setstate, setstate_r - Generates	better
	  pseudo-random	numbers

     LIBRARY
	  Standard C Library (libc.a)

     SYNOPSIS
	  #include <stdlib.h>

	  long random (	void );
	  int random_r (
	       long *retval,
	       struct random_data *rand_data );
	  int srandom (
	       unsigned	seed );
	  int srandom_r	(
	       unsigned	seed ,
	       struct random_data *rand_data );
	  char *initstate (
	       unsigned	seed,
	       char *state,
	       int size	);
	  int initstate_r (
	       unsigned	seed,
	       char *state,
	       int size,
	       char **retval,
	       struct random_data *rand_data );
	  char *setstate (
	       char *state );
	  int setstate_r (
	       char *state ,
	       char **retval
	       struct random_data *rand_data );


     PARAMETERS
	  seed	    Specifies an initial seed value.

	  state	    Points to the array	of state information.

	  size	    Specifies the size of the state information	array.

	  retval    Points to a	place to store the random number.

	  rand_data Points to a	random_data strucutre.


     DESCRIPTION
	  The random() and srandom() functions are random number
	  generators that have virtually the same calling sequence and
	  initialization properties as the rand() and srand() func-
	  tions, but produce sequences that are	more random.  The low
	  dozen	bits generated by the rand() function go through a
	  cyclic pattern, and all the bits generated by	the random()
	  function are usable.	For example, random( )&01"" produces a
	  random binary	value.

	  The random() function	uses a nonlinear additive feedback
	  random number	generator employing a default state array size
	  of 31	long integers to return	successive pseudo-random
	  numbers in the range from 0 to 231-1.	The period of this
	  random number	generator is approximately 16 x	(231-1).  The
	  size of the state array determines the period	of the random
	  number generator. Increasing the state array size increases
	  the period.

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

	  Like the rand() function, the	random() function  produces by
	  default a sequence of	numbers	that can be duplicated by cal-
	  ling the srandom() function with 1 as	the seed.

	  The initstate() and setstate() functions handle restarting
	  and changing random-number generators.  The initstate()
	  function allows a state array, passed	in as an argument, to
	  be  initialized for future use. The size in bytes of the
	  state	array is used by the initstate() function to decide
	  how sophisticated a random-number generator to use; the
	  larger the state array, the more random the numbers.	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() function returns a pointer to
	  the previous state information array.

	  Once a state has been	initialized, the setstate() function
	  allows rapid switching between states. The array defined by
	  the state parameter is used for further random-number	gen-
	  eration until	the initstate()	function is called or the set-
	  state() function is called again. The	setstate() function
	  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:

	   1.  The initstate() function	can be used, with the desired
	       seed, state array, and size of the array.

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


	  The random_r(), srandom_r(), initstate_r(), and setstate_r()
	  functions are	the reentrant versions of the random(),	sran-
	  dom(), initstate(), and setstate() functions,	respectively.
	  Upon success,	the initstate_r() and setstate_r() functions
	  have retval point at the returned state, which is stored in
	  the rand_data	structure.  The	random_r() function has	retval
	  point	at the returned	random number.	 Note that the
	  srandom_r() function takes the rand_data structure, which
	  should first be initialized by the initstate_r() function.
	  Note also that the state parameter needs to be NULL before
	  the initstate_r() or setstate_r() functions are called.

     RETURN VALUES
	  Upon success,	the random() function returns a	random number.

	  Upon success,	the initstate()	and setstate() functions
	  return a pointer to the previous state information array.
	  Upon error, the return 0 (zero).

	  The srandom()	function does not return anything.  It simply
	  initializes the state	seed.

	  Upon success,	the random_r(),	initstate_r(), and
	  setstate_r() functions return	0 (zero).  Upon	error they,
	  and the srandom_r() function,	return -1.

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

	  If the random_r(), srandom_r(), setstate_r(),	or
	  initstate_r()	function fails,	errno may be set to the	fol-
	  lowing:


	  [EINVAL]  The	retval,	rand_data, state, or retval parameters
		    are	NULL (0), or the state field of	the rand_data
		    structure is NULL (0).


     RELATED INFORMATION
	  Functions: drand48(3), rand(3)