NAME

     qstat - Get statistics from Quake servers

SYNOPSIS

     qstat [options ...] [-f file] [-qw host[:port]] [-qws host[:port]]
     [-q2m host[:port]] [-h2s host[:port]] [-hws host[:port]] [-uns
     host[:port]]
     [-raw delimiter] [-default server-type] host[:port] ...

Version 2.1a

     This release supercedes previous 2.1 releases (2.1z BETA and 2.1y
     BETA)

DESCRIPTION

     QStat is a command-line program that displays information about
     Internet game 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.

     Games supported include Quake and all derived games, and Unreal.

     The Quake servers can be divided into two categories: POQS (Plain Old
     Quake Server) and QuakeWorld. Quake shareware, Quake commercial (from
     CD), winquake, winded, unixded, and Hexen II are all POQS. The various
     versions of QuakeWorld and Quake II use a QuakeWorld type server. The
     distinction is based on network protocol used to query the servers, and
     affects the kind of information available for display.

     The different server types can be queried simultaneously. If QStat
     detects that this is being done, the output is keyed by the type of
     server being displayed. See DISPLAY OPTIONS.

     The game server may be specified as an IP address or a hostname.
     Servers can be listed on the command-line or, with the use of the -f
     option, a text file.

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

     QStat supports two additional display modes: raw and templates. In raw
     mode, the server information is displayed using simple delimiters and
     no formatting. This mode is good for programs that parse and reformat
     QStat's output. The template mode uses text files to layout the server
     information within existing text. This is ideal for generating web
     pages.

GAME OPTIONS

     These options select how a server should be queried. The address of
     POQS can be specified at the end of the command-line or in a file (see
     option -f.) QuakeWorld server addresses can be fetched from a
     QuakeWorld master using -qw or specified individually with -qws. The
     address of Quake II and Unreal servers can be specified using
     respectively the -q2s and -uns options.

     Alternatively, addresses can be listed in a file specified with -f.
     Each address in the file may be typed by the kind of server it is.

     Broadcast Queries

     QStat has limited support for broadcast queries. Broadcast queries use
     one network packet to find all the game servers on a local network. A
     broadcast returns servers of one type on one port. You may only
     broadcast to networks to which you computer is directly attached (ie.
     local networks). In this release, broadcast queries are only supported
     for: Quake II servers.

     A broadcast query is specified by prefixing an address with a '+' (plus
     sign). The address should be 255.255.255.255 or a valid broadcast
     address for a local network. On Unixes, 'ifconfig -a' will display the
     broadcast address for all attached networks.

     -qw host[:port]
          Query a QuakeWorld master (host) for its server list and then
          query all the servers for status. The port defaults to 27000 if
          not specified.
     -qw,outfile host[:port],file
          Query a QuakeWorld master for its server list and store it in
          file. If the master cannot be contacted, then file is not changed.
          If file is - (a single dash), then stdout is used. The port
          defaults to 27000 if not specified.
     -qws host[:port]
          Query a single QuakeWorld server for status. The port defaults to
          27500 if not specified.
     -q2m host[:port]
          Query a Quake II master for its server list and then query all the
          servers. The port defaults to 27900 if not specified.
     -q2m,outfile host[:port],file
          Query a Quake II master for its server list and store it in file.
          If the master cannot be contacted, then file is not changed. If
          file is - (a single dash), then stdout is used. The port defaults
          to 27900 if not specified.
     -q2s host[:port]
          Query a single Quake II server for status. The port defaults to
          27910 if not specified.
     -h2s host[:port]
          Query a single Hexen II server for status. The port defaults to
          26900 if not specified.
     -hws host[:port]
          Query a single HexenWorld server for status. The port defaults to
          26950 if not specified.
     -uns host[:query-port]
          Query a single Unreal server for status. The query-port defaults
          to 7778 if not specified. Note that Unreal uses a separate port
          for status queries, different from the game port.
     -f file
          Read host addresses 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). If an address is preceded by a server
          type identifier, then QStat queries the address according to the
          server type. Otherwise QS is assumed, unless -default is used. The
          server types are:

            QS      normal Quake server (POQS)
            H2S     Hexen II server (POQS)
            HWS     HexenWorld server
            QW      QuakeWorld server
            QWM     QuakeWorld master server
            Q2      Quake II server
            Q2M     Quake II master server
            UNS     Unreal server

     -default server-type
          Set the default server type for addresses where the type is not
          obvious. This affects the addresses at the end of the qstat
          command-line and those in a file not prefixed by a server type
          (see -f). The server-type should be one of QS, H2S, HWS, QW, QWM,
          Q2, Q2M, UNS.

