-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathBSD-Random.html
More file actions
186 lines (159 loc) · 8.59 KB
/
BSD-Random.html
File metadata and controls
186 lines (159 loc) · 8.59 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
<html lang="en">
<head>
<title>BSD Random - The GNU C Library</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="The GNU C Library">
<meta name="generator" content="makeinfo 4.9">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Pseudo_002dRandom-Numbers.html#Pseudo_002dRandom-Numbers" title="Pseudo-Random Numbers">
<link rel="prev" href="ISO-Random.html#ISO-Random" title="ISO Random">
<link rel="next" href="SVID-Random.html#SVID-Random" title="SVID Random">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This file documents the GNU C library.
This is Edition 0.11, last updated 2007-09-09,
of `The GNU C Library Reference Manual', for version 2.7.
Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software Needs Free Documentation''
and ``GNU Lesser General Public License'', the Front-Cover texts being
``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A
copy of the license is included in the section entitled "GNU Free
Documentation License".
(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
this GNU Manual. Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom.''-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<p>
<a name="BSD-Random"></a>
Next: <a rel="next" accesskey="n" href="SVID-Random.html#SVID-Random">SVID Random</a>,
Previous: <a rel="previous" accesskey="p" href="ISO-Random.html#ISO-Random">ISO Random</a>,
Up: <a rel="up" accesskey="u" href="Pseudo_002dRandom-Numbers.html#Pseudo_002dRandom-Numbers">Pseudo-Random Numbers</a>
<hr>
</div>
<h4 class="subsection">19.8.2 BSD Random Number Functions</h4>
<p>This section describes a set of random number generation functions that
are derived from BSD. There is no advantage to using these functions
with the GNU C library; we support them for BSD compatibility only.
<p>The prototypes for these functions are in <samp><span class="file">stdlib.h</span></samp>.
<a name="index-stdlib_002eh-2289"></a>
<!-- stdlib.h -->
<!-- BSD -->
<div class="defun">
— Function: long int <b>random</b> (<var>void</var>)<var><a name="index-random-2290"></a></var><br>
<blockquote><p>This function returns the next pseudo-random number in the sequence.
The value returned ranges from <code>0</code> to <code>RAND_MAX</code>.
<p><strong>Note:</strong> Temporarily this function was defined to return a
<code>int32_t</code> value to indicate that the return value always contains
32 bits even if <code>long int</code> is wider. The standard demands it
differently. Users must always be aware of the 32-bit limitation,
though.
</p></blockquote></div>
<!-- stdlib.h -->
<!-- BSD -->
<div class="defun">
— Function: void <b>srandom</b> (<var>unsigned int seed</var>)<var><a name="index-srandom-2291"></a></var><br>
<blockquote><p>The <code>srandom</code> function sets the state of the random number
generator based on the integer <var>seed</var>. If you supply a <var>seed</var> value
of <code>1</code>, this will cause <code>random</code> to reproduce the default set
of random numbers.
<p>To produce a different set of pseudo-random numbers each time your
program runs, do <code>srandom (time (0))</code>.
</p></blockquote></div>
<!-- stdlib.h -->
<!-- BSD -->
<div class="defun">
— Function: void * <b>initstate</b> (<var>unsigned int seed, void *state, size_t size</var>)<var><a name="index-initstate-2292"></a></var><br>
<blockquote><p>The <code>initstate</code> function is used to initialize the random number
generator state. The argument <var>state</var> is an array of <var>size</var>
bytes, used to hold the state information. It is initialized based on
<var>seed</var>. The size must be between 8 and 256 bytes, and should be a
power of two. The bigger the <var>state</var> array, the better.
<p>The return value is the previous value of the state information array.
You can use this value later as an argument to <code>setstate</code> to
restore that state.
</p></blockquote></div>
<!-- stdlib.h -->
<!-- BSD -->
<div class="defun">
— Function: void * <b>setstate</b> (<var>void *state</var>)<var><a name="index-setstate-2293"></a></var><br>
<blockquote><p>The <code>setstate</code> function restores the random number state
information <var>state</var>. The argument must have been the result of
a previous call to <var>initstate</var> or <var>setstate</var>.
<p>The return value is the previous value of the state information array.
You can use this value later as an argument to <code>setstate</code> to
restore that state.
<p>If the function fails the return value is <code>NULL</code>.
</p></blockquote></div>
<p>The four functions described so far in this section all work on a state
which is shared by all threads. The state is not directly accessible to
the user and can only be modified by these functions. This makes it
hard to deal with situations where each thread should have its own
pseudo-random number generator.
<p>The GNU C library contains four additional functions which contain the
state as an explicit parameter and therefore make it possible to handle
thread-local PRNGs. Beside this there are no difference. In fact, the
four functions already discussed are implemented internally using the
following interfaces.
<p>The <samp><span class="file">stdlib.h</span></samp> header contains a definition of the following type:
<!-- stdlib.h -->
<!-- GNU -->
<div class="defun">
— Data Type: <b>struct random_data</b><var><a name="index-struct-random_005fdata-2294"></a></var><br>
<blockquote>
<p>Objects of type <code>struct random_data</code> contain the information
necessary to represent the state of the PRNG. Although a complete
definition of the type is present the type should be treated as opaque.
</p></blockquote></div>
<p>The functions modifying the state follow exactly the already described
functions.
<!-- stdlib.h -->
<!-- GNU -->
<div class="defun">
— Function: int <b>random_r</b> (<var>struct random_data *restrict buf, int32_t *restrict result</var>)<var><a name="index-random_005fr-2295"></a></var><br>
<blockquote><p>The <code>random_r</code> function behaves exactly like the <code>random</code>
function except that it uses and modifies the state in the object
pointed to by the first parameter instead of the global state.
</p></blockquote></div>
<!-- stdlib.h -->
<!-- GNU -->
<div class="defun">
— Function: int <b>srandom_r</b> (<var>unsigned int seed, struct random_data *buf</var>)<var><a name="index-srandom_005fr-2296"></a></var><br>
<blockquote><p>The <code>srandom_r</code> function behaves exactly like the <code>srandom</code>
function except that it uses and modifies the state in the object
pointed to by the second parameter instead of the global state.
</p></blockquote></div>
<!-- stdlib.h -->
<!-- GNU -->
<div class="defun">
— Function: int <b>initstate_r</b> (<var>unsigned int seed, char *restrict statebuf, size_t statelen, struct random_data *restrict buf</var>)<var><a name="index-initstate_005fr-2297"></a></var><br>
<blockquote><p>The <code>initstate_r</code> function behaves exactly like the <code>initstate</code>
function except that it uses and modifies the state in the object
pointed to by the fourth parameter instead of the global state.
</p></blockquote></div>
<!-- stdlib.h -->
<!-- GNU -->
<div class="defun">
— Function: int <b>setstate_r</b> (<var>char *restrict statebuf, struct random_data *restrict buf</var>)<var><a name="index-setstate_005fr-2298"></a></var><br>
<blockquote><p>The <code>setstate_r</code> function behaves exactly like the <code>setstate</code>
function except that it uses and modifies the state in the object
pointed to by the first parameter instead of the global state.
</p></blockquote></div>
</body></html>