Xlib tutorial part 13 -- XScope

by Alan at Mon 11th May 2009 1:00AM EST

Hello, and welcome to part 13 of this Xlib tutorial.

After a nice month long hiatus, we're back.

This week, I want to start talking about debugging tools. First off get a copy of xscope.

You'll have to compile it if you get it from there. For some reason my debian system did not have it installed by default and I could not find it in any of the Debian packages, you may have better luck with your system.

Sometimes when working on a display program, we end up wondering what exactly our program is telling the display server. X, because it is a network protocol, makes it easy to listen in on what is being sent across the wire.

xscope is a program for doing just that. To use it, you set it up as though it's a server and when a client connects to it, it connects to the actual server. It then dumps anything that the client and actual server say to each other onto its standard output.

Each request that the client sends, and each event that the server sends are printed in a (not particularily) easy to read format.

First let's make sure it's all set up. To compile the version I gave a link to, I had to edit the file scope.c and add a line near the beginning #include <sys/param.h>. For whatever reason, MAXHOSTNAMELEN was used, but not defined in scope.c.

I also had to ./configure to create the Makefile, then run make.

Once I had the executable, I discovered that my X server by default hasn't been listening to port 6000. (The normal port for X). I found that quite odd, so I had to restart the server. Then I had to run xhost + so that any client can access the server. (Note, if you're on the internet, this is likely a bad idea. Running xhost + turns off the X security system. Or at least one of them.

I could now start xscope.

Finally, I had to set the DISPLAY environment variable to :1.0 instead of the standard :0.0 in the terminal I want things to run through xscope.

Hopefully, you won't have quite so many problems setting up xscope for your system. But my description of what I did should help you along if you do have problems.

Okay, that's out of the way. Let's take a look at some sample output of xscope. I'm running xtut12 from the last lesson.

 0.00: Client -->   12 bytes
              byte-order: LSB first
           major-version: 000b
           minor-version: 0000
 0.00:                   308 bytes <-- X11 Server
                    protocol-major-version: 000b
                    protocol-minor-version: 0000
                          release-number: 042da808
                        resource-id-base: 01c00000
                        resource-id-mask: 001fffff
                      motion-buffer-size: 00000100
                        image-byte-order: LSB first
                    bitmap-format-bit-order: LSB first
                    bitmap-format-scanline-unit: 20
                    bitmap-format-scanline-pad: 20
                             min-keycode: 8 (^H)
                             max-keycode: 255 (377)
                                  vendor: "The X.Org Foundation"
                          pixmap-formats: (7)
                                   roots: (1)

This is standard start of protocol stuff. The client (xtut12) is announcing itself and the server is describing what's available

When you're reading through a xscope dump, it really helps to remember the the client is the process that's asking for windows to be drawn, and the server is the machine with the monitor, mouse and keyboard. If you get it backwards you can end up quite confused.

Looking further, you can see things like this:

 0.01: Client -->  224 bytes
     ............REQUEST: CreateWindow
                   depth: 00
                     wid: WIN 01c00001
                  parent: WIN 0000003e
                       x: 0
                       y: 0
                   width: 0190
                  height: 0190
            border-width: 0000
                   class: CopyFromParent
                  visual: CopyFromParent
              value-mask: background-pixel | border-pixel
            background-pixel: 0000aedc
                border-pixel: 00006ad9


                     ..............EVENT: MapNotify
                                   event: WIN 01c00001
                                  window: WIN 01c00001
                       override-redirect: False

In this case, we're seeing xtut12 ask for a window to be created, and we can see an event occurring, (much later) when the window is mapped (shown on the screen, assuming all parents are mapped, and it's not obscured).

One unfortunate part of xscope, is that it doesn't know about X extensions, and won't translate them for you.

I think that's all I'm going to do this week. If you can't get xscope running on your system, you can download a sample output to look through

On the other hand if you can get it working, try playing around with it, see if you can figure out how to fix any of the bugs that are in xtut12.

Comments are closed.