NetBSD/lib/libc/gen/getpass.3

.\"	$NetBSD: getpass.3,v 1.22 2012/04/14 10:34:29 wiz Exp $
.\"
.\" Copyright (c) 1989, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)getpass.3	8.1 (Berkeley) 6/4/93
.\"
.Dd April 13, 2012
.Dt GETPASS 3
.Os
.Sh NAME
.Nm getpass
.Nd get a password
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Ft char *
.Fn getpass "const char *prompt"
.Ft char *
.Fn getpass_r "const char *prompt" "char *buf" "size_t buflen"
.Ft char *
.Fn getpassfd "const char *prompt" "char *buf" "size_t buflen" "int *fd" "int flags" "int timeout"
.Sh DESCRIPTION
The
.Fn getpass
function displays a prompt to, and reads in a password from,
.Pa /dev/tty .
If this file is not accessible,
.Fn getpass
displays the prompt on the standard error output and reads from the standard
input.
.Pp
The password may be up to
.Xr sysconf 3
.Dv _SC_PASS_MAX
characters in length.
Any additional
characters and the terminating newline character are discarded.
.Pp
.Fn getpass
turns off character echoing while reading the password.
.Pp
.Fn getpass_r
is similar to
.Fn getpass
only it puts its result in
.Fa buf
for up to
.Fa buflen
characters.
If the
.Fa buf
argument is
.Dv NULL ,
then a buffer will be dynamically allocated.
.Pp
The
.Fn getpassfd
function allows one to specify the three file descriptors corresponding to
.Dv stdin ,
.Dv stdout ,
and
.Dv stderr
in the
.Fa fd
argument, or if
.Fa fd
is
.Dv NULL ,
.Fn getpassfd
first attempts to open
.Pa /dev/tty
and if that fails, defaults to
.Dv STDIN_FILENO
for input and
.Dv STDERR_FILENO
for output.
.Pp
The behavior of
.Fn getpassfd
is controlled by the
.Fa flags
argument:
.Bl -tag -width GETPASS_FORCE_UPPER
.It Dv GETPASS_NEED_TTY
Fail if we are unable to set the tty modes like we want.
.It Dv GETPASS_FAIL_EOF
Fail if we get the end-of-file character instead of returning the result so far.
.It Dv GETPASS_BUF_LIMIT
Beep when the buffer limit is reached, instead of silently absorbing it.
.It Dv GETPASS_NO_SIGNAL
Don't make ttychars send signals.
.It Dv GETPASS_NO_BEEP
Don't beep if we erase past the beginning of the buffer or we try to enter past
the end.
.It Dv GETPASS_ECHO_STAR
Echo a
.Sq *
for each character entered.
.It Dv GETPASS_ECHO
Echo characters as they are typed.
.It Dv GETPASS_ECHO_NL
Echoes a newline if successful.
.It Dv GETPASS_7BIT
Mask the high bit for each entered character.
.It Dv GETPASS_FORCE_LOWER
Lowercase each entered character.
.It Dv GETPASS_FORCE_UPPER
Uppercase each entered character.
.El
.Pp
Finally if the
.Fa timeout
argument is non zero,
.Fn getpassfd
will wait for
.Fa timeout
seconds for input after each character before returning an error, instead of
waiting forever.
.Sh RETURN VALUES
The
.Fn getpass
function returns a pointer to the NUL terminated password, or an empty
string on error.
The
.Fn getpass_r
and
.Fn getpassfd
functions return a pointer to the NUL terminated password, or
.Dv NULL
on error.
.Sh FILES
.Bl -tag -width /dev/tty -compact
.It Pa /dev/tty
.El
.Sh SEE ALSO
.Xr crypt 3
.Sh STANDARDS
The
.Fn getpass
function appeared in
.St -susv2 ,
but it was already marked as legacy.
The function was removed in the
.St -p1003.1-2001
standard.
.Sh HISTORY
A
.Fn getpass
function appeared in
.At v7 .
The
.Fn getpass_r
and
.Fn getpassfd
functions appeared in
.Nx 7.0 .
.Sh BUGS
The
.Fn getpass
function leaves its result in an internal static object and returns
a pointer to that object.
Subsequent calls to
.Fn getpass
will modify the same object.
.Sh 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.
.Pp
Historically
.Nm
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.