diff options
| author | Alejandro Colomar <alx@kernel.org> | 2024-04-26 15:06:49 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2024-05-02 01:24:19 +0200 |
| commit | dcde2f70372b49ec43efc5db864c9ff585d0a2dd (patch) | |
| tree | 78b9b7425130e4a5858e4c01a524d802423879ed /man/man3/random.3 | |
| parent | 12aca537ce78a41bbcdaf485209691e10f8002d7 (diff) | |
| download | man-pages-dcde2f70372b49ec43efc5db864c9ff585d0a2dd.tar.gz | |
man/, share/mk/: Move man*/ to man/
This is a scripted change:
$ mkdir man/;
$ mv man* man/;
$ ln -st . man/man*;
$ find share/mk/ -type f \
| xargs grep -l '^MANDIR *:=' \
| xargs sed -i '/^MANDIR *:=/s,$,/man,';
$ find share/mk/dist/ -type f \
| xargs grep -l man \
| xargs sed -i 's,man%,man/%,g';
Link: <https://lore.kernel.org/linux-man/YxcV4h+Xn7cd6+q2@pevik/T/>
Cc: Petr Vorel <pvorel@suse.cz>
Cc: Jakub Wilk <jwilk@jwilk.net>
Cc: Stefan Puiu <stefan.puiu@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
Diffstat (limited to 'man/man3/random.3')
| -rw-r--r-- | man/man3/random.3 | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/man/man3/random.3 b/man/man3/random.3 new file mode 100644 index 0000000000..c6dc573ddd --- /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 (date) "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) |