]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da MK |
2 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
5 | .\" |
6 | .\" References consulted: | |
7 | .\" Linux libc source code | |
8 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
9 | .\" 386BSD man pages | |
10 | .\" | |
11 | .\" Modified 1993-03-29, David Metcalfe | |
12 | .\" Modified 1993-04-28, Lars Wirzenius | |
13 | .\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) | |
14 | .\" Modified 1995-05-18, Rik Faith (faith@cs.unc.edu) to add | |
15 | .\" better discussion of problems with rand on other systems. | |
16 | .\" (Thanks to Esa Hyyti{ (ehyytia@snakemail.hut.fi).) | |
e00c3a07 | 17 | .\" Modified 1998-04-10, Nicolás Lichtmaier <nick@debian.org> |
fea681da MK |
18 | .\" with contribution from Francesco Potorti <F.Potorti@cnuce.cnr.it> |
19 | .\" Modified 2003-11-15, aeb, added rand_r | |
05a46db6 | 20 | .\" 2010-09-13, mtk, added example program |
fea681da | 21 | .\" |
4c1c5274 | 22 | .TH rand 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
23 | .SH NAME |
24 | rand, rand_r, srand \- pseudo-random number generator | |
1f5aa550 AC |
25 | .SH LIBRARY |
26 | Standard C library | |
8fc3b2cf | 27 | .RI ( libc ", " \-lc ) |
fea681da MK |
28 | .SH SYNOPSIS |
29 | .nf | |
30 | .B #include <stdlib.h> | |
68e4db0a | 31 | .PP |
fea681da | 32 | .B int rand(void); |
fea681da | 33 | .BI "void srand(unsigned int " seed ); |
aa43f7bd AC |
34 | .PP |
35 | .BI "[[deprecated]] int rand_r(unsigned int *" seedp ); | |
fea681da | 36 | .fi |
68e4db0a | 37 | .PP |
d39ad78f | 38 | .RS -4 |
cc4615cc MK |
39 | Feature Test Macro Requirements for glibc (see |
40 | .BR feature_test_macros (7)): | |
d39ad78f | 41 | .RE |
68e4db0a | 42 | .PP |
cc4615cc | 43 | .BR rand_r (): |
9d2adbae MK |
44 | .nf |
45 | Since glibc 2.24: | |
46 | _POSIX_C_SOURCE >= 199506L | |
75c018a1 | 47 | glibc 2.23 and earlier |
9d2adbae MK |
48 | _POSIX_C_SOURCE |
49 | .fi | |
fea681da | 50 | .SH DESCRIPTION |
60a90ecd MK |
51 | The |
52 | .BR rand () | |
50cbc42b | 53 | function returns a pseudo-random integer in the range 0 to |
1ae6b2c7 | 54 | .B RAND_MAX |
91e9dd28 | 55 | inclusive (i.e., the mathematical range [0,\ \fBRAND_MAX\fR]). |
fea681da | 56 | .PP |
60a90ecd MK |
57 | The |
58 | .BR srand () | |
59 | function sets its argument as the seed for a new | |
60 | sequence of pseudo-random integers to be returned by | |
61 | .BR rand (). | |
62 | These sequences are repeatable by calling | |
63 | .BR srand () | |
50cbc42b | 64 | with the same seed value. |
fea681da | 65 | .PP |
60a90ecd MK |
66 | If no seed value is provided, the |
67 | .BR rand () | |
50cbc42b | 68 | function is automatically seeded with a value of 1. |
fea681da MK |
69 | .PP |
70 | The function | |
63aa9df0 | 71 | .BR rand () |
570d37e7 | 72 | is not reentrant, since it |
c13182ef | 73 | uses hidden state that is modified on each call. |
50cbc42b MK |
74 | This might just be the seed value to be used by the next call, |
75 | or it might be something more elaborate. | |
d9bfdb9c | 76 | In order to get reproducible behavior in a threaded |
d931893b MK |
77 | application, this state must be made explicit; |
78 | this can be done using the reentrant function | |
7f7cdb47 | 79 | .BR rand_r (). |
b4937795 | 80 | .PP |
d931893b MK |
81 | Like |
82 | .BR rand (), | |
83 | .BR rand_r () | |
84 | returns a pseudo-random integer in the range [0,\ \fBRAND_MAX\fR]. | |
85 | The | |
86 | .I seedp | |
87 | argument is a pointer to an | |
1ae6b2c7 | 88 | .I unsigned int |
d931893b MK |
89 | that is used to store state between calls. |
90 | If | |
91 | .BR rand_r () | |
92 | is called with the same initial value for the integer pointed to by | |
93 | .IR seedp , | |
94 | and that value is not modified between calls, | |
95 | then the same pseudo-random sequence will result. | |
b4937795 | 96 | .PP |
d931893b MK |
97 | The value pointed to by the |
98 | .I seedp | |
99 | argument of | |
63aa9df0 | 100 | .BR rand_r () |
d931893b MK |
101 | provides only a very small amount of state, |
102 | so this function will be a weak pseudo-random generator. | |
c13182ef | 103 | Try |
fea681da MK |
104 | .BR drand48_r (3) |
105 | instead. | |
47297adb | 106 | .SH RETURN VALUE |
60a90ecd MK |
107 | The |
108 | .BR rand () | |
109 | and | |
110 | .BR rand_r () | |
91e9dd28 | 111 | functions return a value between 0 and |
1ae6b2c7 | 112 | .B RAND_MAX |
91e9dd28 | 113 | (inclusive). |
60a90ecd MK |
114 | The |
115 | .BR srand () | |
116 | function returns no value. | |
570d37e7 PH |
117 | .SH ATTRIBUTES |
118 | For an explanation of the terms used in this section, see | |
119 | .BR attributes (7). | |
120 | .TS | |
121 | allbox; | |
c466875e | 122 | lbx lb lb |
570d37e7 PH |
123 | l l l. |
124 | Interface Attribute Value | |
125 | T{ | |
9e54434e BR |
126 | .na |
127 | .nh | |
570d37e7 PH |
128 | .BR rand (), |
129 | .BR rand_r (), | |
130 | .BR srand () | |
131 | T} Thread safety MT-Safe | |
132 | .TE | |
c466875e | 133 | .sp 1 |
4131356c | 134 | .SH VERSIONS |
60a90ecd MK |
135 | The versions of |
136 | .BR rand () | |
137 | and | |
138 | .BR srand () | |
50cbc42b | 139 | in the Linux C Library use the same random number generator as |
3a72373c | 140 | .BR random (3) |
60a90ecd | 141 | and |
3a72373c | 142 | .BR srandom (3), |
50cbc42b | 143 | so the lower-order bits should be as random as the higher-order bits. |
fea681da | 144 | However, on older |
63aa9df0 | 145 | .BR rand () |
fea681da MK |
146 | implementations, and on current implementations on different systems, |
147 | the lower-order bits are much less random than the higher-order bits. | |
148 | Do not use this function in applications intended to be portable | |
149 | when good randomness is needed. | |
a5ed7447 MK |
150 | (Use |
151 | .BR random (3) | |
152 | instead.) | |
4131356c AC |
153 | .SH STANDARDS |
154 | .TP | |
155 | .BR rand () | |
156 | .TQ | |
157 | .BR srand () | |
158 | C11, POSIX.1-2008. | |
159 | .TP | |
160 | .BR rand_r () | |
161 | POSIX.1-2008. | |
162 | .SH HISTORY | |
163 | .TP | |
164 | .BR rand () | |
165 | .TQ | |
166 | .BR srand () | |
167 | SVr4, 4.3BSD, C89, POSIX.1-2001. | |
168 | .TP | |
169 | .BR rand_r () | |
170 | POSIX.1-2001. | |
171 | Obsolete in POSIX.1-2008. | |
a14af333 | 172 | .SH EXAMPLES |
2b2581ee | 173 | POSIX.1-2001 gives the following example of an implementation of |
63aa9df0 | 174 | .BR rand () |
fea681da | 175 | and |
2b2581ee MK |
176 | .BR srand (), |
177 | possibly useful when one needs the same sequence on two different machines. | |
51f5698d | 178 | .PP |
a6e2f128 | 179 | .in +4n |
bdd915e2 | 180 | .EX |
a6e2f128 | 181 | static unsigned long next = 1; |
fe5dba13 | 182 | \& |
a6e2f128 MK |
183 | /* RAND_MAX assumed to be 32767 */ |
184 | int myrand(void) { | |
185 | next = next * 1103515245 + 12345; | |
186 | return((unsigned)(next/65536) % 32768); | |
187 | } | |
fe5dba13 | 188 | \& |
85908442 | 189 | void mysrand(unsigned int seed) { |
a6e2f128 MK |
190 | next = seed; |
191 | } | |
bdd915e2 | 192 | .EE |
a6e2f128 | 193 | .in |
9750142b MK |
194 | .PP |
195 | The following program can be used to display the | |
196 | pseudo-random sequence produced by | |
197 | .BR rand () | |
198 | when given a particular seed. | |
8341e8b6 AC |
199 | When the seed is |
200 | .IR \-1 , | |
201 | the program uses a random seed. | |
bdd915e2 | 202 | .PP |
9750142b | 203 | .in +4n |
b0b6ab4e | 204 | .\" SRC BEGIN (rand.c) |
bdd915e2 | 205 | .EX |
9750142b | 206 | #include <stdio.h> |
ad3868f0 | 207 | #include <stdlib.h> |
fe5dba13 | 208 | \& |
9750142b MK |
209 | int |
210 | main(int argc, char *argv[]) | |
211 | { | |
b42296e4 AC |
212 | int r; |
213 | unsigned int seed, nloops; | |
fe5dba13 | 214 | \& |
9750142b | 215 | if (argc != 3) { |
d1a71985 | 216 | fprintf(stderr, "Usage: %s <seed> <nloops>\en", argv[0]); |
9750142b MK |
217 | exit(EXIT_FAILURE); |
218 | } | |
fe5dba13 | 219 | \& |
9750142b MK |
220 | seed = atoi(argv[1]); |
221 | nloops = atoi(argv[2]); | |
fe5dba13 | 222 | \& |
8341e8b6 AC |
223 | if (seed == \-1) { |
224 | seed = arc4random(); | |
225 | printf("seed: %u\en", seed); | |
226 | } | |
fe5dba13 | 227 | \& |
9750142b | 228 | srand(seed); |
b42296e4 | 229 | for (unsigned int j = 0; j < nloops; j++) { |
9750142b | 230 | r = rand(); |
d1a71985 | 231 | printf("%d\en", r); |
9750142b | 232 | } |
fe5dba13 | 233 | \& |
9750142b MK |
234 | exit(EXIT_SUCCESS); |
235 | } | |
b9c93deb | 236 | .EE |
b0b6ab4e | 237 | .\" SRC END |
9750142b | 238 | .in |
47297adb | 239 | .SH SEE ALSO |
fea681da MK |
240 | .BR drand48 (3), |
241 | .BR random (3) |