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