diff mbox series

[v9,9/9] manual: Add documentation for arc4random functions

Message ID 20220713173657.516725-10-adhemerval.zanella@linaro.org
State Superseded
Headers show
Series [v9,1/9] stdlib: Add arc4random, arc4random_buf, and arc4random_uniform (BZ #4417) | expand

Commit Message

Adhemerval Zanella July 13, 2022, 5:36 p.m. UTC
From: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org>

---
 manual/math.texi | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

Comments

Mark Harris July 14, 2022, 10:03 a.m. UTC | #1
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/

> +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/

> +@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/

> +@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/


> +@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
>
Adhemerval Zanella July 14, 2022, 11:08 a.m. UTC | #2
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
>>
diff mbox series

Patch

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}
+and @code{_Fork}.  It is not cleared for either direct @code{clone} syscall
+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)
+@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})
+@standards{BSD, stdlib.h}
+@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
+This function fills the region @var{buffer} of @var{length} with random data.
+@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