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

["Tom Schwindl" <schwindl@posteo.de>]

On Sun Jan 1, 2023 at 5:26 PM CET, Alejandro Colomar wrote:
> 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.

I'm not a native speaker, but I think it should be s/in/on/.

--
Best Regards,
Tom Schwindl