Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 176 insertions, 0 deletions

diff --git a/man/man3/random_r.3 b/man/man3/random_r.3
new file mode 100644
index 0000000..5215975
--- /dev/null
+++ b/man/man3/random_r.3
@@ -0,0 +1,176 @@
+'\" t
+.\" Copyright 2008 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\"
+.TH random_r 3 2024-05-02 "Linux man-pages (unreleased)"
+.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>
+.P
+.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 );
+.P
+.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
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.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.
+.P
+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 .
+.P
+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.
+.P
+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.)
+.P
+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
+.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)