1 files changed, 137 insertions, 0 deletions
diff --git a/man3p/random.3p b/man3p/random.3p
new file mode 100644
index 000000000..60fa767bd
--- /dev/null
+++ b/man3p/random.3p
@@ -0,0 +1,137 @@
+.\" 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 .