[thirdparty/man-pages.git] / man3 / arc4random.3

'\" t
.\" Copyright (C) 2023 Alejandro Colomar <alx@kernel.org>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH arc4random 3 (date) "Linux man-pages (unreleased)"
.SH NAME
arc4random, arc4random_uniform, arc4random_buf
\- cryptographically-secure pseudorandom number generator
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
.PP
.B uint32_t arc4random(void);
.BI "uint32_t arc4random_uniform(uint32_t " upper_bound );
.BI "void arc4random_buf(void " buf [. n "], size_t " n );
.fi
.SH DESCRIPTION
These functions give cryptographically-secure pseudorandom numbers.
.PP
.BR arc4random ()
returns a uniformly-distributed value.
.PP
.BR arc4random_uniform ()
returns a uniformly-distributed value less than
.I upper_bound
(see BUGS).
.PP
.BR arc4random_buf ()
fills the memory pointed to by
.IR buf ,
with
.I n
bytes of pseudorandom data.
.PP
The
.BR rand (3)
and
.BR drand48 (3)
families of functions should only be used where
the quality of the pseudorandom numbers is not a concern
.I and
there's a need for repeatability of the results.
Unless you meet both of those conditions,
use the
.BR arc4random ()
functions.
.SH RETURN VALUE
.BR arc4random ()
returns a pseudorandom number.
.PP
.BR arc4random_uniform ()
returns a pseudorandom number less than
.I upper_bound
for valid input, or
.B 0
when
.I upper_bound
is invalid.
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lbx lb lb
l l l.
Interface	Attribute	Value
T{
.na
.nh
.BR arc4random (),
.BR arc4random_uniform (),
.BR arc4random_buf ()
T}	Thread safety	MT-Safe
.TE
.sp 1
.SH STANDARDS
BSD.
.SH HISTORY
OpenBSD 2.1,
FreeBSD 3.0,
NetBSD 1.6,
DragonFly 1.0,
libbsd,
glibc 2.36.
.SH BUGS
An
.I upper_bound
of
.B 0
doesn't make sense in a call to
.BR arc4random_uniform ().
Such a call will fail, and return
.BR 0 .
Be careful,
since that value is
.I not
less than
.IR upper_bound .
In some cases,
such as accessing an array,
using that value could result in Undefined Behavior.
.SH SEE ALSO
.BR getrandom (3),
.BR rand (3),
.BR drand48 (3),
.BR random (7)
Commit	Line	Data
82365306	1	'\" t
848404fe AC	2	.\" Copyright (C) 2023 Alejandro Colomar <alx@kernel.org>
	3	.\"
	4	.\" SPDX-License-Identifier: Linux-man-pages-copyleft
	5	.\"
	6	.TH arc4random 3 (date) "Linux man-pages (unreleased)"
	7	.SH NAME
	8	arc4random, arc4random_uniform, arc4random_buf
	9	\- cryptographically-secure pseudorandom number generator
	10	.SH LIBRARY
	11	Standard C library
b428a1b9	12	.RI ( libc ", " \-lc )
848404fe AC	13	.SH SYNOPSIS
	14	.nf
	15	.B #include <stdlib.h>
	16	.PP
	17	.B uint32_t arc4random(void);
	18	.BI "uint32_t arc4random_uniform(uint32_t " upper_bound );
	19	.BI "void arc4random_buf(void " buf [. n "], size_t " n );
	20	.fi
	21	.SH DESCRIPTION
477c35bc	22	These functions give cryptographically-secure pseudorandom numbers.
848404fe AC	23	.PP
	24	.BR arc4random ()
	25	returns a uniformly-distributed value.
	26	.PP
	27	.BR arc4random_uniform ()
	28	returns a uniformly-distributed value less than
	29	.I upper_bound
3638ab3f	30	(see BUGS).
848404fe AC	31	.PP
	32	.BR arc4random_buf ()
	33	fills the memory pointed to by
	34	.IR buf ,
	35	with
	36	.I n
477c35bc	37	bytes of pseudorandom data.
848404fe AC	38	.PP
	39	The
	40	.BR rand (3)
	41	and
	42	.BR drand48 (3)
	43	families of functions should only be used where
477c35bc	44	the quality of the pseudorandom numbers is not a concern
848404fe AC	45	.I and
	46	there's a need for repeatability of the results.
	47	Unless you meet both of those conditions,
	48	use the
	49	.BR arc4random ()
	50	functions.
	51	.SH RETURN VALUE
	52	.BR arc4random ()
477c35bc	53	returns a pseudorandom number.
848404fe AC	54	.PP
848404fe AC	55	.BR arc4random_uniform ()
477c35bc	56	returns a pseudorandom number less than
848404fe AC	57	.I upper_bound
	58	for valid input, or
	59	.B 0
	60	when
	61	.I upper_bound
	62	is invalid.
	63	.SH ATTRIBUTES
	64	For an explanation of the terms used in this section, see
	65	.BR attributes (7).
848404fe AC	66	.TS
	67	allbox;
	68	lbx lb lb
	69	l l l.
	70	Interface Attribute Value
	71	T{
9e54434e BR	72	.na
9e54434e BR	73	.nh
848404fe AC	74	.BR arc4random (),
	75	.BR arc4random_uniform (),
	76	.BR arc4random_buf ()
	77	T} Thread safety MT-Safe
	78	.TE
848404fe AC	79	.sp 1
848404fe AC	80	.SH STANDARDS
179cc19e AC	81	BSD.
	82	.SH HISTORY
	83	OpenBSD 2.1,
	84	FreeBSD 3.0,
	85	NetBSD 1.6,
	86	DragonFly 1.0,
	87	libbsd,
	88	glibc 2.36.
3638ab3f	89	.SH BUGS
848404fe AC	90	An
	91	.I upper_bound
	92	of
	93	.B 0
	94	doesn't make sense in a call to
	95	.BR arc4random_uniform ().
	96	Such a call will fail, and return
	97	.BR 0 .
	98	Be careful,
	99	since that value is
	100	.I not
	101	less than
	102	.IR upper_bound .
	103	In some cases,
	104	such as accessing an array,
	105	using that value could result in Undefined Behavior.
	106	.SH SEE ALSO
	107	.BR getrandom (3),
	108	.BR rand (3),
	109	.BR drand48 (3),
	110	.BR random (7)