NAME
-
vsErrorSetLog, vsErrorSetTag, vsErrorLog, vsErrorLogV, vsErrorString, vsPushErrorHandler, vsPopErrorHandler, vsGetErrorHandler, vsGetErrorHandlerStackDepth, vsGetErrorHandlerMaxStackDepth - Error handling
HEADER FILE
-
#include <vizserver/vs.h>
SYNOPSIS
extern "C" void vsErrorLog ( |
vsLogPri pri, const char* msg, ...); |
extern "C" void vsErrorLogV ( |
vsLogPri pri, const char* msg, va_list args); |
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.