1
0
mirror of https://git.FreeBSD.org/src.git synced 2024-12-16 10:20:30 +00:00

Come on guys, you can't just take OpenBSD manpage and commit it

over someone else's fixes; this is at least offensive.  If you
have problems doing a proper merge, we are here, your fellow
committers.  :-(

Reapply markup fixes from revision 1.2 and fix some more.  Also
fix the $OpenBSD$ tag.
This commit is contained in:
Ruslan Ermilov 2002-03-15 17:46:53 +00:00
parent 5c9f299b01
commit f3a90e8782
Notes: svn2git 2020-12-20 02:59:44 +00:00
svn path=/head/; revision=92350

View File

@ -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 <Todd.Miller@courtesan.com>
.\" All rights reserved.
@ -34,8 +34,8 @@
.Nm readpassphrase
.Nd get a passphrase from the user
.Sh SYNOPSIS
.Fd #include <readpassphrase.h>
.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