docs: Added All NetBSD Manuals

1 files changed, 478 insertions, 0 deletions

diff --git a/static/netbsd/man8/ping.8 b/static/netbsd/man8/ping.8
new file mode 100644
index 00000000..b74b740d
--- /dev/null
+++ b/static/netbsd/man8/ping.8
@@ -0,0 +1,478 @@
+.\"	$NetBSD: ping.8,v 1.50 2011/09/10 20:47:33 wiz Exp $
+.\"
+.\" Copyright (c) 1985, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)ping.8	8.2 (Berkeley) 12/11/93
+.\"
+.Dd September 10, 2011
+.Dt PING 8
+.Os
+.Sh NAME
+.Nm ping
+.Nd send
+.Tn ICMP ECHO_REQUEST
+packets to network hosts
+.Sh SYNOPSIS
+.Nm
+.Op Fl aCDdfLnoPQqRrv
+.Op Fl c Ar count
+.Op Fl E Ar policy
+.Op Fl g Ar gateway
+.Op Fl h Ar host
+.Op Fl I Ar srcaddr
+.Op Fl i Ar interval
+.Op Fl l Ar preload
+.Op Fl p Ar pattern
+.Op Fl s Ar packetsize
+.Op Fl T Ar ttl
+.Op Fl t Ar tos
+.Op Fl w Ar deadline
+.Ar host
+.Sh DESCRIPTION
+.Nm
+uses the
+.Tn ICMP
+protocol's mandatory
+.Tn ECHO_REQUEST
+datagram to elicit an
+.Tn ICMP ECHO_RESPONSE
+from a host or gateway.
+.Tn ECHO_REQUEST
+datagrams (``pings'') have an IP and
+.Tn ICMP
+header,
+followed by a
+.Dq struct timespec
+and then an arbitrary number of ``pad'' bytes used to fill out the
+packet.
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl a
+Emit an audible beep (by sending an ascii BEL character to the
+standard error output) after each non-duplicate response is received.
+This is disabled for flood pings as it would probably cause temporary
+insanity.
+.It Fl C
+Send timestamps in compat format; two 32 bit words in little endian format,
+the first one representing seconds, and the second one representing
+microseconds.
+.It Fl c Ar count
+Stop after sending (and waiting the specified delay to receive)
+.Ar count
+.Tn ECHO_RESPONSE
+packets.
+.It Fl D
+Set the
+.Dv Don't Fragment
+bit in the IP header.
+This can be used to determine the path MTU.
+.It Fl d
+Set the
+.Dv SO_DEBUG
+option on the socket being used.
+.It Fl E Ar policy
+Use IPsec policy specification string
+.Ar policy
+for packets.
+For the format of specification string, please refer
+.Xr ipsec_set_policy 3 .
+Please note that this option is same as
+.Fl P
+in KAME/FreeBSD and KAME/BSDI
+(as
+.Fl P
+was already occupied in
+.Nx ) .
+.It Fl f
+Flood ping.
+Outputs packets as fast as they come back or one hundred times per second,
+whichever is more.
+For every
+.Tn ECHO_REQUEST
+sent a period ``.'' is printed, while for every
+.Tn 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.
+.Bf -emphasis
+This can be very hard on a network and should be used with caution.
+.Ef
+.It Fl g Ar gateway
+Use Loose Source Routing to send the ECHO_REQUEST packets via
+.Ar gateway .
+.It Fl h Ar host
+is an alternate way of specifying the target host instead of as the
+last argument.
+.It Fl I Ar srcaddr
+Set the source IP address to
+.Ar srcaddr
+which can be a hostname or an IP number.
+For multicast datagrams, it also specifies the outgoing interface.
+.It Fl i Ar interval
+Wait
+.Ar interval
+seconds
+.Em between sending each packet .
+The default is to wait for one second between each packet,
+except when the -f option is used the wait interval is 0.01 seconds.
+.It Fl L
+Disable loopback when sending to multicast destinations,
+so the transmitting host doesn't see the ICMP requests.
+.It Fl l Ar preload
+If
+.Ar preload
+is specified,
+.Nm
+sends that many packets as fast as possible before falling into its normal
+mode of behavior.
+Only the super-user may use this option.
+.It Fl n
+Numeric output only.
+No attempt will be made to look up symbolic names for host addresses.
+.It Fl o
+Exit successfully after receiving one reply packet.
+.It Fl P
+Use a pseudo-random sequence for the data instead of the default,
+fixed sequence of incrementing 8-bit integers.
+This is useful to foil compression on PPP and other links.
+.It Fl p Ar 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,
+.Dq Li \-p ff
+will cause the sent packet to be filled with all
+ones.
+.It Fl Q
+Do not display responses such as Network Unreachable ICMP messages
+concerning the ECHO_REQUESTs sent.
+.It Fl q
+Quiet output.
+Nothing is displayed except the summary lines at startup time and
+when finished.
+.It Fl R
+Record Route.
+Includes the
+.Tn RECORD_ROUTE
+option in the
+.Tn ECHO_REQUEST
+packet and displays the route buffer on returned packets.
+This should show the path to the target host and back, which is
+especially useful in the case of asymmetric routing.
+Note that the IP header is only large enough for nine such addresses,
+and only seven when using the
+.Fl g
+option.
+This is why it was necessary to invent
+.Xr traceroute 8 .
+Many hosts ignore or discard this option.
+.It Fl 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 by
+.Xr routed 8 ) .
+.It Fl s Ar packetsize
+Specifies the number of data bytes to be sent.
+The default is 56, which translates into 64
+.Tn ICMP
+data bytes when combined
+with the 8 bytes of
+.Tn ICMP
+header data.
+The maximum allowed value is 65467 bytes.
+.It Fl T Ar ttl
+Use the specified time-to-live.
+.It Fl t Ar tos
+Use the specified hexadecimal type of service.
+.It Fl v
+Verbose output.
+.Tn ICMP
+packets other than
+.Tn ECHO_RESPONSE
+that are received are listed.
+.It Fl w Ar deadline
+Specifies a timeout, in seconds, before ping exits regardless of
+how many packets have been sent or received.
+.El
+.Pp
+When using
+.Nm
+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''.
+.Pp
+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 minimum/average/maximum round-trip time numbers.
+.Pp
+When the specified number of packets have been sent (and received) or
+if the program is terminated with a
+.Dv SIGINT ,
+a brief summary is displayed.
+The summary information can be displayed while
+.Nm
+is running by sending it a
+.Dv SIGINFO
+signal (see the
+.Dq status
+argument for
+.Xr stty 1
+for more information).
+.Pp
+.Nm
+continually sends one datagram per second, and prints one line of
+output for every ECHO_RESPONSE returned.
+On a trusted system with IP
+Security Options enabled, if the network idiom is not MONO,
+.Nm
+also prints a second line containing the hexadecimal representation
+of the IP security option in the ECHO_RESPONSE.
+If the
+.Fl c
+count option is given, only that number of requests is sent.
+No output is produced if there is no response.
+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 minimum/average/maximum round-trip time numbers.
+When the specified number of packets have been sent (and received) or if
+the program is terminated with an interrupt (SIGINT), a brief
+summary is displayed.
+When not using the
+.Fl f
+(flood) option, the first interrupt, usually generated by control-C or DEL,
+causes
+.Nm
+to wait for its outstanding requests to return.
+It will wait no longer than the longest round trip time
+encountered by previous, successful pings.
+The second interrupt stops ping immediately.
+.Pp
+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
+.Nm
+during normal operations or from automated scripts.
+.Sh ICMP PACKET DETAILS
+An IP header without options is 20 bytes.
+An
+.Tn ICMP
+.Tn ECHO_REQUEST
+packet contains an additional 8 bytes worth of
+.Tn ICMP
+header followed by an arbitrary amount of data.
+When a
+.Ar packetsize
+is given, this indicated the size of this extra piece of data (the
+default is 56).
+Thus the amount of data received inside of an IP packet of type
+.Tn ICMP
+.Tn ECHO_REPLY
+will always be 8 bytes more than the requested data space (the
+.Tn ICMP
+header).
+.Pp
+If the data space is at least 
+.Dv sizeof(struct timespec)
+(16) large,
+.Nm
+uses the first
+.Dv sizeof(struct timespec)
+bytes to include a timestamp to compute round trip times.
+Otherwise if the data space is at least eight bytes large (or the
+.Fl C
+flag is specified),
+.Nm
+uses the first eight bytes of this space to include a timestamp to compute
+round trip times.
+If there are not enough bytes of pad no round trip times are given.
+.Sh DUPLICATE AND DAMAGED PACKETS
+.Nm
+will report duplicate and damaged packets.
+Duplicate packets should never occur, and seem to be caused by
+inappropriate link-level retransmissions.
+Duplicates may occur in many situations and are rarely (if ever) a
+good sign, although the presence of low levels of duplicates may not
+always be cause for alarm.
+.Pp
+Damaged packets are obviously serious cause for alarm and often
+indicate broken hardware somewhere in the
+.Nm
+packet's path (in the network or in the hosts).
+.Sh TRYING DIFFERENT DATA PATTERNS
+The (inter)network layer should never treat packets differently depending
+on the data contained in the data portion.
+Unfortunately, data-dependent problems have been known to sneak into
+networks and remain undetected for long periods of time.
+In many cases the particular pattern that will have problems is something
+that doesn't have sufficient ``transitions'', such as all ones or all
+zeros, or a pattern right at the edge, such as almost all zeros.
+It isn't necessarily enough to specify a data pattern of all zeros (for
+example) on the command line because the pattern that is of interest is
+at the data link level, and the relationship between what you type and
+what the controllers transmit can be complicated.
+.Pp
+This means that if you have a data-dependent problem you will probably
+have to do a lot of testing to find it.
+If you are lucky, you may manage to find a file that either can't be sent
+across your network or that takes much longer to transfer than other
+similar length files.
+You can then examine this file for repeated patterns that you can test
+using the
+.Fl p
+option of
+.Nm .
+.Sh TTL DETAILS
+The
+.Tn TTL
+value of an IP packet represents the maximum number of IP routers
+that the packet can go through before being thrown away.
+In current practice you can expect each router in the Internet to decrement
+the
+.Tn TTL
+field by exactly one.
+.Pp
+The
+.Tn TCP/IP
+specification states that the
+.Tn TTL
+field for
+.Tn TCP
+packets should
+be set to 60, but many systems use smaller values
+.Po
+.Bx 4.3
+uses 30,
+.Bx 4.2
+used 15
+.Pc .
+.Pp
+The maximum possible value of this field is 255, and most
+.Ux
+systems set the
+.Tn TTL
+field of
+.Tn ICMP ECHO_REQUEST
+packets to 255.
+This is why you will find you can ``ping'' some hosts, but not reach them
+with
+.Xr telnet 1
+or
+.Xr ftp 1 .
+.Pp
+In normal operation ping prints the ttl value from the packet it receives.
+When a remote system receives a ping packet, it can do one of three things
+with the
+.Tn TTL
+field in its response:
+.Bl -bullet
+.It
+Not change it; this is what Berkeley
+.Ux
+systems did before the
+.Bx 4.3 tahoe
+release.
+In this case the
+.Tn TTL
+value in the received packet will be 255 minus the
+number of routers in the round-trip path.
+.It
+Set it to 255; this is what current Berkeley
+.Ux
+systems do.
+In this case the
+.Tn TTL
+value in the received packet will be 255 minus the
+number of routers in the path
+.Em from
+the remote system
+.Em to
+the
+.Nm Ns Em ing
+host.
+.It
+Set it to some other value.
+Some machines use the same value for
+.Tn ICMP
+packets that they use for
+.Tn TCP
+packets, for example either 30 or 60.
+Others may use completely wild values.
+.El
+.Sh EXIT STATUS
+.Nm
+returns 0 on success (the host is alive),
+and non-zero if the arguments are incorrect or the host is not responding.
+.Sh SEE ALSO
+.Xr netstat 1 ,
+.Xr icmp 4 ,
+.Xr inet 4 ,
+.Xr ip 4 ,
+.Xr ifconfig 8 ,
+.Xr routed 8 ,
+.Xr spray 8 ,
+.Xr traceroute 8
+.Sh HISTORY
+The
+.Nm
+command appeared in
+.Bx 4.3 .
+IPsec support was added by WIDE/KAME project.
+.Sh BUGS
+Flood pinging is not recommended in general, and flood pinging a broadcast
+or multicast address should only be done under very controlled conditions.
+.Pp
+The
+.Nm
+program has evolved differently under different operating systems,
+and in some cases the same flag performs a different function
+under different operating systems.
+The
+.Fl t
+flag conflicts with
+.Fx .
+The
+.Fl a , c , I , i ,
+.Fl l , P , p , s ,
+and
+.Fl t
+flags conflict with
+.Sy Solaris .
+.Pp
+Some hosts and gateways ignore the
+.Tn RECORD_ROUTE
+option.
+.Pp
+The maximum IP header length is too small for options like
+.Tn RECORD_ROUTE
+to
+be completely useful.
+There's not much that that can be done about this, however.