iflError(3)	  Image	Format Library C++ Reference Manual	   iflError(3)

NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

     #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    [Toc]    [Back]

     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    [Toc]    [Back]
     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    [Toc]    [Back]
     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    [Toc]    [Back]
     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.


									PPPPaaaaggggeeee 3333