1 .\" Copyright (c) 1983, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)random.3 8.1 (Berkeley) 6/4/93
33 .\" $FreeBSD: src/lib/libc/stdlib/random.3,v 1.11.2.6 2003/06/03 19:13:16 schweikh Exp $
34 .\" $DragonFly: src/lib/libc/stdlib/random.3,v 1.5 2007/06/29 19:34:41 swildner Exp $
45 .Nd better random number generator; routines for changing generators
53 .Fn srandom "unsigned long seed"
57 .Fn initstate "unsigned long seed" "char *state" "long n"
59 .Fn setstate "char *state"
64 uses a non-linear additive feedback random number generator employing a
65 default table of size 31 long integers to return successive pseudo-random
66 numbers in the range from 0 to
67 .if t 2\u\s731\s10\d\(mi1.
69 The period of this random number generator is very large, approximately
70 .if t 16\(mu(2\u\s731\s10\d\(mi1).
71 .if n 16*((2**31)\(mi1).
77 functions have (almost) the same calling sequence and initialization properties as the
82 The difference is that
84 produces a much less random sequence \(em in fact, the low dozen bits
85 generated by rand go through a cyclic pattern. All the bits generated by
87 are usable. For example,
89 will produce a random binary
95 will by default produce a sequence of numbers that can be duplicated
104 routine initializes a state array using the
106 random number device which returns good random numbers,
107 suitable for cryptographic use.
108 Note that this particular seeding
109 procedure can generate states which are impossible to reproduce by
112 with any value, since the succeeding terms in the
113 state buffer are no longer derived from the LC algorithm applied to
118 routine allows a state array, passed in as an argument, to be initialized
119 for future use. The size of the state array (in bytes) is used by
121 to decide how sophisticated a random number generator it should use \(em the
122 more state, the better the random numbers will be.
123 (Current "optimal" values for the amount of state information are
124 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to
125 the nearest known amount. Using less than 8 bytes will cause an error.)
126 The seed for the initialization (which specifies a starting point for
127 the random number sequence, and provides for restarting at the same
128 point) is also an argument.
132 returns a pointer to the previous state information array.
134 Once a state has been initialized, the
136 routine provides for rapid switching between states.
140 returns a pointer to the previous state array; its
141 argument state array is used for further random number generation
142 until the next call to
147 Once a state array has been initialized, it may be restarted at a
148 different point either by calling
150 (with the desired seed, the state array, and its size) or by calling
153 (with the state array) and
155 (with the desired seed).
156 The advantage of calling both
160 is that the size of the state array does not have to be remembered after
163 With 256 bytes of state information, the period of the random number
164 generator is greater than
165 .if t 2\u\s769\s10\d,
167 which should be sufficient for most purposes.
171 is called with less than 8 bytes of state information, or if
173 detects that the state information has been garbled, error
174 messages are printed on the standard error output.
182 functions appeared in
187 About 2/3 the speed of
190 The historical implementation used to have a very weak seeding; the
191 random sequence did not vary much with the seed.
192 The current implementation employs a better pseudo-random number
193 generator for the initial state calculation.