[PATCH] rtnetlink.7: Document struct ifa_cacheinfo

[PATCH] rtnetlink.7: Document struct ifa_cacheinfo

[Alex Henrie]

struct ifa_cacheinfo contains the address's creation time, update time,
preferred lifetime, and valid lifetime. See
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60

Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>
---
 man/man7/rtnetlink.7 | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7
index 86ed459bb..b05654315 100644
--- a/man/man7/rtnetlink.7
+++ b/man/man7/rtnetlink.7
@@ -176,7 +176,15 @@ IFA_BROADCAST:raw protocol address:broadcast address
 IFA_ANYCAST:raw protocol address:anycast address
 IFA_CACHEINFO:struct ifa_cacheinfo:Address information
 .TE
-.\" FIXME Document struct ifa_cacheinfo
+.IP
+.EX
+struct ifa_cacheinfo {
+    __u32 ifa_prefered; /* Preferred lifetime in seconds, -1 = forever */
+    __u32 ifa_valid;    /* Valid lifetime in seconds, -1 = forever */
+    __u32 cstamp;       /* Creation timestamp in hundredths of seconds */
+    __u32 tstamp;       /* Update timestamp in hundredths of seconds */
+};
+.EE
 .TP
 .B RTM_NEWROUTE
 .TQ
-- 
2.47.0

Re: [PATCH] rtnetlink.7: Document struct ifa_cacheinfo

[Kuniyuki Iwashima]

From: Alex Henrie <alexhenrie24@gmail.com>
Date: Mon,  4 Nov 2024 21:14:20 -0700
> struct ifa_cacheinfo contains the address's creation time, update time,
> preferred lifetime, and valid lifetime. See
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60
> 
> Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>
> ---
>  man/man7/rtnetlink.7 | 10 +++++++++-
>  1 file changed, 9 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7
> index 86ed459bb..b05654315 100644
> --- a/man/man7/rtnetlink.7
> +++ b/man/man7/rtnetlink.7
> @@ -176,7 +176,15 @@ IFA_BROADCAST:raw protocol address:broadcast address
>  IFA_ANYCAST:raw protocol address:anycast address
>  IFA_CACHEINFO:struct ifa_cacheinfo:Address information
>  .TE
> -.\" FIXME Document struct ifa_cacheinfo
> +.IP
> +.EX
> +struct ifa_cacheinfo {
> +    __u32 ifa_prefered; /* Preferred lifetime in seconds, -1 = forever */
> +    __u32 ifa_valid;    /* Valid lifetime in seconds, -1 = forever */

-1 should be rather 0xFFFFFFFF (INFINITY_LIFE_TIME) as it's unsigned.

Also, it would be nice to mention that ifa_prefered must be less than
or equal to ifa_valid (ifa_prefered <= ifa_valid) and 0 is invalid for
ifa_valid.

  0 <= ifa_prefered <= ifa_valid
  0 < ifa_valid <= 0xFFFFFFFF


> +    __u32 cstamp;       /* Creation timestamp in hundredths of seconds */
> +    __u32 tstamp;       /* Update timestamp in hundredths of seconds */
> +};

Maybe the explanation can follow the struct here as sentences.


> +.EE
>  .TP
>  .B RTM_NEWROUTE
>  .TQ
> -- 
> 2.47.0

Re: [PATCH] rtnetlink.7: Document struct ifa_cacheinfo

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2790 bytes --]

Hi Alex, Kuniyuki, Branden,

On Mon, Nov 04, 2024 at 09:53:38PM GMT, Kuniyuki Iwashima wrote:
> From: Alex Henrie <alexhenrie24@gmail.com>
> Date: Mon,  4 Nov 2024 21:14:20 -0700
> > struct ifa_cacheinfo contains the address's creation time, update time,
> > preferred lifetime, and valid lifetime. See

We use two spaces after period (the correct amount).  :)
(I'm thinking we probably want to document something about it in
 man-pages(7).  Branden, do you want to send a patch about it?  I want
 to include the references you showed to me, and you probably remember
 better those links.)

> > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60

Please use this format for links:

Link: <http://example.com>

