XSetErrorHandler(3X)                         XSetErrorHandler(3X)



NAME
     XSetErrorHandler, XGetErrorText, XDisplayName,
     XSetIOErrorHandler,  XGetErrorDatabaseText - perform default
     error handling

SYNOPSIS
     int (*XSetErrorHandler (handler))()
     int (*handler) (display*,  XErrorEvent*)

     XGetErrorText (display, code, buffer-return, length)
     Display *display;
     int code;
     char *buffer-return;
     int length;

     char *XDisplayName (string)
     char *string;

     int (*XSetIOErrorHandler (handler))()
     int (*handler) (display*)

     XGetErrorDatabaseText (display, name, message,
     default-string, buffer-return, length)
     Display display;
     char *name,*message;
     char *default-string;
     char *buffer-return;
     int length;

DESCRIPTION
     The XSetErrorHandler function sets the program's supplied
     error handler.  Xlib generally calls the program's error
     handler whenever an error is received.  The error handler is
     not called on BadName errors from OpenFont, LookupColor, or
     AllocNamedColor protocol requests or on BadFont errors from
     a QueryFont protocol request.  These errors generally are
     reflected back to the program through the procedural inter-
     face.  Because the error condition is not assumed to be fa-
     tal, it is acceptable for your error handler to return.
     However, the error handler should not call any functions
     (directly or indirectly) on the display that generate proto-
     col requests or that look for input events.  XSetEr-
     rorHandler returns the previous error handler.

     The XGetErrorText function copies a null-terminated string
     describing the specified error code into the specified
     buffer.  It is recommended that you use this function to ob-
     tain an error description because extensions to Xlib may de-
     fine their own error codes and error strings.

     The XDisplayName function returns the name of the display
     that XOpenDisplay would attempt to use.  If a NULL string is



November, 1990                                                  1

XSetErrorHandler(3X)                         XSetErrorHandler(3X)



     specified, XDisplayName looks in the environment for the
     display and returns the display name that XOpenDisplay would
     attempt to use.  This makes it easier to report to the user
     precisely which display the program attempted to open when
     the initial connection attempt failed.

     The XSetIOErrorHandler sets the fatal I/O error handler.
     Xlib calls the program's supplied error handler if any sort
     of system call error occurs (for example, the connection to
     the server was lost).  This is assumed to be a fatal condi-
     tion, and the called routine should not return.  If the I/O
     error handler does return, the client process exits.  Note
     that XSetIOErrorHandler returns the previous error handler.

     The XGetErrorDatabaseText function returns a message (or the
     default message) from the error message database.  Xlib uses
     this function internally to look up its error messages.  On
           r
     a UNIX -based system, the error message database is
     /usr/lib/X11/XErrorDB.

     The name argument should generally be the name of your ap-
     plication.  The message argument should indicate which type
     of error message you want.  Xlib uses three predefined mes-
     sage types to report errors (case is significant):

     XProtoError
             The protocol error number is used as a string for
             the message argument.

     XlibMessage
             These are the message strings that are used inter-
             nally by the library.

     XRequest
             For a core protocol request, the major request pro-
             tocol number is used for the message argument.  For
             an extension request, the extension name (as given
             by
             InitExtension) followed by a period (.) and the
             minor request protocol number is used for the mes-
             sage argument.  If no string is found in the error
             database, the default string is returned in the
             buffer-return argument.

   Arguments
     These functions accept the following arguments:

     buffer-return
             Specifies the buffer in which the error message is
             to be stored.

     code    Specifies the error code for which a description is



2                                                  November, 1990

XSetErrorHandler(3X)                         XSetErrorHandler(3X)



             to be obtained.

     default-string
             Specifies the default error message if no error mes-
             sage is found in the database.

     display Specifies the connection to the X server.

     handler Specifies the program's supplied error handler.

     length  Specifies the size of the buffer.

     message Specifies the error message type.

     name    Specifies the name of the application.

     string  Specifies the character string.

SEE ALSO
     XOpenDisplay(3X), XSynchronize(3X)

     Xlib - C Language Interface


































November, 1990                                                  3