Skip site navigation (1)Skip section navigation (2)
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>