[1/4] Reorganize manual sections on cryptography and random numbers.

Message ID 20180506175153.22629-2-zackw@panix.com
State New
Headers show
Series
  • Revise crypto documentation, deprecate DES, add --disable-crypt
Related show

Commit Message

Zack Weinberg May 6, 2018, 5:51 p.m.
In preparation for improvements to the discussion of cryptography,
password handling, and random number generation, reorganize the
sections of the manual that deal with these topics.  This patch
neither deletes any old text nor introduces any new text; it only
moves text around.  The description of 'getpass' moves to
terminal.texi, since all it does is read a password from the
controlling terminal with echo disabled.  The pseudo-random number
generator sections from math.texi and the "Unpredictable Bytes"
section of crypt.texi are moved to a new file random.texi.  Also, it
is no longer true that crypt.texi's top @node needs to have no pointers.

	* manual/crypt.texi: Move most of the introductory text to the
        'crypt' section.  Move the example programs below the
        @deftypefun for 'crypt_r'.  Move the DESERR_* table and
        DES_FAILED deftypefun below cbc_crypt.  Move the entire
        'getpass' section...
	* manual/terminal.texi: ...here.

	* manual/random.texi: New file consolidating all discussion of
	random number generation.
	* manual/crypt.texi: 'Unpredictable Bytes' section moved to random.texi.
	* manual/math.texi: 'Pseudo-Random Numbers' section moved to
	random.texi.
	* manual/Makefile (chapters): Add 'random' after 'arith'.
	* manual/arith.texi, manual/time.texi: Update chapter-level node
	pointers.
---
 manual/Makefile      |   2 +-
 manual/arith.texi    |   2 +-
 manual/crypt.texi    | 301 +++++--------------
 manual/math.texi     | 586 +-----------------------------------
 manual/random.texi   | 702 +++++++++++++++++++++++++++++++++++++++++++
 manual/terminal.texi |  45 +++
 manual/time.texi     |   2 +-
 7 files changed, 823 insertions(+), 817 deletions(-)
 create mode 100644 manual/random.texi

Comments

Florian Weimer May 8, 2018, 1:29 p.m. | #1
On 05/06/2018 07:51 PM, Zack Weinberg wrote:
> 	* manual/crypt.texi: Move most of the introductory text to the
>          'crypt' section.  Move the example programs below the
>          @deftypefun for 'crypt_r'.  Move the DESERR_* table and
>          DES_FAILED deftypefun below cbc_crypt.  Move the entire
>          'getpass' section...
> 	* manual/terminal.texi: ...here.
> 
> 	* manual/random.texi: New file consolidating all discussion of
> 	random number generation.
> 	* manual/crypt.texi: 'Unpredictable Bytes' section moved to random.texi.
> 	* manual/math.texi: 'Pseudo-Random Numbers' section moved to
> 	random.texi.
> 	* manual/Makefile (chapters): Add 'random' after 'arith'.

I think this is okay.  I have not checked for no inadvertent changes in 
detail, though.

> 	* manual/arith.texi, manual/time.texi: Update chapter-level node
> 	pointers.

Do we still need to maintain node pointers manually?

Thanks,
Florian
Zack Weinberg May 8, 2018, 1:37 p.m. | #2
On Tue, May 8, 2018 at 9:29 AM, Florian Weimer <fweimer@redhat.com> wrote:
>>         * manual/arith.texi, manual/time.texi: Update chapter-level node
>>         pointers.
>
> Do we still need to maintain node pointers manually?

Yes, unfortunately, libc-texinfo.sh needs them (that's the script that
generates the "top menu").

zw
Florian Weimer May 8, 2018, 1:38 p.m. | #3
On 05/08/2018 03:37 PM, Zack Weinberg wrote:
> On Tue, May 8, 2018 at 9:29 AM, Florian Weimer <fweimer@redhat.com> wrote:
>>>          * manual/arith.texi, manual/time.texi: Update chapter-level node
>>>          pointers.
>>
>> Do we still need to maintain node pointers manually?
> 
> Yes, unfortunately, libc-texinfo.sh needs them (that's the script that
> generates the "top menu").

Oh, how unfortunate.  Well, I guess then this patch is okay as-is.

Thanks,
Florian
Rical Jasan May 9, 2018, 11:36 a.m. | #4
On 05/06/2018 10:51 AM, Zack Weinberg wrote:
> In preparation for improvements to the discussion of cryptography,
> password handling, and random number generation, reorganize the
> sections of the manual that deal with these topics.  This patch
> neither deletes any old text nor introduces any new text; it only
> moves text around.  The description of 'getpass' moves to
> terminal.texi, since all it does is read a password from the
> controlling terminal with echo disabled.  The pseudo-random number
> generator sections from math.texi and the "Unpredictable Bytes"
> section of crypt.texi are moved to a new file random.texi.  Also, it
> is no longer true that crypt.texi's top @node needs to have no pointers.
> 
> 	* manual/crypt.texi: Move most of the introductory text to the
>         'crypt' section.  Move the example programs below the
>         @deftypefun for 'crypt_r'.  Move the DESERR_* table and
>         DES_FAILED deftypefun below cbc_crypt.  Move the entire
>         'getpass' section...
> 	* manual/terminal.texi: ...here.
> 
> 	* manual/random.texi: New file consolidating all discussion of
> 	random number generation.
> 	* manual/crypt.texi: 'Unpredictable Bytes' section moved to random.texi.
> 	* manual/math.texi: 'Pseudo-Random Numbers' section moved to
> 	random.texi.
> 	* manual/Makefile (chapters): Add 'random' after 'arith'.
> 	* manual/arith.texi, manual/time.texi: Update chapter-level node
> 	pointers.

This is a great high-level overview of a largely mechanical change.

Other than minor, necessary changes to keep the manual somewhat
cohesive, this appears to be a copy/paste to me (yes, I took the time).

Thank you,
Rical

Patch

diff --git a/manual/Makefile b/manual/Makefile
index c2756640a7..99689c3182 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -36,7 +36,7 @@  endif
 chapters = $(addsuffix .texi, \
 		       intro errno memory ctype string charset locale	\
 		       message search pattern io stdio llio filesys	\
-		       pipe socket terminal syslog math arith time	\
+		       pipe socket terminal syslog math arith random time \
 		       resource setjmp signal startup process ipc job	\
 		       nss users sysinfo conf crypt debug threads	\
 		       probes tunables)
diff --git a/manual/arith.texi b/manual/arith.texi
index 116788ba9a..fe4bf9bd0d 100644
--- a/manual/arith.texi
+++ b/manual/arith.texi
@@ -1,4 +1,4 @@ 
-@node Arithmetic, Date and Time, Mathematics, Top
+@node Arithmetic, Random Number Generation, Mathematics, Top
 @c %MENU% Low level arithmetic functions
 @chapter Arithmetic Functions
 
diff --git a/manual/crypt.texi b/manual/crypt.texi
index 99d2d8e092..c24306c07c 100644
--- a/manual/crypt.texi
+++ b/manual/crypt.texi
@@ -1,34 +1,6 @@ 
-@c This node must have no pointers.
-@node Cryptographic Functions
-@c @node Cryptographic Functions, Debugging Support, System Configuration, Top
-@chapter DES Encryption and Password Handling
-@c %MENU% DES encryption and password handling
-
-On many systems, it is unnecessary to have any kind of user
-authentication; for instance, a workstation which is not connected to a
-network probably does not need any user authentication, because to use
-the machine an intruder must have physical access.
-
-Sometimes, however, it is necessary to be sure that a user is authorized
-to use some service a machine provides---for instance, to log in as a
-particular user id (@pxref{Users and Groups}).  One traditional way of
-doing this is for each user to choose a secret @dfn{password}; then, the
-system can ask someone claiming to be a user what the user's password
-is, and if the person gives the correct password then the system can
-grant the appropriate privileges.
-
-If all the passwords are just stored in a file somewhere, then this file
-has to be very carefully protected.  To avoid this, passwords are run
-through a @dfn{one-way function}, a function which makes it difficult to
-work out what its input was by looking at its output, before storing in
-the file.
-
-@Theglibc{} provides a one-way function that is compatible with
-the behavior of the @code{crypt} function introduced in FreeBSD 2.0.
-It supports two one-way algorithms: one based on the MD5
-message-digest algorithm that is compatible with modern BSD systems,
-and the other based on the Data Encryption Standard (DES) that is
-compatible with Unix systems.
+@node Cryptographic Functions, Debugging Support, System Configuration, Top
+@chapter Cryptographic Functions
+@c %MENU% Password storage and obsolete encryption functions
 
 @vindex AUTH_DES
 @cindex FIPS 140-2
@@ -42,10 +14,8 @@  encrypted authentication use normal DES.
 
 @menu
 * Legal Problems::              This software can get you locked up, or worse.
