Debian Codegraph @

upstream/debian-trixie/man3/random.3

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