Return to ch13a.t CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / new / X / doc / Xlib

Annotation of 43BSDTahoe/new/X/doc/Xlib/ch13a.t, revision 1.1.1.1

1.1       root        1: .NH
                      2: Error Handling
                      3: .XS
                      4: Error Handling
                      5: .XE
                      6: .PP
                      7: .IN "Error Handlers"
                      8: There are two default error handlers in the library, one to handle
                      9: typically fatal conditions (for example, the connection to a display
                     10: server
                     11: dying due to machine crash), and one to handle error events from X.
                     12: These error handlers can be changed to user supplied routines if you
                     13: prefer your own error handling, and can be changed as often as you like.
                     14: If either of these routines are passed a NULL pointer, it will
                     15: reinvoke the default handler.
                     16: The default action of the  supplied routine is to exit.
                     17: .PP
                     18: .FD
                     19: .IN "Definitions" "XIOErrorHandler"
                     20: .IN "XIOErrorHandler"
                     21: XIOErrorHandler( handler )
                     22:        int handler(Display *);
                     23: .FN
                     24: .PP
                     25: The program's
                     26: supplied error handler will be called by Xlib if any sort of system call error
                     27: occurs, e.g. the connection to the server was lost.
                     28: This is assumed to
                     29: be a fatal condition, i.e., the called routine should not return.
                     30: If the IO error handler
                     31: does return, the client process will exit.
                     32: .PP
                     33: .FD
                     34: .IN "Definitions" "XErrorHandler"
                     35: .IN "XErrorHandler"
                     36: XErrorHandler( handler )
                     37:        int handler(Display *, XErrorEvent *)
                     38: .FN
                     39: The program's
                     40: supplied error hander will be called by Xlib whenever an \fIXError\fP event is
                     41: received.
                     42: This is not assumed to be a fatal condition, i.e., it is
                     43: acceptable for this procedure to return.
                     44: However, the error handler should NOT
                     45: perform any operations (directly or indirectly) on the Display.
                     46: The
                     47: fields of the \fIXErrorEvent\fP passed to \fIXError\fP should be interpreted as follows:
                     48: .sp
                     49: .DS
                     50: .TA .5i 2.5i
                     51: .ta .5i 2.5i
                     52: typedef struct _XErrorEvent {
                     53:        long pad;
                     54:        long serial;    /* serial number of failed request */
                     55:        char error_code;        /* error code of failed request */
                     56:        char request_code;      /* request code of failed request */
                     57:        char func;      /* function field of failed request */
                     58:        char pad_b7;
                     59:        Window window;  /* Window of failed request */
                     60:        long pad_l3;
                     61:        long pad_l4;
                     62: } XErrorEvent;
                     63: .DE
                     64: .IN "Data Structures" "XErrorEvent"
                     65: .IN "Serial Number"
                     66: .sp
                     67: The serial number is the number of requests sent over the network connection
                     68: since it was opened, starting from one; it is the number that was the
                     69: value of \fIdpy->request\fP immediately after the failing call was made.  The
                     70: request code is a protocol representation of the name of the procedure
                     71: .IN "File" "<X/X.h>"
                     72: that failed; these are defined in \fI<X/X.h>\fP.  The error code is one of
                     73: the following, also defined in \fI<X/X.h>\fP:
                     74: .IN "Error Numbers"
                     75: .LP
                     76: .TS
                     77: center,box;
                     78: lcl.
                     79: BadRequest     1       bad request code
                     80: BadValue       2       int parameter out of range
                     81: BadWindow      3       parameter not a Window
                     82: BadPixmap      4       parameter not a Pixmap
                     83: BadBitmap      5       parameter not a Bitmap
                     84: BadCursor      6       parameter not a Cursor
                     85: BadFont        7       parameter not a Font
                     86: BadMatch       8       parameter mismatch
                     87: BadTile        9       Pixmap shape invalid for tiling
                     88: BadGrab        10      mouse/button already grabbed
                     89: BadAccess      11      access control violation
                     90: BadAlloc       12      insufficient resources
                     91: BadColor       13      no such color
                     92: .TE
                     93: It is recommended that \fIXError\fP use the following procedure for obtaining
                     94: textual descriptions of errors:
                     95: .FD
                     96: .IN "Definitions" "XErrDescrip"
                     97: .IN "XErrDescrip"
                     98: char *XErrDescrip (code)
                     99:        int code;
                    100: .FN
                    101: Returns a null-terminated string describing the specified error code.
                    102: The string is static in Xlib and should not be modified or freed.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.