1 .\" $NetBSD: ping.8,v 1.50 2011/09/10 20:47:33 wiz Exp $
3 .\" Copyright (c) 1985, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" @(#)ping.8 8.2 (Berkeley) 12/11/93
32 .Dd September 10, 2011
39 packets to network hosts
51 .Op Fl s Ar packetsize
63 .Tn ICMP ECHO_RESPONSE
64 from a host or gateway.
66 datagrams (``pings'') have an IP and
71 and then an arbitrary number of ``pad'' bytes used to fill out the
73 The options are as follows:
76 Emit an audible beep (by sending an ascii BEL character to the
77 standard error output) after each non-duplicate response is received.
78 This is disabled for flood pings as it would probably cause temporary
81 Send timestamps in compat format; two 32 bit words in little endian format,
82 the first one representing seconds, and the second one representing
85 Stop after sending (and waiting the specified delay to receive)
93 This can be used to determine the path MTU.
97 option on the socket being used.
99 Use IPsec policy specification string
102 For the format of specification string, please refer
103 .Xr ipsec_set_policy 3 .
104 Please note that this option is same as
106 in KAME/FreeBSD and KAME/BSDI
109 was already occupied in
113 Outputs packets as fast as they come back or one hundred times per second,
117 sent a period ``.'' is printed, while for every
119 received a backspace is printed.
120 This provides a rapid display of how many packets are being dropped.
121 Only the super-user may use this option.
123 This can be very hard on a network and should be used with caution.
126 Use Loose Source Routing to send the ECHO_REQUEST packets via
129 is an alternate way of specifying the target host instead of as the
132 Set the source IP address to
134 which can be a hostname or an IP number.
135 For multicast datagrams, it also specifies the outgoing interface.
140 .Em between sending each packet .
141 The default is to wait for one second between each packet,
142 except when the -f option is used the wait interval is 0.01 seconds.
144 Disable loopback when sending to multicast destinations,
145 so the transmitting host doesn't see the ICMP requests.
151 sends that many packets as fast as possible before falling into its normal
153 Only the super-user may use this option.
156 No attempt will be made to look up symbolic names for host addresses.
158 Exit successfully after receiving one reply packet.
160 Use a pseudo-random sequence for the data instead of the default,
161 fixed sequence of incrementing 8-bit integers.
162 This is useful to foil compression on PPP and other links.
164 You may specify up to 16 ``pad'' bytes to fill out the packet you send.
165 This is useful for diagnosing data-dependent problems in a network.
168 will cause the sent packet to be filled with all
171 Do not display responses such as Network Unreachable ICMP messages
172 concerning the ECHO_REQUESTs sent.
175 Nothing is displayed except the summary lines at startup time and
183 packet and displays the route buffer on returned packets.
184 This should show the path to the target host and back, which is
185 especially useful in the case of asymmetric routing.
186 Note that the IP header is only large enough for nine such addresses,
187 and only seven when using the
190 This is why it was necessary to invent
192 Many hosts ignore or discard this option.
194 Bypass the normal routing tables and send directly to a host on an attached
196 If the host is not on a directly-attached network, an error is returned.
197 This option can be used to ping a local host through an interface
198 that has no route through it (e.g., after the interface was dropped by
200 .It Fl s Ar packetsize
201 Specifies the number of data bytes to be sent.
202 The default is 56, which translates into 64
204 data bytes when combined
208 The maximum allowed value is 65467 bytes.
210 Use the specified time-to-live.
212 Use the specified hexadecimal type of service.
218 that are received are listed.
220 Specifies a timeout, in seconds, before ping exits regardless of
221 how many packets have been sent or received.
226 for fault isolation, it should first be run on the local host, to verify
227 that the local network interface is up and running.
228 Then, hosts and gateways further and further away should be ``pinged''.
230 Round-trip times and packet loss statistics are computed.
231 If duplicate packets are received, they are not included in the packet
232 loss calculation, although the round trip time of these packets is used
233 in calculating the minimum/average/maximum round-trip time numbers.
235 When the specified number of packets have been sent (and received) or
236 if the program is terminated with a
238 a brief summary is displayed.
239 The summary information can be displayed while
241 is running by sending it a
247 for more information).
250 continually sends one datagram per second, and prints one line of
251 output for every ECHO_RESPONSE returned.
252 On a trusted system with IP
253 Security Options enabled, if the network idiom is not MONO,
255 also prints a second line containing the hexadecimal representation
256 of the IP security option in the ECHO_RESPONSE.
259 count option is given, only that number of requests is sent.
260 No output is produced if there is no response.
261 Round-trip times and packet loss statistics are computed.
262 If duplicate packets are received,
263 they are not included in the packet loss calculation,
264 although the round trip time of these packets is used in calculating
265 the minimum/average/maximum round-trip time numbers.
266 When the specified number of packets have been sent (and received) or if
267 the program is terminated with an interrupt (SIGINT), a brief
268 summary is displayed.
271 (flood) option, the first interrupt, usually generated by control-C or DEL,
274 to wait for its outstanding requests to return.
275 It will wait no longer than the longest round trip time
276 encountered by previous, successful pings.
277 The second interrupt stops ping immediately.
279 This program is intended for use in network testing, measurement and
281 Because of the load it can impose on the network, it is unwise to use
283 during normal operations or from automated scripts.
284 .Sh ICMP PACKET DETAILS
285 An IP header without options is 20 bytes.
289 packet contains an additional 8 bytes worth of
291 header followed by an arbitrary amount of data.
294 is given, this indicated the size of this extra piece of data (the
296 Thus the amount of data received inside of an IP packet of type
299 will always be 8 bytes more than the requested data space (the
303 If the data space is at least
304 .Dv sizeof(struct timespec)
308 .Dv sizeof(struct timespec)
309 bytes to include a timestamp to compute round trip times.
310 Otherwise if the data space is at least eight bytes large (or the
314 uses the first eight bytes of this space to include a timestamp to compute
316 If there are not enough bytes of pad no round trip times are given.
317 .Sh DUPLICATE AND DAMAGED PACKETS
319 will report duplicate and damaged packets.
320 Duplicate packets should never occur, and seem to be caused by
321 inappropriate link-level retransmissions.
322 Duplicates may occur in many situations and are rarely (if ever) a
323 good sign, although the presence of low levels of duplicates may not
324 always be cause for alarm.
326 Damaged packets are obviously serious cause for alarm and often
327 indicate broken hardware somewhere in the
329 packet's path (in the network or in the hosts).
330 .Sh TRYING DIFFERENT DATA PATTERNS
331 The (inter)network layer should never treat packets differently depending
332 on the data contained in the data portion.
333 Unfortunately, data-dependent problems have been known to sneak into
334 networks and remain undetected for long periods of time.
335 In many cases the particular pattern that will have problems is something
336 that doesn't have sufficient ``transitions'', such as all ones or all
337 zeros, or a pattern right at the edge, such as almost all zeros.
338 It isn't necessarily enough to specify a data pattern of all zeros (for
339 example) on the command line because the pattern that is of interest is
340 at the data link level, and the relationship between what you type and
341 what the controllers transmit can be complicated.
343 This means that if you have a data-dependent problem you will probably
344 have to do a lot of testing to find it.
345 If you are lucky, you may manage to find a file that either can't be sent
346 across your network or that takes much longer to transfer than other
347 similar length files.
348 You can then examine this file for repeated patterns that you can test
356 value of an IP packet represents the maximum number of IP routers
357 that the packet can go through before being thrown away.
358 In current practice you can expect each router in the Internet to decrement
361 field by exactly one.
365 specification states that the
370 be set to 60, but many systems use smaller values
378 The maximum possible value of this field is 255, and most
383 .Tn ICMP ECHO_REQUEST
385 This is why you will find you can ``ping'' some hosts, but not reach them
391 In normal operation ping prints the ttl value from the packet it receives.
392 When a remote system receives a ping packet, it can do one of three things
395 field in its response:
398 Not change it; this is what Berkeley
400 systems did before the
405 value in the received packet will be 255 minus the
406 number of routers in the round-trip path.
408 Set it to 255; this is what current Berkeley
413 value in the received packet will be 255 minus the
414 number of routers in the path
422 Set it to some other value.
423 Some machines use the same value for
425 packets that they use for
427 packets, for example either 30 or 60.
428 Others may use completely wild values.
432 returns 0 on success (the host is alive),
433 and non-zero if the arguments are incorrect or the host is not responding.
448 IPsec support was added by WIDE/KAME project.
450 Flood pinging is not recommended in general, and flood pinging a broadcast
451 or multicast address should only be done under very controlled conditions.
455 program has evolved differently under different operating systems,
456 and in some cases the same flag performs a different function
457 under different operating systems.
470 Some hosts and gateways ignore the
474 The maximum IP header length is too small for options like
477 be completely useful.
478 There's not much that that can be done about this, however.