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.29 2021/02/12 17:03:51 deraadt Exp $ 29.\" 30.Dd $Mdocdate: February 12 2021 $ 31.Dt RANDOM 3 32.Os 33.Sh NAME 34.Nm random , 35.Nm srandom , 36.Nm srandom_deterministic , 37.Nm srandomdev , 38.Nm initstate , 39.Nm setstate 40.Nd pseudo-random number generator; routines for changing generators 41.Sh SYNOPSIS 42.In stdlib.h 43.Ft long 44.Fn random void 45.Ft void 46.Fn srandom "unsigned int seed" 47.Ft void 48.Fn srandom_deterministic "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 57Standards insist that this interface return deterministic results. 58Unsafe usage is very common, so 59.Ox 60changed the subsystem to return non-deterministic results by default. 61.Ef 62.Pp 63To satisfy portable code, 64.Fn srandom 65or 66.Fn srandomdev 67may be called to initialize the subsystem. 68In 69.Ox 70the 71.Ar seed 72variable is ignored, and strong random number results will be provided from 73.Xr arc4random 3 . 74In other systems, the 75.Ar seed 76variable primes a simplistic deterministic algorithm. 77.Pp 78If the standardized behavior is required 79.Fn srandom_deterministic 80can be substituted for 81.Fn srandom , 82then subsequent 83.Fn random 84calls will return results using the deterministic algorithm. 85.Pp 86In non-deterministic (default) mode, the 87.Fn random 88function returns results from 89.Xr arc4random 3 90in the range from 0 to (2**31)\-1. 91.Pp 92In deterministic mode, the 93.Fn random 94function uses a non-linear additive feedback random number generator employing 95a default table of size 31 long integers to return successive pseudo-random 96numbers in the range from 0 to (2**31)\-1. 97The period of this random number generator is very large, approximately 9816*((2**31)\-1), but the results are a deterministic sequence from the seed. 99The deterministic sequence algorithm changed a number of times since 100original development, is underspecified, and should not be relied upon to 101remain consistent between platforms and over time. 102.Pp 103The 104.Fn initstate 105routine allows a state array, passed in as an argument, to be initialized 106for future use. 107The size of the state array (in bytes) is used by 108.Fn initstate 109to decide how sophisticated a random number generator it should use \(em the 110more state, the better the random numbers will be. 111(Current "optimal" values for the amount of state information are 1128, 32, 64, 128, and 256 bytes; other amounts will be rounded down to 113the nearest known amount. 114Using less than 8 bytes will cause an error.) 115The seed for the initialization (which specifies a starting point for 116the random number sequence, and provides for restarting at the same 117point) is also an argument. 118The 119.Fn initstate 120function returns a pointer to the previous state information array. 121.Pp 122Once a state has been initialized, the 123.Fn setstate 124routine provides for rapid switching between states. 125The 126.Fn setstate 127function returns a pointer to the previous state array; its 128argument state array is used for further random number generation 129until the next call to 130.Fn initstate 131or 132.Fn setstate . 133.Pp 134Once a state array has been initialized, it may be restarted at a 135different point either by calling 136.Fn initstate 137(with the desired seed, the state array, and its size) or by calling 138both 139.Fn setstate 140(with the state array) and 141.Fn srandom 142(with the desired seed). 143The advantage of calling both 144.Fn setstate 145and 146.Fn srandom 147is that the size of the state array does not have to be remembered after 148it is initialized. 149.Pp 150Use of 151.Fn srandom_deterministic , 152.Fn initstate , 153or 154.Fn setstate 155forces the subsystem into deterministic mode. 156.Sh DIAGNOSTICS 157If 158.Fn initstate 159is called with less than 8 bytes of state information, or if 160.Fn setstate 161detects that the state information has been garbled, error 162messages are printed on the standard error output. 163.Sh SEE ALSO 164.Xr arc4random 3 , 165.Xr drand48 3 , 166.Xr rand 3 , 167.Xr random 4 168.Sh STANDARDS 169The 170.Fn random , 171.Fn initstate , 172and 173.Fn setstate 174functions conform to 175.St -xpg4.2 . 176.Pp 177The 178.Fn srandom 179function does not conform to 180.St -xpg4.2 , 181intentionally. 182.Pp 183The 184.Fn srandomdev 185function is an extension. 186.Pp 187The 188.Fn srandom_deterministic 189function is an 190.Ox 191extension. 192.Sh HISTORY 193These 194functions appeared in 195.Bx 4.2 . 196.Sh AUTHORS 197.An Earl T. Cohen 198