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