stdlib/FreeBSD/random.3

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)random.3    8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD: src/lib/libc/stdlib/random.3,v 1.22 2007/01/09 00:28:10 imp Exp $
  30 .\"
  31 .Dd June 4, 1993
  32 .Dt RANDOM 3
  33 .Os
  34 .Sh NAME
  35 .Nm initstate ,
  36 .Nm random ,
  37 .Nm setstate ,
  38 .Nm srandom ,
  39 .Nm srandomdev
  40 .Nd better random number generator; routines for changing generators
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In stdlib.h
  45 .Ft char *
  46 .Fo initstate
  47 .Fa "unsigned seed"
  48 .Fa "char *state"
  49 .Fa "size_t size"
  50 .Fc
  51 .Ft long
  52 .Fo random
  53 .Fa void
  54 .Fc
  55 .Ft char *
  56 .Fo setstate
  57 .Fa "const char *state"
  58 .Fc
  59 .Ft void
  60 .Fo srandom
  61 .Fa "unsigned seed"
  62 .Fc
  63 .Ft void
  64 .Fo srandomdev
  65 .Fa void
  66 .Fc
  67 .Sh DESCRIPTION
  68 The
  69 .Fn random
  70 function
  71 uses a non-linear, additive feedback, random number generator, employing a
  72 default table of size 31 long integers.
  73 It returns successive pseudo-random
  74 numbers in the range from 0 to
  75 .if t 2\u\s731\s10\d\(mi1.
  76 .if n (2**31)\(mi1.
  77 The period of this random number generator is very large, approximately
  78 .if t 16\(mu(2\u\s731\s10\d\(mi1).
  79 .if n 16*((2**31)\(mi1).
  80 .Pp
  81 The
  82 .Fn random
  83 and
  84 .Fn srandom
  85 functions have (almost) the same calling sequence and initialization properties as the
  86 .Xr rand 3
  87 and
  88 .Xr srand 3
  89 functions.
  90 The difference is that
  91 .Xr rand 3
  92 produces a much less random sequence \(em in fact, the low dozen bits
  93 generated by rand go through a cyclic pattern.
  94 All of the bits generated by
  95 .Fn random
  96 are usable.
  97 For example,
  98 .Sq Li random()&01
  99 will produce a random binary
 100 value.
 101 .Pp
 102 Like
 103 .Xr srand 3 ,
 104 .Fn srandom
 105 sets the initial seed value for future calls to
 106 .Fn random .
 107 Like
 108 .Xr rand 3 ,
 109 .Fn random
 110 will by default produce a sequence of numbers that can be duplicated
 111 by calling
 112 .Fn srandom
 113 with the same seed.
 114 .Pp
 115 The
 116 .Fn srandomdev
 117 routine initializes a state array, using the
 118 .Xr random 4
 119 random number device which returns good random numbers,
 120 suitable for cryptographic use.
 121 Note that this particular seeding
 122 procedure can generate states which are impossible to reproduce by
 123 calling
 124 .Fn srandom
 125 with any value, since the succeeding terms in the
 126 state buffer are no longer derived from the LC algorithm applied to
 127 a fixed seed.
 128 .Pp
 129 The
 130 .Fn initstate
 131 routine allows a state array, passed in as an argument, to be initialized
 132 for future use.
 133 The size of the state array (in bytes) is used by
 134 .Fn initstate
 135 to decide how sophisticated a random number generator it should use \(em the
 136 more state, the better the random numbers will be.
 137 (Current "optimal" values for the amount of state information are
 138 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to
 139 the nearest known amount.
 140 Using less than 8 bytes will cause an error.)
 141 The seed for the initialization (which specifies a starting point for
 142 the random number sequence and provides for restarting at the same
 143 point) is also an argument.
 144 The
 145 .Fn initstate
 146 function
 147 returns a pointer to the previous state information array.
 148 .Pp
 149 Once a state has been initialized, the
 150 .Fn setstate
 151 routine provides for rapid switching between states.
 152 The
 153 .Fn setstate
 154 function
 155 returns a pointer to the previous state array; its
 156 argument state array is used for further random number generation
 157 until the next call to
 158 .Fn initstate
 159 or
 160 .Fn setstate .
 161 .Pp
 162 Once a state array has been initialized, it may be restarted at a
 163 different point either by calling
 164 .Fn initstate
 165 (with the desired seed, the state array, and its size) or by calling
 166 both
 167 .Fn setstate
 168 (with the state array) and
 169 .Fn srandom
 170 (with the desired seed).
 171 The advantage of calling both
 172 .Fn setstate
 173 and
 174 .Fn srandom
 175 is that the size of the state array does not have to be remembered after
 176 it is initialized.
 177 .Pp
 178 With 256 bytes of state information, the period of the random number
 179 generator is greater than
 180 .if t 2\u\s769\s10\d,
 181 .if n 2**69 ,
 182 which should be sufficient for most purposes.
 183 .Sh DIAGNOSTICS
 184 If
 185 .Fn initstate
 186 is called with less than 8 bytes of state information, or if
 187 .Fn setstate
 188 detects that the state information has been garbled, error
 189 messages are printed on the standard error output.
 190 .Sh LEGACY SYNOPSIS
 191 .Fd #include <stdlib.h>
 192 .Pp
 193 .Ft char *
 194 .br
 195 .Fo initstate
 196 .Fa "unsigned long seed"
 197 .Fa "char *state"
 198 .Fa "long size"
 199 .Fc ;
 200 .Pp
 201 .Ft char *
 202 .br
 203 .Fo setstate
 204 .Fa "char *state"
 205 .Fc ;
 206 .Pp
 207 .Ft void
 208 .br
 209 .Fo srandom
 210 .Fa "unsigned long seed"
 211 .Fc ;
 212 .Pp
 213 The type of each parameter is different in the legacy version.
 214 .Sh SEE ALSO
 215 .Xr arc4random 3 ,
 216 .Xr rand 3 ,
 217 .Xr srand 3 ,
 218 .Xr random 4 ,
 219 .Xr compat 5
 220 .Sh HISTORY
 221 These
 222 functions appeared in
 223 .Bx 4.2 .
 224 .Sh AUTHORS
 225 .An Earl T. Cohen
 226 .Sh BUGS
 227 About 2/3 the speed of
 228 .Xr rand 3 .
 229 .Pp
 230 The historical implementation used to have a very weak seeding; the
 231 random sequence did not vary much with the seed.
 232 The current implementation employs a better pseudo-random number
 233 generator for the initial state calculation.
 234 .Pp
 235 Applications requiring cryptographic quality randomness should use
 236 .Xr arc4random 3 .