[PATCH v6 10/10] manual: Add documentation for arc4random functions

[Florian Weimer]

* Adhemerval Zanella via Libc-alpha:

> +@node High Quality Random
> +@subsection High Quality Random Number Functions
> +
> +This section describes the random number functions provided as a GNU
> +extension, based on OpenBSD interfaces.
> +
> +@Theglibc{} uses kernel entropy obtained either through @code{getrandom}
> +or by reading @file{/dev/urandom} to seed and periodically re-seed the
> +internal state.  A per-thread data pool is used, which allows fast output
> +generation.
> +
> +Although these functions provide higher random quality than ISO, BSD, and
> +SVID functions, these still use a Pseudo-Random generator and should not
> +be used in cryptographic contexts.
> +
> +The internal state is cleared and reseed with kernel entropy on @code{fork}
> +and @code{_Fork} (it is not cleared for either direct @code{clone} syscall
> +or through glibc wrapper).

“or when using @theglibc{} @code{syscall} funcition”?

> +The prototypes for these functions are in @file{stdlib.h}.
> +@pindex stdlib.h
> +
> +@deftypefun int32_t arc4random (void)
> +@standards{GNU, stdlib.h}

Should be BSD, I think.  Likewise below.

> +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
> +This function returns a single 32-bit value in the range of 0 to 2^32−1,
> +which is twice the range of @code{rand} and @code{random}.
> +@end deftypefun

Can we use @math for the exponent?  And please say that the range is
inclusive.

> +@deftypefun uint32_t arc4random_uniform (uint32_t @var{upper_bound})
> +@standards{GNU, stdlib.h}
> +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
> +This function returns a single 32-bit value, uniformly distributed but
> +less than the @var{upper_bound}.  It avoids the @w{modulo bias} when the
> +upper bound is not a power of two.
> +
> +The algorithm obtains the exact sampling of a discrete uniform variable
> +using an optimal number of random bits for any range @var{upper_bounds},
> +allowing to consume as less as possible data from the per-thread entropy
> +pool.

I think this overspecifies the implementation.  And we obtain randomness
in blocks of 8 bits, IIRC, so it's not optimal in our implementation.

Thanks,
Florian