Changeset a8fa078 in rtems for doc


Ignore:
Timestamp:
09/14/14 22:00:18 (10 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.11, 5, master
Children:
ebf9a05
Parents:
1434dbd6
git-author:
Chris Johns <chrisj@…> (09/14/14 22:00:18)
git-committer:
Chris Johns <chrisj@…> (09/16/14 05:19:58)
Message:

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.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/shell/network.t

    r1434dbd6 ra8fa078  
    1515@item @code{ifconfig} - configure a network interface
    1616@item @code{route} - show or manipulate the IP routing table
     17@item @code{ping} - ping a host or IP address
    1718
    1819@end itemize
     
    104105mbufs:2048    clusters: 128    free:  63
    105106drops:   0       waits:   0  drains:   0
    106       free:1967          data:79          header:2           socket:0       
    107        pcb:0           rtable:0           htable:0           atable:0       
    108     soname:0           soopts:0           ftable:0           rights:0       
    109     ifaddr:0          control:0          oobdata:0       
     107      free:1967          data:79          header:2           socket:0
     108       pcb:0           rtable:0           htable:0           atable:0
     109    soname:0           soopts:0           ftable:0           rights:0
     110    ifaddr:0          control:0          oobdata:0
    110111@end smallexample
    111112
     
    118119***** eth1 *****
    119120Ethernet Address: 00:04:9F:00:5B:21
    120 Address:192.168.1.244   Broadcast Address:192.168.1.255   Net mask:255.255.255.0   
     121Address:192.168.1.244   Broadcast Address:192.168.1.255   Net mask:255.255.255.0
    121122Flags: Up Broadcast Running Active Multicast
    122 Send queue limit:50   length:1    Dropped:0       
    123       Rx Interrupts:889            Not First:0               Not Last:0       
    124               Giant:0              Non-octet:0       
    125             Bad CRC:0                Overrun:0              Collision:0       
    126       Tx Interrupts:867             Deferred:0         Late Collision:0       
    127    Retransmit Limit:0               Underrun:0             Misaligned:0       
     123Send queue limit:50   length:1    Dropped:0
     124      Rx Interrupts:889            Not First:0               Not Last:0
     125              Giant:0              Non-octet:0
     126            Bad CRC:0                Overrun:0              Collision:0
     127      Tx Interrupts:867             Deferred:0         Late Collision:0
     128   Retransmit Limit:0               Underrun:0             Misaligned:0
    128129@end smallexample
    129130
     
    191192@findex CONFIGURE_SHELL_COMMAND_NETSTATS
    192193
    193 This command is included in the default shell command set. 
     194This command is included in the default shell command set.
    194195When building a custom command set, define
    195196@code{CONFIGURE_SHELL_COMMAND_NETSTATS} to have this
     
    261262***** eth1 *****
    262263Ethernet Address: 00:04:9F:00:5B:21
    263 Address:192.168.1.244   Broadcast Address:192.168.1.255   Net mask:255.255.255.0   
     264Address:192.168.1.244   Broadcast Address:192.168.1.255   Net mask:255.255.255.0
    264265Flags: Up Broadcast Running Active Multicast
    265 Send queue limit:50   length:1    Dropped:0       
    266       Rx Interrupts:5391           Not First:0               Not Last:0       
    267               Giant:0              Non-octet:0       
    268             Bad CRC:0                Overrun:0              Collision:0       
    269       Tx Interrupts:5256            Deferred:0         Late Collision:0       
    270    Retransmit Limit:0               Underrun:0             Misaligned:0     
     266Send queue limit:50   length:1    Dropped:0
     267      Rx Interrupts:5391           Not First:0               Not Last:0
     268              Giant:0              Non-octet:0
     269            Bad CRC:0                Overrun:0              Collision:0
     270      Tx Interrupts:5256            Deferred:0         Late Collision:0
     271   Retransmit Limit:0               Underrun:0             Misaligned:0
    271272@end smallexample
    272273
     
    276277@findex CONFIGURE_SHELL_COMMAND_IFCONFIG
    277278
    278 This command is included in the default shell command set. 
     279This command is included in the default shell command set.
    279280When building a custom command set, define
    280281@code{CONFIGURE_SHELL_COMMAND_IFCONFIG} to have this
     
    382383@findex CONFIGURE_SHELL_COMMAND_ROUTE
    383384
    384 This command is included in the default shell command set. 
     385This command is included in the default shell command set.
    385386When building a custom command set, define
    386387@code{CONFIGURE_SHELL_COMMAND_ROUTE} to have this
     
    412413@end example
    413414
     415@c
     416@c
     417@c
     418@page
     419@subsection ping - ping a host or IP address
     420
     421@pgindex ping
     422
     423@subheading SYNOPSYS:
     424
     425@example
     426ping [-AaDdfnoQqRrv] [-c count] [-G sweepmaxsize] [-g sweepminsize]
     427     [-h sweepincrsize] [-i wait] [-l preload] [-M mask | time] [-m ttl]
     428     [-p pattern] [-S src_addr] [-s packetsize] [-t timeout]
     429     [-W waittime] [-z tos] host
     430ping [-AaDdfLnoQqRrv] [-c count] [-I iface] [-i wait] [-l preload]
     431     [-M mask | time] [-m ttl] [-p pattern] [-S src_addr]
     432     [-s packetsize] [-T ttl] [-t timeout] [-W waittime]
     433     [-z tos] mcast-group
     434@end example
     435
     436@subheading DESCRIPTION:
     437
     438The ping utility uses the ICMP protocol's mandatory ECHO_REQUEST
     439datagram to elicit an ICMP ECHO_RESPONSE from a host or gateway.
     440ECHO_REQUEST datagrams (``pings'') have an IP and ICMP header,
     441followed by a ``struct timeval'' and then an arbitrary number of
     442``pad'' bytes used to fill out the packet.  The options are as
     443follows:
     444
     445@table @b
     446@item -A
     447Audible.  Output a bell (ASCII 0x07) character when no packet is
     448received before the next packet is transmitted.  To cater for
     449round-trip times that are longer than the interval between
     450transmissions, further missing packets cause a bell only if the
     451maximum number of unreceived packets has increased.
     452
     453@item -a
     454Audible.  Include a bell (ASCII 0x07) character in the output when any
     455packet is received.  This option is ignored if other format options
     456are present.
     457
     458@item -c count
     459Stop after sending (and receiving) count ECHO_RESPONSE packets.  If
     460this option is not specified, ping will operate until interrupted.  If
     461this option is specified in conjunction with ping sweeps, each sweep
     462will consist of count packets.
     463
     464@item -D
     465Set the Don't Fragment bit.
     466
     467@item -d
     468Set the SO_DEBUG option on the socket being used.
     469
     470@item -f
     471Flood ping.  Outputs packets as fast as they come back or one
     472hundred times per second, whichever is more.  For every ECHO_REQUEST
     473sent a period ``.'' is printed, while for every ECHO_REPLY received a
     474backspace is printed.  This provides a rapid display of how many
     475packets are being dropped.  Only the super-user may use this option.
     476This can be very hard on a network and should be used with caution.
     477
     478@item -G sweepmaxsize
     479Specify the maximum size of ICMP payload when sending sweeping pings.
     480This option is required for ping sweeps.
     481
     482@item -g sweepminsize
     483Specify the size of ICMP payload to start with when sending sweeping
     484pings.  The default value is 0.
     485
     486@item -h sweepincrsize
     487Specify the number of bytes to increment the size of ICMP payload
     488after each sweep when sending sweeping pings.  The default value is 1.
     489
     490@item -I iface
     491Source multicast packets with the given interface address.  This flag
     492only applies if the ping destination is a multicast address.
     493
     494@item -i wait
     495Wait wait seconds between sending each packet.  The default is to wait
     496for one second between each packet.  The wait time may be fractional,
     497but only the super-user may specify values less than 1 second.  This
     498option is incompatible with the -f option.
     499
     500@item -L
     501Suppress loopback of multicast packets.  This flag only applies if the
     502ping destination is a multicast address.
     503
     504@item -l preload
     505If preload is specified, ping sends that many packets as fast as
     506possible before falling into its normal mode of behavior.  Only the
     507super-user may use this option.
     508
     509@item -M mask | time
     510Use ICMP_MASKREQ or ICMP_TSTAMP instead of ICMP_ECHO.  For mask, print
     511the netmask of the remote machine.  Set the net.inet.icmp.maskrepl MIB
     512variable to enable ICMP_MASKREPLY.  For time, print the origination,
     513reception and transmission timestamps.
     514
     515@item -m ttl
     516Set the IP Time To Live for outgoing packets.  If not specified, the
     517kernel uses the value of the net.inet.ip.ttl MIB variable.
     518
     519@item -n
     520Numeric output only.  No attempt will be made to lookup symbolic names
     521for host addresses.
     522
     523@item -o
     524Exit successfully after receiving one reply packet.
     525
     526@item -p pattern
     527You may specify up to 16 ``pad'' bytes to fill out the packet you
     528send.  This is useful for diagnosing data-dependent problems in a
     529network.  For example, ``-p ff'' will cause the sent packet to be
     530filled with all ones.
     531
     532@item -Q
     533Somewhat quiet output.  Don't display ICMP error messages that are in
     534response to our query messages.  Originally, the -v flag was required
     535to display such errors, but -v displays all ICMP error messages.  On a
     536busy machine, this output can be overbear- ing.  Without the -Q flag,
     537ping prints out any ICMP error mes- sages caused by its own
     538ECHO_REQUEST messages.
     539
     540@item -q
     541Quiet output.  Nothing is displayed except the summary lines at
     542startup time and when finished.
     543
     544@item -R
     545Record route.  Includes the RECORD_ROUTE option in the ECHO_REQUEST
     546packet and displays the route buffer on returned packets.  Note that
     547the IP header is only large enough for nine such routes; the
     548traceroute(8) command is usually better at determining the route
     549packets take to a particular destination.  If more routes come back
     550than should, such as due to an illegal spoofed packet, ping will print
     551the route list and then truncate it at the correct spot.  Many hosts
     552ignore or discard the RECORD_ROUTE option.
     553
     554@item -r
     555Bypass the normal routing tables and send directly to a host on an
     556attached network.  If the host is not on a directly-attached network,
     557an error is returned.  This option can be used to ping a local host
     558through an interface that has no route through it (e.g., after the
     559interface was dropped).
     560
     561@item -S src_addr
     562Use the following IP address as the source address in outgoing
     563packets.  On hosts with more than one IP address, this option can be
     564used to force the source address to be something other than the IP
     565address of the interface the probe packet is sent on.  If the IP
     566address is not one of this machine's interface addresses, an error is
     567returned and nothing is sent.
     568
     569@item -s packetsize
     570Specify the number of data bytes to be sent.  The default is 56, which
     571translates into 64 ICMP data bytes when combined with the 8 bytes of
     572ICMP header data.  Only the super-user may specify val- ues more than
     573default.  This option cannot be used with ping sweeps.
     574
     575@item -T ttl
     576Set the IP Time To Live for multicasted packets.  This flag only
     577applies if the ping destination is a multicast address.
     578
     579@item -t timeout
     580Specify a timeout, in seconds, before ping exits regardless of how
     581many packets have been received.
     582
     583@item -v
     584Verbose output.  ICMP packets other than ECHO_RESPONSE that are
     585received are listed.
     586
     587@item -W waittime
     588Time in milliseconds to wait for a reply for each packet sent.  If a
     589reply arrives later, the packet is not printed as replied, but
     590considered as replied when calculating statistics.
     591
     592@item -z tos
     593Use the specified type of service.
     594
     595@subheading EXIT STATUS:
     596The ping utility exits with one of the following values:
     597
     5980    At least one response was heard from the specified host.
     599
     6002    The transmission was successful but no responses were
     601     received.
     602
     603any other value an error occurred.  These values are defined in
     604<sysexits.h>.
     605
     606@subheading NOTES:
     607
     608When using ping for fault isolation, it should first be run on the
     609local host, to verify that the local network interface is up and
     610running.  Then, hosts and gateways further and further away should be
     611``pinged''.  Round-trip times and packet loss statistics are computed.
     612If duplicate packets are received, they are not included in the packet
     613loss calculation, although the round trip time of these packets is
     614used in calculating the round-trip time statistics.  When the
     615specified number of packets have been sent a brief summary is
     616displayed, showing the number of packets sent and received, and the
     617minimum, mean, maximum, and standard deviation of the round-trip
     618times.
     619
     620This program is intended for use in network testing, measurement and
     621management.  Because of the load it can impose on the network, it is
     622unwise to use ping during normal operations or from automated scripts.
     623
     624@subheading EXAMPLES:
     625
     626The following is an example of how to use @code{oing} to ping:
     627
     628@smallexample
     629[/] # ping 10.10.10.1
     630PING 10.10.10.1 (10.10.10.1): 56 data bytes
     63164 bytes from 10.10.10.1: icmp_seq=0 ttl=63 time=0.356 ms
     63264 bytes from 10.10.10.1: icmp_seq=1 ttl=63 time=0.229 ms
     63364 bytes from 10.10.10.1: icmp_seq=2 ttl=63 time=0.233 ms
     63464 bytes from 10.10.10.1: icmp_seq=3 ttl=63 time=0.235 ms
     63564 bytes from 10.10.10.1: icmp_seq=4 ttl=63 time=0.229 ms
     636
     637--- 10.10.10.1 ping statistics ---
     6385 packets transmitted, 5 packets received, 0.0% packet loss
     639round-trip min/avg/max/stddev = 0.229/0.256/0.356/0.050 ms
     640[/] # ping -f -c 10000  10.10.10.1
     641PING 10.10.10.1 (10.10.10.1): 56 data bytes
     642.
     643--- 10.10.10.1 ping statistics ---
     64410000 packets transmitted, 10000 packets received, 0.0% packet loss
     645round-trip min/avg/max/stddev = 0.154/0.225/0.533/0.027 ms
     646@end smallexample
     647
     648@subheading CONFIGURATION:
     649
     650@findex CONFIGURE_SHELL_NO_COMMAND_PING
     651@findex CONFIGURE_SHELL_COMMAND_PING
     652
     653This command is included in the default shell command set.
     654When building a custom command set, define
     655@code{CONFIGURE_SHELL_COMMAND_PING} to have this
     656command included.
     657
     658This command can be excluded from the shell command set by
     659defining @code{CONFIGURE_SHELL_NO_COMMAND_PING} when all
     660shell commands have been configured.
     661
     662@subheading PROGRAMMING INFORMATION:
     663
     664@findex rtems_shell_rtems_main_ping
     665
     666The @code{ping} is implemented by a C language function
     667which has the following prototype:
     668
     669@example
     670int rtems_shell_rtems_main_ping(
     671  int    argc,
     672  char **argv
     673);
     674@end example
     675
     676The configuration structure for the @code{ping} has the
     677following prototype:
     678
     679@example
     680extern rtems_shell_cmd_t rtems_shell_PING_Command;
     681@end example
     682
Note: See TracChangeset for help on using the changeset viewer.