NAME

     qstat - Get statistics from Quake servers

SYNOPSIS

     qstat [options ...] [-retry retries] [-interval interval] [-raw
     delimiter] [-f file] host[:port] ...

DESCRIPTION

     Qstat displays information about Internet Quake servers. The servers
     are either down, non-responsive, or running a game. For servers running
     a game, the server name, map name, current number of players, and
     response time are displayed. Server rules and player information may
     also be displayed.

     The host may be specified as an IP address or a hostname.

     One line will be displayed for each argument. The first component of
     the line will be an argument given on the command-line. This can be
     used as a key to match input arguments to server status. Server rules
     and player information are displayed under the server info, indented by
     one tab stop

FORMATTING OPTIONS

     -u
          Only display hosts that are running a Quake server.
     -nf
          Only display servers that are not full.
     -cn
          Display color names instead of numbers. This is the default.
     -ncn
          Display color numbers instead of color names. This is the default
          for -raw mode.
     -tc
          Display time in clock format (DhDDmDDs). This is default.
     -tsw
          Display time in stop-watch format (DD:DD:DD).
     -ts
          Display time in seconds. This is the default for -raw mode.
     -pa
          Display player addresses. This is the default for -raw mode.
     -hpn
          Display player names in hex.
     -old
          Use pre-qstat 1.5 display style.
     -raw
          Display data in "raw" mode. The argument to -raw is used to
          separate columns of information. All information returned by the
          Quake server is displayed. General server information is displayed
          in this order: command-line arg (IP address or host name), server
          name, server address (as returned by Quake server), protocol
          version, map name, maximum players, current players, average
          response time, number of retries. Server rules are displayed on
          one line with =. If significant packet loss occurs, rules may be
          missing. Missing rules are indicated by a "?" as the last rule.
          Player information is displayed one per line: player number,
          player name, player address, frags, connect time, shirt color,
          pants color. A blank line separates each set of server
          information.

INFO OPTIONS

     -R
          Fetch and display server rules.
     -P
          Fetch and display player information.

SEARCH OPTIONS

     -f
          Read hosts from the given file. If file is '-', then read from
          stdin. Multiple -f options may be used. The file should contain
          host names or IP addresses separated by white-space (tabs,
          new-lines, spaces, etc).
     -H
          Resolve IP addresses to host names. Use with caution as many quake
          servers do not have registered host names. qstat may take up to a
          minute to timeout on each unregistered IP address. The duration of
          the timeout is controlled by your platform. Names are resolved
          before attempting to contact any hosts.
     -interval
          Interval in seconds between retries. Specify as a floating point
          number. Default interval is 0.5 seconds.
     -retry
          Number of retries. Qstat will send this many packets to a host
          before considering it non-responsive. Default is 3 retries.

     The response time is a measure of the expected playability of the
     server. The first number is the server's average time in milli-seconds
     to respond to a request packet from qstat. The second number is the
     total number of retries required to fetch the displayed information.
     More retries will cause the average response time to be higher. The
     response time will be more accurate if more requests are made to the
     server. A request is made for each server rule and line of player
     information. So setting the -P and -R options will result in a more
     accurate response time.

     Quake supports a number of control codes for special effects in player
     names. Qstat normalizes the codes into the ASCII character set before
     display. The graphic codes are not translated except the orange
     brackets (hex 90, 10, 91, and 11) which are converted to '[' and ']'.
     Use the hex-player-names options -hpn to see the complete player name.

     The Quake server does not return version information. But some small
     amount of info can be gathered from the server rules. The noexit rule
     did not appear until version 1.01.

IMPLEMENTATION NOTES

     Qstat sends packets to each host and waits for return packets. After
     some interval, another packet is sent to each host which has not yet
     responded. This is done several times before the host is considered
     non-responsive. Qstat can wait for responses from up to 20 hosts at a
     time. For host lists longer than that, qstat checks more hosts as
     results are determined.

     If qstat exceeds the maximum number of retries when fetching server
     information, it will give up and try to move on to the next
     information. This means that some rules or player info may occasionally
     not appear. Player info may also be missing if a player drops out
     between getting the general server info and requesting the player info.
     If qstat times out on one rule request, no further rules can be
     fetched. This is a side-effect of the Quake protocol design.

     The number of available file descriptors limits the number of
     simultaneous responses that can be checked. Qstat reuses file
     descriptors so it can never run out. The macro MAXFD in qstat.c
     determines how many file descriptors will be simultaneously opened.
     Raise or lower this value as needed. The default is 20 file
     descriptors.

     Operating systems which translate ICMP Bad Port (ICMP_PORT_UNREACHABLE)
     into a ECONNREFUSED will display some hosts as DOWN. These hosts are up
     and connected to the network, but there is no program on the port.
     Solaris 2.5 and Irix 5.3 correctly support ICMP_PORT_UNREACHABLE, but
     Solaris 2.4 does not. See page 442 of "Unix Network Programming" by
     Richard Stevens for a description of this ICMP behavior.

     Operating systems without correct ICMP behavior will just report hosts
     without Quake servers as non-responsive. Windows NT and Windows 95
     don't seem to support this ICMP.

     For hosts with multiple IP addresses, qstat will only send packets to
     the first address returned from the name service.

BUGS

     Qstat will report bogus reponse times if a server is listed multiple
     times in a file or on the command line. Generally, the later requests
     to the same server will take much longer. Be sure to cull duplicate
     addresses from your server list. On Unix, this can be done with sort |
     uniq.

PORTABILITY

     Qstat has been compiled and tested on Solaris 2.4 and 2.5, Irix 5.3,
     Windows NT 3.51 & 4.0, Windows 95, FreeBSD 2.2, and BSDi. Sorry, no
     Linux testing on this version, though it will probably just work.

WINDOWS

     The Windows version of qstat (win32/qstat.exe) runs on Windows 95 and
     Windows NT as a console application. On Windows 95 and NT 4.0,
     short-cuts can be used to set the arguments to qstat. On Windows NT
     create a batch file similar to the supplied qstat.bat.

OS/2

     The OS/2 version of qstat (os2/qstat.exe) runs on OS/2 Warp. It was
     compiled by Per Hammer, per@mindbend.demon.co.uk. Per keeps an updated
     version of the OS/2 binary on his web page:
     http://www.mindbend.demon.co.uk/quake

VERSION

     This is qstat version 1.5. It works with qtest1 and Quake shareware
     versions 0.9x and 1.0.x from id Software. The qstat webpage is updated
     for each new version and contains links to Quake server listings and
     pages about the Quake network protocol. The page can be found at
     http://www.activesw.com/people/steve/qstat.html

AUTHOR

     Steve Jankowski
     steve@activesw.com

COPYRIGHT

     Copyright 1996 by Steve Jankowski

     Permission granted to use this software for any purpose you desire
     provided that existing copywrite notices are retained verbatim in all
     copies and you derive no monetary benefit from use of the source code
     or resulting program, files, or executable programs except as noted.
     Specific rights reserved:
     o Resale of the programs, source code, files, or program resulting from
     compiling the source code is reserved without written permission of the
     author, Steve Jankowski.
     o Inclusion of the programs, source code or program resulting from
     compiling the source code within another program or system for resale
     is reserved without the written permission of the author, Steve
     Jankowski.
     o Inclusion of the programs, source code or programs resulting from
     compiling the source code within a "compilation" software product is
     reserved without the written permission of the author, Steve Jankowski.

     o Redistribution of a modified version of the archive or its files is
     reserved without the written permission of the author, Steve Jankowski.

     Specific rights granted:
     o Permission is granted to use the programs and source code to generate
     information from which the user derives monetary benefit.
