On Wed, Dec 21, 2022 at 12:41:42PM -0500, Paul R. Tagliamonte wrote:
> > So I think route.8 is where we should try to have complete documentation,
> > and once that is done we should change Xr's and other documentation to
> > point at route.8 instead of netstat.8
>
> In an effort to have my interactions on this list wind up being helpful
> rather than more work for overworked maintainers, attached is a
> revised patch attempting to do so.
>
> This removes the "Flags" description from the netstat.1 manpage
> Directly above it is an instruction to check out the route(8/4)
> pages. The Flags table was moved to route(8).
>
> While doing this, I noticed in the exact place I was going to make a
> change to add the flags, lo and behold I found a reference to
> netlink(1). I feel quite dumb about that one; if I had read the
> manpage better, I'd have found that link and avoided all this.
>
> That being said, I do genuinely believe moving the table to
> route is a bit more expected, so; here it is!
>
> paultag
> --
> :wq
>
> Index: sbin/route/route.8
> ===================================================================
> RCS file: /cvs/src/sbin/route/route.8,v
> retrieving revision 1.106
> diff -u -p -r1.106 route.8
> --- sbin/route/route.8 19 Nov 2022 19:23:37 -0000 1.106
> +++ sbin/route/route.8 21 Dec 2022 17:36:17 -0000
> @@ -197,10 +197,7 @@ the given interface is sent.
> .Op Fl label Ar label
> .Op Fl priority Ar priority
> .Xc
> -Print out the routing table, in a fashion similar to "netstat -r".
> -The output is documented in more detail towards the end of the
> -.Xr netstat 1
> -manual.
> +Display all entries from the routing table, along with related metadata.
i like the choice of "display" over "print out".
i don;t like the "related metadata" bit though.
what about just
Display the routing table.
> .Pp
> If
> .Fl gateway
> @@ -224,6 +221,31 @@ or
> .Cm bgp .
> If the priority is negative, then routes that do not match the numeric
> priority are shown.
> +.Pp
> +The "Flags" column indicates what flags are set on the route. The mapping
> +between letters and flags is:
you should start new sentences on new lines.
> +.Bl -column "1" "RTF_BLACKHOLE" "Protocol specific routing flag #1."
> +.It 1 Ta Dv RTF_PROTO1 Ta "Protocol specific routing flag #1."
> +.It 2 Ta Dv RTF_PROTO2 Ta "Protocol specific routing flag #2."
> +.It 3 Ta Dv RTF_PROTO3 Ta "Protocol specific routing flag #3."
> +.It B Ta Dv RTF_BLACKHOLE Ta "Just discard pkts (during updates)."
> +.It b Ta Dv RTF_BROADCAST Ta "Correspond to a local broadcast address."
> +.It C Ta Dv RTF_CLONING Ta "Generate new routes on use."
> +.It c Ta Dv RTF_CLONED Ta "Cloned routes (generated from RTF_CLONING)."
> +.It D Ta Dv RTF_DYNAMIC Ta "Created dynamically (by redirect)."
> +.It G Ta Dv RTF_GATEWAY Ta "Destination requires forwarding by intermediary."
> +.It H Ta Dv RTF_HOST Ta "Host entry (net otherwise)."
> +.It h Ta Dv RTF_CACHED Ta "Referenced by gateway route."
> +.It L Ta Dv RTF_LLINFO Ta "Valid protocol to link address translation."
> +.It l Ta Dv RTF_LOCAL Ta "Correspond to a local address."
> +.It M Ta Dv RTF_MODIFIED Ta "Modified dynamically (by redirect)."
> +.It m Ta Dv RTF_MULTICAST Ta "Correspond to a multicast address."
> +.It n Ta Dv RTF_CONNECTED Ta "Interface route."
> +.It P Ta Dv RTF_MPATH Ta "Multipath route."
> +.It R Ta Dv RTF_REJECT Ta "Host or net unreachable."
> +.It S Ta Dv RTF_STATIC Ta "Manually added."
> +.It T Ta Dv RTF_MPLS Ta "MPLS route."
> +.It U Ta Dv RTF_UP Ta "Route usable."
> .El
> .Pp
> .Bl -tag -width Fl -compact
> @@ -635,7 +657,6 @@ to create the new entry.
> .El
> .Sh SEE ALSO
> .Xr id 1 ,
> -.Xr netstat 1 ,
i would not remove the Xr. i think if we go ahead with this, we can make
a separate commit where we point people to route(8) rather than
netstart(8), but i suspect many pages will both want references to both.
> .Xr gethostbyname 3 ,
> .Xr netintro 4 ,
> .Xr route 4 ,
> Index: usr.bin/netstat/netstat.1
> ===================================================================
> RCS file: /cvs/src/usr.bin/netstat/netstat.1,v
> retrieving revision 1.95
> diff -u -p -r1.95 netstat.1
> --- usr.bin/netstat/netstat.1 8 Sep 2022 13:18:47 -0000 1.95
> +++ usr.bin/netstat/netstat.1 21 Dec 2022 17:36:18 -0000
> @@ -343,31 +343,6 @@ and
> .Xr route 4
> manual pages.
> .Pp
> -The mapping between letters and flags is:
> -.Bl -column "1" "RTF_BLACKHOLE" "Protocol specific routing flag #1."
> -.It 1 Ta Dv RTF_PROTO1 Ta "Protocol specific routing flag #1."
> -.It 2 Ta Dv RTF_PROTO2 Ta "Protocol specific routing flag #2."
> -.It 3 Ta Dv RTF_PROTO3 Ta "Protocol specific routing flag #3."
> -.It B Ta Dv RTF_BLACKHOLE Ta "Just discard pkts (during updates)."
> -.It b Ta Dv RTF_BROADCAST Ta "Correspond to a local broadcast address."
> -.It C Ta Dv RTF_CLONING Ta "Generate new routes on use."
> -.It c Ta Dv RTF_CLONED Ta "Cloned routes (generated from RTF_CLONING)."
> -.It D Ta Dv RTF_DYNAMIC Ta "Created dynamically (by redirect)."
> -.It G Ta Dv RTF_GATEWAY Ta "Destination requires forwarding by intermediary."
> -.It H Ta Dv RTF_HOST Ta "Host entry (net otherwise)."
> -.It h Ta Dv RTF_CACHED Ta "Referenced by gateway route."
> -.It L Ta Dv RTF_LLINFO Ta "Valid protocol to link address translation."
> -.It l Ta Dv RTF_LOCAL Ta "Correspond to a local address."
> -.It M Ta Dv RTF_MODIFIED Ta "Modified dynamically (by redirect)."
> -.It m Ta Dv RTF_MULTICAST Ta "Correspond to a multicast address."
> -.It n Ta Dv RTF_CONNECTED Ta "Interface route."
> -.It P Ta Dv RTF_MPATH Ta "Multipath route."
> -.It R Ta Dv RTF_REJECT Ta "Host or net unreachable."
> -.It S Ta Dv RTF_STATIC Ta "Manually added."
> -.It T Ta Dv RTF_MPLS Ta "MPLS route."
> -.It U Ta Dv RTF_UP Ta "Route usable."
> -.El
> -.Pp
> Direct routes are created for each interface attached to the local host;
> the gateway field for such entries shows the address of the outgoing
> interface.
> The refcnt field gives the current number of active uses of the route.
except for that, diff seems fine.
jmc
