XLALError.h File Reference

Author:

Creighton, J.This header covers routines to provide the XLAL interface error handling.

More...

#include <stddef.h>
#include <lal/LALAtomicDatatypes.h>

Include dependency graph for XLALError.h:

Go to the source code of this file.

Defines
#define	UNUSED
#define	XLAL_REAL4_FAIL_NAN_INT   0x7fc001a1
	Hexadecimal representation of REAL4 NaN failure bit pattern.
#define	XLAL_REAL8_FAIL_NAN_INT   LAL_INT8_C(0x7ff80000000001a1)
	Hexadecimal representation of REAL8 NaN failure bit pattern.
#define	XLAL_REAL4_FAIL_NAN   ( XLALREAL4FailNaN() )
	Floating-point value of the XLAL REAL4 failure NaN.
#define	XLAL_REAL8_FAIL_NAN   ( XLALREAL8FailNaN() )
	Floating-point value of the XLAL REAL8 failure NaN.
#define	XLAL_IS_REAL4_FAIL_NAN(val)   XLALIsREAL4FailNaN(val)
	Tests if val is a XLAL REAL4 failure NaN.
#define	XLAL_IS_REAL8_FAIL_NAN(val)   XLALIsREAL8FailNaN(val)
	Tests if val is a XLAL REAL8 failure NaN.
#define	XLAL_PERROR(func)   XLALPerror( func, __FILE__, __LINE__, xlalErrno )
	Prints an error message for the current value of xlalErrno.
#define	xlalErrno   ( * XLALGetErrnoPtr() )
	Modifiable lvalue containing the XLAL error number.
#define	XLALErrorHandler   ( * XLALGetErrorHandlerPtr() )
	Modifiable lvalue containing the XLAL error handler.
#define	XLAL_TRY(statement, errnum)
	A macro to (i) disable the XLAL error handling and preserve the current value of xlalErrno (ii) perform a statement that involves an XLAL function call and (iii) restore the XLAL error handler and value of xlalErrno while setting variable errnum to the xlalErrno set by the statement.
#define	XLAL_ERROR_VAL(func, errnum, val)
	Macro to invoke the XLALError() function and return with code val (it should not really be used itself, but forms the basis for other macros).
#define	XLAL_ERROR(func, errnum)   XLAL_ERROR_VAL( func, errnum, XLAL_FAILURE )
	Macro to invoke a failure from a XLAL routine returning an integer.
#define	XLAL_ERROR_NULL(func, errnum)   XLAL_ERROR_VAL( func, errnum, NULL )
	Macro to invoke a failure from a XLAL routine returning a pointer.
#define	XLAL_ERROR_VOID(func, errnum)   XLAL_ERROR_VAL( func, errnum, /* void */ )
	Macro to invoke a failure from a XLAL routine returning void.
#define	XLAL_ERROR_REAL4(func, errnum)   XLAL_ERROR_VAL( func, errnum, XLAL_REAL4_FAIL_NAN )
	Macro to invoke a failure from a XLAL routine returning a REAL4.
#define	XLAL_ERROR_REAL8(func, errnum)   XLAL_ERROR_VAL( func, errnum, XLAL_REAL8_FAIL_NAN )
	Macro to invoke a failure from a XLAL routine returning a REAL8.
Typedefs
typedef void	XLALErrorHandlerType (const char *func, const char *file, int line, int errnum)
	The XLAL error handler type.
Enumerations
enum	XLALErrorValue {   XLAL_SUCCESS = 0, XLAL_FAILURE = -1, XLAL_EIO = 5, XLAL_ENOMEM = 12,   XLAL_EFAULT = 14, XLAL_EINVAL = 22, XLAL_EDOM = 33, XLAL_ERANGE = 34,   XLAL_EFAILED = 128, XLAL_EBADLEN = 129, XLAL_ESIZE = 130, XLAL_EDIMS = 131,   XLAL_ETYPE = 132, XLAL_ETIME = 133, XLAL_EFREQ = 134, XLAL_EUNIT = 135,   XLAL_ENAME = 136, XLAL_EDATA = 137, XLAL_EUSR0 = 200, XLAL_EUSR1 = 201,   XLAL_EUSR2 = 202, XLAL_EUSR3 = 203, XLAL_EUSR4 = 204, XLAL_EUSR5 = 205,   XLAL_EUSR6 = 206, XLAL_EUSR7 = 207, XLAL_EUSR8 = 208, XLAL_EUSR9 = 209,   XLAL_ESYS = 254, XLAL_EERR = 255, XLAL_EFPINVAL = 256, XLAL_EFPDIV0 = 257,   XLAL_EFPOVRFLW = 258, XLAL_EFPUNDFLW = 259, XLAL_EFPINEXCT = 260, XLAL_EMAXITER = 261,   XLAL_EDIVERGE = 262, XLAL_ESING = 263, XLAL_ETOL = 264, XLAL_ELOSS = 265,   XLAL_EFUNC = 1024 }
	XLAL error numbers and return values. More...
