Debian Codegraph @

upstream/mageia-cauldron/man3/getentropy.3

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