GETRANDOM(2) System Calls GETRANDOM(2)

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:

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.
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:
The getrandom() function would have blocked and GRND_NONBLOCK flag was set.
The bufp argument points to an illegal address.
An invalid value was passed in flags.
A signal was caught during the operation and no data was transferred.
An internal error occurred with the corresponding random(7D) device.

Committed

MT-Safe

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

The getrandom() function is non-standard. It originally appeared in Linux.
November 6, 2018 OmniOS