XSCOPE(1) X Version 11(8 Aug 1991) XSCOPE(1)
NAME
xscope - X Window System Protocol Monitor
SYNOPSIS
xscope [ options ] ...
DESCRIPTION
xscope is a program that monitors connections between an X server and a
client. xscope prints to stdout the contents of each request, reply,
error, or event that is communicated between the server and client. This
information can be useful in debugging and performance tuning of X
servers and clients.
xscope attaches to the X server as if it were a client. By adjusting the
host and/or display number, the client can be made to attach to xscope
instead of the X server.
server <-----> xscope <-----> client
All bytes from the server are sent to xscope which sends them on to the
client. All bytes from the client are sent to xscope which passes them
on to the server. xscope is transparent to both the server and the
client.
OPTIONS
-d<display>
Defines the display number. The display number is added to the
input and output port to give the actual ports which are used
by xscope.
-h<host> Determines the host that xscope will use to find the server.
-i<input-port>
Specify the port that xscope will use to take requests from
clients (defaults is 1). For X11, this port is automatically
biased by 6000.
-o<output-port>
Determines the port that xscope will use to connect to the
server (defaults is 0). For X11, this port is automatically
biased by 6000.
-q Quiet output mode. Gives only the names of requests, replies,
errors, and events, but does not indicate contents.
-v<print-level>
Determines the level of verbosity which xscope will provide.
The print-level can be 0 (same as quiet mode), 1, 2, 3, 4. The
larger numbers give more and more output. For example, a
successful setup returns a string which is the name of the
vendor of the X server. At level 1, the explicit field giving
the length of the string is suppressed since it can be inferred
10/89 Page 1
XSCOPE(1) X Version 11(8 Aug 1991) XSCOPE(1)
from the string. At level 2 and above the length is explicitly
printed.
OPERATION
When running with xscope, three processes are involved, potentially all
on different machines:
X server
The X server will run on machine (or host) "A", display "B". ("A"
is a machine name; "B" is a display number).
xscope
xscope must be told where the X server is (what machine and what
display), and, in addition, the port-number on which to listen for X
clients. The options for xscope are "-h<Xserver-host>" and "-
d<display-number>". In this example, -hA and -dB. Typically the
display-number is not given. xscope will not try to connect to the
server until the client connects to xscope.
X client
The client should connect to xscope rather than to the server. To
avoid changing the code for the client, xscope listens on the same
port as the server for connecting clients. If the server and xscope
are on different machines, this works well. However, if the server
and xscope are on the same machine, this creates a port conflict.
To resolve this conflict, xscope can be given a different input or
output port number, as necessary, to avoid the port that the server
is listening to. The client must connect to this offset port
number. The input port for xscope is set by -i<port-number>; the
output port is set by -o<port-number>. The default input port is 1;
the default output port is 0. These ports are offset by the X11
base (6000) and the display number. The client attaches to xscope
by changing its display number by the port offset.
EXAMPLES
xscope -hbagel -i0
The X server would run on "bagel", display 0 (the default). xscope and
the client would both be on "cleo". The client program would connect to
"X" on "cleo:0", and would be attached to xscope, which would then attach
to the server on "bagel:0".
server (bagel:0) <-----> xscope -hbagel -i0 <-----> client -d
cleo:0
xscope -i1
Here is a case where all three processes would run on "cleo". xscope
would listen on port 6001 (which is display 1 for X11). The client would
attach to the server on "cleo:1", and xscope would connect through to the
server on "cleo:0".
Page 2 10/89
XSCOPE(1) X Version 11(8 Aug 1991) XSCOPE(1)
server (cleo:0) <-----> xscope -i1 <-----> client -d cleo:1
xscope -hcleo -d0 -o0 -i1 -v4
This example is similar to the previous one, and would have xscope
communicate with an X server on host ``cleo'', display 0. xscope itself
would be available on the current host as display 1 (display of 0 plus
the 1 of -i1). Verbose level 4.
server (cleo:0) <-----> xscope -hcleo -d0 -o0 -i1 -v4 <----->
client -d cleo:1
xscope -d1 -o1 -i3 -q
The X server for the current host, display 2 (1 for -d1 plus 1 for -o1)
would be used by xscope, which would run as display 4 (1 for -d1 plus 3
for -i3). Quiet mode (verbose level 0).
server (unix:1) <-----> xscope -d1 -o1 -i3 -q <-----> client -d
unix:4
LIMITATIONS
The X Version 11 and PEX Version 5 Protocols are the only protocols
recognized.
The command line arguments for specifying the real X server should be
changed to be more consistent with the style since X11R3.
The Imakefile may be incorrect.
The builtin atoms have been wired in directly. A better solution is to
pick them up from a header file.
There is no code yet to interpret typed commands from the keyboard. It
would be possible for a command language at the keyboard to create
artificial characters to be sent to the server or the client as if they
were generated by the opposite side, or to dynamically alter requests or
replies.
SEE ALSO
X(1), X11 and PEX Protocol documents
AUTHOR
James L. Peterson (MCC)
Copyright 1988, MCC
10/89 Page 3