PRNG(9)

✨ PRNG(9) ✨

okay bestie, so this is the kernel developer's manual page for prng — the Kernel pseudo-random number generators 💅 (yes, from PRNG(9), and we're gonna get into it)

---

🌸 NAME 🌸

prng — Kernel pseudo-random number generators 🎲✨

🦋 SYNOPSIS 🦋

#include <sys/prng.h>

uint32_t
prng32(void);

uint32_t
prng32_bounded(uint32_t bound);

uint64_t
prng64(void);

uint64_t
prng64_bounded(uint64_t bound);

💖 DESCRIPTION 💖

🎀 GENERIC PRNG ROUTINES 🎀

okay so prng is like a whole family of fast, non-cryptographic pseudo-random number generators, and honestly? iconic. 🔥

the thing that makes it different from random(9) is that prng32(), prng32_bounded(), prng64(), and prng64_bounded() avoid shared global state — which means no unnecessary contention on SMP systems. like, they literally said "not today" to lock drama 💀✨

ngl these routines are not explicitly tied to any specific implementation, so they may produce different specific sequences on different hosts, reboots, or versions of FreeBSD. it's giving "mysterious and unpredictable" and we love that for them 🦋

but bestie, here's the guarantee: different CPUs in SMP systems are guaranteed to produce different sequences of integers. periodt. 👑

if you want cryptographically secure random numbers generated by the random(4) kernel cryptographically secure random number generator subsystem, you want arc4random(9) instead — that's the secure one, not this one 🌈

here's the rundown of each one:

• prng32() — generate a 32-bit integer uniformly distributed in [0, 2^32-1] 🎲
• prng32_bounded(bound) — generate an integer uniformly in the range [0, bound-1] 🎯
• prng64() — generate a 64-bit integer uniformly distributed in [0, 2^64-1] 💫
• prng64_bounded(bound) — generate an integer uniformly in the range [0, bound-1] 🍓

⚠️ okay important heads up: these routines are not reentrant; they are not safe to use in interrupt handlers ("interrupt filters" in bus_setup_intr(9) terminology). they are safe to use in all other kernel contexts, including interrupt threads ("ithreads") 😭 please remember this, i'm begging

💜 REPRODUCIBLE PRNG APIS 💜

so in addition to these per-CPU helpers, the <sys/prng.h> header also exposes the entire API of the PCG family of PRNGs as inline functions. fancy ✨

the PCG-C API is described in full at https://www.pcg-random.org/using-pcg-c.html — go read it, iykyk 📖🫶

⭐ HISTORY ⭐

prng was introduced in FreeBSD 13 🎉

---

and that's the whole page, bestie! no cap, you're now a prng expert 🌸💅 — this was the Debian build, dated August 5, 2020, so if you see that footer floating around, that's where it's from 🎀💖