1.\" $OpenBSD: getpass.3,v 1.11 2003/06/02 20:18:34 millert 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.Dd December 7, 2001 31.Dt GETPASS 3 32.Os 33.Sh NAME 34.Nm getpass 35.Nd get a password 36.Sh SYNOPSIS 37.Fd #include <pwd.h> 38.Fd #include <unistd.h> 39.Ft char * 40.Fn getpass "const char *prompt" 41.Sh DESCRIPTION 42The 43.Fn getpass 44function displays a prompt to, and reads in a password from, 45.Pa /dev/tty . 46If this file is not accessible, 47.Fn getpass 48displays the prompt on the standard error output and reads from the standard 49input. 50.Pp 51The password may be up to 52.Dv _PASSWORD_LEN 53(currently 128, as defined in the 54.Aq Pa pwd.h 55include file) 56characters in length. 57Any additional 58characters and the terminating newline character are discarded. 59.Pp 60.Fn getpass 61turns off character echoing while reading the password. 62.Pp 63The calling process should zero the password as soon as possible to 64avoid leaving the cleartext password visible in the process's address 65space. 66.Sh RETURN VALUES 67Upon successful completion, 68.Fn getpass 69returns a pointer to a null-terminated string of at most 70.Dv _PASSWORD_LEN 71characters. 72If an error is encountered, the terminal state is restored and 73a null pointer is returned. 74.Sh FILES 75.Bl -tag -width /dev/tty -compact 76.It Pa /dev/tty 77.El 78.Sh ERRORS 79.Bl -tag -width Er 80.It Bq Er EINTR 81The 82.Fn getpass 83function was interrupted by a signal. 84.It Bq Er EIO 85The process is a member of a background process attempting to read 86from its controlling terminal, the process is ignoring or blocking 87the SIGTTIN signal or the process group is orphaned. 88.It Bq Er EMFILE 89The process has already reached its limit for open file descriptors. 90.It Bq Er ENFILE 91The system file table is full. 92.El 93.Sh SEE ALSO 94.Xr crypt 3 , 95.Xr readpassphrase 3 96.Sh STANDARDS 97Historically, 98.Bx 99versions of 100.Fn getpass 101have accepted a password on the standard input if 102.Pa /dev/tty 103is unavailable. 104This contradicts 105.St -xpg4.2 106but the 107.Ox 108implementation is conformant in all other respects. 109.Sh HISTORY 110A 111.Fn getpass 112function appeared in 113.At v7 . 114.Sh BUGS 115The 116.Fn getpass 117function leaves its result in an internal static object and returns 118a pointer to that object. 119Subsequent calls to 120.Fn getpass 121will modify the same object. 122