getentropy(3)

1GETENTROPY(3)              Linux Programmer's Manual             GETENTROPY(3)
2
3
4

NAME

6       getentropy - fill a buffer with random bytes
7

SYNOPSIS

9       #include <unistd.h>
10
11       int getentropy(void *buffer, size_t length);
12
13   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
14
15       getentropy():
16           _DEFAULT_SOURCE
17

DESCRIPTION

19       The  getentropy()  function  writes length bytes of high-quality random
20       data to the buffer starting at the location pointed to by buffer.   The
21       maximum permitted value for the length argument is 256.
22
23       A  successful call to getentropy() always provides the requested number
24       of bytes of entropy.
25

RETURN VALUE

27       On success, this function returns zero.  On error, -1 is returned,  and
28       errno is set to indicate the error.
29

ERRORS

31       EFAULT Part  or all of the buffer specified by buffer and length is not
32              in valid addressable memory.
33
34       EIO    length is greater than 256.
35
36       EIO    An unspecified error occurred while trying to  overwrite  buffer
37              with random data.
38
39       ENOSYS This  kernel  version does not implement the getrandom(2) system
40              call required to implement this function.
41

VERSIONS

43       The getentropy() function first appeared in glibc 2.25.
44

CONFORMING TO

46       This function is nonstandard.  It is also present on OpenBSD.
47

NOTES

49       The getentropy() function is implemented using getrandom(2).
50
51       Whereas the glibc wrapper  makes  getrandom(2)  a  cancellation  point,
52       getentropy() is not a cancellation point.
53
54       getentropy()  is  also  declared  in  <sys/random.h>.  (No feature test
55       macro need be defined to obtain the declaration from that header file.)
56
57       A call to getentropy() may block if the system has just booted and  the
58       kernel  has  not  yet collected enough randomness to initialize the en‐
59       tropy pool.  In this case, getentropy() will keep blocking  even  if  a
60       signal  is handled, and will return only once the entropy pool has been
61       initialized.
62

COLOPHON

67       This page is part of release 5.12 of the Linux  man-pages  project.   A
68       description  of  the project, information about reporting bugs, and the
69       latest    version    of    this    page,    can     be     found     at
70       https://www.kernel.org/doc/man-pages/.
71
72
73
74Linux                             2021-03-22                     GETENTROPY(3)