1.\" $NetBSD: err.3,v 1.21 2014/01/16 17:21:38 christos 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.\"	@(#)err.3	8.1 (Berkeley) 6/9/93
31.\"
32.Dd January 16, 2014
33.Dt ERR 3
34.Os
35.Sh NAME
36.Nm err ,
37.Nm verr ,
38.Nm errx ,
39.Nm verrx ,
40.Nm errc ,
41.Nm verrc ,
42.Nm warn ,
43.Nm vwarn ,
44.Nm warnx ,
45.Nm vwarnx ,
46.Nm warnc ,
47.Nm vwarnc
48.Nd formatted error messages
49.Sh LIBRARY
50.Lb libc
51.Sh SYNOPSIS
52.In err.h
53.Ft void
54.Fn err "int status" "const char *fmt" "..."
55.Ft void
56.Fn verr "int status" "const char *fmt" "va_list args"
57.Ft void
58.Fn errx "int status" "const char *fmt" "..."
59.Ft void
60.Fn verrx "int status" "const char *fmt" "va_list args"
61.Ft void
62.Fn errc "int status" "int code" "const char *fmt" "..."
63.Ft void
64.Fn verrc "int status" "int code" "const char *fmt" "va_list args"
65.Ft void
66.Fn warn "const char *fmt" "..."
67.Ft void
68.Fn vwarn "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.Ft void
74.Fn warnc "int code" "const char *fmt" "..."
75.Ft void
76.Fn vwarnc "int code" "const char *fmt" "va_list args"
77.Sh DESCRIPTION
78The
79.Fn err
80and
81.Fn warn
82family of functions display a formatted error message on the standard
83error output.
84In all cases, the last component of the program name, a colon character,
85and a space are output.
86If the
87.Fa fmt
88argument is not
89.Dv NULL ,
90the formatted error message is output.
91In the case of the
92.Fn err ,
93.Fn verr ,
94.Fn warn ,
95and
96.Fn vwarn
97functions, the error message string affiliated with the current value of
98the global variable
99.Va errno
100is output next, preceded by a colon character and a space if
101.Fa fmt
102is not
103.Dv NULL .
104In all cases, the output is followed by a newline character.
105The
106.Fn errc ,
107.Fn verrc ,
108.Fn warnc ,
109and
110.Fn vwarnc
111functions take an additional
112.Ar code
113argument to be used as the error number instead of using the global
114.Va errno
115variable.
116The
117.Fn errx ,
118.Fn verrx ,
119.Fn warnx ,
120and
121.Fn vwarnx
122functions will not output this error message string.
123.Pp
124The
125.Fn err ,
126.Fn verr ,
127.Fn errx ,
128and
129.Fn verrx
130functions do not return, but instead cause the program to terminate
131with the status value given by the argument
132.Fa status .
133It is often appropriate to use the value
134.Dv EXIT_FAILURE ,
135defined in
136.In stdlib.h ,
137as the
138.Fa status
139argument given to these functions.
140.Sh EXAMPLES
141Display the current
142.Va errno
143information string and terminate with status indicating failure:
144.Bd -literal -offset indent
145if ((p = malloc(size)) == NULL)
146	err(EXIT_FAILURE, NULL);
147if ((fd = open(file_name, O_RDONLY, 0)) == -1)
148	err(EXIT_FAILURE, "%s", file_name);
149.Ed
150.Pp
151Display an error message and terminate with status indicating failure:
152.Bd -literal -offset indent
153if (tm.tm_hour \*[Lt] START_TIME)
154	errx(EXIT_FAILURE, "too early, wait until %s",
155	    start_time_string);
156.Ed
157.Pp
158Warn of an error:
159.Bd -literal -offset indent
160if ((fd = open(raw_device, O_RDONLY, 0)) == -1)
161	warnx("%s: %s: trying the block device",
162	    raw_device, strerror(errno));
163if ((fd = open(block_device, O_RDONLY, 0)) == -1)
164	warn("%s", block_device);
165.Ed
166.Sh SEE ALSO
167.Xr exit 3 ,
168.Xr getprogname 3 ,
169.Xr strerror 3
170.Sh HISTORY
171The
172.Fn err
173and
174.Fn warn
175functions first appeared in
176.Bx 4.4 .
177The
178.Fn errc
179and
180.Fn warnc
181functions first appeared in
182.Fx 3.0
183and
184.Nx 7.0 .
185.Sh CAVEATS
186It is important never to pass a string with user-supplied data as a
187format without using
188.Ql %s .
189An attacker can put format specifiers in the string to mangle your stack,
190leading to a possible security hole.
191This holds true even if you have built the string
192.Dq by hand
193using a function like
194.Fn snprintf ,
195as the resulting string may still contain user-supplied conversion specifiers
196for later interpolation by the
197.Fn err
198and
199.Fn warn
200functions.
201.Pp
202Always be sure to use the proper secure idiom:
203.Bd -literal -offset indent
204err(1, "%s", string);
205.Ed
206