Bug 205345

Summary:	rtnetlink.7 man page missing documentation for ndmsg struct's ndm_type field
Product:	Documentation	Reporter:	Ossi Herrala (oherrala)
Component:	man-pages	Assignee:	documentation_man-pages (documentation_man-pages)
Status:	NEW ---
Severity:	normal	CC:	mtk.manpages, oherrala
Priority:	P1
Hardware:	All
OS:	Linux
Kernel Version:		Subsystem:
Regression:	No	Bisected commit-id:

Description Ossi Herrala 2019-10-28 09:41:11 UTC

The struct ndmsg (as defined in linux/neighbour.h header file) is missing documentation of ndm_type field in rtnetlink.7 man page.

My research so far for usage of ndm_type:

A long while ago (for example http://www.skrenta.com/rt/man/rtnetlink.4.html) the field was documented as:

       Valid ndm_type values are: NDA_UNSPEC  for  unknown  type,
       NDA_DST  for  a  neighbour cache network layer destination
       address,  ND_LLADDR  for  a  neighbour  cache  link  layer
       address,  ND_CACHEINFO  for  cache  statistics  (a  struct
       nda_cacheinfo  header   follows).

But this has been removed already some time ago. Maybe before man-pages 1.70 release, since this is where the current Git repository starts. I couldn't find commit message indicating why it's removed.

Then there has been a patch for Linux (https://lore.kernel.org/patchwork/patch/487044/) which seem to indicate `RTN_` enum is the correct one to use here.

Comment 1 Michael Kerrisk 2020-05-04 07:18:13 UTC

(In reply to Ossi Herrala from comment #0)
> The struct ndmsg (as defined in linux/neighbour.h header file) is missing
> documentation of ndm_type field in rtnetlink.7 man page.

Yes.

> My research so far for usage of ndm_type:
> 
> A long while ago (for example
> http://www.skrenta.com/rt/man/rtnetlink.4.html) the field was documented as:
> 
>        Valid ndm_type values are: NDA_UNSPEC  for  unknown  type,
>        NDA_DST  for  a  neighbour cache network layer destination
>        address,  ND_LLADDR  for  a  neighbour  cache  link  layer
>        address,  ND_CACHEINFO  for  cache  statistics  (a  struct
>        nda_cacheinfo  header   follows).
> 
> But this has been removed already some time ago.

Actually, it was never in the upstream manual page. I don't know where this text came from. Perhaps a distro-specific patch? In the upstream project, there was never a page called rtnetlink.4

> Maybe before man-pages 1.70
> release, since this is where the current Git repository starts. I couldn't
> find commit message indicating why it's removed.

(See above.)

> Then there has been a patch for Linux
> (https://lore.kernel.org/patchwork/patch/487044/) which seem to indicate
> `RTN_` enum is the correct one to use here.

I do not know. Perhaps you are right, but there's not really enough info in that mail for one to be sure.