.\" Copyright (c) 1985, 1991 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. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. 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.
.\"
.\"     $Id: bing.8,v 1.4.2.1 2001/01/19 18:45:40 pb Exp $
.\"
.Dd April 3, 1995
.Dt BING 8
.Os
.Sh NAME
.Nm bing
.Nd compute point to point throughput using two sizes of
.Tn ICMP ECHO_REQUEST
packets to a pair of remote hosts
.Sh SYNOPSIS
.Nm bing
.Op Fl dDnrRPvVwz
.Op Fl c Ar count
.Op Fl e Ar samples
.Op Fl i Ar wait
.Op Fl p Ar pattern
.Op Fl s Ar small packetsize
.Op Fl S Ar big packetsize
.Ar host1
.Ar host2
.Sh DESCRIPTION
.Nm Bing
determines bandwidth on a point-to-point link by sending
.Tn ICMP ECHO_REQUEST
packets and measuring their roundtrip times for different packet
sizes on each end of the link.
.Pp
.Ar host1
is supposed to be the nearest end of the link, while
.Ar host2
is the other end.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl c Ar count
Stop after
.Ar count
resets of the stats. Useful only in conjunction with the
.Fl e
option. Defaults to 1.
.It Fl d
Set the
.Dv SO_DEBUG
option on the socket being used.
.It Fl D
Display the measured throughput at every received packet.
By default, it is displayed only when the computed value changes,
which itself changes only when the minimum roundtrip time for one
of the packet sizes changes.
.It Fl e Ar samples
Reset stats after sending
.Ar samples
.Tn ECHO_REQUEST
packets.
.It Fl i Ar wait
Wait
.Ar wait
seconds
.Em for each
.Tn ECHO_REPLY
packet.
The default is to wait for four seconds.
.It Fl n
Numeric output only.
No attempt will be made to lookup symbolic names for host addresses.
.It Fl P
Be pedantic regarding round-trip times.
.Pp
Normally,
.Nm bing
assumes that the roundtrip time for a small packet should always
be smaller than the roundtrip time for a big packet to the same
host, that for a given size the roundtrip time for
.Nm host1
should always be smaller than the roundtrip time for
.Nm host2,
and that the increase in the roundtrip time between
.Nm host1
and
.Nm host2
should always be bigger for big packets than for small packets.
.Pp
.Nm Bing
takes advantage of this to better determine the minimum roundtrip
times.
.Pp
Option
.Fl P
disables this behaviour, in the unlikely event it could be of any
use someday. Even IP/X25 links are not weird enough to require
this, though.
.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 R
Record route.
Includes the
.Tn RECORD_ROUTE
option in the
.Tn ECHO_REQUEST
packet and displays
the route buffer on returned packets.
Note that the IP header is only large enough for nine such routes.
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 in the small packets.
The default and minimum value is 8.
.It Fl S Ar packetsize
Specifies the number of data bytes to be sent in the big packets.
The default is 108.
The size should be chosen so that big packet roundtrip times are
long enough to be accurately measured (depending on clock resolution
and number of hops).
.It Fl v
Verbose output.
.Tn ICMP
packets other than
.Tn ECHO_RESPONSE
that are received are listed.
.It Fl V
Very verbose output.
The roundtrip time of each received echo is displayed.
.It Fl w
Display possible warnings about roundtrip times all the time.
By default, warnings are printed only at the end.
.It Fl z
Fill packets with uncompressible (pseudo-random) data.
.El
.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.
When the specified number of loops have been made or
if the program is terminated with a
.Dv SIGINT ,
a brief summary is displayed.
.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 bing
during normal operations or from automated scripts.
.Sh BUGS
Many 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.
.Pp
Some of the final stats (average throughputs) almost never
give a even marginally correct result.
.Sh SEE ALSO
.Xr netstat 1 ,
.Xr ifconfig 8 ,
.Xr ping 8 ,
.Xr routed 8 ,
.Xr traceroute 8
.Sh AUTHOR
Pierre Beyssac <pb@fasterix.freenix.org>