Debian Codegraph @

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