Debian Codegraph @

upstream/debian-trixie/man3/getentropy.3

raw
1 .\" Copyright (C) 2017, Michael Kerrisk <[email protected]>
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH getentropy 3 2024-05-02 "Linux man-pages 6.9.1"
6 .SH NAME
7 getentropy \- fill a buffer with random bytes
8 .SH LIBRARY
9 Standard C library
10 .RI ( libc ", " \-lc )
11 .SH SYNOPSIS
12 .nf
13 .B #include <unistd.h>
14 .P
15 .BI "int getentropy(void " buffer [. length "], size_t " length );
16 .fi
17 .P
18 .RS -4
19 Feature Test Macro Requirements for glibc (see
20 .BR feature_test_macros (7)):
21 .RE
22 .P
23 .BR getentropy ():
24 .nf
25 _DEFAULT_SOURCE
26 .fi
27 .SH DESCRIPTION
28 The
29 .BR getentropy ()
30 function writes
31 .I length
32 bytes of high-quality random data to the buffer starting
33 at the location pointed to by
34 .IR buffer .
35 The maximum permitted value for the
36 .I length
37 argument is 256.
38 .P
39 A successful call to
40 .BR getentropy ()
41 always provides the requested number of bytes of entropy.
42 .SH RETURN VALUE
43 On success, this function returns zero.
44 On error, \-1 is returned, and
45 .I errno
46 is set to indicate the error.
47 .SH ERRORS
48 .TP
49 .B EFAULT
50 Part or all of the buffer specified by
51 .I buffer
52 and
53 .I length
54 is not in valid addressable memory.
55 .TP
56 .B EIO
57 .I length
58 is greater than 256.
59 .TP
60 .B EIO
61 An unspecified error occurred while trying to overwrite
62 .I buffer
63 with random data.
64 .TP
65 .B ENOSYS
66 This kernel version does not implement the
67 .BR getrandom (2)
68 system call required to implement this function.
69 .SH STANDARDS
70 None.
71 .SH HISTORY
72 glibc 2.25.
73 OpenBSD.
74 .SH NOTES
75 The
76 .BR getentropy ()
77 function is implemented using
78 .BR getrandom (2).
79 .P
80 Whereas the glibc wrapper makes
81 .BR getrandom (2)
82 a cancelation point,
83 .BR getentropy ()
84 is not a cancelation point.
85 .P
86 .BR getentropy ()
87 is also declared in
88 .BR <sys/random.h> .
89 (No feature test macro need be defined to obtain the declaration from
90 that header file.)
91 .P
92 A call to
93 .BR getentropy ()
94 may block if the system has just booted and the kernel has
95 not yet collected enough randomness to initialize the entropy pool.
96 In this case,
97 .BR getentropy ()
98 will keep blocking even if a signal is handled,
99 and will return only once the entropy pool has been initialized.
100 .SH SEE ALSO
101 .BR getrandom (2),
102 .BR urandom (4),
103 .BR random (7)