X11 Debugging Notes

I have been programming using Xlib off and on for for many years. I even wrote the Xlib implementation of a GIS graphics engine that was used in the back end of search and rescue planes (Aurora and associated programmes). The latest version will use a Modern OpenGL graphics engine that I had a big hand in implementing.

The one website I continually go back too when I need to debug X11 is:
In particular this page:
The main reason is for the detailed information on how to debug a problem when something goes wrong with your program.

While this site is pretty old the information is still current, at least for Xlib and Motif, not that many people are using these in anger directly very much now.

A couple of things have changed:
  • You should probably add the following to your application to cause Xlib protocol to be synchronous:
XSynchronize(display, True);
  • gdb is now used in preference to dbx (old Sun debugger, now Oracle debugger).
(gdb) break _XError
Function "_XError" not defined.
Make breakpoint pending on future shared library load? (y or [n]) y
Breakpoint 1 (_XError) pending.

If you find that your problem goes away when the protocol is synchronous then your problem is going to be a lot more difficult to fix.

In my case this is usually related to my programs being multi-threaded with multiple connections to the XServer (not all Xlib libraries are thread safe even if you follow the rules that are known about). This is partly why xcb was created.

Either way what you get will be a stack trace back to the problem:

(gdb) where
#0  0xf73106a0 in _XError () from /lib/libX11.so.6
#1  0xf730cff6 in handle_error () from /lib/libX11.so.6
#2  0xf730d0be in handle_response () from /lib/libX11.so.6
#3  0xf730e328 in _XReply () from /lib/libX11.so.6
#4  0xf7309677 in XSync () from /lib/libX11.so.6
#5  0xf7309713 in _XSyncFunction () from /lib/libX11.so.6
#6  0xf49aa46c in XRenderCreatePicture () from /lib/libXrender.so.1
The actual error reported is:
(gdb) c
X Error of failed request:  BadMatch (invalid parameter attributes)
  Major opcode of failed request:  138 (RENDER)
  Minor opcode of failed request:  4 (RenderCreatePicture)
  Serial number of failed request:  94
  Current serial number in output stream:  95

To be honest sometimes the errors make no sense and you have to search on the internet for answers. In this case the following is helpful:
The specification for Xrender is a bit lacking:
A subsequent post covers fixing the above issue with XRenderCreatePicture.

The additional complication in all this is that most modern Linux systems are now using an Xlib library implemented using xcb. This does not however sort out the threading mess that Xlib is known for.