.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "INITSTATE" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" initstate 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
initstate, random, setstate, srandom \- pseudo-random number functions
.SH SYNOPSIS
.LP
\fB#include <stdlib.h>
.br
.sp
char *initstate(unsigned\fP \fIseed\fP\fB, char *\fP\fIstate\fP\fB,
size_t\fP \fIsize\fP\fB);
.br
long random(void);
.br
char *setstate(const char *\fP\fIstate\fP\fB);
.br
void srandom(unsigned\fP \fIseed\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIrandom\fP() function shall use a non-linear additive feedback
random-number generator employing a default state array
size of 31 \fBlong\fP integers to return successive pseudo-random
numbers in the range from 0 to 2**31-1.
The period of this random-number generator is approximately 16 x (2**31-1).
The size of the state array
determines the period of the random-number generator. Increasing the
state array size shall increase the period.
.LP
With 256 bytes of state information, the period of the random-number
generator shall be greater than
2**69.
.LP
Like \fIrand\fP(), \fIrandom\fP() shall produce by default a sequence
of numbers that can
be duplicated by calling \fIsrandom\fP() with 1 as the seed.
.LP
The \fIsrandom\fP() function shall initialize the current state array
using the value of \fIseed\fP.
.LP
The \fIinitstate\fP() and \fIsetstate\fP() functions handle restarting
and changing random-number generators. The
\fIinitstate\fP() function allows a state array, pointed to by the
\fIstate\fP argument, to be initialized for future use. The
\fIsize\fP argument, which specifies the size in bytes of the state
array, shall be used by \fIinitstate\fP() to decide what type
of 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. Other values greater
than 8 bytes are rounded down to the nearest one of these
values. If \fIinitstate\fP() is called with 8<=\fIsize\fP<32, then
\fIrandom\fP() shall use a simple linear congruential
random number generator. The \fIseed\fP argument specifies a starting
point for the random-number sequence and provides for
restarting at the same point. The \fIinitstate\fP() function shall
return a pointer to the previous state information array.
.LP
If \fIinitstate\fP() has not been called, then \fIrandom\fP() shall
behave as though \fIinitstate\fP() had been called with
\fIseed\fP=1 and \fIsize\fP=128.
.LP
Once a state has been initialized, \fIsetstate\fP() allows switching
between state arrays. The array defined by the
\fIstate\fP argument shall be used for further random-number generation
until \fIinitstate\fP() is called or \fIsetstate\fP() is
called again. The \fIsetstate\fP() function shall return a pointer
to the previous state array.
.SH RETURN VALUE
.LP
If \fIinitstate\fP() is called with \fIsize\fP less than 8, it shall
return NULL.
.LP
The \fIrandom\fP() function shall return the generated pseudo-random
number.
.LP
The \fIsrandom\fP() function shall not return a value.
.LP
Upon successful completion, \fIinitstate\fP() and \fIsetstate\fP()
shall return a pointer to the previous state array;
otherwise, a null pointer shall be returned.
.SH ERRORS
.LP
No errors are defined.
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
After initialization, a state array can be restarted at a different
point in one of two ways:
.IP " 1." 4
The \fIinitstate\fP() function can be used, with the desired seed,
state array, and size of the array.
.LP
.IP " 2." 4
The \fIsetstate\fP() function, with the desired state, can be used,
followed by \fIsrandom\fP() 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.
.LP
.LP
Although some implementations of \fIrandom\fP() have written messages
to standard error, such implementations do not conform to
IEEE\ Std\ 1003.1-2001.
.LP
Issue 5 restored the historical behavior of this function.
.LP
Threaded applications should use \fIerand48\fP(), \fInrand48\fP(),
or \fIjrand48\fP() instead of
\fIrandom\fP() when an independent random number sequence in multiple
threads is required.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIdrand48\fP(), \fIrand\fP(), the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, \fI<stdlib.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .