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

       Thorsten Glaser <tg@mirbsd.de>

       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.

perl v5.40.0                                       2024-10-20                               BSD::arc4random(3pm)

       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-LEVELFUNCTIONSarc4random()
           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-LEVELFUNCTIONSarc4random_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".

   PACKAGEVARIABLES$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.

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

       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.

         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;