iflError(3)

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

SYNOPSIS
     #include <ifl/iflCdefs.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)


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.

   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.

     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.