include/qapi/error.h

2  * QEMU Error Objects
16  * Error reporting system loosely patterned after Glib's GError.
20  * - Functions that use Error to report errors have an Error **errp
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.
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
38  *   should set a new error, e.g. with error_setg(errp, ...), or
42  *   failure.  This can make the error checking more concise, and can
43  *   avoid useless error object creation and destruction.  Note that
51  * Create an error:
53  * where @errp points to the location to receive the error.
55  * Create an error and add additional explanation:
67  * Report an error to the current monitor if we have one, else stderr:
69  * This frees the error object.
74  * Report an error somewhere else:
83  *     Error *err = NULL;
90  *     Error *err = NULL;
97  *     Error *err = NULL;
104  * Handle an error without reporting it (just for completeness):
107  * Assert that an expected error occurred, but clean it up without
116  * Create a new error and pass it to the caller:
119  * Call a function, receive an error from it, and pass it to the caller
123  *         handle the error...
129  *         handle the error...
134  *     Error *err = NULL;
137  *         handle the error...
143  *         handle the error...
147  * But when all you do with the error is pass it on, please use
151  * Receive an error, and handle it locally
154  *     Error *err = NULL;
156  *         handle the error...
159  *     Error *err = NULL;
162  *         handle the error...
165  * Pass an existing error to the caller:
170  * Pass an existing error to the caller with the message modified:
179  *     Error *err = NULL, *local_err = NULL;
184  *         handle the error...
188  *     Error *err = NULL;
192  *         handle the error...
197  *     Error *err = NULL;
225  * 0. If the Error ** parameter is not named @errp, rename it to
242  *     bool fn(..., Error **errp)
244  *         Error *err = NULL;
248  *             handle the error...
257  *     bool fn(..., Error **errp)
263  *             handle the error...
275 #include "qapi/qapi-types-error.h"
278  * Overall category of an error.
291  * Get @err's human-readable error message.
293 const char *error_get_pretty(const Error *err);
296  * Get @err's error class.
297  * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is
300 ErrorClass error_get_class(const Error *err);
303  * Create a new error object and assign it to *@errp.
304  * If @errp is NULL, the error is ignored.  Don't bother creating one
309  * The new error's class is ERROR_CLASS_GENERIC_ERROR, and its
310  * human-readable error message is made from printf-style @fmt, ...
320 void error_setg_internal(Error **errp,
328  * the human-readable error message.
336 void error_setg_errno_internal(Error **errp,
345  * is appended to the human-readable error message.
350 void error_setg_win32_internal(Error **errp,
357  * Propagate error object (if any) from @local_err to @dst_errp.
361  * error object.
366  * Else, if @dst_errp already contains an error, ignore this one: free
367  * the error object.
368  * Else, move the error object from @local_err to *@dst_errp.
374 void error_propagate(Error **dst_errp, Error *local_err);
378  * Propagate error object (if any) with some text prepended.
384 void error_propagate_prepend(Error **dst_errp, Error *local_err,
389  * Prepend some text to @errp's human-readable error message.
392 void error_vprepend(Error *const *errp, const char *fmt, va_list ap)
396  * Prepend some text to @errp's human-readable error message.
399 void error_prepend(Error *const *errp, const char *fmt, ...)
403  * Append a printf-style human-readable explanation to an existing error.
404  * If the error is later reported to a human user with
409  * error message.
416 void error_append_hint(Error *const *errp, const char *fmt, ...)
425 void error_setg_file_open_internal(Error **errp,
432 Error *error_copy(const Error *err);
438 void error_free(Error *err);
443 void error_free_or_abort(Error **errp);
449 void warn_report_err(Error *err);
455 void error_report_err(Error *err);
460 void warn_reportf_err(Error *err, const char *fmt, ...)
466 void error_reportf_err(Error *err, const char *fmt, ...)
470  * Just like error_setg(), except you get to specify the error class.
471  * Note: use of error classes other than ERROR_CLASS_GENERIC_ERROR is
477 void error_set_internal(Error **errp,
486  * takes an Error **errp parameter to pass errors to its caller.  The
495  * Error variable, which will be automatically propagated to the
499  * abort from the place where the error is created to the place where
511     Error *local_err;
512     Error **errp;
523  * Special error destination to warn on error.
526 extern Error *error_warn;
529  * Special error destination to abort on error.
532 extern Error *error_abort;
535  * Special error destination to exit(1) on error.
538 extern Error *error_fatal;