]>
Commit | Line | Data |
---|---|---|
d5ec4f27 LC |
1 | /* |
2 | * QEMU Error Objects | |
3 | * | |
4 | * Copyright IBM, Corp. 2011 | |
edf6f3b3 | 5 | * Copyright (C) 2011-2015 Red Hat, Inc. |
d5ec4f27 LC |
6 | * |
7 | * Authors: | |
8 | * Anthony Liguori <aliguori@us.ibm.com> | |
edf6f3b3 | 9 | * Markus Armbruster <armbru@redhat.com> |
d5ec4f27 LC |
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 | */ | |
edf6f3b3 MA |
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 | * | |
f4d0064a MA |
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 | * | |
edf6f3b3 MA |
30 | * Report an error to stderr: |
31 | * error_report_err(err); | |
32 | * This frees the error object. | |
33 | * | |
8277d2aa MA |
34 | * Report an error to stderr with additional text prepended: |
35 | * error_reportf_err(err, "Could not frobnicate '%s': ", name); | |
36 | * | |
edf6f3b3 MA |
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); | |
f4d0064a | 41 | * Note that this loses hints added with error_append_hint(). |
edf6f3b3 MA |
42 | * |
43 | * Handle an error without reporting it (just for completeness): | |
44 | * error_free(err); | |
45 | * | |
a12a5a1a EB |
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 | * | |
edf6f3b3 MA |
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 | * | |
8277d2aa MA |
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 | * | |
edf6f3b3 MA |
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 | * | |
a29a37b9 MA |
74 | * Call a function treating errors as fatal: |
75 | * foo(arg, &error_fatal); | |
76 | * | |
edf6f3b3 MA |
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. | |
8d780f43 MA |
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(). | |
edf6f3b3 MA |
113 | */ |
114 | ||
d5ec4f27 LC |
115 | #ifndef ERROR_H |
116 | #define ERROR_H | |
117 | ||
8277d2aa MA |
118 | #include <stdarg.h> |
119 | #include <stdbool.h> | |
1de7afc9 | 120 | #include "qemu/compiler.h" |
13f59ae8 | 121 | #include "qapi-types.h" |
d5ec4f27 | 122 | |
edf6f3b3 MA |
123 | /* |
124 | * Opaque error object. | |
d5ec4f27 LC |
125 | */ |
126 | typedef struct Error Error; | |
127 | ||
f22a28b8 EB |
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 { | |
d20a580b EB |
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, | |
f22a28b8 EB |
140 | } ErrorClass; |
141 | ||
edf6f3b3 MA |
142 | /* |
143 | * Get @err's human-readable error message. | |
d5ec4f27 | 144 | */ |
edf6f3b3 | 145 | const char *error_get_pretty(Error *err); |
d5ec4f27 | 146 | |
edf6f3b3 MA |
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(). | |
a29a37b9 | 159 | * If @errp is &error_fatal, print a suitable message and exit(1). |
edf6f3b3 MA |
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, ... | |
f4d0064a MA |
163 | * The resulting message should be a single phrase, with no newline or |
164 | * trailing punctuation. | |
edf6f3b3 | 165 | */ |
1e9b65bb MA |
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); | |
edf6f3b3 MA |
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. | |
680d16dc | 178 | */ |
1e9b65bb MA |
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); | |
680d16dc | 186 | |
20840d4c | 187 | #ifdef _WIN32 |
edf6f3b3 MA |
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. | |
20840d4c | 192 | */ |
1e9b65bb MA |
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); | |
20840d4c TS |
200 | #endif |
201 | ||
edf6f3b3 MA |
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(). | |
a29a37b9 MA |
210 | * Else, if @dst_errp is &error_fatal, print a suitable message and |
211 | * exit(1). | |
edf6f3b3 MA |
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. | |
75d789f8 | 216 | */ |
edf6f3b3 | 217 | void error_propagate(Error **dst_errp, Error *local_err); |
75d789f8 | 218 | |
8277d2aa MA |
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 | /* | |
50b7b000 | 233 | * Append a printf-style human-readable explanation to an existing error. |
f4d0064a MA |
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. | |
50b7b000 EB |
239 | */ |
240 | void error_append_hint(Error **errp, const char *fmt, ...) | |
241 | GCC_FMT_ATTR(2, 3); | |
242 | ||
edf6f3b3 MA |
243 | /* |
244 | * Convenience function to report open() failure. | |
54028d75 | 245 | */ |
1e9b65bb MA |
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); | |
54028d75 | 252 | |
ea25fbca | 253 | /* |
edf6f3b3 | 254 | * Return an exact copy of @err. |
79020cfc LC |
255 | */ |
256 | Error *error_copy(const Error *err); | |
257 | ||
edf6f3b3 MA |
258 | /* |
259 | * Free @err. | |
260 | * @err may be NULL. | |
d5ec4f27 | 261 | */ |
edf6f3b3 | 262 | void error_free(Error *err); |
d5ec4f27 | 263 | |
a12a5a1a EB |
264 | /* |
265 | * Convenience function to assert that *@errp is set, then silently free it. | |
266 | */ | |
267 | void error_free_or_abort(Error **errp); | |
268 | ||
edf6f3b3 MA |
269 | /* |
270 | * Convenience function to error_report() and free @err. | |
2ee2f1e4 | 271 | */ |
f4d0064a | 272 | void error_report_err(Error *err); |
2ee2f1e4 | 273 | |
8277d2aa MA |
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 | ||
edf6f3b3 MA |
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. | |
d5ec4f27 | 284 | */ |
1e9b65bb MA |
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); | |
d5ec4f27 | 292 | |
edf6f3b3 MA |
293 | /* |
294 | * Pass to error_setg() & friends to abort() on error. | |
5d24ee70 | 295 | */ |
5d24ee70 PC |
296 | extern Error *error_abort; |
297 | ||
a29a37b9 MA |
298 | /* |
299 | * Pass to error_setg() & friends to exit(1) on error. | |
300 | */ | |
301 | extern Error *error_fatal; | |
302 | ||
d5ec4f27 | 303 | #endif |