getrandom —
get random numbers
Standard C Library (libc, -lc)
#include
<sys/random.h>
ssize_t
getrandom(
void
*bufp,
size_t buflen,
unsigned int flags);
The
getrandom() function is used to retrieve
random and pseudo-random numbers from the operating system.
By default, the
getrandom() function will
read up to
buflen bytes of pseudo-random data
into
bufp. Pseudo-random data will be
retrieved from the same source that provides data to
/dev/urandom. The
getrandom() function may return less data
than was requested in
buflen. This can happen
because of interrupts from signals, availability of data, or because the
request was too large. Callers must always check to see how much data was
actually returned.
The following values may be bitwise-ORed together in the
flags argument to modify the behavior of the
function:
-
-
GRND_NONBLOCK- Instead of blocking, return immediately if data is not available. If no
data was obtained,
EAGAIN will be set
in errno. Otherwise, less data will be
returned than requested.
-
-
GRND_RANDOM- Use the same source of random data as reading from
/dev/random, instead of
/dev/urandom.
The
getrandom() function is intended to
eliminate the need to explicitly call
open(2) and
read(2) on
/dev/random or
/dev/urandom. This eliminates the need to
have the character devices available or cases where a program may not have an
available file descriptor. For other uses,
arc4random(3C) may be a better interface.
Upon successful completion, the
getrandom()
function returns the number of bytes written into
bufp. Otherwise,
-1 is returned and
errno is set to indicate the error.
The
getrandom() function will fail if:
-
-
EAGAIN- The
getrandom() function would have
blocked and GRND_NONBLOCK flag was
set.
-
-
EFAULT- The bufp argument points to an illegal
address.
-
-
EINAVL- An invalid value was passed in
flags.
-
-
EINTR- A signal was caught during the operation and no data was transferred.
-
-
EIO- An internal error occurred with the corresponding
random(7D) device.
Committed
MT-Safe
open(2),
read(2),
arc4random(3C),
random(7D)
getrandom() is non-standard. It originally
appeared in Linux.