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