OpenGL Vizserver Reference Page


NAME
vsErrorSetLog, vsErrorSetTag, vsErrorLog, vsErrorLogV, vsErrorString, vsPushErrorHandler, vsPopErrorHandler, vsGetErrorHandler, vsGetErrorHandlerStackDepth, vsGetErrorHandlerMaxStackDepth - Error handling

HEADER FILE
#include <vizserver/vs.h>

SYNOPSIS
extern "C" void vsErrorSetLog ( FILE* fp);
extern "C" void vsErrorSetTag ( const char* tag);
extern "C" void vsErrorLog ( vsLogPri pri, const char* msg, ...);
extern "C" void vsErrorLogV ( vsLogPri pri, const char* msg, va_list args);
extern "C" const char* vsErrorString ( vsStatus sts);
extern "C" vsBool vsPushErrorHandler ( vsErrorHandler handler);
extern "C" vsErrorHandler vsPopErrorHandler (  );
extern "C" vsErrorHandler vsGetErrorHandler (  );
extern "C" size_t vsGetErrorHandlerStackDepth (  );
extern "C" size_t vsGetErrorHandlerMaxStackDepth (  );

VARIABLE SYNOPSIS
extern const vsErrorHandler vsNaiveErrorHandler;
extern const vsErrorHandler vsRobustErrorHandler;
extern const vsErrorHandler vsSilentErrorHandler;

DESCRIPTION
The following functions are used to report errors and control how those errors are handled in the OpenGL Vizserver environment. The basic facility provides a mechanism to generate error messages to a log file.

   Error Reporting
Error messages can be generated with the vsErrorLog() and vsErrorLogV() routines.

   Error Handling
Errors identified by the vsErrorLog() and vsErrorLogV() routines are dispatched to an error handling function of type vsErrorHandler. The error handler has the form. void errorHandler(vsLogPri pri, const char* msg, va_list args) The parameters to the error handler consist of the priority of the message (pri), the printf style message (msg) and the arguments for that message (args). The message priority can be one of vsLogPriHalt, vsLogPriError, vsLogPriWarning, vsLogPriNotice, vsLogPriInfo, or vsLogPriDebug. These represent the severity of the error that occurred and defines, to some degree, what action the error handler should take.

In general, errors with the vsLogPriHalt priority should never return to the application (although application writers should not depend upon this behaviour). Errors with other less severe priorities can be caught and potentially handled by the invoked handler.

The error handling logic of OpenGL Vizserver defines three basic error handlers. These include the vsNaiveErrorHandler, vsRobustErrorHandler and vsSilentErrorHandler. All of these error handlers format and print the error message to current error log (see vsErrorSetLog()) and for messages with priority higher than or equal to vsLogPriInfo, to the system log (see syslog(3)). The vsSilentErrorHandler error handler only prints errors when the message priority is higher than vsLogPriError. Both the vsSilentErrorHandler and vsRobustErrorHandler exit the program when the message priority is less than vsLogPriError. The vsNaiveErrorHandler, which is the default error handler, exits the program for messages with priority higher than vsLogPriWarning.

It is possible to change the default error handler via the VSERROR environment variable. Values of robust or silent indicate a default of vsRobustErrorHandler or vsSilentErrorHandler respectively.


FUNCTION DESCRIPTIONS

   vsErrorLog()
extern "C" void vsErrorLog ( vsLogPri pri, const char* msg, ...);

The vsErrorLog function calls the current error handler passing its parameters as arguments to that handler (see vsPushErrorHandler()).

The pri argument defines the priority of the message to pass to the current error handler (see vsPushErrorHandler()). The msg and the optional arguments that follow describe a string that follows the printf() conventions.


   vsErrorLogV()
extern "C" void vsErrorLogV ( vsLogPri pri, const char* msg, va_list args);

The vsErrorLogV function calls the current error handler passing its parameters as arguments to that handler (see vsPushErrorHandler()).

The pri argument defines the priority of the message to pass to the current error handler (see vsPushErrorHandler()) The msg and the args arguments supply a printf() style formatting string and its arguments.


   vsErrorSetLog()
extern "C" void vsErrorSetLog ( FILE* fp);

The vsErrorSetLog function sets the file for logging error message to the value in fp. Messages produced via the vsErrorLog() and vsErrorLogV() functions are directed to this file in addition to the system log.

   vsErrorSetTag()
extern "C" void vsErrorSetTag ( const char* tag);

The vsErrorSetTag function sets the error log message tag (prefix) to the value in tag. Message produced via the vsErrorLog() and vsErrorLogV() functions will begin with the supplied tag. Passing NULL for tag will eliminate the tag portion of the output message.

   vsErrorString()
extern "C" const char* vsErrorString ( vsStatus sts);

The vsErrorString function returns the error string associated with the error status given by sts.

   vsGetErrorHandler()
extern "C" vsErrorHandler vsGetErrorHandler (  );

The vsGetErrorHandler function returns the current top level error handler that is invoked for error message logging.

   vsGetErrorHandlerMaxStackDepth()
extern "C" size_t vsGetErrorHandlerMaxStackDepth (  );

vsGetErrorHandlerMaxStackDepth returns the maximum error handler stack depth.

   vsGetErrorHandlerStackDepth()
extern "C" size_t vsGetErrorHandlerStackDepth (  );

vsGetErrorHandlerStackDepth returns the current error handler stack depth.

   vsPopErrorHandler()
extern "C" vsErrorHandler vsPopErrorHandler (  );

vsPopErrorHandler returns the top most error handler and pops it off the top of the error handler stack.

   vsPushErrorHandler()
extern "C" vsBool vsPushErrorHandler ( vsErrorHandler handler);

vsPushErrorHandler inserts the new error handler handler onto the top of the error handler stack. This new error handler will be invoked whenever error logging is requested and persists until it is popped off the stack via the vsPopErrorHandler() function. This function returns TRUE if the new handler was installed and FALSE if the error handler stack would overflow as a result of the push.

VARIABLE DESCRIPTIONS

   vsNaiveErrorHandler
extern const vsErrorHandler vsNaiveErrorHandler;

Simple error handler that simply prints the error message and exits the program if the log priority is higher (less than) vsLogPriWarning.

   
vsRobustErrorHandler
extern const vsErrorHandler vsRobustErrorHandler;

Simple error handler that simply prints the error message and exits the program if the log priority is higher (less than) vsLogPriError.

   
vsSilentErrorHandler
extern const vsErrorHandler vsSilentErrorHandler;

Simple error handler that prints the error message only if the log priority is higher than (less than) vsLogPriWarning and exits the program if the log priority is higher (less than) vsLogPriError.