Date: Mon, 26 May 2014 17:23:52 +1000 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Bryan Drewery <bdrewery@freebsd.org> Cc: svn-src-head@freebsd.org, svn-src-all@freebsd.org, src-committers@freebsd.org, Allan Jude <allanjude@freebsd.org>, owner-src-committers@freebsd.org Subject: Re: svn commit: r266645 - head/usr.bin/netstat Message-ID: <20140526145518.Y1031@besplex.bde.org> In-Reply-To: <4aad9c2211e850938174998f66dd3fbb@shatow.net> References: <201405250741.s4P7fCvh095925@svn.freebsd.org> <4aad9c2211e850938174998f66dd3fbb@shatow.net>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sun, 25 May 2014, Bryan Drewery wrote: > On 2014-05-25 02:41, Allan Jude wrote: >> ... >> Log: >> Document the new -R flag of netstat(1) introduced in r266448 that tracks >> the >> flowid for each socket. >> >> Modified: head/usr.bin/netstat/netstat.1 >> ============================================================================== >> --- head/usr.bin/netstat/netstat.1 Sun May 25 06:42:43 2014 >> (r266644) >> +++ head/usr.bin/netstat/netstat.1 Sun May 25 07:41:12 2014 >> (r266645) >> @@ -45,7 +45,7 @@ depending on the options for the informa > > Looks like you forgot to bump .Dd > >> .It Xo >> .Bk -words >> .Nm >> -.Op Fl 46AaLnSTWx >> +.Op Fl 46AaLnSTWxR Also, the alphabet. >> @@ -84,6 +84,9 @@ but show ports symbolically. >> If >> .Fl x >> is present, display socket buffer and tcp timer statistics for each >> internet socket. >> +If >> +.Fl R >> +is present, display the flowid and flowtype for each internet socket. >> When >> .Fl T >> is present, display information from the TCP control block, including Here -T was already unsorted. The syntax is very complicated and most of the options are not described in a single list, but they are mostly sorted in sub-lists starting with the ones in the synopsis. (The man page is unusually organized and doesn't actually have a SYNOPSIS section. Instead, the synopsis lines are placed in the DESCRIPTION section. I refer to the collection of them as "the synopsis" although there is no actual synopsis). >> @@ -367,6 +370,11 @@ and display them symbolically. >> .It Fl W >> In certain displays, avoid truncating addresses even if this causes >> some fields to overflow. >> +.It Fl R >> +Display the flowid and flowtype for each socket. >> +flowid is a 32 bit hardware specific identifier for each flow. >> +flowtype defines which protocol fields are hashed to produce the id. >> +A complete listing is available in sys/mbuf.h under M_HASHTYPE_* >> .El >> .Pp >> The default display, for active sockets, shows the local -R seems to have only been added to the synopsis for 1 of the displays. If that is correct, then its description doesn't belong here, even if it were sorted (this sub-list was sorted). This is the general list for options that have "the [sic] general meaning". Many of the options in this list are not really general. I think only -M and -N are really general. They are given for all except 4 displays in the synopsis. I think this is a bug in 3 or 4 of these displays in the synopsis. The others (-46fnW and now -R) are not present in most of the displays in the synopsis. I think the bugs for this are distributed. Only the above description for -W is fuzzy enough to be correct (it says "for certain displays"). Actually, this makes it is not even wrong. It is documented for just 2 of the displays, and the details of what it does are given there. PS: oops: the detals are more complicated. The above is generic for "addresses", while the details only mention "interfaces". -W seems to affect both if and only it affects either, but it sometimes affects neither when it is documented to affect "interfaces". Getopt parsing in netstat would have to be just as complicated as the synopsis to restrict to only the documented combinations. It actually seems to allow all combinations except -x with -T. Then netstat does whatever it does with the undocumented/nonsensical combinations. netstat's usage message tries to duplicate all of the synopsis lines. I didn't notice if -R was already up to date or unsorted in the usage message. Comparing the previous versions of them shows only minor bugs: @--- netstat.synopsis 2014-05-26 05:36:41.306465000 +0000 @+++ netstat.usage 2014-05-26 05:35:06.234067000 +0000 @@@ -1,2 +1,2 @@ @- netstat [-46AaLnSTWx] [-f protocol_family | -p protocol] [-M core] @- [-N system] @+usage netstat [-46AaLnSTWx] [-f protocol_family | -p protocol] [-M core] @+ [-M core] [-N system] The usage message is split gratuitously inconsistently. Unfortunately, lining up after printing "usage: " gives a 7-column indentation, while man gives a 5-column identation. (I used diff -w to avoid seeing most such differences.) Despite this, there are enough columns to preserve the line splitting here. @@@ -4,4 +4,5 @@ @- netstat -w wait [-I interface] [-d] [-M core] [-N system] [-q howmany] @- netstat -s [-s] [-46z] [-f protocol_family | -p protocol] [-M core] @- [-N system] @- netstat -i | -I interface -s [-46] [-f protocol_family | -p protocol] @+ [-M core] [-N system] @+ netstat -w wait [-I interface] [-46d] [-M core] [-N system] [-q howmany] @+ netstat -s [-s] [-46z] [-f protocol_family | -p protocol] @+ [-M core] [-N system] @+ netstat -i | -I interface [-46s] [-f protocol_family | -p protocol] The synopsis for -w is missing -46. The synopsis for -i says -s [-46] but the usage says [-46s]. It is unclear where the bug is. The line before this says -s [-s]. There the second -s is certainly correct -- it amplifies the effect of the first -s. It is unclear if the first -s is really a display selector. Some of the lines in the "synopsis" seem to be more like examples giving some but not all useful combinatations of options. The synopsis for -i is missing [-M core] [-N system]. The usage for -i mis-splits the line before either of these as usual. @@@ -10,3 +11,2 @@ @- netstat -B [-z] [-I interface] @- netstat -r [-46AanW] [-F fibnum] [-f address_family] [-M core] @- [-N system] @+ netstat -B [-I interface] @+ netstat -r [-46AanW] [-f address_family] [-M core] [-N system] The usage for -B is missing -z. The synopsis for -r is missing [-F fibnum]. I noticed that -W doesn't work very well. Its main use of avoiding truncation of interface names is completely broken (not done). For -r, as well as adding the Mtu column, it restores printing of the Use column but not the Refs column; the latter is undocumented. Examples of misformatting: Old version on my local system. Some names are about 50 wide, so the full display is almost 160 wide. It is unreadable: @Destination Gateway Flags Refs Use Mtu Netif Expire @default c122-106-144-1.carlnfd1.nsw.optusnet.com.au UGS 0 15216 1500 rl0 @122.106.144/20 link#2 UC 0 0 1500 rl0 @c122-106-144-1.carlnfd1.nsw.optusnet.com.au 00:1d:45:70:a8:d9 UHLW 1 0 1500 rl0 868 @ -current version on freefall. First with -rW: @Internet: @Destination Gateway Flags Use Mtu Netif Expire @default router.v108.ysv.fr UGS 166457765 1500 igb0 @... @Internet6: @Destination Gateway Flags Use Mtu Netif Expire @... @2001:1900:2254:206 link#1 U 2009694789 1500 igb0 @freefall.freebsd.o link#1 UHS 108 16384 lo0 Names are blindly truncated with no indication. Despite this and other space-saving measures, the formatting is still broken by large values in the Use field. The truncation is more of a problem with. ipv6 now now gives very long and cryptic numeric-like fields even without -n. Everyone can knows freefall's full name so they can un-truncate it in the above, bit not manyone can un-truncate the above ipv6 address. -W actually works with -rnW: @Internet: @Destination Gateway Flags Use Mtu Netif Expire @default 8.8.178.129 UGS 166460840 1500 igb0 @... @Internet6: @Destination Gateway Flags Use Mtu Netif Expire @... @2001:1900:2254:206c::/64 link#1 U 2009749211 1500 igb0 @2001:1900:2254:206c::16:87 link#1 UHS 108 16384 lo0 netstat is moderately smart and changes the column widths for ipv6. In my attempts to fix such misformattings using post-processing, I found (learned again) that expanding the column widths to hold a few wide entries doesn't work. In the above, ipv6 has many wide entries so the exansion is necessary (the Gateway field looks too wide in the above, but unshown entries need it. Actually, the fields are still gratuitously wide. In the above, the entry ending with ":87" is widest. The field width should be 1 wider than it, but is 8 wider). The Gateway field width is only 4 wider than it should be). Even ls -C hasn't learned how to format columns yet in FreeBSD. It uses something like the following algorithm to give horrible results when there is a single wide name: - find the widest name - add 1 - add another one for ls -F (my default), even when an extra character for -F is not needed - add 7 and truncate to a multiple of 8. This aligns to a tab boundary. So a few file names of length <= 6 are displayed well enough, 10 per line. Change one to length 7. 8 columns is still enough, especially with only 1 outlier, but the above gives length 16 for 1 name and uses it for all names. So only 5 names are displayed per line, using not 16 columns each for the first 4 and 15 for the last one, all on an 80-column terminal of course. There is a minor problem with possible auto-wrap for the last column. 5 columns of 16 each must be avoided, but it is easily avoided for the last column by leaving just 1 space between fields and not printing a space for the last column. Change one to length 15. 5 columns should still fit, but after mis-expansion of 15 to 24, only 3 columns fit. In large directories, bad verbose names are more common so reduction to 2 or 3 columns is the usual case, so -C works least well in large directories where it is most needed. ls -CF works as well as possible in gnu ls: Script started on Mon May 26 17:15:32 2014 ttyv1:root@besplex:/tmp/s2> /bin/ls -F 000000000000010 000003 000007 0000009 000004 000008 000001 000005 typescript 000002 000006 ttyv1:root@besplex:/tmp/s2> /compat/linux/bin/ls -F 000000000000010 000001 000003 000005 000007 typescript 0000009 000002 000004 000006 000008 ttyv1:root@besplex:/tmp/s2> exit Script done on Mon May 26 17:15:46 2014 gnu ls doesn't expand to a tab stop, and it uses variable-width columns. Sorting prevents it doing fancier things like grouping the wide fields in columns. Bruce
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20140526145518.Y1031>