man pages section 2: System Calls

getentropy (2)

Name

getrandom, getentropy - retrieve data from the kernel random pool

Synopsis

#include <sys/random.h>
int getrandom(void *buf, size_t buflen, unsigned int flags);
int getentropy(void *buf, size_t buflen);

Description

The getrandom() function can be used to request buflen bytes of data from the kernel random pool, which is to be placed into the buffer, pointed to by buf. It is recommended to use the getrandom() function instead of open(2) and read(2) functions on the /dev/random or /dev/urandom device.

The random data returned by the getrandom() function is processed by a FIPS 140-2 approved deterministic random bit generator (DRBG).

If the GRND_RANDOM flag is set, then the implementation uses the same pool as /dev/random, otherwise the /dev/urandom pool is used.

If no entropy is available in the pool, the getrandom() function will block unless the GRND_NONBLOCK flag is set. In this case, the function returns -1 and errno is set to EAGAIN. Note that the number of bytes returned can be the number of bytes requested or 0. Callers need to check the return value to determine if random bytes were returned. This means this is not an acceptable calling sequence:

(void) getrandom(&buf, sizeof (buf), 0);

The getentropy() function is blocked and is expected to be used only to seed a userspace implementation of a random bit generator.

Return Values

Upon successful completion, the getrandom() function returns the number of bytes written to buf. Otherwise, it returns 0 and sets errno to indicate the error.

Upon successful completion, the getentropy() function returns 0. Otherwise, it returns -1 and sets errno to indicate the error.

Errors

The getrandom() and getentropy() functions fail if:

EINVAL

The flags are not set to GRND_RANDOM, GRND_NONBLOCK or both, or bufsz is <= 0 or > 1024.

EFAULT

buf is an invalid address.

EAGAIN

No entropy is available and GRND_NONBLOCK is set.

The getentropy() call also fail if:

EIO

More than 256 bytes are requested, or the returned amount of entropy does not match the request.

Examples

Example 1 Using thegetrandom() function

#include <sys/random.h>
#include <stdlib.h>
.
size_t bufsz = 1024;
char *buf;
int ret;
.
...
buf = malloc(bufsz);
...
ret = getrandom(buf, bufsz, GRND_RANDOM);
if (ret != bufsz) {
                 perror("getrandom failed");
                 ...
                  }
...

Example 2 Using the getentropy() function

#include <sys/random.h>
#include <stdlib.h>
.
size_t entsz = 128;
char *entropy;
int err;
.
...
entropy = malloc(entsz);
...
err = getentropy(entropy, entsz);
if (err != 0) {
                 perror("getentropy failed");
                 ...
              }
/* Use entropy to seed our RNG */

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE Interface Stability Committed MT-Level MT-Safe