NAME

getentropy — fill a buffer with random bytes

SYNOPSIS

#include <unistd.h>

int getentropy(void *buffer, size_t length);


DESCRIPTION

The getentropy() function shall write length bytes of data starting at the location pointed to by buffer. The output shall be unpredictable high quality random data, generated by a cryptographically secure pseudo-random number generator. The maximum permitted value for the length argument is given by the {GETENTROPY_MAX} symbolic constant defined in <limits.h>.

A successful call to getentropy() shall always provide the requested number of bytes of entropy.

RETURN VALUE

Upon successful completion, getentropy() shall return 0; otherwise, -1 shall be returned and errno set to indicate the error.

ERRORS

The getentropy() function shall fail if:

[EINVAL]

The value of length is greater than {GETENTROPY_MAX}.

The getentropy() function may fail if:

[ENOSYS]

The system does not provide the necessary source of entropy.

EXAMPLES

None.

APPLICATION USAGE

The intended use of this function is to create a seed for other pseudo-random number generators.

RATIONALE

The getentropy() function is not a cancellation point. (See 2.9.5.2 Cancellation Points.)

FUTURE DIRECTIONS

None.

SEE ALSO

drand48, initstate, rand

XBD <limits.h>, <unistd.h>

CHANGE HISTORY

First released in Issue 8.