getentropy(3)

1getentropy(3)              Library Functions Manual              getentropy(3)
2
3
4

NAME

6       getentropy - fill a buffer with random bytes
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <unistd.h>
13
14       int getentropy(void buffer[.length], size_t length);
15
16   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
17
18       getentropy():
19           _DEFAULT_SOURCE
20

DESCRIPTION

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

RETURN VALUE

30       On success, this function returns zero.  On error, -1 is returned,  and
31       errno is set to indicate the error.
32

ERRORS

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

STANDARDS

46       None.
47

HISTORY

49       glibc 2.25.  OpenBSD.
50

NOTES

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