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.28 2014/12/09 21:55:39 jmc Exp $ 29.\" 30.Dd $Mdocdate: December 9 2014 $ 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. 99.Pp 100The 101.Fn initstate 102routine allows a state array, passed in as an argument, to be initialized 103for future use. 104The size of the state array (in bytes) is used by 105.Fn initstate 106to decide how sophisticated a random number generator it should use \(em the 107more state, the better the random numbers will be. 108(Current "optimal" values for the amount of state information are 1098, 32, 64, 128, and 256 bytes; other amounts will be rounded down to 110the nearest known amount. 111Using less than 8 bytes will cause an error.) 112The seed for the initialization (which specifies a starting point for 113the random number sequence, and provides for restarting at the same 114point) is also an argument. 115The 116.Fn initstate 117function returns a pointer to the previous state information array. 118.Pp 119Once a state has been initialized, the 120.Fn setstate 121routine provides for rapid switching between states. 122The 123.Fn setstate 124function returns a pointer to the previous state array; its 125argument state array is used for further random number generation 126until the next call to 127.Fn initstate 128or 129.Fn setstate . 130.Pp 131Once a state array has been initialized, it may be restarted at a 132different point either by calling 133.Fn initstate 134(with the desired seed, the state array, and its size) or by calling 135both 136.Fn setstate 137(with the state array) and 138.Fn srandom 139(with the desired seed). 140The advantage of calling both 141.Fn setstate 142and 143.Fn srandom 144is that the size of the state array does not have to be remembered after 145it is initialized. 146.Pp 147Use of 148.Fn srandom_deterministic , 149.Fn initstate , 150or 151.Fn setstate 152forces the subsystem into deterministic mode. 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 arc4random 3 , 162.Xr drand48 3 , 163.Xr rand 3 , 164.Xr random 4 165.Sh STANDARDS 166The 167.Fn random , 168.Fn initstate , 169and 170.Fn setstate 171functions conform to 172.St -xpg4.2 . 173.Pp 174The 175.Fn srandom 176function does not conform to 177.St -xpg4.2 , 178intentionally. 179.Pp 180The 181.Fn srandomdev 182function is an extension. 183.Pp 184The 185.Fn srandom_deterministic 186function is an 187.Ox 188extension. 189.Sh HISTORY 190These 191functions appeared in 192.Bx 4.2 . 193.Sh AUTHORS 194.An Earl T. Cohen 195