Differential D23290 Diff 67637 head/lib/libc/stdlib/rand.3

Changeset View

Standalone View

head/lib/libc/stdlib/rand.3

	Show All 26 Lines
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" @(#)rand.3 8.1 (Berkeley) 6/4/93			.\" @(#)rand.3 8.1 (Berkeley) 6/4/93
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd December 14, 2019			.Dd February 1, 2020
	.Dt RAND 3			.Dt RAND 3
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm rand ,			.Nm rand ,
	.Nm srand ,			.Nm srand ,
	.Nm rand_r			.Nm rand_r
	.Nd bad random number generator			.Nd bad random number generator
	.Sh LIBRARY			.Sh LIBRARY
	Show All 10 Lines
	.Bf -symbolic			.Bf -symbolic
	The functions described in this manual page are not cryptographically			The functions described in this manual page are not cryptographically
	secure.			secure.
	Applications which require unpredictable random numbers should use			Applications which require unpredictable random numbers should use
	.Xr arc4random 3			.Xr arc4random 3
	instead.			instead.
	.Ef			.Ef
	.Pp			.Pp
	These interfaces are obsoleted by
	.Xr random 3 .
	.Pp
	The			The
	.Fn rand			.Fn rand
	function computes a sequence of pseudo-random integers in the range			function computes a sequence of pseudo-random integers in the range
	of 0 to			of 0 to
	.Dv RAND_MAX			.Dv RAND_MAX ,
	(as defined by the header file			inclusive.
	.In stdlib.h ) .
	.Pp			.Pp
	The			The
	.Fn srand			.Fn srand
	function sets its argument			function seeds the algorithm with the
	.Fa seed			.Fa seed
	as the seed for a new sequence of			parameter.
	pseudo-random numbers to be returned by			Repeatable sequences of
	.Fn rand .			.Fn rand
	These sequences are repeatable by calling			output may be obtained by calling
	.Fn srand			.Fn srand
	with the same seed value.			with the same
				.Fa seed .
				.Fn rand
				is implicitly initialized as if
				.Fn srand "1"
				had been invoked explicitly.
	.Pp			.Pp
	If no			In
	.Fa seed			.Fx 13 ,
	value is provided, the functions are automatically			.Fn rand
	seeded with a value of 1.			is implemented using the same 128-byte state LFSR generator algorithm as
	.Pp			.Xr random 3 .
	The			However, the legacy
	.Fn rand_r			.Fn rand_r
	function			function is not (and can not be, because of its limited
	provides the same functionality as			.Fa *ctx
	.Fn rand .			size).
	A pointer to the context value			.Fn rand_r
	.Fa ctx			implements the historical, poor-quality Park-Miller 32-bit LCG and should not
	must be supplied by the caller.			be used in new designs.
	.Pp			.Sh IMPLEMENTATION NOTES
	For better generator quality, use			Since
	.Xr random 3			.Fx 13 ,
	or			.Fn rand
	.Xr lrand48 3 .			is implemented with the same generator as
				.Xr random 3 ,
				so the low-order bits should no longer be significantly worse than the
				high-order bits.
	.Sh SEE ALSO			.Sh SEE ALSO
	.Xr arc4random 3 ,			.Xr arc4random 3 ,
	.Xr lrand48 3 ,
	.Xr random 3 ,			.Xr random 3 ,
	.Xr random 4			.Xr random 4
	.Sh STANDARDS			.Sh STANDARDS
	The			The
	.Fn rand			.Fn rand
	and			and
	.Fn srand			.Fn srand
	functions			functions
	conform to			conform to
	.St -isoC .			.St -isoC .
	.Pp			.Pp
	The			The
	.Fn rand_r			.Fn rand_r
	function is marked as obsolescent in POSIX and may be removed in a future			function is not part of
	revision of the standard.			.St -isoC
				and is marked obsolescent in
				.St -p1003.1-2008 .
				It may be removed in a future revision of POSIX.
				.Sh CAVEATS
				Prior to
				.Fx 13 ,
				.Fn rand
				used the historical Park-Miller generator with 32 bits of state and produced
				poor quality output, especially in the lower bits.
				.Fn rand
				in earlier versions of
				.Fx ,
				as well as other standards-conforming implementations, may continue to produce
				poor quality output.
				.Pp
				.Em These functions should not be used in portable applications that want a
				.Em high quality or high performance pseudorandom number generator .
				One possible replacement,
				.Xr random 3 ,
				is portable to Linux — but it is not especially fast, nor standardized.
				.Pp
				If broader portability or better performance is desired, any of the widely
				available and permissively licensed SFC64/32, JSF64/32, PCG64/32, or SplitMix64
				algorithm implementations may be embedded in your application.
				These algorithms have the benefit of requiring less space than
				.Xr random 3
				and being quite fast (in header inline implementations).