#   Copyright
#
#	Copyright (C) 2007-2010 Jari Aalto
#
#   License
#
#       This program is free software; you can redistribute it and/or modify
#       it under the terms of the GNU General Public License as published by
#       the Free Software Foundation; either version 2 of the License, or
#       (at your option) any later version.
#
#       This program is distributed in the hope that it will be useful,
#       but WITHOUT ANY WARRANTY; without even the implied warranty of
#       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
#       GNU General Public License for more details.
#
#       You should have received a copy of the GNU General Public License
#       along with this program. If not, see <http://www.gnu.org/licenses/>.
#
#   Description
#
#	To learn what TOP LEVEL sections to use in manual pages,
#	see POSIX/Susv standard and "Utility Description Defaults" at
#	http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11
#
#	This is manual page in Perl POD format. Read more at
#	http://perldoc.perl.org/perlpod.html or run command:
#
#	    perldoc perlpod | less
#
#	To check the syntax:
#
#	    podchecker *.pod
#
#	Create manual page with command:
#
#	    pod2man PAGE.N.pod > PAGE.N

=pod

=head1 NAME

speedometer - measure and display the rate of data across a network connection

=head1 SYNOPSIS

   speedometer [options] tap [[-c] tap] ...

=head1 DESCRIPTION

Monitor network traffic or speed/progress of a file transfer. At least
one tap option (B<-f>, B<-rx>, B<-tx>) must be entered. Option B<-c>
starts a new column, otherwise taps are piled vertically.

Note: before you use the program, satrt generating traffic by
transferring files in/out e.g. with scp(1) in the network you're
measuring.

=head1 OPTIONS

=over 4

=item B<-b>

Use old blocky display instead of smoothed display even when UTF-8
encoding is detected.

=item B<-f filename [size]>

Display download speed with progress bar. This option must be used if
directly following another file tap without an expected size
specified.

=item B<-i interval>

Interval in seconds. Examples: 5 or 0.25". Default is 1.

=item B<-p>

Use plain-text display (one tap only).

=item B<-rx iface>

Display bytes received on network interface.

=item B<-tx iface>

Display bytes transmitted on network interface.

=item B<-z>

Report zero size on files that don't exist instead of waiting for them
to be created

=back

EXAMPLES

How long it will take for my 38MB transfer to finish?

    speedometer favorite_episode.rm $(( 38 * 1024 * 1024 ))

How quickly is another transfer going?

    speedometer dl/big.avi

How fast is this LAN?

    host-a$ cat /dev/zero | nc -l -p 12345
    host-b$ nc host-a 12345 > /dev/null
    host-b$ speedometer -rx eth0

How fast is the upstream on this ADSL line?

    speedometer -tx ppp0

How fast can I write data to my filesystem? (with at least 1GB free)

    dd bs=1000000 count=1000 if=/dev/zero of=bigfile &
    speedometer bigfile

=head1 ENVIRONMENT

None.

=head1 FILES

None.

=head1 SEE ALSO

htop(1)
iotop(1)
scp(1)
top(1)
vmstat(1)

=head1 AUTHORS

Program was written by Ian Ward <ian.ward@excess.org>

This manual page was written by Jari Aalto <jari.aalto@cante.net>.
Released under license GNU GPL version 2 or (at your option) any later
version. For more information about license, visit
<http://www.gnu.org/copyleft/gpl.html>.

=cut