From nobody Mon Feb 9 16:01:34 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=1637075610; cv=none; d=zohomail.com; s=zohoarc; b=BYMaZ8+N8QR2GktOgaMnzNWycr/qCiQf+I3yfDrR1cfbFSSRoe5X/QCKS8mJFJmPqMQ8iQruf8OcSzKuy4GdSd6uhVKsNP6q3ma0fayUWfTHzvZSMd8FdkYF1hSK/vbEDWOpfsEB4B8IZVBHjD4bgkI+veBwwmyMwkabiHGSsqI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1637075610; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:To; bh=I9uHr78Bd1hAdWgud7dJDANsSM/mJBoe5Km+LIqe2vI=; b=CkIE+LGRmxOIB6hpjwv8iWsWVkQj3yHoFjTvYfopZXUvyllEGANu9s41/0XbCp3aMMy++hZo+b6NVx5GxHUKTLo++/TEh7MLlX1TRNmk0ejhcUkQm/sHFLmF9EOStAEQ+PxaGuWbYjewO3Q0U+f1zT/On6HNu2kEiqXCUYuCtCI= 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 1637075610632471.23222287564636; Tue, 16 Nov 2021 07:13:30 -0800 (PST) Received: from mail-wr1-f69.google.com (mail-wr1-f69.google.com [209.85.221.69]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-297-9jbaa0W5PDuAZEYKylcenQ-1; Tue, 16 Nov 2021 10:13:26 -0500 Received: by mail-wr1-f69.google.com with SMTP id a2-20020a5d4d42000000b0017b3bcf41b9so4568324wru.23 for ; Tue, 16 Nov 2021 07:13:25 -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 ay21sm2876646wmb.7.2021.11.16.07.13.23 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Nov 2021 07:13:23 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1637075609; 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=I9uHr78Bd1hAdWgud7dJDANsSM/mJBoe5Km+LIqe2vI=; b=OMifRM3zsQ+FhKCDhCVaW6o+AElqhLA82j1w5to4RLkbnUQQuM1Be5XZTgx8UpzaNhvr2+ Nf4eHla926WILiJwNucRO7AeodbK+pN4mjinh5/DEQANhijWd+hZm2v9GN+xp1puIPM+mI GSdbJfzo7/4uYfB2EIlbfq82MlPKv48= X-MC-Unique: 9jbaa0W5PDuAZEYKylcenQ-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=I9uHr78Bd1hAdWgud7dJDANsSM/mJBoe5Km+LIqe2vI=; b=zT5ebn+CRZsZePOahzR84MT8ie9SOuZnSgImIDrq+ZsR+EOt79XGnBkbQSCCY3G7BR KyPYu86TMOoQjx8AW4JCroiY0I9APe6htHd1CwC78jXhYmyABffDLNts6CyeSNVe+1NM R3C6YPmMfzdMZ++I6kpPoJWgkLxTDf4WrILPmVh3mHfsN14bZWi4MnK0y8/6NMfnt77F mTOEvGAY7FjKSPBdPG9h3/a/1dw+DNxiTc17BnOMQ1jYD11E9CY8QMvHeMU5fxxQtL9T yN1zSTZdGOpXSE9FG0pumKaJa31cD1vluBD7VtOlpQDIA1Gk06RuLLs5zBhVf3fxxplK di7A== X-Gm-Message-State: AOAM530Ldl9VCJ80URr2i2As6tyYHf0ZP8kO2fg/0u79SmzsRjyy/s8Q oXskYUYaZZq8z5Ha4+mH3iDHVvSKjoM900bobaH1HWaRiR3j1UEi0lirKTIBDPRehduh/4ltXNT wE/x+p0qjOjuJIQ== X-Received: by 2002:a1c:7714:: with SMTP id t20mr60375342wmi.139.1637075604678; Tue, 16 Nov 2021 07:13:24 -0800 (PST) X-Google-Smtp-Source: ABdhPJwQYAhFyLdU4iFhA7VfEwTgn75yNRIJwDNqnRdl+aOTf1vwgs7GNXm8/DtcNIOrpkLojnQBIg== X-Received: by 2002:a1c:7714:: with SMTP id t20mr60375296wmi.139.1637075604394; Tue, 16 Nov 2021 07:13:24 -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? 1/3] docs/devel/style: Improve GLib functions rST rendering Date: Tue, 16 Nov 2021 16:13:15 +0100 Message-Id: <20211116151317.2691125-2-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: 1637075647315100001 Signed-off-by: Philippe Mathieu-Daud=C3=A9 --- docs/devel/style.rst | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/devel/style.rst b/docs/devel/style.rst index 260e3263fa0..415a6b9d700 100644 --- a/docs/devel/style.rst +++ b/docs/devel/style.rst @@ -413,13 +413,14 @@ multiple exist paths you can also improve the readabi= lity of the code by using ``g_autofree`` and related annotations. See :ref:`autofree-ref` for more details. =20 -Calling ``g_malloc`` with a zero size is valid and will return NULL. +Calling ``g_malloc`` with a zero size is valid and will return ``NULL``. =20 Prefer ``g_new(T, n)`` instead of ``g_malloc(sizeof(T) * n)`` for the foll= owing reasons: =20 -* It catches multiplication overflowing size_t; -* It returns T ``*`` instead of void ``*``, letting compiler catch more ty= pe errors. +* It catches multiplication overflowing ``size_t``; +* It returns ``T *`` instead of ``void *``, letting compiler catch more ty= pe + errors. =20 Declarations like =20 @@ -444,14 +445,14 @@ use this similar function when possible, but note its= different signature: =20 void pstrcpy(char *dest, int dest_buf_size, const char *src) =20 -Don't use strcat because it can't check for buffer overflows, but: +Don't use ``strcat`` because it can't check for buffer overflows, but: =20 .. code-block:: c =20 char *pstrcat(char *buf, int buf_size, const char *s) =20 -The same limitation exists with sprintf and vsprintf, so use snprintf and -vsnprintf. +The same limitation exists with ``sprintf`` and ``vsprintf``, so use +``snprintf`` and ``vsnprintf``. =20 QEMU provides other useful string functions: =20 @@ -464,8 +465,8 @@ QEMU provides other useful string functions: There are also replacement character processing macros for isxyz and toxyz, so instead of e.g. isalnum you should use qemu_isalnum. =20 -Because of the memory management rules, you must use g_strdup/g_strndup -instead of plain strdup/strndup. +Because of the memory management rules, you must use ``g_strdup/g_strndup`` +instead of plain ``strdup/strndup``. =20 Printf-style functions =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -524,10 +525,10 @@ automatic cleanup: =20 Most notably: =20 -* g_autofree - will invoke g_free() on the variable going out of scope +* ``g_autofree`` - will invoke ``g_free()`` on the variable going out of s= cope =20 -* g_autoptr - for structs / objects, will invoke the cleanup func created - by a previous use of G_DEFINE_AUTOPTR_CLEANUP_FUNC. This is +* ``g_autoptr`` - for structs / objects, will invoke the cleanup func crea= ted + by a previous use of ``G_DEFINE_AUTOPTR_CLEANUP_FUNC``. This is supported for most GLib data types and GObjects =20 For example, instead of @@ -551,7 +552,7 @@ For example, instead of return ret; } =20 -Using g_autofree/g_autoptr enables the code to be written as: +Using ``g_autofree/g_autoptr`` enables the code to be written as: =20 .. code-block:: c =20 @@ -569,13 +570,13 @@ Using g_autofree/g_autoptr enables the code to be wri= tten as: While this generally results in simpler, less leak-prone code, there are still some caveats to beware of =20 -* Variables declared with g_auto* MUST always be initialized, +* Variables declared with ``g_auto*`` MUST always be initialized, otherwise the cleanup function will use uninitialized stack memory =20 -* If a variable declared with g_auto* holds a value which must +* If a variable declared with ``g_auto*`` holds a value which must live beyond the life of the function, that value must be saved and the original variable NULL'd out. This can be simpler using - g_steal_pointer + ``g_steal_pointer`` =20 =20 .. code-block:: c --=20 2.31.1