-* getpass::                     Prompting the user for a password.
 * crypt::                       A one-way function for passwords.
 * DES Encryption::              Routines for DES encryption.
-* Unpredictable Bytes::         Randomness for cryptography purposes.
 @end menu
 
 @node Legal Problems
@@ -90,53 +60,34 @@  The rules in this area are continuously changing.  If you know of any
 information in this manual that is out-of-date, please report it to
 the bug database.  @xref{Reporting Bugs}.
 
-@node getpass
-@section Reading Passwords
-
-When reading in a password, it is desirable to avoid displaying it on
-the screen, to help keep it secret.  The following function handles this
-in a convenient way.
-
-@deftypefun {char *} getpass (const char *@var{prompt})
-@standards{BSD, unistd.h}
-@safety{@prelim{}@mtunsafe{@mtasuterm{}}@asunsafe{@ascuheap{} @asulock{} @asucorrupt{}}@acunsafe{@acuterm{} @aculock{} @acucorrupt{}}}
-@c This function will attempt to create a stream for terminal I/O, but
-@c will fallback to stdio/stderr.  It attempts to change the terminal
-@c mode in a thread-unsafe way, write out the prompt, read the password,
-@c then restore the terminal mode.  It has a cleanup to close the stream
-@c in case of (synchronous) cancellation, but not to restore the
-@c terminal mode.
-
-@code{getpass} outputs @var{prompt}, then reads a string in from the
-terminal without echoing it.  It tries to connect to the real terminal,
-@file{/dev/tty}, if possible, to encourage users not to put plaintext
-passwords in files; otherwise, it uses @code{stdin} and @code{stderr}.
-@code{getpass} also disables the INTR, QUIT, and SUSP characters on the
-terminal using the @code{ISIG} terminal attribute (@pxref{Local Modes}).
-The terminal is flushed before and after @code{getpass}, so that
-characters of a mistyped password are not accidentally visible.
-
-In other C libraries, @code{getpass} may only return the first
-@code{PASS_MAX} bytes of a password.  @Theglibc{} has no limit, so
-@code{PASS_MAX} is undefined.
-
-The prototype for this function is in @file{unistd.h}.  @code{PASS_MAX}
-would be defined in @file{limits.h}.
-@end deftypefun
+@node crypt
+@section Encrypting Passwords
 
-This precise set of operations may not suit all possible situations.  In
-this case, it is recommended that users write their own @code{getpass}
-substitute.  For instance, a very simple substitute is as follows:
+On many systems, it is unnecessary to have any kind of user
+authentication; for instance, a workstation which is not connected to a
+network probably does not need any user authentication, because to use
+the machine an intruder must have physical access.
 
-@smallexample
-@include mygetpass.c.texi
-@end smallexample
+Sometimes, however, it is necessary to be sure that a user is authorized
+to use some service a machine provides---for instance, to log in as a
+particular user id (@pxref{Users and Groups}).  One traditional way of
+doing this is for each user to choose a secret @dfn{password}; then, the
+system can ask someone claiming to be a user what the user's password
+is, and if the person gives the correct password then the system can
+grant the appropriate privileges.
 
-The substitute takes the same parameters as @code{getline}
-(@pxref{Line Input}); the user must print any prompt desired.
+If all the passwords are just stored in a file somewhere, then this file
+has to be very carefully protected.  To avoid this, passwords are run
+through a @dfn{one-way function}, a function which makes it difficult to
+work out what its input was by looking at its output, before storing in
+the file.
 
-@node crypt
-@section Encrypting Passwords
+@Theglibc{} provides a one-way function that is compatible with
+the behavior of the @code{crypt} function introduced in FreeBSD 2.0.
+It supports two one-way algorithms: one based on the MD5
+message-digest algorithm that is compatible with modern BSD systems,
+and the other based on the Data Encryption Standard (DES) that is
+compatible with Unix systems.
 
 @deftypefun {char *} crypt (const char *@var{key}, const char *@var{salt})
 @standards{BSD, crypt.h}
@@ -188,6 +139,23 @@  password against the result of a previous call to @code{crypt}, pass
 the result of the previous call as the @var{salt}.
 @end deftypefun
 
+@deftypefun {char *} crypt_r (const char *@var{key}, const char *@var{salt}, {struct crypt_data *} @var{data})
+@standards{GNU, crypt.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{} @ascuheap{} @ascudlopen{}}@acunsafe{@aculock{} @acsmem{}}}
+@c Compared with crypt, this function fixes the @mtasurace:crypt
+@c problem, but nothing else.
+
+The @code{crypt_r} function does the same thing as @code{crypt}, but
+takes an extra parameter which includes space for its result (among
+other things), so it can be reentrant.  @code{data@w{->}initialized} must be
+cleared to zero before the first time @code{crypt_r} is called.
+
+The @code{crypt_r} function is a GNU extension.
+@end deftypefun
+
+The @code{crypt} and @code{crypt_r} functions are prototyped in the
+header @file{crypt.h}.
+
 The following short program is an example of how to use @code{crypt} the
 first time a password is entered.  Note that the @var{salt} generation
 is just barely acceptable; in particular, it is not unique between
@@ -206,23 +174,6 @@  for a password and prints ``Access granted.'' if the user types
 @include testpass.c.texi
 @end smallexample
 
-@deftypefun {char *} crypt_r (const char *@var{key}, const char *@var{salt}, {struct crypt_data *} @var{data})
-@standards{GNU, crypt.h}
-@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{} @ascuheap{} @ascudlopen{}}@acunsafe{@aculock{} @acsmem{}}}
-@c Compared with crypt, this function fixes the @mtasurace:crypt
-@c problem, but nothing else.
-
-The @code{crypt_r} function does the same thing as @code{crypt}, but
-takes an extra parameter which includes space for its result (among
-other things), so it can be reentrant.  @code{data@w{->}initialized} must be
-cleared to zero before the first time @code{crypt_r} is called.
-
-The @code{crypt_r} function is a GNU extension.
-@end deftypefun
-
-The @code{crypt} and @code{crypt_r} functions are prototyped in the
-header @file{crypt.h}.
-
 @node DES Encryption
 @section DES Encryption
 
@@ -345,33 +296,6 @@  This constant, used in the @var{mode} parameter, specifies that no
 hardware device is to be used.
 @end vtable
 
