shell: Add a ping command.

The ping code is taken from a recent FreeBSD release. Some options have been
tested, other not tested or do not work. This could be due to the age of
our TCP/IP stack.

This version of ping will not work if more than 64 file descriptors are
open at once because the select FD size is 64 as set in newlib.

1 files changed, 290 insertions, 21 deletions

diff --git a/doc/shell/network.t b/doc/shell/network.t
index ec052dd2f2..a5bd86a1f1 100644
--- a/doc/shell/network.t
+++ b/doc/shell/network.t
@@ -14,6 +14,7 @@ The RTEMS shell has the following network commands:
 @item @code{netstats} - obtain network statistics
 @item @code{ifconfig} - configure a network interface
 @item @code{route} - show or manipulate the IP routing table
+@item @code{ping} - ping a host or IP address
 
 @end itemize
 
@@ -103,10 +104,10 @@ command to print the MBUF statistics:
 ************ MBUF STATISTICS ************
 mbufs:2048    clusters: 128    free:  63
 drops:   0       waits:   0  drains:   0
-      free:1967          data:79          header:2           socket:0       
-       pcb:0           rtable:0           htable:0           atable:0       
-    soname:0           soopts:0           ftable:0           rights:0       
-    ifaddr:0          control:0          oobdata:0       
+      free:1967          data:79          header:2           socket:0
+       pcb:0           rtable:0           htable:0           atable:0
+    soname:0           soopts:0           ftable:0           rights:0
+    ifaddr:0          control:0          oobdata:0
 @end smallexample
 
 The following is an example of using the @code{netstats}
@@ -117,14 +118,14 @@ command to print the print the interface statistics:
 ************ INTERFACE STATISTICS ************
 ***** eth1 *****
 Ethernet Address: 00:04:9F:00:5B:21
-Address:192.168.1.244   Broadcast Address:192.168.1.255   Net mask:255.255.255.0   
+Address:192.168.1.244   Broadcast Address:192.168.1.255   Net mask:255.255.255.0
 Flags: Up Broadcast Running Active Multicast
-Send queue limit:50   length:1    Dropped:0       
-      Rx Interrupts:889            Not First:0               Not Last:0       
-              Giant:0              Non-octet:0       
-            Bad CRC:0                Overrun:0              Collision:0       
-      Tx Interrupts:867             Deferred:0         Late Collision:0       
-   Retransmit Limit:0               Underrun:0             Misaligned:0       
+Send queue limit:50   length:1    Dropped:0
+      Rx Interrupts:889            Not First:0               Not Last:0
+              Giant:0              Non-octet:0
+            Bad CRC:0                Overrun:0              Collision:0
+      Tx Interrupts:867             Deferred:0         Late Collision:0
+   Retransmit Limit:0               Underrun:0             Misaligned:0
 @end smallexample
 
 The following is an example of using the @code{netstats}
@@ -190,7 +191,7 @@ command to print the TCP statistics:
 @findex CONFIGURE_SHELL_NO_COMMAND_NETSTATS
 @findex CONFIGURE_SHELL_COMMAND_NETSTATS
 
-This command is included in the default shell command set.  
+This command is included in the default shell command set.
 When building a custom command set, define
 @code{CONFIGURE_SHELL_COMMAND_NETSTATS} to have this
 command included.
@@ -260,14 +261,14 @@ The following is an example of how to use @code{ifconfig}:
  ************ INTERFACE STATISTICS ************
 ***** eth1 *****
 Ethernet Address: 00:04:9F:00:5B:21
-Address:192.168.1.244   Broadcast Address:192.168.1.255   Net mask:255.255.255.0   
+Address:192.168.1.244   Broadcast Address:192.168.1.255   Net mask:255.255.255.0
 Flags: Up Broadcast Running Active Multicast
