Update readpassphrase(3)to the latest revisions. Changes are mainly due

to return value constraints now changing as well as more intelligent
handling of signals.

Obtained from:	OpenBSD

1 files changed, 79 insertions, 32 deletions

diff --git a/lib/libc/gen/readpassphrase.3 b/lib/libc/gen/readpassphrase.3
index 3b03c10..3c0aea4 100644
--- a/lib/libc/gen/readpassphrase.3
+++ b/lib/libc/gen/readpassphrase.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: readpassphrase.3,v 1.3 2001/08/06 10:42:25 mpech Exp $
+.\"	$OpenBSD: /usr/local/www/cvsroot/OpenBSD/src/lib/libc/gen/readpassphrase.3,v 1.7 2001/12/15 15:37:51 millert Exp $
 .\"
 .\" Copyright (c) 2000 Todd C. Miller <Todd.Miller@courtesan.com>
 .\" All rights reserved.
@@ -27,15 +27,15 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 20, 2000
+.Dd December 7, 2001
 .Dt READPASSPHRASE 3
 .Os
 .Sh NAME
 .Nm readpassphrase
 .Nd get a passphrase from the user
 .Sh SYNOPSIS
-.In readpassphrase.h
-.Ft "char *"
+.Fd #include <readpassphrase.h>
+.Ft char *
 .Fn readpassphrase "const char *prompt" "char *buf" "size_t bufsiz" "int flags"
 .Sh DESCRIPTION
 The
@@ -53,9 +53,7 @@ In this case it is generally not possible to turn off echo.
 .Pp
 Up to
 .Fa bufsiz
-\- 1 characters (one is for the
-.Dv NUL )
-are read into the provided buffer
+- 1 characters (one is for the NUL) are read into the provided buffer
 .Fa buf .
 Any additional
 characters and the terminating newline (or return) character are discarded.
@@ -64,42 +62,52 @@ characters and the terminating newline (or return) character are discarded.
 takes the following optional
 .Fa flags :
 .Pp
-.Bl -tag -width ".Dv RPP_REQUIRE_TTY" -compact
-.It Dv RPP_ECHO_OFF
-turn off echo (default behavior)
-.It Dv RPP_ECHO_ON
-leave echo on
-.It Dv RPP_REQUIRE_TTY
-fail if there is no tty
-.It Dv RPP_FORCELOWER
-force input to lower case
-.It Dv RPP_FORCEUPPER
-force input to upper case
-.It Dv RPP_SEVENBIT
-strip the high bit from input
-.El
+.Bd -literal -offset indent -compact
+RPP_ECHO_OFF		turn off echo (default behavior)
+RPP_ECHO_ON		leave echo on
+RPP_REQUIRE_TTY		fail if there is no tty
+RPP_FORCELOWER		force input to lower case
+RPP_FORCEUPPER		force input to upper case
+RPP_SEVENBIT		strip the high bit from input
+.Ed
 .Pp
 The calling process should zero the passphrase as soon as possible to
 avoid leaving the cleartext passphrase visible in the process's address
 space.
 .Sh RETURN VALUES
-On success,
+Upon successful completion,
 .Fn readpassphrase
 returns a pointer to the null-terminated passphrase.
-If the
-.Dv RPP_REQUIRE_TTY
-flag is set and
-.Pa /dev/tty
-is inaccessible,
+If an error is encountered, the terminal state is restored and
+a null pointer is returned.
+.Sh ERRORS
+.Bl -tag -width Er
+.It Bq Er EINTR
+The
 .Fn readpassphrase
-returns a
-.Dv NULL
-pointer.
+function was interrupted by a signal.
+.It Bq Er EINVAL
+The
+.Ar bufsiz
+argument was zero.
+.It Bq Er EIO
+The process is a member of a background process attempting to read
+from its controlling terminal, the process is ignoring or blocking
+the SIGTTIN signal or the process group is orphaned.
+.It Bq Er EMFILE
+The process has already reached its limit for open file descriptors.
+.It Bq Er ENFILE
+The system file table is full.
+.It Bq Er ENOTTY
+There is no controlling terminal and the
+.Dv RPP_REQUIRE_TTY
+flag was specified.
+.El
 .Sh EXAMPLES
 The following code fragment will read a passphrase from
 .Pa /dev/tty
 into the buffer
-.Fa passbuf .
+.Fa passbuf.
 .Bd -literal -offset indent
 char passbuf[1024];
 
@@ -116,12 +124,51 @@ if (compare(transform(passbuf), epass) != 0)
 
 memset(passbuf, 0, sizeof(passbuf));
 .Ed
+.Sh SIGNALS
+.Fn readpassphrase
+will catch the following signals:
+.Pp
+.Bd -literal -offset indent -compact
+SIGINT
+SIGHUP
+SIGQUIT
+SIGTERM
+SIGTSTP
+SIGTTIN
+SIGTTOU
+.Ed
+.Pp
+When one of the above signals is intercepted, terminal echo will
+be restored if it had previously been turned off.
+If a signal handler was installed for the signal when
+.Fn readpassphrase
+was called that handler is then executed.
+If no handler was previously installed for the signal then the
+default action is taken as per
+.Xr sigaction 2 .
+.Pp
+The
+.Dv SIGTSTP ,
+.Dv SIGTTIN ,
+.Dv SIGTTOU ,
+signals (stop signal generated from keyboard or due to terminal I/O
+from a background proccess) are treated specially.
+When the process is resumed after it has been stopped,
+.Fn readpassphrase
+will reprint the prompt and the user may then enter a passphrase.
 .Sh FILES
-.Bl -tag -width ".Pa /dev/tty" -compact
+.Bl -tag -width /dev/tty -compact
 .It Pa /dev/tty
 .El
 .Sh SEE ALSO
+.Xr sigaction 2 ,
 .Xr getpass 3
+.Sh STANDARDS
+The
+.Fn readpassphrase
+function is an
+.Ox
+extension and should not be used if portability is desired.
 .Sh HISTORY
 The
 .Fn readpassphrase