From 825a73c36fad8c124870619e4d798c6867424ead Mon Sep 17 00:00:00 2001
From: Conrad Meyer <cem@FreeBSD.org>
Date: Mon, 20 Jan 2020 23:44:10 +0000
Subject: [PATCH] random.3: Some minor improvements to wording/clarity

---
 lib/libc/stdlib/random.3 | 81 ++++++++++++++++++----------------------
 1 file changed, 37 insertions(+), 44 deletions(-)

diff --git a/lib/libc/stdlib/random.3 b/lib/libc/stdlib/random.3
index b42e5d3d2a2e..82d21d1b048b 100644
--- a/lib/libc/stdlib/random.3
+++ b/lib/libc/stdlib/random.3
@@ -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 numbers should use
 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 large, approximately
 .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