-Send queue limit:50   length:1    Dropped:0       
-      Rx Interrupts:5391           Not First:0               Not Last:0       
-              Giant:0              Non-octet:0       
-            Bad CRC:0                Overrun:0              Collision:0       
-      Tx Interrupts:5256            Deferred:0         Late Collision:0       
-   Retransmit Limit:0               Underrun:0             Misaligned:0      
+Send queue limit:50   length:1    Dropped:0
+      Rx Interrupts:5391           Not First:0               Not Last:0
+              Giant:0              Non-octet:0
+            Bad CRC:0                Overrun:0              Collision:0
+      Tx Interrupts:5256            Deferred:0         Late Collision:0
+   Retransmit Limit:0               Underrun:0             Misaligned:0
 @end smallexample
 
 @subheading CONFIGURATION:
@@ -275,7 +276,7 @@ Send queue limit:50   length:1    Dropped:0
 @findex CONFIGURE_SHELL_NO_COMMAND_IFCONFIG
 @findex CONFIGURE_SHELL_COMMAND_IFCONFIG
 
-This command is included in the default shell command set.  
+This command is included in the default shell command set.
 When building a custom command set, define
 @code{CONFIGURE_SHELL_COMMAND_IFCONFIG} to have this
 command included.
@@ -381,7 +382,7 @@ default         192.168.1.14       UGS         0        0      0 eth1
 @findex CONFIGURE_SHELL_NO_COMMAND_ROUTE
 @findex CONFIGURE_SHELL_COMMAND_ROUTE
 
-This command is included in the default shell command set.  
+This command is included in the default shell command set.
 When building a custom command set, define
 @code{CONFIGURE_SHELL_COMMAND_ROUTE} to have this
 command included.
@@ -411,3 +412,271 @@ following prototype:
 extern rtems_shell_cmd_t rtems_shell_ROUTE_Command;
 @end example
 
