]>
Commit | Line | Data |
---|---|---|
5b2abdfb A |
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. | |
5b2abdfb A |
12 | .\" 4. Neither the name of the University nor the names of its contributors |
13 | .\" may be used to endorse or promote products derived from this software | |
14 | .\" without specific prior written permission. | |
15 | .\" | |
16 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
17 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
18 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
19 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
20 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
21 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
22 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
23 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
24 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
25 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
26 | .\" SUCH DAMAGE. | |
27 | .\" | |
28 | .\" From: @(#)err.3 8.1 (Berkeley) 6/9/93 | |
1f2f436a | 29 | .\" $FreeBSD: src/lib/libc/gen/err.3,v 1.24 2008/10/31 15:14:40 rwatson Exp $ |
5b2abdfb A |
30 | .\" |
31 | .Dd March 6, 1999 | |
32 | .Dt ERR 3 | |
33 | .Os | |
34 | .Sh NAME | |
35 | .Nm err , | |
36 | .Nm verr , | |
37 | .Nm errc , | |
38 | .Nm verrc , | |
39 | .Nm errx , | |
40 | .Nm verrx , | |
41 | .Nm warn , | |
42 | .Nm vwarn , | |
43 | .Nm warnc , | |
44 | .Nm vwarnc , | |
45 | .Nm warnx , | |
46 | .Nm vwarnx , | |
47 | .Nm err_set_exit , | |
48 | .Nm err_set_file | |
49 | .Nd formatted error messages | |
50 | .Sh LIBRARY | |
51 | .Lb libc | |
52 | .Sh SYNOPSIS | |
53 | .In err.h | |
54 | .Ft void | |
55 | .Fn err "int eval" "const char *fmt" "..." | |
56 | .Ft void | |
57 | .Fn err_set_exit "void (*exitf)(int)" | |
58 | .Ft void | |
59 | .Fn err_set_file "void *vfp" | |
60 | .Ft void | |
61 | .Fn errc "int eval" "int code" "const char *fmt" "..." | |
62 | .Ft void | |
63 | .Fn errx "int eval" "const char *fmt" "..." | |
64 | .Ft void | |
65 | .Fn warn "const char *fmt" "..." | |
66 | .Ft void | |
67 | .Fn warnc "int code" "const char *fmt" "..." | |
68 | .Ft void | |
69 | .Fn warnx "const char *fmt" "..." | |
70 | .In stdarg.h | |
71 | .Ft void | |
72 | .Fn verr "int eval" "const char *fmt" "va_list args" | |
73 | .Ft void | |
74 | .Fn verrc "int eval" "int code" "const char *fmt" "va_list args" | |
75 | .Ft void | |
76 | .Fn verrx "int eval" "const char *fmt" "va_list args" | |
77 | .Ft void | |
78 | .Fn vwarn "const char *fmt" "va_list args" | |
79 | .Ft void | |
80 | .Fn vwarnc "int code" "const char *fmt" "va_list args" | |
81 | .Ft void | |
82 | .Fn vwarnx "const char *fmt" "va_list args" | |
83 | .Sh DESCRIPTION | |
84 | The | |
85 | .Fn err | |
86 | and | |
87 | .Fn warn | |
88 | family of functions display a formatted error message on the standard | |
89 | error output, or on another file specified using the | |
90 | .Fn err_set_file | |
91 | function. | |
92 | In all cases, the last component of the program name, a colon character, | |
93 | and a space are output. | |
94 | If the | |
95 | .Fa fmt | |
96 | argument is not NULL, the | |
1f2f436a | 97 | .Xr printf 3 Ns |
5b2abdfb A |
98 | -like formatted error message is output. |
99 | The output is terminated by a newline character. | |
100 | .Pp | |
101 | The | |
102 | .Fn err , | |
103 | .Fn errc , | |
104 | .Fn verr , | |
105 | .Fn verrc , | |
106 | .Fn warn , | |
107 | .Fn warnc , | |
108 | .Fn vwarn , | |
109 | and | |
110 | .Fn vwarnc | |
111 | functions append an error message obtained from | |
112 | .Xr strerror 3 | |
1f2f436a | 113 | based on a supplied error code value or the global variable |
5b2abdfb A |
114 | .Va errno , |
115 | preceded by another colon and space unless the | |
116 | .Fa fmt | |
117 | argument is | |
118 | .Dv NULL . | |
119 | .Pp | |
120 | In the case of the | |
121 | .Fn errc , | |
122 | .Fn verrc , | |
123 | .Fn warnc , | |
124 | and | |
125 | .Fn vwarnc | |
126 | functions, | |
127 | the | |
128 | .Fa code | |
129 | argument is used to look up the error message. | |
130 | .Pp | |
131 | The | |
132 | .Fn err , | |
133 | .Fn verr , | |
134 | .Fn warn , | |
135 | and | |
136 | .Fn vwarn | |
137 | functions use the global variable | |
138 | .Va errno | |
139 | to look up the error message. | |
140 | .Pp | |
141 | The | |
142 | .Fn errx | |
143 | and | |
144 | .Fn warnx | |
145 | functions do not append an error message. | |
146 | .Pp | |
147 | The | |
148 | .Fn err , | |
149 | .Fn verr , | |
150 | .Fn errc , | |
151 | .Fn verrc , | |
152 | .Fn errx , | |
153 | and | |
154 | .Fn verrx | |
155 | functions do not return, but exit with the value of the argument | |
156 | .Fa eval . | |
3d9156a7 A |
157 | It is recommended that the standard values defined in |
158 | .Xr sysexits 3 | |
159 | be used for the value of | |
160 | .Fa eval . | |
5b2abdfb A |
161 | The |
162 | .Fn err_set_exit | |
163 | function can be used to specify a function which is called before | |
164 | .Xr exit 3 | |
165 | to perform any necessary cleanup; passing a null function pointer for | |
166 | .Va exitf | |
167 | resets the hook to do nothing. | |
168 | The | |
169 | .Fn err_set_file | |
170 | function sets the output stream used by the other functions. | |
171 | Its | |
172 | .Fa vfp | |
173 | argument must be either a pointer to an open stream | |
174 | (possibly already converted to void *) | |
175 | or a null pointer | |
176 | (in which case the output stream is set to standard error). | |
177 | .Sh EXAMPLES | |
178 | Display the current errno information string and exit: | |
179 | .Bd -literal -offset indent | |
180 | if ((p = malloc(size)) == NULL) | |
1f2f436a | 181 | err(EX_OSERR, NULL); |
5b2abdfb | 182 | if ((fd = open(file_name, O_RDONLY, 0)) == -1) |
1f2f436a | 183 | err(EX_NOINPUT, "%s", file_name); |
5b2abdfb A |
184 | .Ed |
185 | .Pp | |
186 | Display an error message and exit: | |
187 | .Bd -literal -offset indent | |
188 | if (tm.tm_hour < START_TIME) | |
1f2f436a A |
189 | errx(EX_DATAERR, "too early, wait until %s", |
190 | start_time_string); | |
5b2abdfb A |
191 | .Ed |
192 | .Pp | |
193 | Warn of an error: | |
194 | .Bd -literal -offset indent | |
195 | if ((fd = open(raw_device, O_RDONLY, 0)) == -1) | |
196 | warnx("%s: %s: trying the block device", | |
197 | raw_device, strerror(errno)); | |
198 | if ((fd = open(block_device, O_RDONLY, 0)) == -1) | |
1f2f436a | 199 | err(EX_OSFILE, "%s", block_device); |
5b2abdfb A |
200 | .Ed |
201 | .Pp | |
202 | Warn of an error without using the global variable | |
203 | .Va errno : | |
204 | .Bd -literal -offset indent | |
205 | error = my_function(); /* returns a value from <errno.h> */ | |
206 | if (error != 0) | |
207 | warnc(error, "my_function"); | |
208 | .Ed | |
209 | .Sh SEE ALSO | |
210 | .Xr exit 3 , | |
9385eb3d | 211 | .Xr fmtmsg 3 , |
5b2abdfb | 212 | .Xr printf 3 , |
3d9156a7 A |
213 | .Xr strerror 3 , |
214 | .Xr sysexits 3 | |
5b2abdfb A |
215 | .Sh HISTORY |
216 | The | |
217 | .Fn err | |
218 | and | |
219 | .Fn warn | |
220 | functions first appeared in | |
221 | .Bx 4.4 . | |
222 | The | |
223 | .Fn err_set_exit | |
224 | and | |
225 | .Fn err_set_file | |
226 | functions first appeared in | |
227 | .Fx 2.1 . | |
228 | The | |
229 | .Fn errc | |
230 | and | |
231 | .Fn warnc | |
232 | functions first appeared in | |
233 | .Fx 3.0 . |