Manual brought up to date.

iftop.8

@@ -65,6 +65,9 @@ Turn on port display.
 \fB-b\fP
 Don't display bar graphs of traffic. This setting may be altered at run time.
 .TP
+\fB-B\fP
+Display bandwidth rates in bytes/sec rather than bits/sec.
+.TP
 \fB-i\fP \fIinterface\fP
 Listen to packets on \fIinterface\fP.
 .TP
@@ -82,8 +85,7 @@ single number specifying the number of bits set in the netmask, such as /24.
 .SH DISPLAY
 
 When running, \fBiftop\fP uses the whole screen to display network usage. At
-the top of the display is a reminder of keys which control \fBiftop\fP in
+the top of the display is a logarithmic scale for the bar graph which gives a
-operation. Below that is a logarithmic scale for the bar graph which gives a
 visual indication of traffic.
 
 The main part of the display lists, for each pair of hosts, the rate at which
@@ -92,8 +94,8 @@ intervals. The direction of data flow is indicated by arrows, <= and =>. For
 instance,
 .nf
 
-foo.example.com  =>  bar.example.com      1K   500b   100b
+foo.example.com  =>  bar.example.com      1Kb  500b   100b
-                 <=                       2M     2M     2M
+                 <=                       2Mb    2Mb    2Mb
 
 .Sp
 .fi
@@ -107,24 +109,12 @@ You might expect to see something like this where host \fBfoo\fP is making
 repeated HTTP requests to \fBbar\fP, which is sending data back which saturates
 a 2Mbit/s link.
 
-All rates are displayed in bits per second and multiples thereof. The pairs of
+By default, the pairs of hosts responsible for the most traffic (10 second
-hosts responsible for the most traffic are displayed at the top of the list.
+average) are displayed at the top of the list.
 
-At the bottom of the display, various totals are shown, for instance:
+At the bottom of the display, various totals are shown, including peak traffic
-.nf
+over the last 40s, total traffic transferred (after filtering), and total
-
+transfer rates averaged over 2s, 10s and 40s.
-total: 3.1K  TX: 0.3M  peaks:  64b totals:  64b   30b  10b
- peak: 4.5K  RX:   8M         4.5K         4.5K  0.1M   5K
-
-.Sp
-.fi
-The first column of numbers shows the total rate of received plus transmitted
-traffic over the last 2s, and its peak value over the past 40s. The next column
-shows the total amount of traffic observed during this session,
-\fIin bytes, not bits\fP.  The next column shows the peaks in received and
-transmitted traffic, and the remaining colums show the 2, 10 and 40 second
-averages. As with the per-host displays, the top line shows transmitted and the
-bottom line received traffic.
 
 .SH SOURCE / DEST AGGREGATION
 
@@ -138,10 +128,69 @@ machine.
 \fBS\fP or \fBD\fP toggle the display of source and destination ports
 respectively. \fBp\fP will toggle port display on/off.
 
-.SH PAUSE DISPLAY
+.SH DISPLAY ORDER
+
+By default, the display is ordered according to the 10s average (2nd column).
+By pressing \fB1\fP, \fB2\fP or \fB3\fP it is possible to sort by the 1st, 2nd
+or 3rd column.   By pressing \fB<\fP or \fB>\fP the display will be sorted by
+source or destination hostname respectively.
+
+.SH DISPLAY FILTERING
+
+\fBl\fP allows you to enter a POSIX extended regular expression that will be
+used to filter hostnames shown in the display.  This is a good way to quickly
+limit what is shown on the display.  Note that this happens at a much later
+stage than filter code, and does not affect what is actually captured.
+
+.SH PAUSE DISPLAY / FREEZE ORDER
 
 \fBP\fP will pause the current display.
 
+\fBo\fP will freeze the current screen order.  This has the side effect that
+traffic between hosts not shown on the screen at the time will not be shown at
+all, although it will be included in the totals at the bottom of the screen.
+
+.SH FILTER CODE
+
+\fBf\fP allows you to edit the filter code whilst iftop running.  This
+can lead to some unexpected behaviour.
+
+.SH QUIRKS (aka they're features, not bugs)
+
+There are some circumstances in which iftop may not do what you expect.  In
+most cases what it is doing is logical, and we believe it is correct behaviour,
+although I'm happy to hear reasoned arguments for alternative behaviour.
+
+\fBTotals don't add up\fP
+
+There are several reasons why the totals may not appear to add up.  The
+most obvious is having a screen filter in effect, or screen ordering
+frozen.  In this case some captured information is not being shown to
+you, but is included in the totals.
+
+A more subtle explanation comes about when running in promiscuous mode
+without specifying a \fB-n\fP option.  In this case there is no easy way
+to assign the direction of traffic between two other hosts.  For the
+purposes of the main display this is done in an arbitrary fashion (by
+ordering of IP addresses), but for the sake of totals all traffic
+between other hosts is accounted as incoming, because that's what it is
+from the point of view of your interface.  
+
+\fBPeak totals don't add up\fP
+
+Again, this is a feature.  The peak sent and peak received didn't necessarily
+happen at the same time.  The peak total is the maximum of sent plus received
+in each captured time division.
+
+\fBChanging the filter code doesn't seem to work\fP
+
+Give it time.  Changing the filter code affects what is captured from
+the time that you entered it, but most of what is on the display is
+based on some fraction of the last 40s window of capturing.  After
+changing the filter there may be entries on the display that are
+disallowed by the current filter for up to 40s.  DISPLAY FILTERING has
+immediate effect and does not affect what is captured.
+
 .SH SEE ALSO
 .BR tcpdump (8),
 .BR pcap (3),