NAME
getpass —
get a password
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <unistd.h>
char *
getpass(
const
char *prompt);
char *
getpass_r(
const
char *prompt,
char
*buf,
size_t buflen);
char *
getpassfd(
const
char *prompt,
char
*buf,
size_t buflen,
int *fd,
int flags,
int timeout);
DESCRIPTION
The
getpass() function displays a prompt to, and reads in a
password from,
/dev/tty. If this file is not accessible,
getpass() displays the prompt on the standard error output
and reads from the standard input.
The password may be up to
sysconf(3)
_SC_PASS_MAX
characters in length. Any additional
characters and the terminating newline character are discarded.
getpass() turns off character echoing while reading the
password.
getpass_r() is similar to
getpass() only it
puts its result in
buf for up to
buflen characters. If the
buf
argument is
NULL
, then a buffer will be dynamically
allocated.
The
getpassfd() function allows one to specify the three file
descriptors corresponding to
stdin
,
stdout
, and
stderr
in the
fd argument, or if
fd is
NULL
,
getpassfd() first attempts to
open
/dev/tty and if that fails, defaults to
STDIN_FILENO
for input and
STDERR_FILENO
for output.
The behavior of
getpassfd() is controlled by the
flags argument:
-
-
GETPASS_NEED_TTY
- Fail if we are unable to set the tty modes like we
want.
-
-
GETPASS_FAIL_EOF
- Fail if we get the end-of-file character instead of
returning the result so far.
-
-
GETPASS_BUF_LIMIT
- Beep when the buffer limit is reached, instead of silently
absorbing it.
-
-
GETPASS_NO_SIGNAL
- Don't make ttychars send signals.
-
-
GETPASS_NO_BEEP
- Don't beep if we erase past the beginning of the buffer or
we try to enter past the end.
-
-
GETPASS_ECHO_STAR
- Echo a ‘*’ for each character entered.
-
-
GETPASS_ECHO
- Echo characters as they are typed.
-
-
GETPASS_ECHO_NL
- Echoes a newline if successful.
-
-
GETPASS_7BIT
- Mask the high bit for each entered character.
-
-
GETPASS_FORCE_LOWER
- Lowercase each entered character.
-
-
GETPASS_FORCE_UPPER
- Uppercase each entered character.
Finally if the
timeout argument is non zero,
getpassfd() will wait for
timeout
seconds for input after each character before returning an error, instead of
waiting forever.
RETURN VALUES
The
getpass() function returns a pointer to the NUL terminated
password, or an empty string on error. The
getpass_r() and
getpassfd() functions return a pointer to the NUL terminated
password, or
NULL
on error.
FILES
- /dev/tty
-
SEE ALSO
crypt(3)
STANDARDS
The
getpass() function appeared in
Version 2 of the Single UNIX Specification
(“SUSv2”), but it was already marked as legacy. The
function was removed in the
IEEE Std 1003.1-2001
(“POSIX.1”) standard.
HISTORY
A
getpass() function appeared in
Version 7 AT&T UNIX. The
getpass_r() and
getpassfd() functions
appeared in
NetBSD 7.0.
BUGS
The
getpass() function leaves its result in an internal static
object and returns a pointer to that object. Subsequent calls to
getpass() will modify the same object.
SECURITY CONSIDERATIONS
The calling process should zero the password as soon as possible to avoid
leaving the cleartext password visible in the process's address space.
Historically
getpass accepted and returned a password if it
could not modify the terminal settings to turn echo off (or if the input was
not a terminal). In this implementation, only terminal input is
accepted.