1.\" $NetBSD: random.3,v 1.4 1995/12/28 08:52:42 thorpej Exp $ 2.\" 3.\" Copyright (c) 1983, 1991 The Regents of the University of California. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" from: @(#)random.3 6.5 (Berkeley) 4/19/91 35.\" 36.Dd April 19, 1991 37.Dt RANDOM 3 38.Os BSD 4.2 39.Sh NAME 40.Nm random , 41.Nm srandom , 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 seed" 51.Ft char * 52.Fn initstate "unsigned seed" "char *state" "int n" 53.Ft char * 54.Fn setstate "char *state" 55.Sh DESCRIPTION 56The 57.Fn random 58function 59uses a non-linear additive feedback random number generator employing a 60default table of size 31 long integers to return successive pseudo-random 61numbers in the range from 0 to 62.if t 2\u\s731\s10\d\(mi1. 63.if n (2**31)\(mi1. 64The period of this random number generator is very large, approximately 65.if t 16\(mu(2\u\s731\s10\d\(mi1). 66.if n 16*((2**31)\(mi1). 67.Pp 68The 69.Fn random Ns / Fn srandom 70have (almost) the same calling sequence and initialization properties as 71.Xr rand 3 Ns / Xr srand 3 . 72The difference is that 73.Xr rand 74produces a much less random sequence \(em in fact, the low dozen bits 75generated by rand go through a cyclic pattern. All the bits generated by 76.Fn random 77are usable. For example, 78.Sq Li random()&01 79will produce a random binary 80value. 81.Pp 82Unlike 83.Xr srand , 84.Fn srandom 85does not return the old seed; the reason for this is that the amount of 86state information used is much more than a single word. (Two other 87routines are provided to deal with restarting/changing random 88number generators). Like 89.Xr rand 3 , 90however, 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 initstate 101routine allows a state array, passed in as an argument, to be initialized 102for future use. The size of the state array (in bytes) is used by 103.Fn initstate 104to decide how sophisticated a random number generator it should use \(em the 105more state, the better the random numbers will be. 106(Current "optimal" values for the amount of state information are 1078, 32, 64, 128, and 256 bytes; other amounts will be rounded down to 108the nearest known amount. Using less than 8 bytes will cause an error.) 109The seed for the initialization (which specifies a starting point for 110the random number sequence, and provides for restarting at the same 111point) is also an argument. 112The 113.Fn initstate 114function 115returns a pointer to the previous state information array. 116.Pp 117Once a state has been initialized, the 118.Fn setstate 119routine provides for rapid switching between states. 120The 121.Fn setstate 122function 123returns a pointer to the previous state array; its 124argument state array is used for further random number generation 125until the next call to 126.Fn initstate 127or 128.Fn setstate . 129.Pp 130Once a state array has been initialized, it may be restarted at a 131different point either by calling 132.Fn initstate 133(with the desired seed, the state array, and its size) or by calling 134both 135.Fn setstate 136(with the state array) and 137.Fn srandom 138(with the desired seed). 139The advantage of calling both 140.Fn setstate 141and 142.Fn srandom 143is that the size of the state array does not have to be remembered after 144it is initialized. 145.Pp 146With 256 bytes of state information, the period of the random number 147generator is greater than 148.if t 2\u\s769\s10\d, 149.if n 2**69 150which should be sufficient for most purposes. 151.Sh AUTHOR 152Earl T. Cohen 153.Sh DIAGNOSTICS 154If 155.Fn initstate 156is called with less than 8 bytes of state information, or if 157.Fn setstate 158detects that the state information has been garbled, error 159messages are printed on the standard error output. 160.Sh SEE ALSO 161.Xr rand 3 162.Sh HISTORY 163These 164functions appeared in 165.Bx 4.2 . 166.Sh BUGS 167About 2/3 the speed of 168.Xr rand 3 . 169