+
+/*
+ * Error reporting system loosely patterned after Glib's GError.
+ *
+ * Create an error:
+ * error_setg(&err, "situation normal, all fouled up");
+ *
+ * Create an error and add additional explanation:
+ * error_setg(&err, "invalid quark");
+ * error_append_hint(&err, "Valid quarks are up, down, strange, "
+ * "charm, top, bottom.\n");
+ *
+ * Do *not* contract this to
+ * error_setg(&err, "invalid quark\n"
+ * "Valid quarks are up, down, strange, charm, top, bottom.");
+ *
+ * Report an error to the current monitor if we have one, else stderr:
+ * error_report_err(err);
+ * This frees the error object.
+ *
+ * Likewise, but with additional text prepended:
+ * error_reportf_err(err, "Could not frobnicate '%s': ", name);
+ *
+ * Report an error somewhere else:
+ * const char *msg = error_get_pretty(err);
+ * do with msg what needs to be done...
+ * error_free(err);
+ * Note that this loses hints added with error_append_hint().
+ *
+ * Handle an error without reporting it (just for completeness):
+ * error_free(err);
+ *
+ * Assert that an expected error occurred, but clean it up without
+ * reporting it (primarily useful in testsuites):
+ * error_free_or_abort(&err);
+ *
+ * Pass an existing error to the caller:
+ * error_propagate(errp, err);
+ * where Error **errp is a parameter, by convention the last one.
+ *
+ * Pass an existing error to the caller with the message modified:
+ * error_propagate(errp, err);
+ * error_prepend(errp, "Could not frobnicate '%s': ", name);
+ *
+ * Create a new error and pass it to the caller:
+ * error_setg(errp, "situation normal, all fouled up");
+ *
+ * Call a function and receive an error from it:
+ * Error *err = NULL;
+ * foo(arg, &err);
+ * if (err) {
+ * handle the error...
+ * }
+ *
+ * Call a function ignoring errors:
+ * foo(arg, NULL);
+ *
+ * Call a function aborting on errors:
+ * foo(arg, &error_abort);
+ *
+ * Call a function treating errors as fatal:
+ * foo(arg, &error_fatal);
+ *
+ * Receive an error and pass it on to the caller:
+ * Error *err = NULL;
+ * foo(arg, &err);
+ * if (err) {
+ * handle the error...
+ * error_propagate(errp, err);
+ * }
+ * where Error **errp is a parameter, by convention the last one.
+ *
+ * Do *not* "optimize" this to
+ * foo(arg, errp);
+ * if (*errp) { // WRONG!
+ * handle the error...
+ * }
+ * because errp may be NULL!
+ *
+ * But when all you do with the error is pass it on, please use
+ * foo(arg, errp);
+ * for readability.
+ *
+ * Receive and accumulate multiple errors (first one wins):
+ * Error *err = NULL, *local_err = NULL;
+ * foo(arg, &err);
+ * bar(arg, &local_err);
+ * error_propagate(&err, local_err);
+ * if (err) {
+ * handle the error...
+ * }
+ *
+ * Do *not* "optimize" this to
+ * foo(arg, &err);
+ * bar(arg, &err); // WRONG!
+ * if (err) {
+ * handle the error...
+ * }
+ * because this may pass a non-null err to bar().
+ */
+