getrandom(2)

🌈 NAME 🌈

okay so bestie, meet getrandom(2) — she's chilling in the System Calls Manual, and her whole job is to obtain a series of random bytes. it's giving entropy. it's giving cryptographic main character energy. she ate. 💅✨

---

🎀 LIBRARY 🎀

Standard C library (libc, -lc) — she's right there in your libc, no extra shopping required 🫶

---

🦋 SYNOPSIS 🦋

#include <sys/random.h>

ssize_t getrandom(size_t size;
                  void buf[size], size_t size, unsigned int flags);

---

💜 DESCRIPTION 💜

So the getrandom() system call fills the buffer that buf points to with up to size random bytes. and what are those bytes even for?? seeding user-space random number generators, or for cryptographic purposes. literally both, and both are iconic. 🔥

By default, getrandom() pulls its entropy from the urandom source — that's the same source as the /dev/urandom device, iykyk. but you can change that behaviour with the flags argument, no cap.

Now here's the tea on guarantees ☕ if the urandom source has been initialized, reads of up to 256 bytes will always return as many bytes as requested, and they will not be interrupted by signals. obsessed. but for larger buffer sizes? no such guarantees apply, bestie, none at all. like, if the call gets interrupted by a signal handler, it may return a partially filled buffer, or it may just fail with the error EINTR. 😭

and if the urandom source has not yet been initialized?? then getrandom() will block, unless GRND_NONBLOCK is specified in flags. she waits. she's patient. she knows what she's worth. 👑

The flags argument is a bit mask that can contain zero or more of the following values, ORed together:

• GRND_RANDOM — set this bit and the random bytes get drawn from the random source (i.e., the same source as the /dev/random device) instead of the urandom source. the random source is limited based on the entropy that can be obtained from environmental noise — she's on a budget 💀. if the number of available bytes in the random source is less than what was requested in size, the call returns just the available random bytes. and if no random bytes are available at all, the behaviour depends on whether GRND_NONBLOCK is present in the flags argument.
• GRND_NONBLOCK — by default, when reading from the random source, getrandom() blocks if no random bytes are available, and when reading from the urandom source, it blocks if the entropy pool has not yet been initialized. but if the GRND_NONBLOCK flag is set, then getrandom() does not block in these cases — instead it immediately returns -1 with errno set to EAGAIN. no waiting, no drama, just vibes. 🫶

---

⭐ RETURN VALUE ⭐

On success, getrandom() returns the number of bytes that were copied to the buffer buf. and heads up: that number may be less than the number of bytes requested via size, if either GRND_RANDOM was specified in flags and insufficient entropy was present in the random source, or the system call was interrupted by a signal. 🙈

On error, -1 is returned, and errno is set to indicate the error. periodt.

---

💀 ERRORS 💀

• EAGAIN — the requested entropy was not available, and getrandom() would have blocked if the GRND_NONBLOCK flag was not set.
• EFAULT — the address referred to by buf is outside the accessible address space. not accessible, not invited. 🚫
• EINTR — the call was interrupted by a signal handler; peep the description of how interrupted read(2) calls on "slow" devices are handled with and without the SA_RESTART flag over in the signal(7) man page.
• EINVAL — an invalid flag was specified in flags. bestie. why. 😭
• ENOSYS — the glibc wrapper function for getrandom() determined that the underlying kernel does not implement this system call. sadly, no bytes today. 💔

---

🌸 STANDARDS 🌸

Linux. that's the whole list. she's a Linux girl and she owns it. 💅

---

🧚 HISTORY 🧚

Linux 3.17, glibc 2.25. vintage but still thriving, we love a legend. 👑

---

💅 NOTES 💅

For an overview and comparison of the various interfaces that can be used to obtain randomness, check out random(7). ✨

Here's a fun fact: unlike /dev/random and /dev/urandom, getrandom() does not involve the use of pathnames or file descriptors. so getrandom() can be useful in cases where chroot(2) makes /dev pathnames invisible, and where an application (e.g., a daemon during start-up) closes a file descriptor for one of these files that was opened by a library. no path, no fd, no problem. 🦋

🍓 Maximum number of bytes returned 🍓

As of Linux 3.19 the following limits apply:

• When reading from the urandom source, a maximum of 32Mi-1 bytes is returned by a single call to getrandom() on systems where int has a size of 32 bits.
• When reading from the random source, a maximum of 512 bytes is returned.

🎀 Interruption by a signal handler 🎀

When reading from the urandom source (GRND_RANDOM is not set), getrandom() will block until the entropy pool has been initialized (unless the GRND_NONBLOCK flag was specified, ofc). and if a request is made to read a large number of bytes — more than 256 — getrandom() will block until those bytes have been generated and transferred from kernel memory to buf. when reading from the random source (GRND_RANDOM is set), getrandom() will block until some random bytes become available (unless the GRND_NONBLOCK flag was specified). she waits, then she delivers. 💜

The behaviour when a call to getrandom() that is blocked while reading from the urandom source is interrupted by a signal handler depends on the initialization state of the entropy buffer and on the request size, size. so, breaking it down:

• if the entropy is not yet initialized, then the call fails with the EINTR error.
• if the entropy pool has been initialized and the request size is large (size > 256), the call either succeeds — returning a partially filled buffer — or fails with the error EINTR.
• if the entropy pool has been initialized and the request size is small (size <= 256), then getrandom() will not fail with EINTR. instead, it will return all of the bytes that have been requested. iconic behaviour honestly. ✨

When reading from the random source, blocking requests of any size can be interrupted by a signal handler — the call fails with the error EINTR. 😭

Using getrandom() to read small buffers (<= 256 bytes) from the urandom source is the preferred mode of usage. that's the way, bestie. 🫶

The special treatment of small values of size was designed for compatibility with OpenBSD's getentropy(3), which is nowadays supported by glibc. a cute little cross-platform moment. 🌈

okay real talk for a sec: the user of getrandom() must always check the return value, to determine whether either an error occurred or fewer bytes than requested were returned. in the case where GRND_RANDOM is not specified and size is less than or equal to 256, a return of fewer bytes than requested should never happen — but the careful programmer will check for this anyway! 👀 not optional, bestie. check it.

---

🐛 BUGS 🐛

As of Linux 3.19, the following bug exists:

• Depending on CPU load, getrandom() does not react to interrupts before reading all bytes requested. 💀 she is locked in. perhaps too locked in.

---

👀 SEE ALSO 👀

• getentropy(3)
• random(4)
• urandom(4)
• random(7)
• signal(7)

---

and that's the whole page, bestie 💖 this was Linux man-pages 6.20, dated 2026-02-08 — now go get your random bytes, you've got this, and remember: always check the return value. slay. 🎀🌺⭐