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