mirror of https://github.com/mkerrisk/man-pages
138 lines
5.0 KiB
Plaintext
138 lines
5.0 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "INITSTATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" initstate
|
|
.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 .
|