From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1008AC433EF for ; Thu, 28 Oct 2021 16:11:31 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id CC8D16058D for ; Thu, 28 Oct 2021 16:11:30 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org CC8D16058D Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=nongnu.org Received: from localhost ([::1]:32778 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mg801-0004Vm-RM for qemu-devel@archiver.kernel.org; Thu, 28 Oct 2021 12:11:29 -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 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= 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 X-MC-Unique: 26c7H601PL6KvIekvDLSUg-1 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) 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: 8bit 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" 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é --- 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; } -- 2.31.1