1 files changed, 64 insertions, 4 deletions

diff --git a/include/qapi/error.h b/include/qapi/error.h
index 6285cf50d1..45d6c72dee 100644
--- a/include/qapi/error.h
+++ b/include/qapi/error.h
@@ -18,14 +18,27 @@
  * 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 stderr:
  *     error_report_err(err);
  * This frees the error object.
  *
+ * Report an error to stderr 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);
@@ -38,6 +51,10 @@
  *     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");
  *
@@ -76,14 +93,32 @@
  * 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().
  */
 
 #ifndef ERROR_H
 #define ERROR_H
 
+#include <stdarg.h>
+#include <stdbool.h>
 #include "qemu/compiler.h"
 #include "qapi-types.h"
-#include <stdbool.h>
 
 /*
  * Opaque error object.
@@ -125,6 +160,8 @@ ErrorClass error_get_class(const Error *err);
  * If @errp is anything else, *@errp must be NULL.
  * The new error's class is ERROR_CLASS_GENERIC_ERROR, and its
  * human-readable error message is made from printf-style @fmt, ...
+ * The resulting message should be a single phrase, with no newline or
+ * trailing punctuation.
  */
 #define error_setg(errp, fmt, ...)                              \
     error_setg_internal((errp), __FILE__, __LINE__, __func__,   \
@@ -179,9 +216,26 @@ void error_setg_win32_internal(Error **errp,
  */
 void error_propagate(Error **dst_errp, Error *local_err);
 
-/**
+/*
+ * Prepend some text to @errp's human-readable error message.
+ * The text is made by formatting @fmt, @ap like vprintf().
+ */
+void error_vprepend(Error **errp, const char *fmt, va_list ap);
+
+/*
+ * Prepend some text to @errp's human-readable error message.
+ * The text is made by formatting @fmt, ... like printf().
+ */
+void error_prepend(Error **errp, const char *fmt, ...)
+    GCC_FMT_ATTR(2, 3);
+
+/*
  * Append a printf-style human-readable explanation to an existing error.
- * May be called multiple times, and safe if @errp is NULL.
+ * @errp may be NULL, but not &error_fatal or &error_abort.
+ * Trivially the case if you call it only after error_setg() or
+ * error_propagate().
+ * May be called multiple times.  The resulting hint should end with a
+ * newline.
  */
 void error_append_hint(Error **errp, const char *fmt, ...)
     GCC_FMT_ATTR(2, 3);
@@ -215,7 +269,13 @@ void error_free_or_abort(Error **errp);
 /*
  * Convenience function to error_report() and free @err.
  */
-void error_report_err(Error *);
+void error_report_err(Error *err);
+
+/*
+ * Convenience function to error_prepend(), error_report() and free @err.
+ */
+void error_reportf_err(Error *err, const char *fmt, ...)
+    GCC_FMT_ATTR(2, 3);
 
 /*
  * Just like error_setg(), except you get to specify the error class.