Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 194 insertions, 0 deletions

diff --git a/upstream/archlinux/man3p/initstate.3p b/upstream/archlinux/man3p/initstate.3p
new file mode 100644
index 00000000..dcb3cc09
--- /dev/null
+++ b/upstream/archlinux/man3p/initstate.3p
@@ -0,0 +1,194 @@
+'\" et
+.TH INITSTATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.\"
+.SH NAME
+initstate,
+random,
+setstate,
+srandom
+\(em pseudo-random number functions
+.SH SYNOPSIS
+.LP
+.nf
+#include <stdlib.h>
+.P
+char *initstate(unsigned \fIseed\fP, char *\fIstate\fP, size_t \fIsize\fP);
+long random(void);
+char *setstate(char *\fIstate\fP);
+void srandom(unsigned \fIseed\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIrandom\fR()
+function shall use a non-linear additive feedback random-number
+generator employing a default state array size of 31
+.BR long
+integers to return successive pseudo-random numbers in the range from 0
+to 2\u\s-331\s+3\d\-1. The period of this random-number generator is
+approximately 16 x (2\s-3\u31\d\s+3\-\fR1). The size of the state
+array determines the period of the random-number generator. Increasing
+the state array size shall increase the period.
+.P
+With 256 bytes of state information, the period of the random-number
+generator shall be greater than 2\s-3\u69\d\s+3.
+.P
+Like
+\fIrand\fR(),
+\fIrandom\fR()
+shall produce by default a sequence of numbers that can be duplicated
+by calling
+\fIsrandom\fR()
+with 1 as the seed.
+.P
+The
+\fIsrandom\fR()
+function shall initialize the current state array using the value of
+.IR seed .
+.P
+The
+\fIinitstate\fR()
+and
+\fIsetstate\fR()
+functions handle restarting and changing random-number generators. The
+\fIinitstate\fR()
+function allows a state array, pointed to by the
+.IR state
+argument, to be initialized for future use. The
+.IR size
+argument, which specifies the size in bytes of the state array, shall
+be used by
+\fIinitstate\fR()
+to decide what type of random-number generator to use; the larger the
+state array, the more random the numbers. Values for the amount of
+state information are 8, 32, 64, 128, and 256 bytes. Other values
+greater than 8 bytes are rounded down to the nearest one of these
+values. If
+\fIinitstate\fR()
+is called with 8\(<=\fIsize\fR<32, then
+\fIrandom\fR()
+shall use a simple linear congruential random number generator. The
+.IR seed
+argument specifies a starting point for the random-number sequence and
+provides for restarting at the same point. The
+\fIinitstate\fR()
+function shall return a pointer to the previous state information array.
+.P
+If
+\fIinitstate\fR()
+has not been called, then
+\fIrandom\fR()
+shall behave as though
+\fIinitstate\fR()
+had been called with
+.IR seed =1
+and
+.IR size =128.
+.P
+Once a state has been initialized,
+\fIsetstate\fR()
+allows switching between state arrays. The array defined by the
+.IR state
+argument shall be used for further random-number generation until
+\fIinitstate\fR()
+is called or
+\fIsetstate\fR()
+is called again. The
+\fIsetstate\fR()
+function shall return a pointer to the previous state array.
+.SH "RETURN VALUE"
+If
+\fIinitstate\fR()
+is called with
+.IR size
+less than 8, it shall return NULL.
+.P
+The
+\fIrandom\fR()
+function shall return the generated pseudo-random number.
+.P
+The
+\fIsrandom\fR()
+function shall not return a value.
+.P
+Upon successful completion,
+\fIinitstate\fR()
+and
+\fIsetstate\fR()
+shall return a pointer to the previous state array; otherwise, a null
+pointer shall be returned.
+.SH ERRORS
+No errors are defined.
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+None.
+.SH "APPLICATION USAGE"
+After initialization, a state array can be restarted at a different
+point in one of two ways:
+.IP " 1." 4
+The
+\fIinitstate\fR()
+function can be used, with the desired seed, state array, and size of
+the array.
+.IP " 2." 4
+The
+\fIsetstate\fR()
+function, with the desired state, can be used, followed by
+\fIsrandom\fR()
+with the desired seed. The advantage of using both of these functions
+is that the size of the state array does not have to be saved once it
+is initialized.
+.P
+Although some implementations of
+\fIrandom\fR()
+have written messages to standard error, such implementations do not
+conform to POSIX.1\(hy2008.
+.P
+Issue 5 restored the historical behavior of this function.
+.P
+Threaded applications should use
+\fIerand48\fR(),
+\fInrand48\fR(),
+or
+\fIjrand48\fR()
+instead of
+\fIrandom\fR()
+when an independent random number sequence in multiple threads is
+required.
+.P
+These functions should be avoided whenever non-trivial requirements
+(including safety) have to be fulfilled.
+.SH RATIONALE
+None.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIdrand48\fR\^(\|)",
+.IR "\fIrand\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<stdlib.h>\fP"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group.
+In the event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .
+.PP
+Any typographical or formatting errors that appear
+in this page are most likely
+to have been introduced during the conversion of the source files to
+man page format. To report such errors, see
+https://www.kernel.org/doc/man-pages/reporting_bugs.html .