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