[PATCH v9 9/9] manual: Add documentation for arc4random functions
Adhemerval Zanella Netto
adhemerval.zanella@linaro.org
Thu Jul 14 11:08:14 GMT 2022
On 14/07/22 07:03, Mark Harris wrote:
> Adhemerval Zanella via Libc-alpha wrote:
>> diff --git a/manual/math.texi b/manual/math.texi
>> index 477a18b6d1..ab96726e57 100644
>> --- a/manual/math.texi
>> +++ b/manual/math.texi
>> @@ -1447,6 +1447,7 @@ systems.
>> * ISO Random:: @code{rand} and friends.
>> * BSD Random:: @code{random} and friends.
>> * SVID Random:: @code{drand48} and friends.
>> +* High Quality Random:: @code{arc4random} and friends.
>> @end menu
>>
>> @node ISO Random
>> @@ -1985,6 +1986,50 @@ This function is a GNU extension and should not be used in portable
>> programs.
>> @end deftypefun
>>
>> +@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}
>
> s/reseed/reseeded/
Ack.
>
>> +and @code{_Fork}. It is not cleared for either direct @code{clone} syscall
>
> s/for either/on either a/
>
>> +or when using @theglibc{} @code{syscall} function.
>> +
>> +The prototypes for these functions are in @file{stdlib.h}.
>> +@pindex stdlib.h
>> +
>> +@deftypefun int32_t arc4random (void)
>
> s/int32_t/uint32_t/
Ack.
>
>> +@standards{BSD, stdlib.h}
>> +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
>> +This function returns a single 32-bit value in the range of @code{0} to
>> +@code{2^32−1} (inclusive), which is twice the range of @code{rand} and
>> +@code{random}.
>> +@end deftypefun
>> +
>> +@deftypefun void arc4random (void *@var{buffer}, size_t @var{length})
>
> s/arc4random/arc4random_buf/
Ack.
>
>> +@standards{BSD, stdlib.h}
>> +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
>> +This function fills the region @var{buffer} of @var{length} with random data.
>
> s/of @var{length}/of length @var{length} bytes/
Ack.
>
>
>> +@end deftypefun
>> +
>> +@deftypefun uint32_t arc4random_uniform (uint32_t @var{upper_bound})
>> +@standards{BSD, 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.
>> +@end deftypefun
>> +
>> @node FP Function Optimizations
>> @section Is Fast Code or Small Code preferred?
>> @cindex Optimization
>> --
>> 2.34.1
>>
More information about the Libc-alpha
mailing list