Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

NAME
     arc4rand, arc4random, random, read_random,	read_random_uio, srandom --
     supply 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
     attacker.

     The arc4rand() function will return very good quality random numbers,
     better 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
     number 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
     entropy 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_random_uio() are usable.  For	example, `random()&01' will produce a
     random binary 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	gener-
     ate 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.1			 July 16, 2015			  FreeBSD 11.1
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=arc4random&sektion=9&manpath=FreeBSD+11.1-RELEASE+and+Ports>

home | help