Functions
	NRCSID (XLALERRORH,"$Id: XLALError.h,v 1.14 2008/04/24 17:04:21 kipp Exp $")
int	XLALPrintError (const char *fmt,...)
	Prints an error message if error printing is enabled by lalDebugLevel.
int	XLALPrintWarning (const char *fmt,...)
	Prints a warning message if warning printing is enabled by lalDebugLevel.
int	XLALPrintInfo (const char *fmt,...)
	Prints an info message if info printing is enabled by lalDebugLevel.
int	XLALPrintProgressBar (double)
	Prints a progress bar at the "info" verbosity level.
int	XLALPrintDeprecationWarning (const char *old, const char *replacement)
	Prints a deprecation warning at the "warning" verbosity level.
const char *	XLALErrorString (int errnum)
	Returns the error message associated with an error number.
void	XLALPerror (const char *func, const char *file, int line, int errnum)
	Prints an error message for a particular error code in a standard format.
void	XLALDefaultErrorHandler (const char *func, const char *file, int line, int errnum)
	The default XLAL error handler.
void	XLALSilentErrorHandler (const char *func, const char *file, int line, int errnum)
	A silent XLAL error handler.
void	XLALAbortErrorHandler (const char *func, const char *file, int line, int errnum)
	The XLAL error handler that raises SIGABRT.
void	XLALExitErrorHandler (const char *func, const char *file, int line, int errnum)
	The XLAL error handler that calls exit.
void	XLALBacktraceErrorHandler (const char *func, const char *file, int line, int errnum)
	The XLAL error handler that prints a function call backtrace then raises SIGABRT.
XLALErrorHandlerType *	XLALSetErrorHandler (XLALErrorHandlerType *newHandler)
	Sets the error handler to a new handler and returns the old handler.
XLALErrorHandlerType *	XLALSetDefaultErrorHandler (void)
	Sets the error handler to the default handler and returns the old handler.
XLALErrorHandlerType *	XLALSetSilentErrorHandler (void)
	Sets the error handler to a silent handler and returns the old handler.
int	XLALSetErrno (int errnum)
	Sets the XLAL error number to errnum, returns the new value.
int	XLALGetBaseErrno (void)
	Gets the XLAL base error number ignoring the internal-function-failed flag.
int	XLALClearErrno (void)
	Clears the XLAL error number, returns the old value.
int *	XLALGetErrnoPtr (void)
	Function to return pointer to the XLAL error number.
XLALErrorHandlerType **	XLALGetErrorHandlerPtr (void)
	Function to return pointer to the XLAL error handler function pointer.
void	XLALError (const char *func, const char *file, int line, int errnum)
	Routine to set the XLAL error number and invoke the XLAL error handler.

---

Detailed Description

Author:

Creighton, J.This header covers routines to provide the XLAL interface error handling.

D. E.

Date:

2005

XLAL Errors

When an XLAL routine fails, the routine should set the xlalErrno to an appropriate error number and return with the appropriate error code. The return value depends on the return type of the XLAL function. Furthermore, the XLAL error handler should be invoked.

Whenever possible (i.e., always), standard XLAL error macros should be used when generating an error. These macros (i) invoke the current error handler, (ii) set the error code to the specified value, and (iii) return with the correct return value. The error macros that should be used are:

XLAL_ERROR(func,errnum) for XLAL routines returning an integer type.

XLAL_ERROR_VOID(func,errnum) for XLAL routines with no return value.

XLAL_ERROR_NULL(func,errnum) for XLAL routines returning a pointer.

XLAL_ERROR_REAL4(func,errnum) for XLAL routines returning a REAL4 floating-point value.

XLAL_ERROR_REAL8(func,errnum) for XLAL routines returning a REAL8 floating-point value.

Additional error, warning, and informational messages can be generated using the routines XLALPrintError(), XLALPrintWarning() and XLALPrintInfo(). These routines (which work just like printf()) print or suppress the message depending on the value of lalDebugLevel.

