]>
Commit | Line | Data |
---|---|---|
1 | /* | |
2 | * QEMU Error Objects | |
3 | * | |
4 | * Copyright IBM, Corp. 2011 | |
5 | * Copyright (C) 2011-2015 Red Hat, Inc. | |
6 | * | |
7 | * Authors: | |
8 | * Anthony Liguori <aliguori@us.ibm.com> | |
9 | * Markus Armbruster <armbru@redhat.com> | |
10 | * | |
11 | * This work is licensed under the terms of the GNU LGPL, version 2. See | |
12 | * the COPYING.LIB file in the top-level directory. | |
13 | */ | |
14 | ||
15 | /* | |
16 | * Error reporting system loosely patterned after Glib's GError. | |
17 | * | |
18 | * Create an error: | |
19 | * error_setg(&err, "situation normal, all fouled up"); | |
20 | * | |
21 | * Create an error and add additional explanation: | |
22 | * error_setg(&err, "invalid quark"); | |
23 | * error_append_hint(&err, "Valid quarks are up, down, strange, " | |
24 | * "charm, top, bottom.\n"); | |
25 | * | |
26 | * Do *not* contract this to | |
27 | * error_setg(&err, "invalid quark\n" | |
28 | * "Valid quarks are up, down, strange, charm, top, bottom."); | |
29 | * | |
30 | * Report an error to stderr: | |
31 | * error_report_err(err); | |
32 | * This frees the error object. | |
33 | * | |
34 | * Report an error to stderr with additional text prepended: | |
35 | * error_reportf_err(err, "Could not frobnicate '%s': ", name); | |
36 | * | |
37 | * Report an error somewhere else: | |
38 | * const char *msg = error_get_pretty(err); | |
39 | * do with msg what needs to be done... | |
40 | * error_free(err); | |
41 | * Note that this loses hints added with error_append_hint(). | |
42 | * | |
43 | * Handle an error without reporting it (just for completeness): | |
44 | * error_free(err); | |
45 | * | |
46 | * Assert that an expected error occurred, but clean it up without | |
47 | * reporting it (primarily useful in testsuites): | |
48 | * error_free_or_abort(&err); | |
49 | * | |
50 | * Pass an existing error to the caller: | |
51 | * error_propagate(errp, err); | |
52 | * where Error **errp is a parameter, by convention the last one. | |
53 | * | |
54 | * Pass an existing error to the caller with the message modified: | |
55 | * error_propagate(errp, err); | |
56 | * error_prepend(errp, "Could not frobnicate '%s': ", name); | |
57 | * | |
58 | * Create a new error and pass it to the caller: | |
59 | * error_setg(errp, "situation normal, all fouled up"); | |
60 | * | |
61 | * Call a function and receive an error from it: | |
62 | * Error *err = NULL; | |
63 | * foo(arg, &err); | |
64 | * if (err) { | |
65 | * handle the error... | |
66 | * } | |
67 | * | |
68 | * Call a function ignoring errors: | |
69 | * foo(arg, NULL); | |
70 | * | |
71 | * Call a function aborting on errors: | |
72 | * foo(arg, &error_abort); | |
73 | * | |
74 | * Call a function treating errors as fatal: | |
75 | * foo(arg, &error_fatal); | |
76 | * | |
77 | * Receive an error and pass it on to the caller: | |
78 | * Error *err = NULL; | |
79 | * foo(arg, &err); | |
80 | * if (err) { | |
81 | * handle the error... | |
82 | * error_propagate(errp, err); | |
83 | * } | |
84 | * where Error **errp is a parameter, by convention the last one. | |
85 | * | |
86 | * Do *not* "optimize" this to | |
87 | * foo(arg, errp); | |
88 | * if (*errp) { // WRONG! | |
89 | * handle the error... | |
90 | * } | |
91 | * because errp may be NULL! | |
92 | * | |
93 | * But when all you do with the error is pass it on, please use | |
94 | * foo(arg, errp); | |
95 | * for readability. | |
96 | * | |
97 | * Receive and accumulate multiple errors (first one wins): | |
98 | * Error *err = NULL, *local_err = NULL; | |
99 | * foo(arg, &err); | |
100 | * bar(arg, &local_err); | |
101 | * error_propagate(&err, local_err); | |
102 | * if (err) { | |
103 | * handle the error... | |
104 | * } | |
105 | * | |
106 | * Do *not* "optimize" this to | |
107 | * foo(arg, &err); | |
108 | * bar(arg, &err); // WRONG! | |
109 | * if (err) { | |
110 | * handle the error... | |
111 | * } | |
112 | * because this may pass a non-null err to bar(). | |
113 | */ | |
114 | ||
115 | #ifndef ERROR_H | |
116 | #define ERROR_H | |
117 | ||
118 | #include <stdarg.h> | |
119 | #include <stdbool.h> | |
120 | #include "qemu/compiler.h" | |
121 | #include "qapi-types.h" | |
122 | ||
123 | /* | |
124 | * Opaque error object. | |
125 | */ | |
126 | typedef struct Error Error; | |
127 | ||
128 | /* | |
129 | * Overall category of an error. | |
130 | * Based on the qapi type QapiErrorClass, but reproduced here for nicer | |
131 | * enum names. | |
132 | */ | |
133 | typedef enum ErrorClass { | |
134 | ERROR_CLASS_GENERIC_ERROR = QAPI_ERROR_CLASS_GENERICERROR, | |
135 | ERROR_CLASS_COMMAND_NOT_FOUND = QAPI_ERROR_CLASS_COMMANDNOTFOUND, | |
136 | ERROR_CLASS_DEVICE_ENCRYPTED = QAPI_ERROR_CLASS_DEVICEENCRYPTED, | |
137 | ERROR_CLASS_DEVICE_NOT_ACTIVE = QAPI_ERROR_CLASS_DEVICENOTACTIVE, | |
138 | ERROR_CLASS_DEVICE_NOT_FOUND = QAPI_ERROR_CLASS_DEVICENOTFOUND, | |
139 | ERROR_CLASS_KVM_MISSING_CAP = QAPI_ERROR_CLASS_KVMMISSINGCAP, | |
140 | } ErrorClass; | |
141 | ||
142 | /* | |
143 | * Get @err's human-readable error message. | |
144 | */ | |
145 | const char *error_get_pretty(Error *err); | |
146 | ||
147 | /* | |
148 | * Get @err's error class. | |
149 | * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is | |
150 | * strongly discouraged. | |
151 | */ | |
152 | ErrorClass error_get_class(const Error *err); | |
153 | ||
154 | /* | |
155 | * Create a new error object and assign it to *@errp. | |
156 | * If @errp is NULL, the error is ignored. Don't bother creating one | |
157 | * then. | |
158 | * If @errp is &error_abort, print a suitable message and abort(). | |
159 | * If @errp is &error_fatal, print a suitable message and exit(1). | |
160 | * If @errp is anything else, *@errp must be NULL. | |
161 | * The new error's class is ERROR_CLASS_GENERIC_ERROR, and its | |
162 | * human-readable error message is made from printf-style @fmt, ... | |
163 | * The resulting message should be a single phrase, with no newline or | |
164 | * trailing punctuation. | |
165 | */ | |
166 | #define error_setg(errp, fmt, ...) \ | |
167 | error_setg_internal((errp), __FILE__, __LINE__, __func__, \ | |
168 | (fmt), ## __VA_ARGS__) | |
169 | void error_setg_internal(Error **errp, | |
170 | const char *src, int line, const char *func, | |
171 | const char *fmt, ...) | |
172 | GCC_FMT_ATTR(5, 6); | |
173 | ||
174 | /* | |
175 | * Just like error_setg(), with @os_error info added to the message. | |
176 | * If @os_error is non-zero, ": " + strerror(os_error) is appended to | |
177 | * the human-readable error message. | |
178 | */ | |
179 | #define error_setg_errno(errp, os_error, fmt, ...) \ | |
180 | error_setg_errno_internal((errp), __FILE__, __LINE__, __func__, \ | |
181 | (os_error), (fmt), ## __VA_ARGS__) | |
182 | void error_setg_errno_internal(Error **errp, | |
183 | const char *fname, int line, const char *func, | |
184 | int os_error, const char *fmt, ...) | |
185 | GCC_FMT_ATTR(6, 7); | |
186 | ||
187 | #ifdef _WIN32 | |
188 | /* | |
189 | * Just like error_setg(), with @win32_error info added to the message. | |
190 | * If @win32_error is non-zero, ": " + g_win32_error_message(win32_err) | |
191 | * is appended to the human-readable error message. | |
192 | */ | |
193 | #define error_setg_win32(errp, win32_err, fmt, ...) \ | |
194 | error_setg_win32_internal((errp), __FILE__, __LINE__, __func__, \ | |
195 | (win32_err), (fmt), ## __VA_ARGS__) | |
196 | void error_setg_win32_internal(Error **errp, | |
197 | const char *src, int line, const char *func, | |
198 | int win32_err, const char *fmt, ...) | |
199 | GCC_FMT_ATTR(6, 7); | |
200 | #endif | |
201 | ||
202 | /* | |
203 | * Propagate error object (if any) from @local_err to @dst_errp. | |
204 | * If @local_err is NULL, do nothing (because there's nothing to | |
205 | * propagate). | |
206 | * Else, if @dst_errp is NULL, errors are being ignored. Free the | |
207 | * error object. | |
208 | * Else, if @dst_errp is &error_abort, print a suitable message and | |
209 | * abort(). | |
210 | * Else, if @dst_errp is &error_fatal, print a suitable message and | |
211 | * exit(1). | |
212 | * Else, if @dst_errp already contains an error, ignore this one: free | |
213 | * the error object. | |
214 | * Else, move the error object from @local_err to *@dst_errp. | |
215 | * On return, @local_err is invalid. | |
216 | */ | |
217 | void error_propagate(Error **dst_errp, Error *local_err); | |
218 | ||
219 | /* | |
220 | * Prepend some text to @errp's human-readable error message. | |
221 | * The text is made by formatting @fmt, @ap like vprintf(). | |
222 | */ | |
223 | void error_vprepend(Error **errp, const char *fmt, va_list ap); | |
224 | ||
225 | /* | |
226 | * Prepend some text to @errp's human-readable error message. | |
227 | * The text is made by formatting @fmt, ... like printf(). | |
228 | */ | |
229 | void error_prepend(Error **errp, const char *fmt, ...) | |
230 | GCC_FMT_ATTR(2, 3); | |
231 | ||
232 | /* | |
233 | * Append a printf-style human-readable explanation to an existing error. | |
234 | * @errp may be NULL, but not &error_fatal or &error_abort. | |
235 | * Trivially the case if you call it only after error_setg() or | |
236 | * error_propagate(). | |
237 | * May be called multiple times. The resulting hint should end with a | |
238 | * newline. | |
239 | */ | |
240 | void error_append_hint(Error **errp, const char *fmt, ...) | |
241 | GCC_FMT_ATTR(2, 3); | |
242 | ||
243 | /* | |
244 | * Convenience function to report open() failure. | |
245 | */ | |
246 | #define error_setg_file_open(errp, os_errno, filename) \ | |
247 | error_setg_file_open_internal((errp), __FILE__, __LINE__, __func__, \ | |
248 | (os_errno), (filename)) | |
249 | void error_setg_file_open_internal(Error **errp, | |
250 | const char *src, int line, const char *func, | |
251 | int os_errno, const char *filename); | |
252 | ||
253 | /* | |
254 | * Return an exact copy of @err. | |
255 | */ | |
256 | Error *error_copy(const Error *err); | |
257 | ||
258 | /* | |
259 | * Free @err. | |
260 | * @err may be NULL. | |
261 | */ | |
262 | void error_free(Error *err); | |
263 | ||
264 | /* | |
265 | * Convenience function to assert that *@errp is set, then silently free it. | |
266 | */ | |
267 | void error_free_or_abort(Error **errp); | |
268 | ||
269 | /* | |
270 | * Convenience function to error_report() and free @err. | |
271 | */ | |
272 | void error_report_err(Error *err); | |
273 | ||
274 | /* | |
275 | * Convenience function to error_prepend(), error_report() and free @err. | |
276 | */ | |
277 | void error_reportf_err(Error *err, const char *fmt, ...) | |
278 | GCC_FMT_ATTR(2, 3); | |
279 | ||
280 | /* | |
281 | * Just like error_setg(), except you get to specify the error class. | |
282 | * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is | |
283 | * strongly discouraged. | |
284 | */ | |
285 | #define error_set(errp, err_class, fmt, ...) \ | |
286 | error_set_internal((errp), __FILE__, __LINE__, __func__, \ | |
287 | (err_class), (fmt), ## __VA_ARGS__) | |
288 | void error_set_internal(Error **errp, | |
289 | const char *src, int line, const char *func, | |
290 | ErrorClass err_class, const char *fmt, ...) | |
291 | GCC_FMT_ATTR(6, 7); | |
292 | ||
293 | /* | |
294 | * Pass to error_setg() & friends to abort() on error. | |
295 | */ | |
296 | extern Error *error_abort; | |
297 | ||
298 | /* | |
299 | * Pass to error_setg() & friends to exit(1) on error. | |
300 | */ | |
301 | extern Error *error_fatal; | |
302 | ||
303 | #endif |