projects / thirdparty / man-pages.git / blame
| Commit | Line | Data |
|---|---|---|
| b0265728 MK |
1 | .\" Copyright (C) 2017, Michael Kerrisk <mtk.manpages@gmail.com> |
| 2 | .\" | |
| 5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| b0265728 | 4 | .\" |
| 4c1c5274 | 5 | .TH getentropy 3 (date) "Linux man-pages (unreleased)" |
| b0265728 MK |
6 | .SH NAME |
| 7 | getentropy \- fill a buffer with random bytes | |
| 42009080 AC |
8 | .SH LIBRARY |
| 9 | Standard C library | |
| 10 | .RI ( libc ", " \-lc ) | |
| b0265728 | 11 | .SH SYNOPSIS |
| c7db92b9 | 12 | .nf |
| 9cf011f9 | 13 | .B #include <unistd.h> |
| 68e4db0a | 14 | .PP |
| d75c6df9 | 15 | .BI "int getentropy(void *" buffer ", size_t " length ); |
| c7db92b9 | 16 | .fi |
| 68e4db0a | 17 | .PP |
| d39ad78f | 18 | .RS -4 |
| f0ed9710 MK |
19 | Feature Test Macro Requirements for glibc (see |
| 20 | .BR feature_test_macros (7)): | |
| d39ad78f | 21 | .RE |
| 68e4db0a | 22 | .PP |
| f0ed9710 | 23 | .BR getentropy (): |
| 9d2adbae MK |
24 | .nf |
| 25 | _DEFAULT_SOURCE | |
| 26 | .fi | |
| b0265728 MK |
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. | |
| 847e0d88 | 38 | .PP |
| b0265728 MK |
39 | A successful call to |
| 40 | .BR getentropy () | |
| 419ba7b3 | 41 | always provides the requested number of bytes of entropy. |
| b0265728 | 42 | .SH RETURN VALUE |
| 78cba5ac | 43 | On success, this function returns zero. |
| b0265728 MK |
44 | On error, \-1 is returned, and |
| 45 | .I errno | |
| f6a4078b | 46 | is set to indicate the error. |
| b0265728 MK |
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 VERSIONS | |
| 70 | The | |
| 71 | .BR getentropy () | |
| 72 | function first appeared in glibc 2.25. | |
| 3113c7f3 | 73 | .SH STANDARDS |
| b0265728 MK |
74 | This function is nonstandard. |
| 75 | It is also present on OpenBSD. | |
| 76 | .SH NOTES | |
| 77 | The | |
| 78 | .BR getentropy () | |
| 79 | function is implemented using | |
| 80 | .BR getrandom (2). | |
| 847e0d88 | 81 | .PP |
| b0265728 MK |
82 | Whereas the glibc wrapper makes |
| 83 | .BR getrandom (2) | |
| 1f08fc80 | 84 | a cancelation point, |
| b0265728 | 85 | .BR getentropy () |
| 1f08fc80 | 86 | is not a cancelation point. |
| 847e0d88 | 87 | .PP |
| f0ed9710 MK |
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.) | |
| 847e0d88 | 93 | .PP |
| b0265728 MK |
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) |