INFO OPTIONS

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

DISPLAY OPTIONS

     The QStat output should be self explanatory. However, the type of
     information returned is different between POQS and QuakeWorld. If QStat
     queries multiple server types, then each server status line is prefixed
     with a key:

       QS      normal Quake server (POQS)
       H2S     Hexen II server (POQS)
       HWS     HexenWorld server
       QW      QuakeWorld server
       QWM     QuakeWorld master server
       Q2      Quake II server
       Q2M     Quake II master server
       UNS     Unreal server

     -u    Only display hosts that are up and running a Quake server.
     -nf   Do not display full servers.
     -ne   Do not display empty servers.
     -nh   Do not display header line (does not apply to raw or template
          output.)
     -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. Only
          available for Quake and Hexen II.
     -sort sort-key
          Sort servers before display. Servers are sorted according to the
          sort-key which is one or more of:
        * p - Sort by ping
        * g - Sort by game
     -hpn  Display player names in hex.
     -old  Use pre-qstat 1.5 display style.
     -raw delimiter
          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.
          POQS output -- 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 as
          rule-name=value. 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.
          QuakeWorld and HexenWorld server output -- General server
          information is displayed in this order: command-line arg (IP
          address or host name), server name, map name, maximum players,
          current players, average response time, number of retries. Server
          rules are displayed on one line as rule-name=value. Player
          information is displayed one per line: player number, player name,
          frags, connect time, shirt color, pants color, ping time
          (milliseconds), skin name. A blank line separates each set of
          server information.
          QuakeWorld and Quake II master output -- Master server information
          is displayed in this order: command-line arg (IP address or host
          name), number of servers. No other information is diplayed about
          master servers.
          Quake II server output -- General server information and server
          rules are the same as a QuakeWorld server. The rule names are
          somewhat different for Quake II. The player information currently
          returned is very limited: player name, frags, ping time
          (milliseconds). A blank line separates each set of server
          information. Unreal server output -- General server information is
          displayed in this order: command-line arg (IP address or host
          name), server name, map name, current players. No server rules are
          available. Player information is displayed one per line: player
          name, frags, deaths, team number, skin. A blank line separates
          each set of server information.
     -raw-arg
          When used with -raw, always display the server address as it
          appeared in a file or on the command-line. Note that when -H is
          used with -raw, the first field of the raw output could be a
          hostname if the server IP address was resolved. This can make
          matching up input servers addresses with raw output lines fairly
          difficult. When -raw-arg is also used, an additional field, the
          unresolved server address, is added at the beginning of all raw
          output lines.
     -progress
          Print a progress meter. Displays total servers processed,
          including timeouts and down servers. The meter is just a line of
          text that writes over itself with <cr>. Handy for interactive use
          when you are redirecting output to a file (the meter is printed on
          stderr).
     -Tserver file
     -Tplayer file
     -Theader file
     -Ttrailer file
          Output templates. Each template should be a text file containing
          QStat variables that are substituted for results from the server
          query. The -Tserver flag must present to enable template output.
          The other -T flags are optional. The server template is output
          once for each server queried. The player template, if present, is
          output once for each player (if -P is also used). The header
          template is output once before any servers are output. The trailer
          template is output once after all servers are processed. See
          Appendix A for the output template formatting and variables.
          NOTE: All of of the -T flags may be abbreviated with two
          characters: -Ts, -Tp, -Th, and -Tt.

