Merging upstream version 6.8.

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

1 files changed, 193 insertions, 0 deletions

diff --git a/man/man3/random.3 b/man/man3/random.3
new file mode 100644
index 0000000..ff788e4
--- /dev/null
+++ b/man/man3/random.3
@@ -0,0 +1,193 @@
+'\" t
+.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" References consulted:
+.\"     Linux libc source code
+.\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
+.\"     386BSD man pages
+.\" Modified Sun Mar 28 00:25:51 1993, David Metcalfe
+.\" Modified Sat Jul 24 18:13:39 1993 by Rik Faith (faith@cs.unc.edu)
+.\" Modified Sun Aug 20 21:47:07 2000, aeb
+.\"
+.TH random 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+random, srandom, initstate, setstate \- random number generator
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdlib.h>
+.P
+.B long random(void);
+.BI "void srandom(unsigned int " seed );
+.P
+.BI "char *initstate(unsigned int " seed ", char " state [. n "], size_t " n );
+.BI "char *setstate(char *" state );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR random (),
+.BR srandom (),
+.BR initstate (),
+.BR setstate ():
+.nf
+    _XOPEN_SOURCE >= 500
+.\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
+        || /* glibc >= 2.19: */ _DEFAULT_SOURCE
+        || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
+.fi
+.SH DESCRIPTION
+The
+.BR random ()
+function uses a nonlinear additive feedback random
+number generator employing a default table of size 31 long integers to
+return successive pseudo-random numbers in
+the range from 0 to 2\[ha]31\ \-\ 1.
+The period of this random number generator is very large, approximately
+.IR "16\ *\ ((2\[ha]31)\ \-\ 1)" .
+.P
+The
+.BR srandom ()
+function sets its argument as the seed for a new
+sequence of pseudo-random integers to be returned by
+.BR random ().
+These sequences are repeatable by calling
+.BR srandom ()
+with the same
+seed value.
+If no seed value is provided, the
+.BR random ()
+function
+is automatically seeded with a value of 1.
+.P
+The
+.BR initstate ()
+function allows a state array \fIstate\fP to
+be initialized for use by
+.BR random ().
+The size of the state array
+\fIn\fP is used by
+.BR initstate ()
+to decide how sophisticated a
+random number generator it should use\[em]the larger the state array,
+the better the random numbers will be.
+Current "optimal" values for the size of the state array \fIn\fP are
+8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to
+the nearest known amount.
+Using less than 8 bytes results in an error.
+\fIseed\fP is the seed for the
+initialization, which specifies a starting point for the random number
+sequence, and provides for restarting at the same point.
+.P
+The
+.BR setstate ()
+function changes the state array used by the
+.BR random ()
+function.
+The state array \fIstate\fP is used for
+random number generation until the next call to
+.BR initstate ()
+or
+.BR setstate ().
+\fIstate\fP must first have been initialized
+using
+.BR initstate ()
+or be the result of a previous call of
+.BR setstate ().
+.SH RETURN VALUE
+The
+.BR random ()
+function returns a value between 0 and
+.IR "(2\[ha]31)\ \-\ 1" .
+The
+.BR srandom ()
+function returns no value.
+.P
+The
+.BR initstate ()
+function returns a pointer to the previous state array.
+On failure, it returns NULL, and
+.I errno
+is set to indicate the error.
+.P
+On success,
+.BR setstate ()
+returns a pointer to the previous state array.
+On failure, it returns NULL, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+The
+.I state
+argument given to
+.BR setstate ()
+was NULL.
+.TP
+.B EINVAL
+A state array of less than 8 bytes was specified to
+.BR initstate ().
+.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 (),
+.BR srandom (),
+.BR initstate (),
+.BR setstate ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, 4.3BSD.
+.SH NOTES
+Random-number generation is a complex topic.
+.I Numerical Recipes in C: The Art of Scientific Computing
+(William H.\& Press, Brian P.\& Flannery, Saul A.\& Teukolsky,
+William T.\& Vetterling; New York: Cambridge University Press, 2007, 3rd ed.)
+provides an excellent discussion of practical random-number generation
+issues in Chapter 7 (Random Numbers).
+.P
+For a more theoretical discussion which also covers many practical issues
+in depth, see Chapter 3 (Random Numbers) in Donald E.\& Knuth's
+.IR "The Art of Computer Programming" ,
+volume 2 (Seminumerical Algorithms), 2nd ed.; Reading, Massachusetts:
+Addison-Wesley Publishing Company, 1981.
+.SH CAVEATS
+The
+.BR random ()
+function should not be used in multithreaded programs
+where reproducible behavior is required.
+Use
+.BR random_r (3)
+for that purpose.
+.SH BUGS
+According to POSIX,
+.BR initstate ()
+should return NULL on error.
+In the glibc implementation,
+.I errno
+is (as specified) set on error, but the function does not return NULL.
+.\" http://sourceware.org/bugzilla/show_bug.cgi?id=15380
+.SH SEE ALSO
+.BR getrandom (2),
+.BR drand48 (3),
+.BR rand (3),
+.BR random_r (3),
+.BR srand (3)