> > 
> > Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>
> > ---
> >  man/man7/rtnetlink.7 | 10 +++++++++-
> >  1 file changed, 9 insertions(+), 1 deletion(-)
> > 
> > diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7
> > index 86ed459bb..b05654315 100644
> > --- a/man/man7/rtnetlink.7
> > +++ b/man/man7/rtnetlink.7
> > @@ -176,7 +176,15 @@ IFA_BROADCAST:raw protocol address:broadcast address
> >  IFA_ANYCAST:raw protocol address:anycast address
> >  IFA_CACHEINFO:struct ifa_cacheinfo:Address information
> >  .TE
> > -.\" FIXME Document struct ifa_cacheinfo
> > +.IP
> > +.EX

Which include provides the structure?

> > +struct ifa_cacheinfo {
> > +    __u32 ifa_prefered; /* Preferred lifetime in seconds, -1 = forever */
> > +    __u32 ifa_valid;    /* Valid lifetime in seconds, -1 = forever */
> 
> -1 should be rather 0xFFFFFFFF (INFINITY_LIFE_TIME) as it's unsigned.

I prefer UINT32_MAX over 0xF...F, which might be unclear how many Fs it
has.

> Also, it would be nice to mention that ifa_prefered must be less than
> or equal to ifa_valid (ifa_prefered <= ifa_valid) and 0 is invalid for
> ifa_valid.
> 
>   0 <= ifa_prefered <= ifa_valid
>   0 < ifa_valid <= 0xFFFFFFFF

You may want to use interval notation, like we do in timespec(3type).

     struct timespec {
         time_t     tv_sec;   /* Seconds */
         /* ... */  tv_nsec;  /* Nanoseconds [0, 999'999'999] */
     };

It might also be interesting to add a separate manual page for the type,
and reference it here.  Otherwise, the page starts getting fatty.

Have a lovely day!
Alex

> 
> 
> > +    __u32 cstamp;       /* Creation timestamp in hundredths of seconds */
> > +    __u32 tstamp;       /* Update timestamp in hundredths of seconds */
> > +};
> 
> Maybe the explanation can follow the struct here as sentences.
> 
> 
> > +.EE
> >  .TP
> >  .B RTM_NEWROUTE
> >  .TQ
> > -- 
> > 2.47.0
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] rtnetlink.7: Document struct ifa_cacheinfo

[Stephen Hemminger]

[-- Attachment #1: Type: text/plain, Size: 977 bytes --]

On Tue, 5 Nov 2024 12:33:48 +0100
Alejandro Colomar <alx@kernel.org> wrote:

> Hi Alex, Kuniyuki, Branden,
> 
> On Mon, Nov 04, 2024 at 09:53:38PM GMT, Kuniyuki Iwashima wrote:
> > From: Alex Henrie <alexhenrie24@gmail.com>
> > Date: Mon,  4 Nov 2024 21:14:20 -0700  
> > > struct ifa_cacheinfo contains the address's creation time, update time,
> > > preferred lifetime, and valid lifetime. See  
> 
> We use two spaces after period (the correct amount).  :)

Double spacing after period is a leftover from using typewriters.
Modern usage is single space after period.

https://www.grammarly.com/blog/punctuation-capitalization/spaces-after-period/

	These days most contemporary style guides also recommend using a single space between sentences,
	including:

	The Chicago Manual of Style
	The American Psychological Association (often referred to as “APA”)
	Microsoft Manual of Style
	The Gregg Reference Manual
	The Associated Press Stylebook

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] rtnetlink.7: Document struct ifa_cacheinfo

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3659 bytes --]

Hi Stephen,

On Wed, Nov 06, 2024 at 09:18:01AM GMT, Stephen Hemminger wrote:
> On Tue, 5 Nov 2024 12:33:48 +0100
> Alejandro Colomar <alx@kernel.org> wrote:
> 
> > Hi Alex, Kuniyuki, Branden,
> > 
> > On Mon, Nov 04, 2024 at 09:53:38PM GMT, Kuniyuki Iwashima wrote:
> > > From: Alex Henrie <alexhenrie24@gmail.com>
> > > Date: Mon,  4 Nov 2024 21:14:20 -0700  
> > > > struct ifa_cacheinfo contains the address's creation time, update time,
> > > > preferred lifetime, and valid lifetime. See  
> > 
> > We use two spaces after period (the correct amount).  :)
> 
> Double spacing after period is a leftover from using typewriters.

