BSD::arc4random(3pm)

📦
version 1.50 · 6 versions
, in ubuntu stonking

✨ BSD::arc4random(3pm) ✨

okay bestie, come closer, because this is the Perl module that lets you call the arc4random(3) family of libc functions straight from Perl, and honestly? it's giving chaos-gremlin-approved entropy. it's a 3pm manpage, so yeah, it's one of the User Contributed Perl Documentation girlies 💅

🌈 SYNOPSIS 🌈

use BSD::arc4random qw(:all);
$v = arc4random();
$v = arc4random_uniform($hz);
if (!BSD::arc4random::have_kintf()) {
  $v = arc4random_addrandom("entropy to pass to the system");
} else {
  $v = arc4random_pushb("entropy to pass to the system");
  $v = arc4random_pushk("entropy to pass to the kernel");
}
$s = arc4random_bytes(16, "entropy to pass to libc");
arc4random_stir();
$s = arc4random_bytes(16);
print $RANDOM;

like… look at her go. no cap. 🔥

💜 DESCRIPTION 💜

so basically this whole set of functions maps the arc4random(3) family of libc functions into Perl code. iconic behaviour, frankly.

good news first: all functions listed below are ithreads-safe. the internal XS functions are not, but bestie, you are not supposed to call them, either. so we're fine. 🙈

and here's a lil bonus for you: on module load, perl's internal PRNG is re-seeded — as a bonus — using srand with an argument calculated from using arc4random_pushb on some entropy returned from rand's previous state. she just does that. ✨

🎀 LOW-LEVEL FUNCTIONS 🎀

  • arc4random() — returns an unsigned 32-bit integer random value. that's it, that's the function, and she ate.
  • arc4random_addrandom(pbuf) — adds the entropy from pbuf into the libc pool, and returns an unsigned 32-bit integer random value from it.
  • arc4random_pushb(pbuf) — first pushes the pbuf argument to the kernel if possible, then pushes the entropy returned by the kernel into the libc pool, then returns an unsigned 32-bit integer random value from it. multi-step queen. 👑
  • arc4random_pushk(pbuf) — first pushes the pbuf argument to the kernel if possible, then returns an unsigned 32-bit integer random value from the kernel.
⚠️ this function is deprecated, bestie!! use arc4random_pushb instead. she's retired, respect her legacy but move on. 💀
  • arc4random_stir() — this procedure attempts to retrieve new entropy from the kernel and add it to the libc pool. usually, this means you must have access to the urandom(4) device — so create it inside chroot(2) jails first if you use them. yes, before. do not skip this step. 🫶
  • have_kintf() — this constant function returns 1 if arc4random_pushb and/or arc4random_pushk actually call the kernel interfaces, and 0 if they merely map to arc4random_addrandom instead. a little vibe check for your kernel. 🌸

🦋 HIGH-LEVEL FUNCTIONS 🦋

  • arc4random_bytes(num[, pbuf]) — returns a string containing as many random bytes as requested by the integral argument num. an optional pbuf argument is passed to the system first.
  • arc4random_uniform(upper_bound) — calculates a uniformly distributed random number less than upper_bound, avoiding "modulo bias". she's fair, she's balanced, she's that girl. ⭐

🍓 PACKAGE VARIABLES 🍓

  • $RANDOM — returns a random value in the range [0; 32767] on each read attempt, and pushes any value it is assigned to the kernel. it is tied at module load time. magical girl behaviour, honestly. 🧚
  • tie variable, 'BSD::arc4random'[, max] — you can tie any scalar variable to this package! the max argument is the maximum number returned; if it's undefined, 0, or >= 0xFFFFFFFF, no bound is used, and values in the range [0; 2**32-1] are returned. they will behave like $RANDOM. periodt. 💅

🌟 AUTHOR 🌟

Thorsten Glaser <tg@mirbsd.de>

💖 SEE ALSO 💖

Copyright (c) 2008, 2009, 2010, 2011 Thorsten "mirabilos" Glaser Copyright (c) 2009 Benny Siegert Credits to Sebastian "Vutral" Schwarz

This module is covered by the MirOS Licence:

http://mirbsd.de/MirOS-Licence

The original C implementation of arc4random_uniform was contributed by Damien Miller from OpenBSD, with simplifications by Jinmei Tatuya.

and that's the whole page, bestie!! 🎀 this was perl v5.42.3, dated 2026-08-19, and honestly she's a whole main character. go generate some entropy responsibly. mwah 💖🦋✨

📦 where this page comes from