X11 Error Handling API

Data Structures
struct	s_WB_ERROR_INFO
	Structure definition for X11 error information. More...

Typedefs
typedef struct s_WB_ERROR_INFO	WB_ERROR_INFO
	Structure definition for X11 error information. More...

Functions
static __inline__ void	WBSupressErrorOutput (void)
	Supress X11 XErrorEvent output to stderr. More...
static __inline__ void	WBAllowErrorOutput (void)
	Restore X11 XErrorEvent output to stderr. More...
void	WBErrorClear (void)
	Clear the 'last error' information obtained via WBGetLastError() More...
int	WBErrorCheck (void)
	Check to see whether or not an X11 error was detected. More...
int	WBErrorCheckRetry (void)
	Check to see whether or not an X11 error was detected AND can be re-tried. More...
const WB_ERROR_INFO *	WBGetLastError (void)
	Obtain a const pointer to the internal WB_ERROR_INFO structure. More...

Detailed Description

X11 has its own error notification mechanism that normally terminates the application. Since many errors are actually 'expected' (particularly with respect to using the clipboard) it is necessary to process these without program interruption. Normal error handling consists of a notification message sent to stderr, and error information being stored in a set of global variables. Prior to using this information, it is FIRST necessary to clear the error state, and then check for an error after the operation has completed.

WBSupressErrorOutput(); // expect errors, no need for diagnostics
WBErrorClear();

while(1)
{
  // perform some operation that does not
  // normally indicate if an error took place
  // or needs to be checked for retry

  if(!WBErrorCheck())
  {
    break;
  }
  else
  {
    WB_ERROR_INFO *pErr = WBGetLastError();

    // report error, limit number of retries, etc.

    if(!WBErrorCheckRetry())
    {
      // do some kind of cleanup since I failed
      // and could not retry the operation

      break;
    }
  }
}

WBRestoreErrorOutput(); // restore error message output

Typedef Documentation

WB_ERROR_INFO

WB_ERROR_INFO

Structure definition for X11 error information.

typedef struct s_WB_ERROR_INFO
{
  Display *pDisplay;     // Display pointer passed into error handler function (NULL if no error)
  const char *pFunc;     // Name of the function as assigned by BEGIN_XCALL_DEBUG_WRAPPER
  int iLine;             // Line number of the function as assigned by BEGIN_XCALL_DEBUG_WRAPPER
  unsigned long serial;  // serial number from XErrorEvent
  int error_code;        // error code from XErrorEvent
  int request_code;      // request code from XErrorEvent
  int minor_code;        // minor code from XErrorEvent
  XID resourceid;        // resource ID (usually a Window) from XErrorEvent
} WB_ERROR_INFO;

Function Documentation

WBAllowErrorOutput()

static __inline__ void WBAllowErrorOutput ( void  )

static

Restore X11 XErrorEvent output to stderr.

Call this function to decrement the error output supression counter. Error output will be restored whenever the supression counter returns to zero. Each call to the WBSupressErrorOutput() function should be balanced with a call to this function.

Header File: window_helper.h

Definition at line 3703 of file window_helper.h.

WBErrorCheck()

int WBErrorCheck

(

void

)

Check to see whether or not an X11 error was detected.

Returns

A non-zero value if an error was stored in the internal WB_ERROR_INFO structure, else zero

Call this function to check to see if an XErrorEvent has been processed and stored in the internal WB_ERROR_INFO structure. It is necessary to FIRST call WBErrorClear() before any operation that might result in an error that can THEN be checked for using this function.

Header File: window_helper.h

Definition at line 9594 of file window_helper.c.

WBErrorCheckRetry()

int WBErrorCheckRetry

(

void

)

Check to see whether or not an X11 error was detected AND can be re-tried.

Returns

A non-zero value if a retryable error was stored in the internal WB_ERROR_INFO structure, else zero

Call this function to check to see if an XErrorEvent has been processed and stored in the internal WB_ERROR_INFO structure, and if a retry is possible based on the type and condition of the error. It is necessary to FIRST call WBErrorClear() before any operation that might result in an error that can THEN be checked for retryability using this function.

Header File: window_helper.h

Definition at line 9599 of file window_helper.c.

WBErrorClear()

void WBErrorClear

(

void

)

Clear the 'last error' information obtained via WBGetLastError()

Header File: window_helper.h

Definition at line 9589 of file window_helper.c.

WBGetLastError()

const WB_ERROR_INFO* WBGetLastError

(

void

)

Obtain a const pointer to the internal WB_ERROR_INFO structure.

Returns

A const pointer to the internal WB_ERROR_INFO structure

Call this function to obtain details about the last error from the XErrorEvent passed to the error handler. If there has been no error event, the 'pDisplay' member will always be NULL. You should always call WBErrorClear() to clear out this structure before performing an operation that might result in an XErrorEvent.

Header File: window_helper.h

Definition at line 9611 of file window_helper.c.

WBSupressErrorOutput()

static __inline__ void WBSupressErrorOutput ( void  )

static

Supress X11 XErrorEvent output to stderr.

Call this function to increment the error output supression counter. Error output will be restored whenever the supression counter returns to zero. Each call to this function should be balanced with a call to WBAllowErrorOutput().

Header File: window_helper.h

Definition at line 3682 of file window_helper.h.