 |
Index for
Section 3 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
drand48(3)
NAME
drand48, drand48_r, erand48, erand48_r, jrand48, jrand48_r, lcong48,
lcong48_r, lrand48, lrand48_r, mrand48, mrand48_r, nrand48, nrand48_r,
seed48, seed48_r, srand48, srand48_r - Generate uniformly distributed
pseudorandom number sequences
SYNOPSIS
#include <stdlib.h>
double drand48(
void );
int drand48_r(
struct drand48_data *dp,
double *randval );
double erand48(
unsigned short xsubi[3] );
int erand48_r(
unsigned short xsubi[3],
struct drand48_data *dp,
double *randval );
long jrand48(
unsigned short xsubi[3] );
int jrand48_r(
unsigned short xsubi[3],
struct drand48_data *dp,
double *randval );
void lcong48(
unsigned short param[7] );
int lcong48_r(
unsigned short param[7],
struct drand48_data *dp );
long lrand48(
void );
int lrand48_r(
struct drand48_data *dp,
long *randval );
long mrand48(
void );
int mrand48_r(
struct drand48_data *dp,
long *randval );
long nrand48(
unsigned short xsubi[3] );
long nrand48_r(
unsigned short xsubi[3],
struct drand48_data *dp,
long *randval );
unsigned short *seed48(
unsigned short seed_16v[3] );
int *seed48_r(
unsigned short seed_16v[3],
struct drand48_data *dp );
void srand48(
long seed_val );
int srand48_r(
long seed_val,
struct drand48_data *dp );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
drand48(), erand48(), jrand48(), lcong48(), lrand48(), mrand48(),
nrand48(), seed48(), srand48(): XPG4, XPG4-UNIX
drand48_r(), erand48_r(), jrand48_r(), lcong48_r(), lrand48_r(),
mrand48_r(), nrand48_r(), seed48_r(), srand48_r(): POSIX.1c
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
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 randomization. Changing
this value changes the randomization pattern.
seed_16v
Specifies another seed value; an array of three unsigned shorts that
form a 48-bit seed value.
param
Specifies an array that in turn specifies the initial X[i], the
multiplier value a, and the addend value c.
dp [POSIX] Points to a structure which contains data for the reentrant
routines.
randval
[POSIX] Points at the returned nonnegative pseudorandom numbers.
DESCRIPTION
This family of functions generates pseudorandom numbers using the linear
congruential algorithm and 48-bit integer arithmetic.
The drand48() and erand48() functions return nonnegative, double-precision,
floating-point values uniformly distributed 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 < 2^31.
The mrand48() and jrand48() functions return signed long integers uniformly
distributed over the range of y values such that -2^31<= y < 2^31.
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 practice, 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[i], according to the linear congruential formula:
X[n + 1] = (aX[n] + c)[mod m] n>= 0
The parameter m equals 2^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 = 5DEECE66D (hex) = 273673163155 (octal)
c = B (hex) = 13 (octal)
The values returned by the drand48(), erand48(), lrand48(), nrand48(),
mrand48(), and jrand48() functions are computed by first generating the
next 48-bit X[i] in the sequence. Then the appropriate bits, according to
the type of data item to be returned, are copied from the high-order
(most-significant) bits of X[i] and transformed into the returned value.
The drand48(), lrand48(), and mrand48() functions store the last 48-bit
X[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[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[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 program to generate several
independent sequences of pseudorandom 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[i] to
the LONG_BIT bits contained in its parameter. The low-order 16 bits of X[i]
are set to the arbitrary hexadecimal value 330E.
The initializer function seed48() sets the value of X[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 previous value of X[i] which is used only by seed48(). The
returned pointer allows you to restart the pseudorandom sequence at a given
point. Use the pointer to copy the previous X[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[i] value, the multiplier
value a, and the addend value c. The param array elements param[0-2]
specify X[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.
[POSIX] The drand48_r(), erand48_r(), jrand48_r(), lcong48_r(),
lrand48_r(), mrand48_r(), nrand48_r() l, seed48_r(), and srand_r()
functions are the reentrant versions of drand48(), erand48(), jrand48(),
lcong48(), lrand48(), mrand48(), nrand48(), seed48(), and srand48().
NOTES
[POSIX] Note that if the reentrant initialization functions are not used
prior to calling the random number generators, the init field of the struct
drand48_data structure (passed to the random number generator functions)
must be cleared prior to calling them.
[POSIX] Note also, 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.
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 < 2^31.
The mrand48() and jrand48() functions return signed long integers uniformly
distributed over the range -2^31 <=y < 2^31.
The seed48() function returns a pointer to a 48-bit internal buffer.
The lcong48() and srand48() functions do not return a value.
[POSIX] Upon success, both the drand48_r() and erand48_r() functions
return a pointer (randval) to the returned double value, and return a value
of 0 (zero). Upon success, both the mrand48_r() and jrand48_r() functions
have randval at the returned long value, and return a value of 0 (zero).
Upon success, the lcong48_r(), seed48_r(), and srand48_r() return a value
of 0 (zero). The lrand48_r() and rand48_r() functions have randval point at
the returned long value, and return a value of 0 (zero). Upon error, the
reentrant functions return a value of -1, and set errno to [EFAULT].
ERRORS
[POSIX] Upon error, the drand48_r(), erand48_r(), jrand48_r, lcong48_r,
lrand48_r, mrand48_r, nrand48_r, seed48_r, and srand_r functions return a
value of -1, and errno will be set to the following value:
[EFAULT]
The dp, randval, xsubi, param, or seed_16v value is invalid.
SEE ALSO
Functions: rand(3), random(3)
Standards: standards(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|