xref: /openbsd/lib/libc/gen/err.3 (revision 76d0caae) 
1.\"	$OpenBSD: err.3,v 1.22 2021/10/24 21:24:20 deraadt Exp $
2.\"
3.\" Copyright (c) 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 $Mdocdate: October 24 2021 $
31.Dt ERR 3
32.Os
33.Sh NAME
34.Nm err ,
35.Nm verr ,
36.Nm errc ,
37.Nm verrc ,
38.Nm errx ,
39.Nm verrx ,
40.Nm warn ,
41.Nm vwarn ,
42.Nm warnc ,
43.Nm vwarnc ,
44.Nm warnx ,
45.Nm vwarnx
46.Nd formatted error messages
47.Sh SYNOPSIS
48.In err.h
49.Ft void
50.Fn err "int eval" "const char *fmt" "..."
51.Ft void
52.Fn verr "int eval" "const char *fmt" "va_list args"
53.Ft void
54.Fn errc "int eval" "int code" "const char *fmt" "..."
55.Ft void
56.Fn verrc "int eval" "int code" "const char *fmt" "va_list args"
57.Ft void
58.Fn errx "int eval" "const char *fmt" "..."
59.Ft void
60.Fn verrx "int eval" "const char *fmt" "va_list args"
61.Ft void
62.Fn warn "const char *fmt" "..."
63.Ft void
64.Fn vwarn "const char *fmt" "va_list args"
65.Ft void
66.Fn warnc "int code" "const char *fmt" "..."
67.Ft void
68.Fn vwarnc "int code" "const char *fmt" "va_list args"
69.Ft void
70.Fn warnx "const char *fmt" "..."
71.Ft void
72.Fn vwarnx "const char *fmt" "va_list args"
73.Sh DESCRIPTION
74The
75.Fn err
76and
77.Fn warn
78family of functions display a formatted error message on the standard
79error output.
80In all cases, the last component of the program name, followed by
81a colon
82.Pq Sq \&:
83character and a space, are output.
84The text that follows depends on the function being called.
85The
86.Fa fmt
87specification (and associated arguments) may be any format allowed by
88.Xr printf 3
89or
90.Dv NULL .
91If the
92.Fa fmt
93argument is not
94.Dv NULL ,
95the formatted error message is output.
96.Pp
97In the case of the
98.Fn errx ,
99.Fn verrx ,
100.Fn warnx ,
101and
102.Fn vwarnx
103functions only, no additional text is output,
104so the output looks like the following:
105.Bd -literal -offset indent
106progname: fmt
107.Ed
108.Pp
109The other functions all output an error message string affiliated with
110an error value (see
111.Xr strerror 3 ) ,
112preceded by a colon character and a space if
113.Fa fmt
114is not
115.Dv NULL .
116That is, the output is as follows:
117.Bd -literal -offset indent
118progname: fmt: error message string
119.Ed
120.Pp
121if
122.Fa fmt
123is not
124.Dv NULL ,
125or:
126.Bd -literal -offset indent
127progname: error message string
128.Ed
129.Pp
130if it is.
131.Pp
132In the case of the
133.Fn err ,
134.Fn verr ,
135.Fn warn ,
136and
137.Fn vwarn
138functions, the error value used is the current value of the global variable
139.Va errno ,
140while for the
141.Fn errc ,
142.Fn verrc ,
143.Fn warnc ,
144and
145.Fn vwarnc
146function the argument
147.Fa code
148is used.
149.Pp
150In all cases, the output is followed by a newline character.
151.Pp
152The
153.Fn err ,
154.Fn verr ,
155.Fn errc ,
156.Fn verrc ,
157.Fn errx ,
158and
159.Fn verrx
160functions do not return, but exit with the value of the argument
161.Fa eval .
162.Sh EXAMPLES
163Display the current
164.Va errno
165information string and exit:
166.Bd -literal -offset indent
167if ((p = malloc(size)) == NULL)
168	err(1, NULL);
169if ((fd = open(file_name, O_RDONLY)) == -1)
170	err(1, "%s", file_name);
171.Ed
172.Pp
173Display an error message and exit:
174.Bd -literal -offset indent
175if (tm.tm_hour < START_TIME)
176	errx(1, "too early, wait until %s", start_time_string);
177.Ed
178.Pp
179Warn of an error:
180.Bd -literal -offset indent
181if ((fd = open(raw_device, O_RDONLY)) == -1)
182	warnx("%s: %s: trying the block device",
183	    raw_device, strerror(errno));
184if ((fd = open(block_device, O_RDONLY)) == -1)
185	err(1, "%s", block_device);
186.Ed
187.Sh SEE ALSO
188.Xr exit 3 ,
189.Xr perror 3 ,
190.Xr printf 3 ,
191.Xr strerror 3
192.Sh HISTORY
193The functions
194.Fn err ,
195.Fn errx ,
196.Fn verr ,
197.Fn verrx ,
198.Fn warn ,
199.Fn warnx ,
200.Fn vwarn ,
201and
202.Fn vwarnx
203first appeared in
204.Bx 4.4 .
205The functions
206.Fn errc ,
207.Fn verrc ,
208.Fn warnc ,
209and
210.Fn vwarnc
211first appeared in
212.Fx 3.0
213and were ported to
214.Ox 5.6 .
215.Sh CAVEATS
216It is important never to pass a string with user-supplied data as a
217format without using
218.Ql %s .
219An attacker can put format specifiers in the string to mangle the stack,
220leading to a possible security hole.
221This holds true even if the string has been built
222.Dq by hand
223using a function like
224.Fn snprintf ,
225as the resulting string may still contain user-supplied conversion specifiers
226for later interpolation by the
227.Fn err
228and
229.Fn warn
230functions.
231.Pp
232Always be sure to use the proper secure idiom:
233.Bd -literal -offset indent
234err(1, "%s", string);
235.Ed
236.Pp
237On systems other than
238.Ox ,
239the
240.Dv LC_MESSAGES
241.Xr locale 1
242category can cause different strings to be printed instead of the
243normal
244.Xr errno 2
245messages; see CAVEATS in
246.Xr setlocale 3
247for details.
248