1
2	XSCOPE -- a program to monitor X11/Client conversations
3
4XSCOPE is a program to monitor the connections between the X11 window
5server and a client program.  xscope runs as a separate process.  By
6adjusting the host and/or display number that a X11 client attaches
7to, the client is attached to xscope instead of X11.  xscope attaches
8to X11 as if it were the client.  All bytes from the client are sent
9to xscope which passes them on to X11; All bytes from X11 are sent to
10xscope which sends them on to the client.  xscope is transparent to
11the client and X11.
12
13In addition to passing characters back and forth, xscope will print
14information about this traffic on stdout, giving performance and
15debugging information for an X11 client and server.
16
17
18  --------------               --------------             --------------
19  |            |               |            |             |            |
20  |            | ------------> |            | ----------> |            |
21  |   client   |               |  xscope    |             |   server   |
22  |            |               |            |             |            |
23  |            | <-----------  |            | <---------- |            |
24  |            |               |            |             |            |
25  --------------               --------------             --------------
26                                     |
27				     |
28				     v
29			    trace output to stdout
30
31
32When running with xscope, three processes are involved, potentially all
33on different machines:
34
35X11 -- the X11 window server will be running on machine "A" for Display "B".
36	("A" is a machine name; "B" is a display number).
37
38xscope -- xscope must be told where the X11 window server is
39	(what machine and what display).  The options for xscope are
40	-h<X11-host> and -d<display-number>.  In our example, -hA and -dB.
41	Typically the display-number is not given. xscope will not try to
42	connect to X11 until the client connects to xscope.
43
44client -- the client should connect to xscope rather than X11.  To avoid
45	changing the code for the client, xscope listens on the same port
46	as X11. If X11 and xscope are on different machines, this works
47	well.  However, if X11 and xscope are on the same machine, this
48	creates a port conflict.  To resolve this conflict, xscope can
49	be given a different input or output port number, as necessary
50	to avoid the port that X11 is listening to.  The client must connect
51	to this offset port number.  The input port for xscope is set by
52	-i<port-number>; the output port is set by -o<port-number>. The
53	default input port is 1; the default output port is 0. These ports
54	are offset by the X11 base (6000) and the display number. The client
55	attaches to xscope by changing its display number by the port offset.
56
57For example, with X11 running on "bagel", display 0 (the default), and
58xscope and the client running on "cleo", we would start xscope as
59"xscope -hbagel -i0".  The client program could then connect to "X11" on
60"cleo:0", and would be attached to xscope, which would then attach to
61X11 on "bagel:0".
62
63If, however, all three processes were running on "cleo", we would
64start xscope by "xscope -i1".  This would cause it to listen on
65port 6001 (which is display 1 for X11).  The client would attach to
66X11 on "cleo:1", and xscope would connect through to X11 on "cleo:0".
67
68
69LIMITATIONS:
70
71xscope was originally written & used on a Sun3. Additional code may be needed
72for byteswapping on different architectures.
73
74The command line arguments for specifying the real X server should probably
75	be changed to be more consistent with X11R3 applications.
76
77The builtin atoms have been wired in directly; they should probably be
78picked up from a header file.
79
80Each extension needs to have decoding routines manually written; they
81should probably be generated from the XCB xml protocol descriptions.
82
83There is some code to interpret typed commands from the keyboard.
84   It would be possible to extend the a command language to create
85   artificial characters to be sent to X11 or the client as if they were
86   generated  by the other, or to dynamically alter requests or replies.
87
88    ------------------------------------------------------------
89
90The original paper introducing xscope can be read at:
91
92	http://jklp.org/public/profession/papers/xscope/paper.htm
93
94All questions regarding this software should be directed at the
95Xorg mailing list:
96
97        http://lists.freedesktop.org/mailman/listinfo/xorg
98
99Please submit bug reports to the Xorg bugzilla:
100
101        https://bugs.freedesktop.org/enter_bug.cgi?product=xorg
102
103The master development code repository can be found at:
104
105        git://anongit.freedesktop.org/git/xorg/app/xscope
106
107        http://cgit.freedesktop.org/xorg/app/xscope
108
109For patch submission instructions, see:
110
111	http://www.x.org/wiki/Development/Documentation/SubmittingPatches
112
113For more information on the git code manager, see:
114
115        http://wiki.x.org/wiki/GitPage
116
117