I found the PKTINFO docs pretty confusing, so I tried clarifying them:
- being more specific about each field in the struct
  (e.g. "local address of the packet" for a received packet could've
  been interpreted in myriad ways),
- making the differences between sendmsg(2)'s and recvmsg(2)'s handling
  of that struct more explicit,
- and some other slight rewording to make it (IMO) more readable - I cut
  out most of a paragraph that wasn't really saying anything, etc.

I'm not sure if this should even be documented in ip(7) together with
the other sockopts, though?  sendmsg(2)'s handling of in_pktinfo is
completely unrelated to the IP_PKTINFO sockopt.  Documenting it in its
own manual page would also give us more room for subsection headings and
other formatting, examples, etc - instead of trying to cram it into
what's already an enormous manpage.

Same goes for some of the other more complex sockopts, I guess.


PS. sorry for not signing this email, but neomutt didn't want to
cooperate :/  I'll try to figure it out for any followup patches.


Jakub Głogowski (2):
  man/man7/ip.7: Clarify PKTINFO's semantics depending on packet
    direction
  man/man7/ip.7: Reword IP_PKTINFO's description

 man/man7/ip.7 | 57 +++++++++++++++++++++++++++------------------------
 1 file changed, 30 insertions(+), 27 deletions(-)

-- 
2.47.3

Hi Jakub,

On Fri, Nov 14, 2025 at 03:29:29PM +0100, Jakub Głogowski wrote:
> I found the PKTINFO docs pretty confusing, so I tried clarifying them:
> - being more specific about each field in the struct
>   (e.g. "local address of the packet" for a received packet could've
>   been interpreted in myriad ways),
> - making the differences between sendmsg(2)'s and recvmsg(2)'s handling
>   of that struct more explicit,
> - and some other slight rewording to make it (IMO) more readable - I cut
>   out most of a paragraph that wasn't really saying anything, etc.
> 
> I'm not sure if this should even be documented in ip(7) together with
> the other sockopts, though?  sendmsg(2)'s handling of in_pktinfo is
> completely unrelated to the IP_PKTINFO sockopt.  Documenting it in its
> own manual page would also give us more room for subsection headings and
> other formatting, examples, etc - instead of trying to cram it into
> what's already an enormous manpage.
> 
> Same goes for some of the other more complex sockopts, I guess.

Do you suggest moving each socket option to a manual page under
man2const/?  I think I agree with that.  There's precedent, and it makes
the pages more readable.

I'll try to do that soon.  I'll ping you when I've finished, in case you
want to apply further changes.

> PS. sorry for not signing this email, but neomutt didn't want to
> cooperate :/  I'll try to figure it out for any followup patches.

Ok.


Have a lovely day!
Alex

> Jakub Głogowski (2):
>   man/man7/ip.7: Clarify PKTINFO's semantics depending on packet
>     direction
>   man/man7/ip.7: Reword IP_PKTINFO's description
> 
>  man/man7/ip.7 | 57 +++++++++++++++++++++++++++------------------------
>  1 file changed, 30 insertions(+), 27 deletions(-)
> 
> -- 
> 2.47.3
> 

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

On 11/18/25 14:51, Alejandro Colomar wrote:
> Do you suggest moving each socket option to a manual page under
> man2const/?  I think I agree with that.  There's precedent, and it makes
> the pages more readable.

In general - yes, definitely!

However, struct in_pktinfo can be passed to sendmsg even if IP_PKTINFO 
isn't set, so I don't think it would make sense to document it in e.g. 
IP_PKTINFO(2const) - it should probably get its own manpage in man2type.
That option, in turn, only makes sense in the context of that struct, so 
I think it should probably be documented in in_pktinfo(2type).

This would /kinda/ be like how e.g. PA_INT(3const) points to 
printf.h(3head), I guess?

I'd be happy to try writing that manpage if you think this approach 
makes sense :)

Thanks,
dzwdz

Hi dzwdz,

On Tue, Nov 25, 2025 at 02:50:19AM +0100, dzwdz wrote:
> On 11/18/25 14:51, Alejandro Colomar wrote:
> > Do you suggest moving each socket option to a manual page under
> > man2const/?  I think I agree with that.  There's precedent, and it makes
> > the pages more readable.
> 
> In general - yes, definitely!

Done.  I've split ip(7) into a large amount of small pages this weekend.
Please have a look at them and suggest any improvements you consider
appropriate.  ;)

> However, struct in_pktinfo can be passed to sendmsg even if IP_PKTINFO isn't
> set, so I don't think it would make sense to document it in e.g.
> IP_PKTINFO(2const) - it should probably get its own manpage in man2type.
> That option, in turn, only makes sense in the context of that struct, so I
> think it should probably be documented in in_pktinfo(2type).
> 
> This would /kinda/ be like how e.g. PA_INT(3const) points to
> printf.h(3head), I guess?
> 
> I'd be happy to try writing that manpage if you think this approach makes
> sense :)

Yup, it makes sense.  :)

I'll simplify your work by doing some initial changes.  Please wait
a couple of days before starting, so I can finish doing that.


Have a lovely day!
Alex

> 
> Thanks,
> dzwdz




-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

Hi Jakub,

On Tue, Nov 25, 2025 at 01:13:05PM +0100, Alejandro Colomar wrote:
> Hi dzwdz,
> 
> On Tue, Nov 25, 2025 at 02:50:19AM +0100, dzwdz wrote:
> > On 11/18/25 14:51, Alejandro Colomar wrote:
> > > Do you suggest moving each socket option to a manual page under
> > > man2const/?  I think I agree with that.  There's precedent, and it makes
> > > the pages more readable.
> > 
> > In general - yes, definitely!
> 
> Done.  I've split ip(7) into a large amount of small pages this weekend.
> Please have a look at them and suggest any improvements you consider
> appropriate.  ;)
> 
> > However, struct in_pktinfo can be passed to sendmsg even if IP_PKTINFO isn't
> > set, so I don't think it would make sense to document it in e.g.
> > IP_PKTINFO(2const) - it should probably get its own manpage in man2type.
> > That option, in turn, only makes sense in the context of that struct, so I
> > think it should probably be documented in in_pktinfo(2type).
> > 
> > This would /kinda/ be like how e.g. PA_INT(3const) points to
> > printf.h(3head), I guess?
> > 
> > I'd be happy to try writing that manpage if you think this approach makes
> > sense :)
> 
> Yup, it makes sense.  :)
> 
> I'll simplify your work by doing some initial changes.  Please wait
> a couple of days before starting, so I can finish doing that.

Done.  Please fetch the latest changes, and do what you consider
appropriate.  :)


Have a lovely night!
Alex

> 
> 
> Have a lovely day!
> Alex
> 
> > 
> > Thanks,
> > dzwdz
> 
> 
> 
> 
> -- 
> <https://www.alejandro-colomar.es>
> Use port 80 (that is, <...:80/>).



-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).