- NetBSD Manual Pages
GETRANDOM(2) NetBSD System Calls Manual GETRANDOM(2)
Powered by man-cgi (2021-06-01).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.
getrandom -- generate uniform random seeds from system entropy for cryp-
Standard C Library (libc, -lc)
getrandom(void *buf, size_t buflen, unsigned int flags);
The 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:
0 May block. On success, guaranteed to generate the
smaller of buflen or 256 bytes.
GRND_INSECURE Never blocks. On success, guaranteed to generate
the smaller of buflen or 256 bytes.
GRND_RANDOM Will probably block. On success, may generate as
little as a single byte of data.
This 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
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.
If successful, 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
to detect failure. However, with GRND_RANDOM, getrandom() may generate
as little as a single byte if successful.
Generate a key for cryptography:
if (getrandom(secretkey, sizeof secretkey, 0) == -1)
[EAGAIN] The GRND_NONBLOCK flag was specified, and getrandom
would have blocked waiting for entropy.
[EINTR] The GRND_NONBLOCK flag was not specified, getrandom
blocked waiting for entropy, and the process was
interrupted by a signal.
[EINVAL] flags contains an unrecognized flag or a nonsensical
combination of flags.
[EFAULT] buf points outside the allocated address space.
Security can only be guaranteed relative to whatever unpredictable physi-
cal processes or secret seed material are available to the system; see
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 gen-
eration hardware or secret seed material from such hardware on another
arc4random(3), getentropy(3), rnd(4), entropy(7)
The getrandom function is a nonstandard Linux extension and will probably
never be standardized.
The getrandom system call first appeared in Linux 3.17, and was added to
There is no way to multiplex waiting for getrandom() with other I/O in
select(2), poll(2), or kqueue(2), or to atomically unmask a set of sig-
nals 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.
NetBSD 10.99 March 17, 2022 NetBSD 10.99