Debian Codegraph @

upstream/debian-unstable/man3/random_r.3

raw
1 '\" t
2 .\" Copyright 2008, Michael Kerrisk <[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_r 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 random_r, srandom_r, initstate_r, setstate_r \- reentrant
10 random number generator
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <stdlib.h>
17 .P
18 .BI "int random_r(struct random_data *restrict " buf ,
19 .BI " int32_t *restrict " result );
20 .BI "int srandom_r(unsigned int " seed ", struct random_data *" buf );
21 .P
22 .BI "int initstate_r(unsigned int " seed ,
23 .BI " char " statebuf "[restrict ." statelen "], size_t " statelen ,
24 .BI " struct random_data *restrict " buf );
25 .BI "int setstate_r(char *restrict " statebuf ,
26 .BI " struct random_data *restrict " buf );
27 .fi
28 .P
29 .RS -4
30 Feature Test Macro Requirements for glibc (see
31 .BR feature_test_macros (7)):
32 .RE
33 .P
34 .BR random_r (),
35 .BR srandom_r (),
36 .BR initstate_r (),
37 .BR setstate_r ():
38 .nf
39 /* glibc >= 2.19: */ _DEFAULT_SOURCE
40 || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
41 .fi
42 .SH DESCRIPTION
43 These functions are the reentrant equivalents
44 of the functions described in
45 .BR random (3).
46 They are suitable for use in multithreaded programs where each thread
47 needs to obtain an independent, reproducible sequence of random numbers.
48 .P
49 The
50 .BR random_r ()
51 function is like
52 .BR random (3),
53 except that instead of using state information maintained
54 in a global variable,
55 it uses the state information in the argument pointed to by
56 .IR buf ,
57 which must have been previously initialized by
58 .BR initstate_r ().
59 The generated random number is returned in the argument
60 .IR result .
61 .P
62 The
63 .BR srandom_r ()
64 function is like
65 .BR srandom (3),
66 except that it initializes the seed for the random number generator
67 whose state is maintained in the object pointed to by
68 .IR buf ,
69 which must have been previously initialized by
70 .BR initstate_r (),
71 instead of the seed associated with the global state variable.
72 .P
73 The
74 .BR initstate_r ()
75 function is like
76 .BR initstate (3),
77 except that it initializes the state in the object pointed to by
78 .IR buf ,
79 rather than initializing the global state variable.
80 Before calling this function, the
81 .I buf.state
82 field must be initialized to NULL.
83 The
84 .BR initstate_r ()
85 function records a pointer to the
86 .I statebuf
87 argument inside the structure pointed to by
88 .IR buf .
89 Thus,
90 .I statebuf
91 should not be deallocated so long as
92 .I buf
93 is still in use.
94 (So,
95 .I statebuf
96 should typically be allocated as a static variable,
97 or allocated on the heap using
98 .BR malloc (3)
99 or similar.)
100 .P
101 The
102 .BR setstate_r ()
103 function is like
104 .BR setstate (3),
105 except that it modifies the state in the object pointed to by
106 .IR buf ,
107 rather than modifying the global state variable.
108 .I state
109 must first have been initialized
110 using
111 .BR initstate_r ()
112 or be the result of a previous call of
113 .BR setstate_r ().
114 .SH RETURN VALUE
115 All of these functions return 0 on success.
116 On error, \-1 is returned, with
117 .I errno
118 set to indicate the error.
119 .SH ERRORS
120 .TP
121 .B EINVAL
122 A state array of less than 8 bytes was specified to
123 .BR initstate_r ().
124 .TP
125 .B EINVAL
126 The
127 .I statebuf
128 or
129 .I buf
130 argument to
131 .BR setstate_r ()
132 was NULL.
133 .TP
134 .B EINVAL
135 The
136 .I buf
137 or
138 .I result
139 argument to
140 .BR random_r ()
141 was NULL.
142 .SH ATTRIBUTES
143 For an explanation of the terms used in this section, see
144 .BR attributes (7).
145 .TS
146 allbox;
147 lbx lb lb
148 l l l.
149 Interface Attribute Value
150 T{
151 .na
152 .nh
153 .BR random_r (),
154 .BR srandom_r (),
155 .BR initstate_r (),
156 .BR setstate_r ()
157 T} Thread safety MT-Safe race:buf
158 .TE
159 .SH STANDARDS
160 GNU.
161 .\" These functions appear to be on Tru64, but don't seem to be on
162 .\" Solaris, HP-UX, or FreeBSD.
163 .SH BUGS
164 The
165 .BR initstate_r ()
166 interface is confusing.
167 .\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=3662
168 It appears that the
169 .I random_data
170 type is intended to be opaque,
171 but the implementation requires the user to either initialize the
172 .I buf.state
173 field to NULL or zero out the entire structure before the call.
174 .SH SEE ALSO
175 .BR drand48 (3),
176 .BR rand (3),
177 .BR random (3)