[PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[Alejandro Colomar <alx.manpages@gmail.com>]

arc4random(3)
arc4random_uniform(3)
arc4random_buf(3)

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man3/arc4random.3 | 104 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 man3/arc4random.3

diff --git a/man3/arc4random.3 b/man3/arc4random.3
new file mode 100644
index 000000000..5fd292321
--- /dev/null
+++ b/man3/arc4random.3
@@ -0,0 +1,104 @@
+.\" 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 random numbers.
+.PP
+.BR arc4random ()
+returns a uniformly-distributed value.
+.PP
+.BR arc4random_uniform ()
+returns a uniformly-distributed value less than
+.I upper_bound
+(see CAVEATS).
+.PP
+.BR arc4random_buf ()
+fills the memory pointed to by
+.IR buf ,
+with
+.I n
+bytes of random data.
+.PP
+The
+.BR rand (3)
+and
+.BR rand48 (3)
+families of functions should only be used where
+the quality of the random 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 random number.
+.PP
+.BR arc4random_uniform ()
+returns a random 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).
+.ad l
+.nh
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.BR arc4random (),
+.BR arc4random_uniform (),
+.BR arc4random_buf ()
+T}	Thread safety	MT-Safe
+.TE
+.hy
+.ad
+.sp 1
+.SH STANDARDS
+These nonstandard functions are present in several Unix systems.
+.SH CAVEATS
+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 rand48 (3),
+.BR random (7)
-- 
2.39.0