+@c
+@c
+@c
+@page
+@subsection ping - ping a host or IP address
+
+@pgindex ping
+
+@subheading SYNOPSYS:
+
+@example
+ping [-AaDdfnoQqRrv] [-c count] [-G sweepmaxsize] [-g sweepminsize]
+     [-h sweepincrsize] [-i wait] [-l preload] [-M mask | time] [-m ttl]
+     [-p pattern] [-S src_addr] [-s packetsize] [-t timeout]
+     [-W waittime] [-z tos] host
+ping [-AaDdfLnoQqRrv] [-c count] [-I iface] [-i wait] [-l preload]
+     [-M mask | time] [-m ttl] [-p pattern] [-S src_addr]
+     [-s packetsize] [-T ttl] [-t timeout] [-W waittime]
+     [-z tos] mcast-group
+@end example
+
+@subheading DESCRIPTION:
+
+The ping utility uses the ICMP protocol's mandatory ECHO_REQUEST
+datagram to elicit an ICMP ECHO_RESPONSE from a host or gateway.
+ECHO_REQUEST datagrams (``pings'') have an IP and ICMP header,
+followed by a ``struct timeval'' and then an arbitrary number of
+``pad'' bytes used to fill out the packet.  The options are as
+follows:
+
+@table @b
+@item -A
+Audible.  Output a bell (ASCII 0x07) character when no packet is
+received before the next packet is transmitted.  To cater for
+round-trip times that are longer than the interval between
+transmissions, further missing packets cause a bell only if the
+maximum number of unreceived packets has increased.
+
+@item -a
+Audible.  Include a bell (ASCII 0x07) character in the output when any
+packet is received.  This option is ignored if other format options
+are present.
+
+@item -c count
+Stop after sending (and receiving) count ECHO_RESPONSE packets.  If
+this option is not specified, ping will operate until interrupted.  If
+this option is specified in conjunction with ping sweeps, each sweep
+will consist of count packets.
+
+@item -D
+Set the Don't Fragment bit.
+
+@item -d
+Set the SO_DEBUG option on the socket being used.
+
+@item -f
+Flood ping.  Outputs packets as fast as they come back or one
+hundred times per second, whichever is more.  For every ECHO_REQUEST
+sent a period ``.'' is printed, while for every ECHO_REPLY received a
+backspace is printed.  This provides a rapid display of how many
+packets are being dropped.  Only the super-user may use this option.
+This can be very hard on a network and should be used with caution.
+
+@item -G sweepmaxsize
+Specify the maximum size of ICMP payload when sending sweeping pings.
+This option is required for ping sweeps.
+
+@item -g sweepminsize
+Specify the size of ICMP payload to start with when sending sweeping
+pings.  The default value is 0.
+
+@item -h sweepincrsize
+Specify the number of bytes to increment the size of ICMP payload
+after each sweep when sending sweeping pings.  The default value is 1.
+
+@item -I iface
+Source multicast packets with the given interface address.  This flag
+only applies if the ping destination is a multicast address.
+
+@item -i wait
+Wait wait seconds between sending each packet.  The default is to wait
+for one second between each packet.  The wait time may be fractional,
+but only the super-user may specify values less than 1 second.  This
+option is incompatible with the -f option.
+
+@item -L
+Suppress loopback of multicast packets.  This flag only applies if the
+ping destination is a multicast address.
+
+@item -l preload
+If preload is specified, ping sends that many packets as fast as
+possible before falling into its normal mode of behavior.  Only the
+super-user may use this option.
+
+@item -M mask | time
+Use ICMP_MASKREQ or ICMP_TSTAMP instead of ICMP_ECHO.  For mask, print
+the netmask of the remote machine.  Set the net.inet.icmp.maskrepl MIB
+variable to enable ICMP_MASKREPLY.  For time, print the origination,
+reception and transmission timestamps.
+
+@item -m ttl
+Set the IP Time To Live for outgoing packets.  If not specified, the
+kernel uses the value of the net.inet.ip.ttl MIB variable.
+
+@item -n
+Numeric output only.  No attempt will be made to lookup symbolic names
+for host addresses.
+
+@item -o
+Exit successfully after receiving one reply packet.
+
+@item -p pattern
+You may specify up to 16 ``pad'' bytes to fill out the packet you
+send.  This is useful for diagnosing data-dependent problems in a
+network.  For example, ``-p ff'' will cause the sent packet to be
+filled with all ones.
+
+@item -Q
+Somewhat quiet output.  Don't display ICMP error messages that are in
+response to our query messages.  Originally, the -v flag was required
+to display such errors, but -v displays all ICMP error messages.  On a
+busy machine, this output can be overbear- ing.  Without the -Q flag,
+ping prints out any ICMP error mes- sages caused by its own
+ECHO_REQUEST messages.
+
+@item -q
+Quiet output.  Nothing is displayed except the summary lines at
+startup time and when finished.
+
+@item -R
+Record route.  Includes the RECORD_ROUTE option in the ECHO_REQUEST
+packet and displays the route buffer on returned packets.  Note that
+the IP header is only large enough for nine such routes; the
+traceroute(8) command is usually better at determining the route
+packets take to a particular destination.  If more routes come back
+than should, such as due to an illegal spoofed packet, ping will print
+the route list and then truncate it at the correct spot.  Many hosts
+ignore or discard the RECORD_ROUTE option.
+
+@item -r
+Bypass the normal routing tables and send directly to a host on an
+attached network.  If the host is not on a directly-attached network,
+an error is returned.  This option can be used to ping a local host
+through an interface that has no route through it (e.g., after the
+interface was dropped).
+
+@item -S src_addr
+Use the following IP address as the source address in outgoing
+packets.  On hosts with more than one IP address, this option can be
+used to force the source address to be something other than the IP
+address of the interface the probe packet is sent on.  If the IP
+address is not one of this machine's interface addresses, an error is
+returned and nothing is sent.
+
+@item -s packetsize
+Specify the number of data bytes to be sent.  The default is 56, which
+translates into 64 ICMP data bytes when combined with the 8 bytes of
+ICMP header data.  Only the super-user may specify val- ues more than
+default.  This option cannot be used with ping sweeps.
+
+@item -T ttl
+Set the IP Time To Live for multicasted packets.  This flag only
+applies if the ping destination is a multicast address.
+
+@item -t timeout
+Specify a timeout, in seconds, before ping exits regardless of how
+many packets have been received.
+
+@item -v
+Verbose output.  ICMP packets other than ECHO_RESPONSE that are
+received are listed.
+
+@item -W waittime
+Time in milliseconds to wait for a reply for each packet sent.  If a
+reply arrives later, the packet is not printed as replied, but
+considered as replied when calculating statistics.
+
+@item -z tos
+Use the specified type of service.
+
+@subheading EXIT STATUS:
+The ping utility exits with one of the following values:
+
+0    At least one response was heard from the specified host.
+
+2    The transmission was successful but no responses were
+     received.
+
+any other value an error occurred.  These values are defined in
+<sysexits.h>.
+
+@subheading NOTES:
+
+When using ping for fault isolation, it should first be run on the
+local host, to verify that the local network interface is up and
+running.  Then, hosts and gateways further and further away should be
+``pinged''.  Round-trip times and packet loss statistics are computed.
+If duplicate packets are received, they are not included in the packet
+loss calculation, although the round trip time of these packets is
+used in calculating the round-trip time statistics.  When the
+specified number of packets have been sent a brief summary is
+displayed, showing the number of packets sent and received, and the
+minimum, mean, maximum, and standard deviation of the round-trip
+times.
+
+This program is intended for use in network testing, measurement and
+management.  Because of the load it can impose on the network, it is
+unwise to use ping during normal operations or from automated scripts.
+
+@subheading EXAMPLES:
+
+The following is an example of how to use @code{oing} to ping:
+
+@smallexample
+[/] # ping 10.10.10.1
+PING 10.10.10.1 (10.10.10.1): 56 data bytes
+64 bytes from 10.10.10.1: icmp_seq=0 ttl=63 time=0.356 ms
+64 bytes from 10.10.10.1: icmp_seq=1 ttl=63 time=0.229 ms
+64 bytes from 10.10.10.1: icmp_seq=2 ttl=63 time=0.233 ms
+64 bytes from 10.10.10.1: icmp_seq=3 ttl=63 time=0.235 ms
+64 bytes from 10.10.10.1: icmp_seq=4 ttl=63 time=0.229 ms
+
+--- 10.10.10.1 ping statistics ---
+5 packets transmitted, 5 packets received, 0.0% packet loss
+round-trip min/avg/max/stddev = 0.229/0.256/0.356/0.050 ms
+[/] # ping -f -c 10000  10.10.10.1
+PING 10.10.10.1 (10.10.10.1): 56 data bytes
+.
+--- 10.10.10.1 ping statistics ---
+10000 packets transmitted, 10000 packets received, 0.0% packet loss
+round-trip min/avg/max/stddev = 0.154/0.225/0.533/0.027 ms
+@end smallexample
+
+@subheading CONFIGURATION:
+
+@findex CONFIGURE_SHELL_NO_COMMAND_PING
+@findex CONFIGURE_SHELL_COMMAND_PING
+
+This command is included in the default shell command set.
+When building a custom command set, define
+@code{CONFIGURE_SHELL_COMMAND_PING} to have this
+command included.
+
+This command can be excluded from the shell command set by
+defining @code{CONFIGURE_SHELL_NO_COMMAND_PING} when all
+shell commands have been configured.
+
+@subheading PROGRAMMING INFORMATION:
+
+@findex rtems_shell_rtems_main_ping
+
+The @code{ping} is implemented by a C language function
+which has the following prototype:
+
+@example
+int rtems_shell_rtems_main_ping(
+  int    argc,
+  char **argv
+);
+@end example
+
+The configuration structure for the @code{ping} has the
+following prototype:
+
+@example
+extern rtems_shell_cmd_t rtems_shell_PING_Command;
+@end example
+