Detailed Description

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

Author: Creighton, J. 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. In addition, these macros may take an optional printf-like format string (along with additional parameters for this format string) to provide additional information about the nature of the failure. The error macros that should be used are:

XLAL_ERROR(errnum [, fmt [, ...]]) for XLAL routines returning an integer type.

XLAL_ERROR_VOID(errnum [, fmt [, ...]]) for XLAL routines with no return value.

XLAL_ERROR_NULL(errnum [, fmt [, ...]]) for XLAL routines returning a pointer.

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

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

Assert-like error checking can be performed with XLAL_CHECK-style macros. Unlike assert() statements, XLAL_CHECK macros do not get removed when the code is compiled with -DNDEBUG.

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. To print error/warning/info messages with a standard format, use the macros XLAL_PRINT_ERROR(fmt [, ...]) XLAL_PRINT_WARNING(fmt [, ...]) XLAL_PRINT_INFO(fmt [, ...])

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(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.

Prototypes
int	XLALPrintError (const char *fmt,...) _LAL_GCC_PRINTF_FORMAT_(1
	Prints an error message if error printing is enabled by lalDebugLevel. More...

int int	XLALPrintWarning (const char *fmt,...) _LAL_GCC_PRINTF_FORMAT_(1
	Prints a warning message if warning printing is enabled by lalDebugLevel. More...

int int int	XLALPrintInfo (const char *fmt,...) _LAL_GCC_PRINTF_FORMAT_(1
	Prints an info message if info printing is enabled by lalDebugLevel. More...

int int int int	XLALVPrintError (const char *fmt, va_list ap) _LAL_GCC_VPRINTF_FORMAT_(1)
	Prints an error message if error printing is enabled by lalDebugLevel. More...

int	XLALVPrintWarning (const char *fmt, va_list ap) _LAL_GCC_VPRINTF_FORMAT_(1)
	Prints a warning message if warning printing is enabled by lalDebugLevel. More...

int	XLALVPrintInfo (const char *fmt, va_list ap) _LAL_GCC_VPRINTF_FORMAT_(1)
	Prints an info message if info printing is enabled by lalDebugLevel. More...

void	XLALPrintErrorMessage (const char func, const char file, int line, const char *fmt,...) _LAL_GCC_PRINTF_FORMAT_(4
	Print an error message with standard XLAL formatting (if error messages are enabled by lalDebugLevel). More...

void void	XLALPrintWarningMessage (const char func, const char file, int line, const char *fmt,...) _LAL_GCC_PRINTF_FORMAT_(4
	Print an warning message with standard XLAL formatting (if warning messages are enabled by lalDebugLevel). More...

void void void	XLALPrintInfoMessage (const char func, const char file, int line, const char *fmt,...) _LAL_GCC_PRINTF_FORMAT_(4
	Print an info message with standard XLAL formatting (if info messages are enabled by lalDebugLevel). More...

void void void void	XLALVPrintErrorMessage (const char func, const char file, int line, const char *fmt, va_list ap) _LAL_GCC_VPRINTF_FORMAT_(4)
	Print an error message with standard XLAL formatting (if error messages are enabled by lalDebugLevel). More...

void	XLALVPrintWarningMessage (const char func, const char file, int line, const char *fmt, va_list ap) _LAL_GCC_VPRINTF_FORMAT_(4)
	Print an warning message with standard XLAL formatting (if warning messages are enabled by lalDebugLevel). More...

void	XLALVPrintInfoMessage (const char func, const char file, int line, const char *fmt, va_list ap) _LAL_GCC_VPRINTF_FORMAT_(4)
	Print an error message with standard XLAL formatting (if error messages are enabled by lalDebugLevel). More...

int	XLALPrintProgressBar (double)
	Prints a progress bar at the "info" verbosity level. More...

static _LAL_INLINE_ REAL4	XLALREAL4FailNaN (void)
	Returns the value of the XLAL `REAL4` failure NaN. More...

static _LAL_INLINE_ REAL8	XLALREAL8FailNaN (void)
	Returns the value of the XLAL `REAL8` failure NaN. More...

static _LAL_INLINE_ int	XLALIsREAL4FailNaN (REAL4 val)
	Tests if a value is an XLAL `REAL4` failure NaN. More...

static _LAL_INLINE_ int	XLALIsREAL8FailNaN (REAL8 val)
	Tests if a value is an XLAL `REAL8` failure NaN. More...

const char *	XLALErrorString (int errnum)
	Returns the error message associated with an error number. More...

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. More...

void	XLALDefaultErrorHandler (const char func, const char file, int line, int errnum)
	The default XLAL error handler. More...

void	XLALSilentErrorHandler (const char func, const char file, int line, int errnum)
	A silent XLAL error handler. More...

void	XLALAbortErrorHandler (const char func, const char file, int line, int errnum)
	The XLAL error handler that raises SIGABRT. More...

void	XLALExitErrorHandler (const char func, const char file, int line, int errnum)
	The XLAL error handler that calls exit. More...

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. More...

XLALErrorHandlerType **	XLALGetErrorHandlerPtr (void)
	Function to return pointer to the XLAL error handler function pointer. More...

XLALErrorHandlerType *	XLALSetErrorHandler (XLALErrorHandlerType *newHandler)
	Sets the error handler to a new handler and returns the old handler. More...

XLALErrorHandlerType *	XLALSetDefaultErrorHandler (void)
	Sets the error handler to the default handler and returns the old handler. More...

XLALErrorHandlerType *	XLALSetSilentErrorHandler (void)
	Sets the error handler to a silent handler and returns the old handler. More...

int	XLALSetErrno (int errnum)
	Sets the XLAL error number to errnum, returns the new value. More...

int	XLALGetBaseErrno (void)
	Gets the XLAL base error number ignoring the internal-function-failed flag. More...

int	XLALClearErrno (void)
	Clears the XLAL error number, returns the old value. More...

int *	XLALGetErrnoPtr (void)
	Function to return pointer to the XLAL error number. More...

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. More...

Typedefs
typedef void	XLALErrorHandlerType(const char func, const char file, int line, int errnum)
	The XLAL error handler type. More...

Enumerations
enum	XLALErrorValue { XLAL_SUCCESS = 0 , XLAL_FAILURE = -1 , XLAL_ENOENT = 2 , XLAL_EIO = 5 , XLAL_ENOMEM = 12 , XLAL_EFAULT = 14 , XLAL_EINVAL = 22 , XLAL_EDOM = 33 , XLAL_ERANGE = 34 , XLAL_ENOSYS = 38 , 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...

Macros
#define	XLAL_PRINT_DEPRECATION_WARNING(replacement)
	Prints a deprecation warning at the "warning" verbosity level. More...

#define	XLAL_PRINT_ERROR(...) XLALPrintErrorMessage(__func__, __FILE__, __LINE__, __VA_ARGS__)
	Macro that will print an error message with a standard format. More...

#define	XLAL_PRINT_WARNING(...) XLALPrintWarningMessage(__func__, __FILE__, __LINE__, __VA_ARGS__)
	Macro that will print a warning message with a standard format. More...

#define	XLAL_PRINT_INFO(...) XLALPrintInfoMessage(__func__, __FILE__, __LINE__, __VA_ARGS__)
	Macro that will print an info message with a standard format. More...

#define	XLAL_REAL4_FAIL_NAN_INT 0x7fc001a1
	Hexadecimal representation of `REAL4` NaN failure bit pattern. More...

#define	XLAL_REAL8_FAIL_NAN_INT LAL_INT8_C(0x7ff80000000001a1)
	Hexadecimal representation of `REAL8` NaN failure bit pattern. More...

#define	XLAL_REAL4_FAIL_NAN ( XLALREAL4FailNaN() )
	Floating-point value of the XLAL `REAL4` failure NaN. More...

#define	XLAL_REAL8_FAIL_NAN ( XLALREAL8FailNaN() )
	Floating-point value of the XLAL `REAL8` failure NaN. More...

#define	XLAL_IS_REAL4_FAIL_NAN(val) XLALIsREAL4FailNaN(val)
	Tests if `val` is a XLAL `REAL4` failure NaN. More...

#define	XLAL_IS_REAL8_FAIL_NAN(val) XLALIsREAL8FailNaN(val)
	Tests if `val` is a XLAL `REAL8` failure NaN. More...

#define	XLAL_PERROR() XLALPerror(__func__, __FILE__, __LINE__, xlalErrno)
	Prints an error message for the current value of `xlalErrno`. More...

#define	xlalErrno ( * XLALGetErrnoPtr() )
	Modifiable lvalue containing the XLAL error number. More...

#define	XLALErrorHandler ( * XLALGetErrorHandlerPtr() )
	Modifiable lvalue containing the XLAL error handler. More...

#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. More...

#define	XLAL_TRY_SILENT(statement, errnum)
	Performs the same actions as XLAL_TRY(), but additionally silences any error/warning/etc. More...

#define	XLAL_ERROR_VAL(val, ...) _XLAL_ERROR_IMPL_(return val, __VA_ARGS__)
	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). More...

#define	XLAL_ERROR(...) _XLAL_ERROR_IMPL_(return (int)XLAL_FAILURE, __VA_ARGS__)
	Macro to invoke a failure from a XLAL routine returning an integer. More...

#define	XLAL_ERROR_NULL(...) _XLAL_ERROR_IMPL_(return NULL, __VA_ARGS__)
	Macro to invoke a failure from a XLAL routine returning a pointer. More...

#define	XLAL_ERROR_VOID(...) _XLAL_ERROR_IMPL_(return, __VA_ARGS__)
	Macro to invoke a failure from a XLAL routine returning void. More...

#define	XLAL_ERROR_REAL4(...) _XLAL_ERROR_IMPL_(return XLAL_REAL4_FAIL_NAN, __VA_ARGS__)
	Macro to invoke a failure from a XLAL routine returning a `REAL4`. More...

#define	XLAL_ERROR_REAL8(...) _XLAL_ERROR_IMPL_(return XLAL_REAL8_FAIL_NAN, __VA_ARGS__)
	Macro to invoke a failure from a XLAL routine returning a `REAL8`. More...

#define	XLAL_ERROR_MAIN(...) _XLAL_ERROR_IMPL_(return EXIT_FAILURE, __VA_ARGS__)
	Macro to invoke a failure from a C `main()` routine. More...

#define	XLAL_ERROR_FAIL(...) _XLAL_ERROR_IMPL_(goto XLAL_FAIL, __VA_ARGS__)
	Macro to invoke a failure by jumping to a `XLAL_FAIL` label. More...

#define	XLAL_CHECK_VAL(val, assertion, ...) _XLAL_CHECK_IMPL_(return val, assertion, __VA_ARGS__)
	Macro to test an assertion; if it is not true, invoke the `XLALError()` function and return with code val (it should not really be used itself, but forms the basis for other macros). More...

#define	XLAL_CHECK(assertion, ...) _XLAL_CHECK_IMPL_(return (int)XLAL_FAILURE, assertion, __VA_ARGS__)
	Macro to test an assertion and invoke a failure if it is not true in a function that returns an integer. More...

#define	XLAL_CHECK_NULL(assertion, ...) _XLAL_CHECK_IMPL_(return NULL, assertion, __VA_ARGS__)
	Macro to test an assertion and invoke a failure if it is not true in a function that returns a pointer. More...

#define	XLAL_CHECK_VOID(assertion, ...) _XLAL_CHECK_IMPL_(return, assertion, __VA_ARGS__)
	Macro to test an assertion and invoke a failure if it is not true in a function that returns void. More...

#define	XLAL_CHECK_REAL4(assertion, ...) _XLAL_CHECK_IMPL_(return XLAL_REAL4_FAIL_NAN, assertion, __VA_ARGS__)
	Macro to test an assertion and invoke a failure if it is not true in a function that returns a `REAL4`. More...

#define	XLAL_CHECK_REAL8(assertion, ...) _XLAL_CHECK_IMPL_(return XLAL_REAL8_FAIL_NAN, assertion, __VA_ARGS__)
	Macro to test an assertion and invoke a failure if it is not true in a function that returns a `REAL8`. More...

#define	XLAL_CHECK_MAIN(assertion, ...) _XLAL_CHECK_IMPL_(return EXIT_FAILURE, assertion, __VA_ARGS__)
	Macro to test an assertion and invoke a failure if it is not true in a C `main()` routine. More...

#define	XLAL_CHECK_FAIL(assertion, ...) _XLAL_CHECK_IMPL_(goto XLAL_FAIL, assertion, __VA_ARGS__)
	Macro to test an assertion and invoke a failure if it is not true by jumping to a `XLAL_FAIL` label. More...

#define	XLAL_CHECK_ABORT(assertion)
	Macro to test an assertion and invoke a failure if it is not true by calling `lalAbortHook()`. More...

#define	XLAL_CHECK_EXIT(assertion)
	Macro to test an assertion and invoke a failure if it is not true by calling `exit(1)`. More...

Function Documentation

◆ XLALPrintError()

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

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

◆ XLALPrintWarning()

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

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

◆ XLALPrintInfo()

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

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

◆ XLALVPrintError()

int int int int XLALVPrintError	(	const char *	fmt,
		va_list	ap
	)

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

Definition at line 50 of file XLALError.c.

◆ XLALVPrintWarning()

int XLALVPrintWarning	(	const char *	fmt,
		va_list	ap
	)

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

Definition at line 56 of file XLALError.c.

◆ XLALVPrintInfo()

int XLALVPrintInfo	(	const char *	fmt,
		va_list	ap
	)

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

Definition at line 62 of file XLALError.c.

◆ XLALPrintErrorMessage()

void XLALPrintErrorMessage	(	const char *	func,
		const char *	file,
		int	line,
		const char *	fmt,
			...
	)

Print an error message with standard XLAL formatting (if error messages are enabled by lalDebugLevel).

◆ XLALPrintWarningMessage()

void void XLALPrintWarningMessage	(	const char *	func,
		const char *	file,
		int	line,
		const char *	fmt,
			...
	)

Print an warning message with standard XLAL formatting (if warning messages are enabled by lalDebugLevel).

◆ XLALPrintInfoMessage()

void void void XLALPrintInfoMessage	(	const char *	func,
		const char *	file,
		int	line,
		const char *	fmt,
			...
	)

Print an info message with standard XLAL formatting (if info messages are enabled by lalDebugLevel).

◆ XLALVPrintErrorMessage()

void void void void XLALVPrintErrorMessage	(	const char *	func,
		const char *	file,
		int	line,
		const char *	fmt,
		va_list	ap
	)

Print an error message with standard XLAL formatting (if error messages are enabled by lalDebugLevel).

Definition at line 104 of file XLALError.c.

◆ XLALVPrintWarningMessage()

void XLALVPrintWarningMessage	(	const char *	func,
		const char *	file,
		int	line,
		const char *	fmt,
		va_list	ap
	)

Print an warning message with standard XLAL formatting (if warning messages are enabled by lalDebugLevel).

Definition at line 118 of file XLALError.c.

◆ XLALVPrintInfoMessage()

void XLALVPrintInfoMessage	(	const char *	func,
		const char *	file,
		int	line,
		const char *	fmt,
		va_list	ap
	)

Print an error message with standard XLAL formatting (if error messages are enabled by lalDebugLevel).

Definition at line 132 of file XLALError.c.

◆ XLALPrintProgressBar()

int XLALPrintProgressBar ( double fraction )

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

Definition at line 181 of file XLALError.c.

◆ XLALREAL4FailNaN()

static _LAL_INLINE_ REAL4 XLALREAL4FailNaN ( void )

static

Returns the value of the XLAL REAL4 failure NaN.

Definition at line 323 of file XLALError.h.

◆ XLALREAL8FailNaN()

static _LAL_INLINE_ REAL8 XLALREAL8FailNaN ( void )

static

Returns the value of the XLAL REAL8 failure NaN.

Definition at line 335 of file XLALError.h.

◆ XLALIsREAL4FailNaN()

static _LAL_INLINE_ int XLALIsREAL4FailNaN ( REAL4 val )

static

Tests if a value is an XLAL REAL4 failure NaN.

Definition at line 347 of file XLALError.h.

◆ XLALIsREAL8FailNaN()

static _LAL_INLINE_ int XLALIsREAL8FailNaN ( REAL8 val )

static

Tests if a value is an XLAL REAL8 failure NaN.

Definition at line 368 of file XLALError.h.

◆ XLALErrorString()

const char * XLALErrorString ( int errnum )

Returns the error message associated with an error number.

Definition at line 409 of file XLALError.c.

◆ XLALPerror()

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.

Definition at line 539 of file XLALError.c.

◆ XLALDefaultErrorHandler()

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

The default XLAL error handler.

Definition at line 561 of file XLALError.c.

◆ XLALSilentErrorHandler()

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

A silent XLAL error handler.

◆ XLALAbortErrorHandler()

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

The XLAL error handler that raises SIGABRT.

Definition at line 599 of file XLALError.c.

◆ XLALExitErrorHandler()

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

The XLAL error handler that calls exit.

Definition at line 607 of file XLALError.c.

◆ XLALBacktraceErrorHandler()

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 615 of file XLALError.c.

◆ XLALGetErrorHandlerPtr()

XLALErrorHandlerType ** XLALGetErrorHandlerPtr ( void )

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

Definition at line 218 of file XLALError.c.

◆ XLALSetErrorHandler()

XLALErrorHandlerType * XLALSetErrorHandler ( XLALErrorHandlerType * newHandler )

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

Definition at line 372 of file XLALError.c.

◆ XLALSetDefaultErrorHandler()

XLALErrorHandlerType * XLALSetDefaultErrorHandler ( void )

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

Definition at line 383 of file XLALError.c.

◆ XLALSetSilentErrorHandler()

XLALErrorHandlerType * XLALSetSilentErrorHandler ( void )

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

Definition at line 392 of file XLALError.c.

◆ XLALSetErrno()

int XLALSetErrno ( int errnum )

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

Definition at line 327 of file XLALError.c.

◆ XLALGetBaseErrno()

int XLALGetBaseErrno ( void )

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

Definition at line 356 of file XLALError.c.

◆ XLALClearErrno()

int XLALClearErrno ( void )

Clears the XLAL error number, returns the old value.

Definition at line 363 of file XLALError.c.

◆ XLALGetErrnoPtr()

int * XLALGetErrnoPtr ( void )

Function to return pointer to the XLAL error number.

Definition at line 209 of file XLALError.c.

◆ XLALError()

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 582 of file XLALError.c.

Typedef Documentation

◆ XLALErrorHandlerType

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

The XLAL error handler type.

Definition at line 496 of file XLALError.h.

Enumeration Type Documentation

◆ XLALErrorValue

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_ENOENT	No such file or directory.
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_ENOSYS	Function not implemented.
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 400 of file XLALError.h.

Macro Definition Documentation

◆ XLAL_PRINT_DEPRECATION_WARNING

#define XLAL_PRINT_DEPRECATION_WARNING ( replacement )

Value:

  do { \
    static int _xlal_print_deprecation_warning_ = 1; \
    if (_xlal_print_deprecation_warning_) { \
      XLALPrintWarning( \
        "\nDEPRECATION WARNING: program has invoked obsolete function %s(). " \
        "Please see %s() for information about a replacement.\n", \
        __func__, replacement); \
      _xlal_print_deprecation_warning_ = 0; \
    } \
  } while(0)

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

Definition at line 228 of file XLALError.h.

◆ XLAL_PRINT_ERROR

#define XLAL_PRINT_ERROR ( ... ) XLALPrintErrorMessage(__func__, __FILE__, __LINE__, __VA_ARGS__)

Macro that will print an error message with a standard format.

Prototype: XLAL_PRINT_ERROR(fmt [, ...])

Parameters:

fmt A printf-like format string.
... (Optional) Arguments to the format string.

Definition at line 257 of file XLALError.h.

◆ XLAL_PRINT_WARNING

#define XLAL_PRINT_WARNING ( ... ) XLALPrintWarningMessage(__func__, __FILE__, __LINE__, __VA_ARGS__)

Macro that will print a warning message with a standard format.

Prototype: XLAL_PRINT_WARNING(fmt [, ...])

Parameters:

fmt A printf-like format string.
... (Optional) Arguments to the format string.

Definition at line 270 of file XLALError.h.

◆ XLAL_PRINT_INFO

#define XLAL_PRINT_INFO ( ... ) XLALPrintInfoMessage(__func__, __FILE__, __LINE__, __VA_ARGS__)

Macro that will print an info message with a standard format.

Prototype: XLAL_PRINT_INFO(fmt [, ...])

Parameters:

fmt A printf-like format string.
... (Optional) Arguments to the format string.

Definition at line 283 of file XLALError.h.

◆ XLAL_REAL4_FAIL_NAN_INT

#define XLAL_REAL4_FAIL_NAN_INT 0x7fc001a1

Hexadecimal representation of REAL4 NaN failure bit pattern.

Definition at line 312 of file XLALError.h.

◆ XLAL_REAL8_FAIL_NAN_INT

#define XLAL_REAL8_FAIL_NAN_INT LAL_INT8_C(0x7ff80000000001a1)

Hexadecimal representation of REAL8 NaN failure bit pattern.

Definition at line 313 of file XLALError.h.

◆ XLAL_REAL4_FAIL_NAN

#define XLAL_REAL4_FAIL_NAN ( XLALREAL4FailNaN() )

Floating-point value of the XLAL REAL4 failure NaN.

Definition at line 388 of file XLALError.h.

◆ XLAL_REAL8_FAIL_NAN

#define XLAL_REAL8_FAIL_NAN ( XLALREAL8FailNaN() )

Floating-point value of the XLAL REAL8 failure NaN.

Definition at line 389 of file XLALError.h.

◆ XLAL_IS_REAL4_FAIL_NAN

#define XLAL_IS_REAL4_FAIL_NAN ( val ) XLALIsREAL4FailNaN(val)

Tests if val is a XLAL REAL4 failure NaN.

Definition at line 392 of file XLALError.h.

◆ XLAL_IS_REAL8_FAIL_NAN

#define XLAL_IS_REAL8_FAIL_NAN ( val ) XLALIsREAL8FailNaN(val)

Tests if val is a XLAL REAL8 failure NaN.

Definition at line 393 of file XLALError.h.

◆ XLAL_PERROR

#define XLAL_PERROR ( ) XLALPerror(__func__, __FILE__, __LINE__, xlalErrno)

Prints an error message for the current value of xlalErrno.

Definition at line 485 of file XLALError.h.

◆ xlalErrno

#define xlalErrno ( * XLALGetErrnoPtr() )

Modifiable lvalue containing the XLAL error number.

Definition at line 571 of file XLALError.h.

◆ XLALErrorHandler

#define XLALErrorHandler ( * XLALGetErrorHandlerPtr() )

Modifiable lvalue containing the XLAL error handler.

Definition at line 572 of file XLALError.h.

◆ XLAL_TRY

#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 582 of file XLALError.h.

◆ XLAL_TRY_SILENT

#define XLAL_TRY_SILENT	(	statement,
		errnum
	)

Value:

        do { \
                int xlalSaveDebugLevel = lalDebugLevel; \
                XLALClobberDebugLevel(xlalSaveDebugLevel & ~(LALERRORBIT | LALWARNINGBIT | LALINFOBIT | LALTRACEBIT)); \
                XLAL_TRY(statement, errnum); \
                XLALClobberDebugLevel(xlalSaveDebugLevel); \
        } while (0)

Performs the same actions as XLAL_TRY(), but additionally silences any error/warning/etc.

messages being printed while statement is executed, regardless of the value of lalDebugLevel.

Definition at line 600 of file XLALError.h.

◆ XLAL_ERROR_VAL

#define XLAL_ERROR_VAL	(	val,
		...
	)	_XLAL_ERROR_IMPL_(return val, __VA_ARGS__)

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).

Prototype: XLAL_ERROR_VAL(val, errnum [, fmt [, ...]])

Parameters:

val The value to return.
errnum The XLAL error number to set.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 687 of file XLALError.h.

◆ XLAL_ERROR

#define XLAL_ERROR ( ... ) _XLAL_ERROR_IMPL_(return (int)XLAL_FAILURE, __VA_ARGS__)

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

Prototype: XLAL_ERROR(errnum [, fmt [, ...]])

Parameters:

errnum The XLAL error number to set.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 700 of file XLALError.h.

◆ XLAL_ERROR_NULL

#define XLAL_ERROR_NULL ( ... ) _XLAL_ERROR_IMPL_(return NULL, __VA_ARGS__)

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

Prototype: XLAL_ERROR_NULL(errnum [, fmt [, ...]])

Parameters:

errnum The XLAL error number to set.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 713 of file XLALError.h.

◆ XLAL_ERROR_VOID

#define XLAL_ERROR_VOID ( ... ) _XLAL_ERROR_IMPL_(return, __VA_ARGS__)

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

Prototype: XLAL_ERROR_VOID(errnum [, fmt [, ...]])

Parameters:

errnum The XLAL error number to set.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 726 of file XLALError.h.

◆ XLAL_ERROR_REAL4

#define XLAL_ERROR_REAL4 ( ... ) _XLAL_ERROR_IMPL_(return XLAL_REAL4_FAIL_NAN, __VA_ARGS__)

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

Prototype: XLAL_ERROR_REAL4(errnum [, fmt [, ...]])

Parameters:

errnum The XLAL error number to set.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 739 of file XLALError.h.

◆ XLAL_ERROR_REAL8

#define XLAL_ERROR_REAL8 ( ... ) _XLAL_ERROR_IMPL_(return XLAL_REAL8_FAIL_NAN, __VA_ARGS__)

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

Prototype XLAL_ERROR_REAL8(errnum [, fmt [, ...]])

Parameters:

errnum The XLAL error number to set.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 752 of file XLALError.h.

◆ XLAL_ERROR_MAIN

#define XLAL_ERROR_MAIN ( ... ) _XLAL_ERROR_IMPL_(return EXIT_FAILURE, __VA_ARGS__)

Macro to invoke a failure from a C main() routine.

Prototype XLAL_ERROR_MAIN(errnum [, fmt [, ...]])

Parameters:

errnum The XLAL error number to set.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 765 of file XLALError.h.

◆ XLAL_ERROR_FAIL

#define XLAL_ERROR_FAIL ( ... ) _XLAL_ERROR_IMPL_(goto XLAL_FAIL, __VA_ARGS__)

Macro to invoke a failure by jumping to a XLAL_FAIL label.

Prototype XLAL_ERROR_FAIL(errnum [, fmt [, ...]])

Parameters:

errnum The XLAL error number to set.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 778 of file XLALError.h.

◆ XLAL_CHECK_VAL

#define XLAL_CHECK_VAL	(	val,
		assertion,
		...
	)	_XLAL_CHECK_IMPL_(return val, assertion, __VA_ARGS__)

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

Prototype: XLAL_CHECK_VAL(val, assertion, errnum [, fmt [, ...]])

Parameters:

val The value to return.
assertion The assertion to test.
errnum The XLAL error number to set if the assertion is false.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 795 of file XLALError.h.

◆ XLAL_CHECK

#define XLAL_CHECK	(	assertion,
		...
	)	_XLAL_CHECK_IMPL_(return (int)XLAL_FAILURE, assertion, __VA_ARGS__)

Macro to test an assertion and invoke a failure if it is not true in a function that returns an integer.

Prototype: XLAL_CHECK(assertion, errnum [, fmt [, ...]])

Parameters:

assertion The assertion to test.
errnum The XLAL error number to set if the assertion is false.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 810 of file XLALError.h.

◆ XLAL_CHECK_NULL

#define XLAL_CHECK_NULL	(	assertion,
		...
	)	_XLAL_CHECK_IMPL_(return NULL, assertion, __VA_ARGS__)

Macro to test an assertion and invoke a failure if it is not true in a function that returns a pointer.

Prototype: XLAL_CHECK_NULL(assertion, errnum [, fmt [, ...]])

Parameters:

assertion The assertion to test.
errnum The XLAL error number to set if the assertion is false.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 825 of file XLALError.h.

◆ XLAL_CHECK_VOID

#define XLAL_CHECK_VOID	(	assertion,
		...
	)	_XLAL_CHECK_IMPL_(return, assertion, __VA_ARGS__)

