HEADAS Error Handling API

The HEADAS Error Handling API contains a number of functions and macros. The functions are described first, but in practice the macros should be used whenever possible, because they are easier to use and offer performance advantages. Central concepts are that each error message has an associated integer error number, and that the error handler as a whole also has an error number, which corresponds to the first error which was encountered.

1

int HDerror_get(void)

Returns the current value of the error handler's integer error status variable.

2

int HDerror_throw(const char * msg, const char * fileName, int line, int errNum)

This function uses the errNum argument to determine if an error has occurred, and if one has, changes the state of the error handler as appropriate to include the given information about the error. The argument msg is a string describing the error. If it is NULL no text message will be added. Arguments fileName and line are the file name and line number where the error was thrown. If fileName is NULL this information will not be included. The argument errNum is used in conjunction with the error handler's internal error status as follows: if either errNum or the error handler's internal status is non-zero, the information about the error will be added to the error handler's error message stack. If the error handler's internal status is zero, it will be set equal to errNum. Otherwise, the error handler's internal status will not be changed.

This function cannot be used to reset the error handler's internal status to zero after an error. To do this, use HDerror_reset().

3

int HDerror_hint(const char * msg, const char * fileName, int line, int errNum)

This function is similar to HDerror_throw, described above. The arguments given may be used to add to the description of an error. The difference between the two functions is that HDerror_hint never affects the overall error status of the error handler. HDerror_hint may thus not be used to create an error condition, only to comment on an existing error condition.

4

int HDerror_reset(void)

Resets the error handler's status to HD_OK and clears the error message stack.

5

int HDerror_get_stack(const char** stack)

This function returns a NULL-terminated array of const char* pointers which contains the current stack of messages. The standard HEADAS shutdown code which executes just before a task exits will print this stack to stderr if the task exits with non-zero status.

6

void HDerror_dump_silence(int silent)

Sets a silent mode which suppresses all reporting of errors. Calling it with a non-0 argument activates silent mode, while calling it with an argument of 0 sets non-silent (normal) mode. Note that silencing error reporting does not prevent error messages from being added to the error stack; rather it merely prevents these messages from being displayed.

This function should not be used in general. It is present only for the benefit of very unusual tools which return a non-0 exit status to indicate something other than an error. For example, ftdiff uses a non-0 status to indicate that it detected differences between the two input files.

7

int HDerror_dump_is_silent(void)

Returns the current silent mode of the error reporting mechanism. A non-0 value indicates errors are silenced, while a value of 0 indicates errors will be reported.

8

HD_OK

Macro whose value is 0, used throughout HEADAS software to indicate normal (non-error) status.

9

HD_ERROR_GET()

Macro which simply calls HDerror_get(). This is provided mainly for completeness and to allow a consistent look and feel if other similar macros are used.

10

HD_ERROR_THROW(MSG, STATUS)

This macro is provided for more convenient access to the function HDerror_throw(). This macro simply calls the function, using MSG for the input argument msg, STATUS for the input argument errNum, and filling in the fileName and line arguments using ANSI C's __FILE__ and __LINE__ macros.

11

HD_ERROR_SET(STATUS)

This macro is provided for more convenient access to the function HDerror_throw(). This macro simply calls the function, using NULL for the input argument msg, STATUS for the input argument errNum, and filling in the fileName and line arguments using ANSI C's __FILE__ and __LINE__ macros.

12

HD_ERROR_HINT(MSG, STATUS)

This macro is provided for more convenient access to the function HDerror_hint(). This macro simply calls the function, using MSG for the argument msg, STATUS for the argument errNum, and filling in the fileName and line arguments using ANSI C's __FILE__ and __LINE__ macros.