summaryrefslogtreecommitdiff
path: root/src/lib/libc/stdlib/random.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libc/stdlib/random.3')
-rw-r--r--src/lib/libc/stdlib/random.3197
1 files changed, 0 insertions, 197 deletions
diff --git a/src/lib/libc/stdlib/random.3 b/src/lib/libc/stdlib/random.3
deleted file mode 100644
index 0770d20f09..0000000000
--- a/src/lib/libc/stdlib/random.3
+++ /dev/null
@@ -1,197 +0,0 @@
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
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-04-26 11:14:44 +0000