Macro to test an assertion and invoke a failure if it is not true in a function that returns void.

Prototype: XLAL_CHECK_VOID(assertion, errnum [, fmt [, ...]])

Parameters:

assertion The assertion to test.
errnum The XLAL error number to set if the assertion is false.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 840 of file XLALError.h.

◆ XLAL_CHECK_REAL4

#define XLAL_CHECK_REAL4	(	assertion,
		...
	)	_XLAL_CHECK_IMPL_(return XLAL_REAL4_FAIL_NAN, assertion, __VA_ARGS__)

Macro to test an assertion and invoke a failure if it is not true in a function that returns a REAL4.

Prototype: XLAL_CHECK_REAL4(assertion, errnum [, fmt [, ...]])

Parameters:

assertion The assertion to test.
errnum The XLAL error number to set if the assertion is false.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 855 of file XLALError.h.

◆ XLAL_CHECK_REAL8

#define XLAL_CHECK_REAL8	(	assertion,
		...
	)	_XLAL_CHECK_IMPL_(return XLAL_REAL8_FAIL_NAN, assertion, __VA_ARGS__)

Macro to test an assertion and invoke a failure if it is not true in a function that returns a REAL8.

Prototype: XLAL_CHECK_REAL8(assertion, errnum [, fmt [, ...]])

