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.
|
|
Note
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().
Christophe Tronche, [email protected]
