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