SEARCH OPTIONS

     -H    Resolve IP addresses to host names. Use with caution as many game
          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 operating system. Names are
          resolved before attempting to query any servers.
     -Hcache cache-file
          Cache host name and IP address resolutions in cache-file. If the
          file does not exist, it is created. If -Hcache is used without -H,
          then the cache is only used for host to IP address resolution.
          WARNING A host cache file should not be shared by QStat programs
          running at the same time. If you run several QStats at the same
          time, each should have its own cache file.
     -interval seconds
          Interval in seconds between retries. Specify as a floating point
          number. Default interval is 0.5 seconds.
     -retry number
          Number of retries. QStat will send this many packets to a host
          before considering it non-responsive. Default is 3 retries.
     -maxsimultaneous number
          Number of simultaneous servers to query. Unix systems have an
          operating system imposed limit on the number of open sockets per
          process. This limit varies between 32 and 100 depending on the
          platform. On Windows 95 and Windows NT, the "select" winsock
          function limits the number of simultaneous queries to 64. These
          limits can be increased by minor changes to the code, but the
          change is different for each platform. Default is 20 simultaneous
          queries. This option may be abbreviated -maxsim.
     -timeout seconds
          Total run time in seconds before giving up. Default is no timeout.

UNREAL

     QStat has full support for querying Unreal servers. However, there are
     many bugs in the Unreal support for status queries. Expect to get "no
     response" on 4 out of 5 queries, even though the server is running. You
     can improve your chances a little by increasing the retries: -retries
     8.

     Unreal servers return a very limited set of information. The following
     "standard" information is not available from an Unreal server: server
     name, max players, server rules, ping time.

NOTES

     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. For POQS, 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 and Hexen II are POQS. For
     QuakeWorld and Quake II, QStat makes just one request to retrieve all
     the server status information, including server rules and player
     status. The -P and -R options do not increase the number of requests to
     the server.

     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 option -hpn to see the complete player name.

     POQS do 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. The Quake II server rules include a "version" key
     that contains the id build number. Recent releases of QuakeWorld have a
     "*version" key in the server rules. Unreal servers include a "gamever"
     key in the server rules that contains the server version without the
     decimal point.

EXAMPLES

     The following is an example address file which queries a QuakeWorld
     master, several Hexen II servers, some POQS, and a few Quake II
     servers.

     QWM 192.246.40.12:27004
     H2S 207.120.210.4
     H2S 204.145.225.124
     H2S 207.224.190.21
     H2S 165.166.140.154
     H2S 203.25.60.3
     QS 207.25.198.110
     QS 206.154.207.104
     QS 205.246.42.31
     QS 128.164.136.171
     Q2 sm.iquest.net
     Q2 209.39.134.5
     Q2 209.39.134.3

     If the above text were in a file called QSERVER.TXT, then the servers
     could be queried by running:
     qstat -f QSERVER.TXT

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.

     The following applies only applies to POQS. 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 servers 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.

     QStat supports Unreal version 2.15 or greater.

BUGS

     The Unreal support has some flaws. If some of the status packets are
     lost, QStat won't try to refetch the values. This will be fixed in a
     later release.

PORTABILITY

     UNIX - QStat has been compiled and tested on Solaris 2.4/2.5/2.6, Irix
     5.3/6.2/6.3/6.4, FreeBSD 2.2, BSDi, HP-UX 10.20, and various flavors of
     Linux.

     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 3.51, use a batch file.

     OS/2 - An OS/2 binary is no longer included. Try contacting Per Hammer
     for an OS/2 Warp binary. per@mindbend.demon.co.uk.

     VMS - The source includes a VMS patch from John Ross Hunt. This patch
     was tested on QStat 2.0b, but has not been tested on the current
     version. See COMPILE.txt for instructions.

