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

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

[-- Attachment #1.1: Type: text/plain, Size: 2975 bytes --]

arc4random(3)              Library Functions Manual              arc4random(3)

NAME
        arc4random,  arc4random_uniform, arc4random_buf - cryptographically‐se‐
        cure pseudorandom number generator

LIBRARY
        Standard C library (libc, ‐lc)

SYNOPSIS
        #include <stdlib.h>

        uint32_t arc4random(void);
        uint32_t arc4random_uniform(uint32_t upper_bound);
        void arc4random_buf(void buf[.n], size_t n);

DESCRIPTION
        These functions give cryptographically‐secure random numbers.

        arc4random() returns a uniformly‐distributed value.

        arc4random_uniform() returns a uniformly‐distributed  value  less  than
        upper_bound (see CAVEATS).

        arc4random_buf()  fills  the  memory pointed to by buf, with n bytes of
        random data.

        The rand(3) and rand48(3) families of functions  should  only  be  used
        where  the quality of the random numbers is not a concern and there’s a
        need for repeatability of the results.  Unless you meet both  of  those
        conditions, use the arc4random() functions.

RETURN VALUE
        arc4random() returns a random number.

        arc4random_uniform()  returns a random number less than upper_bound for
        valid input, or 0 when upper_bound is invalid.

ATTRIBUTES
        For an explanation of the terms  used  in  this  section,  see  attrib‐
        utes(7).
        ┌────────────────────────────────────────────┬───────────────┬─────────┐
        │Interface                                   │ Attribute     │ Value   │
        ├────────────────────────────────────────────┼───────────────┼─────────┤
        │arc4random(), arc4random_uniform(),         │ Thread safety │ MT‐Safe │
        │arc4random_buf()                            │               │         │
        └────────────────────────────────────────────┴───────────────┴─────────┘

STANDARDS
        These nonstandard functions are present in several Unix systems.

CAVEATS
        An  upper_bound  of  0  doesn’t make sense in a call to arc4random_uni‐
        form().  Such a call will fail, and return 0.  Be careful,  since  that
        value  is  not less than upper_bound.  In some cases, such as accessing
        an array, using that value could result in Undefined Behavior.

SEE ALSO
        getrandom(3), rand(3), rand48(3), random(7)

Linux man‐pages (unreleased)        (date)                       arc4random(3)

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]