GETPASS(3)

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

# NAME

`getpass`, `getpass_r`, `getpassfd` — 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 11.0