include/qapi/error.h

   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  * = Rules =
  19  *
  20  * - Functions that use Error to report errors have an Error **errp
  21  *   parameter.  It should be the last parameter, except for functions
  22  *   taking variable arguments.
  23  *
  24  * - You may pass NULL to not receive the error, &error_abort to abort
  25  *   on error, &error_fatal to exit(1) on error, or a pointer to a
  26  *   variable containing NULL to receive the error.
  27  *
  28  * - Separation of concerns: the function is responsible for detecting
  29  *   errors and failing cleanly; handling the error is its caller's
  30  *   job.  Since the value of @errp is about handling the error, the
  31  *   function should not examine it.
  32  *
  33  * - On success, the function should not touch *errp.  On failure, it
  34  *   should set a new error, e.g. with error_setg(errp, ...), or
  35  *   propagate an existing one, e.g. with error_propagate(errp, ...).
  36  *
  37  * - Whenever practical, also return a value that indicates success /
  38  *   failure.  This can make the error checking more concise, and can
  39  *   avoid useless error object creation and destruction.  Note that
  40  *   we still have many functions returning void.  We recommend
  41  *   • bool-valued functions return true on success / false on failure,
  42  *   • pointer-valued functions return non-null / null pointer, and
  43  *   • integer-valued functions return non-negative / negative.
  44  *
  45  * = Creating errors =
  46  *
  47  * Create an error:
  48  *     error_setg(&err, "situation normal, all fouled up");
  49  *
  50  * Create an error and add additional explanation:
  51  *     error_setg(&err, "invalid quark");
  52  *     error_append_hint(&err, "Valid quarks are up, down, strange, "
  53  *                       "charm, top, bottom.\n");
  54  *
  55  * Do *not* contract this to
  56  *     error_setg(&err, "invalid quark\n" // WRONG!
  57  *                "Valid quarks are up, down, strange, charm, top, bottom.");
  58  *
  59  * = Reporting and destroying errors =
  60  *
  61  * Report an error to the current monitor if we have one, else stderr:
  62  *     error_report_err(err);
  63  * This frees the error object.
  64  *
  65  * Likewise, but with additional text prepended:
  66  *     error_reportf_err(err, "Could not frobnicate '%s': ", name);
  67  *
  68  * Report an error somewhere else:
  69  *     const char *msg = error_get_pretty(err);
  70  *     do with msg what needs to be done...
  71  *     error_free(err);
  72  * Note that this loses hints added with error_append_hint().
  73  *
  74  * Call a function ignoring errors:
  75  *     foo(arg, NULL);
  76  * This is more concise than
  77  *     Error *err = NULL;
  78  *     foo(arg, &err);
  79  *     error_free(err); // don't do this
  80  *
  81  * Call a function aborting on errors:
  82  *     foo(arg, &error_abort);
  83  * This is more concise and fails more nicely than
  84  *     Error *err = NULL;
  85  *     foo(arg, &err);
  86  *     assert(!err); // don't do this
  87  *
  88  * Call a function treating errors as fatal:
  89  *     foo(arg, &error_fatal);
  90  * This is more concise than
  91  *     Error *err = NULL;
  92  *     foo(arg, &err);
  93  *     if (err) { // don't do this
  94  *         error_report_err(err);
  95  *         exit(1);
  96  *     }
  97  *
  98  * Handle an error without reporting it (just for completeness):
  99  *     error_free(err);
 100  *
 101  * Assert that an expected error occurred, but clean it up without
 102  * reporting it (primarily useful in testsuites):
 103  *     error_free_or_abort(&err);
 104  *
 105  * = Passing errors around =
 106  *
 107  * Errors get passed to the caller through the conventional @errp
 108  * parameter.
 109  *
 110  * Pass an existing error to the caller:
 111  *     error_propagate(errp, err);
 112  * where Error **errp is a parameter, by convention the last one.
 113  *
 114  * Pass an existing error to the caller with the message modified:
 115  *     error_propagate_prepend(errp, err,
 116  *                             "Could not frobnicate '%s': ", name);
 117  * This is more concise than
 118  *     error_propagate(errp, err); // don't do this
 119  *     error_prepend(errp, "Could not frobnicate '%s': ", name);
 120  * and works even when @errp is &error_fatal.
 121  *
 122  * Create a new error and pass it to the caller:
 123  *     error_setg(errp, "situation normal, all fouled up");
 124  *
 125  * Call a function, receive an error from it, and pass it to the caller
 126  * - when the function returns a value that indicates failure, say
 127  *   false:
 128  *     if (!foo(arg, errp)) {
 129  *         handle the error...
 130  *     }
 131  * - when it does not, say because it is a void function:
 132  *     Error *err = NULL;
 133  *     foo(arg, &err);
 134  *     if (err) {
 135  *         handle the error...
 136  *         error_propagate(errp, err);
 137  *     }
 138  * Do *not* "optimize" this to
 139  *     foo(arg, errp);
 140  *     if (*errp) { // WRONG!
 141  *         handle the error...
 142  *     }
 143  * because errp may be NULL!
 144  *
 145  * But when all you do with the error is pass it on, please use
 146  *     foo(arg, errp);
 147  * for readability.
 148  *
 149  * Receive an error, and handle it locally
 150  * - when the function returns a value that indicates failure, say
 151  *   false:
 152  *     Error *err = NULL;
 153  *     if (!foo(arg, &err)) {
 154  *         handle the error...
 155  *     }
 156  * - when it does not, say because it is a void function:
 157  *     Error *err = NULL;
 158  *     foo(arg, &err);
 159  *     if (err) {
 160  *         handle the error...
 161  *     }
 162  *
 163  * Receive and accumulate multiple errors (first one wins):
 164  *     Error *err = NULL, *local_err = NULL;
 165  *     foo(arg, &err);
 166  *     bar(arg, &local_err);
 167  *     error_propagate(&err, local_err);
 168  *     if (err) {
 169  *         handle the error...
 170  *     }
 171  *
 172  * Do *not* "optimize" this to
 173  *     Error *err = NULL;
 174  *     foo(arg, &err);
 175  *     bar(arg, &err); // WRONG!
 176  *     if (err) {
 177  *         handle the error...
 178  *     }
 179  * because this may pass a non-null err to bar().
 180  *
 181  * Likewise, do *not*
 182  *     Error *err = NULL;
 183  *     if (cond1) {
 184  *         error_setg(&err, ...);
 185  *     }
 186  *     if (cond2) {
 187  *         error_setg(&err, ...); // WRONG!
 188  *     }
 189  * because this may pass a non-null err to error_setg().
 190  */
 191
 192 #ifndef ERROR_H
 193 #define ERROR_H
 194
 195 #include "qapi/qapi-types-error.h"
 196
 197 /*
 198  * Overall category of an error.
 199  * Based on the qapi type QapiErrorClass, but reproduced here for nicer
 200  * enum names.
 201  */
 202 typedef enum ErrorClass {
 203     ERROR_CLASS_GENERIC_ERROR = QAPI_ERROR_CLASS_GENERICERROR,
 204     ERROR_CLASS_COMMAND_NOT_FOUND = QAPI_ERROR_CLASS_COMMANDNOTFOUND,
 205     ERROR_CLASS_DEVICE_NOT_ACTIVE = QAPI_ERROR_CLASS_DEVICENOTACTIVE,
 206     ERROR_CLASS_DEVICE_NOT_FOUND = QAPI_ERROR_CLASS_DEVICENOTFOUND,
 207     ERROR_CLASS_KVM_MISSING_CAP = QAPI_ERROR_CLASS_KVMMISSINGCAP,
 208 } ErrorClass;
 209
 210 /*
 211  * Get @err's human-readable error message.
 212  */
 213 const char *error_get_pretty(const Error *err);
 214
 215 /*
 216  * Get @err's error class.
 217  * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is
 218  * strongly discouraged.
 219  */
 220 ErrorClass error_get_class(const Error *err);
 221
 222 /*
 223  * Create a new error object and assign it to *@errp.
 224  * If @errp is NULL, the error is ignored.  Don't bother creating one
 225  * then.
 226  * If @errp is &error_abort, print a suitable message and abort().
 227  * If @errp is &error_fatal, print a suitable message and exit(1).
 228  * If @errp is anything else, *@errp must be NULL.
 229  * The new error's class is ERROR_CLASS_GENERIC_ERROR, and its
 230  * human-readable error message is made from printf-style @fmt, ...
 231  * The resulting message should be a single phrase, with no newline or
 232  * trailing punctuation.
 233  * Please don't error_setg(&error_fatal, ...), use error_report() and
 234  * exit(), because that's more obvious.
 235  * Likewise, don't error_setg(&error_abort, ...), use assert().
 236  */
 237 #define error_setg(errp, fmt, ...)                              \
 238     error_setg_internal((errp), __FILE__, __LINE__, __func__,   \
 239                         (fmt), ## __VA_ARGS__)
 240 void error_setg_internal(Error **errp,
 241                          const char *src, int line, const char *func,
 242                          const char *fmt, ...)
 243     GCC_FMT_ATTR(5, 6);
 244
 245 /*
 246  * Just like error_setg(), with @os_error info added to the message.
 247  * If @os_error is non-zero, ": " + strerror(os_error) is appended to
 248  * the human-readable error message.
 249  *
 250  * The value of errno (which usually can get clobbered by almost any
 251  * function call) will be preserved.
 252  */
 253 #define error_setg_errno(errp, os_error, fmt, ...)                      \
 254     error_setg_errno_internal((errp), __FILE__, __LINE__, __func__,     \
 255                               (os_error), (fmt), ## __VA_ARGS__)
 256 void error_setg_errno_internal(Error **errp,
 257                                const char *fname, int line, const char *func,
 258                                int os_error, const char *fmt, ...)
 259     GCC_FMT_ATTR(6, 7);
 260
 261 #ifdef _WIN32
 262 /*
 263  * Just like error_setg(), with @win32_error info added to the message.
 264  * If @win32_error is non-zero, ": " + g_win32_error_message(win32_err)
 265  * is appended to the human-readable error message.
 266  */
 267 #define error_setg_win32(errp, win32_err, fmt, ...)                     \
 268     error_setg_win32_internal((errp), __FILE__, __LINE__, __func__,     \
 269                               (win32_err), (fmt), ## __VA_ARGS__)
 270 void error_setg_win32_internal(Error **errp,
 271                                const char *src, int line, const char *func,
 272                                int win32_err, const char *fmt, ...)
 273     GCC_FMT_ATTR(6, 7);
 274 #endif
 275
 276 /*
 277  * Propagate error object (if any) from @local_err to @dst_errp.
 278  * If @local_err is NULL, do nothing (because there's nothing to
 279  * propagate).
 280  * Else, if @dst_errp is NULL, errors are being ignored.  Free the
 281  * error object.
 282  * Else, if @dst_errp is &error_abort, print a suitable message and
 283  * abort().
 284  * Else, if @dst_errp is &error_fatal, print a suitable message and
 285  * exit(1).
 286  * Else, if @dst_errp already contains an error, ignore this one: free
 287  * the error object.
 288  * Else, move the error object from @local_err to *@dst_errp.
 289  * On return, @local_err is invalid.
 290  * Please don't error_propagate(&error_fatal, ...), use
 291  * error_report_err() and exit(), because that's more obvious.
 292  */
 293 void error_propagate(Error **dst_errp, Error *local_err);
 294
 295
 296 /*
 297  * Propagate error object (if any) with some text prepended.
 298  * Behaves like
 299  *     error_prepend(&local_err, fmt, ...);
 300  *     error_propagate(dst_errp, local_err);
 301  */
 302 void error_propagate_prepend(Error **dst_errp, Error *local_err,
 303                              const char *fmt, ...);
 304
 305 /*
 306  * Prepend some text to @errp's human-readable error message.
 307  * The text is made by formatting @fmt, @ap like vprintf().
 308  */
 309 void error_vprepend(Error *const *errp, const char *fmt, va_list ap);
 310
 311 /*
 312  * Prepend some text to @errp's human-readable error message.
 313  * The text is made by formatting @fmt, ... like printf().
 314  */
 315 void error_prepend(Error *const *errp, const char *fmt, ...)
 316     GCC_FMT_ATTR(2, 3);
 317
 318 /*
 319  * Append a printf-style human-readable explanation to an existing error.
 320  * If the error is later reported to a human user with
 321  * error_report_err() or warn_report_err(), the hints will be shown,
 322  * too.  If it's reported via QMP, the hints will be ignored.
 323  * Intended use is adding helpful hints on the human user interface,
 324  * e.g. a list of valid values.  It's not for clarifying a confusing
 325  * error message.
 326  * @errp may be NULL, but not &error_fatal or &error_abort.
 327  * Trivially the case if you call it only after error_setg() or
 328  * error_propagate().
 329  * May be called multiple times.  The resulting hint should end with a
 330  * newline.
 331  */
 332 void error_append_hint(Error *const *errp, const char *fmt, ...)
 333     GCC_FMT_ATTR(2, 3);
 334
 335 /*
 336  * Convenience function to report open() failure.
 337  */
 338 #define error_setg_file_open(errp, os_errno, filename)                  \
 339     error_setg_file_open_internal((errp), __FILE__, __LINE__, __func__, \
 340                                   (os_errno), (filename))
 341 void error_setg_file_open_internal(Error **errp,
 342                                    const char *src, int line, const char *func,
 343                                    int os_errno, const char *filename);
 344
 345 /*
 346  * Return an exact copy of @err.
 347  */
 348 Error *error_copy(const Error *err);
 349
 350 /*
 351  * Free @err.
 352  * @err may be NULL.
 353  */
 354 void error_free(Error *err);
 355
 356 /*
 357  * Convenience function to assert that *@errp is set, then silently free it.
 358  */
 359 void error_free_or_abort(Error **errp);
 360
 361 /*
 362  * Convenience function to warn_report() and free @err.
 363  * The report includes hints added with error_append_hint().
 364  */
 365 void warn_report_err(Error *err);
 366
 367 /*
 368  * Convenience function to error_report() and free @err.
 369  * The report includes hints added with error_append_hint().
 370  */
 371 void error_report_err(Error *err);
 372
 373 /*
 374  * Convenience function to error_prepend(), warn_report() and free @err.
 375  */
 376 void warn_reportf_err(Error *err, const char *fmt, ...)
 377     GCC_FMT_ATTR(2, 3);
 378
 379 /*
 380  * Convenience function to error_prepend(), error_report() and free @err.
 381  */
 382 void error_reportf_err(Error *err, const char *fmt, ...)
 383     GCC_FMT_ATTR(2, 3);
 384
 385 /*
 386  * Just like error_setg(), except you get to specify the error class.
 387  * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is
 388  * strongly discouraged.
 389  */
 390 #define error_set(errp, err_class, fmt, ...)                    \
 391     error_set_internal((errp), __FILE__, __LINE__, __func__,    \
 392                        (err_class), (fmt), ## __VA_ARGS__)
 393 void error_set_internal(Error **errp,
 394                         const char *src, int line, const char *func,
 395                         ErrorClass err_class, const char *fmt, ...)
 396     GCC_FMT_ATTR(6, 7);
 397
 398 /*
 399  * Special error destination to abort on error.
 400  * See error_setg() and error_propagate() for details.
 401  */
 402 extern Error *error_abort;
 403
 404 /*
 405  * Special error destination to exit(1) on error.
 406  * See error_setg() and error_propagate() for details.
 407  */
 408 extern Error *error_fatal;
 409
 410 #endif