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 * Pass an existing error to the caller: 34 * error_propagate(errp, err); 35 * where Error **errp is a parameter, by convention the last one. 36 * 37 * Create a new error and pass it to the caller: 38 * error_setg(errp, "situation normal, all fouled up"); 39 * 40 * Call a function and receive an error from it: 41 * Error *err = NULL; 42 * foo(arg, &err); 43 * if (err) { 44 * handle the error... 45 * } 46 * 47 * Call a function ignoring errors: 48 * foo(arg, NULL); 49 * 50 * Call a function aborting on errors: 51 * foo(arg, &error_abort); 52 * 53 * Call a function treating errors as fatal: 54 * foo(arg, &error_fatal); 55 * 56 * Receive an error and pass it on to the caller: 57 * Error *err = NULL; 58 * foo(arg, &err); 59 * if (err) { 60 * handle the error... 61 * error_propagate(errp, err); 62 * } 63 * where Error **errp is a parameter, by convention the last one. 64 * 65 * Do *not* "optimize" this to 66 * foo(arg, errp); 67 * if (*errp) { // WRONG! 68 * handle the error... 69 * } 70 * because errp may be NULL! 71 * 72 * But when all you do with the error is pass it on, please use 73 * foo(arg, errp); 74 * for readability. 75 */ 76 77 #ifndef ERROR_H 78 #define ERROR_H 79 80 #include "qemu/compiler.h" 81 #include "qapi-types.h" 82 #include <stdbool.h> 83 84 /* 85 * Opaque error object. 86 */ 87 typedef struct Error Error; 88 89 /* 90 * Get @err's human-readable error message. 91 */ 92 const char *error_get_pretty(Error *err); 93 94 /* 95 * Get @err's error class. 96 * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is 97 * strongly discouraged. 98 */ 99 ErrorClass error_get_class(const Error *err); 100 101 /* 102 * Create a new error object and assign it to *@errp. 103 * If @errp is NULL, the error is ignored. Don't bother creating one 104 * then. 105 * If @errp is &error_abort, print a suitable message and abort(). 106 * If @errp is &error_fatal, print a suitable message and exit(1). 107 * If @errp is anything else, *@errp must be NULL. 108 * The new error's class is ERROR_CLASS_GENERIC_ERROR, and its 109 * human-readable error message is made from printf-style @fmt, ... 110 */ 111 #define error_setg(errp, fmt, ...) \ 112 error_setg_internal((errp), __FILE__, __LINE__, __func__, \ 113 (fmt), ## __VA_ARGS__) 114 void error_setg_internal(Error **errp, 115 const char *src, int line, const char *func, 116 const char *fmt, ...) 117 GCC_FMT_ATTR(5, 6); 118 119 /* 120 * Just like error_setg(), with @os_error info added to the message. 121 * If @os_error is non-zero, ": " + strerror(os_error) is appended to 122 * the human-readable error message. 123 */ 124 #define error_setg_errno(errp, os_error, fmt, ...) \ 125 error_setg_errno_internal((errp), __FILE__, __LINE__, __func__, \ 126 (os_error), (fmt), ## __VA_ARGS__) 127 void error_setg_errno_internal(Error **errp, 128 const char *fname, int line, const char *func, 129 int os_error, const char *fmt, ...) 130 GCC_FMT_ATTR(6, 7); 131 132 #ifdef _WIN32 133 /* 134 * Just like error_setg(), with @win32_error info added to the message. 135 * If @win32_error is non-zero, ": " + g_win32_error_message(win32_err) 136 * is appended to the human-readable error message. 137 */ 138 #define error_setg_win32(errp, win32_err, fmt, ...) \ 139 error_setg_win32_internal((errp), __FILE__, __LINE__, __func__, \ 140 (win32_err), (fmt), ## __VA_ARGS__) 141 void error_setg_win32_internal(Error **errp, 142 const char *src, int line, const char *func, 143 int win32_err, const char *fmt, ...) 144 GCC_FMT_ATTR(6, 7); 145 #endif 146 147 /* 148 * Propagate error object (if any) from @local_err to @dst_errp. 149 * If @local_err is NULL, do nothing (because there's nothing to 150 * propagate). 151 * Else, if @dst_errp is NULL, errors are being ignored. Free the 152 * error object. 153 * Else, if @dst_errp is &error_abort, print a suitable message and 154 * abort(). 155 * Else, if @dst_errp is &error_fatal, print a suitable message and 156 * exit(1). 157 * Else, if @dst_errp already contains an error, ignore this one: free 158 * the error object. 159 * Else, move the error object from @local_err to *@dst_errp. 160 * On return, @local_err is invalid. 161 */ 162 void error_propagate(Error **dst_errp, Error *local_err); 163 164 /** 165 * Append a printf-style human-readable explanation to an existing error. 166 * May be called multiple times, and safe if @errp is NULL. 167 */ 168 void error_append_hint(Error **errp, const char *fmt, ...) 169 GCC_FMT_ATTR(2, 3); 170 171 /* 172 * Convenience function to report open() failure. 173 */ 174 #define error_setg_file_open(errp, os_errno, filename) \ 175 error_setg_file_open_internal((errp), __FILE__, __LINE__, __func__, \ 176 (os_errno), (filename)) 177 void error_setg_file_open_internal(Error **errp, 178 const char *src, int line, const char *func, 179 int os_errno, const char *filename); 180 181 /* 182 * Return an exact copy of @err. 183 */ 184 Error *error_copy(const Error *err); 185 186 /* 187 * Free @err. 188 * @err may be NULL. 189 */ 190 void error_free(Error *err); 191 192 /* 193 * Convenience function to error_report() and free @err. 194 */ 195 void error_report_err(Error *); 196 197 /* 198 * Just like error_setg(), except you get to specify the error class. 199 * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is 200 * strongly discouraged. 201 */ 202 #define error_set(errp, err_class, fmt, ...) \ 203 error_set_internal((errp), __FILE__, __LINE__, __func__, \ 204 (err_class), (fmt), ## __VA_ARGS__) 205 void error_set_internal(Error **errp, 206 const char *src, int line, const char *func, 207 ErrorClass err_class, const char *fmt, ...) 208 GCC_FMT_ATTR(6, 7); 209 210 /* 211 * Pass to error_setg() & friends to abort() on error. 212 */ 213 extern Error *error_abort; 214 215 /* 216 * Pass to error_setg() & friends to exit(1) on error. 217 */ 218 extern Error *error_fatal; 219 220 #endif 221