Debian Codegraph @

upstream/debian-unstable/man3/rand.3

raw
1 '\" t
2 .\" Copyright 1993, David Metcalfe <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH rand 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 rand, rand_r, srand \- pseudo-random number generator
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <stdlib.h>
16 .P
17 .B int rand(void);
18 .BI "void srand(unsigned int " seed );
19 .P
20 .BI "[[deprecated]] int rand_r(unsigned int *" seedp );
21 .fi
22 .P
23 .RS -4
24 Feature Test Macro Requirements for glibc (see
25 .BR feature_test_macros (7)):
26 .RE
27 .P
28 .BR rand_r ():
29 .nf
30 Since glibc 2.24:
31 _POSIX_C_SOURCE >= 199506L
32 glibc 2.23 and earlier
33 _POSIX_C_SOURCE
34 .fi
35 .SH DESCRIPTION
36 The
37 .BR rand ()
38 function returns a pseudo-random integer in the range 0 to
39 .B RAND_MAX
40 inclusive (i.e., the mathematical range
41 .RB [ 0 ,\~ RAND_MAX ]).
42 .P
43 The
44 .BR srand ()
45 function sets its argument as the seed for a new
46 sequence of pseudo-random integers to be returned by
47 .BR rand ().
48 These sequences are repeatable by calling
49 .BR srand ()
50 with the same seed value.
51 .P
52 If no seed value is provided, the
53 .BR rand ()
54 function is automatically seeded with a value of 1.
55 .P
56 The function
57 .BR rand ()
58 is not reentrant, since it
59 uses hidden state that is modified on each call.
60 This might just be the seed value to be used by the next call,
61 or it might be something more elaborate.
62 In order to get reproducible behavior in a threaded
63 application, this state must be made explicit;
64 this can be done using the reentrant function
65 .BR rand_r ().
66 .P
67 Like
68 .BR rand (),
69 .BR rand_r ()
70 returns a pseudo-random integer in the range
71 .RB [ 0 ,\~ RAND_MAX ].
72 The
73 .I seedp
74 argument is a pointer to an
75 .I unsigned int
76 that is used to store state between calls.
77 If
78 .BR rand_r ()
79 is called with the same initial value for the integer pointed to by
80 .IR seedp ,
81 and that value is not modified between calls,
82 then the same pseudo-random sequence will result.
83 .P
84 The value pointed to by the
85 .I seedp
86 argument of
87 .BR rand_r ()
88 provides only a very small amount of state,
89 so this function will be a weak pseudo-random generator.
90 Try
91 .BR drand48_r (3)
92 instead.
93 .SH RETURN VALUE
94 The
95 .BR rand ()
96 and
97 .BR rand_r ()
98 functions return a value between 0 and
99 .B RAND_MAX
100 (inclusive).
101 The
102 .BR srand ()
103 function returns no value.
104 .SH ATTRIBUTES
105 For an explanation of the terms used in this section, see
106 .BR attributes (7).
107 .TS
108 allbox;
109 lbx lb lb
110 l l l.
111 Interface Attribute Value
112 T{
113 .na
114 .nh
115 .BR rand (),
116 .BR rand_r (),
117 .BR srand ()
118 T} Thread safety MT-Safe
119 .TE
120 .SH VERSIONS
121 The versions of
122 .BR rand ()
123 and
124 .BR srand ()
125 in the Linux C Library use the same random number generator as
126 .BR random (3)
127 and
128 .BR srandom (3),
129 so the lower-order bits should be as random as the higher-order bits.
130 However, on older
131 .BR rand ()
132 implementations, and on current implementations on different systems,
133 the lower-order bits are much less random than the higher-order bits.
134 Do not use this function in applications intended to be portable
135 when good randomness is needed.
136 (Use
137 .BR random (3)
138 instead.)
139 .SH STANDARDS
140 .TP
141 .BR rand ()
142 .TQ
143 .BR srand ()
144 C11, POSIX.1-2008.
145 .TP
146 .BR rand_r ()
147 POSIX.1-2008.
148 .SH HISTORY
149 .TP
150 .BR rand ()
151 .TQ
152 .BR srand ()
153 SVr4, 4.3BSD, C89, POSIX.1-2001.
154 .TP
155 .BR rand_r ()
156 POSIX.1-2001.
157 Obsolete in POSIX.1-2008.
158 .SH EXAMPLES
159 POSIX.1-2001 gives the following example of an implementation of
160 .BR rand ()
161 and
162 .BR srand (),
163 possibly useful when one needs the same sequence on two different machines.
164 .P
165 .in +4n
166 .EX
167 static unsigned long next = 1;
168 \&
169 /* RAND_MAX assumed to be 32767 */
170 int myrand(void) {
171 next = next * 1103515245 + 12345;
172 return((unsigned) (next/65536) % 32768);
173 }
174 \&
175 void mysrand(unsigned int seed) {
176 next = seed;
177 }
178 .EE
179 .in
180 .P
181 The following program can be used to display the
182 pseudo-random sequence produced by
183 .BR rand ()
184 when given a particular seed.
185 When the seed is
186 .IR \-1 ,
187 the program uses a random seed.
188 .P
189 .in +4n
190 .\" SRC BEGIN (rand.c)
191 .EX
192 #include <stdio.h>
193 #include <stdlib.h>
194 \&
195 int
196 main(int argc, char *argv[])
197 {
198 int r;
199 unsigned int seed, nloops;
200 \&
201 if (argc != 3) {
202 fprintf(stderr, "Usage: %s <seed> <nloops>\[rs]n", argv[0]);
203 exit(EXIT_FAILURE);
204 }
205 \&
206 seed = atoi(argv[1]);
207 nloops = atoi(argv[2]);
208 \&
209 if (seed == \-1) {
210 seed = arc4random();
211 printf("seed: %u\[rs]n", seed);
212 }
213 \&
214 srand(seed);
215 for (unsigned int j = 0; j < nloops; j++) {
216 r = rand();
217 printf("%d\[rs]n", r);
218 }
219 \&
220 exit(EXIT_SUCCESS);
221 }
222 .EE
223 .\" SRC END
224 .in
225 .SH SEE ALSO
226 .BR drand48 (3),
227 .BR random (3)