sequences
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <stdlib.h>
double drand48 ( void );
int drand48_r (
DRAND48 *dp,
double *randval );
double erand48 (
unsigned short xsubi[3] );
int erand48_r (
unsigned short xsubi[3],
DRAND48 *dp,
double *randval );
long jrand48 (
unsigned short xsubi[3] );
int jrand48_r (
unsigned short xsubi[3],
DRAND48 *dp,
long *randval );
void lcong48 (
unsigned short param[7] );
int lcong48_r (
unsigned short param[7],
DRAND48 *dp );
long lrand48 ( void );
int lrand48_r (
DRAND48 *dp,
long *randval );
long mrand48 ( void );
int mrand48_r (
DRAND48 *dp,
long *randval );
long nrand48 (
unsigned short xsubi[3] );
int nrand48_r (
unsigned short xsubi[3],
DRAND48 *dp,
long *randval );
unsigned short *seed48 (
unsigned short seed_16v[3] );
int *seed48_r (
unsigned short seed_16v[3],
DRAND48 *dp );
void srand48 (
long seed_val);
int srand48_r (
long seed_val,
DRAND48 *dp );
PARAMETERS
xsubi Specifies an array of three shorts, which, when
concatenated together, form a 48-bit integer.
seed_val Specifies the initialization value to begin ran-
domization. Changing this value changes the ran-
domization pattern.
seed_16v Specifies another seed value; an array of three
unsigned shorts that form a 48-bit seed value.
param Specifies an array specifying the initial $X sub
i $, the multiplier value a, and the addend value
c.
dp Points at the DRAND48D structure which contains
parameters for these routines.
randval Points at the returned nonnegative pseudo-random
numbers.
DESCRIPTION
This family of functions generates pseudo-random numbers
using the linear congruential algorithm and 48-bit integer
arithmetic.
The drand48() and erand48() functions return nonnegative,
double-precision, floating-point values uniformly distri-
buted over the range of y values such that 0 < y < 1.0.
The lrand48() and nrand48() functions return nonnegative
long integers uniformly distributed over the range of y
values such that 0 < y < 231.
The mrand48() and jrand48() functions return signed long
integers uniformly distributed over the range of y values
such that -231 < y < 231.
The srand48(), seed48(), and lcong48() functions initialize
the random-number generator. Programs should invoke one of
them before calling the drand48(), lrand48(), or the
mrand48() functions. (Although it is not recommended prac-
tice, constant default initializer values are supplied
automatically if the drand48(), lrand48(), or mrand48()
functions are called without first calling an initialization
function.) The erand48(), nrand48(), and jrand48() functions
do not require that an initialization function be called
first.
All the functions work by generating a sequence of 48-bit
integer values, $X sub i $, according to the linear
congruential formula:
$X sub{n+1}~=~(aX sub n^+^c) sub{roman mod~m}~~~~~~~~n>=~0$
The parameter m equals $2 sup 48$; hence 48-bit integer
arithmetic is performed. Unless lcong48() has been invoked,
the multiplier value $a$ and the addend value $c$ are given
by
$a~mark =~roman "5DEECE66D"^sub 16~=~roman
273673163155^sub 8$
$c~lineup =~roman B^sub 16~=~roman 13^sub 8 $
The values returned by the drand48(), erand48(), lrand48(),
nrand48(), mrand48(), and jrand48() functions are computed
by first generating the next 48-bit $X sub i $ in the
sequence. Then the appropriate number of bits, according to
the type of data item to be returned, are copied from the
high-order (most significant) bits of $X sub i $ and
transformed into the returned value.
The drand48(), lrand48(), and mrand48() functions store the
last 48-bit $X sub i $ generated into an internal buffer,
which is why they must be initialized prior to being
invoked.
The erand48(), nrand48(), and jrand48() functions require
that the calling program provide storage for the successive
$X sub i $ values in the array pointed to by the xsubi
parameter. This is why these routines do not have to be
initialized; the calling program merely has to place the
desired initial value of $X sub i $ into the array and pass
it as a parameter.
By using different parameters, the erand48(), nrand48(), and
jrand48() functions allow separate modules of a large pro-
gram to generate several independent sequences of pseudo-
random numbers, that is, the sequence of numbers that one
module generates does not depend upon how many times the
functions are called by other modules.
The initializer function srand48() sets the high-order 32
bits of $X sub i $ to the LONG_BIT bits contained in its
parameter. The low order 16 bits of $X sub i $ are set to
the arbitrary value $roman 330E sub 16 .$
The initializer function seed48() sets the value of $X sub i
$ to the 48-bit value specified in the array pointed to by
the seed_16v parameter. In addition, seed48() returns a
pointer to a 48-bit internal buffer that contains the previ-
ous value of $X sub i $ that is used only by seed48(). The
returned pointer allows you to restart the pseudo-random
sequence at a given point. Use the pointer to copy the pre-
vious $X sub i $ value into a temporary array. To resume
where the original sequence left off, you can call seed48()
with a pointer to this array.
The lcong48() function specifies the initial $X sub i $
value, the multiplier value a, and the addend value c. The
param array elements param[0-2] specify $X sub i $,
param[3-5] specify the multiplier a, and param[6] specifies
the 16-bit addend c. After lcong48() has been called, a
subsequent call to either srand48() or seed48() restores the
standard a and c as specified previously.
The drand48_r(), erand48_r(), lrand48_r(), nrand48_r(),
mrand48_r(), jrand48_r(), srand48_r(), seed48_r(), and
lcong48_r() functions are the reentrant versions of
drand48(), erand48(), lrand48(), nrand48(), mrand48(),
jrand48(), srand48(), seed48(), and lcong48(), respectively.
NOTES
Note, however, that the 48-bit internal buffer that used to
be returned by the seed48() function is now placed in the
DRAND48D structure in the lastx field by the seed48_r()
function.
AES Support Level:
Trial use
RETURN VALUES
The drand48() and erand48() functions return nonnegative,
double-precision, floating-point values. The lrand48() and
nrand48() functions return signed long integers uniformly
distributed over the range 0 < y < 231. The mrand48() and
jrand48() functions return signed long integers uniformly
distributed over the range -231 < y < 231.
The seed48() function returns a pointer to a 48-bit internal
buffer.
The lcong48() and srand48() functions do not return a value.
Upon success, both drand48_r() and erand48_r() functions
have randval point at the returned double value, and return
a 0 (zero). Upon success, both mrand48_r() and jrand48_r()
functions have randval at the returned long value, and
return a 0 (zero). Upon success, the lcong48_r(),
seed48_r(), and srand48_r() return 0 (zero). The
lrand48_r() and rand48_r() functions have randval point at
the returned long value, and return a 0 (zero). Upon error,
the reentrant functions return -1 and may set errno to
[EFAULT].
ERRORS
Upon error, the drand48_r(), erand48_r(), lrand48_r(),
nrand48_r(), mrand48_r(), jrand48_r(), srand48_r(),
seed48_r(), and lcong48_r() functions return -1 and errno
may be set to the following value.
[EFAULT] The dp and/or randval value is NULL.
RELATED INFORMATION
Functions: rand(3), random(3) delim off
Acknowledgement and Disclaimer