| GETRANDOM(2) | System Calls Manual | GETRANDOM(2) | 
getrandom —
#include <sys/random.h>
ssize_t
  
  getrandom(void
    *buf, size_t
    buflen, unsigned int
    flags);
getrandom function fills buf
  with up to buflen independent uniform random bytes
  derived from the system's entropy pool.
The output of getrandom is meant to be
    unpredictable to an adversary and fit for use in cryptography. See CAVEATS
    below.
getrandom is meant for seeding random
    number generators, not for direct use by applications; most applications
    should use
  arc4random(3).
getrandom is a nonstandard extension that
    was added before POSIX began to converge on
    getentropy(2).
    Applications should avoid getrandom and use
    getentropy(2) instead;
    getrandom may be removed from a later release.
getrandom may block indefinitely unless
    the GRND_INSECURE or
    GRND_NONBLOCK flags are specified.
The flags argument may be:
0GRND_INSECUREGRND_RANDOMThis is provided for source compatibility with Linux; there is no reason to ever use it.
The flag GNRD_NONBLOCK may also be
    included with bitwise-OR, in which case if
    getrandom() would have blocked without
    GRND_NONBLOCK, it returns
    EAGAIN instead.
Adding GRND_NONBLOCK to
    GRND_INSECURE has no effect; the combination
    GRND_INSECURE|GRND_NONBLOCK
    is equivalent to GRND_INSECURE, since
    GRND_INSECURE never blocks. The combination
    GRND_INSECURE|GRND_RANDOM
    always fails with EINVAL.
getrandom() returns the number of bytes
  stored in buf. Otherwise,
  getrandom() returns -1 and sets
  errno.
Since getrandom(..., 0) and
    getrandom(..., GRND_INSECURE) are guaranteed to
    generate buflen or 256 bytes, whichever is smaller, if
    successful, it is sufficient to use, e.g.,
getrandom(buf, 32, 0) == -1
getrandom(buf, 32, GRND_INSECURE) == -1
GRND_RANDOM,
  getrandom() may generate as little as a single byte if
  successful.
uint8_t secretkey[32]; if (getrandom(secretkey, sizeof secretkey, 0) == -1) err(EXIT_FAILURE, "getrandom"); crypto_secretbox_xsalsa20poly1305(..., secretkey);
EAGAIN]GRND_NONBLOCK flag was specified, and
      getrandom would have blocked waiting for
    entropy.EINTR]GRND_NONBLOCK flag was not
      specified, getrandom blocked waiting for entropy,
      and the process was interrupted by a signal.EINVAL]EFAULT]On systems which have no hardware random number generator and which have not had secret seed material loaded, NetBSD makes a reasonable effort to incorporate samples from various physical processes available to it that might be unpredictable from random jitter in timing.
However, the getrandom interface alone can
    make no security guarantees without a physical system configuration that
    includes random number generation hardware or secret seed material from such
    hardware on another machine.
getrandom function is a nonstandard Linux extension
  and will probably never be standardized.
getrandom system call first appeared in Linux 3.17,
  and was added to NetBSD 10.0.
getrandom()
  with other I/O in select(2),
  poll(2), or
  kqueue(2), or to atomically
  unmask a set of signals while getrandom blocks.
  Instead, you can wait for a read from /dev/random; see
  rnd(4).
The getrandom interface has more options
    than real-world applications need, with confusing and unclear semantics
    inherited from Linux.
| March 17, 2022 | NetBSD 10.0 |