[thirdparty/man-pages.git] / man / 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>
.P
.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.
.P
.BR arc4random ()
returns a uniformly-distributed value.
.P
.BR arc4random_uniform ()
returns a uniformly-distributed value less than
.I upper_bound
(see BUGS).
.P
.BR arc4random_buf ()
fills the memory pointed to by
.IR buf ,
with
.I n
bytes of pseudorandom data.
.P
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.
.P
.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
.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>
c6d039a3	16	.P
848404fe AC	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.
c6d039a3	23	.P
848404fe AC	24	.BR arc4random ()
848404fe AC	25	returns a uniformly-distributed value.
c6d039a3	26	.P
848404fe AC	27	.BR arc4random_uniform ()
	28	returns a uniformly-distributed value less than
	29	.I upper_bound
3638ab3f	30	(see BUGS).
c6d039a3	31	.P
848404fe AC	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.
c6d039a3	38	.P
848404fe AC	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.
c6d039a3	54	.P
848404fe	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	79	.SH STANDARDS
179cc19e AC	80	BSD.
	81	.SH HISTORY
	82	OpenBSD 2.1,
	83	FreeBSD 3.0,
	84	NetBSD 1.6,
	85	DragonFly 1.0,
	86	libbsd,
	87	glibc 2.36.
3638ab3f	88	.SH BUGS
848404fe AC	89	An
	90	.I upper_bound
	91	of
	92	.B 0
	93	doesn't make sense in a call to
	94	.BR arc4random_uniform ().
	95	Such a call will fail, and return
	96	.BR 0 .
	97	Be careful,
	98	since that value is
	99	.I not
	100	less than
	101	.IR upper_bound .
	102	In some cases,
	103	such as accessing an array,
	104	using that value could result in Undefined Behavior.
	105	.SH SEE ALSO
	106	.BR getrandom (3),
	107	.BR rand (3),
	108	.BR drand48 (3),
	109	.BR random (7)