Added man pages.

man/man3/random.3

@@ -0,0 +1,131 @@
+.\" Copyright (c) 1983 Regents of the University of California.
+.\" All rights reserved.  The Berkeley software License Agreement
+.\" specifies the terms and conditions for redistribution.
+.\"
+.\"	@(#)random.3	6.2 (Berkeley) 9/29/85
+.\"
+.TH RANDOM 3 "September 29, 1985"
+.UC 5
+.SH NAME
+random, srandom, initstate, setstate \- better random number generator; routines for changing generators
+.SH SYNOPSIS
+.nf
+.ft B
+#include <stdlib.h>
+
+long random(void)
+void srandom(unsigned \fIseed\fP)
+char *initstate(unsigned \fIseed\fP, char *\fIstate\fP, int \fIn\fP)
+char *setstate(char *\fIstate\fP)
+.ft R
+.fi
+.SH DESCRIPTION
+.PP
+.B Random
+uses a non-linear additive feedback random number generator employing a
+default table of size 31 long integers to return successive pseudo-random
+numbers in the range from 0 to
+.if t 2\u\s731\s10\d\(mi1.
+.if n (2**31)\(mi1.
+The period of this random number generator is very large, approximately
+.if t 16\(mu(2\u\s731\s10\d\(mi1).
+.if n 16*((2**31)\(mi1).
+.PP
+.B Random/srandom
+have (almost) the same calling sequence and initialization properties as
+.B rand/srand.
+The difference is that
+.BR rand (3)
+produces a much less random sequence \(em in fact, the low dozen bits
+generated by rand go through a cyclic pattern.  All the bits generated by
+.B random
+are usable.  For example, ``random()&01'' will produce a random binary
+value.
+.PP
+Unlike
+.BR srand ,
+.B srandom
+does not return the old seed; the reason for this is that the amount of
+state information used is much more than a single word.  (Two other
+routines are provided to deal with restarting/changing random
+number generators).  Like
+.BR rand (3),
+however,
+.B random
+will by default produce a sequence of numbers that can be duplicated
+by calling
+.B srandom
+with 
+.B 1
+as the seed.
+.PP
+The
+.B initstate
+routine allows a state array, passed in as an argument, to be initialized
+for future use.  The size of the state array (in bytes) is used by
+.B initstate
+to decide how sophisticated a random number generator it should use -- the
+more state, the better the random numbers will be.
+(Current "optimal" values for the amount of state information are
+8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to
+the nearest known amount.  Using less than 8 bytes will cause an error).
+The seed for the initialization (which specifies a starting point for
+the random number sequence, and provides for restarting at the same
+point) is also an argument.
+.B Initstate
+returns a pointer to the previous state information array.
+.PP
+Once a state has been initialized, the
+.B setstate
+routine provides for rapid switching between states.
+.B Setstate
+returns a pointer to the previous state array; its
+argument state array is used for further random number generation
+until the next call to
+.B initstate
+or
+.BR setstate .
+.PP
+Once a state array has been initialized, it may be restarted at a
+different point either by calling
+.B initstate
+(with the desired seed, the state array, and its size) or by calling
+both
+.B setstate
+(with the state array) and
+.B srandom
+(with the desired seed).
+The advantage of calling both
+.B setstate
+and
+.B srandom
+is that the size of the state array does not have to be remembered after
+it is initialized.
+.PP
+With 256 bytes of state information, the period of the random number
+generator is greater than
+.if t 2\u\s769\s10\d,
+.if n 2**69
+which should be sufficient for most purposes.
+.SH AUTHOR
+Earl T. Cohen
+.SH DIAGNOSTICS
+.PP
+If
+.B initstate
+is called with less than 8 bytes of state information, or if
+.B setstate
+detects that the state information has been garbled, error
+messages are printed on the standard error output.
+.SH "SEE ALSO"
+.BR rand (3).
+.SH NOTES
+.B initstate
+and
+.B setstate
+are not declared in
+.IR <stdlib.h> ,
+programmers must provide their own declarations.
+.SH BUGS
+About 2/3 the speed of
+.BR rand (3).