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