VERSION

     This is QStat version 2.1a. It works with every known version of Quake
     and Unreal 2.15+. The QStat webpage is updated for each new version and
     contains links to Quake server listings and pages about the Quake and
     Unreal network protocols. The page can be found at
     http://www.activesw.com/people/steve/qstat.html

     Quake and Quake II created by id Software. Hexen II and HexenWorld
     created by Raven Software. Unreal created by Epic Games.

AUTHOR

     Steve Jankowski
     steve@activesw.com

COPYRIGHT

     Copyright  1996,1997,1998 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 derived works.

  ------------------------------------------------------------------------

APPENDIX A - Output Templates

QStat output templates provide greater control of the appearance of server
status information. The results of a server query can be organized,
formatted, and wrapped within any other text. The most obvious use is to
generate HTML for web pages. However, it could also generate custom output
for redisplay within another tool.

There are four output templates:

   * server - Output once for each server queried. (required)
   * player - Output once for each player. Must be used with -P. Invoked by
     the $PLAYERTEMPLATE variable.
   * header - Output once before any servers are queried.
   * trailer - Output once after all servers are queried.

The server template must be specified to enable template output. The other
templates are optional.

Each output template is a file containing text and QStat variables. The text
is output unchanged by QStat, but the variables are processed and replaced
by QStat. Most variables are replaced by values from a queried server. Some
variables have hardcoded values, and some generate no output, but affect how
the template is processed.

Variables are grouped according to the templates where they can be used.
General variables may be used in any of the templates. Server variables may
be used in the server template. Player variables may be used in the player
template. Expression variables may only be used with the $IF and $IFNOT
variables. If a variable is used where it doesn't make sense, it is ignored
and generates no output.

Variables are specified using one of several syntaxes:

    $VAR
    $VAR:OPTION
    $(VAR)
    $(VAR:OPTION)
    $(VAR:OPTION(ARGUMENT))

The syntax used does not affect the output. However using the $() syntax is
somewhat more readable when the text gets cluttered. If you want the
variable to be followed immediately by text, then the $() syntax must be
used.

Download considerations

If you are generating output to be downloaded, then you'll want to make your
output as small as possible. In the case of HTML, you can reduce the size of
your pages by excluding stuff.
*Remove unneeded spaces (indenting and newlines)
*Remove unneeded end tags. The HTML spec says the following tags can always
be left out: </TD> </TR> </TH>
*When creating a table, "width" modifiers are only needed on one cell of a
column. Put them on the cells of the first row of the table.

General Variables

 $QSTATURL          Output the web address of the QStat home page.
 $QSTATVERSION      Output the version of QStat being run.
 $QSTATAUTHOR       Output the name of the QStat programmer.
 $QSTATAUTHOREMAIL  Output the email address of the QStat programmer.
 $HTML              Enable HTML friendly string output. Server results may
                    include characters that have special meaning in HTML.
                    These are replaced by equivalent SGML entities. QStat
                    converts '<', '>', and '&' to '&lt;', '&gt;', and
                    '&amp;'. Use this variable once in the header template.
 $IF                Conditional output. If the variable option is "true,"
                    the template is output up to a matching $ENDIF
                    variable. If the variable option is "false," the
                    template is ignored until after a matching $ENDIF. See
                    Conditional Options for a list of supported conditional
                    options.

 $IFNOT             Conditional output. Same as $IF, but the opposite
                    sense.

 $ENDIF             End conditional output. There must be one $ENDIF for
                    each $IF and $IFNOT within a template.
 $NOW               Output the current local time.
 $TOTALSERVERS      The total number of servers to be queried.
 $TOTALUP           The number of servers up and running.
 $TOTALNOTUP        The number of servers either DOWN or TIMEOUT.
 $TOTALPLAYERS      The number of players found on all servers.
 $\                 Ignore the next newline. Not really a variable, but a
                    way to curtail the output of extra newlines. Saves
                    space in the output while the template remains
                    readable. Must be the last thing on the line.

