Hi Michael,
> I'm a little unclear. Do you mean that the manual page should include
> the additional comments?
Yes, this is true. It must be clear that Netlink error responses,
i.e. messages with type NLMSG_ERROR (0x2), can be longer than
sizeof(struct nlmsgerr). In certain circumstances the payload can be longer.
I appended a patch. If you need further information or the patch in
a different format, I'm looking forward to solving this with you.
diff --git a/man7/netlink.7 b/man7/netlink.7
index c69bb62bf..c8ca5da28 100644
--- a/man7/netlink.7
+++ b/man7/netlink.7
@@ -189,13 +189,25 @@ message signals an error and the payload contains an
.I nlmsgerr
structure,
.B NLMSG_DONE
-message terminates a multipart message.
+message terminates a multipart message. Error messages get the
+original request appened, unless the user requests to cap the
+error message, and get extra error data if requested.
.PP
.in +4n
.EX
struct nlmsgerr {
int error; /* Negative errno or 0 for acknowledgements */
struct nlmsghdr msg; /* Message header that caused the error */
+ /*
+ * followed by the message contents unless NETLINK_CAP_ACK was set
+ * or the ACK indicates success (error == 0).
+ * For example Generic Netlink message with attributes.
+ * message length is aligned with NLMSG_ALIGN()
+ */
+ /*
+ * followed by TLVs defined in enum nlmsgerr_attrs
+ * if NETLINK_EXT_ACK was set
+ */
};
.EE
.in
I also attached the patch as a file.
Am Sa., 20. Feb. 2021 um 21:07 Uhr schrieb Michael Kerrisk (man-pages)
<mtk.manpages@xxxxxxxxx>:
>
> Hi Philipp,
>
> On Sat, 20 Feb 2021 at 16:25, Philipp Schuster <phip1611@xxxxxxxxx> wrote:
> >
> > To whom it may concern,
> > I'd like to inform you about a bug in the Netlink(7) man page [0].
> >
> > It describes struct nlmsgerr the following way:
> >
> > struct nlmsgerr {
> > int error; /* Negative errno or 0 for acknowledgements */
> > struct nlmsghdr msg; /* Message header that caused the error */
> > };
> >
> > but according to Kernel code [1] [2] [3] it actually should be:
> >
> > struct nlmsgerr {
> > int error; /* Negative errno or 0 for acknowledgements */
> > struct nlmsghdr msg; /* Message header that caused the error */
> > /*
> > * followed by the message contents unless NETLINK_CAP_ACK was set
> > * or the ACK indicates success (error == 0)
> > * message length is aligned with NLMSG_ALIGN()
> > */
> > /*
> > * followed by TLVs defined in enum nlmsgerr_attrs
> > * if NETLINK_EXT_ACK was set
> > */
> > };
> >
> > This discrepancy led to errors implementing at least a Rust library which
> > made wrong assumptions about the returned value.
>
> I'm a little unclear. Do you mean that the manual page should include
> the additional comments?
>
> Thanks,
>
> Michael
>
> > [0] https://man7.org/linux/man-pages/man7/netlink.7.html
> > [1] https://elixir.bootlin.com/linux/v5.11/source/include/uapi/linux/netlink.h#L112
> > [2] https://elixir.bootlin.com/linux/v5.11/source/net/netlink/af_netlink.c#L2416
> > [3] https://elixir.bootlin.com/linux/v5.11/source/net/netlink/af_netlink.c#L2440
> >
> >
> > Kind regards
> > --
> > Philipp Schuster
>
>
>
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/
--
Philipp Schuster
diff --git a/man7/netlink.7 b/man7/netlink.7
index c69bb62bf..cf03e1c56 100644
--- a/man7/netlink.7
+++ b/man7/netlink.7
@@ -189,13 +189,25 @@ message signals an error and the payload contains an
.I nlmsgerr
structure,
.B NLMSG_DONE
-message terminates a multipart message.
+message terminates a multipart message. Error messages get the
+original request appended, unless the user requests to cap the
+error message, and get extra error data if requested.
.PP
.in +4n
.EX
struct nlmsgerr {
int error; /* Negative errno or 0 for acknowledgements */
struct nlmsghdr msg; /* Message header that caused the error */
+ /*
+ * followed by the message contents unless NETLINK_CAP_ACK was set
+ * or the ACK indicates success (error == 0).
+ * For example Generic Netlink message with attributes.
+ * message length is aligned with NLMSG_ALIGN()
+ */
+ /*
+ * followed by TLVs defined in enum nlmsgerr_attrs
+ * if NETLINK_EXT_ACK was set
+ */
};
.EE
.in
