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.
-S<zero-or-one>
Run with SIGUSR1 triggered tracing. Following the
option with a zero begins xscope not tracing;
following the option with a one begins xscope
Page 1 (printed 7/20/06)
XSCOPE(1) X Version 11 (8 Aug 1991) XSCOPE(1)
tracing. Send a SIGUSR1 signal to the xscope
process to toggle tracing.
-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 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
Page 2 (printed 7/20/06)
XSCOPE(1) X Version 11 (8 Aug 1991) XSCOPE(1)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".
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.
Page 3 (printed 7/20/06)
XSCOPE(1) X Version 11 (8 Aug 1991) XSCOPE(1)
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
Page 4 (printed 7/20/06)
