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