Date: Mon, 20 Jan 2020 23:44:11 +0000 (UTC) From: Conrad Meyer <cem@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r356935 - head/lib/libc/stdlib Message-ID: <202001202344.00KNiBfs028394@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202001202344.00KNiBfs028394>