Detailed Description

Provides routines to report and handle errors.

Synopsis

#include <lal/LALError.h>

Note: These LAL-interface functions are obsolete and deprecated, use the XLAL functions described in Header XLALError.h instead.

This header covers routines that print status messages, and that allow functions to abort. These functions should not be invoked in production code, except in very specific circumstances.

Description

These functions cause LAL to print status messages and perform basic error handling. Their implementation is quite simple but may be altered in the future to provide reasonable behaviour when integrated with other systems (e.g., LDAS). As a general rule, LALWarning() and LALInfo() are the only routines that programmers should use in their own modules; the other routines are used internally by LAL. Descriptions of the individual functions are as follows.

LALPrintError(): prints a formatted string to some designated output device (usually the stderr stream), returning the number of characters printed, or negative if an error occurred. The format of the argument list is the same as for the standard C routine printf(). By funneling all LAL error printing through this one routine, it is easier to adapt LAL to implementations that have particular I/O or error-logging requirements. Most LAL routines should use LALError(), LALWarning(), and LALInfo() to report their status, rather than calling LALPrintError() directly.

LALRaise(): prints a formatted string to an error logging device, as above, and then raises the requested signal. Standard LAL routines should not terminate execution, but should instead return control to the calling routine, reporting errors through their LALStatus structure. Programmers should never invoke LALRaise() explicitly. A hook to a LALRaise()-type function, lalRaiseHook, is provided, should the user wish to change the default behavior of LALRaise() (i.e., the LAL library always uses lalRaiseHook rather than LALRaise, but lalRaiseHook is set to LALRaise by default).

LALAbort(): prints a formatted string to an error logging device, as above, and then terminates program execution. Usually this is done by raising a SIGABRT signal, but this can change in implementations that have different requirements. Standard LAL routines should not terminate execution, but should instead return control to the calling routine, reporting errors through their LALStatus structure. The exception is when a function receives a NULL status pointer, in which case it has no option but to abort. This is done automatically by the INITSTATUS() macro (see LALStatusMacros.h), so programmers should never need to invoke LALAbort() explicitly. A hook to a LALAbort()-type function, lalAbortHook, is provided, should the user wish to change the default behavior of LALAbort() (i.e., the LAL library always uses lalAbortHook rather than LALAbort, but lalAbortHook is set to LALAbort by default).

LALError(): prints the statement string to the error log, provided that the value of the global lalDebugLevel is set to allow error messages. It returns the number of characters printed. This is the standard LAL routine for printing error messages. However, LALError() is called automatically by the status-handling macros (see LALStatusMacros.h) whenever a LAL function returns with non-zero error code. Since an error is, by definition, a condition that would cause a routine to terminate abnormally, LAL programmers will generally not have to call LALError() explicitly.

LALWarning(): prints the warning string to the error log, provided that the value of the global lalDebugLevel is set to allow warning messages. It returns the number of characters printed. A warning message is less serious than an error message: it indicates that computation is proceeding successfully, but with unusual or unexpected behaviour that may invalidate the results of the computation.

LALInfo(): prints the info string to the error log, provided that the value of the global lalDebugLevel is set to allow information messages. It returns the number of characters printed. An information message indicates that a computation is proceding normally, and simply provides additional information about its progress.

LALTrace(): prints a message providing information, taken from the status structure, about the function currently being executed; it is used to track the progress of execution through nested function calls. It returns the number of characters printed. The message begins with the word Enter (if exitflg = 0) or Leave (if exitflg \(\neq0\)), to indicate whether the flow of execution has just entered or is about to leave the function. Tracking information is printed only if the value of the global lalDebugLevel is set to allow it. LALTrace() is called automatically by the status macros when entering or leaving a function (see LALStatusMacros.h), so LAL programmers need never invoke it explicitly.

Algorithm

The functions LALError(), LALWarning(), LALInfo(), and LALTrace() print status messages depending on the value of the global lalDebugLevel. Specifically, each type of status message is associated with a particular bit in lalDebugLevel. If the value of the bit is 1, that type status message will be printed; if it is 0, that type of message will be suppressed. See the documentation in LALStatusMacros.h for information about how to set the value of lalDebugLevel.

Macro replacement functions

When a LAL module is compiled with the flag LAL_STATUS_MACROS_DISABLED set, the usual status-handling macros defined in LALStatusMacros.h are replaced with function calls to specialized support functions that perform the same operations. These functions are necessarily global in scope, and so we provide their prototype declarations below. However, they will never be invoked explicitly in any LAL function, so we will not bother with additional usage information.

Prototypes
int	LALPrintError (const char *fmt,...)

int	LALRaise (int sig, const char *fmt,...)

void	LALAbort (const char *fmt,...)

int	LALError (LALStatus status, const char statement)

int	LALWarning (LALStatus status, const char warning)

int	LALInfo (LALStatus status, const char info)

int	LALTrace (LALStatus *status, int exitflg)

Function Documentation

◆ LALPrintError()

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

Definition at line 46 of file LALError.c.

◆ LALRaise()

int LALRaise	(	int	sig,
		const char *	fmt,
			...
	)

Definition at line 58 of file LALError.c.

◆ LALAbort()

void LALAbort	(	const char *	fmt,
			...
	)

Definition at line 76 of file LALError.c.

◆ LALError()

int LALError	(	LALStatus *	status,
		const char *	statement
	)

Definition at line 93 of file LALError.c.

◆ LALWarning()

int LALWarning	(	LALStatus *	status,
		const char *	warning
	)

Definition at line 108 of file LALError.c.

◆ LALInfo()

int LALInfo	(	LALStatus *	status,
		const char *	info
	)

Definition at line 122 of file LALError.c.

◆ LALTrace()

int LALTrace	(	LALStatus *	status,
		int	exitflg
	)

Definition at line 135 of file LALError.c.