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