1.\" Copyright (c) 1983, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
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.
19.\"
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
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)random.3 8.1 (Berkeley) 6/4/93
33.\"
34.Dd June 4, 1993
35.Dt RANDOM 3
36.Os BSD 4.2
37.Sh NAME
38.Nm random ,
39.Nm srandom ,
40.Nm srandomdev ,
41.Nm initstate ,
42.Nm setstate
43.Nd better random number generator; routines for changing generators
44.Sh SYNOPSIS
45.Fd #include <stdlib.h>
46.Ft long
47.Fn random void
48.Ft void
49.Fn srandom "unsigned long seed"
50.Ft int
51.Fn srandomdev void
52.Ft char *
53.Fn initstate "unsigned long seed" "char *state" "long n"
54.Ft char *
55.Fn setstate "char *state"
56.Sh DESCRIPTION
57The
58.Fn random
59function
60uses a non-linear additive feedback random number generator employing a
61default table of size 31 long integers to return successive pseudo-random
62numbers in the range from 0 to
63.if t 2\u\s731\s10\d\(mi1.
64.if n (2**31)\(mi1.
65The period of this random number generator is very large, approximately
66.if t 16\(mu(2\u\s731\s10\d\(mi1).
67.if n 16*((2**31)\(mi1).
68.Pp
69The
70.Fn random
71and
72.Fn srandom
73functions have (almost) the same calling sequence and initialization properties as the
74.Xr rand 3
75and
76.Xr srand 3
77functions.
78The difference is that
79.Xr rand 3
80produces a much less random sequence \(em in fact, the low dozen bits
81generated by rand go through a cyclic pattern. All the bits generated by
82.Fn random
83are usable. For example,
84.Sq Li random()&01
85will produce a random binary
86value.
87.Pp
88Like
89.Xr rand 3 ,
90.Fn random
91will by default produce a sequence of numbers that can be duplicated
92by calling
93.Fn srandom
94with
95.Ql 1
96as the seed.
97.Pp
98The
99.Fn srandomdev
100routine initialize a state array using
101.Xr urandom 4
102random number device which returns good random numbers,
103suitable for cryptographic use.
104Note that this particular seeding
105procedure can generate states which are impossible to reproduce by
106calling
107.Fn srandom
108with any value, since the succeeding terms in the
109state buffer are no longer derived from the LC algorithm applied to
110a fixed seed.
111If successful
112.Fn srandomdev
113returns 0. It returns -1 on failure, and sets
114.Va errno
115to indicate the error.
116.Pp
117The
118.Fn initstate
119routine allows a state array, passed in as an argument, to be initialized
120for future use. The size of the state array (in bytes) is used by
121.Fn initstate
122to decide how sophisticated a random number generator it should use \(em the
123more state, the better the random numbers will be.
124(Current "optimal" values for the amount of state information are
1258, 32, 64, 128, and 256 bytes; other amounts will be rounded down to
126the nearest known amount. Using less than 8 bytes will cause an error.)
127The seed for the initialization (which specifies a starting point for
128the random number sequence, and provides for restarting at the same
129point) is also an argument.
130The
131.Fn initstate
132function
133returns a pointer to the previous state information array.
134.Pp
135Once a state has been initialized, the
136.Fn setstate
137routine provides for rapid switching between states.
138The
139.Fn setstate
140function
141returns a pointer to the previous state array; its
142argument state array is used for further random number generation
143until the next call to
144.Fn initstate
145or
146.Fn setstate .
147.Pp
148Once a state array has been initialized, it may be restarted at a
149different point either by calling
150.Fn initstate
151(with the desired seed, the state array, and its size) or by calling
152both
153.Fn setstate
154(with the state array) and
155.Fn srandom
156(with the desired seed).
157The advantage of calling both
158.Fn setstate
159and
160.Fn srandom
161is that the size of the state array does not have to be remembered after
162it is initialized.
163.Pp
164With 256 bytes of state information, the period of the random number
165generator is greater than
166.if t 2\u\s769\s10\d,
167.if n 2**69
168which should be sufficient for most purposes.
169.Sh AUTHOR
170Earl T. Cohen
171.Sh DIAGNOSTICS
172If
173.Fn initstate
174is called with less than 8 bytes of state information, or if
175.Fn setstate
176detects that the state information has been garbled, error
177messages are printed on the standard error output.
178.Sh SEE ALSO
179.Xr rand 3 ,
180.Xr srand 3 ,
181.Xr urandom 4
182.Sh HISTORY
183These
184functions appeared in
185.Bx 4.2 .
186.Sh BUGS
187.Pp
188About 2/3 the speed of
189.Xr rand 3 .
190.Pp
191The historical implementation used to have a very weak seeding; the
| 1.\" Copyright (c) 1983, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
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.
19.\"
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
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)random.3 8.1 (Berkeley) 6/4/93
33.\"
34.Dd June 4, 1993
35.Dt RANDOM 3
36.Os BSD 4.2
37.Sh NAME
38.Nm random ,
39.Nm srandom ,
40.Nm srandomdev ,
41.Nm initstate ,
42.Nm setstate
43.Nd better random number generator; routines for changing generators
44.Sh SYNOPSIS
45.Fd #include <stdlib.h>
46.Ft long
47.Fn random void
48.Ft void
49.Fn srandom "unsigned long seed"
50.Ft int
51.Fn srandomdev void
52.Ft char *
53.Fn initstate "unsigned long seed" "char *state" "long n"
54.Ft char *
55.Fn setstate "char *state"
56.Sh DESCRIPTION
57The
58.Fn random
59function
60uses a non-linear additive feedback random number generator employing a
61default table of size 31 long integers to return successive pseudo-random
62numbers in the range from 0 to
63.if t 2\u\s731\s10\d\(mi1.
64.if n (2**31)\(mi1.
65The period of this random number generator is very large, approximately
66.if t 16\(mu(2\u\s731\s10\d\(mi1).
67.if n 16*((2**31)\(mi1).
68.Pp
69The
70.Fn random
71and
72.Fn srandom
73functions have (almost) the same calling sequence and initialization properties as the
74.Xr rand 3
75and
76.Xr srand 3
77functions.
78The difference is that
79.Xr rand 3
80produces a much less random sequence \(em in fact, the low dozen bits
81generated by rand go through a cyclic pattern. All the bits generated by
82.Fn random
83are usable. For example,
84.Sq Li random()&01
85will produce a random binary
86value.
87.Pp
88Like
89.Xr rand 3 ,
90.Fn random
91will by default produce a sequence of numbers that can be duplicated
92by calling
93.Fn srandom
94with
95.Ql 1
96as the seed.
97.Pp
98The
99.Fn srandomdev
100routine initialize a state array using
101.Xr urandom 4
102random number device which returns good random numbers,
103suitable for cryptographic use.
104Note that this particular seeding
105procedure can generate states which are impossible to reproduce by
106calling
107.Fn srandom
108with any value, since the succeeding terms in the
109state buffer are no longer derived from the LC algorithm applied to
110a fixed seed.
111If successful
112.Fn srandomdev
113returns 0. It returns -1 on failure, and sets
114.Va errno
115to indicate the error.
116.Pp
117The
118.Fn initstate
119routine allows a state array, passed in as an argument, to be initialized
120for future use. The size of the state array (in bytes) is used by
121.Fn initstate
122to decide how sophisticated a random number generator it should use \(em the
123more state, the better the random numbers will be.
124(Current "optimal" values for the amount of state information are
1258, 32, 64, 128, and 256 bytes; other amounts will be rounded down to
126the nearest known amount. Using less than 8 bytes will cause an error.)
127The seed for the initialization (which specifies a starting point for
128the random number sequence, and provides for restarting at the same
129point) is also an argument.
130The
131.Fn initstate
132function
133returns a pointer to the previous state information array.
134.Pp
135Once a state has been initialized, the
136.Fn setstate
137routine provides for rapid switching between states.
138The
139.Fn setstate
140function
141returns a pointer to the previous state array; its
142argument state array is used for further random number generation
143until the next call to
144.Fn initstate
145or
146.Fn setstate .
147.Pp
148Once a state array has been initialized, it may be restarted at a
149different point either by calling
150.Fn initstate
151(with the desired seed, the state array, and its size) or by calling
152both
153.Fn setstate
154(with the state array) and
155.Fn srandom
156(with the desired seed).
157The advantage of calling both
158.Fn setstate
159and
160.Fn srandom
161is that the size of the state array does not have to be remembered after
162it is initialized.
163.Pp
164With 256 bytes of state information, the period of the random number
165generator is greater than
166.if t 2\u\s769\s10\d,
167.if n 2**69
168which should be sufficient for most purposes.
169.Sh AUTHOR
170Earl T. Cohen
171.Sh DIAGNOSTICS
172If
173.Fn initstate
174is called with less than 8 bytes of state information, or if
175.Fn setstate
176detects that the state information has been garbled, error
177messages are printed on the standard error output.
178.Sh SEE ALSO
179.Xr rand 3 ,
180.Xr srand 3 ,
181.Xr urandom 4
182.Sh HISTORY
183These
184functions appeared in
185.Bx 4.2 .
186.Sh BUGS
187.Pp
188About 2/3 the speed of
189.Xr rand 3 .
190.Pp
191The historical implementation used to have a very weak seeding; the
|