-The result of the function will be one of these values:
-
-@vtable @code
-@item DESERR_NONE
-@standards{SUNRPC, rpc/des_crypt.h}
-The encryption succeeded.
-
-@item DESERR_NOHWDEVICE
-@standards{SUNRPC, rpc/des_crypt.h}
-The encryption succeeded, but there was no hardware device available.
-
-@item DESERR_HWERROR
-@standards{SUNRPC, rpc/des_crypt.h}
-The encryption failed because of a hardware problem.
-
-@item DESERR_BADPARAM
-@standards{SUNRPC, rpc/des_crypt.h}
-The encryption failed because of a bad parameter, for instance @var{len}
-is not a multiple of 8 or @var{len} is larger than @code{DES_MAXDATA}.
-@end vtable
-@end deftypefun
-
-@deftypefun int DES_FAILED (int @var{err})
-@standards{SUNRPC, rpc/des_crypt.h}
-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-This macro returns 1 if @var{err} is a `success' result code from
-@code{ecb_crypt} or @code{cbc_crypt}, and 0 otherwise.
 @end deftypefun
 
 @deftypefun int cbc_crypt (char *@var{key}, char *@var{blocks}, unsigned int @var{len}, unsigned int @var{mode}, char *@var{ivec})
@@ -400,6 +324,34 @@  bytes.
 Otherwise, all the parameters are similar to those for @code{ecb_crypt}.
 @end deftypefun
 
+The result of the function will be one of these values:
+
+@vtable @code
+@item DESERR_NONE
+@standards{SUNRPC, rpc/des_crypt.h}
+The encryption succeeded.
+
+@item DESERR_NOHWDEVICE
+@standards{SUNRPC, rpc/des_crypt.h}
+The encryption succeeded, but there was no hardware device available.
+
+@item DESERR_HWERROR
+@standards{SUNRPC, rpc/des_crypt.h}
+The encryption failed because of a hardware problem.
+
+@item DESERR_BADPARAM
+@standards{SUNRPC, rpc/des_crypt.h}
+The encryption failed because of a bad parameter, for instance @var{len}
+is not a multiple of 8 or @var{len} is larger than @code{DES_MAXDATA}.
+@end vtable
+
+@deftypefun int DES_FAILED (int @var{err})
+@standards{SUNRPC, rpc/des_crypt.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns 1 if @var{err} is a `success' result code from
+@code{ecb_crypt} or @code{cbc_crypt}, and 0 otherwise.
+@end deftypefun
+
 @deftypefun void des_setparity (char *@var{key})
 @standards{SUNRPC, rpc/des_crypt.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@@ -412,112 +364,3 @@  each byte.
 The @code{ecb_crypt}, @code{cbc_crypt}, and @code{des_setparity}
 functions and their accompanying macros are all defined in the header
 @file{rpc/des_crypt.h}.
-
-@node Unpredictable Bytes
-@section Generating Unpredictable Bytes
-
-Some cryptographic applications (such as session key generation) need
-unpredictable bytes.
-
-In general, application code should use a deterministic random bit
-generator, which could call the @code{getentropy} function described
-below internally to obtain randomness to seed the generator.  The
-@code{getrandom} function is intended for low-level applications which
-need additional control over the blocking behavior.
-
-@deftypefun int getentropy (void *@var{buffer}, size_t @var{length})
-@standards{GNU, sys/random.h}
-@safety{@mtsafe{}@assafe{}@acsafe{}}
-
-This function writes @var{length} bytes of random data to the array
-starting at @var{buffer}, which must be at most 256 bytes long.  The
-function returns zero on success.  On failure, it returns @code{-1} and
-@code{errno} is updated accordingly.
-
-The @code{getentropy} function is declared in the header file
-@file{sys/random.h}.  It is derived from OpenBSD.
-
-The @code{getentropy} function is not a cancellation point.  A call to
-@code{getentropy} can block if the system has just booted and the kernel
-entropy pool has not yet been initialized.  In this case, the function
-will keep blocking even if a signal arrives, and return only after the
-entropy pool has been initialized.
-
-The @code{getentropy} function can fail with several errors, some of
-which are listed below.
-
-@table @code
-@item ENOSYS
-The kernel does not implement the required system call.
-
-@item EFAULT
-The combination of @var{buffer} and @var{length} arguments specifies
-an invalid memory range.
-
-@item EIO
-More than 256 bytes of randomness have been requested, or the buffer
-could not be overwritten with random data for an unspecified reason.
-
-@end table
-
-@end deftypefun
-
-@deftypefun ssize_t getrandom (void *@var{buffer}, size_t @var{length}, unsigned int @var{flags})
-@standards{GNU, sys/random.h}
-@safety{@mtsafe{}@assafe{}@acsafe{}}
-
-This function writes @var{length} bytes of random data to the array
-starting at @var{buffer}.  On success, this function returns the number
-of bytes which have been written to the buffer (which can be less than
-@var{length}).  On error, @code{-1} is returned, and @code{errno} is
-updated accordingly.
-
-The @code{getrandom} function is declared in the header file
-@file{sys/random.h}.  It is a GNU extension.
-
-The following flags are defined for the @var{flags} argument:
-
-@table @code
-@item GRND_RANDOM
-Use the @file{/dev/random} (blocking) pool instead of the
-@file{/dev/urandom} (non-blocking) pool to obtain randomness.  If the
-@code{GRND_RANDOM} flag is specified, the @code{getrandom} function can
-block even after the randomness source has been initialized.
-
-@item GRND_NONBLOCK
-Instead of blocking, return to the caller immediately if no data is
-available.
-@end table
-
-The @code{getrandom} function is a cancellation point.
-
-Obtaining randomness from the @file{/dev/urandom} pool (i.e., a call
-without the @code{GRND_RANDOM} flag) can block if the system has just
-booted and the pool has not yet been initialized.
-
-The @code{getrandom} function can fail with several errors, some of
-which are listed below.  In addition, the function may not fill the
-buffer completely and return a value less than @var{length}.
-
-@table @code
-@item ENOSYS
-The kernel does not implement the @code{getrandom} system call.
-
-@item EAGAIN
-No random data was available and @code{GRND_NONBLOCK} was specified in
-@var{flags}.
-
-@item EFAULT
-The combination of @var{buffer} and @var{length} arguments specifies
-an invalid memory range.
-
-@item EINTR
-The system call was interrupted.  During the system boot process, before
-the kernel randomness pool is initialized, this can happen even if
-@var{flags} is zero.
-
-@item EINVAL
-The @var{flags} argument contains an invalid combination of flags.
-@end table
-
-@end deftypefun
diff --git a/manual/math.texi b/manual/math.texi
index d19a14b47d..776db62d1e 100644
--- a/manual/math.texi
+++ b/manual/math.texi
@@ -28,7 +28,7 @@ 
 @end ifclear
 
 @node Mathematics, Arithmetic, Syslog, Top
-@c %MENU% Math functions, useful constants, random numbers
+@c %MENU% Math functions, useful constants
 @chapter Mathematics
 
 This chapter contains information about functions for performing
@@ -81,8 +81,6 @@  aarch64, alpha, mips64, riscv, s390 and sparc.
 * Hyperbolic Functions::        sinh, cosh, tanh, etc.
 * Special Functions::           Bessel, gamma, erf.
 * Errors in Math Functions::    Known Maximum Errors in Math Functions.
-* Pseudo-Random Numbers::       Functions for generating pseudo-random
-				 numbers.
 * FP Function Optimizations::   Fast code or small code.
 @end menu
 
@@ -1401,588 +1399,6 @@  Functions not listed do not have known errors.
 @c This multitable does not fit on a single page
 @include libm-err.texi
 
-@node Pseudo-Random Numbers
-@section Pseudo-Random Numbers
-@cindex random numbers
-@cindex pseudo-random numbers
-@cindex seed (for random numbers)
-
-This section describes the GNU facilities for generating a series of
-pseudo-random numbers.  The numbers generated are not truly random;
-typically, they form a sequence that repeats periodically, with a period
-so large that you can ignore it for ordinary purposes.  The random
-number generator works by remembering a @dfn{seed} value which it uses
-to compute the next random number and also to compute a new seed.
-
-Although the generated numbers look unpredictable within one run of a
-program, the sequence of numbers is @emph{exactly the same} from one run
-to the next.  This is because the initial seed is always the same.  This
-is convenient when you are debugging a program, but it is unhelpful if
-you want the program to behave unpredictably.  If you want a different
-pseudo-random series each time your program runs, you must specify a
-different seed each time.  For ordinary purposes, basing the seed on the
-current time works well.  For random numbers in cryptography,
-@pxref{Unpredictable Bytes}.
-
-You can obtain repeatable sequences of numbers on a particular machine type
-by specifying the same initial seed value for the random number
-generator.  There is no standard meaning for a particular seed value;
-the same seed, used in different C libraries or on different CPU types,
-will give you different random numbers.
-
-@Theglibc{} supports the standard @w{ISO C} random number functions
-plus two other sets derived from BSD and SVID.  The BSD and @w{ISO C}
-functions provide identical, somewhat limited functionality.  If only a
-small number of random bits are required, we recommend you use the
-@w{ISO C} interface, @code{rand} and @code{srand}.  The SVID functions
-provide a more flexible interface, which allows better random number
-generator algorithms, provides more random bits (up to 48) per call, and
-can provide random floating-point numbers.  These functions are required
-by the XPG standard and therefore will be present in all modern Unix
-systems.
-
-@menu
-* ISO Random::                  @code{rand} and friends.
-* BSD Random::                  @code{random} and friends.
-* SVID Random::                 @code{drand48} and friends.
-@end menu
-
-@node ISO Random
-@subsection ISO C Random Number Functions
-
-This section describes the random number functions that are part of
-the @w{ISO C} standard.
-
-To use these facilities, you should include the header file
-@file{stdlib.h} in your program.
-@pindex stdlib.h
-
-@deftypevr Macro int RAND_MAX
-@standards{ISO, stdlib.h}
-The value of this macro is an integer constant representing the largest
-value the @code{rand} function can return.  In @theglibc{}, it is
-@code{2147483647}, which is the largest signed integer representable in
-32 bits.  In other libraries, it may be as low as @code{32767}.
-@end deftypevr
-
-@deftypefun int rand (void)
-@standards{ISO, stdlib.h}
-@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
-@c Just calls random.
-The @code{rand} function returns the next pseudo-random number in the
-series.  The value ranges from @code{0} to @code{RAND_MAX}.
-@end deftypefun
-
-@deftypefun void srand (unsigned int @var{seed})
-@standards{ISO, stdlib.h}
-@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
-@c Alias to srandom.
-This function establishes @var{seed} as the seed for a new series of
-pseudo-random numbers.  If you call @code{rand} before a seed has been
-established with @code{srand}, it uses the value @code{1} as a default
-seed.
-
-To produce a different pseudo-random series each time your program is
-run, do @code{srand (time (0))}.
-@end deftypefun
-
-POSIX.1 extended the C standard functions to support reproducible random
-numbers in multi-threaded programs.  However, the extension is badly
-designed and unsuitable for serious work.
-
-@deftypefun int rand_r (unsigned int *@var{seed})
-@standards{POSIX.1, stdlib.h}
-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-This function returns a random number in the range 0 to @code{RAND_MAX}
-just as @code{rand} does.  However, all its state is stored in the
-@var{seed} argument.  This means the RNG's state can only have as many
-bits as the type @code{unsigned int} has.  This is far too few to
-provide a good RNG.
-
-If your program requires a reentrant RNG, we recommend you use the
-reentrant GNU extensions to the SVID random number generator.  The
-POSIX.1 interface should only be used when the GNU extensions are not
-available.
-@end deftypefun
-
-
-@node BSD Random
-@subsection BSD Random Number Functions
-
-This section describes a set of random number generation functions that
-are derived from BSD.  There is no advantage to using these functions
-with @theglibc{}; we support them for BSD compatibility only.
-
-The prototypes for these functions are in @file{stdlib.h}.
-@pindex stdlib.h
-
-@deftypefun {long int} random (void)
-@standards{BSD, stdlib.h}
-@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
-@c Takes a lock and calls random_r with an automatic variable and the
-@c global state, while holding a lock.
-This function returns the next pseudo-random number in the sequence.
-The value returned ranges from @code{0} to @code{2147483647}.
-
-@strong{NB:} Temporarily this function was defined to return a
-@code{int32_t} value to indicate that the return value always contains
-32 bits even if @code{long int} is wider.  The standard demands it
-differently.  Users must always be aware of the 32-bit limitation,
-though.
-@end deftypefun
-
-@deftypefun void srandom (unsigned int @var{seed})
-@standards{BSD, stdlib.h}
-@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
-@c Takes a lock and calls srandom_r with an automatic variable and a
-@c static buffer.  There's no MT-safety issue because the static buffer
-@c is internally protected by a lock, although other threads may modify
-@c the set state before it is used.
-The @code{srandom} function sets the state of the random number
-generator based on the integer @var{seed}.  If you supply a @var{seed} value
-of @code{1}, this will cause @code{random} to reproduce the default set
-of random numbers.
-
-To produce a different set of pseudo-random numbers each time your
-program runs, do @code{srandom (time (0))}.
-@end deftypefun
-
-@deftypefun {char *} initstate (unsigned int @var{seed}, char *@var{state}, size_t @var{size})
-@standards{BSD, stdlib.h}
-@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
-The @code{initstate} function is used to initialize the random number
-generator state.  The argument @var{state} is an array of @var{size}
-bytes, used to hold the state information.  It is initialized based on
-@var{seed}.  The size must be between 8 and 256 bytes, and should be a
-power of two.  The bigger the @var{state} array, the better.
-
-The return value is the previous value of the state information array.
-You can use this value later as an argument to @code{setstate} to
-restore that state.
-@end deftypefun
-
-@deftypefun {char *} setstate (char *@var{state})
-@standards{BSD, stdlib.h}
-@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
-The @code{setstate} function restores the random number state
-information @var{state}.  The argument must have been the result of
-a previous call to @var{initstate} or @var{setstate}.
-
-The return value is the previous value of the state information array.
-You can use this value later as an argument to @code{setstate} to
-restore that state.
-
-If the function fails the return value is @code{NULL}.
-@end deftypefun
-
-The four functions described so far in this section all work on a state
-which is shared by all threads.  The state is not directly accessible to
-the user and can only be modified by these functions.  This makes it
-hard to deal with situations where each thread should have its own
-pseudo-random number generator.
-
-@Theglibc{} contains four additional functions which contain the
-state as an explicit parameter and therefore make it possible to handle
-thread-local PRNGs.  Besides this there is no difference.  In fact, the
-four functions already discussed are implemented internally using the
-following interfaces.
-
-The @file{stdlib.h} header contains a definition of the following type:
-
-@deftp {Data Type} {struct random_data}
-@standards{GNU, stdlib.h}
-
-Objects of type @code{struct random_data} contain the information
-necessary to represent the state of the PRNG.  Although a complete
-definition of the type is present the type should be treated as opaque.
-@end deftp
-
-The functions modifying the state follow exactly the already described
-functions.
-
-@deftypefun int random_r (struct random_data *restrict @var{buf}, int32_t *restrict @var{result})
-@standards{GNU, stdlib.h}
-@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
-The @code{random_r} function behaves exactly like the @code{random}
-function except that it uses and modifies the state in the object
-pointed to by the first parameter instead of the global state.
-@end deftypefun
-
-@deftypefun int srandom_r (unsigned int @var{seed}, struct random_data *@var{buf})
-@standards{GNU, stdlib.h}
-@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
-The @code{srandom_r} function behaves exactly like the @code{srandom}
-function except that it uses and modifies the state in the object
-pointed to by the second parameter instead of the global state.
-@end deftypefun
-
-@deftypefun int initstate_r (unsigned int @var{seed}, char *restrict @var{statebuf}, size_t @var{statelen}, struct random_data *restrict @var{buf})
-@standards{GNU, stdlib.h}
-@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
-The @code{initstate_r} function behaves exactly like the @code{initstate}
-function except that it uses and modifies the state in the object
-pointed to by the fourth parameter instead of the global state.
-@end deftypefun
-
-@deftypefun int setstate_r (char *restrict @var{statebuf}, struct random_data *restrict @var{buf})
-@standards{GNU, stdlib.h}
-@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
-The @code{setstate_r} function behaves exactly like the @code{setstate}
-function except that it uses and modifies the state in the object
-pointed to by the first parameter instead of the global state.
-@end deftypefun
-
-@node SVID Random
-@subsection SVID Random Number Function
-
-The C library on SVID systems contains yet another kind of random number
-generator functions.  They use a state of 48 bits of data.  The user can
-choose among a collection of functions which return the random bits
-in different forms.
-
-Generally there are two kinds of function.  The first uses a state of
-the random number generator which is shared among several functions and
-by all threads of the process.  The second requires the user to handle
-the state.
-
-All functions have in common that they use the same congruential
-formula with the same constants.  The formula is
-
-@smallexample
-Y = (a * X + c) mod m
-@end smallexample
-
-@noindent
-where @var{X} is the state of the generator at the beginning and
-@var{Y} the state at the end.  @code{a} and @code{c} are constants
-determining the way the generator works.  By default they are
-
-@smallexample
-a = 0x5DEECE66D = 25214903917
-c = 0xb = 11
-@end smallexample
-
-@noindent
-but they can also be changed by the user.  @code{m} is of course 2^48
-since the state consists of a 48-bit array.
-
-The prototypes for these functions are in @file{stdlib.h}.
-@pindex stdlib.h
-
-
-@deftypefun double drand48 (void)
-@standards{SVID, stdlib.h}
-@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
-@c Uses of the static state buffer are not guarded by a lock (thus
-@c @mtasurace:drand48), so they may be found or left at a
-@c partially-updated state in case of calls from within signal handlers
-@c or cancellation.  None of this will break safety rules or invoke
-@c undefined behavior, but it may affect randomness.
-This function returns a @code{double} value in the range of @code{0.0}
-to @code{1.0} (exclusive).  The random bits are determined by the global
-state of the random number generator in the C library.
-
-Since the @code{double} type according to @w{IEEE 754} has a 52-bit
-mantissa this means 4 bits are not initialized by the random number
-generator.  These are (of course) chosen to be the least significant
-bits and they are initialized to @code{0}.
-@end deftypefun
-
-@deftypefun double erand48 (unsigned short int @var{xsubi}[3])
-@standards{SVID, stdlib.h}
-@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
-@c The static buffer is just initialized with default parameters, which
-@c are later read to advance the state held in xsubi.
-This function returns a @code{double} value in the range of @code{0.0}
-to @code{1.0} (exclusive), similarly to @code{drand48}.  The argument is
-an array describing the state of the random number generator.
-
-This function can be called subsequently since it updates the array to
-guarantee random numbers.  The array should have been initialized before
-initial use to obtain reproducible results.
-@end deftypefun
-
-@deftypefun {long int} lrand48 (void)
-@standards{SVID, stdlib.h}
-@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
-The @code{lrand48} function returns an integer value in the range of
-@code{0} to @code{2^31} (exclusive).  Even if the size of the @code{long
-int} type can take more than 32 bits, no higher numbers are returned.
-The random bits are determined by the global state of the random number
-generator in the C library.
-@end deftypefun
-
-@deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3])
-@standards{SVID, stdlib.h}
-@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
-This function is similar to the @code{lrand48} function in that it
-returns a number in the range of @code{0} to @code{2^31} (exclusive) but
-the state of the random number generator used to produce the random bits
-is determined by the array provided as the parameter to the function.
-
-The numbers in the array are updated afterwards so that subsequent calls
-to this function yield different results (as is expected of a random
-number generator).  The array should have been initialized before the
-first call to obtain reproducible results.
-@end deftypefun
-
-@deftypefun {long int} mrand48 (void)
-@standards{SVID, stdlib.h}
-@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
-The @code{mrand48} function is similar to @code{lrand48}.  The only
-difference is that the numbers returned are in the range @code{-2^31} to
-@code{2^31} (exclusive).
-@end deftypefun
-
-@deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3])
-@standards{SVID, stdlib.h}
-@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
-The @code{jrand48} function is similar to @code{nrand48}.  The only
-difference is that the numbers returned are in the range @code{-2^31} to
-@code{2^31} (exclusive).  For the @code{xsubi} parameter the same
-requirements are necessary.
-@end deftypefun
-
-The internal state of the random number generator can be initialized in
-several ways.  The methods differ in the completeness of the
-information provided.
-
-@deftypefun void srand48 (long int @var{seedval})
-@standards{SVID, stdlib.h}
-@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
-The @code{srand48} function sets the most significant 32 bits of the
-internal state of the random number generator to the least
-significant 32 bits of the @var{seedval} parameter.  The lower 16 bits
-are initialized to the value @code{0x330E}.  Even if the @code{long
-int} type contains more than 32 bits only the lower 32 bits are used.
-
-Owing to this limitation, initialization of the state of this
-function is not very useful.  But it makes it easy to use a construct
-like @code{srand48 (time (0))}.
-
-A side-effect of this function is that the values @code{a} and @code{c}
-from the internal state, which are used in the congruential formula,
-are reset to the default values given above.  This is of importance once
-the user has called the @code{lcong48} function (see below).
-@end deftypefun
-
-@deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
-@standards{SVID, stdlib.h}
-@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
-The @code{seed48} function initializes all 48 bits of the state of the
-internal random number generator from the contents of the parameter
-@var{seed16v}.  Here the lower 16 bits of the first element of
-@var{seed16v} initialize the least significant 16 bits of the internal
-state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order
-16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]}
-initialize the most significant 16 bits of the state.
-
-Unlike @code{srand48} this function lets the user initialize all 48 bits
-of the state.
-
-The value returned by @code{seed48} is a pointer to an array containing
-the values of the internal state before the change.  This might be
-useful to restart the random number generator at a certain state.
-Otherwise the value can simply be ignored.
-
-As for @code{srand48}, the values @code{a} and @code{c} from the
-congruential formula are reset to the default values.
-@end deftypefun
-
-There is one more function to initialize the random number generator
-which enables you to specify even more information by allowing you to
-change the parameters in the congruential formula.
-
-@deftypefun void lcong48 (unsigned short int @var{param}[7])
-@standards{SVID, stdlib.h}
-@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
-The @code{lcong48} function allows the user to change the complete state
-of the random number generator.  Unlike @code{srand48} and
-@code{seed48}, this function also changes the constants in the
-congruential formula.
-
-From the seven elements in the array @var{param} the least significant
-16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]}
-determine the initial state, the least significant 16 bits of
-@code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
-constant @code{a} and @code{@var{param}[6]} determines the 16-bit value
-@code{c}.
-@end deftypefun
-
-All the above functions have in common that they use the global
-parameters for the congruential formula.  In multi-threaded programs it
-might sometimes be useful to have different parameters in different
-threads.  For this reason all the above functions have a counterpart
-which works on a description of the random number generator in the
-user-supplied buffer instead of the global state.
-
-Please note that it is no problem if several threads use the global
-state if all threads use the functions which take a pointer to an array
-containing the state.  The random numbers are computed following the
-same loop but if the state in the array is different all threads will
-obtain an individual random number generator.
-
-The user-supplied buffer must be of type @code{struct drand48_data}.
-This type should be regarded as opaque and not manipulated directly.
-
-@deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
-@standards{GNU, stdlib.h}
-@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
-This function is equivalent to the @code{drand48} function with the
-difference that it does not modify the global random number generator
-parameters but instead the parameters in the buffer supplied through the
-pointer @var{buffer}.  The random number is returned in the variable
-pointed to by @var{result}.
-
-The return value of the function indicates whether the call succeeded.
-If the value is less than @code{0} an error occurred and @var{errno} is
-set to indicate the problem.
-
-This function is a GNU extension and should not be used in portable
-programs.
-@end deftypefun
-
-@deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result})
-@standards{GNU, stdlib.h}
-@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
-The @code{erand48_r} function works like @code{erand48}, but in addition
-it takes an argument @var{buffer} which describes the random number
-generator.  The state of the random number generator is taken from the
-@code{xsubi} array, the parameters for the congruential formula from the
-global random number generator data.  The random number is returned in
-the variable pointed to by @var{result}.
-
-The return value is non-negative if the call succeeded.
-
-This function is a GNU extension and should not be used in portable
-programs.
-@end deftypefun
-
-@deftypefun int lrand48_r (struct drand48_data *@var{buffer}, long int *@var{result})
-@standards{GNU, stdlib.h}
-@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
-This function is similar to @code{lrand48}, but in addition it takes a
-pointer to a buffer describing the state of the random number generator
-just like @code{drand48}.
-
-If the return value of the function is non-negative the variable pointed
-to by @var{result} contains the result.  Otherwise an error occurred.
-
-This function is a GNU extension and should not be used in portable
-programs.
-@end deftypefun
-
-@deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
-@standards{GNU, stdlib.h}
-@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
-The @code{nrand48_r} function works like @code{nrand48} in that it
-produces a random number in the range @code{0} to @code{2^31}.  But instead
-of using the global parameters for the congruential formula it uses the
-information from the buffer pointed to by @var{buffer}.  The state is
-described by the values in @var{xsubi}.
-
-If the return value is non-negative the variable pointed to by
-@var{result} contains the result.
-
-This function is a GNU extension and should not be used in portable
-programs.
-@end deftypefun
-
-@deftypefun int mrand48_r (struct drand48_data *@var{buffer}, long int *@var{result})
-@standards{GNU, stdlib.h}
-@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
-This function is similar to @code{mrand48} but like the other reentrant
-functions it uses the random number generator described by the value in
-the buffer pointed to by @var{buffer}.
-
-If the return value is non-negative the variable pointed to by
-@var{result} contains the result.
-
-This function is a GNU extension and should not be used in portable
-programs.
-@end deftypefun
-
-@deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
-@standards{GNU, stdlib.h}
-@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
-The @code{jrand48_r} function is similar to @code{jrand48}.  Like the
-other reentrant functions of this function family it uses the
-congruential formula parameters from the buffer pointed to by
-@var{buffer}.
-
-If the return value is non-negative the variable pointed to by
-@var{result} contains the result.
-
-This function is a GNU extension and should not be used in portable
-programs.
-@end deftypefun
-
-Before any of the above functions are used the buffer of type
-@code{struct drand48_data} should be initialized.  The easiest way to do
-this is to fill the whole buffer with null bytes, e.g. by
-
-@smallexample
-memset (buffer, '\0', sizeof (struct drand48_data));
-@end smallexample
-
-@noindent
-Using any of the reentrant functions of this family now will
-automatically initialize the random number generator to the default
-values for the state and the parameters of the congruential formula.
-
-The other possibility is to use any of the functions which explicitly
-initialize the buffer.  Though it might be obvious how to initialize the
-buffer from looking at the parameter to the function, it is highly
-recommended to use these functions since the result might not always be
-what you expect.
-
-@deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
-@standards{GNU, stdlib.h}
-@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
-The description of the random number generator represented by the
-information in @var{buffer} is initialized similarly to what the function
-@code{srand48} does.  The state is initialized from the parameter
-@var{seedval} and the parameters for the congruential formula are
-initialized to their default values.
-
-If the return value is non-negative the function call succeeded.
-
-This function is a GNU extension and should not be used in portable
-programs.
-@end deftypefun
-
-@deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer})
-@standards{GNU, stdlib.h}
-@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
-This function is similar to @code{srand48_r} but like @code{seed48} it
-initializes all 48 bits of the state from the parameter @var{seed16v}.
-
-If the return value is non-negative the function call succeeded.  It
-does not return a pointer to the previous state of the random number
-generator like the @code{seed48} function does.  If the user wants to
-preserve the state for a later re-run s/he can copy the whole buffer
-pointed to by @var{buffer}.
-
-This function is a GNU extension and should not be used in portable
-programs.
-@end deftypefun
-
-@deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer})
-@standards{GNU, stdlib.h}
-@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
-This function initializes all aspects of the random number generator
-described in @var{buffer} with the data in @var{param}.  Here it is
-especially true that the function does more than just copying the
-contents of @var{param} and @var{buffer}.  More work is required and
-therefore it is important to use this function rather than initializing
-the random number generator directly.
-
-If the return value is non-negative the function call succeeded.
-
-This function is a GNU extension and should not be used in portable
-programs.
-@end deftypefun
-
 @node FP Function Optimizations
 @section Is Fast Code or Small Code preferred?
 @cindex Optimization