On rare occations, you may be prepared for an XLAL routine to fail, and may want to handle the failure immediately. In these circumstances, the XLAL error handler needs to be disabled before the routine is called so that the failure can be caught. The XLAL_TRY(statement,errnum) macro is designed to be used in these situations. Here is an example:

 REAL8 XLALLogFactorial( INT4 n )
 {
   REAL8 y;
   int errnum; 
   XLAL_TRY( y = XLALGammaFunction( n + 1 ), errnum );
   if ( XLAL_IS_REAL8_FAIL_NAN( y ) )
     switch ( errnum )
     {
       case XLAL_ERANGE:
         y  = n * ( log(n) - 1 );
         y += 0.5 * log( 2.0 * LAL_PI * n );
         return y;
       default:
         XLALSetErrno( errnum );
         XLAL_ERROR_REAL8( "XLALLogFactorial", XLAL_EFUNC );
     }
   return log( y );
 }

XLAL Function Return Codes

XLAL functions that return an integer-type will return XLAL_FAILURE on failure. XLAL functions that return a pointer will return NULL on failure.

The LAL specification requires that XLAL functions that return a floating-point type (either REAL4 or REAL8) should return a particular value to indicate an error. These values are given by the macros XLAL_REAL4_FAIL_NAN and XLAL_REAL8_FAIL_NAN (they are Not a Number or NaN values). To implement these we choose hexadecimal representations and then provide static functions that return the equivalent REAL4 or REAL8 values. The macros then invoke these functions. This is done so that the compiler can easily inline the functions (or eliminate them if they are not used). Conversion from the hexadecimal representation to the floating-point representation is done using a union.

The LAL specification also requires that there be two macros, XLAL_IS_REAL4_FAIL_NAN(val) and XLAL_IS_REAL8_FAIL_NAN(val) that will test if val is one of these XLAL-specific fail NaNs. Again these macros invoke static functions that return the result of the comparison. The cmparison itself is done with the hexadecimal representation.

XLAL Error Codes

The LAL specification requires particular return code and error values. These are implemented here as enumeration constants in the XLALErrorValue enumeration.

Definition in file XLALError.h.

---

Define Documentation

#define UNUSED

Definition at line 152 of file XLALError.h.

#define XLAL_REAL4_FAIL_NAN_INT   0x7fc001a1

Hexadecimal representation of REAL4 NaN failure bit pattern.

Definition at line 177 of file XLALError.h.

#define XLAL_REAL8_FAIL_NAN_INT   LAL_INT8_C(0x7ff80000000001a1)

Hexadecimal representation of REAL8 NaN failure bit pattern.

Definition at line 178 of file XLALError.h.

#define XLAL_REAL4_FAIL_NAN   ( XLALREAL4FailNaN() )

Floating-point value of the XLAL REAL4 failure NaN.

Definition at line 228 of file XLALError.h.

#define XLAL_REAL8_FAIL_NAN   ( XLALREAL8FailNaN() )

Floating-point value of the XLAL REAL8 failure NaN.

Definition at line 229 of file XLALError.h.

#define XLAL_IS_REAL4_FAIL_NAN

(

val

)

XLALIsREAL4FailNaN(val)

Tests if val is a XLAL REAL4 failure NaN.

Definition at line 232 of file XLALError.h.

#define XLAL_IS_REAL8_FAIL_NAN

(

val

)

XLALIsREAL8FailNaN(val)

Tests if val is a XLAL REAL8 failure NaN.

Definition at line 233 of file XLALError.h.

#define XLAL_PERROR

(

func

)

XLALPerror( func, __FILE__, __LINE__, xlalErrno )

Prints an error message for the current value of xlalErrno.

Definition at line 317 of file XLALError.h.

#define xlalErrno   ( * XLALGetErrnoPtr() )

Modifiable lvalue containing the XLAL error number.

Definition at line 387 of file XLALError.h.

#define XLALErrorHandler   ( * XLALGetErrorHandlerPtr() )

Modifiable lvalue containing the XLAL error handler.

Definition at line 388 of file XLALError.h.

#define XLAL_TRY	(	statement,
		errnum		)

Value:

