getpass(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
GETPASS(3)              NetBSD 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 dis-
     carded.

     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.

NetBSD 10.1                     April 13, 2012                     NetBSD 10.1