err.3: EXAMPLES: use EXIT_FAILURE rather than 1 as exit status

[thirdparty/man-pages.git] / man3 / random.3

diff --git a/man3/random.3 b/man3/random.3
index 9565c281a4fba6bd9bedf0462ce7db85b9c25857..76b076f4257107a05976161ca46cbb2cbd37b7fc 100644 (file)
--- a/man3/random.3
+++ b/man3/random.3
@@ -30,35 +30,37 @@
 .\" 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  2010-09-20 "GNU" "Linux Programmer's Manual"
+.TH RANDOM 3  2019-03-06 "GNU" "Linux Programmer's Manual"
 .SH NAME
 random, srandom, initstate, setstate \- random number generator
 .SH SYNOPSIS
 .nf
 .B #include <stdlib.h>
-.sp
+.PP
 .B long int random(void);
-
+.PP
 .BI "void srandom(unsigned int " seed );
-
+.PP
 .BI "char *initstate(unsigned int " seed ", char *" state ", size_t " n );
-.br
+.PP
 .BI "char *setstate(char *" state );
 .fi
-.sp
+.PP
 .in -4n
 Feature Test Macro Requirements for glibc (see
 .BR feature_test_macros (7)):
 .in
-.sp
+.PP
 .ad l
 .BR random (),
 .BR srandom (),
 .BR initstate (),
 .BR setstate ():
 .RS 4
-_SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
-_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
+_XOPEN_SOURCE\ >=\ 500
+.\"    || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
+    || /* Glibc since 2.19: */ _DEFAULT_SOURCE
+    || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
 .RE
 .ad
 .SH DESCRIPTION
@@ -96,6 +98,10 @@ The size of the state array
 to decide how sophisticated a
 random number generator it should use\(emthe 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.
@@ -123,46 +129,81 @@ function returns a value between 0 and
 The
 .BR srandom ()
 function returns no value.
+.PP
 The
 .BR initstate ()
 function returns a pointer to the previous state array.
-The
+On error,
+.I errno
+is set to indicate the cause.
+.PP
+On success,
 .BR setstate ()
-function returns a pointer to the previous state array, or NULL on error.
+returns a pointer to the previous state array.
+On error, it returns NULL, with
+.I errno
+set to indicate the cause of 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;
+lbw23 lb lb
+l l l.
+Interface      Attribute       Value
+T{
+.BR random (),
+.BR srandom (),
+.br
+.BR initstate (),
+.BR setstate ()
+T}     Thread safety   MT-Safe
+.TE
 .SH CONFORMING TO
-4.3BSD, POSIX.1-2001.
+POSIX.1-2001, POSIX.1-2008, 4.3BSD.
 .SH NOTES
-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 will cause an
-error.
-.PP
-This function should not be used in cases where multiple threads use
+The
 .BR random ()
-and the behavior should be reproducible.
+function should not be used in multithreaded programs
+where reproducible behavior is required.
 Use
 .BR random_r (3)
 for that purpose.
 .PP
 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.)
+(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).
 .PP
 For a more theoretical discussion which also covers many practical issues
-in depth, see Chapter 3 (Random Numbers) in Donald E. Knuth's
+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 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),