[apple/xnu.git] / bsd / man / man4 / random.4

.Dd September 6, 2001
.Dt RANDOM 4
.Os Darwin
.Sh NAME
.Nm random
,
.Nm urandom
.Nd random data source devices.
.Sh SYNOPSIS
.Cd "pseudo-device random"
.Sh DESCRIPTION
The
.Nm
device produces uniformly distributed random byte values
of potentially high quality.
.Pp
To obtain random bytes, open
.Nm /dev/random
for reading and read from it.
.Pp
The same random data is also available from
.Xr getentropy 2 .
Using the
.Xr getentropy 2
system call interface will provide resiliency to file descriptor exhaustion, chroot, or sandboxing which can make
.Nm /dev/random
unavailable.  Additionally, the
.Xr arc4random 3
API provides a fast userspace random number generator built on the
.Nm
data source and is preferred over directly accessing the system's random device.
.Pp
.Nm /dev/urandom
is a compatibility nod to Linux. On Linux,
.Nm /dev/urandom
will produce lower quality output if the entropy pool drains, while
.Nm /dev/random
will prefer to block and wait for additional entropy to be collected.
With Yarrow, this choice and distinction is not necessary, and
the two devices behave identically. You may use either.
.Pp
The
.Nm
device implements the
.Nm Yarrow
pseudo random number generator algorithm and maintains its entropy pool.
The kernel automatically seeds the algorithm with additional entropy during normal execution.
.Sh FILES
.Bl -tag -width /dev/urandom -compact
.It Pa /dev/random
.It Pa /dev/urandom
.El
.Sh HISTORY
A
.Nm
device appeared in the Linux operating system.
Commit	Line	Data
9bccf70c A	1	.Dd September 6, 2001
	2	.Dt RANDOM 4
	3	.Os Darwin
	4	.Sh NAME
	5	.Nm random
	6	,
	7	.Nm urandom
	8	.Nd random data source devices.
	9	.Sh SYNOPSIS
	10	.Cd "pseudo-device random"
	11	.Sh DESCRIPTION
	12	The
	13	.Nm
	14	device produces uniformly distributed random byte values
	15	of potentially high quality.
	16	.Pp
	17	To obtain random bytes, open
	18	.Nm /dev/random
	19	for reading and read from it.
	20	.Pp
39037602 A	21	The same random data is also available from
	22	.Xr getentropy 2 .
	23	Using the
	24	.Xr getentropy 2
	25	system call interface will provide resiliency to file descriptor exhaustion, chroot, or sandboxing which can make
9bccf70c	26	.Nm /dev/random
39037602 A	27	unavailable. Additionally, the
	28	.Xr arc4random 3
	29	API provides a fast userspace random number generator built on the
	30	.Nm
	31	data source and is preferred over directly accessing the system's random device.
9bccf70c A	32	.Pp
	33	.Nm /dev/urandom
	34	is a compatibility nod to Linux. On Linux,
	35	.Nm /dev/urandom
	36	will produce lower quality output if the entropy pool drains, while
	37	.Nm /dev/random
	38	will prefer to block and wait for additional entropy to be collected.
	39	With Yarrow, this choice and distinction is not necessary, and
	40	the two devices behave identically. You may use either.
39037602	41	.Pp
9bccf70c A	42	The
	43	.Nm
	44	device implements the
	45	.Nm Yarrow
	46	pseudo random number generator algorithm and maintains its entropy pool.
39037602	47	The kernel automatically seeds the algorithm with additional entropy during normal execution.
9bccf70c A	48	.Sh FILES
	49	.Bl -tag -width /dev/urandom -compact
	50	.It Pa /dev/random
	51	.It Pa /dev/urandom
	52	.El
	53	.Sh HISTORY
	54	A
	55	.Nm
6d2010ae	56	device appeared in the Linux operating system.