Debian Codegraph @

upstream/debian-unstable/man3/drand48.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 drand48 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48,
10 lcong48 \- generate uniformly distributed pseudo-random numbers
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <stdlib.h>
17 .P
18 .B double drand48(void);
19 .BI "double erand48(unsigned short " xsubi [3]);
20 .P
21 .B long lrand48(void);
22 .BI "long nrand48(unsigned short " xsubi [3]);
23 .P
24 .B long mrand48(void);
25 .BI "long jrand48(unsigned short " xsubi [3]);
26 .P
27 .BI "void srand48(long " seedval );
28 .BI "unsigned short *seed48(unsigned short " seed16v [3]);
29 .BI "void lcong48(unsigned short " param [7]);
30 .fi
31 .P
32 .RS -4
33 Feature Test Macro Requirements for glibc (see
34 .BR feature_test_macros (7)):
35 .RE
36 .P
37 All functions shown above:
38 .\" .BR drand48 (),
39 .\" .BR erand48 (),
40 .\" .BR lrand48 (),
41 .\" .BR nrand48 (),
42 .\" .BR mrand48 (),
43 .\" .BR jrand48 (),
44 .\" .BR srand48 (),
45 .\" .BR seed48 (),
46 .\" .BR lcong48 ():
47 .nf
48 _XOPEN_SOURCE
49 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
50 || /* glibc <= 2.19: */ _SVID_SOURCE
51 .fi
52 .SH DESCRIPTION
53 These functions generate pseudo-random numbers using the linear congruential
54 algorithm and 48-bit integer arithmetic.
55 .P
56 The
57 .BR drand48 ()
58 and
59 .BR erand48 ()
60 functions return nonnegative
61 double-precision floating-point values uniformly distributed over the interval
62 [0.0,\ 1.0).
63 .P
64 The
65 .BR lrand48 ()
66 and
67 .BR nrand48 ()
68 functions return nonnegative
69 long integers uniformly distributed over the interval [0,\ 2\[ha]31).
70 .P
71 The
72 .BR mrand48 ()
73 and
74 .BR jrand48 ()
75 functions return signed long
76 integers uniformly distributed over the interval [\-2\[ha]31,\ 2\[ha]31).
77 .P
78 The
79 .BR srand48 (),
80 .BR seed48 (),
81 and
82 .BR lcong48 ()
83 functions are
84 initialization functions, one of which should be called before using
85 .BR drand48 (),
86 .BR lrand48 (),
87 or
88 .BR mrand48 ().
89 The functions
90 .BR erand48 (),
91 .BR nrand48 (),
92 and
93 .BR jrand48 ()
94 do not require
95 an initialization function to be called first.
96 .P
97 All the functions work by generating a sequence of 48-bit integers,
98 .IR Xi ,
99 according to the linear congruential formula:
100 .P
101 .in +4n
102 .EX
103 .B Xn+1 = (aXn + c) mod m, where n >= 0
104 .EE
105 .in
106 .P
107 The parameter
108 .I m
109 = 2\[ha]48, hence 48-bit integer arithmetic is performed.
110 Unless
111 .BR lcong48 ()
112 is called,
113 .I a
114 and
115 .I c
116 are given by:
117 .P
118 .in +4n
119 .EX
120 .B a = 0x5DEECE66D
121 .B c = 0xB
122 .EE
123 .in
124 .P
125 The value returned by any of the functions
126 .BR drand48 (),
127 .BR erand48 (),
128 .BR lrand48 (),
129 .BR nrand48 (),
130 .BR mrand48 (),
131 or
132 .BR jrand48 ()
133 is
134 computed by first generating the next 48-bit
135 .I Xi
136 in the sequence.
137 Then the appropriate number of bits, according to the type of data item to
138 be returned, is copied from the high-order bits of
139 .I Xi
140 and transformed
141 into the returned value.
142 .P
143 The functions
144 .BR drand48 (),
145 .BR lrand48 (),
146 and
147 .BR mrand48 ()
148 store
149 the last 48-bit
150 .I Xi
151 generated in an internal buffer.
152 The functions
153 .BR erand48 (),
154 .BR nrand48 (),
155 and
156 .BR jrand48 ()
157 require the calling
158 program to provide storage for the successive
159 .I Xi
160 values in the array
161 argument
162 .IR xsubi .
163 The functions are initialized by placing the initial
164 value of
165 .I Xi
166 into the array before calling the function for the first
167 time.
168 .P
169 The initializer function
170 .BR srand48 ()
171 sets the high order 32-bits of
172 .I Xi
173 to the argument
174 .IR seedval .
175 The low order 16-bits are set
176 to the arbitrary value 0x330E.
177 .P
178 The initializer function
179 .BR seed48 ()
180 sets the value of
181 .I Xi
182 to
183 the 48-bit value specified in the array argument
184 .IR seed16v .
185 The
186 previous value of
187 .I Xi
188 is copied into an internal buffer and a
189 pointer to this buffer is returned by
190 .BR seed48 ().
191 .P
192 The initialization function
193 .BR lcong48 ()
194 allows the user to specify
195 initial values for
196 .IR Xi ,
197 .IR a ,
198 and
199 .IR c .
200 Array argument
201 elements
202 .I param[0\-2]
203 specify
204 .IR Xi ,
205 .I param[3\-5]
206 specify
207 .IR a ,
208 and
209 .I param[6]
210 specifies
211 .IR c .
212 After
213 .BR lcong48 ()
214 has been called, a subsequent call to either
215 .BR srand48 ()
216 or
217 .BR seed48 ()
218 will restore the standard values of
219 .I a
220 and
221 .IR c .
222 .SH ATTRIBUTES
223 For an explanation of the terms used in this section, see
224 .BR attributes (7).
225 .TS
226 allbox;
227 lbx lb lb
228 l l l.
229 Interface Attribute Value
230 T{
231 .na
232 .nh
233 .BR drand48 (),
234 .BR erand48 (),
235 .BR lrand48 (),
236 .BR nrand48 (),
237 .BR mrand48 (),
238 .BR jrand48 (),
239 .BR srand48 (),
240 .BR seed48 (),
241 .BR lcong48 ()
242 T} Thread safety T{
243 .na
244 .nh
245 MT-Unsafe race:drand48
246 T}
247 .TE
248 .P
249 The above
250 functions record global state information for the random number generator,
251 so they are not thread-safe.
252 .SH STANDARDS
253 POSIX.1-2008.
254 .SH HISTORY
255 POSIX.1-2001, SVr4.
256 .SH SEE ALSO
257 .BR rand (3),
258 .BR random (3)