@@ -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)
@@ -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
@@ -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
@@ -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
new file mode 100644
@@ -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
@@ -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
@@ -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