man3/drand48.3

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