GETPASS(3)

GETPASS(3) | Library Functions Manual | GETPASS(3)

# 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.

April 13, 2012 | NetBSD 8.3