Debian Codegraph @

upstream/debian-unstable/man3/random.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 random 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 random, srandom, initstate, setstate \- 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 long random(void);
18 .BI "void srandom(unsigned int " seed );
19 .P
20 .BR "char *initstate(" "size_t n;"
21 .BI " unsigned int " seed ", char " state [ n "], size_t " n );
22 .BI "char *setstate(char *" state );
23 .fi
24 .P
25 .RS -4
26 Feature Test Macro Requirements for glibc (see
27 .BR feature_test_macros (7)):
28 .RE
29 .P
30 .BR random (),
31 .BR srandom (),
32 .BR initstate (),
33 .BR setstate ():
34 .nf
35 _XOPEN_SOURCE >= 500
36 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
37 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
38 || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
39 .fi
40 .SH DESCRIPTION
41 The
42 .BR random ()
43 function uses a nonlinear additive feedback random
44 number generator employing a default table of size 31 long integers to
45 return successive pseudo-random numbers in
46 the range from 0 to 2\[ha]31\ \-\ 1.
47 The period of this random number generator is very large, approximately
48 .IR "16\ *\ ((2\[ha]31)\ \-\ 1)" .
49 .P
50 The
51 .BR srandom ()
52 function sets its argument as the seed for a new
53 sequence of pseudo-random integers to be returned by
54 .BR random ().
55 These sequences are repeatable by calling
56 .BR srandom ()
57 with the same
58 seed value.
59 If no seed value is provided, the
60 .BR random ()
61 function
62 is automatically seeded with a value of 1.
63 .P
64 The
65 .BR initstate ()
66 function allows a state array
67 .I state
68 to
69 be initialized for use by
70 .BR random ().
71 The size of the state array
72 .I n
73 is used by
74 .BR initstate ()
75 to decide how sophisticated a
76 random number generator it should use\[em]the larger the state array,
77 the better the random numbers will be.
78 Current "optimal" values for the size of the state array
79 .I n
80 are
81 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to
82 the nearest known amount.
83 Using less than 8 bytes results in an error.
84 .I seed
85 is the seed for the initialization,
86 which specifies a starting point for the random number
87 sequence, and provides for restarting at the same point.
88 .P
89 The
90 .BR setstate ()
91 function changes the state array used by the
92 .BR random ()
93 function.
94 The state array
95 .I state
96 is used for
97 random number generation until the next call to
98 .BR initstate ()
99 or
100 .BR setstate ().
101 .I state
102 must first have been initialized
103 using
104 .BR initstate ()
105 or be the result of a previous call of
106 .BR setstate ().
107 .SH RETURN VALUE
108 The
109 .BR random ()
110 function returns a value between 0 and
111 .IR "(2\[ha]31)\ \-\ 1" .
112 The
113 .BR srandom ()
114 function returns no value.
115 .P
116 The
117 .BR initstate ()
118 function returns a pointer to the previous state array.
119 On failure, it returns NULL, and
120 .I errno
121 is set to indicate the error.
122 .P
123 On success,
124 .BR setstate ()
125 returns a pointer to the previous state array.
126 On failure, it returns NULL, and
127 .I errno
128 is set to indicate the error.
129 .SH ERRORS
130 .TP
131 .B EINVAL
132 The
133 .I state
134 argument given to
135 .BR setstate ()
136 was NULL.
137 .TP
138 .B EINVAL
139 A state array of less than 8 bytes was specified to
140 .BR initstate ().
141 .SH ATTRIBUTES
142 For an explanation of the terms used in this section, see
143 .BR attributes (7).
144 .TS
145 allbox;
146 lbx lb lb
147 l l l.
148 Interface Attribute Value
149 T{
150 .na
151 .nh
152 .BR random (),
153 .BR srandom (),
154 .BR initstate (),
155 .BR setstate ()
156 T} Thread safety MT-Safe
157 .TE
158 .SH STANDARDS
159 POSIX.1-2008.
160 .SH HISTORY
161 POSIX.1-2001, 4.3BSD.
162 .SH NOTES
163 Random-number generation is a complex topic.
164 .I Numerical Recipes in C: The Art of Scientific Computing
165 (William H.\& Press, Brian P.\& Flannery, Saul A.\& Teukolsky,
166 William T.\& Vetterling; New York: Cambridge University Press, 2007, 3rd ed.)
167 provides an excellent discussion of practical random-number generation
168 issues in Chapter 7 (Random Numbers).
169 .P
170 For a more theoretical discussion which also covers many practical issues
171 in depth, see Chapter 3 (Random Numbers) in Donald E.\& Knuth's
172 .IR "The Art of Computer Programming" ,
173 volume 2 (Seminumerical Algorithms), 2nd ed.; Reading, Massachusetts:
174 Addison-Wesley Publishing Company, 1981.
175 .SH CAVEATS
176 The
177 .BR random ()
178 function should not be used in multithreaded programs
179 where reproducible behavior is required.
180 Use
181 .BR random_r (3)
182 for that purpose.
183 .SH BUGS
184 According to POSIX,
185 .BR initstate ()
186 should return NULL on error.
187 In the glibc implementation,
188 .I errno
189 is (as specified) set on error, but the function does not return NULL.
190 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=15380
191 .SH SEE ALSO
192 .BR getrandom (2),
193 .BR drand48 (3),
194 .BR rand (3),
195 .BR random_r (3),
196 .BR srand (3)