]>
Commit | Line | Data |
---|---|---|
b0265728 MK |
1 | .\" Copyright (C) 2017, Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" | |
3 | .\" %%%LICENSE_START(VERBATIM) | |
4 | .\" Permission is granted to make and distribute verbatim copies of this | |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of | |
9 | .\" this manual under the conditions for verbatim copying, provided that | |
10 | .\" the entire resulting derived work is distributed under the terms of | |
11 | .\" a permission notice identical to this one. | |
12 | .\" | |
13 | .\" Since the Linux kernel and libraries are constantly changing, this | |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume. | |
15 | .\" no responsibility for errors or omissions, or for damages resulting. | |
16 | .\" from the use of the information contained herein. The author(s) may. | |
17 | .\" not have taken the same level of care in the production of this. | |
18 | .\" manual, which is licensed free of charge, as they might when working. | |
19 | .\" professionally. | |
20 | .\" | |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
23 | .\" %%%LICENSE_END | |
24 | .\" | |
4b8c67d9 | 25 | .TH GETENTROPY 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
b0265728 MK |
26 | .SH NAME |
27 | getentropy \- fill a buffer with random bytes | |
28 | .SH SYNOPSIS | |
9cf011f9 | 29 | .B #include <unistd.h> |
68e4db0a | 30 | .PP |
d75c6df9 | 31 | .BI "int getentropy(void *" buffer ", size_t " length ); |
68e4db0a | 32 | .PP |
f0ed9710 MK |
33 | .in -4n |
34 | Feature Test Macro Requirements for glibc (see | |
35 | .BR feature_test_macros (7)): | |
36 | .in | |
68e4db0a | 37 | .PP |
f0ed9710 MK |
38 | .BR getentropy (): |
39 | .br | |
40 | .RS 4 | |
41 | .ad l | |
42 | _DEFAULT_SOURCE | |
43 | .RE | |
44 | .ad | |
b0265728 MK |
45 | .SH DESCRIPTION |
46 | The | |
47 | .BR getentropy () | |
48 | function writes | |
49 | .I length | |
50 | bytes of high-quality random data to the buffer starting | |
51 | at the location pointed to by | |
52 | .IR buffer . | |
53 | The maximum permitted value for the | |
54 | .I length | |
55 | argument is 256. | |
847e0d88 | 56 | .PP |
b0265728 MK |
57 | A successful call to |
58 | .BR getentropy () | |
419ba7b3 | 59 | always provides the requested number of bytes of entropy. |
b0265728 | 60 | .SH RETURN VALUE |
78cba5ac | 61 | On success, this function returns zero. |
b0265728 MK |
62 | On error, \-1 is returned, and |
63 | .I errno | |
64 | is set appropriately. | |
65 | .SH ERRORS | |
66 | .TP | |
67 | .B EFAULT | |
68 | Part or all of the buffer specified by | |
69 | .I buffer | |
70 | and | |
71 | .I length | |
72 | is not in valid addressable memory. | |
73 | .TP | |
74 | .B EIO | |
75 | .I length | |
76 | is greater than 256. | |
77 | .TP | |
78 | .B EIO | |
79 | An unspecified error occurred while trying to overwrite | |
80 | .I buffer | |
81 | with random data. | |
82 | .TP | |
83 | .B ENOSYS | |
84 | This kernel version does not implement the | |
85 | .BR getrandom (2) | |
86 | system call required to implement this function. | |
87 | .SH VERSIONS | |
88 | The | |
89 | .BR getentropy () | |
90 | function first appeared in glibc 2.25. | |
91 | .SH CONFORMING TO | |
92 | This function is nonstandard. | |
93 | It is also present on OpenBSD. | |
94 | .SH NOTES | |
95 | The | |
96 | .BR getentropy () | |
97 | function is implemented using | |
98 | .BR getrandom (2). | |
847e0d88 | 99 | .PP |
b0265728 MK |
100 | Whereas the glibc wrapper makes |
101 | .BR getrandom (2) | |
102 | a cancellation point, | |
103 | .BR getentropy () | |
104 | is not a cancellation point. | |
847e0d88 | 105 | .PP |
f0ed9710 MK |
106 | .BR getentropy () |
107 | is also declared in | |
108 | .BR <sys/random.h> . | |
109 | (No feature test macro need be defined to obtain the declaration from | |
110 | that header file.) | |
847e0d88 | 111 | .PP |
b0265728 MK |
112 | A call to |
113 | .BR getentropy () | |
114 | may block if the system has just booted and the kernel has | |
115 | not yet collected enough randomness to initialize the entropy pool. | |
116 | In this case, | |
117 | .BR getentropy () | |
118 | will keep blocking even if a signal is handled, | |
119 | and will return only once the entropy pool has been initialized. | |
120 | .SH SEE ALSO | |
121 | .BR getrandom (2), | |
122 | .BR urandom (4), | |
123 | .BR random (7) |