From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 1791) id B5A813834E52; Fri, 22 Jul 2022 15:33:28 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org B5A813834E52 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset="utf-8" From: Adhemerval Zanella To: glibc-cvs@sourceware.org Subject: [glibc] manual: Add documentation for arc4random functions X-Act-Checkin: glibc X-Git-Author: Adhemerval Zanella Netto X-Git-Refname: refs/heads/master X-Git-Oldrev: 3b56f944c5398114486d6abd60c465682b802072 X-Git-Newrev: ca4d3ea5130d66e66c5af14e958e99341bf20689 Message-Id: <20220722153328.B5A813834E52@sourceware.org> Date: Fri, 22 Jul 2022 15:33:28 +0000 (GMT) X-BeenThere: glibc-cvs@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Glibc-cvs mailing list List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 22 Jul 2022 15:33:28 -0000 https://sourceware.org/git/gitweb.cgi?p=glibc.git;h=ca4d3ea5130d66e66c5af14e958e99341bf20689 commit ca4d3ea5130d66e66c5af14e958e99341bf20689 Author: Adhemerval Zanella Netto Date: Thu Jul 21 10:05:07 2022 -0300 manual: Add documentation for arc4random functions Diff: --- manual/math.texi | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/manual/math.texi b/manual/math.texi index 477a18b6d1..141695cc30 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,51 @@ 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 reseeded with kernel entropy on @code{fork} +and @code{_Fork}. It is not cleared on either a 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 uint32_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_buf (void *@var{buffer}, size_t @var{length}) +@standards{BSD, stdlib.h} +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}} +This function fills the region @var{buffer} of length @var{length} bytes +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