random(3)

🎲 random(3) — the manual page, but make it make sense 💅

okay bestie, so this is the random(3) page from your friendly neighborhood Library Functions Manual, and it lives in the Standard C library (libc, -lc). pull up a chair, we're talking pseudo-random numbers and it's lowkey iconic 🎀

---

✨ NAME ✨

random, srandom, initstate, setstate — random number generator 🦋

no fr that's the whole name section. four lil functions. one big vibe.

---

📚 LIBRARY 📚

Standard C library (libc, -lc)

---

🫶 SYNOPSIS 🫶

#include <stdlib.h>

long random(void);
void srandom(unsigned int seed);

char *initstate(size_t n;
                unsigned int seed, char state[n], size_t n);
char *setstate(char *state);

🌸 Feature Test Macro Requirements for glibc (see feature_test_macros(7)): 🌸

random(), srandom(), initstate(), setstate():

_XOPEN_SOURCE >= 500
    || /* glibc >= 2.19: */ _DEFAULT_SOURCE
    || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE

---

💖 DESCRIPTION 💖

okay so first up, random(). she uses a nonlinear additive feedback random number generator and she's serving a default table of size 31 long integers, handing you successive pseudo-random numbers in the range from 0 to 2^31 - 1. and the period? literally enormous. approximately 16 * ((2^31) - 1). she's committed, periodt 👑

then there's srandom(), which takes its argument and sets it as the seed for a whole new sequence of pseudo-random integers that random() is gonna return. the way that these sequences are repeatable if you call srandom() with the same seed value... obsessed. and if you don't provide a seed at all, random() just auto-seeds itself with a value of 1. she's independent like that 🙈

next, initstate() — she lets you initialize a state array state for random() to use. the size of that state array, n, is what initstate() uses to decide how sophisticated a random number generator it should go with. and bestie, the rule is simple: the larger the state array, the better the random numbers will be ✨ the current "optimal" values for the size of the state array n are 8, 32, 64, 128, and 256 bytes. other amounts? they get rounded down to the nearest known amount. and using less than 8 bytes results in an error, so don't do that 💀

also seed is the seed for the initialization — it specifies a starting point for the random number sequence, and it provides for restarting at the same point. so you can go back, iykyk 🧚

and finally setstate() — she changes the state array that random() is using. the state array state is used for random number generation until the next call to initstate() or setstate(). but important: state must first have been initialized using initstate(), or be the result of a previous call of setstate(). no shortcuts, bestie 🫣

---

🎁 RETURN VALUE 🎁

• random() returns a value between 0 and (2^31) - 1. cute.
• srandom() returns no value. she gives nothing and takes nothing 💅
• initstate() returns a pointer to the previous state array. On failure, it returns NULL, and errno is set to indicate the error. flag it 😭
• On success, setstate() returns a pointer to the previous state array. On failure, it returns NULL, and errno is set to indicate the error. same energy fr fr.

---

💀 ERRORS 💀

• EINVAL — the state argument given to setstate() was NULL. girl, you passed nothing. nothing. 🫠
• EINVAL — a state array of less than 8 bytes was specified to initstate(). tiny state array. no notes. just no.

---

🔥 ATTRIBUTES 🔥

for an explanation of the terms used in this section, see attributes(7).

• random(), srandom(), initstate(), setstate() — Thread safety: MT-Safe ✅

all four of them. MT-Safe. every single one. the whole squad is safe, we love to see it 🌈

---

📜 STANDARDS 📜

POSIX.1-2008. certified, bestie 💖

---

🦕 HISTORY 🦕

POSIX.1-2001, 4.3BSD. she's been around. she's got lore. she's vintage 👑

---

🧠 NOTES 🧠

ngl random-number generation is a complex topic, and if you want the real tea, these two are the reads:

• Numerical Recipes in C: The Art of Scientific Computing (William H. Press, Brian P. Flannery, Saul A. Teukolsky, William T. Vetterling; New York: Cambridge University Press, 2007, 3rd ed.) — provides an excellent discussion of practical random-number generation issues in Chapter 7 (Random Numbers). 🍓
• For a more theoretical discussion which also covers many practical issues in depth, see Chapter 3 (Random Numbers) in Donald E. Knuth's The Art of Computer Programming, volume 2 (Seminumerical Algorithms), 2nd ed.; Reading, Massachusetts: Addison-Wesley Publishing Company, 1981. 🧚

like, actual textbooks. for a random number generator. and honestly? we respect it.

---

⚠️ CAVEATS ⚠️

heads up bestie: the random() function should not be used in multithreaded programs where reproducible behavior is required. use random_r(3) for that purpose. no cap. this one matters 🔥

---

🐛 BUGS 🐛

According to POSIX, initstate() should return NULL on error. In the glibc implementation, errno is (as specified) set on error, but the function does not return NULL. so like... the man page said one thing and glibc said another. it's giving discrepancy 💀 and it's a documented one, so now you know 🌸

---

👀 SEE ALSO 👀

• getrandom(2)
• drand48(3)
• rand(3)
• random_r(3)
• srand(3)

---

<div align="center">and that's the whole page bestie!! go forth and generate numbers responsibly 🎲💖✨</div>

this diva of a man page is brought to you by Linux man-pages 6.20, dated 2026-02-08, and it's the random(3) page — now go seed something (with srandom(), obviously) 🎀🦋