VIPER REFERENCE MANUAL


NAME
iflError, iflErrorV, iflGetErrorHandler, iflSetErrorHandler, iflStatusEncode, iflStatusToString, iflMainStatusToString - error handling

HEADER FILE
#include <ifl/iflError.h>

SYNOPSIS

   Error Reporting
void iflError ( int flags, const char* msg, ...);
void iflErrorV ( int flags, const char* msg, va_list);

   Handling Errors
extern "C" void iflGetErrorHandler ( iflErrorHandlerType* handler, void** arg);
extern "C" void iflSetErrorHandler ( iflErrorHandlerType newhandler, void* newarg);

   Translating Error Status Codes
inline iflStatus iflStatusEncode ( unsigned int mainstatus, unsigned int subDomain=iflSubDomainNONE, unsigned int subStatus=0);
extern "C" char* iflStatusToString ( iflStatus status, char buf[], int bufsize);
extern "C" const char* iflMainStatusToString ( iflMainStatus status);

VARIABLE SYNOPSIS

   Standard Error Handlers
extern iflErrorHandlerFunc iflNaiveErrorHandler;
extern iflErrorHandlerFunc iflRobustErrorHandler;
extern iflErrorHandlerFunc iflSilentErrorHandler;

DESCRIPTION
These functions are used to report errors and control how those errors are handled in the IFL environment. These facilities can also be used to generate debugging messages. The routines are grouped into three functional areas: error reporting, error handling, and status code translation.

   Error Reporting
Error messages can be generated with the iflError() routine.

The iflErrorV() routine is provided for situations where the variable arguments have already already been packaged.

   Handling Errors
The handling of errors generated by iflError() is controlled by iflSetErrorHandler().

   Translating Error Status Codes
Errors are encoded via the iflStatus type. There are three components of an iflStatus code:

Component Interpretation
unsigned int mainstatus:12 IFL status code
unsigned int subDomain:4 domain of subStatus
unsigned int subStatus:16 subdomain status code

mainstatus encodes a main status code; subStatus encodes an elaboration of the main status code from another domain. For example: mainstatus might be iflOPENFAILED and subStatus might be ENOFILE to indicate why IFL returned iflOPENFAILED. In order to determine what subStatus means one must examine subdomain to see whether subStatus contains UNIX errno's, etc.

The completely 0 status code, iflOKAY, is reserved. This makes it easier for most cases in which the caller does not care about the specific value, but only wants to compare with iflOKAY.

These fields of the iflStatus type can be picked apart with the iflGetMainStatus(), iflGetSubDomain() and iflGetSubStatus() macros defined in <ifl/iflError.h>.

The iflMainStatus enumerated type used for IFL generated errors can be translated to a string using the iflMainStatusToString() routine.

An encoded iflStatus value can be converted to a string using iflStatusToString().

An iflMainStatus with optional sub-domain and sub-status is encoded into an iflStatus value by using the iflStatusEncode() function.

FUNCTION DESCRIPTIONS

   iflError()
void iflError ( int flags, const char* msg, ...);

This routine is used to generate error messages. The flags parameter can have one of the following values:

MM_INFO
informational message, many error handlers will just ignore the message; this is primarily intended for debugging messages

MM_WARNING
warning, most error handlers will return and allow the program to continue executing

MM_ERROR
error, some error handlers will abort (the default error handler will)

MM_HALT
fatal error, most error handlers will abort the program

The fmt parameter is treated as a printf() format string. The remaining parameters (if any) are used in the formatting process as dictated by the format string.

   iflErrorV()
void iflErrorV ( int flags, const char* msg, va_list);

This routine is provided for situations where the variable arguments have already been packaged in the "va_list" argument, ap. See the stdarg(5) man page for more details on this mechanism

   iflGetErrorHandler()
extern "C" void iflGetErrorHandler ( iflErrorHandlerType* handler, void** arg);

The routine returns the error handler currently in effect in handler and the current closuer argument in arg.

   iflMainStatusToString()
extern "C" const char* iflMainStatusToString ( iflMainStatus status);

This routine returns a static message string for the main status value, status.

   iflSetErrorHandler()
extern "C" void iflSetErrorHandler ( iflErrorHandlerType newhandler, void* newarg);

The routine is used to control the handing of errors reported with iflError(). The error handler is specified by the newhandler parameter and will be passed the newarg parameter as a user closure. The prototype for an error handling routine that could be passed as newhandler is:
    handler(void* closureArg, int flags, const char* fmt, va_list ap)
where the closureArg corresponds to the newarg parameter of iflSetErrorHandler() and the flags, fmt and ap parameters are as described for iflErrorV().

It is up to the error handler to decide whether or not to output a message and whether or not to abort based on the value of flags.

The user may choose to supply their own error handler or use one of three built-in error handlers supplied with IL: iflNaiveErrorHandler, iflRobustErrorHandler or iflSilentErrorHandler

   iflStatusEncode()
inline iflStatus iflStatusEncode ( unsigned int mainstatus, unsigned int subDomain=iflSubDomainNONE, unsigned int subStatus=0);

The routine encodes an iflMainStatus, mainstatus, with optional sub-domain, subDomain, and sub-status, subStatus into an iflStatus value.

   iflStatusToString()
extern "C" char* iflStatusToString ( iflStatus status, char buf[], int bufsize);

This routine convertes an encoded iflStatus value, status to a string. The message will be converted into the user's buffer, buf, and truncated to bufsize characters in length if necessary.

VARIABLE DESCRIPTIONS

   iflNaiveErrorHandler
extern iflErrorHandlerFunc iflNaiveErrorHandler;

This handler will abort on errors or fatal errors, it ignores informational messages; this is the default handler.

   
iflRobustErrorHandler
extern iflErrorHandlerFunc iflRobustErrorHandler;

This handler will only abort on fatal errors, it ignores informational messages.

   
iflSilentErrorHandler
extern iflErrorHandlerFunc iflSilentErrorHandler;

This handler will ignore all but fatal errors, which will be printed and cause the program to exit.

SEE ALSO
printf, stdarg(5)