BSD::arc4random(3pm)					User Contributed Perl Documentation				      BSD::arc4random(3pm)

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 <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.14.2							    2011-06-05						      BSD::arc4random(3pm)