Debian Codegraph @

upstream/debian-unstable/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-04-21 "Linux man-pages 6.18"
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 POSIX.1-2024.
73 .SH HISTORY
74 OpenBSD 5.6,
75 glibc 2.25,
76 FreeBSD 12.0,
77 POSIX.1-2024.
78 .SH NOTES
79 The
80 .BR getentropy ()
81 function is implemented using
82 .BR getrandom (2).
83 .P
84 Whereas the glibc wrapper makes
85 .BR getrandom (2)
86 a cancelation point,
87 .BR getentropy ()
88 is not a cancelation point.
89 .P
90 .BR getentropy ()
91 is also declared in
92 .BR <sys/random.h> .
93 (No feature test macro need be defined to obtain the declaration from
94 that header file.)
95 .P
96 A call to
97 .BR getentropy ()
98 may block if the system has just booted and the kernel has
99 not yet collected enough randomness to initialize the entropy pool.
100 In this case,
101 .BR getentropy ()
102 will keep blocking even if a signal is handled,
103 and will return only once the entropy pool has been initialized.
104 .SH SEE ALSO
105 .BR getrandom (2),
106 .BR urandom (4),
107 .BR random (7)