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 .\" $DragonFly: src/lib/libcr/stdlib/Attic/random.3,v 1.2 2003/06/17 04:26:46 dillon Exp $
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt RANDOM 3
  38 .Os
  39 .Sh NAME
  40 .Nm random ,
  41 .Nm srandom ,
  42 .Nm srandomdev ,
  43 .Nm initstate ,
  44 .Nm setstate
  45 .Nd better random number generator; routines for changing generators
  46 .Sh LIBRARY
  47 .Lb libc
  48 .Sh SYNOPSIS
  49 .In stdlib.h
  50 .Ft long
  51 .Fn random void
  52 .Ft void
  53 .Fn srandom "unsigned long seed"
  54 .Ft void
  55 .Fn srandomdev void
  56 .Ft char *
  57 .Fn initstate "unsigned long seed" "char *state" "long n"
  58 .Ft char *
  59 .Fn setstate "char *state"
  60 .Sh DESCRIPTION
  61 The
  62 .Fn random
  63 function
  64 uses a non-linear additive feedback random number generator employing a
  65 default table of size 31 long integers to return successive pseudo-random
  66 numbers in the range from 0 to
  67 .if t 2\u\s731\s10\d\(mi1.
  68 .if n (2**31)\(mi1.
  69 The period of this random number generator is very large, approximately
  70 .if t 16\(mu(2\u\s731\s10\d\(mi1).
  71 .if n 16*((2**31)\(mi1).
  72 .Pp
  73 The
  74 .Fn random
  75 and
  76 .Fn srandom
  77 functions have (almost) the same calling sequence and initialization properties as the
  78 .Xr rand 3
  79 and
  80 .Xr srand 3
  81 functions.
  82 The difference is that
  83 .Xr rand 3
  84 produces a much less random sequence \(em in fact, the low dozen bits
  85 generated by rand go through a cyclic pattern.  All the bits generated by
  86 .Fn random
  87 are usable.  For example,
  88 .Sq Li random()&01
  89 will produce a random binary
  90 value.
  91 .Pp
  92 Like
  93 .Xr rand 3 ,
  94 .Fn random
  95 will by default produce a sequence of numbers that can be duplicated
  96 by calling
  97 .Fn srandom
  98 with
  99 .Ql 1
 100 as the seed.
 101 .Pp
 102 The
 103 .Fn srandomdev
 104 routine initializes a state array using the
 105 .Xr urandom 4
 106 random number device which returns good random numbers,
 107 suitable for cryptographic use.
 108 Note that this particular seeding
 109 procedure can generate states which are impossible to reproduce by
 110 calling
 111 .Fn srandom
 112 with any value, since the succeeding terms in the
 113 state buffer are no longer derived from the LC algorithm applied to
 114 a fixed seed.
 115 .Pp
 116 The
 117 .Fn initstate
 118 routine allows a state array, passed in as an argument, to be initialized
 119 for future use.  The size of the state array (in bytes) is used by
 120 .Fn initstate
 121 to decide how sophisticated a random number generator it should use \(em the
 122 more state, the better the random numbers will be.
 123 (Current "optimal" values for the amount of state information are
 124 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to
 125 the nearest known amount.  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 AUTHORS
 169 .An Earl T. Cohen
 170 .Sh DIAGNOSTICS
 171 If
 172 .Fn initstate
 173 is called with less than 8 bytes of state information, or if
 174 .Fn setstate
 175 detects that the state information has been garbled, error
 176 messages are printed on the standard error output.
 177 .Sh SEE ALSO
 178 .Xr rand 3 ,
 179 .Xr srand 3 ,
 180 .Xr urandom 4
 181 .Sh HISTORY
 182 These
 183 functions appeared in
 184 .Bx 4.2 .
 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.