GETRANDOM(2) System Calls GETRANDOM(2)

NAME

getrandom - get random numbers

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <sys/random.h>

ssize_t
getrandom(void *bufp, size_t buflen, unsigned int flags);

DESCRIPTION

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.

RETURN VALUES

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.

ERRORS

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(4D) device.

INTERFACE STABILITY

Committed

MT-LEVEL
MT-Safe

SEE ALSO

open(2), read(2), arc4random(3C), random(4D)

STANDARDS

The getrandom() function is non-standard. It originally appeared in
Linux.

illumos November 6, 2018 illumos