Parameters:

assertion The assertion to test.
errnum The XLAL error number to set if the assertion is false.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 870 of file XLALError.h.

◆ XLAL_CHECK_MAIN

#define XLAL_CHECK_MAIN	(	assertion,
		...
	)	_XLAL_CHECK_IMPL_(return EXIT_FAILURE, assertion, __VA_ARGS__)

Macro to test an assertion and invoke a failure if it is not true in a C main() routine.

Prototype: XLAL_CHECK_MAIN(assertion, errnum [, fmt [, ...]])

Parameters:

assertion The assertion to test.
errnum The XLAL error number to set if the assertion is false.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 885 of file XLALError.h.

◆ XLAL_CHECK_FAIL

#define XLAL_CHECK_FAIL	(	assertion,
		...
	)	_XLAL_CHECK_IMPL_(goto XLAL_FAIL, assertion, __VA_ARGS__)

Macro to test an assertion and invoke a failure if it is not true by jumping to a XLAL_FAIL label.

Prototype: XLAL_CHECK_FAIL(assertion, errnum [, fmt [, ...]])

Parameters:

assertion The assertion to test.
errnum The XLAL error number to set if the assertion is false.
fmt (Optional) Format string for additional error information.
... (Optional) Additional arguments for printf-like format.

Definition at line 900 of file XLALError.h.

