diff options
Diffstat (limited to 'src/lib/libc/stdlib/rand48.3')
-rw-r--r-- | src/lib/libc/stdlib/rand48.3 | 240 |
1 files changed, 0 insertions, 240 deletions
diff --git a/src/lib/libc/stdlib/rand48.3 b/src/lib/libc/stdlib/rand48.3 deleted file mode 100644 index fa7a7179bc..0000000000 --- a/src/lib/libc/stdlib/rand48.3 +++ /dev/null | |||
@@ -1,240 +0,0 @@ | |||
1 | .\" Copyright (c) 1993 Martin Birgmeier | ||
2 | .\" All rights reserved. | ||
3 | .\" | ||
4 | .\" You may redistribute unmodified or modified versions of this source | ||
5 | .\" code provided that the above copyright notice and this and the | ||
6 | .\" following conditions are retained. | ||
7 | .\" | ||
8 | .\" This software is provided ``as is'', and comes with no warranties | ||
9 | .\" of any kind. I shall in no event be liable for anything that happens | ||
10 | .\" to anyone/anything when using this software. | ||
11 | .\" | ||
12 | .\" $OpenBSD: rand48.3,v 1.21 2019/12/20 19:16:40 tb Exp $ | ||
13 | .\" | ||
14 | .Dd $Mdocdate: December 20 2019 $ | ||
15 | .Dt DRAND48 3 | ||
16 | .Os | ||
17 | .Sh NAME | ||
18 | .Nm drand48 , | ||
19 | .Nm erand48 , | ||
20 | .Nm lrand48 , | ||
21 | .Nm nrand48 , | ||
22 | .Nm mrand48 , | ||
23 | .Nm jrand48 , | ||
24 | .Nm srand48 , | ||
25 | .Nm srand48_deterministic , | ||
26 | .Nm seed48 , | ||
27 | .Nm seed48_deterministic , | ||
28 | .Nm lcong48 , | ||
29 | .Nm lcong48_deterministic | ||
30 | .Nd pseudo-random number generators and initialization routines | ||
31 | .Sh SYNOPSIS | ||
32 | .In stdlib.h | ||
33 | .Ft double | ||
34 | .Fn drand48 void | ||
35 | .Ft double | ||
36 | .Fn erand48 "unsigned short xseed[3]" | ||
37 | .Ft long | ||
38 | .Fn lrand48 void | ||
39 | .Ft long | ||
40 | .Fn nrand48 "unsigned short xseed[3]" | ||
41 | .Ft long | ||
42 | .Fn mrand48 void | ||
43 | .Ft long | ||
44 | .Fn jrand48 "unsigned short xseed[3]" | ||
45 | .Ft void | ||
46 | .Fn srand48 "long seed" | ||
47 | .Ft void | ||
48 | .Fn srand48_deterministic "long seed" | ||
49 | .Ft "unsigned short *" | ||
50 | .Fn seed48 "unsigned short xseed[3]" | ||
51 | .Ft "unsigned short *" | ||
52 | .Fn seed48_deterministic "unsigned short xseed[3]" | ||
53 | .Ft void | ||
54 | .Fn lcong48 "unsigned short p[7]" | ||
55 | .Ft void | ||
56 | .Fn lcong48_deterministic "unsigned short p[7]" | ||
57 | .Sh DESCRIPTION | ||
58 | .Bf -symbolic | ||
59 | Standards insist that this interface return deterministic results. | ||
60 | Unsafe usage is very common, so | ||
61 | .Ox | ||
62 | changed the subsystem to return non-deterministic results by default. | ||
63 | .Ef | ||
64 | .Pp | ||
65 | To satisfy portable code, | ||
66 | .Fn srand48 , | ||
67 | .Fn seed48 , | ||
68 | or | ||
69 | .Fn lcong48 | ||
70 | should be called to initialize the subsystem. | ||
71 | In | ||
72 | .Ox | ||
73 | the | ||
74 | seeding parameters are ignored, and strong random number results will be | ||
75 | provided from | ||
76 | .Xr arc4random 3 . | ||
77 | In other systems, the | ||
78 | parameters prime a simplistic deterministic algorithm. | ||
79 | .Pp | ||
80 | If the standardized behavior is required then | ||
81 | .Fn srand48_deterministic , | ||
82 | .Fn seed48_deterministic , | ||
83 | and | ||
84 | .Fn lcong48_deterministic | ||
85 | can be substituted for | ||
86 | .Fn srand48 , | ||
87 | .Fn seed48 , | ||
88 | and | ||
89 | .Fn lcong48 . | ||
90 | That will cause subsequent | ||
91 | calls to | ||
92 | .Fn drand48 , | ||
93 | .Fn lrand48 , | ||
94 | and | ||
95 | .Fn jrand48 | ||
96 | to return results using the deterministic algorithm. | ||
97 | .Pp | ||
98 | .Fn drand48 | ||
99 | and | ||
100 | .Fn erand48 | ||
101 | return values of type double. | ||
102 | The full 48 bits of r(n+1) are | ||
103 | loaded into the mantissa of the returned value, with the exponent set | ||
104 | such that the values produced lie in the interval [0.0, 1.0). | ||
105 | .Pp | ||
106 | .Fn lrand48 | ||
107 | and | ||
108 | .Fn nrand48 | ||
109 | return values of type long in the range | ||
110 | [0, 2**31-1]. | ||
111 | The high-order (31) bits of | ||
112 | r(n+1) are loaded into the lower bits of the returned value, with | ||
113 | the topmost (sign) bit set to zero. | ||
114 | .Pp | ||
115 | .Fn mrand48 | ||
116 | and | ||
117 | .Fn jrand48 | ||
118 | return values of type long in the range | ||
119 | [-2**31, 2**31-1]. | ||
120 | The high-order (32) bits of r(n+1) are loaded into the returned value. | ||
121 | .Pp | ||
122 | In the deterministic mode, the | ||
123 | .Fn rand48 | ||
124 | family of functions generates numbers using a linear congruential | ||
125 | algorithm working on integers 48 bits in size. | ||
126 | The particular formula employed is | ||
127 | r(n+1) = (a * r(n) + c) mod m | ||
128 | where the default values are | ||
129 | for the multiplicand a = 0xfdeece66d = 25214903917 and | ||
130 | the addend c = 0xb = 11. | ||
131 | The modulus is always fixed at m = 2 ** 48. | ||
132 | r(n) is called the seed of the random number generator. | ||
133 | .Pp | ||
134 | For all the six generator routines described next, the first | ||
135 | computational step is to perform a single iteration of the algorithm. | ||
136 | .Pp | ||
137 | .Fn drand48 , | ||
138 | .Fn lrand48 , | ||
139 | and | ||
140 | .Fn mrand48 | ||
141 | use an internal buffer to store r(n). | ||
142 | For these functions | ||
143 | the initial value of r(0) = 0x1234abcd330e = 20017429951246. | ||
144 | .Pp | ||
145 | On the other hand, | ||
146 | .Fn erand48 , | ||
147 | .Fn nrand48 , | ||
148 | and | ||
149 | .Fn jrand48 | ||
150 | use a user-supplied buffer to store the seed r(n), | ||
151 | which consists of an array of 3 shorts, where the zeroth member | ||
152 | holds the least significant bits. | ||
153 | .Pp | ||
154 | All functions share the same multiplicand and addend. | ||
155 | .Pp | ||
156 | .Fn srand48_deterministic | ||
157 | is used to initialize the internal buffer r(n) of | ||
158 | .Fn drand48 , | ||
159 | .Fn lrand48 , | ||
160 | and | ||
161 | .Fn mrand48 | ||
162 | such that the 32 bits of the seed value are copied into the upper 32 bits | ||
163 | of r(n), with the lower 16 bits of r(n) arbitrarily being set to 0x330e. | ||
164 | Additionally, the constant multiplicand and addend of the algorithm are | ||
165 | reset to the default values given above. | ||
166 | .Pp | ||
167 | .Fn seed48_deterministic | ||
168 | also initializes the internal buffer r(n) of | ||
169 | .Fn drand48 , | ||
170 | .Fn lrand48 , | ||
171 | and | ||
172 | .Fn mrand48 , | ||
173 | but here all 48 bits of the seed can be specified in an array of 3 shorts, | ||
174 | where the zeroth member specifies the lowest bits. | ||
175 | Again, the constant multiplicand and addend of the algorithm are | ||
176 | reset to the default values given above. | ||
177 | .Fn seed48_deterministic | ||
178 | returns a pointer to an array of 3 shorts which contains the old seed. | ||
179 | This array is statically allocated, so its contents are lost after | ||
180 | each new call to | ||
181 | .Fn seed48_deterministic . | ||
182 | .Pp | ||
183 | Finally, | ||
184 | .Fn lcong48_deterministic | ||
185 | allows full control over the multiplicand and addend used in | ||
186 | .Fn drand48 , | ||
187 | .Fn erand48 , | ||
188 | .Fn lrand48 , | ||
189 | .Fn nrand48 , | ||
190 | .Fn mrand48 , | ||
191 | and | ||
192 | .Fn jrand48 , | ||
193 | and the seed used in | ||
194 | .Fn drand48 , | ||
195 | .Fn lrand48 , | ||
196 | and | ||
197 | .Fn mrand48 . | ||
198 | An array of 7 shorts is passed as parameter; the first three shorts are | ||
199 | used to initialize the seed; the second three are used to initialize the | ||
200 | multiplicand; and the last short is used to initialize the addend. | ||
201 | It is thus not possible to use values greater than 0xffff as the addend. | ||
202 | .Pp | ||
203 | Note that all three methods of seeding the random number generator | ||
204 | always also set the multiplicand and addend for any of the six | ||
205 | generator calls. | ||
206 | .Sh SEE ALSO | ||
207 | .Xr arc4random 3 , | ||
208 | .Xr rand 3 , | ||
209 | .Xr random 3 | ||
210 | .Sh STANDARDS | ||
211 | The | ||
212 | .Fn drand48 , | ||
213 | .Fn erand48 , | ||
214 | .Fn jrand48 , | ||
215 | .Fn lrand48 , | ||
216 | .Fn mrand48 , | ||
217 | and | ||
218 | .Fn nrand48 , | ||
219 | functions conform to | ||
220 | .St -p1003.1-2008 . | ||
221 | .Pp | ||
222 | The | ||
223 | .Fn seed48 , | ||
224 | .Fn srand48 , | ||
225 | and | ||
226 | .Fn lcong48 | ||
227 | function do not conform to | ||
228 | .St -ansiC , | ||
229 | intentionally. | ||
230 | .Pp | ||
231 | The | ||
232 | .Fn seed48_deterministic , | ||
233 | .Fn srand48_deterministic , | ||
234 | and | ||
235 | .Fn lcong48_deterministic | ||
236 | functions are | ||
237 | .Ox | ||
238 | extensions. | ||
239 | .Sh AUTHORS | ||
240 | .An Martin Birgmeier | ||