mirror of https://github.com/mkerrisk/man-pages
173 lines
6.6 KiB
Plaintext
173 lines
6.6 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "DRAND48" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" drand48
|
|
.SH PROLOG
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
The Linux implementation of this interface may differ (consult
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
or the interface may not be implemented on Linux.
|
|
.SH NAME
|
|
drand48, erand48, jrand48, lcong48, lrand48, mrand48, nrand48, seed48,
|
|
srand48 \- generate uniformly distributed
|
|
pseudo\-random numbers
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <stdlib.h>
|
|
.br
|
|
.sp
|
|
double drand48(void);
|
|
.br
|
|
double erand48(unsigned short\fP \fIxsubi\fP\fB[3]);
|
|
.br
|
|
long jrand48(unsigned short\fP \fIxsubi\fP\fB[3]);
|
|
.br
|
|
void lcong48(unsigned short\fP \fIparam\fP\fB[7]);
|
|
.br
|
|
long lrand48(void);
|
|
.br
|
|
long mrand48(void);
|
|
.br
|
|
long nrand48(unsigned short\fP \fIxsubi\fP\fB[3]);
|
|
.br
|
|
unsigned short *seed48(unsigned short\fP \fIseed16v\fP\fB[3]);
|
|
.br
|
|
void srand48(long\fP \fIseedval\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
This family of functions shall generate pseudo-random numbers using
|
|
a linear congruential algorithm and 48-bit integer
|
|
arithmetic.
|
|
.LP
|
|
The \fIdrand48\fP() and \fIerand48\fP() functions shall return non-negative,
|
|
double-precision, floating-point values,
|
|
uniformly distributed over the interval [0.0,1.0).
|
|
.LP
|
|
The \fIlrand48\fP() and \fInrand48\fP() functions shall return non-negative,
|
|
long integers, uniformly distributed over the
|
|
interval [0,2**31).
|
|
.LP
|
|
The \fImrand48\fP() and \fIjrand48\fP() functions shall return signed
|
|
long integers uniformly distributed over the interval
|
|
[-2**31,2**31).
|
|
.LP
|
|
The \fIsrand48\fP(), \fIseed48\fP(), and \fIlcong48\fP() functions
|
|
are initialization entry points, one of which should be
|
|
invoked before either \fIdrand48\fP(), \fIlrand48\fP(), or \fImrand48\fP()
|
|
is called. (Although it is not recommended practice,
|
|
constant default initializer values shall be supplied automatically
|
|
if \fIdrand48\fP(), \fIlrand48\fP(), or \fImrand48\fP() is
|
|
called without a prior call to an initialization entry point.) The
|
|
\fIerand48\fP(), \fInrand48\fP(), and \fIjrand48\fP()
|
|
functions do not require an initialization entry point to be called
|
|
first.
|
|
.LP
|
|
All the routines 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
|
|
.LP
|
|
The parameter \fIm\fP = 2**48; hence 48-bit integer arithmetic is
|
|
performed. Unless \fIlcong48\fP() is invoked, the multiplier
|
|
value \fIa\fP and the addend value \fIc\fP are given by:
|
|
\fIa\fP = 5DEECE66D_16 = 273673163155_8
|
|
.LP
|
|
\fIc\fP = B_16 = 13_8
|
|
.LP
|
|
The value returned by any of the \fIdrand48\fP(), \fIerand48\fP(),
|
|
\fIjrand48\fP(), \fIlrand48\fP(), \fImrand48\fP(), or
|
|
\fInrand48\fP() functions is computed by first generating the next
|
|
48-bit X_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 (leftmost) bits of X_i and
|
|
transformed into the returned value.
|
|
.LP
|
|
The \fIdrand48\fP(), \fIlrand48\fP(), and \fImrand48\fP() functions
|
|
store the last 48-bit X_i generated in an internal
|
|
buffer; that is why the application shall ensure that these are initialized
|
|
prior to being invoked. The \fIerand48\fP(),
|
|
\fInrand48\fP(), and \fIjrand48\fP() functions require the calling
|
|
program to provide storage for the successive X_i values
|
|
in the array specified as an argument when the functions are invoked.
|
|
That 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 an argument. By using
|
|
different arguments, \fIerand48\fP(), \fInrand48\fP(), and \fIjrand48\fP()
|
|
allow separate modules of a large program to generate
|
|
several \fIindependent\fP streams of pseudo-random numbers; that is,
|
|
the sequence of numbers in each stream shall \fInot\fP
|
|
depend upon how many times the routines are called to generate numbers
|
|
for the other streams.
|
|
.LP
|
|
The initializer function \fIsrand48\fP() sets the high-order 32 bits
|
|
of X_i to the low-order 32 bits contained in its
|
|
argument. The low-order 16 bits of X_i are set to the arbitrary value
|
|
330E_16.
|
|
.LP
|
|
The initializer function \fIseed48\fP() sets the value of X_i to the
|
|
48-bit value specified in the argument array. The
|
|
low-order 16 bits of X_i are set to the low-order 16 bits of \fIseed16v\fP[\fI0\fP].
|
|
The mid-order 16 bits of X_i are
|
|
set to the low-order 16 bits of \fIseed16v\fP[\fI1\fP]. The high-order
|
|
16 bits of X_i are set to the low-order 16 bits of
|
|
\fIseed16v\fP[\fI2\fP]. In addition, the previous value of X_i is
|
|
copied into a 48-bit internal buffer, used only by
|
|
\fIseed48\fP(), and a pointer to this buffer is the value returned
|
|
by \fIseed48\fP(). This returned pointer, which can just be
|
|
ignored if not needed, is useful if a program is to be restarted from
|
|
a given point at some future time-use the pointer to get at
|
|
and store the last X_i value, and then use this value to reinitialize
|
|
via \fIseed48\fP() when the program is restarted.
|
|
.LP
|
|
The initializer function \fIlcong48\fP() allows the user to specify
|
|
the initial X_i, the multiplier value \fIa\fP, and the
|
|
addend value \fIc\fP.
|
|
Argument array elements \fIparam\fP[\fI0-2\fP] specify X_i, \fIparam\fP[\fI3-5\fP]
|
|
specify the
|
|
multiplier \fIa\fP, and \fIparam\fP[\fI6\fP] specifies the 16-bit
|
|
addend \fIc\fP. After \fIlcong48\fP() is called, a subsequent call
|
|
to
|
|
either \fIsrand48\fP() or \fIseed48\fP() shall restore the standard
|
|
multiplier and addend values, \fIa\fP and \fIc,\fP
|
|
specified above.
|
|
.LP
|
|
The \fIdrand48\fP(), \fIlrand48\fP(), and \fImrand48\fP() functions
|
|
need not be reentrant. A function that is not required to
|
|
be reentrant is not required to be thread-safe.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
As described in the DESCRIPTION above.
|
|
.SH ERRORS
|
|
.LP
|
|
No errors are defined.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIrand\fP(), the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
\fI<stdlib.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|