lib/libc/stdlib/rand48.3

   1 .\"     $NetBSD: rand48.3,v 1.10 2003/05/10 12:24:54 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1993 Martin Birgmeier
   4 .\" All rights reserved.
   5 .\"
   6 .\" You may redistribute unmodified or modified versions of this source
   7 .\" code provided that the above copyright notice and this and the
   8 .\" following conditions are retained.
   9 .\"
  10 .\" This software is provided ``as is'', and comes with no warranties
  11 .\" of any kind. I shall in no event be liable for anything that happens
  12 .\" to anyone/anything when using this software.
  13 .\"
  14 .Dd October 8, 1993
  15 .Dt RAND48 3
  16 .Os
  17 .Sh NAME
  18 .Nm drand48 ,
  19 .Nm erand48 ,
  20 .Nm lrand48 ,
  21 .Nm nrand48 ,
  22 .Nm mrand48 ,
  23 .Nm jrand48 ,
  24 .Nm srand48 ,
  25 .Nm seed48 ,
  26 .Nm lcong48
  27 .Nd pseudo-random number generators and initialization routines
  28 .Sh LIBRARY
  29 .Lb libc
  30 .Sh SYNOPSIS
  31 .In stdlib.h
  32 .Ft double
  33 .Fn drand48 void
  34 .Ft double
  35 .Fn erand48 "unsigned short xseed[3]"
  36 .Ft long
  37 .Fn lrand48 void
  38 .Ft long
  39 .Fn nrand48 "unsigned short xseed[3]"
  40 .Ft long
  41 .Fn mrand48 void
  42 .Ft long
  43 .Fn jrand48 "unsigned short xseed[3]"
  44 .Ft void
  45 .Fn srand48 "long seed"
  46 .Ft "unsigned short *"
  47 .Fn seed48 "unsigned short xseed[3]"
  48 .Ft void
  49 .Fn lcong48 "unsigned short p[7]"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn rand48
  53 family of functions generates pseudo-random numbers using a linear
  54 congruential algorithm working on integers 48 bits in size.
  55 The particular formula employed is
  56 r(n+1) = (a * r(n) + c) mod m
  57 where the default values are
  58 for the multiplicand a = 0x5deece66d = 25214903917 and
  59 the addend c = 0xb = 11.
  60 The modulus is always fixed at m = 2 ** 48.
  61 r(n) is called the seed of the random number generator.
  62 .Pp
  63 For all the six generator routines described next, the first
  64 computational step is to perform a single iteration of the algorithm.
  65 .Pp
  66 .Fn drand48
  67 and
  68 .Fn erand48
  69 return values of type double.
  70 The full 48 bits of r(n+1) are loaded into the mantissa of the
  71 returned value, with the exponent set such that the values produced
  72 lie in the interval [0.0, 1.0).
  73 .Pp
  74 .Fn lrand48
  75 and
  76 .Fn nrand48
  77 return values of type long in the range [0, 2**31-1].
  78 The high-order (31) bits of r(n+1) are loaded into the lower bits
  79 of the returned value, with the topmost (sign) bit set to zero.
  80 .Pp
  81 .Fn mrand48
  82 and
  83 .Fn jrand48
  84 return values of type long in the range [-2**31, 2**31-1].
  85 The high-order (32) bits of r(n+1) are loaded into the returned value.
  86 .Pp
  87 .Fn drand48 ,
  88 .Fn lrand48 ,
  89 and
  90 .Fn mrand48
  91 use an internal buffer to store r(n).
  92 For these functions
  93 the initial value of r(0) = 0x1234abcd330e = 20017429951246.
  94 .Pp
  95 On the other hand,
  96 .Fn erand48 ,
  97 .Fn nrand48 ,
  98 and
  99 .Fn jrand48
 100 use a user-supplied buffer to store the seed r(n), which consists
 101 of an array of 3 shorts, where the zeroth member holds the least
 102 significant bits.
 103 .Pp
 104 All functions share the same multiplicand and addend.
 105 .Pp
 106 .Fn srand48
 107 is used to initialize the internal buffer r(n) of
 108 .Fn drand48 ,
 109 .Fn lrand48 ,
 110 and
 111 .Fn mrand48
 112 such that the 32 bits of the seed value are copied into the upper 32 bits
 113 of r(n), with the lower 16 bits of r(n) arbitrarily being set to 0x330e.
 114 Additionally, the constant multiplicand and addend of the algorithm are
 115 reset to the default values given above.
 116 .Pp
 117 .Fn seed48
 118 also initializes the internal buffer r(n) of
 119 .Fn drand48 ,
 120 .Fn lrand48 ,
 121 and
 122 .Fn mrand48 ,
 123 but here all 48 bits of the seed can be specified in an array of 3 shorts,
 124 where the zeroth member specifies the lowest bits.
 125 Again, the constant multiplicand and addend of the algorithm are
 126 reset to the default values given above.
 127 .Fn seed48
 128 returns a pointer to an array of 3 shorts which contains the old seed.
 129 This array is statically allocated, thus its contents are lost after
 130 each new call to
 131 .Fn seed48 .
 132 .Pp
 133 Finally,
 134 .Fn lcong48
 135 allows full control over the multiplicand and addend used in
 136 .Fn drand48 ,
 137 .Fn erand48 ,
 138 .Fn lrand48 ,
 139 .Fn nrand48 ,
 140 .Fn mrand48 ,
 141 and
 142 .Fn jrand48 ,
 143 and the seed used in
 144 .Fn drand48 ,
 145 .Fn lrand48 ,
 146 and
 147 .Fn mrand48 .
 148 An array of 7 shorts is passed as parameter; the first three shorts are
 149 used to initialize the seed; the second three are used to initialize the
 150 multiplicand; and the last short is used to initialize the addend.
 151 It is thus not possible to use values greater than 0xffff as the addend.
 152 .Pp
 153 Note that all three methods of seeding the random number generator
 154 always also set the multiplicand and addend for any of the six
 155 generator calls.
 156 .Pp
 157 For a more powerful random number generator, see
 158 .Xr random 3 .
 159 .Sh SEE ALSO
 160 .Xr rand 3 ,
 161 .Xr random 3
 162 .Sh AUTHORS
 163 Martin Birgmeier