That's a lie that modern style guides repeat believing that repeating it
will eventually make it true (as if that were possible).

The origin is much older, and ancient (pre-typewriter) books already
used different space lengths for after period.

The true reason why the 2-space tradition was replaced by the 1-space
modern rule is that editorials started hiring incompetent people, and
it seems it was hard for that incompetent people to decide if one space
or two spaces were appropriate at a given place, so they would get it
wrong.  To avoid being embarrased by frequent spacing typos, instead of
hiring competent people (which would have been expensive), they simply
changed the rules to accomodate for those incompetent ones, and told
them to unconditionally use 1 space always.  That also reduces the time
they had to think about the number of spaces being used, so they became
more efficient.

But that removes information from the text.  If a sentence ends in some
initials, it's hard to distinguish if it's the end of a sentence, or if
the sentence continues and the dot is just for the initials.  It seems
the editorials just cared about generating text faster, and didn't care
at all about readers having more difficulty in reading what they wrote
(which just shows the low quality of what they produced).

Ironically enough, studies promoted by the defendants of the one-space
rule proof that two spaces result in more readable text.  They try to
write their conclusions as if not, but if you read enough in their
experiments, you realize how blind they are with their own experiments.

And also ironically, those one-space defendants say two-space tradition
is obsolete cruft from times where mono-spaced fonts were prevalent.
Guess what?  We here still live in a world were mono-spaced fonts are
the rule (anyone reading manual pages in a terminal here?) (I guess none
of us programs with proportional fonts, right?), so even if all those
lies were true (and they are not), in our reigns two-spaces should still
be the rule.

We had some discussion about this a few years ago, and we had links for
the claims I'm making, so I want to eventually recollect those links and
document it well for all contributors to see.

> Modern usage is single space after period.
> 
> https://www.grammarly.com/blog/punctuation-capitalization/spaces-after-period/
> 
> 	These days most contemporary style guides also recommend using a single space between sentences,
> 	including:
> 
> 	The Chicago Manual of Style
> 	The American Psychological Association (often referred to as “APA”)
> 	Microsoft Manual of Style
> 	The Gregg Reference Manual
> 	The Associated Press Stylebook

Paraphrasing the Linux kernel coding style...

	First off, I’d suggest printing out a copy of the Chicago Manual
	of Style, and NOT read it.  Burn it, it’s a great symbolic
	gesture.


Have a lovely night!
Alex


-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] rtnetlink.7: Document struct ifa_cacheinfo

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2234 bytes --]

Hi Stephen,

At 2024-11-06T09:18:01-0800, Stephen Hemminger wrote:
> Alejandro Colomar <alx@kernel.org> wrote:
> > We use two spaces after period (the correct amount).  :)
> 
> Double spacing after period is a leftover from using typewriters.

No, it isn't.  See URL below.

> Modern usage is single space after period.
[...]
> 	These days most contemporary style guides also recommend using a
> 	single space between sentences, including:
> 
> 	The Chicago Manual of Style
> 	The American Psychological Association (often referred to as “APA”)
> 	Microsoft Manual of Style
> 	The Gregg Reference Manual
> 	The Associated Press Stylebook

You're not bringing any new information to the table, and you don't
appear to understand why the two-space rule is in place for _typesetting
software_.  I don't just mean *roff, but TeX as well.

Neither of these is a WYSIWYG system.  Neither of them is Markdown.

The rule is not there so that people can argue over how many space
widths should separate sentences.  The rule is there so that the
formatter knows where the boundaries between sentences _are_.

If you despise the use of two spaces between sentences in a *roff source
document, there's an easy solution: use what Alex calls "semantic
newlines".

https://www.gnu.org/software/groff/manual/groff.html.node/Sentences.html#Sentences

I furthermore remind the reader that, in GNU troff/man(7), the
intersentence space width is configurable at _rendering_ time--if the
author of the man(7) document honors one of the conventions that permits
the formatter to detect sentence boundaries.

For example...

groff_man_style(7):

