From nobody Mon Feb 9 09:29:48 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=philmd@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=philmd@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1637075613; cv=none; d=zohomail.com; s=zohoarc; b=UlJUjmo2KBa6N83nabM8Ck2Bok27u1d0ePC0CprwJHOGQhWooGaDOaPE7RJcUKj1xnRj4M1Mmp8RErgQcY3GMaU3jDIS2TMs3VAHV3hxqjtRq2mQVvov1QKskrAxM9kgVagCuuS+NmYUB7c6UUgmctsGufTyU7Btcn9sKVLc3OQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1637075613; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:To; bh=Ms3B9QbG5Lq6X9ovVT6jCZ1RA1SZmRfiYx9TmX6F1t4=; b=ThP3BPwhQ6Ha5keRXRSh3A2nLZEYIp9ihORdN1ab4csjSJ5g/sh9EoJqMH9eNaxSUnRHTfqV6xRQPhxzIPxK29TcS4mWGZIBCFbVMW5kXVx7dhc30HRepeeE/PpmDa4BDJjWoWN0p1xX37d0AFnLfeOpsPupyOPmPvLa9BAJfOA= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=philmd@redhat.com; dmarc=pass header.from= (p=none dis=none) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 163707561339282.9226876649243; Tue, 16 Nov 2021 07:13:33 -0800 (PST) Received: from mail-wm1-f70.google.com (mail-wm1-f70.google.com [209.85.128.70]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-273-BLT4LMTGNCevk96j17TE5w-1; Tue, 16 Nov 2021 10:13:31 -0500 Received: by mail-wm1-f70.google.com with SMTP id g80-20020a1c2053000000b003331a764709so1349789wmg.2 for ; Tue, 16 Nov 2021 07:13:30 -0800 (PST) Return-Path: Return-Path: Received: from x1w.. (62.red-83-57-168.dynamicip.rima-tde.net. [83.57.168.62]) by smtp.gmail.com with ESMTPSA id o4sm3141465wmq.31.2021.11.16.07.13.28 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Nov 2021 07:13:28 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1637075612; 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=Ms3B9QbG5Lq6X9ovVT6jCZ1RA1SZmRfiYx9TmX6F1t4=; b=DfW75/pTxLByrQTPWqYY2ablkMMCh/7OfghoXh7dR3yzEcCVuo5eimdfk6fiN9uVPVuYI5 Oh1hSPghJB4TG+Bv3/F6wPIHi74xgzEu8BZM5rAX1swnDF41CaohyQY5CYoYe6Z7iG8KOR j8+QEZzUZ1AZoJWio9uCad9m1TUzY/Y= X-MC-Unique: BLT4LMTGNCevk96j17TE5w-1 X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=Ms3B9QbG5Lq6X9ovVT6jCZ1RA1SZmRfiYx9TmX6F1t4=; b=Mt3t4og7dpSSGr8tWn+91bMz/N1gCbKP5CqngL6Vf00jCBfQKXsmc51RglVLpH0b2T 3RZ/bcO6x2MOB192BajuEWXaV04BwxQSJLsZCCcXfrdGqel54gRM5tKg/ZVc6TgUOU/i 3kb578nhg9ppTqxNzbK6WRPd+tbG7SdqZSiX1TLE1LYkcp9T36nw0LGlaFGvvqdEmV6v gOYzPym4QU70WnFiUYlZCCjy3JgpEHpsk6ByXurfl1t7q5LGqveqpjxcmdU6Cuav0jC+ 0ss9az3iD2gNEfW5p5KjghA5zjn+wEPzLkZq8OJBjW0atEAl7txW+AE5HTUBjDPLzhia nRXA== X-Gm-Message-State: AOAM531y2i8qvbCxHBLu4NYZXxLn0clojGMpbZ6b42Cxj9Chc12X2GMI B3FkuuEuMqg7CrjbIgnI07WBeCC/JzR+PbzWuqrxUw7Hutqz4bKfa109TZipJMX1OG5YI8KJn+m yFG2WSTan3KP97g== X-Received: by 2002:a5d:46cb:: with SMTP id g11mr10255439wrs.26.1637075609360; Tue, 16 Nov 2021 07:13:29 -0800 (PST) X-Google-Smtp-Source: ABdhPJyKrIz4ZXrYywbmjqVM+jHNv8Gv2kN8EykBs2fpvd6a/Pt52hzN1viz2/PIyiFpw2ui9yGJBg== X-Received: by 2002:a5d:46cb:: with SMTP id g11mr10255376wrs.26.1637075609047; Tue, 16 Nov 2021 07:13:29 -0800 (PST) From: =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= To: qemu-devel@nongnu.org Cc: Peter Maydell , "Daniel P . Berrange" , Markus Armbruster , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Subject: [PATCH-for-6.2? 2/3] docs/devel/style: Improve Error** functions rST rendering Date: Tue, 16 Nov 2021 16:13:16 +0100 Message-Id: <20211116151317.2691125-3-philmd@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20211116151317.2691125-1-philmd@redhat.com> References: <20211116151317.2691125-1-philmd@redhat.com> MIME-Version: 1.0 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=philmd@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1637075649670100001 Signed-off-by: Philippe Mathieu-Daud=C3=A9 --- docs/devel/style.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/devel/style.rst b/docs/devel/style.rst index 415a6b9d700..21f0f213193 100644 --- a/docs/devel/style.rst +++ b/docs/devel/style.rst @@ -602,16 +602,16 @@ Error handling and reporting Reporting errors to the human user ---------------------------------- =20 -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. +Do not use ``printf()``, ``fprintf()`` or ``monitor_printf()``. Instead, = use +``error_report()`` or ``error_vreport()`` from error-report.h. This ensur= es +the error is reported in the right place (current monitor or ``stderr``), = and +in a uniform format. =20 -Use error_printf() & friends to print additional information. +Use ``error_printf()`` & friends to print additional information. =20 -error_report() prints the current location. In certain common cases +``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 +automatically. To manipulate it manually, use the ``loc_*()`` from error-report.h. =20 Propagating errors @@ -621,7 +621,7 @@ An error can't always be reported to the user right whe= re 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. =20 -The most flexible one is Error objects. See error.h for usage +The most flexible one is ``Error`` objects. See error.h for usage information. =20 Use the simplest suitable method to communicate success / failure to @@ -631,10 +631,10 @@ error, non-negative / -errno, non-null / null, or Err= or 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 ``*````*`` para= meter. +the eyes than propagating an Error object through an ``Error **`` paramete= r. =20 Example: when a function's callers need to report details on failure -only the function really knows, use Error ``*````*``, and set suitable err= ors. +only the function really knows, use ``Error **``, and set suitable errors. =20 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 @@ -643,17 +643,17 @@ consumes the error returned. Handling errors --------------- =20 -Calling exit() is fine when handling configuration errors during +Calling ``exit()`` is fine when handling configuration errors during startup. It's problematic during normal operation. In particular, -monitor commands should never exit(). +monitor commands should never ``exit()``. =20 -Do not call exit() or abort() to handle an error that can be triggered +Do not call ``exit()`` or ``abort()`` to handle an error that can be trigg= ered by the guest (e.g., some unimplemented corner case in guest code translation or device emulation). Guests should not be able to terminate QEMU. =20 -Note that &error_fatal is just another way to exit(1), and &error_abort -is just another way to abort(). +Note that ``&error_fatal`` is just another way to ``exit(1)``, and +``&error_abort`` is just another way to ``abort()``. =20 =20 trace-events style --=20 2.31.1