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 * 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 * 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 * 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 * 57 * Call a function treating errors as fatal: 58 * foo(arg, &error_fatal); 59 * 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 * Receive and accumulate multiple errors (first one wins): 81 * Error *err = NULL, *local_err = NULL; 82 * foo(arg, &err); 83 * bar(arg, &local_err); 84 * error_propagate(&err, local_err); 85 * if (err) { 86 * handle the error... 87 * } 88 * 89 * Do *not* "optimize" this to 90 * foo(arg, &err); 91 * bar(arg, &err); // WRONG! 92 * if (err) { 93 * handle the error... 94 * } 95 * because this may pass a non-null err to bar(). 96 */ 97 98 #ifndef ERROR_H 99 #define ERROR_H 100 101 #include "qemu/compiler.h" 102 #include "qapi-types.h" 103 #include <stdbool.h> 104 105 /* 106 * Opaque error object. 107 */ 108 typedef struct Error Error; 109 110 /* 111 * Overall category of an error. 112 * Based on the qapi type QapiErrorClass, but reproduced here for nicer 113 * enum names. 114 */ 115 typedef enum ErrorClass { 116 ERROR_CLASS_GENERIC_ERROR = QAPI_ERROR_CLASS_GENERICERROR, 117 ERROR_CLASS_COMMAND_NOT_FOUND = QAPI_ERROR_CLASS_COMMANDNOTFOUND, 118 ERROR_CLASS_DEVICE_ENCRYPTED = QAPI_ERROR_CLASS_DEVICEENCRYPTED, 119 ERROR_CLASS_DEVICE_NOT_ACTIVE = QAPI_ERROR_CLASS_DEVICENOTACTIVE, 120 ERROR_CLASS_DEVICE_NOT_FOUND = QAPI_ERROR_CLASS_DEVICENOTFOUND, 121 ERROR_CLASS_KVM_MISSING_CAP = QAPI_ERROR_CLASS_KVMMISSINGCAP, 122 } ErrorClass; 123 124 /* 125 * Get @err's human-readable error message. 126 */ 127 const char *error_get_pretty(Error *err); 128 129 /* 130 * Get @err's error class. 131 * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is 132 * strongly discouraged. 133 */ 134 ErrorClass error_get_class(const Error *err); 135 136 /* 137 * Create a new error object and assign it to *@errp. 138 * If @errp is NULL, the error is ignored. Don't bother creating one 139 * then. 140 * If @errp is &error_abort, print a suitable message and abort(). 141 * If @errp is &error_fatal, print a suitable message and exit(1). 142 * If @errp is anything else, *@errp must be NULL. 143 * The new error's class is ERROR_CLASS_GENERIC_ERROR, and its 144 * human-readable error message is made from printf-style @fmt, ... 145 */ 146 #define error_setg(errp, fmt, ...) \ 147 error_setg_internal((errp), __FILE__, __LINE__, __func__, \ 148 (fmt), ## __VA_ARGS__) 149 void error_setg_internal(Error **errp, 150 const char *src, int line, const char *func, 151 const char *fmt, ...) 152 GCC_FMT_ATTR(5, 6); 153 154 /* 155 * Just like error_setg(), with @os_error info added to the message. 156 * If @os_error is non-zero, ": " + strerror(os_error) is appended to 157 * the human-readable error message. 158 */ 159 #define error_setg_errno(errp, os_error, fmt, ...) \ 160 error_setg_errno_internal((errp), __FILE__, __LINE__, __func__, \ 161 (os_error), (fmt), ## __VA_ARGS__) 162 void error_setg_errno_internal(Error **errp, 163 const char *fname, int line, const char *func, 164 int os_error, const char *fmt, ...) 165 GCC_FMT_ATTR(6, 7); 166 167 #ifdef _WIN32 168 /* 169 * Just like error_setg(), with @win32_error info added to the message. 170 * If @win32_error is non-zero, ": " + g_win32_error_message(win32_err) 171 * is appended to the human-readable error message. 172 */ 173 #define error_setg_win32(errp, win32_err, fmt, ...) \ 174 error_setg_win32_internal((errp), __FILE__, __LINE__, __func__, \ 175 (win32_err), (fmt), ## __VA_ARGS__) 176 void error_setg_win32_internal(Error **errp, 177 const char *src, int line, const char *func, 178 int win32_err, const char *fmt, ...) 179 GCC_FMT_ATTR(6, 7); 180 #endif 181 182 /* 183 * Propagate error object (if any) from @local_err to @dst_errp. 184 * If @local_err is NULL, do nothing (because there's nothing to 185 * propagate). 186 * Else, if @dst_errp is NULL, errors are being ignored. Free the 187 * error object. 188 * Else, if @dst_errp is &error_abort, print a suitable message and 189 * abort(). 190 * Else, if @dst_errp is &error_fatal, print a suitable message and 191 * exit(1). 192 * Else, if @dst_errp already contains an error, ignore this one: free 193 * the error object. 194 * Else, move the error object from @local_err to *@dst_errp. 195 * On return, @local_err is invalid. 196 */ 197 void error_propagate(Error **dst_errp, Error *local_err); 198 199 /** 200 * Append a printf-style human-readable explanation to an existing error. 201 * May be called multiple times, and safe if @errp is NULL. 202 */ 203 void error_append_hint(Error **errp, const char *fmt, ...) 204 GCC_FMT_ATTR(2, 3); 205 206 /* 207 * Convenience function to report open() failure. 208 */ 209 #define error_setg_file_open(errp, os_errno, filename) \ 210 error_setg_file_open_internal((errp), __FILE__, __LINE__, __func__, \ 211 (os_errno), (filename)) 212 void error_setg_file_open_internal(Error **errp, 213 const char *src, int line, const char *func, 214 int os_errno, const char *filename); 215 216 /* 217 * Return an exact copy of @err. 218 */ 219 Error *error_copy(const Error *err); 220 221 /* 222 * Free @err. 223 * @err may be NULL. 224 */ 225 void error_free(Error *err); 226 227 /* 228 * Convenience function to assert that *@errp is set, then silently free it. 229 */ 230 void error_free_or_abort(Error **errp); 231 232 /* 233 * Convenience function to error_report() and free @err. 234 */ 235 void error_report_err(Error *); 236 237 /* 238 * Just like error_setg(), except you get to specify the error class. 239 * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is 240 * strongly discouraged. 241 */ 242 #define error_set(errp, err_class, fmt, ...) \ 243 error_set_internal((errp), __FILE__, __LINE__, __func__, \ 244 (err_class), (fmt), ## __VA_ARGS__) 245 void error_set_internal(Error **errp, 246 const char *src, int line, const char *func, 247 ErrorClass err_class, const char *fmt, ...) 248 GCC_FMT_ATTR(6, 7); 249 250 /* 251 * Pass to error_setg() & friends to abort() on error. 252 */ 253 extern Error *error_abort; 254 255 /* 256 * Pass to error_setg() & friends to exit(1) on error. 257 */ 258 extern Error *error_fatal; 259 260 #endif 261