home | help 
RANDOM(9)		    Kernel Developer's Manual		       RANDOM(9)

NAME
     arc4rand, arc4random, random, read_random, read_random_uio, srandom -- sup-
     ply pseudo-random numbers

SYNOPSIS
     #include <sys/libkern.h>

     void
     srandom(u_long seed);

     u_long
     random(void);

     void
     arc4rand(void *ptr, u_int length, int reseed);

     uint32_t
     arc4random(void);

     #include <sys/random.h>

     int
     read_random(void *buffer, int count);

     int
     read_random_uio(struct uio *uio, bool nonblock);

DESCRIPTION
     The  random()  function  will by default produce a sequence of numbers that
     can be duplicated by calling srandom() with some constant as the seed.  The
     srandom() function may be called with  any  arbitrary  seed  value  to  get
     slightly  more unpredictable numbers.  It is important to remember that the
     random() function is entirely predictable, and  is  therefore  not  of  use
     where  knowledge  of  the	sequence  of numbers may be of benefit to an at-
     tacker.

     The arc4rand() function will return very good quality random numbers,  bet-
     ter   suited  for	security-related  purposes.   The  random  numbers  from
     arc4rand() are seeded from the entropy device if it  is  available.   Auto-
     matic  reseeds happen after a certain timeinterval and after a certain num-
     ber of bytes have been delivered.	A forced reseed can be forced by passing
     a non-zero value in the reseed argument.

     The read_random() function is used to return entropy directly from the  en-
     tropy  device  if it has been loaded.  If the entropy device is not loaded,
     then the buffer is ignored and zero is returned.  The buffer is filled with
     no more than count bytes.	It is strongly advised that read_random() is not
     used; instead use arc4rand() unless it is necessary to know that no entropy
     has been returned.

     The  read_random_uio()  function  behaves	 identically   to   read(2)   on
     /dev/random.   The uio argument points to a buffer where random data should
     be stored.  This function only returns data if the random device is seeded.
     It blocks if unseeded, except when the nonblock argument is true.

     All the bits returned by random(), arc4rand(), read_random(), and read_ran-
     dom_uio() are usable.  For example, `random()&01' will produce a random bi-
     nary value.

     The arc4random() is a convenience function which calls arc4rand() to return
     a 32 bit pseudo-random integer.

RETURN VALUES
     The random() function uses a non-linear  additive	feedback  random  number
     generator	employing a default table of size 31 containing long integers to
     return successive pseudo-random numbers in the range from 0  to  (2**31)-1.
     The  period  of  this  random number generator is very large, approximately
     16*((2**31)-1).

     The arc4rand() function uses  the	RC4  algorithm	to  generate  successive
     pseudo-random bytes.  The arc4random() function uses arc4rand() to generate
     pseudo-random numbers in the range from 0 to (2**32)-1.

     The read_random() function returns the number of bytes placed in buffer.

     read_random_uio()	returns zero when successful, otherwise an error code is
     returned.

ERRORS
     read_random_uio() may fail if:

     [EFAULT]		uio points to an invalid memory region.

     [EWOULDBLOCK]	The random device is unseeded and nonblock is true.

AUTHORS
     Dan Moschuk wrote arc4random().
     Mark R V Murray wrote read_random().

FreeBSD 11.2			  July 16, 2015 		       RANDOM(9)
home | help