summaryrefslogtreecommitdiff
path: root/src/lib/libc/stdlib/rand48.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libc/stdlib/rand48.3')
-rw-r--r--src/lib/libc/stdlib/rand48.3240
1 files changed, 0 insertions, 240 deletions
diff --git a/src/lib/libc/stdlib/rand48.3 b/src/lib/libc/stdlib/rand48.3
deleted file mode 100644
index fa7a7179bc..0000000000
--- a/src/lib/libc/stdlib/rand48.3
+++ /dev/null
@@ -1,240 +0,0 @@
1.\" Copyright (c) 1993 Martin Birgmeier
2.\" All rights reserved.
3.\"
4.\" You may redistribute unmodified or modified versions of this source
5.\" code provided that the above copyright notice and this and the
6.\" following conditions are retained.
7.\"
8.\" This software is provided ``as is'', and comes with no warranties
9.\" of any kind. I shall in no event be liable for anything that happens
10.\" to anyone/anything when using this software.
11.\"
12.\" $OpenBSD: rand48.3,v 1.21 2019/12/20 19:16:40 tb Exp $
13.\"
14.Dd $Mdocdate: December 20 2019 $
15.Dt DRAND48 3
16.Os
17.Sh NAME
18.Nm drand48 ,
19.Nm erand48 ,
20.Nm lrand48 ,
21.Nm nrand48 ,
22.Nm mrand48 ,
23.Nm jrand48 ,
24.Nm srand48 ,
25.Nm srand48_deterministic ,
26.Nm seed48 ,
27.Nm seed48_deterministic ,
28.Nm lcong48 ,
29.Nm lcong48_deterministic
30.Nd pseudo-random number generators and initialization routines
31.Sh SYNOPSIS
32.In stdlib.h
33.Ft double
34.Fn drand48 void
35.Ft double
36.Fn erand48 "unsigned short xseed[3]"
37.Ft long
38.Fn lrand48 void
39.Ft long
40.Fn nrand48 "unsigned short xseed[3]"
41.Ft long
42.Fn mrand48 void
43.Ft long
44.Fn jrand48 "unsigned short xseed[3]"
45.Ft void
46.Fn srand48 "long seed"
47.Ft void
48.Fn srand48_deterministic "long seed"
49.Ft "unsigned short *"
50.Fn seed48 "unsigned short xseed[3]"
51.Ft "unsigned short *"
52.Fn seed48_deterministic "unsigned short xseed[3]"
53.Ft void
54.Fn lcong48 "unsigned short p[7]"
55.Ft void
56.Fn lcong48_deterministic "unsigned short p[7]"
57.Sh DESCRIPTION
58.Bf -symbolic
59Standards insist that this interface return deterministic results.
60Unsafe usage is very common, so
61.Ox
62changed the subsystem to return non-deterministic results by default.
63.Ef
64.Pp
65To satisfy portable code,
66.Fn srand48 ,
67.Fn seed48 ,
68or
69.Fn lcong48
70should be called to initialize the subsystem.
71In
72.Ox
73the
74seeding parameters are ignored, and strong random number results will be
75provided from
76.Xr arc4random 3 .
77In other systems, the
78parameters prime a simplistic deterministic algorithm.
79.Pp
80If the standardized behavior is required then
81.Fn srand48_deterministic ,
82.Fn seed48_deterministic ,
83and
84.Fn lcong48_deterministic
85can be substituted for
86.Fn srand48 ,
87.Fn seed48 ,
88and
89.Fn lcong48 .
90That will cause subsequent
91calls to
92.Fn drand48 ,
93.Fn lrand48 ,
94and
95.Fn jrand48
96to return results using the deterministic algorithm.
97.Pp
98.Fn drand48
99and
100.Fn erand48
101return values of type double.
102The full 48 bits of r(n+1) are
103loaded into the mantissa of the returned value, with the exponent set
104such that the values produced lie in the interval [0.0, 1.0).
105.Pp
106.Fn lrand48
107and
108.Fn nrand48
109return values of type long in the range
110[0, 2**31-1].
111The high-order (31) bits of
112r(n+1) are loaded into the lower bits of the returned value, with
113the topmost (sign) bit set to zero.
114.Pp
115.Fn mrand48
116and
117.Fn jrand48
118return values of type long in the range
119[-2**31, 2**31-1].
120The high-order (32) bits of r(n+1) are loaded into the returned value.
121.Pp
122In the deterministic mode, the
123.Fn rand48
124family of functions generates numbers using a linear congruential
125algorithm working on integers 48 bits in size.
126The particular formula employed is
127r(n+1) = (a * r(n) + c) mod m
128where the default values are
129for the multiplicand a = 0xfdeece66d = 25214903917 and
130the addend c = 0xb = 11.
131The modulus is always fixed at m = 2 ** 48.
132r(n) is called the seed of the random number generator.
133.Pp
134For all the six generator routines described next, the first
135computational step is to perform a single iteration of the algorithm.
136.Pp
137.Fn drand48 ,
138.Fn lrand48 ,
139and
140.Fn mrand48
141use an internal buffer to store r(n).
142For these functions
143the initial value of r(0) = 0x1234abcd330e = 20017429951246.
144.Pp
145On the other hand,
146.Fn erand48 ,
147.Fn nrand48 ,
148and
149.Fn jrand48
150use a user-supplied buffer to store the seed r(n),
151which consists of an array of 3 shorts, where the zeroth member
152holds the least significant bits.
153.Pp
154All functions share the same multiplicand and addend.
155.Pp
156.Fn srand48_deterministic
157is used to initialize the internal buffer r(n) of
158.Fn drand48 ,
159.Fn lrand48 ,
160and
161.Fn mrand48
162such that the 32 bits of the seed value are copied into the upper 32 bits
163of r(n), with the lower 16 bits of r(n) arbitrarily being set to 0x330e.
164Additionally, the constant multiplicand and addend of the algorithm are
165reset to the default values given above.
166.Pp
167.Fn seed48_deterministic
168also initializes the internal buffer r(n) of
169.Fn drand48 ,
170.Fn lrand48 ,
171and
172.Fn mrand48 ,
173but here all 48 bits of the seed can be specified in an array of 3 shorts,
174where the zeroth member specifies the lowest bits.
175Again, the constant multiplicand and addend of the algorithm are
176reset to the default values given above.
177.Fn seed48_deterministic
178returns a pointer to an array of 3 shorts which contains the old seed.
179This array is statically allocated, so its contents are lost after
180each new call to
181.Fn seed48_deterministic .
182.Pp
183Finally,
184.Fn lcong48_deterministic
185allows full control over the multiplicand and addend used in
186.Fn drand48 ,
187.Fn erand48 ,
188.Fn lrand48 ,
189.Fn nrand48 ,
190.Fn mrand48 ,
191and
192.Fn jrand48 ,
193and the seed used in
194.Fn drand48 ,
195.Fn lrand48 ,
196and
197.Fn mrand48 .
198An array of 7 shorts is passed as parameter; the first three shorts are
199used to initialize the seed; the second three are used to initialize the
200multiplicand; and the last short is used to initialize the addend.
201It is thus not possible to use values greater than 0xffff as the addend.
202.Pp
203Note that all three methods of seeding the random number generator
204always also set the multiplicand and addend for any of the six
205generator calls.
206.Sh SEE ALSO
207.Xr arc4random 3 ,
208.Xr rand 3 ,
209.Xr random 3
210.Sh STANDARDS
211The
212.Fn drand48 ,
213.Fn erand48 ,
214.Fn jrand48 ,
215.Fn lrand48 ,
216.Fn mrand48 ,
217and
218.Fn nrand48 ,
219functions conform to
220.St -p1003.1-2008 .
221.Pp
222The
223.Fn seed48 ,
224.Fn srand48 ,
225and
226.Fn lcong48
227function do not conform to
228.St -ansiC ,
229intentionally.
230.Pp
231The
232.Fn seed48_deterministic ,
233.Fn srand48_deterministic ,
234and
235.Fn lcong48_deterministic
236functions are
237.Ox
238extensions.
239.Sh AUTHORS
240.An Martin Birgmeier