Files

...

     /usr/groff/site-tmac/man.local
            Put site‐local changes and customizations into this file.

                   .\" Put only one space after the end of a sentence.
                   .ss 12 0 \" See groff(7).
                   .\" Keep pages narrow even on wide terminals.
                   .if n .if \n[LL]>80n .nr LL 80n

Arguing about the number of spaces between sentences in a discussion of
"semantic newlines" (or whatever you want to call them) is
counterproductive and wasteful of time.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] rtnetlink.7: Document struct ifa_cacheinfo

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 474 bytes --]

At 2024-11-06T18:44:08+0100, Alejandro Colomar wrote:
> Paraphrasing the Linux kernel coding style...
> 
> 	First off, I’d suggest printing out a copy of the Chicago Manual
> 	of Style, and NOT read it.  Burn it, it’s a great symbolic
> 	gesture.

I wouldn't go that far.  CMoS has much that is valuable.

Russell Harper is simply not a reliable source regarding the
inter-sentence spacing issue.  As we've seen, he has a lot of company.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] rtnetlink.7: Document struct ifa_cacheinfo

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1640 bytes --]

Hi Branden,

On Wed, Nov 06, 2024 at 11:45:31AM GMT, G. Branden Robinson wrote:
> You're not bringing any new information to the table, and you don't
> appear to understand why the two-space rule is in place for _typesetting
> software_.  I don't just mean *roff, but TeX as well.
> 
> Neither of these is a WYSIWYG system.  Neither of them is Markdown.
> 
> The rule is not there so that people can argue over how many space
> widths should separate sentences.  The rule is there so that the
> formatter knows where the boundaries between sentences _are_.

Actually, in this case it was about the use of intersentence space in a
commit message.  It was not about the contents of a manual page itself.

However, I think that loss of information is equally bad for a human
than for a type-setting system such as roff(1) or TeX.

> If you despise the use of two spaces between sentences in a *roff source
> document, there's an easy solution: use what Alex calls "semantic
> newlines".
> 
> https://www.gnu.org/software/groff/manual/groff.html.node/Sentences.html#Sentences

[...]

> Arguing about the number of spaces between sentences in a discussion of
> "semantic newlines" (or whatever you want to call them) is
> counterproductive and wasteful of time.

Hmmm, you're right.  Using semantic newlines completely removes
intersentence spaces in manual pages; we shouldn't document that in
man-pages(7).  However, for commit messages I still want to enforce
two spaces, so we should probably document it in CONTRIBUTING.d/patches.

Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] rtnetlink.7: Document struct ifa_cacheinfo

[Stephen Hemminger]

On Mon,  4 Nov 2024 21:14:20 -0700
Alex Henrie <alexhenrie24@gmail.com> wrote:

> struct ifa_cacheinfo contains the address's creation time, update time,
> preferred lifetime, and valid lifetime. See
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60
> 
> Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>
> ---
>  man/man7/rtnetlink.7 | 10 +++++++++-
>  1 file changed, 9 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7
> index 86ed459bb..b05654315 100644
> --- a/man/man7/rtnetlink.7
> +++ b/man/man7/rtnetlink.7
> @@ -176,7 +176,15 @@ IFA_BROADCAST:raw protocol address:broadcast address
>  IFA_ANYCAST:raw protocol address:anycast address
>  IFA_CACHEINFO:struct ifa_cacheinfo:Address information
>  .TE
> -.\" FIXME Document struct ifa_cacheinfo
> +.IP
> +.EX
> +struct ifa_cacheinfo {
> +    __u32 ifa_prefered; /* Preferred lifetime in seconds, -1 = forever */
> +    __u32 ifa_valid;    /* Valid lifetime in seconds, -1 = forever */
> +    __u32 cstamp;       /* Creation timestamp in hundredths of seconds */
> +    __u32 tstamp;       /* Update timestamp in hundredths of seconds */
> +};
> +.EE
>  .TP
>  .B RTM_NEWROUTE
>  .TQ

This is for man pages, not iproute2. Resetting in patchwork

Re: [PATCH] rtnetlink.7: Document struct ifa_cacheinfo

[Alex Henrie]

