original/man3/drand48.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" References consulted:
  24 .\"     Linux libc source code
  25 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  26 .\"     386BSD man pages
  27 .\" Modified Sat Jul 24 19:46:03 1993 by Rik Faith (faith@cs.unc.edu)
  28 .TH DRAND48 3  2007-07-26 "" "Linux Programmer's Manual"
  29 .SH NAME
  30 drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48,
  31 lcong48 \- generate uniformly distributed pseudo-random numbers
  32 .SH SYNOPSIS
  33 .nf
  34 .B #include <stdlib.h>
  35 .sp
  36 .B double drand48(void);
  37 .sp
  38 .BI "double erand48(unsigned short " xsubi [3]);
  39 .sp
  40 .B long int lrand48(void);
  41 .sp
  42 .BI "long int nrand48(unsigned short " xsubi [3]);
  43 .sp
  44 .B long int mrand48(void);
  45 .sp
  46 .BI "long int jrand48(unsigned short " xsubi [3]);
  47 .sp
  48 .BI "void srand48(long int " seedval );
  49 .sp
  50 .BI "unsigned short *seed48(unsigned short " seed16v [3]);
  51 .sp
  52 .BI "void lcong48(unsigned short " param [7]);
  53 .fi
  54 .sp
  55 .in -4n
  56 Feature Test Macro Requirements for glibc (see
  57 .BR feature_test_macros (7)):
  58 .in
  59 .sp
  60 .ad l
  61 All functions shown above:
  62 .\" .BR drand48 (),
  63 .\" .BR erand48 (),
  64 .\" .BR lrand48 (),
  65 .\" .BR nrand48 (),
  66 .\" .BR mrand48 (),
  67 .\" .BR jrand48 (),
  68 .\" .BR srand48 (),
  69 .\" .BR seed48 (),
  70 .\" .BR lcong48 ():
  71 _SVID_SOURCE || _XOPEN_SOURCE
  72 .ad b
  73 .SH DESCRIPTION
  74 These functions generate pseudo-random numbers using the linear congruential
  75 algorithm and 48-bit integer arithmetic.
  76 .PP
  77 The
  78 .BR drand48 ()
  79 and
  80 .BR erand48 ()
  81 functions return nonnegative
  82 double-precision floating-point values uniformly distributed between
  83 [0.0, 1.0).
  84 .PP
  85 The
  86 .BR lrand48 ()
  87 and
  88 .BR nrand48 ()
  89 functions return nonnegative
  90 long integers uniformly distributed between 0 and 2^31.
  91 .PP
  92 The
  93 .BR mrand48 ()
  94 and
  95 .BR jrand48 ()
  96 functions return signed long
  97 integers uniformly distributed between \-2^31 and 2^31.
  98 .PP
  99 The
 100 .BR srand48 (),
 101 .BR seed48 ()
 102 and
 103 .BR lcong48 ()
 104 functions are
 105 initialization functions, one of which should be called before using
 106 .BR drand48 (),
 107 .BR lrand48 ()
 108 or
 109 .BR mrand48 ().
 110 The functions
 111 .BR erand48 (),
 112 .BR nrand48 ()
 113 and
 114 .BR jrand48 ()
 115 do not require
 116 an initialization function to be called first.
 117 .PP
 118 All the functions work by generating a sequence of 48-bit integers,
 119 \fIXi\fP, according to the linear congruential formula:
 120 .sp
 121 .nf
 122 .RS
 123 .B Xn+1 = (aXn + c) mod m,   where n >= 0
 124 .RE
 125 .fi
 126 .sp
 127 The parameter \fIm\fP = 2^48, hence 48-bit integer arithmetic is performed.
 128 Unless
 129 .BR lcong48 ()
 130 is called, \fIa\fP and \fIc\fP are given by:
 131 .sp
 132 .nf
 133 .RS
 134 .B a = 0x5DEECE66D
 135 .B c = 0xB
 136 .RE
 137 .fi
 138 .sp
 139 The value returned by any of the functions
 140 .BR drand48 (),
 141 .BR erand48 (),
 142 .BR lrand48 (),
 143 .BR nrand48 (),
 144 .BR mrand48 ()
 145 or
 146 .BR jrand48 ()
 147 is
 148 computed by first generating the next 48-bit \fIXi\fP in the sequence.
 149 Then the appropriate number of bits, according to the type of data item to
 150 be returned, is copied from the high-order bits of \fIXi\fP and transformed
 151 into the returned value.
 152 .PP
 153 The functions
 154 .BR drand48 (),
 155 .BR lrand48 ()
 156 and
 157 .BR mrand48 ()
 158 store
 159 the last 48-bit \fIXi\fP generated in an internal buffer.
 160 The functions
 161 .BR erand48 (),
 162 .BR nrand48 ()
 163 and
 164 .BR jrand48 ()
 165 require the calling
 166 program to provide storage for the successive \fIXi\fP values in the array
 167 argument \fIxsubi\fP.
 168 The functions are initialized by placing the initial
 169 value of \fIXi\fP 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 \fIXi\fP to the argument \fIseedval\fP.
 176 The low order 16-bits are set
 177 to the arbitrary value 0x330E.
 178 .PP
 179 The initializer function
 180 .BR seed48 ()
 181 sets the value of \fIXi\fP to
 182 the 48-bit value specified in the array argument \fIseed16v\fP.
 183 The
 184 previous value of \fIXi\fP is copied into an internal buffer and a
 185 pointer to this buffer is returned by
 186 .BR seed48 ().
 187 .PP
 188 The initialization function
 189 .BR lcong48 ()
 190 allows the user to specify
 191 initial values for \fIXi\fP, \fIa\fP and \fIc\fP.
 192 Array argument
 193 elements \fIparam[0-2]\fP specify \fIXi\fP, \fIparam[3-5]\fP specify
 194 \fIa\fP, and \fIparam[6]\fP specifies \fIc\fP.
 195 After
 196 .BR lcong48 ()
 197 has been called, a subsequent call to either
 198 .BR srand48 ()
 199 or
 200 .BR seed48 ()
 201 will restore the standard values of \fIa\fP and \fIc\fP.
 202 .SH "CONFORMING TO"
 203 SVr4, POSIX.1-2001.
 204 .SH NOTES
 205 These functions are declared obsolete by SVID 3, which states that
 206 .BR rand (3)
 207 should be used instead.
 208 .SH "SEE ALSO"
 209 .BR rand (3),
 210 .BR random (3)