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 the current monitor if we have one, else stderr: 31 * error_report_err(err); 32 * This frees the error object. 33 * 34 * Likewise, but 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_prepend(errp, err); 56 * 57 * Avoid 58 * error_propagate(errp, err); 59 * error_prepend(errp, "Could not frobnicate '%s': ", name); 60 * because this fails to prepend when @errp is &error_fatal. 61 * 62 * Create a new error and pass it to the caller: 63 * error_setg(errp, "situation normal, all fouled up"); 64 * 65 * Call a function and receive an error from it: 66 * Error *err = NULL; 67 * foo(arg, &err); 68 * if (err) { 69 * handle the error... 70 * } 71 * 72 * Call a function ignoring errors: 73 * foo(arg, NULL); 74 * 75 * Call a function aborting on errors: 76 * foo(arg, &error_abort); 77 * 78 * Call a function treating errors as fatal: 79 * foo(arg, &error_fatal); 80 * 81 * Receive an error and pass it on to the caller: 82 * Error *err = NULL; 83 * foo(arg, &err); 84 * if (err) { 85 * handle the error... 86 * error_propagate(errp, err); 87 * } 88 * where Error **errp is a parameter, by convention the last one. 89 * 90 * Do *not* "optimize" this to 91 * foo(arg, errp); 92 * if (*errp) { // WRONG! 93 * handle the error... 94 * } 95 * because errp may be NULL! 96 * 97 * But when all you do with the error is pass it on, please use 98 * foo(arg, errp); 99 * for readability. 100 * 101 * Receive and accumulate multiple errors (first one wins): 102 * Error *err = NULL, *local_err = NULL; 103 * foo(arg, &err); 104 * bar(arg, &local_err); 105 * error_propagate(&err, local_err); 106 * if (err) { 107 * handle the error... 108 * } 109 * 110 * Do *not* "optimize" this to 111 * foo(arg, &err); 112 * bar(arg, &err); // WRONG! 113 * if (err) { 114 * handle the error... 115 * } 116 * because this may pass a non-null err to bar(). 117 */ 118 119 #ifndef ERROR_H 120 #define ERROR_H 121 122 #include "qapi/qapi-types-error.h" 123 124 /* 125 * Overall category of an error. 126 * Based on the qapi type QapiErrorClass, but reproduced here for nicer 127 * enum names. 128 */ 129 typedef enum ErrorClass { 130 ERROR_CLASS_GENERIC_ERROR = QAPI_ERROR_CLASS_GENERICERROR, 131 ERROR_CLASS_COMMAND_NOT_FOUND = QAPI_ERROR_CLASS_COMMANDNOTFOUND, 132 ERROR_CLASS_DEVICE_NOT_ACTIVE = QAPI_ERROR_CLASS_DEVICENOTACTIVE, 133 ERROR_CLASS_DEVICE_NOT_FOUND = QAPI_ERROR_CLASS_DEVICENOTFOUND, 134 ERROR_CLASS_KVM_MISSING_CAP = QAPI_ERROR_CLASS_KVMMISSINGCAP, 135 } ErrorClass; 136 137 /* 138 * Get @err's human-readable error message. 139 */ 140 const char *error_get_pretty(const Error *err); 141 142 /* 143 * Get @err's error class. 144 * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is 145 * strongly discouraged. 146 */ 147 ErrorClass error_get_class(const Error *err); 148 149 /* 150 * Create a new error object and assign it to *@errp. 151 * If @errp is NULL, the error is ignored. Don't bother creating one 152 * then. 153 * If @errp is &error_abort, print a suitable message and abort(). 154 * If @errp is &error_fatal, print a suitable message and exit(1). 155 * If @errp is anything else, *@errp must be NULL. 156 * The new error's class is ERROR_CLASS_GENERIC_ERROR, and its 157 * human-readable error message is made from printf-style @fmt, ... 158 * The resulting message should be a single phrase, with no newline or 159 * trailing punctuation. 160 * Please don't error_setg(&error_fatal, ...), use error_report() and 161 * exit(), because that's more obvious. 162 * Likewise, don't error_setg(&error_abort, ...), use assert(). 163 */ 164 #define error_setg(errp, fmt, ...) \ 165 error_setg_internal((errp), __FILE__, __LINE__, __func__, \ 166 (fmt), ## __VA_ARGS__) 167 void error_setg_internal(Error **errp, 168 const char *src, int line, const char *func, 169 const char *fmt, ...) 170 GCC_FMT_ATTR(5, 6); 171 172 /* 173 * Just like error_setg(), with @os_error info added to the message. 174 * If @os_error is non-zero, ": " + strerror(os_error) is appended to 175 * the human-readable error message. 176 * 177 * The value of errno (which usually can get clobbered by almost any 178 * function call) will be preserved. 179 */ 180 #define error_setg_errno(errp, os_error, fmt, ...) \ 181 error_setg_errno_internal((errp), __FILE__, __LINE__, __func__, \ 182 (os_error), (fmt), ## __VA_ARGS__) 183 void error_setg_errno_internal(Error **errp, 184 const char *fname, int line, const char *func, 185 int os_error, const char *fmt, ...) 186 GCC_FMT_ATTR(6, 7); 187 188 #ifdef _WIN32 189 /* 190 * Just like error_setg(), with @win32_error info added to the message. 191 * If @win32_error is non-zero, ": " + g_win32_error_message(win32_err) 192 * is appended to the human-readable error message. 193 */ 194 #define error_setg_win32(errp, win32_err, fmt, ...) \ 195 error_setg_win32_internal((errp), __FILE__, __LINE__, __func__, \ 196 (win32_err), (fmt), ## __VA_ARGS__) 197 void error_setg_win32_internal(Error **errp, 198 const char *src, int line, const char *func, 199 int win32_err, const char *fmt, ...) 200 GCC_FMT_ATTR(6, 7); 201 #endif 202 203 /* 204 * Propagate error object (if any) from @local_err to @dst_errp. 205 * If @local_err is NULL, do nothing (because there's nothing to 206 * propagate). 207 * Else, if @dst_errp is NULL, errors are being ignored. Free the 208 * error object. 209 * Else, if @dst_errp is &error_abort, print a suitable message and 210 * abort(). 211 * Else, if @dst_errp is &error_fatal, print a suitable message and 212 * exit(1). 213 * Else, if @dst_errp already contains an error, ignore this one: free 214 * the error object. 215 * Else, move the error object from @local_err to *@dst_errp. 216 * On return, @local_err is invalid. 217 * Please don't error_propagate(&error_fatal, ...), use 218 * error_report_err() and exit(), because that's more obvious. 219 */ 220 void error_propagate(Error **dst_errp, Error *local_err); 221 222 223 /* 224 * Propagate error object (if any) with some text prepended. 225 * Behaves like 226 * error_prepend(&local_err, fmt, ...); 227 * error_propagate(dst_errp, local_err); 228 */ 229 void error_propagate_prepend(Error **dst_errp, Error *local_err, 230 const char *fmt, ...); 231 232 /* 233 * Prepend some text to @errp's human-readable error message. 234 * The text is made by formatting @fmt, @ap like vprintf(). 235 */ 236 void error_vprepend(Error *const *errp, const char *fmt, va_list ap); 237 238 /* 239 * Prepend some text to @errp's human-readable error message. 240 * The text is made by formatting @fmt, ... like printf(). 241 */ 242 void error_prepend(Error *const *errp, const char *fmt, ...) 243 GCC_FMT_ATTR(2, 3); 244 245 /* 246 * Append a printf-style human-readable explanation to an existing error. 247 * If the error is later reported to a human user with 248 * error_report_err() or warn_report_err(), the hints will be shown, 249 * too. If it's reported via QMP, the hints will be ignored. 250 * Intended use is adding helpful hints on the human user interface, 251 * e.g. a list of valid values. It's not for clarifying a confusing 252 * error message. 253 * @errp may be NULL, but not &error_fatal or &error_abort. 254 * Trivially the case if you call it only after error_setg() or 255 * error_propagate(). 256 * May be called multiple times. The resulting hint should end with a 257 * newline. 258 */ 259 void error_append_hint(Error *const *errp, const char *fmt, ...) 260 GCC_FMT_ATTR(2, 3); 261 262 /* 263 * Convenience function to report open() failure. 264 */ 265 #define error_setg_file_open(errp, os_errno, filename) \ 266 error_setg_file_open_internal((errp), __FILE__, __LINE__, __func__, \ 267 (os_errno), (filename)) 268 void error_setg_file_open_internal(Error **errp, 269 const char *src, int line, const char *func, 270 int os_errno, const char *filename); 271 272 /* 273 * Return an exact copy of @err. 274 */ 275 Error *error_copy(const Error *err); 276 277 /* 278 * Free @err. 279 * @err may be NULL. 280 */ 281 void error_free(Error *err); 282 283 /* 284 * Convenience function to assert that *@errp is set, then silently free it. 285 */ 286 void error_free_or_abort(Error **errp); 287 288 /* 289 * Convenience function to warn_report() and free @err. 290 * The report includes hints added with error_append_hint(). 291 */ 292 void warn_report_err(Error *err); 293 294 /* 295 * Convenience function to error_report() and free @err. 296 * The report includes hints added with error_append_hint(). 297 */ 298 void error_report_err(Error *err); 299 300 /* 301 * Convenience function to error_prepend(), warn_report() and free @err. 302 */ 303 void warn_reportf_err(Error *err, const char *fmt, ...) 304 GCC_FMT_ATTR(2, 3); 305 306 /* 307 * Convenience function to error_prepend(), error_report() and free @err. 308 */ 309 void error_reportf_err(Error *err, const char *fmt, ...) 310 GCC_FMT_ATTR(2, 3); 311 312 /* 313 * Just like error_setg(), except you get to specify the error class. 314 * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is 315 * strongly discouraged. 316 */ 317 #define error_set(errp, err_class, fmt, ...) \ 318 error_set_internal((errp), __FILE__, __LINE__, __func__, \ 319 (err_class), (fmt), ## __VA_ARGS__) 320 void error_set_internal(Error **errp, 321 const char *src, int line, const char *func, 322 ErrorClass err_class, const char *fmt, ...) 323 GCC_FMT_ATTR(6, 7); 324 325 /* 326 * Special error destination to abort on error. 327 * See error_setg() and error_propagate() for details. 328 */ 329 extern Error *error_abort; 330 331 /* 332 * Special error destination to exit(1) on error. 333 * See error_setg() and error_propagate() for details. 334 */ 335 extern Error *error_fatal; 336 337 #endif 338