On Tue, Nov 5, 2024 at 4:33 AM Alejandro Colomar <alx@kernel.org> wrote:

> On Mon, Nov 04, 2024 at 09:53:38PM GMT, Kuniyuki Iwashima wrote:
> > From: Alex Henrie <alexhenrie24@gmail.com>
> > Date: Mon,  4 Nov 2024 21:14:20 -0700
> > > struct ifa_cacheinfo contains the address's creation time, update time,
> > > preferred lifetime, and valid lifetime. See
>
> We use two spaces after period (the correct amount).  :)
> (I'm thinking we probably want to document something about it in
>  man-pages(7).  Branden, do you want to send a patch about it?  I want
>  to include the references you showed to me, and you probably remember
>  better those links.)
>
> > > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60
>
> Please use this format for links:
>
> Link: <http://example.com>

Since the second sentence will be eliminated in favor of a Link line,
the first sentence will no longer have any spaces after its period.

> Which include provides the structure?

linux/if_addr.h, which is the file I linked to in the commit message,
and the same file that contains struct ifaddrmsg which is documented a
few paragraphs earlier in the same section of the man page.

> > > +struct ifa_cacheinfo {
> > > +    __u32 ifa_prefered; /* Preferred lifetime in seconds, -1 = forever */
> > > +    __u32 ifa_valid;    /* Valid lifetime in seconds, -1 = forever */
> >
> > -1 should be rather 0xFFFFFFFF (INFINITY_LIFE_TIME) as it's unsigned.
>
> I prefer UINT32_MAX over 0xF...F, which might be unclear how many Fs it
> has.

INFINITY_LIFE_TIME is not defined in any public header, so let's not
mention it. I agree that it's hard to see at a glance how many F's are
in 0xFFFFFFFF. I would suggest ~0u, which is short and sweet, but
UINT32_MAX is a little better because ~0u isn't 32 bits on all C
compilers that have ever existed.

> > Also, it would be nice to mention that ifa_prefered must be less than
> > or equal to ifa_valid (ifa_prefered <= ifa_valid) and 0 is invalid for
> > ifa_valid.
> >
> >   0 <= ifa_prefered <= ifa_valid
> >   0 < ifa_valid <= 0xFFFFFFFF

I'll add a paragraph to explain those relationships.

> It might also be interesting to add a separate manual page for the type,
> and reference it here.  Otherwise, the page starts getting fatty.

Perhaps. In my opinion, there's not enough material here to be worthy
of its own page.

Thanks for the feedback,

-Alex

[PATCH man-pages v2] rtnetlink.7: Document struct ifa_cacheinfo

[Alex Henrie]

struct ifa_cacheinfo contains the address's creation time, update time,
preferred lifetime remaining, and valid lifetime remaining.

Link: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60>
Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>
---
Changes from v1:
- Move link to Link line in commit message
- Add the word "remaining" to clarify that the reported values will
  decrease over time
- Say UINT32_MAX instead of -1
- Add a short paragraph to explain the constraints on the minimum and
  maximum lifetimes

Thanks to Kuniyuki and Alejandro for your feedback.
---
 man/man7/rtnetlink.7 | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7
index 86ed459bb..ed08834b0 100644
--- a/man/man7/rtnetlink.7
+++ b/man/man7/rtnetlink.7
@@ -176,7 +176,24 @@ IFA_BROADCAST:raw protocol address:broadcast address
 IFA_ANYCAST:raw protocol address:anycast address
 IFA_CACHEINFO:struct ifa_cacheinfo:Address information
 .TE
-.\" FIXME Document struct ifa_cacheinfo
+.IP
+.EX
+struct ifa_cacheinfo {
+    __u32 ifa_prefered; /* Preferred lifetime remaining, in seconds */
+    __u32 ifa_valid;    /* Valid lifetime remaining, in seconds */
+    __u32 cstamp;       /* Creation timestamp, in hundredths of seconds */
+    __u32 tstamp;       /* Update timestamp, in hundredths of seconds */
+};
+.EE
+.IP
+.I ifa_valid
+cannot be zero, and
+.I ifa_prefered
+cannot be greater than
+.IR ifa_valid .
+A value of
+.B UINT32_MAX
+represents an infinite lifetime.
 .TP
 .B RTM_NEWROUTE
 .TQ
-- 
2.47.0

Re: [PATCH] rtnetlink.7: Document struct ifa_cacheinfo

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3234 bytes --]

