arc4random(3)

✨ arc4random(3) ✨

okay bestie, buckle up, we're in the Library Functions Manual section (that's the man family this cutie lives in 💅) and today's topic is: getting random numbers that aren't mid. like actually, truly, cryptographically random. no cap.

---

🌈 NAME 🌈

arc4random, arc4random_uniform, arc4random_buf — the cryptographically-secure pseudorandom number generator trio. three icons, one vibe check, zero predictability 💖

---

📚 LIBRARY 📚

Standard C library (libc, -lc). she's built right in, you just gotta show up 🫶

---

🎀 SYNOPSIS 🎀

#include <stdlib.h>

uint32_t arc4random(void);
uint32_t arc4random_uniform(uint32_t upper_bound);
void arc4random_buf(size_t n;
                    void buf[n], size_t n);

---

🌸 DESCRIPTION 🌸

these functions hand you cryptographically-secure pseudorandom numbers. like, the good stuff. the un-guessable stuff. it's giving security, it's giving chaos, it's giving "how did you even predict that, you can't" 💀

• arc4random() — returns a uniformly-distributed value. every number has the same chance, no favorites, no nepo babies ✨
• arc4random_uniform() — returns a uniformly-distributed value less than upper_bound (but pls read the BUGS section below, it's important, i'm not joking 🙈)
• arc4random_buf() — fills the memory that buf points to with n bytes of pseudorandom data. bulk random, grab a bucket 🧚

and now the part that's gonna ruffle some feathers: the rand(3) and drand48(3) families of functions? they should only be used where the quality of the pseudorandom numbers is not a concern and there's a need for repeatability of the results. that's a two-condition situation. BOTH of them. if you don't meet both, use the arc4random() functions. no debate, no exceptions, periodt 👑

---

💜 RETURN VALUE 💜

• arc4random() returns a pseudorandom number. simple. clean. iconic.
• arc4random_uniform() returns a pseudorandom number less than upper_bound for valid input, or 0 when upper_bound is invalid. note that 0 on the fail path. remember it. we'll come back to it 😭

---

🔥 ATTRIBUTES 🔥

for an explanation of the terms used in this section, go see attributes(7). but here's the tea:

• arc4random(), arc4random_uniform(), arc4random_buf() — Thread safety: MT-Safe. yes ma'am, safe to call from multiple threads, no drama, no beef 🌈

---

⭐ STANDARDS ⭐

BSD. that's it, that's the whole section. born on BSD, raised on BSD 🩷

---

🦋 HISTORY 🦋

• OpenBSD 2.1
• FreeBSD 3.0
• NetBSD 1.6
• DragonFly 1.0
• libbsd
• glibc 2.36

look at that glow-up timeline, she's been bookin' since the 90s and she just landed in glibc 2.36 like it was nothing 👑

---

😭 BUGS 😭

okay this is the serious bit, bestie, so listen up fr fr:

an upper_bound of 0 doesn't make sense in a call to arc4random_uniform(). such a call will fail, and return 0.

be careful, because that value is not less than upper_bound. in some cases — like accessing an array — using that value could result in undefined behavior. 🚨

so if you're doing something like using that return value as an array index, you are lowkey stepping into the void. i'm not being dramatic, that's literally what undefined behavior means 💀 please validate your bounds, i'm begging 🙏

---

🍓 SEE ALSO 🍓

• getrandom(3)
• rand(3)
• drand48(3)
• random(7)

go read those too, i know you want to, you're a scholar 🎀

---

and that's the whole page, babe. this lil slice of the Linux man-pages 6.20, dated 2025-06-28, from the arc4random(3) page, is officially yours now ✨ go forth and be random (but like, the cryptographically secure kind, obviously) 💖👑🌸