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 .IR 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 .IR 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 /sys/src/libc/port/*rand.c
160 .br
161 .B /sys/src/libc/9sys/truerand.c
162 .br
163 .B /sys/src/libsec/port/genrandom.c
164 .br
165 .B /sys/src/libsec/port/prng.c
166 .br
167 .B /sys/src/libsec/port/*fastrand.c
168 .SH "SEE ALSO
169 .IR cons (3),
170 .IR mp (3),
171 .SH BUGS
172 .I Truerand
173 and
174 .I ntruerand
175 maintain a static file descriptor.