Adding upstream version 6.05.01.upstream/6.05.01

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

1 files changed, 241 insertions, 0 deletions

diff --git a/man3/rand.3 b/man3/rand.3
new file mode 100644
index 0000000..6146ce9
--- /dev/null
+++ b/man3/rand.3
@@ -0,0 +1,241 @@
+'\" 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 1993-03-29, David Metcalfe
+.\" Modified 1993-04-28, Lars Wirzenius
+.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu)
+.\" Modified 1995-05-18, Rik Faith (faith@cs.unc.edu) to add
+.\"          better discussion of problems with rand on other systems.
+.\"          (Thanks to Esa Hyyti{ (ehyytia@snakemail.hut.fi).)
+.\" Modified 1998-04-10, Nicolás Lichtmaier <nick@debian.org>
+.\"          with contribution from Francesco Potorti <F.Potorti@cnuce.cnr.it>
+.\" Modified 2003-11-15, aeb, added rand_r
+.\" 2010-09-13, mtk, added example program
+.\"
+.TH rand 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+rand, rand_r, srand \- pseudo-random number generator
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdlib.h>
+.PP
+.B int rand(void);
+.BI "void srand(unsigned int " seed );
+.PP
+.BI "[[deprecated]] int rand_r(unsigned int *" seedp );
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR rand_r ():
+.nf
+    Since glibc 2.24:
+        _POSIX_C_SOURCE >= 199506L
+    glibc 2.23 and earlier
+        _POSIX_C_SOURCE
+.fi
+.SH DESCRIPTION
+The
+.BR rand ()
+function returns a pseudo-random integer in the range 0 to
+.B RAND_MAX
+inclusive (i.e., the mathematical range [0,\ \fBRAND_MAX\fR]).
+.PP
+The
+.BR srand ()
+function sets its argument as the seed for a new
+sequence of pseudo-random integers to be returned by
+.BR rand ().
+These sequences are repeatable by calling
+.BR srand ()
+with the same seed value.
+.PP
+If no seed value is provided, the
+.BR rand ()
+function is automatically seeded with a value of 1.
+.PP
+The function
+.BR rand ()
+is not reentrant, since it
+uses hidden state that is modified on each call.
+This might just be the seed value to be used by the next call,
+or it might be something more elaborate.
+In order to get reproducible behavior in a threaded
+application, this state must be made explicit;
+this can be done using the reentrant function
+.BR rand_r ().
+.PP
+Like
+.BR rand (),
+.BR rand_r ()
+returns a pseudo-random integer in the range [0,\ \fBRAND_MAX\fR].
+The
+.I seedp
+argument is a pointer to an
+.I unsigned int
+that is used to store state between calls.
+If
+.BR rand_r ()
+is called with the same initial value for the integer pointed to by
+.IR seedp ,
+and that value is not modified between calls,
+then the same pseudo-random sequence will result.
+.PP
+The value pointed to by the
+.I seedp
+argument of
+.BR rand_r ()
+provides only a very small amount of state,
+so this function will be a weak pseudo-random generator.
+Try
+.BR drand48_r (3)
+instead.
+.SH RETURN VALUE
+The
+.BR rand ()
+and
+.BR rand_r ()
+functions return a value between 0 and
+.B RAND_MAX
+(inclusive).
+The
+.BR srand ()
+function returns no value.
+.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 rand (),
+.BR rand_r (),
+.BR srand ()
+T}	Thread safety	MT-Safe
+.TE
+.sp 1
+.SH VERSIONS
+The versions of
+.BR rand ()
+and
+.BR srand ()
+in the Linux C Library use the same random number generator as
+.BR random (3)
+and
+.BR srandom (3),
+so the lower-order bits should be as random as the higher-order bits.
+However, on older
+.BR rand ()
+implementations, and on current implementations on different systems,
+the lower-order bits are much less random than the higher-order bits.
+Do not use this function in applications intended to be portable
+when good randomness is needed.
+(Use
+.BR random (3)
+instead.)
+.SH STANDARDS
+.TP
+.BR rand ()
+.TQ
+.BR srand ()
+C11, POSIX.1-2008.
+.TP
+.BR rand_r ()
+POSIX.1-2008.
+.SH HISTORY
+.TP
+.BR rand ()
+.TQ
+.BR srand ()
+SVr4, 4.3BSD, C89, POSIX.1-2001.
+.TP
+.BR rand_r ()
+POSIX.1-2001.
+Obsolete in POSIX.1-2008.
+.SH EXAMPLES
+POSIX.1-2001 gives the following example of an implementation of
+.BR rand ()
+and
+.BR srand (),
+possibly useful when one needs the same sequence on two different machines.
+.PP
+.in +4n
+.EX
+static unsigned long next = 1;
+\&
+/* RAND_MAX assumed to be 32767 */
+int myrand(void) {
+    next = next * 1103515245 + 12345;
+    return((unsigned)(next/65536) % 32768);
+}
+\&
+void mysrand(unsigned int seed) {
+    next = seed;
+}
+.EE
+.in
+.PP
+The following program can be used to display the
+pseudo-random sequence produced by
+.BR rand ()
+when given a particular seed.
+When the seed is
+.IR \-1 ,
+the program uses a random seed.
+.PP
+.in +4n
+.\" SRC BEGIN (rand.c)
+.EX
+#include <stdio.h>
+#include <stdlib.h>
+\&
+int
+main(int argc, char *argv[])
+{
+    int           r;
+    unsigned int  seed, nloops;
+\&
+    if (argc != 3) {
+        fprintf(stderr, "Usage: %s <seed> <nloops>\en", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+\&
+    seed = atoi(argv[1]);
+    nloops = atoi(argv[2]);
+\&
+    if (seed == \-1) {
+        seed = arc4random();
+        printf("seed: %u\en", seed);
+    }
+\&
+    srand(seed);
+    for (unsigned int j = 0; j < nloops; j++) {
+        r =  rand();
+        printf("%d\en", r);
+    }
+\&
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.in
+.SH SEE ALSO
+.BR drand48 (3),
+.BR random (3)