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