The
readpassphrase ();
function displays a prompt to, and reads in a passphrase from,
/dev/tty
If this file is inaccessible
and the
RPP_REQUIRE_TTY
flag is not set,
readpassphrase ();
displays the prompt on the standard error output and reads from the standard
input.
In this case it is generally not possible to turn off echo.
Up to
Fa bufsiz
- 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.
The
readpassphrase ();
function
takes the following optional
Fa flags :
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
The calling process should zero the passphrase as soon as possible to
avoid leaving the cleartext passphrase visible in the process's address
space.
RETURN VALUES
Upon successful completion,
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.
FILES
/dev/tty
EXAMPLES
The following code fragment will read a passphrase from
/dev/tty
into the buffer
Fa passbuf .
char passbuf[1024];
...
if (readpassphrase("Response: ", passbuf, sizeof(passbuf),
RPP_REQUIRE_TTY) == NULL)
errx(1, "unable to read passphrase");
if (compare(transform(passbuf), epass) != 0)
errx(1, "bad passphrase");
...
memset(passbuf, 0, sizeof(passbuf));
SIGNALS
The
readpassphrase ();
function
will catch the following signals:
SIGINT
SIGHUP
SIGQUIT
SIGTERM
SIGTSTP
SIGTTIN
SIGTTOU
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
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
sigaction(2).
The
SIGTSTP , SIGTTIN
and
SIGTTOU
signals (stop signal generated from keyboard or due to terminal I/O
from a background process) are treated specially.
When the process is resumed after it has been stopped,
readpassphrase ();
will reprint the prompt and the user may then enter a passphrase.
ERRORS
Bq Er EINTR
The
readpassphrase ();
function was interrupted by a signal.
Bq Er EINVAL
The
Fa bufsiz
argument was zero.
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.
Bq Er EMFILE
The process has already reached its limit for open file descriptors.
Bq Er ENFILE
The system file table is full.
Bq Er ENOTTY
There is no controlling terminal and the
RPP_REQUIRE_TTY
flag was specified.
