From nobody Mon Feb 9 16:34:23 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=1637247452; cv=none; d=zohomail.com; s=zohoarc; b=adSvmYQBFIIGQLPHECQKprkHI1a7rp9Vea8GEUCMK2YiupCs86mOIUXxS4iyznXOkEVX3t4+Vk4Wkji5v9TgeZG/bsU2jrn5bV6s1uYTxjcu2l4toIwLxaMjTm8pmyiyRfa0iYscKRgC1fzMYP0xnLF9Zxv698/FKWC/2f1a9Tg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1637247452; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:To; bh=/HpEathA5riapQobuv/wwQs6HF4NNRoprJj+KElllXM=; b=WqhTiXKhxAewSE2U0zrfse9GXoyeQX6rx4WGZ+I/AH+d/TiFZdsEeZxAb0ajD/9a8a1b5W406HqYm/hXLFl1qXqrtgTKSvjFY1szeFX6f4XrXIVcZg051+Q04OWJQwdM9cqxVTD2V5S8KBaeYjwrF3u+N08WdF4oeOM/wacS5s0= 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 1637247452144286.69840722504125; Thu, 18 Nov 2021 06:57:32 -0800 (PST) Received: from mail-wm1-f72.google.com (mail-wm1-f72.google.com [209.85.128.72]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-61-5lrZ8SuPNn6TkKhRCXfw9w-1; Thu, 18 Nov 2021 09:57:28 -0500 Received: by mail-wm1-f72.google.com with SMTP id l6-20020a05600c4f0600b0033321934a39so3223878wmq.9 for ; Thu, 18 Nov 2021 06:57:27 -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 38sm119011wrc.1.2021.11.18.06.57.25 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 18 Nov 2021 06:57:26 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1637247451; 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=/HpEathA5riapQobuv/wwQs6HF4NNRoprJj+KElllXM=; b=TFpZuF8/iVSxO9iwMszKlDzVC5VDD3/jRvQyfXNJEywrwBHEoKBTjkeoYtgv4XbRbPjdqQ OpHdAZK2ERzdyyy9J/CTdCQjdUwcMtJRGI1/+rRWv4iCkrEkQLw0o6a2EC2fy/4YRZhbAj xpP2zZSDJMYd2y3ApF4a0pMd89+BTCY= X-MC-Unique: 5lrZ8SuPNn6TkKhRCXfw9w-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=/HpEathA5riapQobuv/wwQs6HF4NNRoprJj+KElllXM=; b=ltOLA6MWrTyytEo8TyASV9SaTKmDS4NdqBoiBU7R16cE7cgMrOUPFaNOtGpk4EH4hH Z3MfcfXKjeG64l8/B/sJWtxxuo5aJwBtZFjbBr5TiwQiMqzvAnJiA87zvATWHF/8m3tO /i6Ifw0lrGeVyYHjNKngkEfuBijqDvlZuVF/nwMatnE6YQgfgiw1yGj+VKJBZHgUvNu7 OMBhfZ8nXVluIrfs/WB517YmeFlPZSWl3hr7Y4nZKENTxy3f/1NDdHxTWzJbeBGYWu/i rulg1aCykhPneeVNxo7g5h9TJLduIEEX2wv7iU06gLFYmvD1TCSmTVUg0XP/x1zF4H7k pnhQ== X-Gm-Message-State: AOAM533XGlYjMIi+DLcZAb81t+TPIAy3/WIS8jqZ0BfE1RbUxozsz+6F nvEfDscu50AlXnicmktUW/DQzcFvUOdvxVF37/mjnwNjtc40HYApZdWLZmKd5ZMepDFavWG4Axs C62XJtQBj/IY3Dg== X-Received: by 2002:adf:dd0a:: with SMTP id a10mr32197008wrm.60.1637247446618; Thu, 18 Nov 2021 06:57:26 -0800 (PST) X-Google-Smtp-Source: ABdhPJy9540F1z7RYJ5+NhbiHpVspcg/n+EsQJDIPIvg6LAIdPON8lY1Ry++DNhW9b/FKJUIJYSG8Q== X-Received: by 2002:adf:dd0a:: with SMTP id a10mr32196978wrm.60.1637247446390; Thu, 18 Nov 2021 06:57:26 -0800 (PST) From: =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= To: qemu-devel@nongnu.org Cc: Markus Armbruster , Peter Maydell , Darren Kenny , "Daniel P . Berrange" , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Subject: [PATCH-for-6.2? v2 2/5] docs/devel/style: Improve Error** functions rST rendering Date: Thu, 18 Nov 2021 15:57:13 +0100 Message-Id: <20211118145716.4116731-3-philmd@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20211118145716.4116731-1-philmd@redhat.com> References: <20211118145716.4116731-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: 1637247453488100001 Signed-off-by: Philippe Mathieu-Daud=C3=A9 Reviewed-by: Alex Benn=C3=A9e --- 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 3e519dc6ade..1a23021bc3e 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