diff --git a/lib/libc/gen/readpassphrase.3 b/lib/libc/gen/readpassphrase.3 index 3c0aea47d106..cfa6cf0631db 100644 --- a/lib/libc/gen/readpassphrase.3 +++ b/lib/libc/gen/readpassphrase.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: /usr/local/www/cvsroot/OpenBSD/src/lib/libc/gen/readpassphrase.3,v 1.7 2001/12/15 15:37:51 millert Exp $ +.\" $OpenBSD: readpassphrase.3,v 1.7 2001/12/15 15:37:51 millert Exp $ .\" .\" Copyright (c) 2000 Todd C. Miller .\" All rights reserved. @@ -34,8 +34,8 @@ .Nm readpassphrase .Nd get a passphrase from the user .Sh SYNOPSIS -.Fd #include -.Ft char * +.In readpassphrase.h +.Ft "char *" .Fn readpassphrase "const char *prompt" "char *buf" "size_t bufsiz" "int flags" .Sh DESCRIPTION The @@ -53,7 +53,9 @@ In this case it is generally not possible to turn off echo. .Pp Up to .Fa bufsiz -- 1 characters (one is for the NUL) are read into the provided buffer +\- 1 characters (one is for the +.Dv NUL ) +are read into the provided buffer .Fa buf . Any additional characters and the terminating newline (or return) character are discarded. @@ -62,14 +64,20 @@ characters and the terminating newline (or return) character are discarded. takes the following optional .Fa flags : .Pp -.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 +.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 .Pp The calling process should zero the passphrase as soon as possible to avoid leaving the cleartext passphrase visible in the process's address @@ -79,7 +87,9 @@ Upon successful completion, .Fn readpassphrase returns a pointer to the null-terminated passphrase. If an error is encountered, the terminal state is restored and -a null pointer is returned. +a +.Dv NULL +pointer is returned. .Sh ERRORS .Bl -tag -width Er .It Bq Er EINTR @@ -88,12 +98,14 @@ The function was interrupted by a signal. .It Bq Er EINVAL The -.Ar bufsiz +.Fa 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. +the +.Dv 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 @@ -107,7 +119,7 @@ flag was specified. 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]; @@ -128,15 +140,15 @@ memset(passbuf, 0, sizeof(passbuf)); .Fn readpassphrase will catch the following signals: .Pp -.Bd -literal -offset indent -compact -SIGINT -SIGHUP -SIGQUIT -SIGTERM -SIGTSTP -SIGTTIN -SIGTTOU -.Ed +.Bl -tag -compact +.It Dv SIGINT +.It Dv SIGHUP +.It Dv SIGQUIT +.It Dv SIGTERM +.It Dv SIGTSTP +.It Dv SIGTTIN +.It Dv SIGTTOU +.El .Pp When one of the above signals is intercepted, terminal echo will be restored if it had previously been turned off. @@ -148,16 +160,16 @@ default action is taken as per .Xr sigaction 2 . .Pp The -.Dv SIGTSTP , -.Dv SIGTTIN , -.Dv SIGTTOU , +.Dv SIGTSTP , SIGTTIN , +and +.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 /dev/tty -compact +.Bl -tag -width ".Pa /dev/tty" -compact .It Pa /dev/tty .El .Sh SEE ALSO @@ -167,7 +179,6 @@ will reprint the prompt and the user may then enter a passphrase. The .Fn readpassphrase function is an -.Ox extension and should not be used if portability is desired. .Sh HISTORY The