drand48.3p (7103B)
- '\" et
- .TH DRAND48 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .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.
- .\"
- .EQ
- delim $$
- .EN
- .SH NAME
- drand48,
- erand48,
- jrand48,
- lcong48,
- lrand48,
- mrand48,
- nrand48,
- seed48,
- srand48
- \(em generate uniformly distributed pseudo-random numbers
- .SH SYNOPSIS
- .LP
- .nf
- #include <stdlib.h>
- .P
- double drand48(void);
- double erand48(unsigned short \fIxsubi\fP[3]);
- long jrand48(unsigned short \fIxsubi\fP[3]);
- void lcong48(unsigned short \fIparam\fP[7]);
- long lrand48(void);
- long mrand48(void);
- long nrand48(unsigned short \fIxsubi\fP[3]);
- unsigned short *seed48(unsigned short \fIseed16v\fP[3]);
- void srand48(long \fIseedval\fP);
- .fi
- .SH DESCRIPTION
- This family of functions shall generate pseudo-random numbers using
- a linear congruential algorithm and 48-bit integer arithmetic.
- .P
- The
- \fIdrand48\fR()
- and
- \fIerand48\fR()
- functions shall return non-negative, double-precision, floating-point
- values, uniformly distributed over the interval [0.0,1.0).
- .P
- The
- \fIlrand48\fR()
- and
- \fInrand48\fR()
- functions shall return non-negative, long integers, uniformly
- distributed over the interval [0,2\u\s-331\s+3\d).
- .P
- The
- \fImrand48\fR()
- and
- \fIjrand48\fR()
- functions shall return signed long integers uniformly distributed over
- the interval [\-2\u\s-331\s+3\d,2\u\s-331\s+3\d).
- .P
- The
- \fIsrand48\fR(),
- \fIseed48\fR(),
- and
- \fIlcong48\fR()
- functions are initialization entry points, one of which should be
- invoked before either
- \fIdrand48\fR(),
- \fIlrand48\fR(),
- or
- \fImrand48\fR()
- is called. (Although it is not recommended practice, constant default
- initializer values shall be supplied automatically if
- \fIdrand48\fR(),
- \fIlrand48\fR(),
- or
- \fImrand48\fR()
- is called without a prior call to an initialization entry point.) The
- \fIerand48\fR(),
- \fInrand48\fR(),
- and
- \fIjrand48\fR()
- functions do not require an initialization entry point to be called
- first.
- .P
- All the routines work by generating a sequence of 48-bit integer
- values, $X_ i" " ,$ according to the linear congruential formula:
- .sp
- .RS
- $X sub{n+1} " " = " " (aX_ n" "^+^c) sub{roman mod " " m} " " " " " " " " " " " " " " " " n>= " " 0$
- .RE
- .P
- The parameter $m^=^2"^" 48$; hence 48-bit integer arithmetic is
- performed. Unless
- \fIlcong48\fR()
- is invoked, the multiplier value $a$ and the addend value $c$ are given
- by:
- .sp
- .RS
- $a " " mark = " " roman "5DEECE66D"^sub 16 " " = " " roman 273673163155^sub 8$
- .P
- $c " " lineup = " " roman B^sub 16 " " = " " roman 13^sub 8$
- .RE
- .P
- The value returned by any of the
- \fIdrand48\fR(),
- \fIerand48\fR(),
- \fIjrand48\fR(),
- \fIlrand48\fR(),
- \fImrand48\fR(),
- or
- \fInrand48\fR()
- 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.
- .P
- The
- \fIdrand48\fR(),
- \fIlrand48\fR(),
- and
- \fImrand48\fR()
- 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\fR(),
- \fInrand48\fR(),
- and
- \fIjrand48\fR()
- 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\fR(),
- \fInrand48\fR(),
- and
- \fIjrand48\fR()
- allow separate modules of a large program to generate several
- .IR independent
- streams of pseudo-random numbers; that is, the sequence of numbers in
- each stream shall
- .IR not
- depend upon how many times the routines are called to generate numbers
- for the other streams.
- .P
- The initializer function
- \fIsrand48\fR()
- 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 $roman 330E_ 16" " .$
- .P
- The initializer function
- \fIseed48\fR()
- 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
- .IR seed16v [ 0 ].
- The mid-order 16 bits of $X_ i$ are set to the low-order 16 bits of
- .IR seed16v [ 1 ].
- The high-order 16 bits of $X_ i$ are set to the low-order 16 bits of
- .IR seed16v [ 2 ].
- In addition, the previous value of $X_ i$ is copied into a 48-bit
- internal buffer, used only by
- \fIseed48\fR(),
- and a pointer to this buffer is the value returned by
- \fIseed48\fR().
- 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\(emuse the pointer to get at and store the last $X_ i$
- value, and then use this value to reinitialize via
- \fIseed48\fR()
- when the program is restarted.
- .P
- The initializer function
- \fIlcong48\fR()
- allows the user to specify the initial $X_ i" " ,$ the multiplier value
- $a,$ and the addend value $c.$ Argument array elements
- .IR param [ 0-2 ]
- specify $X_ i" " ,$
- .IR param [ 3-5 ]
- specify the multiplier $a,$ and
- .IR param [ 6 ]
- specifies the 16-bit addend $c.$ After
- \fIlcong48\fR()
- is called, a subsequent call to either
- \fIsrand48\fR()
- or
- \fIseed48\fR()
- shall restore the standard multiplier and addend values,
- .IR a
- and
- .IR c,
- specified above.
- .P
- The
- \fIdrand48\fR(),
- \fIlrand48\fR(),
- and
- \fImrand48\fR()
- functions need not be thread-safe.
- .SH "RETURN VALUE"
- As described in the DESCRIPTION above.
- .SH ERRORS
- No errors are defined.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- These functions should be avoided whenever non-trivial
- requirements (including safety) have to be fulfilled.
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIinitstate\fR\^(\|)",
- .IR "\fIrand\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<stdlib.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .