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