From bf61a8b14e57ef56e8f5e190e9bdd0ba5db16a6f Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Tue, 8 Nov 2016 21:33:20 +1100 Subject: shell: Update commands to use descriptions. --- shell/network_commands.rst | 1022 ++++++++++++++++++++++---------------------- 1 file changed, 508 insertions(+), 514 deletions(-) (limited to 'shell/network_commands.rst') diff --git a/shell/network_commands.rst b/shell/network_commands.rst index 985706a..5deaa73 100644 --- a/shell/network_commands.rst +++ b/shell/network_commands.rst @@ -27,190 +27,191 @@ This section details the Network Commands available. A subsection is dedicated to each of the commands and describes the behavior and configuration of that command as well as providing an example usage. +.. raw:: latex + + \clearpage + .. _netstats: netstats - obtain network statistics ------------------------------------ .. index:: netstats -**SYNOPSYS:** - -.. code-block:: shell - - netstats [-Aimfpcut] - -**DESCRIPTION:** - -This command is used to display various types of network statistics. The -information displayed can be specified using command line arguments in various -combinations. The arguments are interpreted as follows: - -*-A* - print All statistics - -*-i* - print Inet Routes - -*-m* - print MBUF Statistics - -*-f* - print IF Statistics - -*-p* - print IP Statistics - -*-c* - print ICMP Statistics +SYNOPSYS: + .. code-block:: shell -*-u* - print UDP Statistics + netstats [-Aimfpcut] -*-t* - print TCP Statistics +DESCRIPTION: + This command is used to display various types of network statistics. The + information displayed can be specified using command line arguments in + various combinations. The arguments are interpreted as follows: -**EXIT STATUS:** + *-A* + print All statistics -This command returns 0 on success and non-zero if an error is encountered. + *-i* + print Inet Routes -**NOTES:** + *-m* + print MBUF Statistics -NONE + *-f* + print IF Statistics -**EXAMPLES:** + *-p* + print IP Statistics -The following is an example of using the ``netstats`` command to print the IP -routing table: + *-c* + print ICMP Statistics -.. code-block:: shell + *-u* + print UDP Statistics - [/] $ netstats -i - Destination Gateway/Mask/Hw Flags Refs Use Expire Interface - default 192.168.1.14 UGS 0 0 0 eth1 - 192.168.1.0 255.255.255.0 U 0 0 1 eth1 - 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1219 eth1 - 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 840 1202 eth1 - 192.168.1.151 00:1C:23:B2:0F:BB UHL 1 23 1219 eth1 + *-t* + print TCP Statistics -The following is an example of using the ``netstats`` command to print the MBUF -statistics: +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -.. code-block:: shell +NOTES: + NONE + +EXAMPLES: + The following is an example of using the ``netstats`` command to print the + IP routing table: - [/] $ netstats -m - ************ 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 + .. code-block:: shell -The following is an example of using the ``netstats`` command to print the -print the interface statistics: + [/] $ netstats -i + Destination Gateway/Mask/Hw Flags Refs Use Expire Interface + default 192.168.1.14 UGS 0 0 0 eth1 + 192.168.1.0 255.255.255.0 U 0 0 1 eth1 + 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1219 eth1 + 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 840 1202 eth1 + 192.168.1.151 00:1C:23:B2:0F:BB UHL 1 23 1219 eth1 -.. code-block:: shell + The following is an example of using the ``netstats`` command to print the + MBUF statistics: - [/] $ netstats -f - ************ 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 - 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 + .. code-block:: shell -The following is an example of using the ``netstats`` command to print the -print IP statistics: + [/] $ netstats -m + ************ 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 -.. code-block:: shell + The following is an example of using the ``netstats`` command to print the + print the interface statistics: - [/] $ netstats -p - ************ IP Statistics ************ - total packets received 894 - packets rcvd for unreachable dest 13 - datagrams delivered to upper level 881 - total ip packets generated here 871 + .. code-block:: shell -The following is an example of using the ``netstats`` command to print the ICMP -statistics: + [/] $ netstats -f + ************ 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 + 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 -.. code-block:: shell + The following is an example of using the ``netstats`` command to print the + print IP statistics: - [/] $ netstats -c - ************ ICMP Statistics ************ - Type 0 sent 843 - number of responses 843 - Type 8 received 843 + .. code-block:: shell -The following is an example of using the ``netstats`` command to print the UDP -statistics: + [/] $ netstats -p + ************ IP Statistics ************ + total packets received 894 + packets rcvd for unreachable dest 13 + datagrams delivered to upper level 881 + total ip packets generated here 871 -.. code-block:: shell + The following is an example of using the ``netstats`` command to print the + ICMP statistics: + + .. code-block:: shell - [/] $ netstats -u - ************ UDP Statistics ************ - -The following is an example of using the ``netstats`` command to print the TCP -statistics: - -.. code-block:: shell - - [/] $ netstats -t - ************ TCP Statistics ************ - connections accepted 1 - connections established 1 - segs where we tried to get rtt 34 - times we succeeded 35 - delayed acks sent 2 - total packets sent 37 - data packets sent 35 - data bytes sent 2618 - ack-only packets sent 2 - total packets received 47 - packets received in sequence 12 - bytes received in sequence 307 - rcvd ack packets 35 - bytes acked by rcvd acks 2590 - times hdr predict ok for acks 27 - times hdr predict ok for data pkts 10 - -**CONFIGURATION:** + [/] $ netstats -c + ************ ICMP Statistics ************ + Type 0 sent 843 + number of responses 843 + Type 8 received 843 + + The following is an example of using the ``netstats`` command to print the + UDP statistics: + + .. code-block:: shell + + [/] $ netstats -u + ************ UDP Statistics ************ + + The following is an example of using the ``netstats`` command to print the + TCP statistics: + + .. code-block:: shell + + [/] $ netstats -t + ************ TCP Statistics ************ + connections accepted 1 + connections established 1 + segs where we tried to get rtt 34 + times we succeeded 35 + delayed acks sent 2 + total packets sent 37 + data packets sent 35 + data bytes sent 2618 + ack-only packets sent 2 + total packets received 47 + packets received in sequence 12 + bytes received in sequence 307 + rcvd ack packets 35 + bytes acked by rcvd acks 2590 + times hdr predict ok for acks 27 + times hdr predict ok for data pkts 10 .. index:: CONFIGURE_SHELL_NO_COMMAND_NETSTATS .. index:: CONFIGURE_SHELL_COMMAND_NETSTATS -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_NETSTATS`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_NETSTATS`` to have + this command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_NETSTATS`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_NETSTATS`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_netstats -The ``netstats`` is implemented by a C language function -which has the following prototype: +PROGRAMMING INFORMATION: + The ``netstats`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_netstats( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``netstats`` has the following prototype: - int rtems_shell_rtems_main_netstats( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``netstats`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_NETSTATS_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_NETSTATS_Command; + \clearpage .. _ifconfig: @@ -218,79 +219,77 @@ ifconfig - configure a network interface ---------------------------------------- .. index:: ifconfig -**SYNOPSYS:** - -.. code-block:: shell - - ifconfig - ifconfig interface - ifconfig interface \[up|down] - ifconfig interface \[netmask|pointtopoint|broadcast] IP - -**DESCRIPTION:** - -This command may be used to display information about the network interfaces in -the system or configure them. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. +SYNOPSYS: + .. code-block:: shell -**NOTES:** + ifconfig + ifconfig interface + ifconfig interface \[up|down] + ifconfig interface \[netmask|pointtopoint|broadcast] IP -Just like its counterpart on GNU/Linux and BSD systems, this command is -complicated. More example usages would be a welcome submission. +DESCRIPTION: + This command may be used to display information about the network + interfaces in the system or configure them. -**EXAMPLES:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -The following is an example of how to use ``ifconfig``: +NOTES: + Just like its counterpart on GNU/Linux and BSD systems, this command is + complicated. More example usages would be a welcome submission. -.. code-block:: shell +EXAMPLES: + The following is an example of how to use ``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 - 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 + .. code-block:: shell -**CONFIGURATION:** + ************ 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 + 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 .. index:: CONFIGURE_SHELL_NO_COMMAND_IFCONFIG .. index:: CONFIGURE_SHELL_COMMAND_IFCONFIG -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_IFCONFIG`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_IFCONFIG`` to have + this command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_IFCONFIG`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_IFCONFIG`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_ifconfig -The ``ifconfig`` is implemented by a C language function which has the -following prototype: +PROGRAMMING INFORMATION: + The ``ifconfig`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_ifconfig( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``ifconfig`` has the following + prototype: - int rtems_shell_rtems_main_ifconfig( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``ifconfig`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_IFCONFIG_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_IFCONFIG_Command; + \clearpage .. _route: @@ -298,101 +297,98 @@ route - show or manipulate the ip routing table ----------------------------------------------- .. index:: route -**SYNOPSYS:** - -.. code-block:: shell - - route [subcommand] [args] - -**DESCRIPTION:** - -This command is used to display and manipulate the routing table. When invoked -with no arguments, the current routing information is displayed. When invoked -with the subcommands ``add`` or ``del``, then additional arguments must be -provided to describe the route. - -Command templates include the following: - -.. code-block:: shell - - route [add|del] -net IP_ADDRESS gw GATEWAY_ADDRESS [netmask MASK] - route [add|del] -host IP_ADDRESS gw GATEWAY_ADDRES [netmask MASK] - -When not provided the netmask defaults to ``255.255.255.0`` - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -Just like its counterpart on GNU/Linux and BSD systems, this command is -complicated. More example usages would be a welcome submission. - -**EXAMPLES:** - -The following is an example of how to use ``route`` to display, add, and delete -a new route: - -.. code-block:: shell - - [/] $ route - Destination Gateway/Mask/Hw Flags Refs Use Expire Interface - default 192.168.1.14 UGS 0 0 0 eth1 - 192.168.1.0 255.255.255.0 U 0 0 1 eth1 - 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1444 eth1 - 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 10844 1202 eth1 - 192.168.1.151 00:1C:23:B2:0F:BB UHL 2 37 1399 eth1 - [/] $ route add -net 192.168.3.0 gw 192.168.1.14 - [/] $ route - Destination Gateway/Mask/Hw Flags Refs Use Expire Interface - default 192.168.1.14 UGS 0 0 0 eth1 - 192.168.1.0 255.255.255.0 U 0 0 1 eth1 - 192.168.1.14 00:A0:C8:1C:EE:28 UHL 2 0 1498 eth1 - 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 14937 1202 eth1 - 192.168.1.151 00:1C:23:B2:0F:BB UHL 2 96 1399 eth1 - 192.168.3.0 192.168.1.14 UGS 0 0 0 eth1 - [/] $ route del -net 192.168.3.0 gw 192.168.1.14 - [/] $ route - Destination Gateway/Mask/Hw Flags Refs Use Expire Interface - default 192.168.1.14 UGS 0 0 0 eth1 - 192.168.1.0 255.255.255.0 U 0 0 1 eth1 - 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1498 eth1 - 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 15945 1202 eth1 - 192.168.1.151 00:1C:23:B2:0F:BB UHL 2 117 1399 eth1 - -**CONFIGURATION:** +SYNOPSYS: + .. code-block:: shell + + route [subcommand] [args] + +DESCRIPTION: + This command is used to display and manipulate the routing table. When + invoked with no arguments, the current routing information is displayed. + When invoked with the subcommands ``add`` or ``del``, then additional + arguments must be provided to describe the route. + + Command templates include the following: + + .. code-block:: shell + + route [add|del] -net IP_ADDRESS gw GATEWAY_ADDRESS [netmask MASK] + route [add|del] -host IP_ADDRESS gw GATEWAY_ADDRES [netmask MASK] + + When not provided the netmask defaults to ``255.255.255.0`` + +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. + +NOTES: + Just like its counterpart on GNU/Linux and BSD systems, this command is + complicated. More example usages would be a welcome submission. + +EXAMPLES: + The following is an example of how to use ``route`` to display, add, and + delete a new route: + + .. code-block:: shell + + [/] $ route + Destination Gateway/Mask/Hw Flags Refs Use Expire Interface + default 192.168.1.14 UGS 0 0 0 eth1 + 192.168.1.0 255.255.255.0 U 0 0 1 eth1 + 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1444 eth1 + 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 10844 1202 eth1 + 192.168.1.151 00:1C:23:B2:0F:BB UHL 2 37 1399 eth1 + [/] $ route add -net 192.168.3.0 gw 192.168.1.14 + [/] $ route + Destination Gateway/Mask/Hw Flags Refs Use Expire Interface + default 192.168.1.14 UGS 0 0 0 eth1 + 192.168.1.0 255.255.255.0 U 0 0 1 eth1 + 192.168.1.14 00:A0:C8:1C:EE:28 UHL 2 0 1498 eth1 + 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 14937 1202 eth1 + 192.168.1.151 00:1C:23:B2:0F:BB UHL 2 96 1399 eth1 + 192.168.3.0 192.168.1.14 UGS 0 0 0 eth1 + [/] $ route del -net 192.168.3.0 gw 192.168.1.14 + [/] $ route + Destination Gateway/Mask/Hw Flags Refs Use Expire Interface + default 192.168.1.14 UGS 0 0 0 eth1 + 192.168.1.0 255.255.255.0 U 0 0 1 eth1 + 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1498 eth1 + 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 15945 1202 eth1 + 192.168.1.151 00:1C:23:B2:0F:BB UHL 2 117 1399 eth1 .. index:: CONFIGURE_SHELL_NO_COMMAND_ROUTE .. index:: CONFIGURE_SHELL_COMMAND_ROUTE -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_ROUTE`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_ROUTE`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_ROUTE`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_ROUTE`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_route -The ``route`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``route`` is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_route( - int argc, - char **argv - ); + int rtems_shell_rtems_main_route( + int argc, + char **argv + ); -The configuration structure for the ``route`` has the following prototype: + The configuration structure for the ``route`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_ROUTE_Command; + extern rtems_shell_cmd_t rtems_shell_ROUTE_Command; + +.. raw:: latex + + \clearpage .. _ping: @@ -400,255 +396,253 @@ ping - ping a host or IP address -------------------------------- .. index:: ping -**SYNOPSYS:** - -.. code-block:: shell - - 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 - -**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: - -*-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. - -*-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. - -*-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. - -*-D* - Set the Don't Fragment bit. - -*-d* - Set the SO_DEBUG option on the socket being used. - -*-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. - -*-G sweepmaxsize* - Specify the maximum size of ICMP payload when sending sweeping pings. This - option is required for ping sweeps. - -*-g sweepminsize* - Specify the size of ICMP payload to start with when sending sweeping pings. - The default value is 0. - -*-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. - -*-I iface* - Source multicast packets with the given interface address. This flag only - applies if the ping destination is a multicast address. - -*-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. - -*-L* - Suppress loopback of multicast packets. This flag only applies if the ping - destination is a multicast address. - -*-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. - -*-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. - -*-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. - -*-n* - Numeric output only. No attempt will be made to lookup symbolic names for - host addresses. - -*-o* - Exit successfully after receiving one reply packet. - -*-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. - -*-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. - -*-q* - Quiet output. Nothing is displayed except the summary lines at startup - time and when finished. - -*-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. - -*-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). - -*-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. - -*-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. - -*-T ttl* - Set the IP Time To Live for multicasted packets. This flag only applies if - the ping destination is a multicast address. - -*-t timeout* - Specify a timeout, in seconds, before ping exits regardless of how many - packets have been received. - -*-v* - Verbose output. ICMP packets other than ECHO_RESPONSE that are received - are listed. - -*-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. - -*-z tos* - Use the specified type of service. - -**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 . - -**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. - -This command can fail if more than the FD_SET size number of file descriptors -are open. - -**EXAMPLES:** - -The following is an example of how to use ``oing`` to ping: - -.. code-block:: shell - - [/] # 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 - -**CONFIGURATION:** +SYNOPSYS: + .. code-block:: shell + + 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 + +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: + + *-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. + + *-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. + + *-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. + + *-D* + Set the Don't Fragment bit. + + *-d* + Set the SO_DEBUG option on the socket being used. + + *-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. + + *-G sweepmaxsize* + Specify the maximum size of ICMP payload when sending sweeping pings. + This option is required for ping sweeps. + + *-g sweepminsize* + Specify the size of ICMP payload to start with when sending sweeping + pings. The default value is 0. + + *-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. + + *-I iface* + Source multicast packets with the given interface address. This flag + only applies if the ping destination is a multicast address. + + *-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. + + *-L* + Suppress loopback of multicast packets. This flag only applies if the + ping destination is a multicast address. + + *-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. + + *-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. + + *-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. + + *-n* + Numeric output only. No attempt will be made to lookup symbolic names + for host addresses. + + *-o* + Exit successfully after receiving one reply packet. + + *-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. + + *-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. + + *-q* + Quiet output. Nothing is displayed except the summary lines at startup + time and when finished. + + *-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. + + *-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). + + *-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. + + *-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. + + *-T ttl* + Set the IP Time To Live for multicasted packets. This flag only + applies if the ping destination is a multicast address. + + *-t timeout* + Specify a timeout, in seconds, before ping exits regardless of how many + packets have been received. + + *-v* + Verbose output. ICMP packets other than ECHO_RESPONSE that are + received are listed. + + *-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. + + *-z tos* + Use the specified type of service. + +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 + . + +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. + + This command can fail if more than the FD_SET size number of file + descriptors are open. + +EXAMPLES: + The following is an example of how to use ``oing`` to ping: + + .. code-block:: shell + + [/] # 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 .. index:: CONFIGURE_SHELL_NO_COMMAND_PING .. index:: CONFIGURE_SHELL_COMMAND_PING -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_PING`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_PING`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_PING`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_PING`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_ping -The ``ping`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``ping`` is implemented by a C language function which has the following + prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_ping( - int argc, - char **argv - ); + int rtems_shell_rtems_main_ping( + int argc, + char **argv + ); -The configuration structure for the ``ping`` has the following prototype: + The configuration structure for the ``ping`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_PING_Command; + extern rtems_shell_cmd_t rtems_shell_PING_Command; -- cgit v1.2.3