Hi Alex, Kuniyuki, Branden,

On Mon, Nov 04, 2024 at 09:53:38PM GMT, Kuniyuki Iwashima wrote:

From: Alex Henrie <redacted>
Date: Mon,  4 Nov 2024 21:14:20 -0700

quoted

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.)

quoted

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>

quoted

Signed-off-by: Alex Henrie <redacted>
---
 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?

quoted

+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

quoted

+    __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.

quoted

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

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