11.8.2 Using the Default Error Handlers

There are two default error handlers in Xlib: one to handle typically fatal conditions (for example, the connection to a display server dying because a machine crashed) and one to handle protocol errors from the X server. These error handlers can be changed to user-supplied routines if you prefer your own error handling and can be changed as often as you like. If either function is passed a NULL pointer, it will reinvoke the default handler. The action of the default handlers is to print an explanatory message and exit.

To set the error handler, use XSetErrorHandler().

The XErrorEvent structure contains:

typedef struct {
	int type;
	Display *display;		/* Display the event was read from */
	unsigned long serial;		/* serial number of failed request */
	unsigned char error_code;	/* error code of failed request */
	unsigned char request_code;	/* Major op-code of failed request */
	unsigned char minor_code;	/* Minor op-code of failed request */
	XID resourceid;			/* resource id */
} XErrorEvent;

The serial member is the number of requests, starting from one, sent over the network connection since it was opened. It is the number that was the value of NextRequest() immediately before the failing call was made. The request_code member is a protocol request of the procedure that failed, as defined in X11/Xproto.h . The following error codes can be returned by the functions described in this chapter:

Error Code Description

BadAccess A client attempts to grab a key/button combination already grabbed by another client.

A client attempts to free a colormap entry that it had not already allocated or to free an entry in a colormap that was created with all entries writable.

A client attempts to store into a read-only or unallocated colormap entry.

A client attempts to modify the access control list from other than the local (or otherwise authorized) host.

A client attempts to select an event type that another client has already selected.

BadAlloc The server fails to allocate the requested resource. Note that the explicit listing of BadAlloc errors in requests only covers allocation errors at a very coarse level and is not intended to (nor can it in practice hope to) cover all cases of a server running out of allocation space in the middle of service. The semantics when a server runs out of allocation space are left unspecified, but a server may generate a BadAlloc error on any request for this reason, and clients should be prepared to receive such errors and handle or discard them.
BadAtom A value for an atom argument does not name a defined atom.
BadColor A value for a colormap argument does not name a defined colormap.
BadCursor A value for a cursor argument does not name a defined cursor.
BadDrawable A value for a drawable argument does not name a defined window or pixmap.
BadFont A value for a font argument does not name a defined font (or, in some cases, GContext).
BadGC A value for a GContext argument does not name a defined GContext .
BadIDChoice The value chosen for a resource identifier either is not included in the range assigned to the client or is already in use. Under normal circumstances, this cannot occur and should be considered a server or Xlib error.
BadImplementation The server does not implement some aspect of the request. A server that generates this error for a core request is deficient. As such, this error is not listed for any of the requests, but clients should be prepared to receive such errors and handle or discard them.
BadLength The length of a request is shorter or longer than that required to contain the arguments. This is an internal Xlib or server error.

The length of a request exceeds the maximum length accepted by the server.

BadMatch In a graphics request, the root and depth of the graphics context does not match that of the drawable.

An InputOnly window is used as a drawable.

Some argument or pair of arguments has the correct type and range, but it fails to match in some other way required by the request.

An InputOnly window lacks this attribute.

BadName A font or color of the specified name does not exist.
BadPixmap A value for a pixmap argument does not name a defined pixmap.
BadRequest The major or minor opcode does not specify a valid request. This usually is an Xlib or server error.
BadValue Some numeric value falls outside of the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives typically can generate this error (due to the encoding).
BadWindow A value for a window argument does not name a defined window.


The BadAtom, BadColor, BadCursor, BadDrawable, BadFont, BadGC, BadPixmap, and BadWindow errors are also used when the argument type is extended by a set of fixed alternatives.

To obtain textual descriptions of the specified error code, use XGetErrorText().

To obtain error messages from the error database, use XGetErrorDatabaseText().

To report an error to the user when the requested display does not exist, use XDisplayName().

To handle fatal I/O errors, use XSetIOErrorHandler().

Next Chapter: Input Device Functions

Christophe Tronche, ch@tronche.com