1 .TH RAND 3
2 .SH NAME
3 rand, lrand, frand, nrand, lnrand, srand, truerand, ntruerand, fastrand, nfastrand \- random number generator
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .PP
9 .ta \w'\fLdouble 'u
10 .B
11 int	rand(void)
12 .PP
13 .B
14 long	lrand(void)
15 .PP
16 .B
17 double	frand(void)
18 .PP
19 .B
20 int	nrand(int val)
21 .PP
22 .B
23 long	lnrand(long val)
24 .PP
25 .B
26 void	srand(long seed)
27 .PP
28 .B
29 ulong	truerand(void)
30 .PP
31 .B
32 ulong	ntruerand(ulong val)
33 .sp
34 .B #include <mp.h>
35 .br
36 .B #include <libsec.h>
37 .PP
38 .B
39 void	genrandom(uchar *buf, int nbytes)
40 .PP
41 .B
42 void	prng(uchar *buf, int nbytes)
43 .PP
44 .B
45 ulong	fastrand(void)
46 .PP
47 .B
48 ulong	nfastrand(ulong val)
49 .SH DESCRIPTION
50 .I Rand
51 returns a uniform pseudo-random
52 number
53 .IR x ,
54 .RI 0≤ x <2\u\s715\s10\d.
55 .PP
56 .I Lrand
57 returns a uniform
58 .B long
59 .IR x ,
60 .RI 0≤ x <2\u\s731\s10\d.
61 .PP
62 .I Frand
63 returns a uniform
64 .B double
65 .IR x ,
66 .RI 0.0≤ x <1.0,
67 This function calls
68 .I lrand
69 twice to generate a number with as many as 62 significant bits of mantissa.
70 .PP
71 .I Nrand
72 returns a uniform integer
73 .IR x ,
74 .RI 0≤ x < val.
75 .I Lnrand
76 is the same, but returns a
77 .BR long .
78 .PP
79 The algorithm is additive feedback with:
80 .IP
81 x[n] = (x[n\(mi273] + x[n\(mi607]) mod
82 .if t 2\u\s731\s0\d
83 .if n 2^31
84 .LP
85 giving a period of
86 .if t 2\u\s730\s10\d \(mu (2\u\s7607\s10\d \- 1).
87 .if n 2^30 × (2^607 - 1).
88 .PP
89 The generators are initialized by calling
90 .I srand
91 with whatever you like as argument.
92 To get a different starting value each time,
93 .IP
94 .L
95 srand(time(0))
96 .LP
97 will work as long as it is not called more often
98 than once per second.
99 Calling
100 .IP
101 .L
102 srand(1)
103 .LP
104 will initialize the generators to their
105 starting state.
106 .PP
107 .I Truerand
108 returns a random unsigned long read from
109 .BR /dev/random .
110 Due to the nature of
111 .BR /dev/random ,
112 truerand can only return a few hundred bits a
113 second.
114 .PP
115 .I Ntruerand
116 returns a uniform random integer
117 .IR x ,
118 .RI 0≤ x < val ≤ 2\u\s732\s10\d-1.
119 .PP
120 .I Genrandom
121 fills a buffer with bytes from the X9.17 pseudo-random
122 number generator.  The X9.17 generator is seeded by 24
123 truly random bytes read from
124 .BR /dev/random .
125 .PP
126 .I Prng
127 uses the native
128 .MR rand (3)
129 pseudo-random number generator to fill the buffer.  Used with
130 .IR srand ,
131 this function can produce a reproducible stream of pseudo random
132 numbers useful in testing.
133 .PP
134 Both
135 .I genrandom
136 and
137 .I prng
138 may be passed to
139 .I mprand
140 (see
141 .MR mp (3) ).
142 .PP
143 .I Fastrand
144 uses
145 .I genrandom
146 to return a uniform
147 .B "unsigned long
148 .IR x ,
149 .RI 0≤ x < 2\u\s732\s10\d-1.
150 .PP
151 .I Nfastrand
152 uses
153 .I genrandom
154 to return a uniform
155 .B "unsigned long
156 .IR x ,
157 .RI 0≤ x < val ≤ 2\u\s732\s10\d-1.
158 .SH SOURCE
159 .B \*9/src/lib9
160 .br
161 .B \*9/src/libsec/port
162 .SH "SEE ALSO
163 .\" .IR cons (3),
164 .MR mp (3)
165 .SH BUGS
166 .I Truerand
167 and
168 .I ntruerand
169 maintain a static file descriptor.
170 .PP
171 To avoid name conflicts with the underlying system,
172 .IR rand ,
173 .IR lrand ,
174 .IR frand ,
175 .IR nrand ,
176 .IR lnrand ,
177 and
178 .I srand
179 are preprocessor macros defined as
180 .IR p9rand ,
181 .IR p9lrand ,
182 and so on;
183 see
184 .MR intro (3) .
185 .ie \n(HT .ds HT "
186 .el .ds HT " (see HTML-formatted man page for link)
187 .PP
188 Some versions of SunOS do not ship with
189 .B /dev/random
190 installed.
191 You may have to download a
192 .HR "http://sunsolve.sun.com/search/document.do?assetkey=1-25-27606-1" "patch from Sun\*(HT"
193 to add it to your system.