24528676 fping.1m man page should be renumbered to follow new section standards
authorRich Burridge <rich.burridge@oracle.com>
Thu, 08 Sep 2016 11:59:52 -0700
changeset 6863 4eb57cfa3349
parent 6862 6cc42aa3b75a
child 6864 45128c94429d
24528676 fping.1m man page should be renumbered to follow new section standards
components/fping/fping.1m
components/fping/fping.p5m
components/fping/patches/adjust-man-page.patch
--- a/components/fping/fping.1m	Thu Sep 08 11:15:34 2016 -0700
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,328 +0,0 @@
-'\" te
-.\"
-.\"  
-.TH fping 1M "29 Feb 2008" "SunOS 5.11" "System Administration Commands"
-.SH NAME
-fping \- send ICMP ECHO_REQUEST packets to network hosts
-.SH SYNOPSIS
-.B fping
-[ \fIoptions\fR ]
-[ \fIsystems...\fR ]
-
-.SH DESCRIPTION
-.NXR "fping command"
-.NXR "ICMP ECHO_REQUEST"
-
-      
-.B fping 
-is a 
-.B ping
-like program which uses the Internet Control
-Message Protocol (ICMP) echo request to determine if a target host is
-responding. 
-.B fping 
-differs from 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. 
-.PP
-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
-).
-.PP
-Unlike 
-.B ping
-,
-.B fping 
-is meant to be used in scripts, so its output is designed to be 
-easy to parse.
-.SH OPTIONS
-.IP \fB-a\fR 5
-Show systems that are alive.
-.IP \fB-A\fR 5
-Display targets by address rather than DNS name.
-.IP \fB-b\fIn\fR 5
-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.
-.IP \fB-B\fIn\fR 5
-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.
-.IP \fB-c\fR 5
-Number of request packets to send to each target.  In this mode, a
-line is displayed for each received response (this can suppressed with
--q or -Q).  Also, statistics about responses for each target are displayed
-when all requests have been sent (or when interrupted).
-.IP \fB-C\fR 5
-Similar to -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 "-" indicating that no response was received to the fourth
-request.
-.IP \fB-d\fR 5
-Use gethostbyaddr(3NSL) 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.
-.IP \fB-e\fR 5
-Show elapsed (round-trip) time of packets.
-.IP \fB-f\fR 5
-Read list of targets from a file.  
-
-% fping < targets_file
-
-.IP \fB-g\fR 5
-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.
-
-ex. To ping the class C 192.168.1.x, the specified command line could look like either:
-
-fping -g 192.168.1.0/24
-
-or
-
-fping -g 192.168.1.0 192.168.1.255
-.IP \fB-h\fR 5
-Print usage message.
-.IP \fB-i\fIn\fR 5
-The minimum amount of time (in milliseconds) between sending a ping packet to any target (default is 25).
-.IP \fB-l\fR 5
-Loop sending packets to each target indefinitely.  Can be interrupted
-with ctl-C; statistics about responses for each target are then displayed.
-.IP \fB-m\fR 5
-Send pings to each of a target host's multiple interfaces.
-.IP \fB-n\fR 5
-Same as -d.
-.IP \fB-p\fR 5
-In looping or counting modes (-l, -c, or -C), this parameter sets the
-time in milliseconds that
-.B fping
-waits between successive packets to an individual target.  Default is
-1000.
-.IP \fB-q\fR 5
-Quiet. Don't show per-target results, just set final exit status.
-.IP \fB-Q\fIn\fR 5
-Like -q, but show summary results every n seconds.
-.IP \fB-r\fIn\fR 5
-Retry limit (default 3). This is the number of times an attempt at pinging
-a target will be made, not including the first try.
-.IP \fB-s\fR 5
-Print cumulative statistics upon exit.
-.IP \fB-t\fIn\fR 5
-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.
-.IP \fB-u\fR 5
-Show targets that are unreachable.
-.IP \fB-v\fR 5
-Print 
-.B fping
-version information.
-
-.SH EXAMPLES
-The following perl script will check a list of hosts and send mail if
-any are unreachable. It uses the open2 function which allows a program
-to be opened for reading and writing. fping does not start pinging the
-list of systems until it reads EOF, which it gets after INPUT is closed. 
-Sure the open2 usage is not needed in this example, but it's a good open2
-example none the less. 
-.nf
-
-#!/usr/local/bin/perl
-require 'open2.pl';
-
-$MAILTO = "root";
-
-$pid = &open2("OUTPUT","INPUT","/usr/local/bin/fping -u");
-
[email protected]=("slapshot","foo","foobar");
-
-foreach(@check) {  print INPUT "$_\\n"; }
-close(INPUT);
[email protected]=<OUTPUT>;
-
-if ($#output != -1) {
- chop($date=`date`);
- open(MAIL,"|mail -s 'unreachable systems' $MAILTO");
- print MAIL "\\nThe following systems are unreachable as of: $date\\n\\n";
- print MAIL @output;
- close MAIL;
-}
-
-.ni
-Another good example is when you want to perform an action only on hosts
-that are currently reachable.
-.nf
-
-#!/usr/local/bin/perl
-
-$hosts_to_backup = `cat /etc/hosts.backup | fping -a`;
-
-foreach $host (split(/\\n/,$hosts_to_backup)) {
-  # do it
-}
-
-.ni
-.LP
-The following is an output example: 
-.sp
-\fB% fping a.b.com x.y.z.net 192.168.0.1 192.168.0.3\fR
-.in +2
-.nf
-a.b.com is alive
-x.y.z.net is alive
-192.168.0.1 is alive
-192.168.0.3 is alive
-.fi
-.in -2
-.sp
-.LP
-The following is an output example using the '-a' option: 
-.sp
-\fB% fping -a a.b.com x.y.z.net 192.168.0.1 192.168.0.3\fR
-.in +2
-.nf
-a.b.com
-x.y.z.net
-192.168.0.1
-192.168.0.3
-.fi
-.in -2
-.LP
-The following is an output example using the '-c' option: 
-.sp
-\fb% fping -c 3 a.b.com x.y.z.net 192.168.0.1\fR
-.in +2
-.nf
-a.b.com		: [0], 84 bytes, 51.1 ms (51.1 avg, 0% loss)
-192.168.0.1	: [0], 84 bytes, 0.08 ms (0.08 avg, 0% loss) [<- 192.168.0.4]
-x.y.z.net 	: [0], 84 bytes, 70.6 ms (70.6 avg, 0% loss)
-a.b.com		: [1], 84 bytes, 60.9 ms (56.0 avg, 0% loss)
-192.168.0.1	: [1], 84 bytes, 0.09 ms (0.08 avg, 0% loss) [<- 192.168.0.4]
-a.b.com		: [2], 84 bytes, 40.6 ms (50.9 avg, 0% loss)
-192.168.0.1	: [2], 84 bytes, 0.11 ms (0.09 avg, 0% loss) [<- 192.168.0.4]
-x.y.z.net		: [2], 84 bytes, 68.8 ms (69.7 avg, 33% loss)
-.sp
-a.b.com		: xmt/rcv/%loss = 3/3/0%, min/avg/max = 40.6/50.9/60.9
-x.y.z.net		: xmt/rcv/%loss = 3/2/33%, min/avg/max = 68.8/69.7/70.6
-192.168.0.1	: xmt/rcv/%loss = 3/3/0%, min/avg/max = 0.08/0.09/0.11
-.fi
-.in -2
-.LP
-The following is an output example using the '-C' option: 
-.sp
-\fb% fping -C 3 a.b.com x.y.z.net 192.168.0.1\fR
-.in +2
-.nf
-a.b.com		: [0], 84 bytes, 41.7 ms (41.7 avg, 0% loss)
-x.y.z.net		: [0], 84 bytes, 66.6 ms (66.6 avg, 0% loss)
-a.b.com		: [1], 84 bytes, 50.7 ms (46.2 avg, 0% loss)
-x.y.z.net		: [1], 84 bytes, 62.6 ms (64.6 avg, 0% loss)
-a.b.com		: [2], 84 bytes, 44.9 ms (45.8 avg, 0% loss)
-x.y.z.net		: [2], 84 bytes, 69.5 ms (66.2 avg, 0% loss)
-.sp
-a.b.com		: 41.74 50.72 44.94
-x.y.z.net		: 66.69 62.63 69.52
-192.168.0.1	: - - -
-.fi
-.in -2
-.LP
-The following is an output example using the '-e' option: 
-.sp
-\fb% fping -e a.b.com x.y.z.net 192.168.0.1\fR
-.in +2
-.nf
-a.b.com is alive (18.9 ms)
-x.y.z.net is alive (9.51 ms)
-192.168.0.1 is alive (0.35 ms)
-.fi
-.in -2
-.LP
-The following is an output example using the '-g' option: 
-.sp
-\fb% fping -g 192.168.0.1 192.168.0.6\fR
-.in +2
-.nf
-192.168.0.0 is alive [<- 192.168.0.4]
-192.168.0.4 is alive
-192.168.0.1 is unreachable
-192.168.0.2 is unreachable
-192.168.0.3 is unreachable
-192.168.0.5 is unreachable
-192.168.0.6 is unreachable
-.fi
-.in -2
-.LP
-The following is an output example using the '-s' option: 
-.sp
-\fb% fping -s a.b.com x.y.z.net 192.168.0.1\fR
-.in +2
-.nf
-a.b.com is alive
-x.y.z.net is alive
-192.168.0.1 is unreachable
-
-       3 targets
-       2 alive
-       1 unreachable
-       0 unknown addresses
-
-       4 timeouts (waiting for response)
-       6 ICMP Echos sent
-       2 ICMP Echo Replies received
-       0 other ICMP received
-
- 46.1 ms (min round trip time)
- 58.7 ms (avg round trip time)
- 71.3 ms (max round trip time)
-        4.153 sec (elapsed real time)
-.fi
-.in -2
-
-.SH AUTHORS
-.nf
-Roland J. Schemers III, Stanford University, concept and versions 1.x
-RL "Bob" Morgan, Stanford University, versions 2.x
-ZeroHype Technologies Inc. (http://www.zerohype.com), versions 2.3x and up,
-fping website:  http://www.fping.com
-.ni
-.SH 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.
-.SH BUGS
-Ha! If we knew of any we would have fixed them!
-.SH RESTRICTIONS
-Successful execution of this program requires that it be granted
-the net_icmpaccess privilege.
-
-.ni
-.SH SEE ALSO
-netstat(8), ping(8), ifconfig(8), rbac(7), privileges(7)
-
--- a/components/fping/fping.p5m	Thu Sep 08 11:15:34 2016 -0700
+++ b/components/fping/fping.p5m	Thu Sep 08 11:59:52 2016 -0700
@@ -20,7 +20,7 @@
 #
 
 #
-# Copyright (c) 2011, 2015, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved.
 #
 
 <transform file path=usr.*/man/.+ -> default mangler.man.stability volatile>
@@ -38,5 +38,5 @@
 set name=org.opensolaris.consolidation value=$(CONSOLIDATION)
 file exec_attr path=etc/security/exec_attr.d/fping
 file path=usr/bin/fping
-file fping.1m path=usr/share/man/man1m/fping.1m
+file path=usr/share/man/man8/fping.8
 license fping.license license=MIT
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/components/fping/patches/adjust-man-page.patch	Thu Sep 08 11:59:52 2016 -0700
@@ -0,0 +1,183 @@
+Adjust the fping man page to be Solaris specific.
+
+These changes should probably be sent upstream, when the patch
+can be reworked into a form that would be acceptable.
+
+--- fping-2.4b2_to/fping.8.orig	2016-09-08 08:27:57.573911510 +0000
++++ fping-2.4b2_to/fping.8	2016-09-08 08:38:11.582287257 +0000
[email protected]@ -1,4 +1,4 @@
+-.TH fping l
++.TH fping 8
+ .SH NAME
+ fping \- send ICMP ECHO_REQUEST packets to network hosts
+ .SH SYNOPSIS
[email protected]@ -13,7 +13,7 @@
+       
+ .B fping 
+ is a 
+-.MS ping 8
++.B ping
+ like program which uses the Internet Control
+ Message Protocol (ICMP) echo request to determine if a target host is
+ responding. 
[email protected]@ -83,13 +83,12 @@
+ with the "-" indicating that no response was received to the fourth
+ request.
+ .IP \fB-d\fR 5
+-Use DNS to lookup address of return ping packet. This allows you to give
++Use gethostbyaddr(3NSL) 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.
+ .IP \fB-e\fR 5
+ Show elapsed (round-trip) time of packets.
+ .IP \fB-f\fR 5
+-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:
++Read list of targets from a file.
+ 
+ % fping < targets_file
+ 
[email protected]@ -187,6 +186,121 @@
+ }
+ 
+ .ni
++.LP
++The following is an output example: 
++.sp
++\fB% fping a.b.com x.y.z.net 192.168.0.1 192.168.0.3\fR
++.in +2
++.nf
++a.b.com is alive
++x.y.z.net is alive
++192.168.0.1 is alive
++192.168.0.3 is alive
++.fi
++.in -2
++.sp
++.LP
++The following is an output example using the '-a' option: 
++.sp
++\fB% fping -a a.b.com x.y.z.net 192.168.0.1 192.168.0.3\fR
++.in +2
++.nf
++a.b.com
++x.y.z.net
++192.168.0.1
++192.168.0.3
++.fi
++.in -2
++.LP
++The following is an output example using the '-c' option: 
++.sp
++\fb% fping -c 3 a.b.com x.y.z.net 192.168.0.1\fR
++.in +2
++.nf
++a.b.com         : [0], 84 bytes, 51.1 ms (51.1 avg, 0% loss)
++192.168.0.1     : [0], 84 bytes, 0.08 ms (0.08 avg, 0% loss) [<- 192.168.0.4]
++x.y.z.net       : [0], 84 bytes, 70.6 ms (70.6 avg, 0% loss)
++a.b.com         : [1], 84 bytes, 60.9 ms (56.0 avg, 0% loss)
++192.168.0.1     : [1], 84 bytes, 0.09 ms (0.08 avg, 0% loss) [<- 192.168.0.4]
++a.b.com         : [2], 84 bytes, 40.6 ms (50.9 avg, 0% loss)
++192.168.0.1     : [2], 84 bytes, 0.11 ms (0.09 avg, 0% loss) [<- 192.168.0.4]
++x.y.z.net               : [2], 84 bytes, 68.8 ms (69.7 avg, 33% loss)
++.sp
++a.b.com         : xmt/rcv/%loss = 3/3/0%, min/avg/max = 40.6/50.9/60.9
++x.y.z.net               : xmt/rcv/%loss = 3/2/33%, min/avg/max = 68.8/69.7/70.6
++192.168.0.1     : xmt/rcv/%loss = 3/3/0%, min/avg/max = 0.08/0.09/0.11
++.fi
++.in -2
++.LP
++The following is an output example using the '-C' option: 
++.sp
++\fb% fping -C 3 a.b.com x.y.z.net 192.168.0.1\fR
++.in +2
++.nf
++a.b.com         : [0], 84 bytes, 41.7 ms (41.7 avg, 0% loss)
++x.y.z.net               : [0], 84 bytes, 66.6 ms (66.6 avg, 0% loss)
++a.b.com         : [1], 84 bytes, 50.7 ms (46.2 avg, 0% loss)
++x.y.z.net               : [1], 84 bytes, 62.6 ms (64.6 avg, 0% loss)
++a.b.com         : [2], 84 bytes, 44.9 ms (45.8 avg, 0% loss)
++x.y.z.net               : [2], 84 bytes, 69.5 ms (66.2 avg, 0% loss)
++.sp
++a.b.com         : 41.74 50.72 44.94
++x.y.z.net               : 66.69 62.63 69.52
++192.168.0.1     : - - -
++.fi
++.in -2
++.LP
++The following is an output example using the '-e' option: 
++.sp
++\fb% fping -e a.b.com x.y.z.net 192.168.0.1\fR
++.in +2
++.nf
++a.b.com is alive (18.9 ms)
++x.y.z.net is alive (9.51 ms)
++192.168.0.1 is alive (0.35 ms)
++.fi
++.in -2
++.LP
++The following is an output example using the '-g' option: 
++.sp
++\fb% fping -g 192.168.0.1 192.168.0.6\fR
++.in +2
++.nf
++192.168.0.0 is alive [<- 192.168.0.4]
++192.168.0.4 is alive
++192.168.0.1 is unreachable
++192.168.0.2 is unreachable
++192.168.0.3 is unreachable
++192.168.0.5 is unreachable
++192.168.0.6 is unreachable
++.fi
++.in -2
++.LP
++The following is an output example using the '-s' option: 
++.sp
++\fb% fping -s a.b.com x.y.z.net 192.168.0.1\fR
++.in +2
++.nf
++a.b.com is alive
++x.y.z.net is alive
++192.168.0.1 is unreachable
++
++       3 targets
++       2 alive
++       1 unreachable
++       0 unknown addresses
++
++       4 timeouts (waiting for response)
++       6 ICMP Echos sent
++       2 ICMP Echo Replies received
++       0 other ICMP received
++
++ 46.1 ms (min round trip time)
++ 58.7 ms (avg round trip time)
++ 71.3 ms (max round trip time)
++        4.153 sec (elapsed real time)
++.fi
++.in -2
+ 
+ .SH AUTHORS
+ .nf
[email protected]@ -202,19 +316,10 @@
+ .SH BUGS
+ Ha! If we knew of any we would have fixed them!
+ .SH RESTRICTIONS
+-If certain options are used (i.e, a low value for -i and -t, and a 
+-high value for -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 (when fping is installed setuid root) , normal users can't specify 
+-the following:
+-.nf
+-
+- -i n   where n < 10  msec
+- -r n   where n > 20
+- -t n   where n < 250 msec
++Successful execution of this program requires that it be granted
++the net_icmpaccess privilege.
+ 
+ .ni
+ .SH SEE ALSO
+-netstat(1), ping(8), ifconfig(8c)
++netstat(8), ping(8), ifconfig(8), rbac(7), privileges(7)
+