Bon dia Alex,  :)

On Sun, Nov 10, 2024 at 11:17:40PM GMT, Alex Henrie wrote:
> On Tue, Nov 5, 2024 at 4:33 AM Alejandro Colomar <alx@kernel.org> wrote:
> 
> > On Mon, Nov 04, 2024 at 09:53:38PM GMT, Kuniyuki Iwashima wrote:
> > > From: Alex Henrie <alexhenrie24@gmail.com>
> > > Date: Mon,  4 Nov 2024 21:14:20 -0700
> > > > struct ifa_cacheinfo contains the address's creation time, update time,
> > > > preferred lifetime, and valid lifetime. See
> >
> > We use two spaces after period (the correct amount).  :)
> > (I'm thinking we probably want to document something about it in
> >  man-pages(7).  Branden, do you want to send a patch about it?  I want
> >  to include the references you showed to me, and you probably remember
> >  better those links.)
> >
> > > > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60
> >
> > Please use this format for links:
> >
> > Link: <http://example.com>
> 
> Since the second sentence will be eliminated in favor of a Link line,
> the first sentence will no longer have any spaces after its period.
> 
> > Which include provides the structure?

The manual page should document it.  Readers should know which header
they need to include to use a structure, no?

> 
> linux/if_addr.h, which is the file I linked to in the commit message,
> and the same file that contains struct ifaddrmsg which is documented a
> few paragraphs earlier in the same section of the man page.
> 
> > > > +struct ifa_cacheinfo {
> > > > +    __u32 ifa_prefered; /* Preferred lifetime in seconds, -1 = forever */
> > > > +    __u32 ifa_valid;    /* Valid lifetime in seconds, -1 = forever */
> > >
> > > -1 should be rather 0xFFFFFFFF (INFINITY_LIFE_TIME) as it's unsigned.
> >
> > I prefer UINT32_MAX over 0xF...F, which might be unclear how many Fs it
> > has.
> 
> INFINITY_LIFE_TIME is not defined in any public header, so let's not
> mention it. I agree that it's hard to see at a glance how many F's are
> in 0xFFFFFFFF. I would suggest ~0u, which is short and sweet, but
> UINT32_MAX is a little better because ~0u isn't 32 bits on all C
> compilers that have ever existed.
> 
> > > Also, it would be nice to mention that ifa_prefered must be less than
> > > or equal to ifa_valid (ifa_prefered <= ifa_valid) and 0 is invalid for
> > > ifa_valid.
> > >
> > >   0 <= ifa_prefered <= ifa_valid
> > >   0 < ifa_valid <= 0xFFFFFFFF
> 
> I'll add a paragraph to explain those relationships.
> 
> > It might also be interesting to add a separate manual page for the type,
> > and reference it here.  Otherwise, the page starts getting fatty.
> 
> Perhaps. In my opinion, there's not enough material here to be worthy
> of its own page.

If you see the pages in section 2type or 3type, they're pretty small.
Types don't have that much to tell.  But they're nevertheless useful.
When you just want to see which header you need for a given type, just
run `make type`, and you'll immediately see it.  It also has a few lines
of description.

But up to you.

> Thanks for the feedback,

Have a lovely day!
Alex

> 
> -Alex
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH man-pages v2] rtnetlink.7: Document struct ifa_cacheinfo

[Kuniyuki Iwashima]

From: Alex Henrie <alexhenrie24@gmail.com>
Date: Sun, 10 Nov 2024 23:20:06 -0700
> struct ifa_cacheinfo contains the address's creation time, update time,
> preferred lifetime remaining, and valid lifetime remaining.
> 
> Link: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60>

Link does not need <> around URL.


> Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>

otherwise looks good to me:

Reviewed-by: Kuniyuki Iwashima <kuniyu@amazon.com>

Re: [PATCH man-pages v2] rtnetlink.7: Document struct ifa_cacheinfo

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 728 bytes --]

