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 | .\" | |
0b373d97 | 5 | .\" @(#)random.3 6.1 (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 | |
31 | numbers in the range from 0 to 2\u\s731\s10\d\-1. The period of this | |
32 | random number generator is very large, approximately 16*(2\u\s731\s10\d\-1). | |
33 | .PP | |
34 | .I Random/srandom | |
35 | have (almost) the same calling sequence and initialization properties as | |
36 | .I rand/srand. | |
37 | The difference is that | |
38 | .IR rand (3) | |
39 | produces a much less random sequence -- in fact, the low dozen bits | |
40 | generated by rand go through a cyclic pattern. All the bits generated by | |
41 | .I random | |
42 | are usable. For example, \*(lqrandom()&01\*(rq will produce a random binary | |
43 | value. | |
44 | .PP | |
45 | Unlike | |
46 | .IR srand , | |
47 | .I srandom | |
48 | does not return the old seed; the reason for this is that the amount of | |
49 | state information used is much more than a single word. (Two other | |
50 | routines are provided to deal with restarting/changing random | |
51 | number generators). Like | |
52 | .IR rand (3), | |
53 | however, | |
54 | .I random | |
55 | will by default produce a sequence of numbers that can be duplicated | |
56 | by calling | |
57 | .I srandom | |
58 | with | |
59 | .I 1 | |
60 | as the seed. | |
61 | .PP | |
62 | The | |
63 | .I initstate | |
64 | routine allows a state array, passed in as an argument, to be initialized | |
65 | for future use. The size of the state array (in bytes) is used by | |
66 | .I initstate | |
67 | to decide how sophisticated a random number generator it should use -- the | |
68 | more state, the better the random numbers will be. | |
69 | (Current "optimal" values for the amount of state information are | |
70 | 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to | |
71 | the nearest known amount. Using less than 8 bytes will cause an error). | |
72 | The seed for the initialization (which specifies a starting point for | |
73 | the random number sequence, and provides for restarting at the same | |
74 | point) is also an argument. | |
75 | .I Initstate | |
76 | returns a pointer to the previous state information array. | |
77 | .PP | |
78 | Once a state has been initialized, the | |
79 | .I setstate | |
80 | routine provides for rapid switching between states. | |
0b373d97 KM |
81 | .I Setstate |
82 | returns a pointer to the previous state array; its | |
7db0d200 KM |
83 | argument state array is used for further random number generation |
84 | until the next call to | |
85 | .I initstate | |
86 | or | |
87 | .I setstate. | |
88 | .PP | |
89 | Once a state array has been initialized, it may be restarted at a | |
90 | different point either by calling | |
91 | .I initstate | |
92 | (with the desired seed, the state array, and its size) or by calling | |
93 | both | |
94 | .I setstate | |
95 | (with the state array) and | |
96 | .I srandom | |
97 | (with the desired seed). | |
98 | The advantage of calling both | |
99 | .I setstate | |
100 | and | |
101 | .I srandom | |
102 | is that the size of the state array does not have to be remembered after | |
103 | it is initialized. | |
104 | .PP | |
105 | With 256 bytes of state information, the period of the random number | |
106 | generator is greater than 2\u\s769\s10\d, which should be sufficient for | |
107 | most purposes. | |
108 | .SH AUTHOR | |
109 | Earl T. Cohen | |
110 | .SH DIAGNOSTICS | |
111 | .PP | |
112 | If | |
113 | .I initstate | |
114 | is called with less than 8 bytes of state information, or if | |
115 | .I setstate | |
116 | detects that the state information has been garbled, error | |
117 | messages are printed on the standard error output. | |
118 | .SH "SEE ALSO" | |
119 | rand(3) | |
120 | .SH BUGS | |
121 | About 2/3 the speed of | |
122 | .IR rand (3C). |