1.\"	$NetBSD: getpass.3,v 1.22 2012/04/14 10:34:29 wiz Exp $
2.\"
3.\" Copyright (c) 1989, 1991, 1993
4.\"	The Regents of the University of California.  All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors
15.\"    may be used to endorse or promote products derived from this software
16.\"    without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\"     @(#)getpass.3	8.1 (Berkeley) 6/4/93
31.\"
32.Dd April 13, 2012
33.Dt GETPASS 3
34.Os
35.Sh NAME
36.Nm getpass
37.Nd get a password
38.Sh LIBRARY
39.Lb libc
40.Sh SYNOPSIS
41.In unistd.h
42.Ft char *
43.Fn getpass "const char *prompt"
44.Ft char *
45.Fn getpass_r "const char *prompt" "char *buf" "size_t buflen"
46.Ft char *
47.Fn getpassfd "const char *prompt" "char *buf" "size_t buflen" "int *fd" "int flags" "int timeout"
48.Sh DESCRIPTION
49The
50.Fn getpass
51function displays a prompt to, and reads in a password from,
52.Pa /dev/tty .
53If this file is not accessible,
54.Fn getpass
55displays the prompt on the standard error output and reads from the standard
56input.
57.Pp
58The password may be up to
59.Xr sysconf 3
60.Dv _SC_PASS_MAX
61characters in length.
62Any additional
63characters and the terminating newline character are discarded.
64.Pp
65.Fn getpass
66turns off character echoing while reading the password.
67.Pp
68.Fn getpass_r
69is similar to
70.Fn getpass
71only it puts its result in
72.Fa buf
73for up to
74.Fa buflen
75characters.
76If the
77.Fa buf
78argument is
79.Dv NULL ,
80then a buffer will be dynamically allocated.
81.Pp
82The
83.Fn getpassfd
84function allows one to specify the three file descriptors corresponding to
85.Dv stdin ,
86.Dv stdout ,
87and
88.Dv stderr
89in the
90.Fa fd
91argument, or if
92.Fa fd
93is
94.Dv NULL ,
95.Fn getpassfd
96first attempts to open
97.Pa /dev/tty
98and if that fails, defaults to
99.Dv STDIN_FILENO
100for input and
101.Dv STDERR_FILENO
102for output.
103.Pp
104The behavior of
105.Fn getpassfd
106is controlled by the
107.Fa flags
108argument:
109.Bl -tag -width GETPASS_FORCE_UPPER
110.It Dv GETPASS_NEED_TTY
111Fail if we are unable to set the tty modes like we want.
112.It Dv GETPASS_FAIL_EOF
113Fail if we get the end-of-file character instead of returning the result so far.
114.It Dv GETPASS_BUF_LIMIT
115Beep when the buffer limit is reached, instead of silently absorbing it.
116.It Dv GETPASS_NO_SIGNAL
117Don't make ttychars send signals.
118.It Dv GETPASS_NO_BEEP
119Don't beep if we erase past the beginning of the buffer or we try to enter past
120the end.
121.It Dv GETPASS_ECHO_STAR
122Echo a
123.Sq *
124for each character entered.
125.It Dv GETPASS_ECHO
126Echo characters as they are typed.
127.It Dv GETPASS_ECHO_NL
128Echoes a newline if successful.
129.It Dv GETPASS_7BIT
130Mask the high bit for each entered character.
131.It Dv GETPASS_FORCE_LOWER
132Lowercase each entered character.
133.It Dv GETPASS_FORCE_UPPER
134Uppercase each entered character.
135.El
136.Pp
137Finally if the
138.Fa timeout
139argument is non zero,
140.Fn getpassfd
141will wait for
142.Fa timeout
143seconds for input after each character before returning an error, instead of
144waiting forever.
145.Sh RETURN VALUES
146The
147.Fn getpass
148function returns a pointer to the NUL terminated password, or an empty
149string on error.
150The
151.Fn getpass_r
152and
153.Fn getpassfd
154functions return a pointer to the NUL terminated password, or
155.Dv NULL
156on error.
157.Sh FILES
158.Bl -tag -width /dev/tty -compact
159.It Pa /dev/tty
160.El
161.Sh SEE ALSO
162.Xr crypt 3
163.Sh STANDARDS
164The
165.Fn getpass
166function appeared in
167.St -susv2 ,
168but it was already marked as legacy.
169The function was removed in the
170.St -p1003.1-2001
171standard.
172.Sh HISTORY
173A
174.Fn getpass
175function appeared in
176.At v7 .
177The
178.Fn getpass_r
179and
180.Fn getpassfd
181functions appeared in
182.Nx 7.0 .
183.Sh BUGS
184The
185.Fn getpass
186function leaves its result in an internal static object and returns
187a pointer to that object.
188Subsequent calls to
189.Fn getpass
190will modify the same object.
191.Sh SECURITY CONSIDERATIONS
192The calling process should zero the password as soon as possible to
193avoid leaving the cleartext password visible in the process's address
194space.
195.Pp
196Historically
197.Nm
198accepted and returned a password if it could not modify the terminal
199settings to turn echo off (or if the input was not a terminal).
200In this implementation, only terminal input is accepted.
201