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