DRAND48(3)                 POSIX Programmer's Manual                DRAND48(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       drand48, erand48, jrand48, lcong48, lrand48, mrand48, nrand48, seed48,
       srand48 -- generate uniformly distributed pseudo-random numbers

SSYYNNOOPPSSIISS
       #include <stdlib.h>

       double drand48(void);
       double erand48(unsigned short _x_s_u_b_i[3]);
       long jrand48(unsigned short _x_s_u_b_i[3]);
       void lcong48(unsigned short _p_a_r_a_m[7]);
       long lrand48(void);
       long mrand48(void);
       long nrand48(unsigned short _x_s_u_b_i[3]);
       unsigned short *seed48(unsigned short _s_e_e_d_1_6_v[3]);
       void srand48(long _s_e_e_d_v_a_l);

DDEESSCCRRIIPPTTIIOONN
       This family of functions shall generate pseudo-random numbers using a
       linear congruential algorithm and 48-bit integer arithmetic.

       The _d_r_a_n_d_4_8() and _e_r_a_n_d_4_8() functions shall return non-negative,
       double-precision, floating-point values, uniformly distributed over the
       interval [0.0,1.0).

       The _l_r_a_n_d_4_8() and _n_r_a_n_d_4_8() functions shall return non-negative, long
       integers, uniformly distributed over the interval [0,231).

       The _m_r_a_n_d_4_8() and _j_r_a_n_d_4_8() functions shall return signed long integers
       uniformly distributed over the interval [-231,231).

       The _s_r_a_n_d_4_8(), _s_e_e_d_4_8(), and _l_c_o_n_g_4_8() functions are initialization
       entry points, one of which should be invoked before either _d_r_a_n_d_4_8(),
       _l_r_a_n_d_4_8(), or _m_r_a_n_d_4_8() is called. (Although it is not recommended
       practice, constant default initializer values shall be supplied
       automatically if _d_r_a_n_d_4_8(), _l_r_a_n_d_4_8(), or _m_r_a_n_d_4_8() is called without a
       prior call to an initialization entry point.) The _e_r_a_n_d_4_8(), _n_r_a_n_d_4_8(),
       and _j_r_a_n_d_4_8() functions do not require an initialization entry point to
       be called first.

       All the routines work by generating a sequence of 48-bit integer
       values, _X__i , according to the linear congruential formula:

              _X_n+1 = (_a_X__n +_c)mod _m        _n>= 0

       The parameter _m=2_^48; hence 48-bit integer arithmetic is performed.
       Unless _l_c_o_n_g_4_8() is invoked, the multiplier value _a and the addend
       value _c are given by:

              _a = 5DEECE66D16 = 2736731631558

              _c = B16 = 138

       The value returned by any of the _d_r_a_n_d_4_8(), _e_r_a_n_d_4_8(), _j_r_a_n_d_4_8(),
       _l_r_a_n_d_4_8(), _m_r_a_n_d_4_8(), or _n_r_a_n_d_4_8() 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.

       The _d_r_a_n_d_4_8(), _l_r_a_n_d_4_8(), and _m_r_a_n_d_4_8() 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
       _e_r_a_n_d_4_8(), _n_r_a_n_d_4_8(), and _j_r_a_n_d_4_8() 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, _e_r_a_n_d_4_8(),
       _n_r_a_n_d_4_8(), and _j_r_a_n_d_4_8() allow separate modules of a large program to
       generate several _i_n_d_e_p_e_n_d_e_n_t streams of pseudo-random numbers; that is,
       the sequence of numbers in each stream shall _n_o_t depend upon how many
       times the routines are called to generate numbers for the other
       streams.

       The initializer function _s_r_a_n_d_4_8() 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 .

       The initializer function _s_e_e_d_4_8() 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 _s_e_e_d_1_6_v[_0].  The mid-order 16 bits of
       _X__i are set to the low-order 16 bits of _s_e_e_d_1_6_v[_1].  The high-order 16
       bits of _X__i are set to the low-order 16 bits of _s_e_e_d_1_6_v[_2].  In
       addition, the previous value of _X__i is copied into a 48-bit internal
       buffer, used only by _s_e_e_d_4_8(), and a pointer to this buffer is the
       value returned by _s_e_e_d_4_8().  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
       _s_e_e_d_4_8() when the program is restarted.

       The initializer function _l_c_o_n_g_4_8() allows the user to specify the
       initial _X__i , the multiplier value _a, and the addend value _c. Argument
       array elements _p_a_r_a_m[_0_-_2] specify _X__i , _p_a_r_a_m[_3_-_5] specify the
       multiplier _a, and _p_a_r_a_m[_6] specifies the 16-bit addend _c. After
       _l_c_o_n_g_4_8() is called, a subsequent call to either _s_r_a_n_d_4_8() or _s_e_e_d_4_8()
       shall restore the standard multiplier and addend values, _a and _c_,
       specified above.

       The _d_r_a_n_d_4_8(), _l_r_a_n_d_4_8(), and _m_r_a_n_d_4_8() functions need not be thread-
       safe.

RREETTUURRNN VVAALLUUEE
       As described in the DESCRIPTION above.

EERRRROORRSS
       No errors are defined.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       These functions should be avoided whenever non-trivial requirements
       (including safety) have to be fulfilled.

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _i_n_i_t_s_t_a_t_e(), _r_a_n_d()

       The Base Definitions volume of POSIX.1-2017, <<ssttddlliibb..hh>>

CCOOPPYYRRIIGGHHTT
       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 .

       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 .



IEEE/The Open Group                  2017                           DRAND48(3)
