svn commit: r356935 - head/lib/libc/stdlib
Conrad Meyer
cem at FreeBSD.org
Mon Jan 20 23:44:11 UTC 2020
Author: cem
Date: Mon Jan 20 23:44:10 2020
New Revision: 356935
URL: https://svnweb.freebsd.org/changeset/base/356935
Log:
random.3: Some minor improvements to wording/clarity
Modified:
head/lib/libc/stdlib/random.3
Modified: head/lib/libc/stdlib/random.3
==============================================================================
--- head/lib/libc/stdlib/random.3 Mon Jan 20 23:43:47 2020 (r356934)
+++ head/lib/libc/stdlib/random.3 Mon Jan 20 23:44:10 2020 (r356935)
@@ -28,7 +28,7 @@
.\" @(#)random.3 8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
-.Dd April 22, 2019
+.Dd January 20, 2020
.Dt RANDOM 3
.Os
.Sh NAME
@@ -60,7 +60,7 @@ Applications which require unpredictable random number
instead.
.Ef
.Pp
-The
+Unless initialized with less than 32 bytes of state, the
.Fn random
function
uses a non-linear additive feedback random number generator employing a
@@ -72,53 +72,51 @@ The period of this random number generator is very lar
.if t 16\(mu(2\u\s731\s10\d\(mi1).
.if n 16*((2**31)\(mi1).
.Pp
+If initialized with less than 32 bytes of state,
+.Fn random
+uses the same poor-quality Park-Miller LCG as
+.Xr rand 3 .
+.Pp
The
.Fn random
and
.Fn srandom
-functions have (almost) the same calling sequence and initialization properties as the
+functions are analagous to
.Xr rand 3
and
-.Xr srand 3
-functions.
+.Xr srand 3 .
The difference is that
.Xr 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
-.Fn random
-are usable.
-For example,
-.Sq Li random()&01
-will produce a random binary
-value.
+is a worse pseudo-random number generator.
.Pp
Like
.Xr rand 3 ,
.Fn random
-will by default produce a sequence of numbers that can be duplicated
-by calling
-.Fn srandom
-with
-.Ql 1
-as the seed.
+is implicitly initialized as if
+.Fn srandom "1"
+had been invoked explicitly.
.Pp
The
.Fn srandomdev
-routine initializes a state array using
-pseudo-random numbers obtained from the kernel.
-Note that this particular seeding
-procedure can generate states which are impossible to reproduce by
-calling
-.Fn srandom
-with any value, since the succeeding terms in the
-state buffer are no longer derived from the LC algorithm applied to
-a fixed seed.
+routine initializes the state array using random numbers obtained from the
+kernel.
+This can generate states which are impossible to reproduce by calling
+.Fn srandom ,
+because the succeeding terms in the state buffer are no longer derived from the
+Park-Miller LCG algorithm applied to a fixed seed.
.Pp
The
.Fn initstate
-routine allows a state array, passed in as an argument, to be initialized
-for future use.
+routine initializes the provided state array of
+.Vt uint32_t
+values and uses it in future
+.Fn random
+invocations.
+(Despite the
+.Vt char *
+type of
+.Fa state ,
+the underlying object must be a naturally aligned array of 32-bit values.)
The size of the state array (in bytes) is used by
.Fn initstate
to decide how sophisticated a random number generator it should use \(em the
@@ -127,26 +125,21 @@ more state, the better the random numbers will be.
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.
The
+.Fa seed
+is used as in
+.Fn srandom .
+The
.Fn initstate
function
returns a pointer to the previous state information array.
.Pp
-Once a state has been initialized, the
-.Fn setstate
-routine provides for rapid switching between states.
The
.Fn setstate
-function
-returns a pointer to the previous state array; its
-argument state array is used for further random number generation
-until the next call to
-.Fn initstate
-or
-.Fn setstate .
+routine switches
+.Fn random
+to using the provided state.
+It returns a pointer to the previous state.
.Pp
Once a state array has been initialized, it may be restarted at a
different point either by calling
More information about the svn-src-all
mailing list