include/qapi/error.h

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.
21  *   parameter.  It should be the last parameter, except for functions
24  * - You may pass NULL to not receive the error, &error_abort to abort
26  *   variable containing NULL to receive the error.
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
33  * - The function may pass @errp to functions it calls to pass on
37  * - On success, the function should not touch *errp.  On failure, it
42  *   failure.  This can make the error checking more concise, and can
53  * where @errp points to the location to receive the error.
67  * Report an error to the current monitor if we have one, else stderr:
69  * This frees the error object.
113  * Errors get passed to the caller through the conventional @errp
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
120  * - when the function returns a value that indicates failure, say
123  *         handle the error...
129  *         handle the error...
137  *         handle the error...
143  *         handle the error...
145  * because errp may be NULL without the ERRP_GUARD() guard.
147  * But when all you do with the error is pass it on, please use
152  * - when the function returns a value that indicates failure, say
156  *         handle the error...
162  *         handle the error...
165  * Pass an existing error to the caller:
170  * Pass an existing error to the caller with the message modified:
184  *         handle the error...
192  *         handle the error...
208  * Without ERRP_GUARD(), use of the @errp parameter is restricted:
214  * To use ERRP_GUARD(), add it right at the beginning of the function.
215  * @errp can then be used without worrying about the argument being
219  * the source with useless code.
225  * 0. If the Error ** parameter is not named @errp, rename it to
228  * 1. Add an ERRP_GUARD() invocation, by convention right at the
229  *    beginning of the function.  This makes @errp safe to use.
248  *             handle the error...
263  *             handle the error...
279  * Based on the qapi type QapiErrorClass, but reproduced here for nicer
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
311  * The resulting message should be a single phrase, with no newline or
326  * Just like error_setg(), with @os_error info added to the message.
328  * the human-readable error message.
330  * The value of errno (which usually can get clobbered by almost any
343  * Just like error_setg(), with @win32_error info added to the message.
345  * is appended to the human-readable error message.
360  * Else, if @dst_errp is NULL, errors are being ignored.  Free the
367  * the error object.
368  * Else, move the error object from @local_err to *@dst_errp.
390  * The text is made by formatting @fmt, @ap like vprintf().
397  * The text is made by formatting @fmt, ... like printf().
404  * If the error is later reported to a human user with
405  * error_report_err() or warn_report_err(), the hints will be shown,
406  * too.  If it's reported via QMP, the hints will be ignored.
407  * Intended use is adding helpful hints on the human user interface,
411  * Trivially the case if you call it only after error_setg() or
413  * May be called multiple times.  The resulting hint should end with a
449  * The report includes hints added with error_append_hint().
455  * The report includes hints added with error_append_hint().
472  * Similar to warn_report_err(), except it prints the message just once.
484  * Just like error_setg(), except you get to specify the error class.
499  * This macro is for use right at the beginning of a function that
500  * takes an Error **errp parameter to pass errors to its caller.  The
503  * It must be used when the function dereferences @errp or passes
506  * cluttering the source with useless code.
509  * Error variable, which will be automatically propagated to the
512  * Note: &error_abort is not rewritten, because that would move the
513  * abort from the place where the error is created to the place where