convert man-page to pod, for easier editing

doc/fping.pod

@@ -0,0 +1,240 @@
+=head1 NAME
+
+fping - send ICMP ECHO_REQUEST packets to network hosts
+
+=head1 SYNOPSIS
+
+B<fping> [ I<options> ] [ I<systems...> ] 
+
+=head1 DESCRIPTION
+
+B<fping> is a program like B<ping> which uses the Internet Control Message
+Protocol (ICMP) echo request to determine if a target host is responding.
+B<fping> differs from B<ping> in that you can specify any number of targets on the
+command line, or specify a file containing the lists of targets to ping.
+Instead of sending to one target until it times out or replies, B<fping> will
+send out a ping packet and move on to the next target in a round-robin fashion.
+In the default mode, if a target replies, it is noted and removed from the list
+of targets to check; if a target does not respond within a certain time limit
+and/or retry limit it is designated as unreachable. B<fping> also supports
+sending a specified number of pings to a target, or looping indefinitely (as in
+B<ping> ). Unlike B<ping>, B<fping> is meant to be used in scripts, so its
+output is designed to be easy to parse.
+
+=head1 OPTIONS
+
+=over 5
+
+=item B<-a>
+
+Show systems that are alive. 
+
+=item B<-A>
+
+Display targets by address rather than DNS name. 
+
+=item B<-b> I<n>
+
+Number of bytes of ping data to send.  The minimum size (normally 12) allows
+room for the data that B<fping> needs to do its work (sequence number,
+timestamp).  The reported received data size includes the IP header (normally
+20 bytes) and ICMP header (8 bytes), so the minimum total size is 40 bytes.
+Default is 56, as in B<ping>. Maximum is the theoretical maximum IP datagram
+size (64K), though most systems limit this to a smaller, system-dependent
+number. 
+
+=item B<-B> I<n>
+
+In the default mode, B<fping> sends several requests to a target before giving
+up, waiting longer for a reply on each successive request.  This parameter is
+the value by which the wait time is multiplied on each successive request; it
+must be entered as a floating-point number (x.y).  The default is 1.5. 
+
+=item B<-c>
+
+Number of request packets to send to each target.  In this mode, a line is
+displayed for each received response (this can suppressed with B<-q> or B<-Q>).
+Also, statistics about responses for each target are displayed when all
+requests have been sent (or when interrupted). 
+
+=item B<-C>
+
+Similar to B<-c>, but the per-target statistics are displayed
+in a format designed for automated response-time statistics gathering.  For
+example: 
+
+ % fping -C 5 -q somehost 
+ somehost : 91.7 37.0 29.2 - 36.8 
+
+shows the response time in milliseconds for each of the five requests, with the
+C<-> indicating that no response was received to the fourth request. 
+
+=item B<-d>
+
+Use DNS to lookup address of return ping packet. This allows you to give fping
+a list of IP addresses as input and print hostnames in the output. 
+
+=item B<-e>
+
+Show elapsed (round-trip) time of packets. 
+
+=item B<-f>
+
+Read list of targets from a file.  This option can only be used by the root
+user. Regular users should pipe in the file via stdin: 
+
+ % fping < targets_file 
+
+=item B<-g>
+
+Generate a target list from a supplied
+IP netmask, or a starting and ending IP. Specify the netmask or start/end
+in the targets portion of the command line. If a network with netmask is
+given, the network and broadcast addresses will be excluded. 
+ex. To ping the network 192.168.1.0/24, the specified command line could look like either:
+
+ fping -g 192.168.1.0/24 
+
+or 
+
+ fping -g 192.168.1.1 192.168.1.254 
+
+=item B<-h>
+
+Print usage message.
+
+=item B<-i> I<n>
+
+The minimum amount of time (in milliseconds) between sending a ping packet
+to any target (default is 25). 
+
+=item B<-l>
+
+Loop sending packets to each target indefinitely. Can be interrupted with
+Ctrl-C; statistics about responses for each target are then displayed. 
+
+=item B<-m>
+
+Send pings to each of a target host's multiple interfaces.
+
+=item B<-n>
+
+Same as -d. 
+
+=item B<-p>
+
+In looping or counting modes (B<-l>, B<-c>, or B<-C>), this parameter sets
+the time in milliseconds that B<fping> waits between successive packets to
+an individual target.  Default is 1000. 
+
+=item B<-q>
+
+Quiet. Don't show per-target results,
+just set final exit status. 
+
+=item B<-Q> I<n>
+
+Like B<-q>, but show summary results every n seconds.
+
+=item B<-r> I<n>
+
+Retry limit (default 3). This is the number of times an attempt at pinging
+a target will be made, not including the first try. 
+
+=item B<-s>
+
+Print cumulative statistics upon exit. 
+
+=item B<-S> I<addr>
+
+Set source address. 
+
+=item B<-I> I<if>
+
+Set the interface (requires SO_BINDTODEVICE support) 
+
+=item B<-t> I<n>
+
+Initial target timeout in milliseconds (default 500). In the default mode, this
+is the amount of time that B<fping> waits for a response to its first request.
+Successive timeouts are multiplied by the backoff factor. 
+
+=item B<-T> I<n>
+
+Ignored (for compatibility with fping 2.4). 
+
+=item B<-u>
+
+Show targets that are unreachable. 
+
+=item B<-O> I<n>
+
+Set the typ of service flag (TOS). I<n> can be either decimal or hexadecimal
+(0xh) format. 
+
+=item B<-v>
+
+Print B<fping> version information. 
+
+=item B<-H> I<n>
+
+Set the IP TTL field (time to live hops). 
+
+=back
+
+=head1 AUTHORS
+
+=over 4
+
+=item *
+
+Roland J. Schemers III, Stanford University, concept and versions 1.x
+
+=item *
+
+RL "Bob" Morgan, Stanford University, versions 2.x
+
+=item *
+
+David Papp, versions 2.3x and up
+
+=item *
+
+David Schweikert, versions 3.0 and up
+
+=back
+
+B<fping website: L<http://www.fping.org>>
+
+=head1 DIAGNOSTICS
+
+Exit status is 0 if all the hosts are reachable, 1 if some hosts
+were unreachable, 2 if any IP addresses were not found, 3 for invalid command
+line arguments, and 4 for a system call failure.
+
+=head1 RESTRICTIONS
+
+If certain options are used (i.e, a low value for B<-i> and B<-t>, and a high value
+for B<-r>) it is possible to flood the network. This program must be installed as
+setuid root in order to open up a raw socket, or must be run by root. In order
+to stop mere mortals from hosing the network, normal users can't specify the following: 
+
+=over 4
+
+=item *
+
+B<-i> I<n>, where I<n> < 10 msec
+
+=item *
+
+B<-r> I<n>, where I<n> > 20
+
+=item *
+
+B<-t> I<n>, where n < 250 msec
+
+=back
+
+=head1 SEE ALSO
+
+C<ping(8)>