---
name: "BSD::arc4random"
section: "3pm"
platform: "linux"
package: "libbsd-arc4random-perl"
version: "1.50-8+b4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/BSD::arc4random"
---

# BSD::arc4random(3pm)

Perl interface to the arc4 random number generator

## NAME

BSD::arc4random - Perl interface to the arc4 random number generator

## 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;
```

## DESCRIPTION

This set of functions maps the [**arc4random**(3)](/arc4random/3.md) family of libc functions into Perl code. All functions listed below are ithreads-safe. The internal XS functions are not, but you are not supposed to call them, either.

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.

### LOW-LEVEL FUNCTIONS

- **arc4random**()

  This function returns an unsigned 32-bit integer random value.

- **arc4random\_addrandom**(*pbuf*)

  This function adds the entropy from *pbuf* into the libc pool and returns an unsigned 32-bit integer random value from it.

- **arc4random\_pushb**(*pbuf*)

  This function first pushes the *pbuf* argument to the kernel if possible, then the entropy returned by the kernel into the libc pool, then returns an unsigned 32-bit integer random value from it.

- **arc4random\_pushk**(*pbuf*)

  This function 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. Use **arc4random\_pushb** instead.

- **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)](/urandom/4.md) device; create it inside [**chroot**(2)](/chroot/2.md) jails first if you use them.

- **have\_kintf**()

  This constant function returns 1 if **arc4random\_pushb** and/or **arc4random\_pushk** actually call the kernel interfaces, 0 if they merely map to **arc4random\_addrandom** instead.

### HIGH-LEVEL FUNCTIONS

- **arc4random\_bytes**(*num*\[, *pbuf*\])

  This function 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*)

  Calculate a uniformly distributed random number less than upper\_bound avoiding "modulo bias".

### PACKAGE VARIABLES

- **$RANDOM**

  The **$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.

- tie *variable*, 'BSD::arc4random'\[, *max*\]

  You can tie any scalar variable to this package; the *max* argument is the maximum number returned; if undefined, 0 or \>= 0xFFFFFFFF, no bound is used, and values in the range \[0; 2\*\*32-1\] are returned. They will behave like **$RANDOM**.

## AUTHOR

Thorsten Glaser \<tg@mirbsd.de\>

## SEE ALSO

The [**arc4random**(3)](/arc4random/3.md) manual page, available online at: \<https://www.mirbsd.org/man/arc4random.3\>

Perl's rand and srand functions via perlfunc and perlfaq4.

The **randex.pl** plugin for Irssi, implementing the MirOS RANDEX protocol (entropy exchange over IRC), with CVSweb at: \<http://cvs.mirbsd.de/ports/net/irssi/files/randex.pl\>

\<https://www.mirbsd.org/a4rp5bsd.htm\> when it's done being written.

## COPYRIGHT AND LICENSE

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.