stdlib/FreeBSD/random.3.patch

   1 --- random.3.orig       2010-04-28 23:38:47.000000000 -0700
   2 +++ random.3    2010-04-29 09:47:13.000000000 -0700
   3 @@ -32,32 +32,45 @@
   4  .Dt RANDOM 3
   5  .Os
   6  .Sh NAME
   7 +.Nm initstate ,
   8  .Nm random ,
   9 +.Nm setstate ,
  10  .Nm srandom ,
  11 -.Nm srandomdev ,
  12 -.Nm initstate ,
  13 -.Nm setstate
  14 +.Nm srandomdev
  15  .Nd better random number generator; routines for changing generators
  16  .Sh LIBRARY
  17  .Lb libc
  18  .Sh SYNOPSIS
  19  .In stdlib.h
  20 +.Ft char *
  21 +.Fo initstate
  22 +.Fa "unsigned seed"
  23 +.Fa "char *state"
  24 +.Fa "size_t size"
  25 +.Fc
  26  .Ft long
  27 -.Fn random void
  28 +.Fo random
  29 +.Fa void
  30 +.Fc
  31 +.Ft char *
  32 +.Fo setstate
  33 +.Fa "const char *state"
  34 +.Fc
  35  .Ft void
  36 -.Fn srandom "unsigned long seed"
  37 +.Fo srandom
  38 +.Fa "unsigned seed"
  39 +.Fc
  40  .Ft void
  41 -.Fn srandomdev void
  42 -.Ft char *
  43 -.Fn initstate "unsigned long seed" "char *state" "long n"
  44 -.Ft char *
  45 -.Fn setstate "char *state"
  46 +.Fo srandomdev
  47 +.Fa void
  48 +.Fc
  49  .Sh DESCRIPTION
  50  The
  51  .Fn random
  52  function
  53 -uses a non-linear additive feedback random number generator employing a
  54 -default table of size 31 long integers to return successive pseudo-random
  55 +uses a non-linear, additive feedback, random number generator, employing a
  56 +default table of size 31 long integers.
  57 +It returns successive pseudo-random
  58  numbers in the range from 0 to
  59  .if t 2\u\s731\s10\d\(mi1.
  60  .if n (2**31)\(mi1.
  61 @@ -78,7 +91,7 @@ The difference is that
  62  .Xr rand 3
  63  produces a much less random sequence \(em in fact, the low dozen bits
  64  generated by rand go through a cyclic pattern.
  65 -All the bits generated by
  66 +All of the bits generated by
  67  .Fn random
  68  are usable.
  69  For example,
  70 @@ -87,18 +100,21 @@ will produce a random binary
  71  value.
  72  .Pp
  73  Like
  74 +.Xr srand 3 ,
  75 +.Fn srandom
  76 +sets the initial seed value for future calls to
  77 +.Fn random .
  78 +Like
  79  .Xr rand 3 ,
  80  .Fn random
  81  will by default produce a sequence of numbers that can be duplicated
  82  by calling
  83  .Fn srandom
  84 -with
  85 -.Ql 1
  86 -as the seed.
  87 +with the same seed.
  88  .Pp
  89  The
  90  .Fn srandomdev
  91 -routine initializes a state array using the
  92 +routine initializes a state array, using the
  93  .Xr random 4
  94  random number device which returns good random numbers,
  95  suitable for cryptographic use.
  96 @@ -123,7 +139,7 @@ more state, the better the random number
  97  the nearest known amount.
  98  Using less than 8 bytes will cause an error.)
  99  The seed for the initialization (which specifies a starting point for
 100 -the random number sequence, and provides for restarting at the same
 101 +the random number sequence and provides for restarting at the same
 102  point) is also an argument.
 103  The
 104  .Fn initstate
 105 @@ -162,7 +178,7 @@ it is initialized.
 106  With 256 bytes of state information, the period of the random number
 107  generator is greater than
 108  .if t 2\u\s769\s10\d,
 109 -.if n 2**69
 110 +.if n 2**69 ,
 111  which should be sufficient for most purposes.
 112  .Sh DIAGNOSTICS
 113  If
 114 @@ -171,11 +187,36 @@ is called with less than 8 bytes of stat
 115  .Fn setstate
 116  detects that the state information has been garbled, error
 117  messages are printed on the standard error output.
 118 +.Sh LEGACY SYNOPSIS
 119 +.Fd #include <stdlib.h>
 120 +.Pp
 121 +.Ft char *
 122 +.br
 123 +.Fo initstate
 124 +.Fa "unsigned long seed"
 125 +.Fa "char *state"
 126 +.Fa "long size"
 127 +.Fc ;
 128 +.Pp
 129 +.Ft char *
 130 +.br
 131 +.Fo setstate
 132 +.Fa "char *state"
 133 +.Fc ;
 134 +.Pp
 135 +.Ft void
 136 +.br
 137 +.Fo srandom
 138 +.Fa "unsigned long seed"
 139 +.Fc ;
 140 +.Pp
 141 +The type of each parameter is different in the legacy version.
 142  .Sh SEE ALSO
 143  .Xr arc4random 3 ,
 144  .Xr rand 3 ,
 145  .Xr srand 3 ,
 146 -.Xr random 4
 147 +.Xr random 4 ,
 148 +.Xr compat 5
 149  .Sh HISTORY
 150  These
 151  functions appeared in