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