Server Variables

 $HOSTNAME          Output the host name of the server if known, otherwise
                    the server address as given to QStat.
 $SERVERNAME        Output the name of the server.
 $PING              The time in milli-seconds to get a response from the
                    server. If the server is DOWN or TIMEOUT, nothing is
                    output.
 $PLAYERS           The number of players on the server.
 $MAXPLAYERS        The maximum number of players allowed on the server.
 $MAP               The name of the map being played.
 $GAME              The name of the game being played.

 $RETRIES           The number of retries needed to get the server status.
                    This is a measure of packet loss.

 $IPADDR            The IP address of the server. Does not include the port
                    number.
 $PORT              The port the server is running on.
 $ARG               The server address as given to QStat.
 $TYPE              Output one of the following depending on the server
                    type:

                        Quake
                        Quake II
                        Quake II Master
                        QuakeWorld
                        QuakeWorld Master
                        Hexen II
                        HexenWorld
                        Unreal

                    If the server type is not known, nothing is output.
 $RULE:name         The value of a server rule. If the rule is not returned
                    by the server, nothing is output. Must be used with the
                    -R flag.
 $ALLRULES          Output all the server rules in the format name=value
                    separated by commas. Must be used with the -R flag.
 $PLAYERTEMPLATE    Invoke the player template. The player template is
                    output once for each player on the server. Must be used
                    with the -P flag.

Player Variables

The player template is only invoked if $PLAYERTEMPLATE is used in the server
template.

 $PLAYERNAME        The name of the player.
 $FRAGS             The number of frags scored.

 $PLAYERPING        The player's ping time to the server. This value is not
                    available from Unreal servers.

 $CONNECTTIME       How long the player has been playing. This value is not
                    available from Quake II or Unreal servers.

 $SKIN              The name of the player's skin. This value is not
                    available from ?? servers.

 $MESH              The name of the player's mesh (model). This value is
                    only available from Unreal servers.

 $SHIRTCOLOR        Color of the player's shirt. This value is not
                    available from Quake II or Unreal servers.

 $PANTSCOLOR        Color of the player's pants. This value is not
                    available from Quake II or Unreal servers.
 $PLAYERIP          The IP address of the player's computer. This value is
                    only available from Quake and Hexen II servers.

 $TEAMNUM           The player's team number. This value is only available
                    from Unreal servers.

Conditional Options

These options maybe used with the $IF and $IFNOT variables. For example, to
display player information, the following could be used in the server
template:

    $(IF:PLAYERS)$(IF:FLAG(-P))
    The server has $(PLAYERS) players:
    $(PLAYERTEMPLATE)
    $(ENDIF)$(ENDIF)

The template between the $IF and $ENDIF variables will only be displayed if
the server has one or more players and the -P flag was given to QStat.

 GAME               True if the server has a game set.
 PLAYERS            True if the server has one or more players.
 QUAKE              True if the server is running Quake (the original).
 QUAKE2             True if the server is running Quake II.
 Q2MASTER           True if the server is a Quake II master.
 QUAKEWORLD         True if the server is running QuakeWorld.
 QWMASTER           True if the server is a QuakeWorld master.
 HEXEN2             True if the server is running Hexen II.
 HEXENWORLD         True if the server is running HexenWorld.
 UNREAL             True if the server is running Unreal.
 RULE(name)         True if the rule name is set on the server.
 FLAG(name)         True if the flag name was used on the QStat
                    command-line. The only flag names supported are: -H,
                    -P, and -R. Any other flag name returns false.
 UP                 True if the server is up and running.
 DOWN               True if the server is known to be not running. This is
                    true if the server computer returns an ICMP indicating
                    that nothing is running on the port. Only supported by
                    some operating systems.
 TIMEOUT            True if the server never responded to a status query.
 HOSTNOTFOUND       True if the host name lookup failed.
