xref: /netbsd-src/lib/libc/gen/err.3 (revision d710132b4b8ce7f7cccaaf660cb16aa16b4077a0)
1.\" $NetBSD: err.3,v 1.17 2003/04/16 13:34:36 wiz 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. All advertising materials mentioning features or use of this software
15.\"    must display the following acknowledgement:
16.\"	This product includes software developed by the University of
17.\"	California, Berkeley and its contributors.
18.\" 4. Neither the name of the University nor the names of its contributors
19.\"    may be used to endorse or promote products derived from this software
20.\"    without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\"	@(#)err.3	8.1 (Berkeley) 6/9/93
35.\"
36.Dd March 21, 2001
37.Dt ERR 3
38.Os
39.Sh NAME
40.Nm err ,
41.Nm verr ,
42.Nm errx ,
43.Nm verrx ,
44.Nm warn ,
45.Nm vwarn ,
46.Nm warnx ,
47.Nm vwarnx
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 warn "const char *fmt" "..."
63.Ft void
64.Fn vwarn "const char *fmt" "va_list args"
65.Ft void
66.Fn warnx "const char *fmt" "..."
67.Ft void
68.Fn vwarnx "const char *fmt" "va_list args"
69.Sh DESCRIPTION
70The
71.Fn err
72and
73.Fn warn
74family of functions display a formatted error message on the standard
75error output.
76In all cases, the last component of the program name, a colon character,
77and a space are output.
78If the
79.Fa fmt
80argument is not
81.Dv NULL ,
82the formatted error message is output.
83In the case of the
84.Fn err ,
85.Fn verr ,
86.Fn warn ,
87and
88.Fn vwarn
89functions, the error message string affiliated with the current value of
90the global variable
91.Va errno
92is output next, preceded by a colon character and a space if
93.Fa fmt
94is not
95.Dv NULL .
96In all cases, the output is followed by a newline character.
97.Pp
98The
99.Fn err ,
100.Fn verr ,
101.Fn errx ,
102and
103.Fn verrx
104functions do not return, but instead cause the program to terminate
105with the status value given by the argument
106.Fa status .
107It is often appropriate to use the value
108.Dv EXIT_FAILURE ,
109defined in
110.Aq Ar stdlib.h ,
111as the
112.Fa status
113argument given to these functions.
114.Sh EXAMPLES
115Display the current
116.Va errno
117information string and terminate with status indicating failure:
118.Bd -literal -offset indent
119if ((p = malloc(size)) == NULL)
120	err(EXIT_FAILURE, NULL);
121if ((fd = open(file_name, O_RDONLY, 0)) == -1)
122	err(EXIT_FAILURE, "%s", file_name);
123.Ed
124.Pp
125Display an error message and terminate with status indicating failure:
126.Bd -literal -offset indent
127if (tm.tm_hour \*[Lt] START_TIME)
128	errx(EXIT_FAILURE, "too early, wait until %s",
129	    start_time_string);
130.Ed
131.Pp
132Warn of an error:
133.Bd -literal -offset indent
134if ((fd = open(raw_device, O_RDONLY, 0)) == -1)
135	warnx("%s: %s: trying the block device",
136	    raw_device, strerror(errno));
137if ((fd = open(block_device, O_RDONLY, 0)) == -1)
138	warn("%s", block_device);
139.Ed
140.Sh SEE ALSO
141.Xr exit 3 ,
142.Xr getprogname 3 ,
143.Xr strerror 3
144.Sh HISTORY
145The
146.Fn err
147and
148.Fn warn
149functions first appeared in
150.Bx 4.4 .
151.Sh CAVEATS
152It is important never to pass a string with user-supplied data as a
153format without using
154.Ql %s .
155An attacker can put format specifiers in the string to mangle your stack,
156leading to a possible security hole.
157This holds true even if you have built the string
158.Dq by hand
159using a function like
160.Fn snprintf ,
161as the resulting string may still contain user-supplied conversion specifiers
162for later interpolation by the
163.Fn err
164and
165.Fn warn
166functions.
167.Pp
168Always be sure to use the proper secure idiom:
169.Bd -literal -offset indent
170err(1, "%s", string);
171.Ed
172