LAL  7.1.7.1-2d066e5

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 not compiled with NDEBUG defined.

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)
{
int errnum;
XLAL_TRY(y = XLALGammaFunction(n + 1), errnum);
switch (errnum) {
y = n * (log(n) - 1);
y += 0.5 * log(2.0 * LAL_PI * n);
return y;
default:
XLALSetErrno(errnum);
}
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...
 
XLALErrorHandlerTypeXLALSetErrorHandler (XLALErrorHandlerType *newHandler)
 Sets the error handler to a new handler and returns the old handler. More...
 
XLALErrorHandlerTypeXLALSetDefaultErrorHandler (void)
 Sets the error handler to the default handler and returns the old handler. More...
 
XLALErrorHandlerTypeXLALSetSilentErrorHandler (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...
 

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  )

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

◆ XLALREAL8FailNaN()

static _LAL_INLINE_ REAL8 XLALREAL8FailNaN ( void  )
static

Returns the value of the XLAL REAL8 failure NaN.

Definition at line 336 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 348 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 369 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
funcname of function where the error occurs
filesource file name (use the FILE macro)
linesource line number (use the LINE macro)
errnumerror 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 497 of file XLALError.h.

Enumeration Type Documentation

◆ 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 401 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 229 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 258 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 271 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 284 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 313 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 314 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 389 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 390 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 393 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 394 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 486 of file XLALError.h.

◆ xlalErrno

#define xlalErrno   ( * XLALGetErrnoPtr() )

Modifiable lvalue containing the XLAL error number.

Definition at line 572 of file XLALError.h.

◆ XLALErrorHandler

#define XLALErrorHandler   ( * XLALGetErrorHandlerPtr() )

Modifiable lvalue containing the XLAL error handler.

Definition at line 573 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)
XLALErrorHandlerType * XLALSetSilentErrorHandler(void)
Sets the error handler to a silent handler and returns the old handler.
Definition: XLALError.c:392
#define xlalErrno
Modifiable lvalue containing the XLAL error number.
Definition: XLALError.h:572

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 583 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)
enable error messages
Definition: LALDebugLevel.h:31
enable warning messages
Definition: LALDebugLevel.h:32
enable tracing messages
Definition: LALDebugLevel.h:34
#define lalDebugLevel
Definition: LALDebugLevel.h:56
enable info messages
Definition: LALDebugLevel.h:33

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 601 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 688 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 701 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 714 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 727 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 740 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 753 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 766 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 779 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 796 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 811 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 826 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 841 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 856 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 871 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 886 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 901 of file XLALError.h.