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 that are used by xscope. 

−h<host>
Determines the host that xscope will use to find the server. 

−i<input-port>
Specifies the port that xscope will use to take requests from clients (default 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 (default 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 that xscope will provide.  The print-level can be 0 (same as quiet mode), 1, 2, 3, or 4.  The larger numbers give 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 to which the server is listening.  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."

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

September 02, 1992