diff options
Diffstat (limited to '')
| -rw-r--r-- | man3/random_r.3 | 177 |
1 files changed, 177 insertions, 0 deletions
diff --git a/man3/random_r.3 b/man3/random_r.3 new file mode 100644 index 0000000..c812c2f --- /dev/null +++ b/man3/random_r.3 @@ -0,0 +1,177 @@ +'\" t +.\" Copyright 2008 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH random_r 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +random_r, srandom_r, initstate_r, setstate_r \- reentrant +random number generator +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.PP +.BI "int random_r(struct random_data *restrict " buf , +.BI " int32_t *restrict " result ); +.BI "int srandom_r(unsigned int " seed ", struct random_data *" buf ); +.PP +.BI "int initstate_r(unsigned int " seed ", \ +char " statebuf "[restrict ." statelen ], +.BI " size_t " statelen ", struct random_data *restrict " buf ); +.BI "int setstate_r(char *restrict " statebuf , +.BI " struct random_data *restrict " buf ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR random_r (), +.BR srandom_r (), +.BR initstate_r (), +.BR setstate_r (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +These functions are the reentrant equivalents +of the functions described in +.BR random (3). +They are suitable for use in multithreaded programs where each thread +needs to obtain an independent, reproducible sequence of random numbers. +.PP +The +.BR random_r () +function is like +.BR random (3), +except that instead of using state information maintained +in a global variable, +it uses the state information in the argument pointed to by +.IR buf , +which must have been previously initialized by +.BR initstate_r (). +The generated random number is returned in the argument +.IR result . +.PP +The +.BR srandom_r () +function is like +.BR srandom (3), +except that it initializes the seed for the random number generator +whose state is maintained in the object pointed to by +.IR buf , +which must have been previously initialized by +.BR initstate_r (), +instead of the seed associated with the global state variable. +.PP +The +.BR initstate_r () +function is like +.BR initstate (3) +except that it initializes the state in the object pointed to by +.IR buf , +rather than initializing the global state variable. +Before calling this function, the +.I buf.state +field must be initialized to NULL. +The +.BR initstate_r () +function records a pointer to the +.I statebuf +argument inside the structure pointed to by +.IR buf . +Thus, +.I statebuf +should not be deallocated so long as +.I buf +is still in use. +(So, +.I statebuf +should typically be allocated as a static variable, +or allocated on the heap using +.BR malloc (3) +or similar.) +.PP +The +.BR setstate_r () +function is like +.BR setstate (3) +except that it modifies the state in the object pointed to by +.IR buf , +rather than modifying the global state variable. +\fIstate\fP must first have been initialized +using +.BR initstate_r () +or be the result of a previous call of +.BR setstate_r (). +.SH RETURN VALUE +All of these functions return 0 on success. +On error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +A state array of less than 8 bytes was specified to +.BR initstate_r (). +.TP +.B EINVAL +The +.I statebuf +or +.I buf +argument to +.BR setstate_r () +was NULL. +.TP +.B EINVAL +The +.I buf +or +.I result +argument to +.BR random_r () +was NULL. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR random_r (), +.BR srandom_r (), +.BR initstate_r (), +.BR setstate_r () +T} Thread safety MT-Safe race:buf +.TE +.sp 1 +.SH STANDARDS +GNU. +.\" These functions appear to be on Tru64, but don't seem to be on +.\" Solaris, HP-UX, or FreeBSD. +.SH BUGS +The +.BR initstate_r () +interface is confusing. +.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=3662 +It appears that the +.I random_data +type is intended to be opaque, +but the implementation requires the user to either initialize the +.I buf.state +field to NULL or zero out the entire structure before the call. +.SH SEE ALSO +.BR drand48 (3), +.BR rand (3), +.BR random (3) |