diff --git a/manual/random.texi b/manual/random.texi
new file mode 100644
index 0000000000..c53ed7fc22
--- /dev/null
+++ b/manual/random.texi
@@ -0,0 +1,702 @@ 
+@node Random Number Generation, Date and Time, Arithmetic, Top
+@chapter Random Number Generation
+@c %MENU% Various ways to generate random values.
+
+@menu
+* Pseudo-Random Numbers::       Sequences of numbers with apparently
+                                 random distribution, but not difficult
+                                 to predict.
+* Unpredictable Bytes::         Asking the operating system for truly
+				 unpredictable bytes.
+@end menu
+
+@node Pseudo-Random Numbers
+@section Pseudo-Random Numbers
+@cindex random numbers
+@cindex pseudo-random numbers
+@cindex seed (for random numbers)
+
+This section describes the GNU facilities for generating a series of
+pseudo-random numbers.  The numbers generated are not truly random;
+typically, they form a sequence that repeats periodically, with a period
+so large that you can ignore it for ordinary purposes.  The random
+number generator works by remembering a @dfn{seed} value which it uses
+to compute the next random number and also to compute a new seed.
+
+Although the generated numbers look unpredictable within one run of a
+program, the sequence of numbers is @emph{exactly the same} from one run
+to the next.  This is because the initial seed is always the same.  This
+is convenient when you are debugging a program, but it is unhelpful if
+you want the program to behave unpredictably.  If you want a different
+pseudo-random series each time your program runs, you must specify a
+different seed each time.  For ordinary purposes, basing the seed on the
+current time works well.  For random numbers in cryptography,
+@pxref{Unpredictable Bytes}.
+
+You can obtain repeatable sequences of numbers on a particular machine type
+by specifying the same initial seed value for the random number
+generator.  There is no standard meaning for a particular seed value;
+the same seed, used in different C libraries or on different CPU types,
+will give you different random numbers.
+
+@Theglibc{} supports the standard @w{ISO C} random number functions
+plus two other sets derived from BSD and SVID.  The BSD and @w{ISO C}
+functions provide identical, somewhat limited functionality.  If only a
+small number of random bits are required, we recommend you use the
+@w{ISO C} interface, @code{rand} and @code{srand}.  The SVID functions
+provide a more flexible interface, which allows better random number
+generator algorithms, provides more random bits (up to 48) per call, and
+can provide random floating-point numbers.  These functions are required
+by the XPG standard and therefore will be present in all modern Unix
+systems.
+
+@menu
+* ISO Random::                  @code{rand} and friends.
+* BSD Random::                  @code{random} and friends.
+* SVID Random::                 @code{drand48} and friends.
+@end menu
+
+@node ISO Random
+@subsection ISO C Random Number Functions
+
+This section describes the random number functions that are part of
+the @w{ISO C} standard.
+
+To use these facilities, you should include the header file
+@file{stdlib.h} in your program.
+@pindex stdlib.h
+
+@deftypevr Macro int RAND_MAX
+@standards{ISO, stdlib.h}
+The value of this macro is an integer constant representing the largest
+value the @code{rand} function can return.  In @theglibc{}, it is
+@code{2147483647}, which is the largest signed integer representable in
+32 bits.  In other libraries, it may be as low as @code{32767}.
+@end deftypevr
+
+@deftypefun int rand (void)
+@standards{ISO, stdlib.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c Just calls random.
+The @code{rand} function returns the next pseudo-random number in the
+series.  The value ranges from @code{0} to @code{RAND_MAX}.
+@end deftypefun
+
+@deftypefun void srand (unsigned int @var{seed})
+@standards{ISO, stdlib.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c Alias to srandom.
+This function establishes @var{seed} as the seed for a new series of
+pseudo-random numbers.  If you call @code{rand} before a seed has been
+established with @code{srand}, it uses the value @code{1} as a default
+seed.
+
+To produce a different pseudo-random series each time your program is
+run, do @code{srand (time (0))}.
+@end deftypefun
+
+POSIX.1 extended the C standard functions to support reproducible random
+numbers in multi-threaded programs.  However, the extension is badly
+designed and unsuitable for serious work.
+
+@deftypefun int rand_r (unsigned int *@var{seed})
+@standards{POSIX.1, stdlib.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function returns a random number in the range 0 to @code{RAND_MAX}
+just as @code{rand} does.  However, all its state is stored in the
+@var{seed} argument.  This means the RNG's state can only have as many
+bits as the type @code{unsigned int} has.  This is far too few to
+provide a good RNG.
+
+If your program requires a reentrant RNG, we recommend you use the
+reentrant GNU extensions to the SVID random number generator.  The
+POSIX.1 interface should only be used when the GNU extensions are not
+available.
+@end deftypefun
+
+
+@node BSD Random
+@subsection BSD Random Number Functions
+
+This section describes a set of random number generation functions that
+are derived from BSD.  There is no advantage to using these functions
+with @theglibc{}; we support them for BSD compatibility only.
+
+The prototypes for these functions are in @file{stdlib.h}.
+@pindex stdlib.h
+
+@deftypefun {long int} random (void)
+@standards{BSD, stdlib.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c Takes a lock and calls random_r with an automatic variable and the
+@c global state, while holding a lock.
+This function returns the next pseudo-random number in the sequence.
+The value returned ranges from @code{0} to @code{2147483647}.
+
+@strong{NB:} Temporarily this function was defined to return a
+@code{int32_t} value to indicate that the return value always contains
+32 bits even if @code{long int} is wider.  The standard demands it
+differently.  Users must always be aware of the 32-bit limitation,
+though.
+@end deftypefun
+
+@deftypefun void srandom (unsigned int @var{seed})
+@standards{BSD, stdlib.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c Takes a lock and calls srandom_r with an automatic variable and a
+@c static buffer.  There's no MT-safety issue because the static buffer
+@c is internally protected by a lock, although other threads may modify
+@c the set state before it is used.
+The @code{srandom} function sets the state of the random number
+generator based on the integer @var{seed}.  If you supply a @var{seed} value
+of @code{1}, this will cause @code{random} to reproduce the default set
+of random numbers.
+
+To produce a different set of pseudo-random numbers each time your
+program runs, do @code{srandom (time (0))}.
+@end deftypefun
+
+@deftypefun {char *} initstate (unsigned int @var{seed}, char *@var{state}, size_t @var{size})
+@standards{BSD, stdlib.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+The @code{initstate} function is used to initialize the random number
+generator state.  The argument @var{state} is an array of @var{size}
+bytes, used to hold the state information.  It is initialized based on
+@var{seed}.  The size must be between 8 and 256 bytes, and should be a
+power of two.  The bigger the @var{state} array, the better.
+
+The return value is the previous value of the state information array.
+You can use this value later as an argument to @code{setstate} to
+restore that state.
+@end deftypefun
+
+@deftypefun {char *} setstate (char *@var{state})
+@standards{BSD, stdlib.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+The @code{setstate} function restores the random number state
+information @var{state}.  The argument must have been the result of
+a previous call to @var{initstate} or @var{setstate}.
+
+The return value is the previous value of the state information array.
+You can use this value later as an argument to @code{setstate} to
+restore that state.
+
+If the function fails the return value is @code{NULL}.
+@end deftypefun
+
+The four functions described so far in this section all work on a state
+which is shared by all threads.  The state is not directly accessible to
+the user and can only be modified by these functions.  This makes it
+hard to deal with situations where each thread should have its own
+pseudo-random number generator.
+
+@Theglibc{} contains four additional functions which contain the
+state as an explicit parameter and therefore make it possible to handle
+thread-local PRNGs.  Besides this there is no difference.  In fact, the
+four functions already discussed are implemented internally using the
+following interfaces.
+
+The @file{stdlib.h} header contains a definition of the following type:
+
+@deftp {Data Type} {struct random_data}
+@standards{GNU, stdlib.h}
+
+Objects of type @code{struct random_data} contain the information
+necessary to represent the state of the PRNG.  Although a complete
+definition of the type is present the type should be treated as opaque.
+@end deftp
+
+The functions modifying the state follow exactly the already described
+functions.
+
+@deftypefun int random_r (struct random_data *restrict @var{buf}, int32_t *restrict @var{result})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{random_r} function behaves exactly like the @code{random}
+function except that it uses and modifies the state in the object
+pointed to by the first parameter instead of the global state.
+@end deftypefun
+
+@deftypefun int srandom_r (unsigned int @var{seed}, struct random_data *@var{buf})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{srandom_r} function behaves exactly like the @code{srandom}
+function except that it uses and modifies the state in the object
+pointed to by the second parameter instead of the global state.
+@end deftypefun
+
+@deftypefun int initstate_r (unsigned int @var{seed}, char *restrict @var{statebuf}, size_t @var{statelen}, struct random_data *restrict @var{buf})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{initstate_r} function behaves exactly like the @code{initstate}
+function except that it uses and modifies the state in the object
+pointed to by the fourth parameter instead of the global state.
+@end deftypefun
+
+@deftypefun int setstate_r (char *restrict @var{statebuf}, struct random_data *restrict @var{buf})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{setstate_r} function behaves exactly like the @code{setstate}
+function except that it uses and modifies the state in the object
+pointed to by the first parameter instead of the global state.
+@end deftypefun
+
+@node SVID Random
+@subsection SVID Random Number Function
+
+The C library on SVID systems contains yet another kind of random number
+generator functions.  They use a state of 48 bits of data.  The user can
+choose among a collection of functions which return the random bits
+in different forms.
+
+Generally there are two kinds of function.  The first uses a state of
+the random number generator which is shared among several functions and
+by all threads of the process.  The second requires the user to handle
+the state.
+
+All functions have in common that they use the same congruential
+formula with the same constants.  The formula is
+
+@smallexample
+Y = (a * X + c) mod m
+@end smallexample
+
+@noindent
+where @var{X} is the state of the generator at the beginning and
+@var{Y} the state at the end.  @code{a} and @code{c} are constants
+determining the way the generator works.  By default they are
+
+@smallexample
+a = 0x5DEECE66D = 25214903917
+c = 0xb = 11
+@end smallexample
+
+@noindent
+but they can also be changed by the user.  @code{m} is of course 2^48
+since the state consists of a 48-bit array.
+
+The prototypes for these functions are in @file{stdlib.h}.
+@pindex stdlib.h
+
+
+@deftypefun double drand48 (void)
+@standards{SVID, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+@c Uses of the static state buffer are not guarded by a lock (thus
+@c @mtasurace:drand48), so they may be found or left at a
+@c partially-updated state in case of calls from within signal handlers
+@c or cancellation.  None of this will break safety rules or invoke
+@c undefined behavior, but it may affect randomness.
+This function returns a @code{double} value in the range of @code{0.0}
+to @code{1.0} (exclusive).  The random bits are determined by the global
+state of the random number generator in the C library.
+
+Since the @code{double} type according to @w{IEEE 754} has a 52-bit
+mantissa this means 4 bits are not initialized by the random number
+generator.  These are (of course) chosen to be the least significant
+bits and they are initialized to @code{0}.
+@end deftypefun
+
+@deftypefun double erand48 (unsigned short int @var{xsubi}[3])
+@standards{SVID, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+@c The static buffer is just initialized with default parameters, which
+@c are later read to advance the state held in xsubi.
+This function returns a @code{double} value in the range of @code{0.0}
+to @code{1.0} (exclusive), similarly to @code{drand48}.  The argument is
+an array describing the state of the random number generator.
+
+This function can be called subsequently since it updates the array to
+guarantee random numbers.  The array should have been initialized before
+initial use to obtain reproducible results.
+@end deftypefun
+
+@deftypefun {long int} lrand48 (void)
+@standards{SVID, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+The @code{lrand48} function returns an integer value in the range of
+@code{0} to @code{2^31} (exclusive).  Even if the size of the @code{long
+int} type can take more than 32 bits, no higher numbers are returned.
+The random bits are determined by the global state of the random number
+generator in the C library.
+@end deftypefun
+
+@deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3])
+@standards{SVID, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+This function is similar to the @code{lrand48} function in that it
+returns a number in the range of @code{0} to @code{2^31} (exclusive) but
+the state of the random number generator used to produce the random bits
+is determined by the array provided as the parameter to the function.
+
+The numbers in the array are updated afterwards so that subsequent calls
+to this function yield different results (as is expected of a random
+number generator).  The array should have been initialized before the
+first call to obtain reproducible results.
+@end deftypefun
+
+@deftypefun {long int} mrand48 (void)
+@standards{SVID, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+The @code{mrand48} function is similar to @code{lrand48}.  The only
+difference is that the numbers returned are in the range @code{-2^31} to
+@code{2^31} (exclusive).
+@end deftypefun
+
+@deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3])
+@standards{SVID, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+The @code{jrand48} function is similar to @code{nrand48}.  The only
+difference is that the numbers returned are in the range @code{-2^31} to
+@code{2^31} (exclusive).  For the @code{xsubi} parameter the same
+requirements are necessary.
+@end deftypefun
+
+The internal state of the random number generator can be initialized in
+several ways.  The methods differ in the completeness of the
+information provided.
+
+@deftypefun void srand48 (long int @var{seedval})
+@standards{SVID, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+The @code{srand48} function sets the most significant 32 bits of the
+internal state of the random number generator to the least
+significant 32 bits of the @var{seedval} parameter.  The lower 16 bits
+are initialized to the value @code{0x330E}.  Even if the @code{long
+int} type contains more than 32 bits only the lower 32 bits are used.
+
+Owing to this limitation, initialization of the state of this
+function is not very useful.  But it makes it easy to use a construct
+like @code{srand48 (time (0))}.
+
+A side-effect of this function is that the values @code{a} and @code{c}
+from the internal state, which are used in the congruential formula,
+are reset to the default values given above.  This is of importance once
+the user has called the @code{lcong48} function (see below).
+@end deftypefun
+
+@deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
+@standards{SVID, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+The @code{seed48} function initializes all 48 bits of the state of the
+internal random number generator from the contents of the parameter
+@var{seed16v}.  Here the lower 16 bits of the first element of
+@var{seed16v} initialize the least significant 16 bits of the internal
+state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order
+16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]}
+initialize the most significant 16 bits of the state.
+
+Unlike @code{srand48} this function lets the user initialize all 48 bits
+of the state.
+
+The value returned by @code{seed48} is a pointer to an array containing
+the values of the internal state before the change.  This might be
+useful to restart the random number generator at a certain state.
+Otherwise the value can simply be ignored.
+
+As for @code{srand48}, the values @code{a} and @code{c} from the
+congruential formula are reset to the default values.
+@end deftypefun
+
+There is one more function to initialize the random number generator
+which enables you to specify even more information by allowing you to
+change the parameters in the congruential formula.
+
+@deftypefun void lcong48 (unsigned short int @var{param}[7])
+@standards{SVID, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+The @code{lcong48} function allows the user to change the complete state
+of the random number generator.  Unlike @code{srand48} and
+@code{seed48}, this function also changes the constants in the
+congruential formula.
+
+From the seven elements in the array @var{param} the least significant
+16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]}
+determine the initial state, the least significant 16 bits of
+@code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
+constant @code{a} and @code{@var{param}[6]} determines the 16-bit value
+@code{c}.
+@end deftypefun
+
+All the above functions have in common that they use the global
+parameters for the congruential formula.  In multi-threaded programs it
+might sometimes be useful to have different parameters in different
+threads.  For this reason all the above functions have a counterpart
+which works on a description of the random number generator in the
+user-supplied buffer instead of the global state.
+
+Please note that it is no problem if several threads use the global
+state if all threads use the functions which take a pointer to an array
+containing the state.  The random numbers are computed following the
+same loop but if the state in the array is different all threads will
+obtain an individual random number generator.
+
+The user-supplied buffer must be of type @code{struct drand48_data}.
+This type should be regarded as opaque and not manipulated directly.
+
+@deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+This function is equivalent to the @code{drand48} function with the
+difference that it does not modify the global random number generator
+parameters but instead the parameters in the buffer supplied through the
+pointer @var{buffer}.  The random number is returned in the variable
+pointed to by @var{result}.
+
+The return value of the function indicates whether the call succeeded.
+If the value is less than @code{0} an error occurred and @var{errno} is
+set to indicate the problem.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{erand48_r} function works like @code{erand48}, but in addition
+it takes an argument @var{buffer} which describes the random number
+generator.  The state of the random number generator is taken from the
+@code{xsubi} array, the parameters for the congruential formula from the
+global random number generator data.  The random number is returned in
+the variable pointed to by @var{result}.
+
+The return value is non-negative if the call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@deftypefun int lrand48_r (struct drand48_data *@var{buffer}, long int *@var{result})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+This function is similar to @code{lrand48}, but in addition it takes a
+pointer to a buffer describing the state of the random number generator
+just like @code{drand48}.
+
+If the return value of the function is non-negative the variable pointed
+to by @var{result} contains the result.  Otherwise an error occurred.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{nrand48_r} function works like @code{nrand48} in that it
+produces a random number in the range @code{0} to @code{2^31}.  But instead
+of using the global parameters for the congruential formula it uses the
+information from the buffer pointed to by @var{buffer}.  The state is
+described by the values in @var{xsubi}.
+
+If the return value is non-negative the variable pointed to by
+@var{result} contains the result.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@deftypefun int mrand48_r (struct drand48_data *@var{buffer}, long int *@var{result})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+This function is similar to @code{mrand48} but like the other reentrant
+functions it uses the random number generator described by the value in
+the buffer pointed to by @var{buffer}.
+
+If the return value is non-negative the variable pointed to by
+@var{result} contains the result.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{jrand48_r} function is similar to @code{jrand48}.  Like the
+other reentrant functions of this function family it uses the
+congruential formula parameters from the buffer pointed to by
+@var{buffer}.
+
+If the return value is non-negative the variable pointed to by
+@var{result} contains the result.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+Before any of the above functions are used the buffer of type
+@code{struct drand48_data} should be initialized.  The easiest way to do
+this is to fill the whole buffer with null bytes, e.g. by
+
+@smallexample
+memset (buffer, '\0', sizeof (struct drand48_data));
+@end smallexample
+
+@noindent
+Using any of the reentrant functions of this family now will
+automatically initialize the random number generator to the default
+values for the state and the parameters of the congruential formula.
+
+The other possibility is to use any of the functions which explicitly
+initialize the buffer.  Though it might be obvious how to initialize the
+buffer from looking at the parameter to the function, it is highly
+recommended to use these functions since the result might not always be
+what you expect.
+
+@deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+The description of the random number generator represented by the
+information in @var{buffer} is initialized similarly to what the function
+@code{srand48} does.  The state is initialized from the parameter
+@var{seedval} and the parameters for the congruential formula are
+initialized to their default values.
+
+If the return value is non-negative the function call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+This function is similar to @code{srand48_r} but like @code{seed48} it
+initializes all 48 bits of the state from the parameter @var{seed16v}.
+
+If the return value is non-negative the function call succeeded.  It
+does not return a pointer to the previous state of the random number
+generator like the @code{seed48} function does.  If the user wants to
+preserve the state for a later re-run s/he can copy the whole buffer
+pointed to by @var{buffer}.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+This function initializes all aspects of the random number generator
+described in @var{buffer} with the data in @var{param}.  Here it is
+especially true that the function does more than just copying the
+contents of @var{param} and @var{buffer}.  More work is required and
+therefore it is important to use this function rather than initializing
+the random number generator directly.
+
+If the return value is non-negative the function call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@node Unpredictable Bytes
+@section Generating Unpredictable Bytes
+
+Some cryptographic applications (such as session key generation) need
+unpredictable bytes.
+
+In general, application code should use a deterministic random bit
+generator, which could call the @code{getentropy} function described
+below internally to obtain randomness to seed the generator.  The
+@code{getrandom} function is intended for low-level applications which
+need additional control over the blocking behavior.
+
+@deftypefun int getentropy (void *@var{buffer}, size_t @var{length})
+@standards{GNU, sys/random.h}
+@safety{@mtsafe{}@assafe{}@acsafe{}}
+
+This function writes @var{length} bytes of random data to the array
+starting at @var{buffer}, which must be at most 256 bytes long.  The
+function returns zero on success.  On failure, it returns @code{-1} and
+@code{errno} is updated accordingly.
+
+The @code{getentropy} function is declared in the header file
+@file{sys/random.h}.  It is derived from OpenBSD.
+
+The @code{getentropy} function is not a cancellation point.  A call to
+@code{getentropy} can block if the system has just booted and the kernel
+entropy pool has not yet been initialized.  In this case, the function
+will keep blocking even if a signal arrives, and return only after the
+entropy pool has been initialized.
+
+The @code{getentropy} function can fail with several errors, some of
+which are listed below.
+
+@table @code
+@item ENOSYS
+The kernel does not implement the required system call.
+
+@item EFAULT
+The combination of @var{buffer} and @var{length} arguments specifies
+an invalid memory range.
+
+@item EIO
+More than 256 bytes of randomness have been requested, or the buffer
+could not be overwritten with random data for an unspecified reason.
+
+@end table
+
+@end deftypefun
+
+@deftypefun ssize_t getrandom (void *@var{buffer}, size_t @var{length}, unsigned int @var{flags})
+@standards{GNU, sys/random.h}
+@safety{@mtsafe{}@assafe{}@acsafe{}}
+
+This function writes @var{length} bytes of random data to the array
+starting at @var{buffer}.  On success, this function returns the number
+of bytes which have been written to the buffer (which can be less than
+@var{length}).  On error, @code{-1} is returned, and @code{errno} is
+updated accordingly.
+
+The @code{getrandom} function is declared in the header file
+@file{sys/random.h}.  It is a GNU extension.
+
+The following flags are defined for the @var{flags} argument:
+
+@table @code
+@item GRND_RANDOM
+Use the @file{/dev/random} (blocking) pool instead of the
+@file{/dev/urandom} (non-blocking) pool to obtain randomness.  If the
+@code{GRND_RANDOM} flag is specified, the @code{getrandom} function can
+block even after the randomness source has been initialized.
+
+@item GRND_NONBLOCK
+Instead of blocking, return to the caller immediately if no data is
+available.
+@end table
+
+The @code{getrandom} function is a cancellation point.
+
+Obtaining randomness from the @file{/dev/urandom} pool (i.e., a call
+without the @code{GRND_RANDOM} flag) can block if the system has just
+booted and the pool has not yet been initialized.
+
+The @code{getrandom} function can fail with several errors, some of
+which are listed below.  In addition, the function may not fill the
+buffer completely and return a value less than @var{length}.
+
+@table @code
+@item ENOSYS
+The kernel does not implement the @code{getrandom} system call.
+
+@item EAGAIN
+No random data was available and @code{GRND_NONBLOCK} was specified in
+@var{flags}.
+
+@item EFAULT
+The combination of @var{buffer} and @var{length} arguments specifies
+an invalid memory range.
+
+@item EINTR
+The system call was interrupted.  During the system boot process, before
+the kernel randomness pool is initialized, this can happen even if
+@var{flags} is zero.
+
+@item EINVAL
+The @var{flags} argument contains an invalid combination of flags.
+@end table
+
+@end deftypefun
diff --git a/manual/terminal.texi b/manual/terminal.texi
index 4aace48b14..0b275fc002 100644
--- a/manual/terminal.texi
+++ b/manual/terminal.texi
@@ -24,6 +24,7 @@  descriptor is and how to open a file descriptor for a terminal device.
 * Line Control::                Sending break sequences, clearing
                                  terminal buffers @dots{}
 * Noncanon Example::            How to read single characters without echo.
+* getpass::                     Prompting the user for a password.
 * Pseudo-Terminals::            How to open a pseudo-terminal.
 @end menu
 
@@ -1871,6 +1872,50 @@  existing shells do not actually do this, so you may wish to establish
 handlers for job control signals that reset terminal modes.  The above
 example does so.
 
+@node getpass
+@section Reading Passwords
+
+When reading in a password, it is desirable to avoid displaying it on
+the screen, to help keep it secret.  The following function handles this
+in a convenient way.
+
+@deftypefun {char *} getpass (const char *@var{prompt})
+@standards{BSD, unistd.h}
+@safety{@prelim{}@mtunsafe{@mtasuterm{}}@asunsafe{@ascuheap{} @asulock{} @asucorrupt{}}@acunsafe{@acuterm{} @aculock{} @acucorrupt{}}}
+@c This function will attempt to create a stream for terminal I/O, but
+@c will fallback to stdio/stderr.  It attempts to change the terminal
+@c mode in a thread-unsafe way, write out the prompt, read the password,
+@c then restore the terminal mode.  It has a cleanup to close the stream
+@c in case of (synchronous) cancellation, but not to restore the
+@c terminal mode.
+
+@code{getpass} outputs @var{prompt}, then reads a string in from the
+terminal without echoing it.  It tries to connect to the real terminal,
+@file{/dev/tty}, if possible, to encourage users not to put plaintext
+passwords in files; otherwise, it uses @code{stdin} and @code{stderr}.
+@code{getpass} also disables the INTR, QUIT, and SUSP characters on the
+terminal using the @code{ISIG} terminal attribute (@pxref{Local Modes}).
+The terminal is flushed before and after @code{getpass}, so that
+characters of a mistyped password are not accidentally visible.
+
+In other C libraries, @code{getpass} may only return the first
+@code{PASS_MAX} bytes of a password.  @Theglibc{} has no limit, so
+@code{PASS_MAX} is undefined.
+
+The prototype for this function is in @file{unistd.h}.  @code{PASS_MAX}
+would be defined in @file{limits.h}.
+@end deftypefun
+
+This precise set of operations may not suit all possible situations.  In
+this case, it is recommended that users write their own @code{getpass}
+substitute.  For instance, a very simple substitute is as follows:
+
+@smallexample
+@include mygetpass.c.texi
+@end smallexample
+
+The substitute takes the same parameters as @code{getline}
+(@pxref{Line Input}); the user must print any prompt desired.
 
 @node Pseudo-Terminals
 @section Pseudo-Terminals
diff --git a/manual/time.texi b/manual/time.texi
index 4d154452eb..d0821703c0 100644
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -1,4 +1,4 @@ 
-@node Date and Time, Resource Usage And Limitation, Arithmetic, Top
+@node Date and Time, Resource Usage And Limitation, Random Number Generation, Top
 @c %MENU% Functions for getting the date and time and formatting them nicely
 @chapter Date and Time