]>
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 | * | |
10303f04 | 30 | * Report an error to the current monitor if we have one, else stderr: |
edf6f3b3 MA |
31 | * error_report_err(err); |
32 | * This frees the error object. | |
33 | * | |
10303f04 | 34 | * Likewise, but with additional text prepended: |
8277d2aa MA |
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 | ||
13f59ae8 | 118 | #include "qapi-types.h" |
d5ec4f27 | 119 | |
f22a28b8 EB |
120 | /* |
121 | * Overall category of an error. | |
122 | * Based on the qapi type QapiErrorClass, but reproduced here for nicer | |
123 | * enum names. | |
124 | */ | |
125 | typedef enum ErrorClass { | |
d20a580b EB |
126 | ERROR_CLASS_GENERIC_ERROR = QAPI_ERROR_CLASS_GENERICERROR, |
127 | ERROR_CLASS_COMMAND_NOT_FOUND = QAPI_ERROR_CLASS_COMMANDNOTFOUND, | |
128 | ERROR_CLASS_DEVICE_ENCRYPTED = QAPI_ERROR_CLASS_DEVICEENCRYPTED, | |
129 | ERROR_CLASS_DEVICE_NOT_ACTIVE = QAPI_ERROR_CLASS_DEVICENOTACTIVE, | |
130 | ERROR_CLASS_DEVICE_NOT_FOUND = QAPI_ERROR_CLASS_DEVICENOTFOUND, | |
131 | ERROR_CLASS_KVM_MISSING_CAP = QAPI_ERROR_CLASS_KVMMISSINGCAP, | |
f22a28b8 EB |
132 | } ErrorClass; |
133 | ||
edf6f3b3 MA |
134 | /* |
135 | * Get @err's human-readable error message. | |
d5ec4f27 | 136 | */ |
d59ce6f3 | 137 | const char *error_get_pretty(const Error *err); |
d5ec4f27 | 138 | |
edf6f3b3 MA |
139 | /* |
140 | * Get @err's error class. | |
141 | * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is | |
142 | * strongly discouraged. | |
143 | */ | |
144 | ErrorClass error_get_class(const Error *err); | |
145 | ||
146 | /* | |
147 | * Create a new error object and assign it to *@errp. | |
148 | * If @errp is NULL, the error is ignored. Don't bother creating one | |
149 | * then. | |
150 | * If @errp is &error_abort, print a suitable message and abort(). | |
a29a37b9 | 151 | * If @errp is &error_fatal, print a suitable message and exit(1). |
edf6f3b3 MA |
152 | * If @errp is anything else, *@errp must be NULL. |
153 | * The new error's class is ERROR_CLASS_GENERIC_ERROR, and its | |
154 | * human-readable error message is made from printf-style @fmt, ... | |
f4d0064a MA |
155 | * The resulting message should be a single phrase, with no newline or |
156 | * trailing punctuation. | |
10303f04 MA |
157 | * Please don't error_setg(&error_fatal, ...), use error_report() and |
158 | * exit(), because that's more obvious. | |
159 | * Likewise, don't error_setg(&error_abort, ...), use assert(). | |
edf6f3b3 | 160 | */ |
1e9b65bb MA |
161 | #define error_setg(errp, fmt, ...) \ |
162 | error_setg_internal((errp), __FILE__, __LINE__, __func__, \ | |
163 | (fmt), ## __VA_ARGS__) | |
164 | void error_setg_internal(Error **errp, | |
165 | const char *src, int line, const char *func, | |
166 | const char *fmt, ...) | |
167 | GCC_FMT_ATTR(5, 6); | |
edf6f3b3 MA |
168 | |
169 | /* | |
170 | * Just like error_setg(), with @os_error info added to the message. | |
171 | * If @os_error is non-zero, ": " + strerror(os_error) is appended to | |
172 | * the human-readable error message. | |
680d16dc | 173 | */ |
1e9b65bb MA |
174 | #define error_setg_errno(errp, os_error, fmt, ...) \ |
175 | error_setg_errno_internal((errp), __FILE__, __LINE__, __func__, \ | |
176 | (os_error), (fmt), ## __VA_ARGS__) | |
177 | void error_setg_errno_internal(Error **errp, | |
178 | const char *fname, int line, const char *func, | |
179 | int os_error, const char *fmt, ...) | |
180 | GCC_FMT_ATTR(6, 7); | |
680d16dc | 181 | |
20840d4c | 182 | #ifdef _WIN32 |
edf6f3b3 MA |
183 | /* |
184 | * Just like error_setg(), with @win32_error info added to the message. | |
185 | * If @win32_error is non-zero, ": " + g_win32_error_message(win32_err) | |
186 | * is appended to the human-readable error message. | |
20840d4c | 187 | */ |
1e9b65bb MA |
188 | #define error_setg_win32(errp, win32_err, fmt, ...) \ |
189 | error_setg_win32_internal((errp), __FILE__, __LINE__, __func__, \ | |
190 | (win32_err), (fmt), ## __VA_ARGS__) | |
191 | void error_setg_win32_internal(Error **errp, | |
192 | const char *src, int line, const char *func, | |
193 | int win32_err, const char *fmt, ...) | |
194 | GCC_FMT_ATTR(6, 7); | |
20840d4c TS |
195 | #endif |
196 | ||
edf6f3b3 MA |
197 | /* |
198 | * Propagate error object (if any) from @local_err to @dst_errp. | |
199 | * If @local_err is NULL, do nothing (because there's nothing to | |
200 | * propagate). | |
201 | * Else, if @dst_errp is NULL, errors are being ignored. Free the | |
202 | * error object. | |
203 | * Else, if @dst_errp is &error_abort, print a suitable message and | |
204 | * abort(). | |
a29a37b9 MA |
205 | * Else, if @dst_errp is &error_fatal, print a suitable message and |
206 | * exit(1). | |
edf6f3b3 MA |
207 | * Else, if @dst_errp already contains an error, ignore this one: free |
208 | * the error object. | |
209 | * Else, move the error object from @local_err to *@dst_errp. | |
210 | * On return, @local_err is invalid. | |
10303f04 MA |
211 | * Please don't error_propagate(&error_fatal, ...), use |
212 | * error_report_err() and exit(), because that's more obvious. | |
75d789f8 | 213 | */ |
edf6f3b3 | 214 | void error_propagate(Error **dst_errp, Error *local_err); |
75d789f8 | 215 | |
8277d2aa MA |
216 | /* |
217 | * Prepend some text to @errp's human-readable error message. | |
218 | * The text is made by formatting @fmt, @ap like vprintf(). | |
219 | */ | |
220 | void error_vprepend(Error **errp, const char *fmt, va_list ap); | |
221 | ||
222 | /* | |
223 | * Prepend some text to @errp's human-readable error message. | |
224 | * The text is made by formatting @fmt, ... like printf(). | |
225 | */ | |
226 | void error_prepend(Error **errp, const char *fmt, ...) | |
227 | GCC_FMT_ATTR(2, 3); | |
228 | ||
229 | /* | |
50b7b000 | 230 | * Append a printf-style human-readable explanation to an existing error. |
f4d0064a MA |
231 | * @errp may be NULL, but not &error_fatal or &error_abort. |
232 | * Trivially the case if you call it only after error_setg() or | |
233 | * error_propagate(). | |
234 | * May be called multiple times. The resulting hint should end with a | |
235 | * newline. | |
50b7b000 EB |
236 | */ |
237 | void error_append_hint(Error **errp, const char *fmt, ...) | |
238 | GCC_FMT_ATTR(2, 3); | |
239 | ||
edf6f3b3 MA |
240 | /* |
241 | * Convenience function to report open() failure. | |
54028d75 | 242 | */ |
1e9b65bb MA |
243 | #define error_setg_file_open(errp, os_errno, filename) \ |
244 | error_setg_file_open_internal((errp), __FILE__, __LINE__, __func__, \ | |
245 | (os_errno), (filename)) | |
246 | void error_setg_file_open_internal(Error **errp, | |
247 | const char *src, int line, const char *func, | |
248 | int os_errno, const char *filename); | |
54028d75 | 249 | |
ea25fbca | 250 | /* |
edf6f3b3 | 251 | * Return an exact copy of @err. |
79020cfc LC |
252 | */ |
253 | Error *error_copy(const Error *err); | |
254 | ||
edf6f3b3 MA |
255 | /* |
256 | * Free @err. | |
257 | * @err may be NULL. | |
d5ec4f27 | 258 | */ |
edf6f3b3 | 259 | void error_free(Error *err); |
d5ec4f27 | 260 | |
a12a5a1a EB |
261 | /* |
262 | * Convenience function to assert that *@errp is set, then silently free it. | |
263 | */ | |
264 | void error_free_or_abort(Error **errp); | |
265 | ||
edf6f3b3 MA |
266 | /* |
267 | * Convenience function to error_report() and free @err. | |
2ee2f1e4 | 268 | */ |
f4d0064a | 269 | void error_report_err(Error *err); |
2ee2f1e4 | 270 | |
8277d2aa MA |
271 | /* |
272 | * Convenience function to error_prepend(), error_report() and free @err. | |
273 | */ | |
274 | void error_reportf_err(Error *err, const char *fmt, ...) | |
275 | GCC_FMT_ATTR(2, 3); | |
276 | ||
edf6f3b3 MA |
277 | /* |
278 | * Just like error_setg(), except you get to specify the error class. | |
279 | * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is | |
280 | * strongly discouraged. | |
d5ec4f27 | 281 | */ |
1e9b65bb MA |
282 | #define error_set(errp, err_class, fmt, ...) \ |
283 | error_set_internal((errp), __FILE__, __LINE__, __func__, \ | |
284 | (err_class), (fmt), ## __VA_ARGS__) | |
285 | void error_set_internal(Error **errp, | |
286 | const char *src, int line, const char *func, | |
287 | ErrorClass err_class, const char *fmt, ...) | |
288 | GCC_FMT_ATTR(6, 7); | |
d5ec4f27 | 289 | |
edf6f3b3 | 290 | /* |
10303f04 MA |
291 | * Special error destination to abort on error. |
292 | * See error_setg() and error_propagate() for details. | |
5d24ee70 | 293 | */ |
5d24ee70 PC |
294 | extern Error *error_abort; |
295 | ||
a29a37b9 | 296 | /* |
10303f04 MA |
297 | * Special error destination to exit(1) on error. |
298 | * See error_setg() and error_propagate() for details. | |
a29a37b9 MA |
299 | */ |
300 | extern Error *error_fatal; | |
301 | ||
d5ec4f27 | 302 | #endif |