◆ XLAL_CHECK_ABORT

#define XLAL_CHECK_ABORT ( assertion )

Value:

        do { \
                if (!(assertion)) { \
                        XLAL_PRINT_ERROR("Check failed: %s", #assertion); \
                        lalAbortHook("XLAL_CHECK_ABORT() failed"); \
                } \
        } while (0)

Macro to test an assertion and invoke a failure if it is not true by calling lalAbortHook().

Prototype: XLAL_CHECK_ABORT(assertion)

Parameters:

assertion The assertion to test.

Definition at line 912 of file XLALError.h.

◆ XLAL_CHECK_EXIT

#define XLAL_CHECK_EXIT ( assertion )

Value:

        do { \
                if (!(assertion)) { \
                        XLAL_PRINT_ERROR("Check failed: %s", #assertion); \
                        exit(1); \
                } \
        } while (0)

Macro to test an assertion and invoke a failure if it is not true by calling exit(1).

Prototype: XLAL_CHECK_EXIT(assertion)

Parameters:

assertion The assertion to test.

Definition at line 930 of file XLALError.h.

Detailed Description

XLAL Errors

XLAL Function Return Codes

XLAL Error Codes

Prototypes

Typedefs

Enumerations

Macros

Function Documentation

◆ XLALPrintError()

◆ XLALPrintWarning()

◆ XLALPrintInfo()

◆ XLALVPrintError()

◆ XLALVPrintWarning()

◆ XLALVPrintInfo()

◆ XLALPrintErrorMessage()

◆ XLALPrintWarningMessage()

◆ XLALPrintInfoMessage()

◆ XLALVPrintErrorMessage()

◆ XLALVPrintWarningMessage()

◆ XLALVPrintInfoMessage()

◆ XLALPrintProgressBar()

◆ XLALREAL4FailNaN()

◆ XLALREAL8FailNaN()

◆ XLALIsREAL4FailNaN()

◆ XLALIsREAL8FailNaN()

◆ XLALErrorString()

◆ XLALPerror()

◆ XLALDefaultErrorHandler()

◆ XLALSilentErrorHandler()

◆ XLALAbortErrorHandler()

◆ XLALExitErrorHandler()

◆ XLALBacktraceErrorHandler()

◆ XLALGetErrorHandlerPtr()

◆ XLALSetErrorHandler()

◆ XLALSetDefaultErrorHandler()

◆ XLALSetSilentErrorHandler()

◆ XLALSetErrno()

◆ XLALGetBaseErrno()

◆ XLALClearErrno()

◆ XLALGetErrnoPtr()

◆ XLALError()

Typedef Documentation

◆ XLALErrorHandlerType

Enumeration Type Documentation

◆ XLALErrorValue

Macro Definition Documentation

◆ XLAL_PRINT_DEPRECATION_WARNING

◆ XLAL_PRINT_ERROR

◆ XLAL_PRINT_WARNING

◆ XLAL_PRINT_INFO

◆ XLAL_REAL4_FAIL_NAN_INT

◆ XLAL_REAL8_FAIL_NAN_INT

◆ XLAL_REAL4_FAIL_NAN

◆ XLAL_REAL8_FAIL_NAN

◆ XLAL_IS_REAL4_FAIL_NAN

◆ XLAL_IS_REAL8_FAIL_NAN

◆ XLAL_PERROR

◆ xlalErrno

◆ XLALErrorHandler

◆ XLAL_TRY

◆ XLAL_TRY_SILENT

◆ XLAL_ERROR_VAL

◆ XLAL_ERROR

◆ XLAL_ERROR_NULL

◆ XLAL_ERROR_VOID

◆ XLAL_ERROR_REAL4

◆ XLAL_ERROR_REAL8

◆ XLAL_ERROR_MAIN

◆ XLAL_ERROR_FAIL

◆ XLAL_CHECK_VAL

◆ XLAL_CHECK

◆ XLAL_CHECK_NULL

◆ XLAL_CHECK_VOID

◆ XLAL_CHECK_REAL4

◆ XLAL_CHECK_REAL8

◆ XLAL_CHECK_MAIN

◆ XLAL_CHECK_FAIL

◆ XLAL_CHECK_ABORT

◆ XLAL_CHECK_EXIT