diff mbox series

[v5,10/10] manual: Add documentation for arc4random functions

Message ID 20220504135921.3679585-11-adhemerval.zanella@linaro.org
State Superseded
Headers
Series Add arc4random support |

Checks

Context Check Description
dj/TryBot-apply_patch success Patch applied to master at the time it was sent
dj/TryBot-32bit success Build for i686

Commit Message

Adhemerval Zanella May 4, 2022, 1:59 p.m. UTC 
  ---
 manual/math.texi | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
diff mbox series

Patch

diff --git a/manual/math.texi b/manual/math.texi
index 477a18b6d1..8e7d313752 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 prototypes for these functions are in @file{stdlib.h}.
+@pindex stdlib.h
+
+@deftypefun int32_t arc4random (void)
+@standards{GNU, stdlib.h}
+@safety{@mtsafe{}@assafe{}@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
+
+@deftypefun void arc4random (void *@var{buffer}, size_t @var{length})
+@standards{GNU, stdlib.h}
+@safety{@mtsafe{}@assafe{}@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{GNU, stdlib.h}
+@safety{@mtsafe{}@assafe{}@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.
+@end deftypefun
+
 @node FP Function Optimizations
 @section Is Fast Code or Small Code preferred?
 @cindex Optimization