man3/drand48.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   8 .\"     386BSD man pages
   9 .\" Modified Sat Jul 24 19:46:03 1993 by Rik Faith (faith@cs.unc.edu)
  10 .TH DRAND48 3  2021-03-22 GNU "Linux Programmer's Manual"
  11 .SH NAME
  12 drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48,
  13 lcong48 \- generate uniformly distributed pseudo-random numbers
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <stdlib.h>
  20 .PP
  21 .B double drand48(void);
  22 .BI "double erand48(unsigned short " xsubi [3]);
  23 .PP
  24 .B long lrand48(void);
  25 .BI "long nrand48(unsigned short " xsubi [3]);
  26 .PP
  27 .B long mrand48(void);
  28 .BI "long jrand48(unsigned short " xsubi [3]);
  29 .PP
  30 .BI "void srand48(long " seedval );
  31 .BI "unsigned short *seed48(unsigned short " seed16v [3]);
  32 .BI "void lcong48(unsigned short " param [7]);
  33 .fi
  34 .PP
  35 .RS -4
  36 Feature Test Macro Requirements for glibc (see
  37 .BR feature_test_macros (7)):
  38 .RE
  39 .PP
  40 All functions shown above:
  41 .\" .BR drand48 (),
  42 .\" .BR erand48 (),
  43 .\" .BR lrand48 (),
  44 .\" .BR nrand48 (),
  45 .\" .BR mrand48 (),
  46 .\" .BR jrand48 (),
  47 .\" .BR srand48 (),
  48 .\" .BR seed48 (),
  49 .\" .BR lcong48 ():
  50 .nf
  51     _XOPEN_SOURCE
  52         || /* Glibc since 2.19: */ _DEFAULT_SOURCE
  53         || /* Glibc <= 2.19: */ _SVID_SOURCE
  54 .fi
  55 .SH DESCRIPTION
  56 These functions generate pseudo-random numbers using the linear congruential
  57 algorithm and 48-bit integer arithmetic.
  58 .PP
  59 The
  60 .BR drand48 ()
  61 and
  62 .BR erand48 ()
  63 functions return nonnegative
  64 double-precision floating-point values uniformly distributed over the interval
  65 [0.0,\ 1.0).
  66 .PP
  67 The
  68 .BR lrand48 ()
  69 and
  70 .BR nrand48 ()
  71 functions return nonnegative
  72 long integers uniformly distributed over the interval [0,\ 2^31).
  73 .PP
  74 The
  75 .BR mrand48 ()
  76 and
  77 .BR jrand48 ()
  78 functions return signed long
  79 integers uniformly distributed over the interval [\-2^31,\ 2^31).
  80 .PP
  81 The
  82 .BR srand48 (),
  83 .BR seed48 (),
  84 and
  85 .BR lcong48 ()
  86 functions are
  87 initialization functions, one of which should be called before using
  88 .BR drand48 (),
  89 .BR lrand48 (),
  90 or
  91 .BR mrand48 ().
  92 The functions
  93 .BR erand48 (),
  94 .BR nrand48 (),
  95 and
  96 .BR jrand48 ()
  97 do not require
  98 an initialization function to be called first.
  99 .PP
 100 All the functions work by generating a sequence of 48-bit integers,
 101 .IR Xi ,
 102 according to the linear congruential formula:
 103 .PP
 104 .in +4n
 105 .EX
 106 .B Xn+1 = (aXn + c) mod m,   where n >= 0
 107 .EE
 108 .in
 109 .PP
 110 The parameter
 111 .I m
 112 = 2^48, hence 48-bit integer arithmetic is performed.
 113 Unless
 114 .BR lcong48 ()
 115 is called,
 116 .I a
 117 and
 118 .I c
 119 are given by:
 120 .PP
 121 .in +4n
 122 .EX
 123 .B a = 0x5DEECE66D
 124 .B c = 0xB
 125 .EE
 126 .in
 127 .PP
 128 The value returned by any of the functions
 129 .BR drand48 (),
 130 .BR erand48 (),
 131 .BR lrand48 (),
 132 .BR nrand48 (),
 133 .BR mrand48 (),
 134 or
 135 .BR jrand48 ()
 136 is
 137 computed by first generating the next 48-bit
 138 .I Xi
 139 in the sequence.
 140 Then the appropriate number of bits, according to the type of data item to
 141 be returned, is copied from the high-order bits of
 142 .I Xi
 143 and transformed
 144 into the returned value.
 145 .PP
 146 The functions
 147 .BR drand48 (),
 148 .BR lrand48 (),
 149 and
 150 .BR mrand48 ()
 151 store
 152 the last 48-bit
 153 .I Xi
 154 generated in an internal buffer.
 155 The functions
 156 .BR erand48 (),
 157 .BR nrand48 (),
 158 and
 159 .BR jrand48 ()
 160 require the calling
 161 program to provide storage for the successive
 162 .I Xi
 163 values in the array
 164 argument
 165 .IR xsubi .
 166 The functions are initialized by placing the initial
 167 value of
 168 .I Xi
 169 into the array before calling the function for the first
 170 time.
 171 .PP
 172 The initializer function
 173 .BR srand48 ()
 174 sets the high order 32-bits of
 175 .I Xi
 176 to the argument
 177 .IR seedval .
 178 The low order 16-bits are set
 179 to the arbitrary value 0x330E.
 180 .PP
 181 The initializer function
 182 .BR seed48 ()
 183 sets the value of
 184 .I Xi
 185 to
 186 the 48-bit value specified in the array argument
 187 .IR seed16v .
 188 The
 189 previous value of
 190 .I Xi
 191 is copied into an internal buffer and a
 192 pointer to this buffer is returned by
 193 .BR seed48 ().
 194 .PP
 195 The initialization function
 196 .BR lcong48 ()
 197 allows the user to specify
 198 initial values for
 199 .IR Xi ,
 200 .IR a ,
 201 and
 202 .IR c .
 203 Array argument
 204 elements
 205 .I param[0\-2]
 206 specify
 207 .IR Xi ,
 208 .I param[3\-5]
 209 specify
 210 .IR a ,
 211 and
 212 .I param[6]
 213 specifies
 214 .IR c .
 215 After
 216 .BR lcong48 ()
 217 has been called, a subsequent call to either
 218 .BR srand48 ()
 219 or
 220 .BR seed48 ()
 221 will restore the standard values of
 222 .I a
 223 and
 224 .IR c .
 225 .SH ATTRIBUTES
 226 For an explanation of the terms used in this section, see
 227 .BR attributes (7).
 228 .ad l
 229 .nh
 230 .TS
 231 allbox;
 232 lbx lb lb
 233 l l l.
 234 Interface       Attribute       Value
 235 T{
 236 .BR drand48 (),
 237 .BR erand48 (),
 238 .BR lrand48 (),
 239 .BR nrand48 (),
 240 .BR mrand48 (),
 241 .BR jrand48 (),
 242 .BR srand48 (),
 243 .BR seed48 (),
 244 .BR lcong48 ()
 245 T}      Thread safety   T{
 246 MT-Unsafe race:drand48
 247 T}
 248 .TE
 249 .hy
 250 .ad
 251 .sp 1
 252 .PP
 253 The above
 254 functions record global state information for the random number generator,
 255 so they are not thread-safe.
 256 .SH CONFORMING TO
 257 POSIX.1-2001, POSIX.1-2008, SVr4.
 258 .SH SEE ALSO
 259 .BR rand (3),
 260 .BR random (3)