iflError(3) Image Format Library C++ Reference Manual iflError(3)
NAME
iflError, iflErrorV, iflGetErrorHandler, iflSetErrorHandler,
iflStatusToString, iflMainStatusToString, iflStatusEncode - error
handling
SYNOPSIS
#include <ifl/iflError.h>
void iflError(int flags, const char* fmt, ...)
void iflErrorV(int flags, const char* fmt, va_list ap)
void iflGetErrorHandler(iflErrorHandlerType* handler, void** arg)
void iflSetErrorHandler(iflErrorHandlerType newhandler, void* newarg)
char* iflStatusToString(iflStatus status, char buf[], int bufsize)
const char* iflMainStatusToString(iflMainStatus status)
iflStatusEncode(unsigned int mainstatus,
unsigned int subDomain = iflSubDomainNONE,
unsigned int subStatus = 0)
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 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.
The iflErrorV() 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.
Page 1
iflError(3) Image Format Library C++ Reference Manual iflError(3)
Handling Errors
The handling of errors is controlled by iflSetErrorHandler(). 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 this handler will abort on errors or fatal
errors, it ignores informational messages; this
is the default handler
iflRobustErrorHandler this handler will only abort on fatal errors, it
ignores informational messages
iflSilentErrorHandler this handler will ignore all but fatal errors,
which will be printed and cause the program to
exit.
Translating Error Status Codes
Errors are encoded via the iflStatus type. There are three components of
an iflStatus code:
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 IL
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.
Page 2
iflError(3) Image Format Library C++ Reference Manual iflError(3)
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 IL generated errors can be
translated to a string using the iflMainStatusToString() routine.
An encoded iflStatus value can be converted to a string using
iflStatusToString(). The message will be converted into the user's
buffer, buf, and truncated to bufsize characters in length if necessary.
An iflMainStatus with optional sub-domain and sub-status is encoded into
an iflStatus value by using the iflStatusEncode() function.
Page 3