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

INTERFACE STABILITY


Committed

MT-LEVEL
MT-Safe

SEE ALSO


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

STANDARDS


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

OmniOS November 6, 2018 OmniOS