From nobody Mon Feb 9 07:55:26 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1635437499859421.84947520370486; Thu, 28 Oct 2021 09:11:39 -0700 (PDT) Received: from localhost ([::1]:32778 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mg80A-0004Vm-Nx for importer@patchew.org; Thu, 28 Oct 2021 12:11:38 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:50834) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mg7lt-0002QM-7y for qemu-devel@nongnu.org; Thu, 28 Oct 2021 11:56:53 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]:25928) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mg7lf-0004Hg-Kf for qemu-devel@nongnu.org; Thu, 28 Oct 2021 11:56:52 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-105-26c7H601PL6KvIekvDLSUg-1; Thu, 28 Oct 2021 11:56:35 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 9B43819253C0; Thu, 28 Oct 2021 15:56:33 +0000 (UTC) Received: from localhost.localdomain.com (unknown [10.39.195.37]) by smtp.corp.redhat.com (Postfix) with ESMTP id C0C416C8F7; Thu, 28 Oct 2021 15:56:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1635436598; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=nJKO301o9ZN+OxIchHeO7hDI+gNxCJRLZXc8cl3DDYk=; b=XJgIP0AEJu96HXVeAMP5eOT/fHaNFTgs235R+W3dRMIe8hAu1E2GP0Y1boJ+LVIBcifdX6 WeVw1LJ6WOLhkC84rAHU44oru+e+CXgd3cqWGQuJJUOwk7CWHgcd0riBTmEdSTp5mBm9Cm 3olZAQLnSfXdsiLZMjfYi4et3xu+XF4= X-MC-Unique: 26c7H601PL6KvIekvDLSUg-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: qemu-devel@nongnu.org Subject: [PATCH v4 05/22] docs/devel: update error handling guidance for HMP commands Date: Thu, 28 Oct 2021 16:54:40 +0100 Message-Id: <20211028155457.967291-6-berrange@redhat.com> In-Reply-To: <20211028155457.967291-1-berrange@redhat.com> References: <20211028155457.967291-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=berrange@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=berrange@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Laurent Vivier , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eduardo Habkost , David Hildenbrand , Michael Roth , Cornelia Huck , Richard Henderson , "Dr. David Alan Gilbert" , Peter Xu , Yuval Shaia , Halil Pasic , Christian Borntraeger , qemu-s390x@nongnu.org, Gerd Hoffmann , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Eric Blake , Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1635437501016100001 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. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Dr. David Alan Gilbert --- 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-m= onitor-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 comm= and:: Error *err =3D NULL; =20 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 =20 @@ -466,9 +465,7 @@ Here's the HMP counterpart of the query-alarm-clock com= mand:: Error *err =3D NULL; =20 clock =3D 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; } =20 @@ -607,9 +604,7 @@ has to traverse the list, it's shown below for referenc= e:: Error *err =3D NULL; =20 method_list =3D 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; } =20 --=20 2.31.1