From owner-svn-src-all@freebsd.org Mon Jan 20 23:44:11 2020 Return-Path: Delivered-To: svn-src-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 735E522A372; Mon, 20 Jan 2020 23:44:11 +0000 (UTC) (envelope-from cem@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 481pCv2FPXz3x0Y; Mon, 20 Jan 2020 23:44:11 +0000 (UTC) (envelope-from cem@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 486523A8A; Mon, 20 Jan 2020 23:44:11 +0000 (UTC) (envelope-from cem@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id 00KNiBcZ028395; Mon, 20 Jan 2020 23:44:11 GMT (envelope-from cem@FreeBSD.org) Received: (from cem@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id 00KNiBfs028394; Mon, 20 Jan 2020 23:44:11 GMT (envelope-from cem@FreeBSD.org) Message-Id: <202001202344.00KNiBfs028394@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: cem set sender to cem@FreeBSD.org using -f From: Conrad Meyer Date: Mon, 20 Jan 2020 23:44:11 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r356935 - head/lib/libc/stdlib X-SVN-Group: head X-SVN-Commit-Author: cem X-SVN-Commit-Paths: head/lib/libc/stdlib X-SVN-Commit-Revision: 356935 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 20 Jan 2020 23:44:11 -0000 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