LDP: Update original to LDP v3.68

[linuxjm/LDP_man-pages.git] / original / man3 / random.3

diff --git a/original/man3/random.3 b/original/man3/random.3
index 7568dc1..705d0ee 100644 (file)
--- a/original/man3/random.3
+++ b/original/man3/random.3
@@ -1,5 +1,6 @@
 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
 .\"
+.\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
 .\" preserved on all copies.
@@ -19,6 +20,7 @@
 .\"
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
 .\"
 .\" References consulted:
 .\"     Linux libc source code
@@ -28,7 +30,7 @@
 .\" 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  2009-02-03 "GNU" "Linux Programmer's Manual"
+.TH RANDOM 3  2014-03-25 "GNU" "Linux Programmer's Manual"
 .SH NAME
 random, srandom, initstate, setstate \- random number generator
 .SH SYNOPSIS
@@ -54,8 +56,11 @@ Feature Test Macro Requirements for glibc (see
 .BR srandom (),
 .BR initstate (),
 .BR setstate ():
-_SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500
-.ad b
+.RS 4
+_SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
+_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
+.RE
+.ad
 .SH DESCRIPTION
 The
 .BR random ()
@@ -89,7 +94,7 @@ 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,
+random number generator it should use\(emthe larger the state array,
 the better the random numbers will be.
 \fIseed\fP is the seed for the
 initialization, which specifies a starting point for the random number
@@ -110,7 +115,7 @@ using
 .BR initstate ()
 or be the result of a previous call of
 .BR setstate ().
-.SH "RETURN VALUE"
+.SH RETURN VALUE
 The
 .BR random ()
 function returns a value between 0 and
@@ -118,18 +123,42 @@ function returns a value between 0 and
 The
 .BR srandom ()
 function returns no value.
+
 The
 .BR initstate ()
-and
+function returns a pointer to the previous state array.
+On error,
+.I errno
+is set to indicate the cause.
+
+On success,
 .BR setstate ()
-functions return 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 "CONFORMING TO"
+.SH ATTRIBUTES
+.SS Multithreading (see pthreads(7))
+The
+.BR random (),
+.BR srandom (),
+.BR initstate (),
+and
+.BR setstate ()
+functions are thread-safe.
+.SH CONFORMING TO
 4.3BSD, POSIX.1-2001.
 .SH NOTES
 Current "optimal" values for the size of the state array \fIn\fP are
@@ -157,8 +186,25 @@ 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 "SEE ALSO"
+.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 drand48 (3),
 .BR rand (3),
 .BR random_r (3),
 .BR srand (3)
+.SH COLOPHON
+This page is part of release 3.68 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.