How stable is TCP_INFO?

From: Pau Amma <pauamma_at_gundo.com>
Date: Tue, 01 Feb 2022 03:55:26 UTC
(Please cc me on replies - I'm subscribed nomail as this is a one-off 
question.)

While reviewing the manual page bits in 
https://reviews.freebsd.org/D23230, I checked tcp(4) as it stands in 
14-current (using 
https://www.freebsd.org/cgi/man.cgi?query=tcp&apropos=0&sektion=4&manpath=FreeBSD+14.0-current&arch=default&format=html), 
and it mentions it's subject to change. (It's also very poorly 
documented, perhaps as a result of the stated instability.) The history 
section mentions it was brought in following Linux 2.6, and checking the 
git log dates its arrival in FreeBSD to November 2004, and official 
acknowledgement in documentation of its existence to January 2007. The 
TCP_INFO language in tcp(4) hasn't changed since as far as I can tell.

Half of the 16 changes 
https://cgit.freebsd.org/src/log/?qt=grep&q=tcp_info returns are over 12 
years in the past, and of the remaining ones, after a gap of about 6.75 
years, only 
https://cgit.freebsd.org/src/commit/?id=5a17b6ad98c6c3fa7a7a1ab02551abfb25cc40c9 
(report use of the ECN option), maybe 
https://cgit.freebsd.org/src/commit/?id=f8fea0d90e04d0a1908c36080ab1cfb84dc705a2 
(something related to cxgbe that may or may not change what it reports), 
maybe 
https://cgit.freebsd.org/src/commit/?id=7576fe761e9df400f097d4d7ce9f24340f8c4dd7 
(report something related to that same driver), and probably 
https://cgit.freebsd.org/src/commit/?id=61e02298cea3bee31604640e53da1567271dfa57 
(report something else(?) still related to that driver) seem to change 
that API, if I'm reading the code right (not a given at all).  That's 1 
definite change, 1 likely change, and 2 possible changes in over 5 
years. So how unstable is that API, and is it time to document it now?