+.de EX \"Begin example
+.ne 5
+.if n .sp 1
+.if t .sp .5
+.nf
+.in +.5i
+..
+.de EE
+.fi
+.in -.5i
+.if n .sp 1
+.if t .sp .5
+..
.TH Sonar 1 "3-Nov-98" "X Version 11"
.SH NAME
sonar - display a sonar scope
.SH SYNOPSIS
.B sonar
+[\-ping \fIhosts-or-subnets\fP]
[\-background \fIcolor\fP]
[\-sweep\-color \fIcolor\fP]
[\-low\-color \fIcolor\fP]
[\-grid\-color \fIcolor\fP]
[\-text\-color \fIcolor\fP]
[\-ttl \fIinteger\fP]
-[\-mode ping]
[\-font \fIfont\fP]
[\-ping\-timeout \fIint\fP]
-[\-ping\-source list | file | subnet ]
-[\-ping\-file \fIhosts-file\fP]
-[\-ping\-list \fIhost-name-list\fP]
[\-team-a-name \fIstring\fP]
[\-team-b-name \fIstring\fP]
[\-team-a-count \fIint\fP]
[\-team-b-count \fIint\fP]
+[\-no\-dns]
+[\-no\-times]
+[\-debug]
.SH DESCRIPTION
The \fIsonar\fP program displays a sonar scope on the computer's screen.
This scope polls a sensor as the sweep goes around the scope and displays
"Time to live": visible time of a Bogie. Try values between 10 (very short)
and 100.
.TP 8
-.B \-mode \fIsimulation | ping\fP
-The sensor mode to use, the currently supported modes \fIsimulate\fP (the
-default) and \fIping\fP.
-.TP 8
.B \-font \fIfont\fP
The font used to display text on the scope. Default "fixed".
.TP 8
The amount of time in milliseconds the program will wait for an answer
to a ping.
.TP 8
-.B \-ping\-source list | file | subnet
-Th source of the list of hosts to ping. Valid values are: \fIlist\fP,
-\fIfile\fP, \fIsubnet\fP. The first two values are described below;
-and \fIsubnet\fP indicates that the sonar should ping all hosts in the
-same subnet as the current machine. (All addresses are treated
-as class C nets, therefore this will at most ping about 256 hosts.)
+.B \-ping \fIhosts-or-subnets\fP
+The list of things to ping, separated by commas or spaces.
+Elements of this list may be:
+.RS 8
+.TP 12
+.B simulation
+to run in simulation mode, instead of pinging real hosts (this is the default
+if the program is not installed setuid);
+.TP 12
+.I hostname
+to ping the given host;
+.TP 12
+.I A.B.C.D
+to ping the given IP address;
+.TP 12
+.B subnet
+to ping the local class C subnet (the nearest 255 addresses);
+.TP 12
+.B subnet/\fINN\fP
+to ping a different-sized local subnet: e.g., \fBsubnet/28\fP would ping
+a 4-bit subnet (the nearest 15 addresses);
+.TP 12
+.I A.B.C.D/NN
+to ping an arbitrary other subnet: the IP address specifies the base address,
+and the part after the slash is how wide the subnet is. Typical values
+are /24 (for 255 addresses) and /28 (for 15 addresses.)
+.TP 12
+.I filename
+to ping the hosts listed in the given file. This file can be in the
+format used by \fI/etc/hosts\fP, or it can be any file that has host
+names as the first element on each line. If you use ssh, try this:
+
+ sonar -ping $HOME/.ssh/known_hosts
+.RE
.TP 8
-.B \-ping\-file \fIfilename\fP
-The path to a file in \fI/etc/hosts\fP format. Only used when \fIpingSource\fP
-is set to \fIfile\fP.
+.B \-no\-dns
+Do not attempt to resolve IP addresses to hostnames.
.TP 8
-.B \-ping\-list \fIlist\fP
-A comma separated list of hostnames, eg \fI"pinky,brain,dot"\fP.
-Only used when \fIpingSource\fP is set to \fIlist\fP.
+.B \-no\-times
+Do not display ping times beneath the host names.
.TP 8
.B \-team-a-name \fIstring\fP
-The name of team A, in simulation-mode.
+In simulation mode, the name of team A.
.TP 8
.B \-team-b-name \fIstring\fP
-The name of team B, in simulation-mode.
+In simulation mode, the name of team B.
.TP 8
.B \-team-a-count \fIint\fP
-The number of bogies on team A, in simulation-mode.
+In simulation mode, the number of bogies on team A.
.TP 8
.B \-team-b-count \fIint\fP
-The number of bogies on team B, in simulation-mode.
+In simulation mode, the number of bogies on team B.
.SH RESOURCES
Configuration of the targets to ping is best done by setting X Resources.
.PP
.B ttl \fI(integer)\fP
See option \-ttl, above; default value is \fI90\fP or one sweep.
.TP 8
-.B mode \fI(ping)\fP
-See option \-mode, above. If set to \fIdefault\fP, it will ping hosts if
-possible, otherwise, will run in simulation-mode.
+.B ping \fI(string)\fP
+See option \-ping, above. If set to \fBdefault\fP, it will ping
+the contents of /etc/hosts if possible, otherwise, will run in
+simulation-mode.
.TP 8
.B font \fI(font)\fP
See option \-font, above; default value is \fIfixed\fP.
.TP 8
.B pingTimeout \fI(Integer)\fP
-See option \-pingtimeout, above; default value is \fI3000\fP.
-.TP 8
-.B pingSource \fIlist | file | subnet\fP
-See option \-ping\-source, above. Default value is \fIhostfile\fP.
-.TP 8
-.B pingFile \fIpathname\fP
-See option \-ping\-file, above. Default value is \fI/etc/hosts\fP.
-.TP 8
-.B pingList \fIhost,host,host...\fP
-See option \-ping\-list, above; default value is \fI"localhost"\fP.
+See option \-pingtimeout, above; default value is 3000.
.TP 8
.B teamAName \fIstring\fP
-See option \-team\-a\-name, above. Default value is "F18".
+See option \-team\-a\-name, above. Default value is \fBF18\fP.
.TP 8
.B teamBName \fIstring\fP
-See option \-teamBName, above. Default value is "MIG".
+See option \-teamBName, above. Default value is \fBMIG\fP.
.TP 8
.B teamACount \fIint\fP
See option \-teamACount, above. Default value is 4.
See option \-teamBCount, above. Default value is 4.
.SH NOTES
In order to use the ping sensor, this program must be installed as
-setuid root, so that it can create an ICMP socket.
+setuid root, so that it can create an ICMP socket. Root privileges
+are disavowed shortly after startup (just after connecting to the
+X server and reading the resource database) so this is \fIbelieved\fP
+to be a safe thing to do, but it is usually recommended that you
+have as few setuid programs around as possible, on general principles.
+.EX
+chown root.root sonar
+chmod u+s sonar
+.EE
+In ping-mode, the display is a logarithmic scale, calibrated so that the
+three rings represent ping times of approximately 2.5, 70 and 2,000
+milliseconds respectively.
+
+This means that if any the hosts you are pinging take longer than 2
+seconds to respond, they won't show up; and if you are pinging several
+hosts with very fast response times, they will all appear close to the
+center of the screen (making their names hard to read.)
.SH SEE ALSO
.BR X (1),
.BR xscreensaver (1),
.BR ping (8)
.SH COPYRIGHT
-Copyright \(co 1998 by Stephen Martin. (smartin@canada.com)
+Copyright \(co 1998 by Stephen Martin. <smartin@canada.com>
+Copyright \(co 2000-2004 by Jamie Zawinski <jwz@jwz.org>
Permission to use, copy, modify, distribute, and sell this software and its
documentation for any purpose is hereby granted without fee, provided that
Stephen Martin <smartin@canada.com>, 3-nov-98.
Thanks to Tom Kelly for suggesting a modular approach to the sensor
-amoung other things.
+among other things.
Thomas Bahls <thommy@cs.tu-berlin.de> hacked the "ttl" option, 12-jul-98.
+Better subnet support and command-line processing by Jamie Zawinski, 17-Jul-00.