On Mon, Nov 11, 2024 at 05:11:45PM GMT, Kuniyuki Iwashima wrote:
> From: Alex Henrie <alexhenrie24@gmail.com>
> Date: Sun, 10 Nov 2024 23:20:06 -0700
> > struct ifa_cacheinfo contains the address's creation time, update time,
> > preferred lifetime remaining, and valid lifetime remaining.
> > 
> > Link: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60>
> 
> Link does not need <> around URL.

I prefer to have <> always.  It doesn't hurt.  :)

> > Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>
> 
> otherwise looks good to me:
> 
> Reviewed-by: Kuniyuki Iwashima <kuniyu@amazon.com>

Thanks!

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH man-pages v2] rtnetlink.7: Document struct ifa_cacheinfo

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2127 bytes --]

Bona nit Alex,

On Sun, Nov 10, 2024 at 11:20:06PM GMT, Alex Henrie wrote:
> struct ifa_cacheinfo contains the address's creation time, update time,
> preferred lifetime remaining, and valid lifetime remaining.
> 
> Link: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60>
> Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>
> ---
> Changes from v1:
> - Move link to Link line in commit message
> - Add the word "remaining" to clarify that the reported values will
>   decrease over time
> - Say UINT32_MAX instead of -1
> - Add a short paragraph to explain the constraints on the minimum and
>   maximum lifetimes
> 
> Thanks to Kuniyuki and Alejandro for your feedback.
> ---
>  man/man7/rtnetlink.7 | 19 ++++++++++++++++++-
>  1 file changed, 18 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7
> index 86ed459bb..ed08834b0 100644
> --- a/man/man7/rtnetlink.7
> +++ b/man/man7/rtnetlink.7
> @@ -176,7 +176,24 @@ IFA_BROADCAST:raw protocol address:broadcast address
>  IFA_ANYCAST:raw protocol address:anycast address
>  IFA_CACHEINFO:struct ifa_cacheinfo:Address information
>  .TE
> -.\" FIXME Document struct ifa_cacheinfo
> +.IP
> +.EX

I expect users that need to use this struct to also need to include the
header that defines it, right?  We should probably specify it by using
an #include.  What do you think?

Have a lovely night!
Alex

> +struct ifa_cacheinfo {
> +    __u32 ifa_prefered; /* Preferred lifetime remaining, in seconds */
> +    __u32 ifa_valid;    /* Valid lifetime remaining, in seconds */
> +    __u32 cstamp;       /* Creation timestamp, in hundredths of seconds */
> +    __u32 tstamp;       /* Update timestamp, in hundredths of seconds */
> +};
> +.EE
> +.IP
> +.I ifa_valid
> +cannot be zero, and
> +.I ifa_prefered
> +cannot be greater than
> +.IR ifa_valid .
> +A value of
> +.B UINT32_MAX
> +represents an infinite lifetime.
>  .TP
>  .B RTM_NEWROUTE
>  .TQ
> -- 
> 2.47.0
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH man-pages v2] rtnetlink.7: Document struct ifa_cacheinfo

[Kuniyuki Iwashima]

From: Alejandro Colomar <alx@kernel.org>
Date: Wed, 13 Nov 2024 00:26:15 +0100
> > diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7
> > index 86ed459bb..ed08834b0 100644
> > --- a/man/man7/rtnetlink.7
> > +++ b/man/man7/rtnetlink.7
> > @@ -176,7 +176,24 @@ IFA_BROADCAST:raw protocol address:broadcast address
> >  IFA_ANYCAST:raw protocol address:anycast address
> >  IFA_CACHEINFO:struct ifa_cacheinfo:Address information
> >  .TE
> > -.\" FIXME Document struct ifa_cacheinfo
> > +.IP
> > +.EX
> 
> I expect users that need to use this struct to also need to include the
> header that defines it, right?

rtnetlink.7 tells #include <linux/rtnetlink.h> is needed in SYNOPSIS
and the header internally includes <linux/if_addr.h>, so users need
not include it explicitly for struct ifa_cacheinfo.


> We should probably specify it by using
> an #include.  What do you think?

So I think we need not mention linux/if_addr.h here.

Re: [PATCH man-pages v2] rtnetlink.7: Document struct ifa_cacheinfo

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1190 bytes --]

