]>
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 | * | |
21 | * Report an error to stderr: | |
22 | * error_report_err(err); | |
23 | * This frees the error object. | |
24 | * | |
25 | * Report an error somewhere else: | |
26 | * const char *msg = error_get_pretty(err); | |
27 | * do with msg what needs to be done... | |
28 | * error_free(err); | |
29 | * | |
30 | * Handle an error without reporting it (just for completeness): | |
31 | * error_free(err); | |
32 | * | |
a12a5a1a EB |
33 | * Assert that an expected error occurred, but clean it up without |
34 | * reporting it (primarily useful in testsuites): | |
35 | * error_free_or_abort(&err); | |
36 | * | |
edf6f3b3 MA |
37 | * Pass an existing error to the caller: |
38 | * error_propagate(errp, err); | |
39 | * where Error **errp is a parameter, by convention the last one. | |
40 | * | |
41 | * Create a new error and pass it to the caller: | |
42 | * error_setg(errp, "situation normal, all fouled up"); | |
43 | * | |
44 | * Call a function and receive an error from it: | |
45 | * Error *err = NULL; | |
46 | * foo(arg, &err); | |
47 | * if (err) { | |
48 | * handle the error... | |
49 | * } | |
50 | * | |
51 | * Call a function ignoring errors: | |
52 | * foo(arg, NULL); | |
53 | * | |
54 | * Call a function aborting on errors: | |
55 | * foo(arg, &error_abort); | |
56 | * | |
a29a37b9 MA |
57 | * Call a function treating errors as fatal: |
58 | * foo(arg, &error_fatal); | |
59 | * | |
edf6f3b3 MA |
60 | * Receive an error and pass it on to the caller: |
61 | * Error *err = NULL; | |
62 | * foo(arg, &err); | |
63 | * if (err) { | |
64 | * handle the error... | |
65 | * error_propagate(errp, err); | |
66 | * } | |
67 | * where Error **errp is a parameter, by convention the last one. | |
68 | * | |
69 | * Do *not* "optimize" this to | |
70 | * foo(arg, errp); | |
71 | * if (*errp) { // WRONG! | |
72 | * handle the error... | |
73 | * } | |
74 | * because errp may be NULL! | |
75 | * | |
76 | * But when all you do with the error is pass it on, please use | |
77 | * foo(arg, errp); | |
78 | * for readability. | |
79 | */ | |
80 | ||
d5ec4f27 LC |
81 | #ifndef ERROR_H |
82 | #define ERROR_H | |
83 | ||
1de7afc9 | 84 | #include "qemu/compiler.h" |
13f59ae8 | 85 | #include "qapi-types.h" |
d5ec4f27 LC |
86 | #include <stdbool.h> |
87 | ||
edf6f3b3 MA |
88 | /* |
89 | * Opaque error object. | |
d5ec4f27 LC |
90 | */ |
91 | typedef struct Error Error; | |
92 | ||
f22a28b8 EB |
93 | /* |
94 | * Overall category of an error. | |
95 | * Based on the qapi type QapiErrorClass, but reproduced here for nicer | |
96 | * enum names. | |
97 | */ | |
98 | typedef enum ErrorClass { | |
d20a580b EB |
99 | ERROR_CLASS_GENERIC_ERROR = QAPI_ERROR_CLASS_GENERICERROR, |
100 | ERROR_CLASS_COMMAND_NOT_FOUND = QAPI_ERROR_CLASS_COMMANDNOTFOUND, | |
101 | ERROR_CLASS_DEVICE_ENCRYPTED = QAPI_ERROR_CLASS_DEVICEENCRYPTED, | |
102 | ERROR_CLASS_DEVICE_NOT_ACTIVE = QAPI_ERROR_CLASS_DEVICENOTACTIVE, | |
103 | ERROR_CLASS_DEVICE_NOT_FOUND = QAPI_ERROR_CLASS_DEVICENOTFOUND, | |
104 | ERROR_CLASS_KVM_MISSING_CAP = QAPI_ERROR_CLASS_KVMMISSINGCAP, | |
f22a28b8 EB |
105 | } ErrorClass; |
106 | ||
edf6f3b3 MA |
107 | /* |
108 | * Get @err's human-readable error message. | |
d5ec4f27 | 109 | */ |
edf6f3b3 | 110 | const char *error_get_pretty(Error *err); |
d5ec4f27 | 111 | |
edf6f3b3 MA |
112 | /* |
113 | * Get @err's error class. | |
114 | * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is | |
115 | * strongly discouraged. | |
116 | */ | |
117 | ErrorClass error_get_class(const Error *err); | |
118 | ||
119 | /* | |
120 | * Create a new error object and assign it to *@errp. | |
121 | * If @errp is NULL, the error is ignored. Don't bother creating one | |
122 | * then. | |
123 | * If @errp is &error_abort, print a suitable message and abort(). | |
a29a37b9 | 124 | * If @errp is &error_fatal, print a suitable message and exit(1). |
edf6f3b3 MA |
125 | * If @errp is anything else, *@errp must be NULL. |
126 | * The new error's class is ERROR_CLASS_GENERIC_ERROR, and its | |
127 | * human-readable error message is made from printf-style @fmt, ... | |
128 | */ | |
1e9b65bb MA |
129 | #define error_setg(errp, fmt, ...) \ |
130 | error_setg_internal((errp), __FILE__, __LINE__, __func__, \ | |
131 | (fmt), ## __VA_ARGS__) | |
132 | void error_setg_internal(Error **errp, | |
133 | const char *src, int line, const char *func, | |
134 | const char *fmt, ...) | |
135 | GCC_FMT_ATTR(5, 6); | |
edf6f3b3 MA |
136 | |
137 | /* | |
138 | * Just like error_setg(), with @os_error info added to the message. | |
139 | * If @os_error is non-zero, ": " + strerror(os_error) is appended to | |
140 | * the human-readable error message. | |
680d16dc | 141 | */ |
1e9b65bb MA |
142 | #define error_setg_errno(errp, os_error, fmt, ...) \ |
143 | error_setg_errno_internal((errp), __FILE__, __LINE__, __func__, \ | |
144 | (os_error), (fmt), ## __VA_ARGS__) | |
145 | void error_setg_errno_internal(Error **errp, | |
146 | const char *fname, int line, const char *func, | |
147 | int os_error, const char *fmt, ...) | |
148 | GCC_FMT_ATTR(6, 7); | |
680d16dc | 149 | |
20840d4c | 150 | #ifdef _WIN32 |
edf6f3b3 MA |
151 | /* |
152 | * Just like error_setg(), with @win32_error info added to the message. | |
153 | * If @win32_error is non-zero, ": " + g_win32_error_message(win32_err) | |
154 | * is appended to the human-readable error message. | |
20840d4c | 155 | */ |
1e9b65bb MA |
156 | #define error_setg_win32(errp, win32_err, fmt, ...) \ |
157 | error_setg_win32_internal((errp), __FILE__, __LINE__, __func__, \ | |
158 | (win32_err), (fmt), ## __VA_ARGS__) | |
159 | void error_setg_win32_internal(Error **errp, | |
160 | const char *src, int line, const char *func, | |
161 | int win32_err, const char *fmt, ...) | |
162 | GCC_FMT_ATTR(6, 7); | |
20840d4c TS |
163 | #endif |
164 | ||
edf6f3b3 MA |
165 | /* |
166 | * Propagate error object (if any) from @local_err to @dst_errp. | |
167 | * If @local_err is NULL, do nothing (because there's nothing to | |
168 | * propagate). | |
169 | * Else, if @dst_errp is NULL, errors are being ignored. Free the | |
170 | * error object. | |
171 | * Else, if @dst_errp is &error_abort, print a suitable message and | |
172 | * abort(). | |
a29a37b9 MA |
173 | * Else, if @dst_errp is &error_fatal, print a suitable message and |
174 | * exit(1). | |
edf6f3b3 MA |
175 | * Else, if @dst_errp already contains an error, ignore this one: free |
176 | * the error object. | |
177 | * Else, move the error object from @local_err to *@dst_errp. | |
178 | * On return, @local_err is invalid. | |
75d789f8 | 179 | */ |
edf6f3b3 | 180 | void error_propagate(Error **dst_errp, Error *local_err); |
75d789f8 | 181 | |
50b7b000 EB |
182 | /** |
183 | * Append a printf-style human-readable explanation to an existing error. | |
184 | * May be called multiple times, and safe if @errp is NULL. | |
185 | */ | |
186 | void error_append_hint(Error **errp, const char *fmt, ...) | |
187 | GCC_FMT_ATTR(2, 3); | |
188 | ||
edf6f3b3 MA |
189 | /* |
190 | * Convenience function to report open() failure. | |
54028d75 | 191 | */ |
1e9b65bb MA |
192 | #define error_setg_file_open(errp, os_errno, filename) \ |
193 | error_setg_file_open_internal((errp), __FILE__, __LINE__, __func__, \ | |
194 | (os_errno), (filename)) | |
195 | void error_setg_file_open_internal(Error **errp, | |
196 | const char *src, int line, const char *func, | |
197 | int os_errno, const char *filename); | |
54028d75 | 198 | |
ea25fbca | 199 | /* |
edf6f3b3 | 200 | * Return an exact copy of @err. |
79020cfc LC |
201 | */ |
202 | Error *error_copy(const Error *err); | |
203 | ||
edf6f3b3 MA |
204 | /* |
205 | * Free @err. | |
206 | * @err may be NULL. | |
d5ec4f27 | 207 | */ |
edf6f3b3 | 208 | void error_free(Error *err); |
d5ec4f27 | 209 | |
a12a5a1a EB |
210 | /* |
211 | * Convenience function to assert that *@errp is set, then silently free it. | |
212 | */ | |
213 | void error_free_or_abort(Error **errp); | |
214 | ||
edf6f3b3 MA |
215 | /* |
216 | * Convenience function to error_report() and free @err. | |
2ee2f1e4 MA |
217 | */ |
218 | void error_report_err(Error *); | |
219 | ||
edf6f3b3 MA |
220 | /* |
221 | * Just like error_setg(), except you get to specify the error class. | |
222 | * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is | |
223 | * strongly discouraged. | |
d5ec4f27 | 224 | */ |
1e9b65bb MA |
225 | #define error_set(errp, err_class, fmt, ...) \ |
226 | error_set_internal((errp), __FILE__, __LINE__, __func__, \ | |
227 | (err_class), (fmt), ## __VA_ARGS__) | |
228 | void error_set_internal(Error **errp, | |
229 | const char *src, int line, const char *func, | |
230 | ErrorClass err_class, const char *fmt, ...) | |
231 | GCC_FMT_ATTR(6, 7); | |
d5ec4f27 | 232 | |
edf6f3b3 MA |
233 | /* |
234 | * Pass to error_setg() & friends to abort() on error. | |
5d24ee70 | 235 | */ |
5d24ee70 PC |
236 | extern Error *error_abort; |
237 | ||
a29a37b9 MA |
238 | /* |
239 | * Pass to error_setg() & friends to exit(1) on error. | |
240 | */ | |
241 | extern Error *error_fatal; | |
242 | ||
d5ec4f27 | 243 | #endif |