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(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 * Please don't error_setg(&error_fatal, ...), use error_report() and 166 * exit(), because that's more obvious. 167 * Likewise, don't error_setg(&error_abort, ...), use assert(). 168 */ 169 #define error_setg(errp, fmt, ...) \ 170 error_setg_internal((errp), __FILE__, __LINE__, __func__, \ 171 (fmt), ## __VA_ARGS__) 172 void error_setg_internal(Error **errp, 173 const char *src, int line, const char *func, 174 const char *fmt, ...) 175 GCC_FMT_ATTR(5, 6); 176 177 /* 178 * Just like error_setg(), with @os_error info added to the message. 179 * If @os_error is non-zero, ": " + strerror(os_error) is appended to 180 * the human-readable error message. 181 */ 182 #define error_setg_errno(errp, os_error, fmt, ...) \ 183 error_setg_errno_internal((errp), __FILE__, __LINE__, __func__, \ 184 (os_error), (fmt), ## __VA_ARGS__) 185 void error_setg_errno_internal(Error **errp, 186 const char *fname, int line, const char *func, 187 int os_error, const char *fmt, ...) 188 GCC_FMT_ATTR(6, 7); 189 190 #ifdef _WIN32 191 /* 192 * Just like error_setg(), with @win32_error info added to the message. 193 * If @win32_error is non-zero, ": " + g_win32_error_message(win32_err) 194 * is appended to the human-readable error message. 195 */ 196 #define error_setg_win32(errp, win32_err, fmt, ...) \ 197 error_setg_win32_internal((errp), __FILE__, __LINE__, __func__, \ 198 (win32_err), (fmt), ## __VA_ARGS__) 199 void error_setg_win32_internal(Error **errp, 200 const char *src, int line, const char *func, 201 int win32_err, const char *fmt, ...) 202 GCC_FMT_ATTR(6, 7); 203 #endif 204 205 /* 206 * Propagate error object (if any) from @local_err to @dst_errp. 207 * If @local_err is NULL, do nothing (because there's nothing to 208 * propagate). 209 * Else, if @dst_errp is NULL, errors are being ignored. Free the 210 * error object. 211 * Else, if @dst_errp is &error_abort, print a suitable message and 212 * abort(). 213 * Else, if @dst_errp is &error_fatal, print a suitable message and 214 * exit(1). 215 * Else, if @dst_errp already contains an error, ignore this one: free 216 * the error object. 217 * Else, move the error object from @local_err to *@dst_errp. 218 * On return, @local_err is invalid. 219 * Please don't error_propagate(&error_fatal, ...), use 220 * error_report_err() and exit(), because that's more obvious. 221 */ 222 void error_propagate(Error **dst_errp, Error *local_err); 223 224 /* 225 * Prepend some text to @errp's human-readable error message. 226 * The text is made by formatting @fmt, @ap like vprintf(). 227 */ 228 void error_vprepend(Error **errp, const char *fmt, va_list ap); 229 230 /* 231 * Prepend some text to @errp's human-readable error message. 232 * The text is made by formatting @fmt, ... like printf(). 233 */ 234 void error_prepend(Error **errp, const char *fmt, ...) 235 GCC_FMT_ATTR(2, 3); 236 237 /* 238 * Append a printf-style human-readable explanation to an existing error. 239 * @errp may be NULL, but not &error_fatal or &error_abort. 240 * Trivially the case if you call it only after error_setg() or 241 * error_propagate(). 242 * May be called multiple times. The resulting hint should end with a 243 * newline. 244 */ 245 void error_append_hint(Error **errp, const char *fmt, ...) 246 GCC_FMT_ATTR(2, 3); 247 248 /* 249 * Convenience function to report open() failure. 250 */ 251 #define error_setg_file_open(errp, os_errno, filename) \ 252 error_setg_file_open_internal((errp), __FILE__, __LINE__, __func__, \ 253 (os_errno), (filename)) 254 void error_setg_file_open_internal(Error **errp, 255 const char *src, int line, const char *func, 256 int os_errno, const char *filename); 257 258 /* 259 * Return an exact copy of @err. 260 */ 261 Error *error_copy(const Error *err); 262 263 /* 264 * Free @err. 265 * @err may be NULL. 266 */ 267 void error_free(Error *err); 268 269 /* 270 * Convenience function to assert that *@errp is set, then silently free it. 271 */ 272 void error_free_or_abort(Error **errp); 273 274 /* 275 * Convenience function to error_report() and free @err. 276 */ 277 void error_report_err(Error *err); 278 279 /* 280 * Convenience function to error_prepend(), error_report() and free @err. 281 */ 282 void error_reportf_err(Error *err, const char *fmt, ...) 283 GCC_FMT_ATTR(2, 3); 284 285 /* 286 * Just like error_setg(), except you get to specify the error class. 287 * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is 288 * strongly discouraged. 289 */ 290 #define error_set(errp, err_class, fmt, ...) \ 291 error_set_internal((errp), __FILE__, __LINE__, __func__, \ 292 (err_class), (fmt), ## __VA_ARGS__) 293 void error_set_internal(Error **errp, 294 const char *src, int line, const char *func, 295 ErrorClass err_class, const char *fmt, ...) 296 GCC_FMT_ATTR(6, 7); 297 298 /* 299 * Special error destination to abort on error. 300 * See error_setg() and error_propagate() for details. 301 */ 302 extern Error *error_abort; 303 304 /* 305 * Special error destination to exit(1) on error. 306 * See error_setg() and error_propagate() for details. 307 */ 308 extern Error *error_fatal; 309 310 #endif 311