Hi Kuniyuki,

On Tue, Nov 12, 2024 at 03:33:29PM GMT, Kuniyuki Iwashima wrote:
> From: Alejandro Colomar <alx@kernel.org>
> Date: Wed, 13 Nov 2024 00:26:15 +0100
> > > diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7
> > > index 86ed459bb..ed08834b0 100644
> > > --- a/man/man7/rtnetlink.7
> > > +++ b/man/man7/rtnetlink.7
> > > @@ -176,7 +176,24 @@ IFA_BROADCAST:raw protocol address:broadcast address
> > >  IFA_ANYCAST:raw protocol address:anycast address
> > >  IFA_CACHEINFO:struct ifa_cacheinfo:Address information
> > >  .TE
> > > -.\" FIXME Document struct ifa_cacheinfo
> > > +.IP
> > > +.EX
> > 
> > I expect users that need to use this struct to also need to include the
> > header that defines it, right?
> 
> rtnetlink.7 tells #include <linux/rtnetlink.h> is needed in SYNOPSIS
> and the header internally includes <linux/if_addr.h>, so users need
> not include it explicitly for struct ifa_cacheinfo.
> 

Ahh, okay.  Then it's fine.

Thanks!
Alex

> 
> > We should probably specify it by using
> > an #include.  What do you think?
> 
> So I think we need not mention linux/if_addr.h here.

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH man-pages v2] rtnetlink.7: Document struct ifa_cacheinfo

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2595 bytes --]

Hi Alex,

On Sun, Nov 10, 2024 at 11:20:06PM GMT, Alex Henrie wrote:
> struct ifa_cacheinfo contains the address's creation time, update time,
> preferred lifetime remaining, and valid lifetime remaining.
> 
> Link: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60>
> Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>

Patch applied.  Thanks!  And thank you for the review, Kuniyuki!
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=eb801003747466333742aeb0e25abb8235ca4776>

I've applied some minor tweaks below, to avoid going over the 80-col
right margin in the formatted output (which BTW triggers a warning in
`make check`).  See below.

Cheers,
Alex

> ---
> Changes from v1:
> - Move link to Link line in commit message
> - Add the word "remaining" to clarify that the reported values will
>   decrease over time
> - Say UINT32_MAX instead of -1
> - Add a short paragraph to explain the constraints on the minimum and
>   maximum lifetimes
> 
> Thanks to Kuniyuki and Alejandro for your feedback.
> ---
>  man/man7/rtnetlink.7 | 19 ++++++++++++++++++-
>  1 file changed, 18 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7
> index 86ed459bb..ed08834b0 100644
> --- a/man/man7/rtnetlink.7
> +++ b/man/man7/rtnetlink.7
> @@ -176,7 +176,24 @@ IFA_BROADCAST:raw protocol address:broadcast address
>  IFA_ANYCAST:raw protocol address:anycast address
>  IFA_CACHEINFO:struct ifa_cacheinfo:Address information
>  .TE
> -.\" FIXME Document struct ifa_cacheinfo
> +.IP
> +.EX
> +struct ifa_cacheinfo {
> +    __u32 ifa_prefered; /* Preferred lifetime remaining, in seconds */
> +    __u32 ifa_valid;    /* Valid lifetime remaining, in seconds */
> +    __u32 cstamp;       /* Creation timestamp, in hundredths of seconds */
> +    __u32 tstamp;       /* Update timestamp, in hundredths of seconds */

+struct ifa_cacheinfo {
+    __u32 ifa_prefered; // Preferred lifetime remaining, in seconds
+    __u32 ifa_valid;    // Valid lifetime remaining, in seconds
+    __u32 cstamp;       // Creation timestamp, in centiseconds
+    __u32 tstamp;       // Update timestamp, in centiseconds

> +};
> +.EE
> +.IP
> +.I ifa_valid
> +cannot be zero, and
> +.I ifa_prefered
> +cannot be greater than
> +.IR ifa_valid .
> +A value of
> +.B UINT32_MAX
> +represents an infinite lifetime.
>  .TP
>  .B RTM_NEWROUTE
>  .TQ
> -- 
> 2.47.0
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]