1 files changed, 109 insertions, 0 deletions
diff --git a/man/man3/arc4random.3 b/man/man3/arc4random.3
new file mode 100644
index 0000000..44e6674
--- /dev/null
+++ b/man/man3/arc4random.3
@@ -0,0 +1,109 @@
+'\" t
+.\" Copyright (C) 2023 Alejandro Colomar <alx@kernel.org>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH arc4random 3 2024-05-02 "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)