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 .\" 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 random ,
  40 .Nm srandom ,
  41 .Nm srandomdev ,
  42 .Nm initstate ,
  43 .Nm setstate
  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 long
  50 .Fn random void
  51 .Ft void
  52 .Fn srandom "unsigned long seed"
  53 .Ft void
  54 .Fn srandomdev void
  55 .Ft char *
  56 .Fn initstate "unsigned long seed" "char *state" "long n"
  57 .Ft char *
  58 .Fn setstate "char *state"
  59 .Sh DESCRIPTION
  60 The
  61 .Fn random
  62 function
  63 uses a non-linear additive feedback random number generator employing a
  64 default table of size 31 long integers to return successive pseudo-random
  65 numbers in the range from 0 to
  66 .if t 2\u\s731\s10\d\(mi1.
  67 .if n (2**31)\(mi1.
  68 The period of this random number generator is very large, approximately
  69 .if t 16\(mu(2\u\s731\s10\d\(mi1).
  70 .if n 16*((2**31)\(mi1).
  71 .Pp
  72 The
  73 .Fn random
  74 and
  75 .Fn srandom
  76 functions have (almost) the same calling sequence and initialization properties as the
  77 .Xr rand 3
  78 and
  79 .Xr srand 3
  80 functions.
  81 The difference is that
  82 .Xr rand 3
  83 produces a much less random sequence \(em in fact, the low dozen bits
  84 generated by rand go through a cyclic pattern.
  85 All the bits generated by
  86 .Fn random
  87 are usable.
  88 For example,
  89 .Sq Li random()&01
  90 will produce a random binary
  91 value.
  92 .Pp
  93 Like
  94 .Xr rand 3 ,
  95 .Fn random
  96 will by default produce a sequence of numbers that can be duplicated
  97 by calling
  98 .Fn srandom
  99 with
 100 .Ql 1
 101 as the seed.
 102 .Pp
 103 The
 104 .Fn srandomdev
 105 routine initializes a state array using the
 106 .Xr random 4
 107 random number device which returns good random numbers,
 108 suitable for cryptographic use.
 109 Note that this particular seeding
 110 procedure can generate states which are impossible to reproduce by
 111 calling
 112 .Fn srandom
 113 with any value, since the succeeding terms in the
 114 state buffer are no longer derived from the LC algorithm applied to
 115 a fixed seed.
 116 .Pp
 117 The
 118 .Fn initstate
 119 routine allows a state array, passed in as an argument, to be initialized
 120 for future use.
 121 The size of the state array (in bytes) is used by
 122 .Fn initstate
 123 to decide how sophisticated a random number generator it should use \(em the
 124 more state, the better the random numbers will be.
 125 (Current "optimal" values for the amount of state information are
 126 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to
 127 the nearest known amount.
 128 Using less than 8 bytes will cause an error.)
 129 The seed for the initialization (which specifies a starting point for
 130 the random number sequence, and provides for restarting at the same
 131 point) is also an argument.
 132 The
 133 .Fn initstate
 134 function
 135 returns a pointer to the previous state information array.
 136 .Pp
 137 Once a state has been initialized, the
 138 .Fn setstate
 139 routine provides for rapid switching between states.
 140 The
 141 .Fn setstate
 142 function
 143 returns a pointer to the previous state array; its
 144 argument state array is used for further random number generation
 145 until the next call to
 146 .Fn initstate
 147 or
 148 .Fn setstate .
 149 .Pp
 150 Once a state array has been initialized, it may be restarted at a
 151 different point either by calling
 152 .Fn initstate
 153 (with the desired seed, the state array, and its size) or by calling
 154 both
 155 .Fn setstate
 156 (with the state array) and
 157 .Fn srandom
 158 (with the desired seed).
 159 The advantage of calling both
 160 .Fn setstate
 161 and
 162 .Fn srandom
 163 is that the size of the state array does not have to be remembered after
 164 it is initialized.
 165 .Pp
 166 With 256 bytes of state information, the period of the random number
 167 generator is greater than
 168 .if t 2\u\s769\s10\d,
 169 .if n 2**69
 170 which should be sufficient for most purposes.
 171 .Sh AUTHORS
 172 .An Earl T. Cohen
 173 .Sh DIAGNOSTICS
 174 If
 175 .Fn initstate
 176 is called with less than 8 bytes of state information, or if
 177 .Fn setstate
 178 detects that the state information has been garbled, error
 179 messages are printed on the standard error output.
 180 .Sh SEE ALSO
 181 .Xr arc4random 3 ,
 182 .Xr rand 3 ,
 183 .Xr srand 3 ,
 184 .Xr random 4
 185 .Sh HISTORY
 186 These
 187 functions appeared in
 188 .Bx 4.2 .
 189 .Sh BUGS
 190 About 2/3 the speed of
 191 .Xr rand 3 .
 192 .Pp
 193 The historical implementation used to have a very weak seeding; the
 194 random sequence did not vary much with the seed.
 195 The current implementation employs a better pseudo-random number
 196 generator for the initial state calculation.
 197 .Pp
 198 Applications requiring cryptographic quality randomness should use
 199 .Xr arc4random 3 .