From 6fa6b54f5b931e10e24f773d991a48da4f79e61a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Date: Thu, 28 Oct 2021 16:13:55 +0100 Subject: [PATCH] docs/devel: update error handling guidance for HMP commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Best practice is to use the 'hmp_handle_error' function, not 'monitor_printf' or 'error_report_err'. This ensures that the message always gets an 'Error: ' prefix, distinguishing it from normal command output. Reviewed-by: Dr. David Alan Gilbert Signed-off-by: Daniel P. Berrangé --- docs/devel/writing-monitor-commands.rst | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/docs/devel/writing-monitor-commands.rst b/docs/devel/writing-monitor-commands.rst index a973c48f66..a381b52024 100644 --- a/docs/devel/writing-monitor-commands.rst +++ b/docs/devel/writing-monitor-commands.rst @@ -293,9 +293,7 @@ Here's the implementation of the "hello-world" HMP command:: Error *err = NULL; qmp_hello_world(!!message, message, &err); - if (err) { - monitor_printf(mon, "%s\n", error_get_pretty(err)); - error_free(err); + if (hmp_handle_error(mon, err)) { return; } } @@ -307,9 +305,10 @@ There are three important points to be noticed: 1. The "mon" and "qdict" arguments are mandatory for all HMP functions. The former is the monitor object. The latter is how the monitor passes arguments entered by the user to the command implementation -2. hmp_hello_world() performs error checking. In this example we just print - the error description to the user, but we could do more, like taking - different actions depending on the error qmp_hello_world() returns +2. hmp_hello_world() performs error checking. In this example we just call + hmp_handle_error() which prints a message to the user, but we could do + more, like taking different actions depending on the error + qmp_hello_world() returns 3. The "err" variable must be initialized to NULL before performing the QMP call @@ -466,9 +465,7 @@ Here's the HMP counterpart of the query-alarm-clock command:: Error *err = NULL; clock = qmp_query_alarm_clock(&err); - if (err) { - monitor_printf(mon, "Could not query alarm clock information\n"); - error_free(err); + if (hmp_handle_error(mon, err)) { return; } @@ -607,9 +604,7 @@ has to traverse the list, it's shown below for reference:: Error *err = NULL; method_list = qmp_query_alarm_methods(&err); - if (err) { - monitor_printf(mon, "Could not query alarm methods\n"); - error_free(err); + if (hmp_handle_error(mon, err)) { return; }