do {           XLALErrorHandlerType *xlalSaveErrorHandler;           int xlalSaveErrno;           xlalSaveErrorHandler = XLALSetSilentErrorHandler();           xlalSaveErrno = xlalErrno;           XLALClearErrno();           statement ;           errnum = xlalErrno;           xlalErrno = xlalSaveErrno;           XLALSetErrorHandler( xlalSaveErrorHandler );         } while ( 0 )

A macro to (i) disable the XLAL error handling and preserve the current value of xlalErrno (ii) perform a statement that involves an XLAL function call and (iii) restore the XLAL error handler and value of xlalErrno while setting variable errnum to the xlalErrno set by the statement.

Definition at line 400 of file XLALError.h.

#define XLAL_ERROR_VAL	(	func,
		errnum,
		val		)

Value:

do {           XLALError( func, __FILE__, __LINE__, errnum );           return val;         } while (0)

Macro to invoke the XLALError() function and return with code val (it should not really be used itself, but forms the basis for other macros).

Definition at line 435 of file XLALError.h.

#define XLAL_ERROR	(	func,
		errnum		)	XLAL_ERROR_VAL( func, errnum, XLAL_FAILURE )

Macro to invoke a failure from a XLAL routine returning an integer.

Definition at line 442 of file XLALError.h.

#define XLAL_ERROR_NULL	(	func,
		errnum		)	XLAL_ERROR_VAL( func, errnum, NULL )

Macro to invoke a failure from a XLAL routine returning a pointer.

Definition at line 446 of file XLALError.h.

#define XLAL_ERROR_VOID	(	func,
		errnum		)	XLAL_ERROR_VAL( func, errnum, /* void */ )

Macro to invoke a failure from a XLAL routine returning void.

Definition at line 450 of file XLALError.h.

#define XLAL_ERROR_REAL4	(	func,
		errnum		)	XLAL_ERROR_VAL( func, errnum, XLAL_REAL4_FAIL_NAN )

Macro to invoke a failure from a XLAL routine returning a REAL4.

Definition at line 454 of file XLALError.h.

#define XLAL_ERROR_REAL8	(	func,
		errnum		)	XLAL_ERROR_VAL( func, errnum, XLAL_REAL8_FAIL_NAN )

Macro to invoke a failure from a XLAL routine returning a REAL8.

Definition at line 458 of file XLALError.h.

---

Typedef Documentation

typedef void XLALErrorHandlerType(const char *func, const char *file, int line, int errnum)

The XLAL error handler type.

Definition at line 328 of file XLALError.h.

---

Enumeration Type Documentation

enum XLALErrorValue

XLAL error numbers and return values.

Enumerator:

XLAL_SUCCESS	Success return value (not an error number).
XLAL_FAILURE	Failure return value (not an error number).
XLAL_EIO	I/O error.
XLAL_ENOMEM	Memory allocation error.
XLAL_EFAULT	Invalid pointer.
XLAL_EINVAL	Invalid argument.
XLAL_EDOM	Input domain error.
XLAL_ERANGE	Output range error.
XLAL_EFAILED	Generic failure.
XLAL_EBADLEN	Inconsistent or invalid length.
XLAL_ESIZE	Wrong size.
XLAL_EDIMS	Wrong dimensions.
XLAL_ETYPE	Wrong or unknown type.
XLAL_ETIME	Invalid time.
XLAL_EFREQ	Invalid freqency.
XLAL_EUNIT	Invalid units.
XLAL_ENAME	Wrong name.
XLAL_EDATA	Invalid data.
XLAL_EUSR0	User-defined error 0.
XLAL_EUSR1	User-defined error 1.
XLAL_EUSR2	User-defined error 2.
XLAL_EUSR3	User-defined error 3.
XLAL_EUSR4	User-defined error 4.
XLAL_EUSR5	User-defined error 5.
XLAL_EUSR6	User-defined error 6.
XLAL_EUSR7	User-defined error 7.
XLAL_EUSR8	User-defined error 8.
XLAL_EUSR9	User-defined error 9.
XLAL_ESYS	System error.
XLAL_EERR	Internal error.
XLAL_EFPINVAL	IEEE Invalid floating point operation, eg sqrt(-1), 0/0.
XLAL_EFPDIV0	IEEE Division by zero floating point error.
XLAL_EFPOVRFLW	IEEE Floating point overflow error.
XLAL_EFPUNDFLW	IEEE Floating point underflow error.
XLAL_EFPINEXCT	IEEE Floating point inexact error.
XLAL_EMAXITER	Exceeded maximum number of iterations.
XLAL_EDIVERGE	Series is diverging.
XLAL_ESING	Apparent singularity detected.
XLAL_ETOL	Failed to reach specified tolerance.
XLAL_ELOSS	Loss of accuracy.
XLAL_EFUNC	Internal function call failed bit: "or" this with existing error number.

