xref: /freebsd/lib/libc/gen/rand48.3 (revision ae83180158c4c937f170e31eff311b18c0286a93)
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.\"     @(#)rand48.3 V1.0 MB 8 Oct 1993
13.\" $FreeBSD$
14.\"
15.Dd October 8, 1993
16.Dt RAND48 3
17.Os
18.Sh NAME
19.Nm drand48 ,
20.Nm erand48 ,
21.Nm lrand48 ,
22.Nm nrand48 ,
23.Nm mrand48 ,
24.Nm jrand48 ,
25.Nm srand48 ,
26.Nm seed48 ,
27.Nm lcong48
28.Nd pseudo random number generators and initialization routines
29.Sh LIBRARY
30.Lb libc
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 "unsigned short *"
48.Fn seed48 "unsigned short xseed[3]"
49.Ft void
50.Fn lcong48 "unsigned short p[7]"
51.Sh DESCRIPTION
52The
53.Fn rand48
54family of functions generates pseudo-random numbers using a linear
55congruential algorithm working on integers 48 bits in size.
56The
57particular formula employed is
58r(n+1) = (a * r(n) + c) mod m
59where the default values are
60for the multiplicand a = 0xfdeece66d = 25214903917 and
61the addend c = 0xb = 11.
62The modulo is always fixed at m = 2 ** 48.
63r(n) is called the seed of the random number generator.
64.Pp
65For all the six generator routines described next, the first
66computational step is to perform a single iteration of the algorithm.
67.Pp
68.Fn drand48
69and
70.Fn erand48
71return values of type double.
72The full 48 bits of r(n+1) are
73loaded into the mantissa of the returned value, with the exponent set
74such that the values produced lie in the interval [0.0, 1.0).
75.Pp
76.Fn lrand48
77and
78.Fn nrand48
79return values of type long in the range
80[0, 2**31-1]. The high-order (31) bits of
81r(n+1) are loaded into the lower bits of the returned value, with
82the topmost (sign) bit set to zero.
83.Pp
84.Fn mrand48
85and
86.Fn jrand48
87return values of type long in the range
88[-2**31, 2**31-1]. The high-order (32) bits of
89r(n+1) are loaded into the returned value.
90.Pp
91.Fn drand48 ,
92.Fn lrand48 ,
93and
94.Fn mrand48
95use an internal buffer to store r(n). For these functions
96the initial value of r(0) = 0x1234abcd330e = 20017429951246.
97.Pp
98On the other hand,
99.Fn erand48 ,
100.Fn nrand48 ,
101and
102.Fn jrand48
103use a user-supplied buffer to store the seed r(n),
104which consists of an array of 3 shorts, where the zeroth member
105holds the least significant bits.
106.Pp
107All functions share the same multiplicand and addend.
108.Pp
109.Fn srand48
110is used to initialize the internal buffer r(n) of
111.Fn drand48 ,
112.Fn lrand48 ,
113and
114.Fn mrand48
115such that the 32 bits of the seed value are copied into the upper 32 bits
116of r(n), with the lower 16 bits of r(n) arbitrarily being set to 0x330e.
117Additionally, the constant multiplicand and addend of the algorithm are
118reset to the default values given above.
119.Pp
120.Fn seed48
121also initializes the internal buffer r(n) of
122.Fn drand48 ,
123.Fn lrand48 ,
124and
125.Fn mrand48 ,
126but here all 48 bits of the seed can be specified in an array of 3 shorts,
127where the zeroth member specifies the lowest bits.
128Again,
129the constant multiplicand and addend of the algorithm are
130reset to the default values given above.
131.Fn seed48
132returns a pointer to an array of 3 shorts which contains the old seed.
133This array is statically allocated, thus its contents are lost after
134each new call to
135.Fn seed48 .
136.Pp
137Finally,
138.Fn lcong48
139allows full control over the multiplicand and addend used in
140.Fn drand48 ,
141.Fn erand48 ,
142.Fn lrand48 ,
143.Fn nrand48 ,
144.Fn mrand48 ,
145and
146.Fn jrand48 ,
147and the seed used in
148.Fn drand48 ,
149.Fn lrand48 ,
150and
151.Fn mrand48 .
152An array of 7 shorts is passed as parameter; the first three shorts are
153used to initialize the seed; the second three are used to initialize the
154multiplicand; and the last short is used to initialize the addend.
155It is thus not possible to use values greater than 0xffff as the addend.
156.Pp
157Note that all three methods of seeding the random number generator
158always also set the multiplicand and addend for any of the six
159generator calls.
160.Pp
161For a more powerful random number generator, see
162.Xr random 3 .
163.Sh AUTHORS
164.An Martin Birgmeier
165.Sh SEE ALSO
166.Xr rand 3 ,
167.Xr random 3
168