diff options
Diffstat (limited to 'manual/terminal.texi')
| -rw-r--r-- | manual/terminal.texi | 45 |
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 |