-
Notifications
You must be signed in to change notification settings - Fork 0
/
getrandom.html
375 lines (283 loc) · 11.3 KB
/
getrandom.html
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
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
<!-- Creator : groff version 1.22.4 -->
<!-- CreationDate: Wed Jan 29 11:26:17 2020 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>GETRANDOM</title>
</head>
<body>
<h1 align="center">GETRANDOM</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#RETURN VALUE">RETURN VALUE</a><br>
<a href="#ERRORS">ERRORS</a><br>
<a href="#VERSIONS">VERSIONS</a><br>
<a href="#CONFORMING TO">CONFORMING TO</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#BUGS">BUGS</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#COLOPHON">COLOPHON</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">getrandom -
obtain a series of random bytes</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>#include
<sys/random.h></b></p>
<p style="margin-left:11%; margin-top: 1em"><b>ssize_t
getrandom(void *</b><i>buf</i><b>, size_t</b>
<i>buflen</i><b>, unsigned int</b> <i>flags</i><b>);</b></p>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The
<b>getrandom</b>() system call fills the buffer pointed to
by <i>buf</i> with up to <i>buflen</i> random bytes. These
bytes can be used to seed user-space random number
generators or for cryptographic purposes.</p>
<p style="margin-left:11%; margin-top: 1em">By default,
<b>getrandom</b>() draws entropy from the <i>urandom</i>
source (i.e., the same source as the <i>/dev/urandom</i>
device). This behavior can be changed via the <i>flags</i>
argument.</p>
<p style="margin-left:11%; margin-top: 1em">If the
<i>urandom</i> source has been initialized, reads of up to
256 bytes will always return as many bytes as requested and
will not be interrupted by signals. No such guarantees apply
for larger buffer sizes. For example, if the call is
interrupted by a signal handler, it may return a partially
filled buffer, or fail with the error <b>EINTR</b>.</p>
<p style="margin-left:11%; margin-top: 1em">If the
<i>urandom</i> source has not yet been initialized, then
<b>getrandom</b>() will block, unless <b>GRND_NONBLOCK</b>
is specified in <i>flags</i>.</p>
<p style="margin-left:11%; margin-top: 1em">The
<i>flags</i> argument is a bit mask that can contain zero or
more of the following values ORed together: <b><br>
GRND_RANDOM</b></p>
<p style="margin-left:22%;">If this bit is set, then random
bytes are drawn from the <i>random</i> source (i.e., the
same source as the <i>/dev/random</i> device) instead of the
<i>urandom</i> source. The <i>random</i> source is limited
based on the entropy that can be obtained from environmental
noise. If the number of available bytes in the <i>random</i>
source is less than requested in <i>buflen</i>, the call
returns just the available random bytes. If no random bytes
are available, the behavior depends on the presence of
<b>GRND_NONBLOCK</b> in the <i>flags</i> argument.</p>
<p style="margin-left:11%;"><b>GRND_NONBLOCK</b></p>
<p style="margin-left:22%;">By default, when reading from
the <i>random</i> source, <b>getrandom</b>() blocks if no
random bytes are available, and when reading from the
<i>urandom</i> source, it blocks if the entropy pool has not
yet been initialized. If the <b>GRND_NONBLOCK</b> flag is
set, then <b>getrandom</b>() does not block in these cases,
but instead immediately returns -1 with <i>errno</i> set to
<b>EAGAIN</b>.</p>
<h2>RETURN VALUE
<a name="RETURN VALUE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">On success,
<b>getrandom</b>() returns the number of bytes that were
copied to the buffer <i>buf</i>. This may be less than the
number of bytes requested via <i>buflen</i> if either
<b>GRND_RANDOM</b> was specified in <i>flags</i> and
insufficient entropy was present in the <i>random</i> source
or the system call was interrupted by a signal.</p>
<p style="margin-left:11%; margin-top: 1em">On error, -1 is
returned, and <i>errno</i> is set appropriately.</p>
<h2>ERRORS
<a name="ERRORS"></a>
</h2>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p style="margin-top: 1em"><b>EAGAIN</b></p></td>
<td width="2%"></td>
<td width="78%">
<p style="margin-top: 1em">The requested entropy was not
available, and <b>getrandom</b>() would have blocked if the
<b>GRND_NONBLOCK</b> flag was not set.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EFAULT</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>The address referred to by <i>buf</i> is outside the
accessible address space.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINTR</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>The call was interrupted by a signal handler; see the
description of how interrupted <b>read</b>(2) calls on
"slow" devices are handled with and without the
<b>SA_RESTART</b> flag in the <b>signal</b>(7) man page.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>An invalid flag was specified in <i>flags</i>.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>ENOSYS</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>The glibc wrapper function for <b>getrandom</b>()
determined that the underlying kernel does not implement
this system call.</p></td></tr>
</table>
<h2>VERSIONS
<a name="VERSIONS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>getrandom</b>()
was introduced in version 3.17 of the Linux kernel. Support
was added to glibc in version 2.25.</p>
<h2>CONFORMING TO
<a name="CONFORMING TO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">This system
call is Linux-specific.</p>
<h2>NOTES
<a name="NOTES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">For an overview
and comparison of the various interfaces that can be used to
obtain randomness, see <b>random</b>(7).</p>
<p style="margin-left:11%; margin-top: 1em">Unlike
<i>/dev/random</i> and <i>/dev/urandom</i>,
<b>getrandom</b>() does not involve the use of pathnames or
file descriptors. Thus, <b>getrandom</b>() can be useful in
cases where <b>chroot</b>(2) makes <i>/dev</i> pathnames
invisible, and where an application (e.g., a daemon during
start-up) closes a file descriptor for one of these files
that was opened by a library.</p>
<p style="margin-left:11%; margin-top: 1em"><b>Maximum
number of bytes returned</b> <br>
As of Linux 3.19 the following limits apply:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="1%">
<p style="margin-top: 1em">*</p></td>
<td width="3%"></td>
<td width="85%">
<p style="margin-top: 1em">When reading from the
<i>urandom</i> source, a maximum of 33554431 bytes is
returned by a single call to <b>getrandom</b>() on systems
where <i>int</i> has a size of 32 bits.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="1%">
<p>*</p></td>
<td width="3%"></td>
<td width="85%">
<p>When reading from the <i>random</i> source, a maximum of
512 bytes is returned.</p></td></tr>
</table>
<p style="margin-left:11%; margin-top: 1em"><b>Interruption
by a signal handler</b> <br>
When reading from the <i>urandom</i> source
(<b>GRND_RANDOM</b> is not set), <b>getrandom</b>() will
block until the entropy pool has been initialized (unless
the <b>GRND_NONBLOCK</b> flag was specified). If a request
is made to read a large number of bytes (more than 256),
<b>getrandom</b>() will block until those bytes have been
generated and transferred from kernel memory to <i>buf</i>.
When reading from the <i>random</i> source
(<b>GRND_RANDOM</b> is set), <b>getrandom</b>() will block
until some random bytes become available (unless the
<b>GRND_NONBLOCK</b> flag was specified).</p>
<p style="margin-left:11%; margin-top: 1em">The behavior
when a call to <b>getrandom</b>() that is blocked while
reading from the <i>urandom</i> source is interrupted by a
signal handler depends on the initialization state of the
entropy buffer and on the request size, <i>buflen</i>. If
the entropy is not yet initialized, then the call fails with
the <b>EINTR</b> error. If the entropy pool has been
initialized and the request size is large
(<i>buflen </i>> 256), the call either
succeeds, returning a partially filled buffer, or fails with
the error <b>EINTR</b>. If the entropy pool has been
initialized and the request size is small
(<i>buflen </i><= 256), then <b>getrandom</b>()
will not fail with <b>EINTR</b>. Instead, it will return all
of the bytes that have been requested.</p>
<p style="margin-left:11%; margin-top: 1em">When reading
from the <i>random</i> source, blocking requests of any size
can be interrupted by a signal handler (the call fails with
the error <b>EINTR</b>).</p>
<p style="margin-left:11%; margin-top: 1em">Using
<b>getrandom</b>() to read small buffers (<= 256
bytes) from the <i>urandom</i> source is the preferred mode
of usage.</p>
<p style="margin-left:11%; margin-top: 1em">The special
treatment of small values of <i>buflen</i> was designed for
compatibility with OpenBSD’s <b>getentropy</b>(3),
which is nowadays supported by glibc.</p>
<p style="margin-left:11%; margin-top: 1em">The user of
<b>getrandom</b>() <i>must</i> always check the return
value, to determine whether either an error occurred or
fewer bytes than requested were returned. In the case where
<b>GRND_RANDOM</b> is not specified and <i>buflen</i> is
less than or equal to 256, a return of fewer bytes than
requested should never happen, but the careful programmer
will check for this anyway!</p>
<h2>BUGS
<a name="BUGS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">As of Linux
3.19, the following bug exists:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="1%">
<p style="margin-top: 1em">*</p></td>
<td width="3%"></td>
<td width="85%">
<p style="margin-top: 1em">Depending on CPU load,
<b>getrandom</b>() does not react to interrupts before
reading all bytes requested.</p></td></tr>
</table>
<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>getentropy</b>(3),
<b>random</b>(4), <b>urandom</b>(4), <b>random</b>(7),
<b>signal</b>(7)</p>
<h2>COLOPHON
<a name="COLOPHON"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">This page is
part of release 5.02 of the Linux <i>man-pages</i> project.
A description of the project, information about reporting
bugs, and the latest version of this page, can be found at
https://www.kernel.org/doc/man-pages/.</p>
<hr>
</body>
</html>