xref: /freebsd/lib/libc/gen/rand48.3 (revision 7aa383846770374466b1dcb2cefd71bde9acf463)
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 February 2, 2010
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 = 0x5deece66d = 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
68The
69.Fn drand48
70and
71.Fn erand48
72functions
73return values of type double.
74The full 48 bits of r(n+1) are
75loaded into the mantissa of the returned value, with the exponent set
76such that the values produced lie in the interval [0.0, 1.0).
77.Pp
78The
79.Fn lrand48
80and
81.Fn nrand48
82functions
83return values of type long in the range
84[0, 2**31-1].
85The high-order (31) bits of
86r(n+1) are loaded into the lower bits of the returned value, with
87the topmost (sign) bit set to zero.
88.Pp
89The
90.Fn mrand48
91and
92.Fn jrand48
93functions
94return values of type long in the range
95[-2**31, 2**31-1].
96The high-order (32) bits of
97r(n+1) are loaded into the returned value.
98.Pp
99The
100.Fn drand48 ,
101.Fn lrand48 ,
102and
103.Fn mrand48
104functions
105use an internal buffer to store r(n).
106For these functions
107the initial value of r(0) = 0x1234abcd330e = 20017429951246.
108.Pp
109On the other hand,
110.Fn erand48 ,
111.Fn nrand48 ,
112and
113.Fn jrand48
114use a user-supplied buffer to store the seed r(n),
115which consists of an array of 3 shorts, where the zeroth member
116holds the least significant bits.
117.Pp
118All functions share the same multiplicand and addend.
119.Pp
120The
121.Fn srand48
122function
123is used to initialize the internal buffer r(n) of
124.Fn drand48 ,
125.Fn lrand48 ,
126and
127.Fn mrand48
128such that the 32 bits of the seed value are copied into the upper 32 bits
129of r(n), with the lower 16 bits of r(n) arbitrarily being set to 0x330e.
130Additionally, the constant multiplicand and addend of the algorithm are
131reset to the default values given above.
132.Pp
133The
134.Fn seed48
135function
136also initializes the internal buffer r(n) of
137.Fn drand48 ,
138.Fn lrand48 ,
139and
140.Fn mrand48 ,
141but here all 48 bits of the seed can be specified in an array of 3 shorts,
142where the zeroth member specifies the lowest bits.
143Again,
144the constant multiplicand and addend of the algorithm are
145reset to the default values given above.
146The
147.Fn seed48
148function
149returns a pointer to an array of 3 shorts which contains the old seed.
150This array is statically allocated, thus its contents are lost after
151each new call to
152.Fn seed48 .
153.Pp
154Finally,
155.Fn lcong48
156allows full control over the multiplicand and addend used in
157.Fn drand48 ,
158.Fn erand48 ,
159.Fn lrand48 ,
160.Fn nrand48 ,
161.Fn mrand48 ,
162and
163.Fn jrand48 ,
164and the seed used in
165.Fn drand48 ,
166.Fn lrand48 ,
167and
168.Fn mrand48 .
169An array of 7 shorts is passed as argument; the first three shorts are
170used to initialize the seed; the second three are used to initialize the
171multiplicand; and the last short is used to initialize the addend.
172It is thus not possible to use values greater than 0xffff as the addend.
173.Pp
174Note that all three methods of seeding the random number generator
175always also set the multiplicand and addend for any of the six
176generator calls.
177.Pp
178For a more powerful random number generator, see
179.Xr random 3 .
180.Sh SEE ALSO
181.Xr rand 3 ,
182.Xr random 3
183.Sh AUTHORS
184.An Martin Birgmeier
185