path: root/HACKING
diff options
authorMarkus Armbruster <armbru@redhat.com>2016-02-03 19:03:48 +0100
committerMarkus Armbruster <armbru@redhat.com>2016-02-09 13:19:49 +0100
commitd76a3bf5c46d9e981faf09e6194c795ee54e5ae4 (patch)
tree2a3f0e1b42bade11ca3aa7daff818c817050bd90 /HACKING
parent10303f04b98efa76e638b9ae4632688f56f088fc (diff)
HACKING: Add a section on error handling and reporting
Inspired by an RFC PATCH from Lluís Vilanova. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1454522628-28294-3-git-send-email-armbru@redhat.com> Reviewed-by: Lluís Vilanova <vilanova@ac.upc.edu>
Diffstat (limited to 'HACKING')
1 files changed, 55 insertions, 0 deletions
diff --git a/HACKING b/HACKING
index 12fbc8afe4..058aa8fd49 100644
@@ -157,3 +157,58 @@ painful. These are:
* you may assume that integers are 2s complement representation
* you may assume that right shift of a signed integer duplicates
the sign bit (ie it is an arithmetic shift, not a logical shift)
+7. Error handling and reporting
+7.1 Reporting errors to the human user
+Do not use printf(), fprintf() or monitor_printf(). Instead, use
+error_report() or error_vreport() from error-report.h. This ensures the
+error is reported in the right place (current monitor or stderr), and in
+a uniform format.
+Use error_printf() & friends to print additional information.
+error_report() prints the current location. In certain common cases
+like command line parsing, the current location is tracked
+automatically. To manipulate it manually, use the loc_*() from
+7.2 Propagating errors
+An error can't always be reported to the user right where it's detected,
+but often needs to be propagated up the call chain to a place that can
+handle it. This can be done in various ways.
+The most flexible one is Error objects. See error.h for usage
+Use the simplest suitable method to communicate success / failure to
+callers. Stick to common methods: non-negative on success / -1 on
+error, non-negative / -errno, non-null / null, or Error objects.
+Example: when a function returns a non-null pointer on success, and it
+can fail only in one way (as far as the caller is concerned), returning
+null on failure is just fine, and certainly simpler and a lot easier on
+the eyes than propagating an Error object through an Error ** parameter.
+Example: when a function's callers need to report details on failure
+only the function really knows, use Error **, and set suitable errors.
+Do not report an error to the user when you're also returning an error
+for somebody else to handle. Leave the reporting to the place that
+consumes the error returned.
+7.3 Handling errors
+Calling exit() is fine when handling configuration errors during
+startup. It's problematic during normal operation. In particular,
+monitor commands should never exit().
+Do not call exit() or abort() to handle an error that can be triggered
+by the guest (e.g., some unimplemented corner case in guest code
+translation or device emulation). Guests should not be able to
+terminate QEMU.
+Note that &error_fatal is just another way to exit(1), and &error_abort
+is just another way to abort().