Add a missing '-width' in various manpages' lists.
[dragonfly.git] / lib / libc / gen / readpassphrase.3
CommitLineData
984263bc
MD
1.\" $OpenBSD: readpassphrase.3,v 1.7 2001/12/15 15:37:51 millert Exp $
2.\"
3.\" Copyright (c) 2000 Todd C. Miller <Todd.Miller@courtesan.com>
4.\" 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. The name of the author may not be used to endorse or promote products
15.\" derived from this software without specific prior written permission.
16.\"
17.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
18.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
19.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
20.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
21.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
22.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
23.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
24.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
25.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
26.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27.\"
28.\" $FreeBSD: src/lib/libc/gen/readpassphrase.3,v 1.4.2.3 2003/03/15 15:11:05 trhodes Exp $
29.\"
30.Dd December 7, 2001
31.Dt READPASSPHRASE 3
32.Os
33.Sh NAME
34.Nm readpassphrase
35.Nd get a passphrase from the user
770899e9
SW
36.Sh LIBRARY
37.Lb libc
984263bc 38.Sh SYNOPSIS
d71cdd9f 39.In sys/types.h
984263bc
MD
40.In readpassphrase.h
41.Ft "char *"
42.Fn readpassphrase "const char *prompt" "char *buf" "size_t bufsiz" "int flags"
43.Sh DESCRIPTION
44The
45.Fn readpassphrase
46function displays a prompt to, and reads in a passphrase from,
47.Pa /dev/tty .
48If this file is inaccessible
49and the
50.Dv RPP_REQUIRE_TTY
51flag is not set,
52.Fn readpassphrase
53displays the prompt on the standard error output and reads from the standard
54input.
55In this case it is generally not possible to turn off echo.
56.Pp
57Up to
58.Fa bufsiz
59\- 1 characters (one is for the
60.Dv NUL )
61are read into the provided buffer
62.Fa buf .
63Any additional
64characters and the terminating newline (or return) character are discarded.
65.Pp
66The
67.Fn readpassphrase
68function
69takes the following optional
70.Fa flags :
71.Pp
72.Bl -tag -width ".Dv RPP_REQUIRE_TTY" -compact
73.It Dv RPP_ECHO_OFF
74turn off echo (default behavior)
75.It Dv RPP_ECHO_ON
76leave echo on
77.It Dv RPP_REQUIRE_TTY
78fail if there is no tty
79.It Dv RPP_FORCELOWER
80force input to lower case
81.It Dv RPP_FORCEUPPER
82force input to upper case
83.It Dv RPP_SEVENBIT
84strip the high bit from input
85.El
86.Pp
87The calling process should zero the passphrase as soon as possible to
88avoid leaving the cleartext passphrase visible in the process's address
89space.
90.Sh RETURN VALUES
91Upon successful completion,
92.Fn readpassphrase
93returns a pointer to the null-terminated passphrase.
94If an error is encountered, the terminal state is restored and
95a
96.Dv NULL
97pointer is returned.
0b84df5c
SW
98.Sh FILES
99.Bl -tag -width ".Pa /dev/tty" -compact
100.It Pa /dev/tty
101.El
102.Sh EXAMPLES
103The following code fragment will read a passphrase from
104.Pa /dev/tty
105into the buffer
106.Fa passbuf .
107.Bd -literal -offset indent
108char passbuf[1024];
109
110\&...
111
112if (readpassphrase("Response: ", passbuf, sizeof(passbuf),
113 RPP_REQUIRE_TTY) == NULL)
114 errx(1, "unable to read passphrase");
115
116if (compare(transform(passbuf), epass) != 0)
117 errx(1, "bad passphrase");
118
119\&...
120
121memset(passbuf, 0, sizeof(passbuf));
122.Ed
984263bc
MD
123.Sh ERRORS
124.Bl -tag -width Er
125.It Bq Er EINTR
126The
127.Fn readpassphrase
128function was interrupted by a signal.
129.It Bq Er EINVAL
130The
131.Fa bufsiz
132argument was zero.
133.It Bq Er EIO
134The process is a member of a background process attempting to read
135from its controlling terminal, the process is ignoring or blocking
136the
137.Dv SIGTTIN
138signal or the process group is orphaned.
139.It Bq Er EMFILE
140The process has already reached its limit for open file descriptors.
141.It Bq Er ENFILE
142The system file table is full.
143.It Bq Er ENOTTY
144There is no controlling terminal and the
145.Dv RPP_REQUIRE_TTY
146flag was specified.
147.El
984263bc
MD
148.Sh SIGNALS
149The
150.Fn readpassphrase
151function
152will catch the following signals:
153.Pp
783d47c4 154.Bl -tag -compact -width ".Dv SIGQUIT"
984263bc
MD
155.It Dv SIGINT
156.It Dv SIGHUP
157.It Dv SIGQUIT
158.It Dv SIGTERM
159.It Dv SIGTSTP
160.It Dv SIGTTIN
161.It Dv SIGTTOU
162.El
163.Pp
164When one of the above signals is intercepted, terminal echo will
165be restored if it had previously been turned off.
166If a signal handler was installed for the signal when
167.Fn readpassphrase
168was called that handler is then executed.
169If no handler was previously installed for the signal then the
170default action is taken as per
171.Xr sigaction 2 .
172.Pp
173The
174.Dv SIGTSTP , SIGTTIN ,
175and
176.Dv SIGTTOU
177signals (stop signal generated from keyboard or due to terminal I/O
178from a background process) are treated specially.
179When the process is resumed after it has been stopped,
180.Fn readpassphrase
181will reprint the prompt and the user may then enter a passphrase.
984263bc
MD
182.Sh SEE ALSO
183.Xr sigaction 2 ,
184.Xr getpass 3
185.Sh STANDARDS
186The
187.Fn readpassphrase
188function is an
189extension and should not be used if portability is desired.
190.Sh HISTORY
191The
192.Fn readpassphrase
193function first appeared in
194.Ox 2.9 .