lib/libcr/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.11.2.6 2003/06/03 19:13:16 schweikh 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.  All the bits generated by
  85 .Fn random
  86 are usable.  For example,
  87 .Sq Li random()&01
  88 will produce a random binary
  89 value.
  90 .Pp
  91 Like
  92 .Xr rand 3 ,
  93 .Fn random
  94 will by default produce a sequence of numbers that can be duplicated
  95 by calling
  96 .Fn srandom
  97 with
  98 .Ql 1
  99 as the seed.
 100 .Pp
 101 The
 102 .Fn srandomdev
 103 routine initializes a state array using the
 104 .Xr urandom 4
 105 random number device which returns good random numbers,
 106 suitable for cryptographic use.
 107 Note that this particular seeding
 108 procedure can generate states which are impossible to reproduce by
 109 calling
 110 .Fn srandom
 111 with any value, since the succeeding terms in the
 112 state buffer are no longer derived from the LC algorithm applied to
 113 a fixed seed.
 114 .Pp
 115 The
 116 .Fn initstate
 117 routine allows a state array, passed in as an argument, to be initialized
 118 for future use.  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.  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 AUTHORS
 168 .An Earl T. Cohen
 169 .Sh DIAGNOSTICS
 170 If
 171 .Fn initstate
 172 is called with less than 8 bytes of state information, or if
 173 .Fn setstate
 174 detects that the state information has been garbled, error
 175 messages are printed on the standard error output.
 176 .Sh SEE ALSO
 177 .Xr rand 3 ,
 178 .Xr srand 3 ,
 179 .Xr urandom 4
 180 .Sh HISTORY
 181 These
 182 functions appeared in
 183 .Bx 4.2 .
 184 .Sh BUGS
 185 About 2/3 the speed of
 186 .Xr rand 3 .
 187 .Pp
 188 The historical implementation used to have a very weak seeding; the
 189 random sequence did not vary much with the seed.
 190 The current implementation employs a better pseudo-random number
 191 generator for the initial state calculation.