Error Handling and Debugging

Error handling and debugging module, utilities, macros and definitions. See the Error handling and Debugging topic guide for more details.

Summary

S_NEW_ERR	Set a new error with no context.
S_CLR_ERR	Clear the given error.
S_CTX_ERR	Set a new error with a context.
S_FTL_ERR	Set a new fatal context error.
S_CHK_ERR	Check if an error has been set.
S_WARNING	Macro that sets a warning message.
S_DEBUG	Macro that sets a debug message.
s_set_errdbg_level	Change the debugging level.
s_get_errdbg_level	Get the debugging level.
s_set_errdbg_logger	Set the error and debugging system logger to the given one.
s_errdbg_on	Query whether the Error and Debugging System is activated or not.
s_error_str	Convert the given error code into a string representation.

Definitions

typedef enum s_erc

Definitions of error return codes.

Values:

• S_SUCCESS =         0 -

  Success, no errors.

• S_FAILURE =        -1 -

  An unspecified failure occurred.

• S_MEMERROR =       -2 -

  A memory allocation error.

• S_ARGERROR =       -3 -

  Error in function arguments.

• S_METHINVLD =      -4 -

  Class/Object method does not exist.

• S_IOEOF =          -5 -

  End of file/stream.

• S_WARNERR =        -6 -

  Warning, possible error.

• S_CONTERR =        -7 -

  Error context continued.

typedef enum s_dbg_lvl

Debug level definitions.

If the debug level is set to S_DBG_TRACE then all debug messages with a debug level equal and lower will be output to the Logging system.

See also:s_log_event.

Values:

• S_DBG_NONE = 0 -

  No debugging output.

• S_DBG_INFO = 1 -

  Basic debug level.

• S_DBG_TRACE = 2 -

  Verbose debug level.

• S_DBG_ALL = 3 -

  All debugging logged.

Macros

Set/Clear

Macros that sets and clears errors.

macro S_NEW_ERR(ERROR, ERROR_CODE)

Set a new error with no context.

Set ERROR to the error code that occurred, ERROR_CODE. This macro is useful in deeply nested functions where there is not enough context to add, i.e. it is only known that an error of ERROR_CODE type occurred, but not why it occurred.

Parameters:

• ERROR –

  Pointer to error code variable to set (type s_erc*).

• ERROR_CODE –

  The new error code (type s_erc).

macro S_CLR_ERR(ERROR)

Clear the given error.

It is good practice to clear the error code (*ERROR = S_SUCCESS) at the beginning of all functions.

Parameters:

• ERROR –

  Pointer to error code to clear (type s_erc*).

macro S_CTX_ERR(ERROR, NEW_ERROR, FUNCTION_NAME, MSG, ...)

Set a new error with a context.

Sets ERROR to the error code that occurred, NEW_ERROR, as well as giving the error logger the function name and a variable length argument string of the context wherein this error occurred.

Parameters:

• ERROR –

  Pointer to error code variable to set (type s_erc*).

• NEW_ERROR –

  The new error code (type s_erc).

• FUNCTION_NAME –

  The name of the function where the error occurred (optional, can be NULL).

• MSG –

  A format string specifying the error message and the format of the variable length argument list. Same as the standard printf() function.

macro S_FTL_ERR(ERROR, NEW_ERROR, FUNCTION_NAME, MSG, ...)

Set a new fatal context error.

Sets ERROR to the fatal error code that occurred, NEW_ERROR, as well as giving the error logger the function name and a variable length argument string of the context wherein this error occurred. The same as S_CTX_ERR except that if the build option SPCT_ERROR_ABORT_FATAL is set then the program is aborted.

Parameters:

• ERROR –

  Pointer to error code variable to set (type s_erc*).

• NEW_ERROR –

  The new error code (type s_erc).

• FUNCTION_NAME –

  The name of the function where the error occurred (optional, can be NULL).

• MSG –

  A format string specifying the error message and the format of the variable length argument list. Same as the standard printf() function.

See also

SPCT_ERROR_ABORT_FATAL

Check & Set

Macro that tests for errors and sets new context based on test.

macro S_CHK_ERR(ERROR, NEW_ERROR, FUNCTION_NAME, MSG, ...)

Check if an error has been set.

Test if an error has occurred (if ERROR is set, i.e. not equal to S_SUCCESS), and if so set a new context error (same as S_CTX_ERR), and return TRUE. If no error was set, (*ERROR = S_SUCCESS) then nothing is done and FALSE is returned. This macro can be used in if statements directly after calling a function with an error code parameter, testing if an error occurred, setting a new error context and executing the if statement. If no error occurred then no new context is set and the if statement is not executed.

Parameters:

• ERROR –

  Pointer to error code variable to set (type s_erc*).

• NEW_ERROR –

  The new error code (type s_erc).

• FUNCTION_NAME –

  The name of the function where the error occurred (optional, can be NULL).

• MSG –

  A format string specifying the error message and the format of the variable length argument list. Same as the standard printf() function.

Warnings

Macro that sets warning messages.

macro S_WARNING(ERROR, FUNCTION_NAME, MSG, ...)

Macro that sets a warning message.

Set a warning with the given context. The warning is logged with the given context and message.

Parameters:

• ERROR –

  Pointer to error code variable to set (type s_erc*).

• FUNCTION_NAME –

  The name of the function where the error occurred (optional, can be NULL).

• MSG –

  A format string specifying the error message and the format of the variable length argument list. Same as the standard printf() function.

Debugging

Macro that sets debug messages. If either SPCT_DEBUGMODE or SPCT_ERROR_HANDLING are not defined, then this macro will not log debugging messages.

macro S_DEBUG(LEVEL, MSG, ...)

Macro that sets a debug message.

The debug message is logged only if the given debug level is equal or lower that the set level of the Error handling and Debugging module. This level can be changed with the s_set_errdbg_level function.

Parameters:

• LEVEL –

  The debug level (s_dbg_lvl) of this message.

• MSG –

  A format string specifying the error message and the format of the variable length argument list. Same as the standard printf() function.

Functions

void s_set_errdbg_level(s_dbg_lvl level, s_erc *error)

Change the debugging level.

Parameters:

• level –

  The new debugging level.

• error –

  Error code.

See also:

s_dbg_lvl

s_dbg_lvl s_get_errdbg_level(s_erc *error)

Get the debugging level.

Parameters:

• error –

  Error code.

Return:

The debugging level.

See also:

s_dbg_lvl

void s_set_errdbg_logger(s_logger *logger)

Set the error and debugging system logger to the given one.

The current logger (if any) will be freed. This is useful when the logger needs to be changed after Speect has started up.

Parameters:

• logger –

  The new logger for the error and debugging system

s_bool s_errdbg_on(void)

Query whether the Error and Debugging System is activated or not.

The system can be activated/deactivate with the compile time definition of SPCT_ERROR_HANDLING. If deactivated then no logging or checking of error codes will occur.

Return:TRUE if activated, else FALSE.

See also

SPCT_ERROR_HANDLING

char *s_error_str(s_erc error)

Convert the given error code into a string representation.

Parameters:

• error –

  Error code.

Return:

Pointer to string representation of the given error code. If the error code is unknown then “<em>Undefined error</em>” is returned.

Note:

Caller is responsible for returned character buffer’s memory.

Thread-safe.