Commit | Line | Data |
---|---|---|
02c81f9a KB |
1 | .\" Copyright (c) 1983 The Regents of the University of California. |
2 | .\" All rights reserved. | |
7db0d200 | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
7db0d200 | 5 | .\" |
91cff1e1 | 6 | .\" @(#)random.3 6.4 (Berkeley) %G% |
02c81f9a KB |
7 | .\" |
8 | .UC 7 | |
0b373d97 | 9 | .TH RANDOM 3 "" |
7db0d200 KM |
10 | .UC 5 |
11 | .SH NAME | |
12 | random, srandom, initstate, setstate \- better random number generator; routines for changing generators | |
13 | .SH SYNOPSIS | |
14 | .nf | |
15 | .B long random() | |
16 | .PP | |
17 | .B srandom(seed) | |
18 | .B int seed; | |
19 | .PP | |
20 | .B char *initstate(seed, state, n) | |
21 | .B unsigned seed; | |
22 | .B char *state; | |
23 | .B int n; | |
24 | .PP | |
25 | .B char *setstate(state) | |
26 | .B char *state; | |
27 | .fi | |
28 | .SH DESCRIPTION | |
29 | .PP | |
30 | .I Random | |
31 | uses a non-linear additive feedback random number generator employing a | |
32 | default table of size 31 long integers to return successive pseudo-random | |
2bae4d9a KM |
33 | numbers in the range from 0 to |
34 | .if t 2\u\s731\s10\d\(mi1. | |
35 | .if n (2**31)\(mi1. | |
36 | The period of this random number generator is very large, approximately | |
37 | .if t 16\(mu(2\u\s731\s10\d\(mi1). | |
38 | .if n 16*((2**31)\(mi1). | |
7db0d200 KM |
39 | .PP |
40 | .I Random/srandom | |
41 | have (almost) the same calling sequence and initialization properties as | |
42 | .I rand/srand. | |
43 | The difference is that | |
44 | .IR rand (3) | |
2bae4d9a | 45 | produces a much less random sequence \(em in fact, the low dozen bits |
7db0d200 KM |
46 | generated by rand go through a cyclic pattern. All the bits generated by |
47 | .I random | |
2bae4d9a | 48 | are usable. For example, ``random()&01'' will produce a random binary |
7db0d200 KM |
49 | value. |
50 | .PP | |
51 | Unlike | |
52 | .IR srand , | |
53 | .I srandom | |
54 | does not return the old seed; the reason for this is that the amount of | |
55 | state information used is much more than a single word. (Two other | |
56 | routines are provided to deal with restarting/changing random | |
57 | number generators). Like | |
58 | .IR rand (3), | |
59 | however, | |
60 | .I random | |
61 | will by default produce a sequence of numbers that can be duplicated | |
62 | by calling | |
63 | .I srandom | |
64 | with | |
65 | .I 1 | |
66 | as the seed. | |
67 | .PP | |
68 | The | |
69 | .I initstate | |
70 | routine allows a state array, passed in as an argument, to be initialized | |
71 | for future use. The size of the state array (in bytes) is used by | |
72 | .I initstate | |
73 | to decide how sophisticated a random number generator it should use -- the | |
74 | more state, the better the random numbers will be. | |
75 | (Current "optimal" values for the amount of state information are | |
76 | 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to | |
77 | the nearest known amount. Using less than 8 bytes will cause an error). | |
78 | The seed for the initialization (which specifies a starting point for | |
79 | the random number sequence, and provides for restarting at the same | |
80 | point) is also an argument. | |
81 | .I Initstate | |
82 | returns a pointer to the previous state information array. | |
83 | .PP | |
84 | Once a state has been initialized, the | |
85 | .I setstate | |
86 | routine provides for rapid switching between states. | |
0b373d97 KM |
87 | .I Setstate |
88 | returns a pointer to the previous state array; its | |
7db0d200 KM |
89 | argument state array is used for further random number generation |
90 | until the next call to | |
91 | .I initstate | |
92 | or | |
93 | .I setstate. | |
94 | .PP | |
95 | Once a state array has been initialized, it may be restarted at a | |
96 | different point either by calling | |
97 | .I initstate | |
98 | (with the desired seed, the state array, and its size) or by calling | |
99 | both | |
100 | .I setstate | |
101 | (with the state array) and | |
102 | .I srandom | |
103 | (with the desired seed). | |
104 | The advantage of calling both | |
105 | .I setstate | |
106 | and | |
107 | .I srandom | |
108 | is that the size of the state array does not have to be remembered after | |
109 | it is initialized. | |
110 | .PP | |
111 | With 256 bytes of state information, the period of the random number | |
2bae4d9a KM |
112 | generator is greater than |
113 | .if t 2\u\s769\s10\d, | |
114 | .if n 2**69 | |
115 | which should be sufficient for most purposes. | |
7db0d200 KM |
116 | .SH AUTHOR |
117 | Earl T. Cohen | |
118 | .SH DIAGNOSTICS | |
119 | .PP | |
120 | If | |
121 | .I initstate | |
122 | is called with less than 8 bytes of state information, or if | |
123 | .I setstate | |
124 | detects that the state information has been garbled, error | |
125 | messages are printed on the standard error output. | |
126 | .SH "SEE ALSO" | |
127 | rand(3) | |
128 | .SH BUGS | |
129 | About 2/3 the speed of | |
130 | .IR rand (3C). |