X11 Work Bench Toolkit  1.0
X11 Error Handling API

Data Structures

struct  __WB_ERROR_INFO__
 Structure definition for X11 error information. More...
 

Typedefs

typedef struct __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_INFOWBGetLastError (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
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
{
// report error, limit number of retries, etc.
{
// do some kind of cleanup since I failed
// and could not retry the operation
break;
}
}
}
WBRestoreErrorOutput(); // restore error message output

Typedef Documentation

Structure definition for X11 error information.

typedef struct __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

Function Documentation

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 3053 of file window_helper.h.

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 9399 of file window_helper.c.

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 9404 of file window_helper.c.

void WBErrorClear ( void  )

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

Header File: window_helper.h

Definition at line 9394 of file window_helper.c.

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 9416 of file window_helper.c.

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 3037 of file window_helper.h.