manual page first distributed with 4.2BSD

SCCS-vsn: lib/libc/stdlib/random.3 5.1

diff --git a/usr/src/lib/libc/stdlib/random.3 b/usr/src/lib/libc/stdlib/random.3
new file mode 100644 (file)
index 0000000..690db4b
--- /dev/null
+++ b/usr/src/lib/libc/stdlib/random.3
@@ -0,0 +1,121 @@
+.\" 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    5.1 (Berkeley) %G%
+.\"
+.TH RANDOM 3 "19 January 1983"
+.UC 5
+.SH NAME
+random, srandom, initstate, setstate \- better random number generator; routines for changing generators
+.SH SYNOPSIS
+.nf
+.B long  random()
+.PP
+.B srandom(seed)
+.B int  seed;
+.PP
+.B char  *initstate(seed, state, n)
+.B unsigned  seed;
+.B char  *state;
+.B int  n;
+.PP
+.B char  *setstate(state)
+.B char  *state;
+.fi
+.SH DESCRIPTION
+.PP
+.I 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 2\u\s731\s10\d\-1.  The period of this
+random number generator is very large, approximately 16*(2\u\s731\s10\d\-1).
+.PP
+.I Random/srandom
+have (almost) the same calling sequence and initialization properties as
+.I rand/srand.
+The difference is that
+.IR rand (3)
+produces a much less random sequence -- in fact, the low dozen bits
+generated by rand go through a cyclic pattern.  All the bits generated by
+.I random
+are usable.  For example, \*(lqrandom()&01\*(rq will produce a random binary
+value.
+.PP
+Unlike
+.IR srand ,
+.I 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
+.IR rand (3),
+however,
+.I random
+will by default produce a sequence of numbers that can be duplicated
+by calling
+.I srandom
+with 
+.I 1
+as the seed.
+.PP
+The
+.I 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
+.I 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.
+.I Initstate
+returns a pointer to the previous state information array.
+.PP
+Once a state has been initialized, the
+.I setstate
+routine provides for rapid switching between states.
+.I 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
+.I initstate
+or
+.I setstate.
+.PP
+Once a state array has been initialized, it may be restarted at a
+different point either by calling
+.I initstate
+(with the desired seed, the state array, and its size) or by calling
+both
+.I setstate
+(with the state array) and
+.I srandom
+(with the desired seed).
+The advantage of calling both
+.I setstate
+and
+.I 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 2\u\s769\s10\d, which should be sufficient for
+most purposes.
+.SH AUTHOR
+Earl T. Cohen
+.SH DIAGNOSTICS
+.PP
+If
+.I initstate
+is called with less than 8 bytes of state information, or if
+.I setstate
+detects that the state information has been garbled, error
+messages are printed on the standard error output.
+.SH "SEE ALSO"
+rand(3)
+.SH BUGS
+About 2/3 the speed of
+.IR rand (3C).