xref: /dragonfly/lib/libc/gen/getpass.3 (revision dc71b7ab)
1.\" Copyright (c) 1989, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     @(#)getpass.3	8.1 (Berkeley) 6/4/93
29.\" $FreeBSD: src/lib/libc/gen/getpass.3,v 1.6.2.4 2002/06/30 14:01:45 des Exp $
30.\" $DragonFly: src/lib/libc/gen/getpass.3,v 1.3 2007/09/08 20:50:49 swildner Exp $
31.\"
32.Dd June 4, 1993
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 pwd.h
42.In unistd.h
43.Ft char *
44.Fn getpass "const char *prompt"
45.Sh DESCRIPTION
46The
47.Fn getpass
48function displays a prompt to, and reads in a password from,
49.Pa /dev/tty .
50If this file is not accessible,
51.Fn getpass
52displays the prompt on the standard error output and reads from the standard
53input.
54.Pp
55The password may be up to
56.Dv _PASSWORD_LEN
57(currently 128) characters in length.
58Any additional
59characters and the terminating newline character are discarded.
60.Pp
61The
62.Fn getpass
63function turns off character echoing while reading the password.
64.Sh RETURN VALUES
65The
66.Fn getpass
67function returns a pointer to the null terminated password.
68.Sh FILES
69.Bl -tag -width /dev/tty -compact
70.It Pa /dev/tty
71.El
72.Sh SEE ALSO
73.Xr crypt 3 ,
74.Xr readpassphrase 3
75.Sh HISTORY
76A
77.Fn getpass
78function appeared in
79.At v7 .
80.Sh BUGS
81The
82.Fn getpass
83function leaves its result in an internal static object and returns
84a pointer to that object.
85Subsequent calls to
86.Fn getpass
87will modify the same object.
88.Pp
89The calling process should zero the password as soon as possible to
90avoid leaving the cleartext password visible in the process's address
91space.
92.Pp
93Upon receipt of a
94.Dv SIGTSTP ,
95the input buffer will be flushed, so any
96partially typed password must be retyped when the process
97continues.
98