manual: Reorganize crypt.texi.

In preparation for a major revision of the documentation for
crypt(_r), getentropy, and getrandom, reorganize crypt.texi.  This
patch does not change any text; it only deletes and moves text.

The description of 'getpass' moves to terminal.texi, since all it does
is read a password from the controlling terminal with echo disabled.
The "Legal Problems" section of crypt.texi is dropped, and the
introductory text is shifted down to the "Encrypting Passwords"
section; the next patch will add some new introductory text.

Also, it is no longer true that crypt.texi's top @node needs to have
no pointers.  That was a vestige of crypt/ being an add-on.  (makeinfo
itself doesn't need @node pointers anymore, but the scripts that
assemble the libc manual's topmost node rely on each chapter-level
node having them.)

1 files changed, 45 insertions, 0 deletions

diff --git a/manual/terminal.texi b/manual/terminal.texi
index 4aace48..0b275fc 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