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