]>
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> | |
c6d039a3 | 31 | .P |
fea681da | 32 | .B int rand(void); |
fea681da | 33 | .BI "void srand(unsigned int " seed ); |
c6d039a3 | 34 | .P |
aa43f7bd | 35 | .BI "[[deprecated]] int rand_r(unsigned int *" seedp ); |
fea681da | 36 | .fi |
c6d039a3 | 37 | .P |
d39ad78f | 38 | .RS -4 |
cc4615cc MK |
39 | Feature Test Macro Requirements for glibc (see |
40 | .BR feature_test_macros (7)): | |
d39ad78f | 41 | .RE |
c6d039a3 | 42 | .P |
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]). |
c6d039a3 | 56 | .P |
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. |
c6d039a3 | 65 | .P |
60a90ecd MK |
66 | If no seed value is provided, the |
67 | .BR rand () | |
50cbc42b | 68 | function is automatically seeded with a value of 1. |
c6d039a3 | 69 | .P |
fea681da | 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 (). |
c6d039a3 | 80 | .P |
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. | |
c6d039a3 | 96 | .P |
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 | |
4131356c | 133 | .SH VERSIONS |
60a90ecd MK |
134 | The versions of |
135 | .BR rand () | |
136 | and | |
137 | .BR srand () | |
50cbc42b | 138 | in the Linux C Library use the same random number generator as |
3a72373c | 139 | .BR random (3) |
60a90ecd | 140 | and |
3a72373c | 141 | .BR srandom (3), |
50cbc42b | 142 | so the lower-order bits should be as random as the higher-order bits. |
fea681da | 143 | However, on older |
63aa9df0 | 144 | .BR rand () |
fea681da MK |
145 | implementations, and on current implementations on different systems, |
146 | the lower-order bits are much less random than the higher-order bits. | |
147 | Do not use this function in applications intended to be portable | |
148 | when good randomness is needed. | |
a5ed7447 MK |
149 | (Use |
150 | .BR random (3) | |
151 | instead.) | |
4131356c AC |
152 | .SH STANDARDS |
153 | .TP | |
154 | .BR rand () | |
155 | .TQ | |
156 | .BR srand () | |
157 | C11, POSIX.1-2008. | |
158 | .TP | |
159 | .BR rand_r () | |
160 | POSIX.1-2008. | |
161 | .SH HISTORY | |
162 | .TP | |
163 | .BR rand () | |
164 | .TQ | |
165 | .BR srand () | |
166 | SVr4, 4.3BSD, C89, POSIX.1-2001. | |
167 | .TP | |
168 | .BR rand_r () | |
169 | POSIX.1-2001. | |
170 | Obsolete in POSIX.1-2008. | |
a14af333 | 171 | .SH EXAMPLES |
2b2581ee | 172 | POSIX.1-2001 gives the following example of an implementation of |
63aa9df0 | 173 | .BR rand () |
fea681da | 174 | and |
2b2581ee MK |
175 | .BR srand (), |
176 | possibly useful when one needs the same sequence on two different machines. | |
c6d039a3 | 177 | .P |
a6e2f128 | 178 | .in +4n |
bdd915e2 | 179 | .EX |
a6e2f128 | 180 | static unsigned long next = 1; |
fe5dba13 | 181 | \& |
a6e2f128 MK |
182 | /* RAND_MAX assumed to be 32767 */ |
183 | int myrand(void) { | |
184 | next = next * 1103515245 + 12345; | |
185 | return((unsigned)(next/65536) % 32768); | |
186 | } | |
fe5dba13 | 187 | \& |
85908442 | 188 | void mysrand(unsigned int seed) { |
a6e2f128 MK |
189 | next = seed; |
190 | } | |
bdd915e2 | 191 | .EE |
a6e2f128 | 192 | .in |
c6d039a3 | 193 | .P |
9750142b MK |
194 | The following program can be used to display the |
195 | pseudo-random sequence produced by | |
196 | .BR rand () | |
197 | when given a particular seed. | |
8341e8b6 AC |
198 | When the seed is |
199 | .IR \-1 , | |
200 | the program uses a random seed. | |
c6d039a3 | 201 | .P |
9750142b | 202 | .in +4n |
b0b6ab4e | 203 | .\" SRC BEGIN (rand.c) |
bdd915e2 | 204 | .EX |
9750142b | 205 | #include <stdio.h> |
ad3868f0 | 206 | #include <stdlib.h> |
fe5dba13 | 207 | \& |
9750142b MK |
208 | int |
209 | main(int argc, char *argv[]) | |
210 | { | |
b42296e4 AC |
211 | int r; |
212 | unsigned int seed, nloops; | |
fe5dba13 | 213 | \& |
9750142b | 214 | if (argc != 3) { |
d1a71985 | 215 | fprintf(stderr, "Usage: %s <seed> <nloops>\en", argv[0]); |
9750142b MK |
216 | exit(EXIT_FAILURE); |
217 | } | |
fe5dba13 | 218 | \& |
9750142b MK |
219 | seed = atoi(argv[1]); |
220 | nloops = atoi(argv[2]); | |
fe5dba13 | 221 | \& |
8341e8b6 AC |
222 | if (seed == \-1) { |
223 | seed = arc4random(); | |
224 | printf("seed: %u\en", seed); | |
225 | } | |
fe5dba13 | 226 | \& |
9750142b | 227 | srand(seed); |
b42296e4 | 228 | for (unsigned int j = 0; j < nloops; j++) { |
9750142b | 229 | r = rand(); |
d1a71985 | 230 | printf("%d\en", r); |
9750142b | 231 | } |
fe5dba13 | 232 | \& |
9750142b MK |
233 | exit(EXIT_SUCCESS); |
234 | } | |
b9c93deb | 235 | .EE |
b0b6ab4e | 236 | .\" SRC END |
9750142b | 237 | .in |
47297adb | 238 | .SH SEE ALSO |
fea681da MK |
239 | .BR drand48 (3), |
240 | .BR random (3) |