Definition at line 238 of file XLALError.h.

---

Function Documentation

NRCSID	(	XLALERRORH	,
		"$Id: XLALError.	h,
		v 1.14 2008/04/24 17:04:21 kipp Exp $"
	)

int XLALPrintError	(	const char *	fmt,
			...
	)

Prints an error message if error printing is enabled by lalDebugLevel.

Definition at line 45 of file XLALError.c.

int XLALPrintWarning	(	const char *	fmt,
			...
	)

Prints a warning message if warning printing is enabled by lalDebugLevel.

Definition at line 59 of file XLALError.c.

int XLALPrintInfo	(	const char *	fmt,
			...
	)

Prints an info message if info printing is enabled by lalDebugLevel.

Definition at line 73 of file XLALError.c.

int XLALPrintProgressBar

(

double

)

Prints a progress bar at the "info" verbosity level.

Definition at line 90 of file XLALError.c.

int XLALPrintDeprecationWarning	(	const char *	old,
		const char *	replacement
	)

Prints a deprecation warning at the "warning" verbosity level.

Definition at line 104 of file XLALError.c.

const char* XLALErrorString

(

int

code

)

Returns the error message associated with an error number.

Definition at line 316 of file XLALError.c.

void XLALPerror	(	const char *	func,
		const char *	file,
		int	line,
		int	code
	)

Prints an error message for a particular error code in a standard format.

Definition at line 441 of file XLALError.c.

void XLALDefaultErrorHandler	(	const char *	func,
		const char *	file,
		int	line,
		int	errnum
	)

The default XLAL error handler.

Definition at line 465 of file XLALError.c.

void XLALSilentErrorHandler	(	const char *	func,
		const char *	file,
		int	line,
		int	errnum
	)

A silent XLAL error handler.

Definition at line 472 of file XLALError.c.

void XLALAbortErrorHandler	(	const char *	func,
		const char *	file,
		int	line,
		int	errnum
	)

The XLAL error handler that raises SIGABRT.

Definition at line 504 of file XLALError.c.

void XLALExitErrorHandler	(	const char *	func,
		const char *	file,
		int	line,
		int	errnum
	)

The XLAL error handler that calls exit.

Definition at line 512 of file XLALError.c.

void XLALBacktraceErrorHandler	(	const char *	func,
		const char *	file,
		int	line,
		int	errnum
	)

The XLAL error handler that prints a function call backtrace then raises SIGABRT.

Definition at line 521 of file XLALError.c.

XLALErrorHandlerType* XLALSetErrorHandler

(

XLALErrorHandlerType *

newHandler

)

Sets the error handler to a new handler and returns the old handler.

Definition at line 280 of file XLALError.c.

XLALErrorHandlerType* XLALSetDefaultErrorHandler

(

void

)

Sets the error handler to the default handler and returns the old handler.

Definition at line 290 of file XLALError.c.

XLALErrorHandlerType* XLALSetSilentErrorHandler

(

void

)

Sets the error handler to a silent handler and returns the old handler.

Definition at line 299 of file XLALError.c.

int XLALSetErrno

(

int

errnum

)

Sets the XLAL error number to errnum, returns the new value.

Definition at line 237 of file XLALError.c.

int XLALGetBaseErrno

(

void

)

Gets the XLAL base error number ignoring the internal-function-failed flag.

Definition at line 264 of file XLALError.c.

int XLALClearErrno

(

void

)

Clears the XLAL error number, returns the old value.

Definition at line 271 of file XLALError.c.

int* XLALGetErrnoPtr

(

void

)

Function to return pointer to the XLAL error number.

Definition at line 123 of file XLALError.c.

XLALErrorHandlerType** XLALGetErrorHandlerPtr

(

void

)

Function to return pointer to the XLAL error handler function pointer.

Definition at line 132 of file XLALError.c.

void XLALError	(	const char *	func,
		const char *	file,
		int	line,
		int	errnum
	)

Routine to set the XLAL error number and invoke the XLAL error handler.

It is used by the error macros.

Parameters:

func	name of function where the error occurs
file	source file name (use the __FILE__ macro)
line	source line number (use the __LINE__ macro)
errnum	error code

Definition at line 487 of file XLALError.c.

---