Document signal handling in readpassphrase(3)

1 files changed, 47 insertions, 2 deletions

diff --git a/lib/libc/gen/readpassphrase.3 b/lib/libc/gen/readpassphrase.3
index b39ce37bd3f..0abfbf3de7e 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: readpassphrase.3,v 1.4 2001/12/07 20:21:17 millert Exp $
 .\"
 .\" Copyright (c) 2000 Todd C. Miller <Todd.Miller@courtesan.com>
 .\" All rights reserved.
@@ -104,12 +104,57 @@ 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
+.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
+signal (stop signal generated from keyboard) is 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.
+.Pp
+Note: if the handler for a signal was
+.Dv SIG_IGN
+(ignore signal) when
+.Fn readpassphrase
+was called, terminal echo will not be restored to its previous value
+(since there is no other handler to call).
+This is only a problem when the program that calls
+.Fn readpassphrase
+is running as a child process of another program that also
+receives the signal (and exits or suspends due to it).
+Because of this it is suggested that these signals be blocked
+instead of ignored.
+See
+.Xr sigprocmask 3
+for details on blocking signal receipt.
 .Sh FILES
 .Bl -tag -width /dev/tty -compact
 .It Pa /dev/tty
 .El
 .Sh SEE ALSO
-.Xr getpass 3
+.Xr sigaction 2 ,
+.Xr getpass 3 ,
+.Xr sigprocmask 3
 .Sh HISTORY
 The
 .Fn readpassphrase