From: Alejandro Colomar <alx.manpages@gmail.com>
To: linux-man@vger.kernel.org
Cc: Alejandro Colomar <alx@kernel.org>,
libc-alpha@sourceware.org, "Jason A. Donenfeld" <Jason@zx2c4.com>
Subject: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions
Date: Sun, 1 Jan 2023 17:26:28 +0100 [thread overview]
Message-ID: <20230101162627.28031-1-alx@kernel.org> (raw)
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
next reply other threads:[~2023-01-01 16:26 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-01-01 16:26 Alejandro Colomar [this message]
2023-01-01 16:27 ` Alejandro Colomar
2023-03-17 21:31 ` Jakub Wilk
2023-03-17 21:44 ` Alejandro Colomar
2023-03-17 21:54 ` Alejandro Colomar
2023-01-01 16:39 ` Tom Schwindl
2023-01-01 16:41 ` Alejandro Colomar
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230101162627.28031-1-alx@kernel.org \
--to=alx.manpages@gmail.com \
--cc=Jason@zx2c4.com \
--cc=alx@kernel.org \
--cc=libc-alpha@sourceware.org \
--cc=linux-man@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).