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

Alejandro Colomar
2024-11-12T23:26:19Z

[-- 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/>