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) 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) device; create it
           inside chroot(2) 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) 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.