netdev - Re: [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs)

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20220929084715.3c9626f7@kernel.org>
Date:   Thu, 29 Sep 2022 08:47:15 -0700
From:   Jakub Kicinski <kuba@...nel.org>
To:     Guillaume Nault <gnault@...hat.com>
Cc:     davem@...emloft.net, netdev@...r.kernel.org, edumazet@...gle.com,
        pabeni@...hat.com, robh@...nel.org, johannes@...solutions.net,
        ecree.xilinx@...il.com, stephen@...workplumber.org, sdf@...gle.com,
        f.fainelli@...il.com, fw@...len.de, linux-doc@...r.kernel.org,
        razor@...ckwall.org, nicolas.dichtel@...nd.com
Subject: Re: [PATCH net-next 1/6] docs: add more netlink docs (incl. spec
 docs)

On Thu, 29 Sep 2022 17:11:45 +0200 Guillaume Nault wrote:
> Maybe we can make this more explicit.
> Something like:
> 
> -Having to rely on ``NLM_F_ECHO`` is a hack, not a valid design.
> +Users shouldn't have to use ``NLM_F_ECHO`` to get a handle on the created
> +object.
> 
> (or keep both sentences, I feel they fit well together).
> 
> Then maybe explain in the next section why support for NLM_F_ECHO is
> desirable anyway:
> 
>  Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
> -to take effect.
> +to take effect. This is usefull for programs that need precise feedback from
> + the kernel (for example for logging purpose).

Folded it a little bit:

diff --git a/Documentation/core-api/netlink.rst b/Documentation/core-api/netlink.rst
index 2a97f765d0d2..7b98dd48a6af 100644
--- a/Documentation/core-api/netlink.rst
+++ b/Documentation/core-api/netlink.rst
@@ -37,15 +37,15 @@ added whether it replies with a full message or only an ACK is uAPI and
 cannot be changed. It's better to err on the side of replying.
 
 Specifically NEW and ADD commands should reply with information identifying
-the created object such as the allocated object's ID.
-
-Having to rely on ``NLM_F_ECHO`` is a hack, not a valid design.
+the created object such as the allocated object's ID (without having to
+resort to using ``NLM_F_ECHO``).
 
 NLM_F_ECHO
 ----------
 
 Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
-to take effect.
+to take effect.  This is useful for programs that need precise feedback
+from the kernel (for example for logging purposes).
 
 Support dump consistency
 ------------------------