| Message ID | 20241111062205.207027-1-alexhenrie24@gmail.com (mailing list archive) |
|---|---|
| State | Not Applicable |
| Headers | show |
| Series | [man-pages,v2] rtnetlink.7: Document struct ifa_cacheinfo | expand |
| Context | Check | Description |
|---|---|---|
| netdev/tree_selection | success | Not a local patch |
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>
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!
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 >
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.
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.
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 >
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
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(-)