initstate.3p (5576B)
- '\" et
- .TH INITSTATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .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
- \(em pseudo-random number functions
- .SH SYNOPSIS
- .LP
- .nf
- #include <stdlib.h>
- .P
- char *initstate(unsigned \fIseed\fP, char *\fIstate\fP, size_t \fIsize\fP);
- long random(void);
- char *setstate(char *\fIstate\fP);
- void srandom(unsigned \fIseed\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIrandom\fR()
- function shall use a non-linear additive feedback random-number
- generator employing a default state array size of 31
- .BR long
- integers to return successive pseudo-random numbers in the range from 0
- to 2\u\s-331\s+3\d\-1. The period of this random-number generator is
- approximately 16 x (2\s-3\u31\d\s+3\-\fR1). The size of the state
- array determines the period of the random-number generator. Increasing
- the state array size shall increase the period.
- .P
- With 256 bytes of state information, the period of the random-number
- generator shall be greater than 2\s-3\u69\d\s+3.
- .P
- Like
- \fIrand\fR(),
- \fIrandom\fR()
- shall produce by default a sequence of numbers that can be duplicated
- by calling
- \fIsrandom\fR()
- with 1 as the seed.
- .P
- The
- \fIsrandom\fR()
- function shall initialize the current state array using the value of
- .IR seed .
- .P
- The
- \fIinitstate\fR()
- and
- \fIsetstate\fR()
- functions handle restarting and changing random-number generators. The
- \fIinitstate\fR()
- function allows a state array, pointed to by the
- .IR state
- argument, to be initialized for future use. The
- .IR size
- argument, which specifies the size in bytes of the state array, shall
- be used by
- \fIinitstate\fR()
- 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\fR()
- is called with 8\(<=\fIsize\fR<32, then
- \fIrandom\fR()
- shall use a simple linear congruential random number generator. The
- .IR seed
- argument specifies a starting point for the random-number sequence and
- provides for restarting at the same point. The
- \fIinitstate\fR()
- function shall return a pointer to the previous state information array.
- .P
- If
- \fIinitstate\fR()
- has not been called, then
- \fIrandom\fR()
- shall behave as though
- \fIinitstate\fR()
- had been called with
- .IR seed =1
- and
- .IR size =128.
- .P
- Once a state has been initialized,
- \fIsetstate\fR()
- allows switching between state arrays. The array defined by the
- .IR state
- argument shall be used for further random-number generation until
- \fIinitstate\fR()
- is called or
- \fIsetstate\fR()
- is called again. The
- \fIsetstate\fR()
- function shall return a pointer to the previous state array.
- .SH "RETURN VALUE"
- If
- \fIinitstate\fR()
- is called with
- .IR size
- less than 8, it shall return NULL.
- .P
- The
- \fIrandom\fR()
- function shall return the generated pseudo-random number.
- .P
- The
- \fIsrandom\fR()
- function shall not return a value.
- .P
- Upon successful completion,
- \fIinitstate\fR()
- and
- \fIsetstate\fR()
- shall return a pointer to the previous state array; otherwise, a null
- pointer shall be returned.
- .SH ERRORS
- No errors are defined.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- After initialization, a state array can be restarted at a different
- point in one of two ways:
- .IP " 1." 4
- The
- \fIinitstate\fR()
- function can be used, with the desired seed, state array, and size of
- the array.
- .IP " 2." 4
- The
- \fIsetstate\fR()
- function, with the desired state, can be used, followed by
- \fIsrandom\fR()
- 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.
- .P
- Although some implementations of
- \fIrandom\fR()
- have written messages to standard error, such implementations do not
- conform to POSIX.1\(hy2008.
- .P
- Issue 5 restored the historical behavior of this function.
- .P
- Threaded applications should use
- \fIerand48\fR(),
- \fInrand48\fR(),
- or
- \fIjrand48\fR()
- instead of
- \fIrandom\fR()
- when an independent random number sequence in multiple threads is
- required.
- .P
- These functions should be avoided whenever non-trivial requirements
- (including safety) have to be fulfilled.
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIdrand48\fR\^(\|)",
- .IR "\fIrand\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<stdlib.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .