| 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 |
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 >
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 --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
From: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org> --- manual/math.texi | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+)