]> git.ipfire.org Git - thirdparty/man-pages.git/blob - man3/err.3
Put SEE ALSO section into alphabetical order.
[thirdparty/man-pages.git] / man3 / err.3
1 .\" Copyright (c) 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. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\" From: @(#)err.3 8.1 (Berkeley) 6/9/93
33 .\" $FreeBSD: src/lib/libc/gen/err.3,v 1.11.2.5 2001/08/17 15:42:32 ru Exp $
34 .\"
35 .\" 2007-12-08, mtk, Converted from mdoc to man macros
36 .\"
37 .TH ERR 3 2007-12-28 "Linux" "Linux Programmer's Manual"
38 .SH NAME
39 err, verr, errx, verrx, warn, vwarn, warnx, vwarnx \- formatted error messages
40 .SH SYNOPSIS
41 .nf
42 .B #include <err.h>
43 .sp
44 .BI "void err(int " eval ", const char *" fmt ", ...);"
45 .sp
46 .BI "void errx(int " eval ", const char *" fmt ", ...);"
47 .sp
48 .BI "void warn(const char *" fmt ", ...);"
49 .sp
50 .BI "void warnx(const char *" fmt ", ...);"
51 .sp
52 .B #include <stdarg.h>
53 .sp
54 .BI "void verr(int " eval ", const char *" fmt ", va_list " args );
55 .sp
56 .BI "void verrx(int " eval ", const char *" fmt ", va_list " args );
57 .sp
58 .BI "void vwarn(const char *" fmt ", va_list " args );
59 .sp
60 .BI "void vwarnx(const char *" fmt ", va_list " args );
61 .fi
62 .SH DESCRIPTION
63 The
64 .BR err ()
65 and
66 .BR warn ()
67 family of functions display a formatted error message on the standard
68 error output.
69 In all cases, the last component of the program name, a colon character,
70 and a space are output.
71 If the
72 .I fmt
73 argument is not NULL, the
74 .BR printf (3)-like
75 formatted error message is output.
76 The output is terminated by a newline character.
77 .PP
78 The
79 .BR err (),
80 .BR verr (),
81 .BR warn (),
82 and
83 .BR vwarn ()
84 functions append an error message obtained from
85 .BR strerror (3)
86 based on a code or the global variable
87 .IR errno ,
88 preceded by another colon and space unless the
89 .I fmt
90 argument is
91 NULL.
92 .PP
93 The
94 .BR err (),
95 .BR verr (),
96 .BR warn (),
97 and
98 .BR vwarn ()
99 functions use the global variable
100 .I errno
101 to look up the error message.
102 .PP
103 The
104 .BR errx ()
105 and
106 .BR warnx ()
107 functions do not append an error message.
108 .PP
109 The
110 .BR err (),
111 .BR verr (),
112 .BR errx (),
113 and
114 .BR verrx ()
115 functions do not return, but exit with the value of the argument
116 .IR eval .
117 .SH EXAMPLES
118 Display the current errno information string and exit:
119 .in +4n
120 .nf
121
122 if ((p = malloc(size)) == NULL)
123 err(1, NULL);
124 if ((fd = open(file_name, O_RDONLY, 0)) == \-1)
125 err(1, "%s", file_name);
126 .fi
127 .in
128 .PP
129 Display an error message and exit:
130 .in +4n
131 .nf
132
133 if (tm.tm_hour < START_TIME)
134 errx(1, "too early, wait until %s", start_time_string);
135 .fi
136 .in
137 .PP
138 Warn of an error:
139 .in +4n
140 .nf
141
142 if ((fd = open(raw_device, O_RDONLY, 0)) == \-1)
143 warnx("%s: %s: trying the block device",
144 raw_device, strerror(errno));
145 if ((fd = open(block_device, O_RDONLY, 0)) == \-1)
146 err(1, "%s", block_device);
147 .fi
148 .in
149 .SH "CONFORMING TO"
150 These functions are non-standard BSD extensions.
151 .\" .SH HISTORY
152 .\" The
153 .\" .BR err ()
154 .\" and
155 .\" .BR warn ()
156 .\" functions first appeared in
157 .\" 4.4BSD.
158 .SH SEE ALSO
159 .BR error (3),
160 .BR exit (3),
161 .BR perror (3),
162 .BR printf (3),
163 .BR strerror (3)