1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
|
<html>
<head>
<title>QStat 2.0b documentation</title>
</head>
<BODY bgcolor=#543540 text=#e5e5e5 link=#ccffff vlink=#90e0e0>
<dl>
<H3><dt>NAME</H3>
<dd>
qstat - Get statistics from Quake servers
<H3><dt>SYNOPSIS</H3>
<dd>
<b>qstat</b> [<i>options</i> ...]
[<b>-f</b> <i>file</i>]
[<b>-qw</b> <i>host</i>[:<i>port</i>]]
[<b>-qws</b> <i>host</i>[:<i>port</i>]]
[<b>-h2s</b> <i>host</i>[:<i>port</i>]]
<br>
[<b>-raw</b> <i>delimiter</i>]
<i>host</i>[:<i>port</i>] ...
<H3><dt>Version 2.0b</H3>
<H3><dt>DESCRIPTION</H3>
<dd><p>
QStat is a command-line program that 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.
<p>
Several different Quake server types and derived games are
supported. These 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.
<p>
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.
<p>
The Quake 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 <b>-f</b> option, a text file.
</p>
<p>
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.
</p>
<H3><dt>GAME OPTIONS</H3>
<p>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 <b>-f</b>.) QuakeWorld server addresses can be fetched from a
QuakeWorld master using <b>-qw</b> or specified individually with
<b>-qws</b>. The address of Quake II servers can be specified using the
<b>-qws</b> option (must include port number) or in a file.
</p>
<p>Alternatively, addresses can be listed in a file specified with
<b>-f</b>. Each address in the file may be typed by the kind of
server it is.
</p>
<dl compact><dt><b>-qw</b> <i>host</i>[:<i>port</i>]<dd>
Query a QuakeWorld master (<i>host</i>) for its server list
and then query all the servers for status. The port defaults
to 27000 if not specified.
<dt><b>-qws</b> <i>host</i>[:<i>port</i>]<dd>
Query a single QuakeWorld server for status. The port defaults
to 27500 if not specified. This option can be used to query a
Quake II server by specifying the port number. Most Quake II
servers use port 27910.
<dt><b>-h2s</b> <i>host</i>[:<i>port</i>]<dd>
Query a single Hexen II server for status. The port defaults
to 26900 if not specified.
<dt><b>-hexen2</b><dd>
Query using the Hexen II protocol. This mode only applies to
POQS (non-QuakeWorld servers). More specifically, those
addresses listed at the end of the command-line or that do
not have a server type in an address file (see <b>-f</b>.)
<dt><b>-f</b><i> file</i><dd>
Read host addresses from the given file. If file is <b>-</b>,
then read from stdin. Multiple <b>-f</b> 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. The server types are:
<pre>
QS normal Quake server (POQS)
H2S Hexen II server (POQS)
QW QW server
QWM QW master server
Q2 Quake II server (will assume a default port of 27910)
</pre>
</dl>
<H3><dt>INFO OPTIONS</H3>
<dl compact><dt><b>-R</b><dd>
Fetch and display server rules.
<dt><b>-P</b><dd>
Fetch and display player information.
</dl>
<H3><dt>DISPLAY OPTIONS</H3>
<p>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:
<pre>
QS normal Quake server (POQS)
H2S Hexen II server (POQS)
QW QW server
QWM QW master server
Q2 Q2 server
</pre>
</p>
<dl compact><dt><b>-u</b><dd>
Only display hosts that are running a Quake server.
<dt><b>-nf</b><dd>
Do not display full servers.
<dt><b>-ne</b><dd>
Do not display empty servers.
<dt><b>-cn</b><dd>
Display color names instead of numbers. This is
the default.
<dt><b>-ncn</b><dd>
Display color numbers instead of color names. This is
the default for <b>-raw</b> mode.
<dt><b>-tc</b><dd>
Display time in clock format (DhDDmDDs). This is default.
<dt><b>-tsw</b><dd>
Display time in stop-watch format (DD:DD:DD).
<dt><b>-ts</b><dd>
Display time in seconds. This is the default for
<b>-raw</b> mode.
<dt><b>-pa</b><dd>
Display player addresses. This is the default for
<b>-raw</b> mode. Not available for QuakeWorld.
<dt><b>-hpn</b><dd>
Display player names in hex.
<dt><b>-old</b><dd>
Use pre-qstat 1.5 display style.
<dt><b>-raw</b><i> delimiter</i><dd>
Display data in "raw" mode. The argument to
<b>-raw</b> is used to separate columns of
information. All information returned by the Quake
server is displayed.
<br>
<b>POQS output</b> -- 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 <i>rule-name</i>=<i>value</i>. 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.
<br>
<b>QuakeWorld server output</b> -- 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 <i>rule-name</i>=<i>value</i>. 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.
<br>
<b>QuakeWorld master output</b> -- 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 a QW master.
<br>
<b>Quake II server output</b> -- 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.
<dt><b>-raw-arg</b><dd>
When used with <b>-raw</b>, always display the server address
as it appeared in a file or on the command-line. Note that
when <b>-H</b> is used with <b>-raw</b>, 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 <b>-raw-arg</b> is used, an additional
field, the unresolved server address, is added at the beginning
of all raw output lines.
<dt><b>-progress</b><dd>
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).
</dl>
<H3><dt>SEARCH OPTIONS</H3>
<dl compact><dt><b>-H</b><dd>
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.
<dt><b>-interval</b><i> seconds</i><dd>
Interval in seconds between retries. Specify as a
floating point number. Default interval is 0.5 seconds.
<dt><b>-retry</b><i> number</i><dd>
Number of retries. Qstat will send this many packets
to a host before considering it non-responsive. Default
is 3 retries.
<dt><b>-maxsimultaneous</b><i> number</i><dd>
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.
<dt><b>-timeout</b><i> seconds</i><dd>
Total run time in seconds before giving up. Default is
no timeout.
</dl>
<H3><dt>NOTES</H3>
<dd><p>
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 <b>-P</b> and
<b>-R</b> 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 <b>-P</b> and <b>-R</b> options do
not increase the number of requests to the server.
</p>
<p>
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 <b>-hpn</b> to see the complete player name.
</p>
<p>
Quake servers 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 includes a version key that
appears to contain the id build number.
</p>
<H3><dt>EXAMPLES</H3>
<dd><p>The following is an example address file which queries a QuakeWorld
master, several Hexen II servers, some POQS, and a few Quake II servers.
</p>
<pre>
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
</pre>
<p>If the above text were in a file called <code>QSERVER.TXT</code>,
then the servers could be queried by running:
<br>
<code>qstat -f QSERVER.TXT</code>
<H3><dt>IMPLEMENTATION NOTES</H3>
<dd><p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
For hosts with multiple IP addresses, qstat will only send
packets to the first address returned from the name service.
</p>
<H3><dt>BUGS</H3>
<dd><p>
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 <code>sort | uniq</code>.
</p>
<H3><dt>PORTABILITY</H3>
<dd><p>
QStat has been compiled and tested on Solaris 2.4/2.5/2.6,
Irix 5.3/6.2/6.3, Windows NT 3.51 & 4.0, Windows 95, FreeBSD 2.2,
BSDi, HP-UX 10.20, and various flavors of Linux.
</p>
<H3><dt>WINDOWS</H3>
<dd><p>
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.
</p>
<H3><dt>OS/2</H3>
<dd><p>
An OS/2 binary is no longer included. Try contacting Per Hammer
for an OS/2 Warp binary.
<a href="mailto:per@mindbend.demon.co.uk">per@mindbend.demon.co.uk</a>.
</p>
<H3><dt>VERSION</H3>
<dd><p>
This is qstat version 2.0b. It works with every known
version of Quake and all derivatives except versions of
QuakeWorld before 1.5. No one is running pre-1.5 QuakeWorld,
so this can hardly be a problem.
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
<br>
<a href="http://www.activesw.com/people/steve/qstat.html">
http://www.activesw.com/people/steve/qstat.html</a>
</p>
<p>Quake and Quake II created by id Software. Hexen II created by Raven Software.
</p>
<H3><dt>AUTHOR</H3>
<dd><p>
<a href="http://www.activesw.com/people/steve/">Steve Jankowski</a>
<br>
<a href="mailto:steve@activesw.com">steve@activesw.com</a>
<H3><dt>COPYRIGHT</H3>
<dd><p>
Copyright © 1996,1997 by Steve Jankowski
</p>
<p>
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.
</p>
</dl>
</body>
</html>
|
