aboutsummaryrefslogtreecommitdiff
path: root/manual/terminal.texi
diff options
context:
space:
mode:
authorZack Weinberg <zackw@panix.com>2018-06-29 16:53:29 +0200
committerFlorian Weimer <fweimer@redhat.com>2018-06-29 16:53:29 +0200
commit6ab902e4decd89c1a9206497d14ddba7680bfc37 (patch)
tree1d1a97ad2b41b5af32bc722898b259018bd640ca /manual/terminal.texi
parentb10a0accee709a5efff2fadf0b0bbb79ff0ad759 (diff)
downloadglibc-6ab902e4decd89c1a9206497d14ddba7680bfc37.tar
glibc-6ab902e4decd89c1a9206497d14ddba7680bfc37.tar.gz
glibc-6ab902e4decd89c1a9206497d14ddba7680bfc37.tar.bz2
glibc-6ab902e4decd89c1a9206497d14ddba7680bfc37.zip
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.)
Diffstat (limited to 'manual/terminal.texi')
-rw-r--r--manual/terminal.texi45
1 files changed, 45 insertions, 0 deletions
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