charm_err#
Error handling module:
defines, initializes, frees and resets the
charm_err
structure,tests whether an
charm_err
structure is empty, andhandles errors.
Note
When CHarm detects an error (e.g., an internal memory allocation failure), it properly frees all the internally allocated memory before returning back to the caller. No memory leaks should therefore occur, not even after a premature exit.
Defines
-
CHARM_ERR_MAX_FILE 4096#
Maximum number of characters that can be stored in
charm_err.file[i]
,i = 0, 1, ..., CHARM_ERR_MAX_LEVEL - 1
, including the terminating null character.
-
CHARM_ERR_MAX_FUNC 256#
Maximum number of characters that can be stored in
charm_err.func[i]
,i = 0, 1, ..., CHARM_ERR_MAX_LEVEL - 1
, including the terminating null character.
-
CHARM_ERR_MAX_MSG 4096#
Maximum number of characters in
charm_err.msg
, including the terminating null character.
-
CHARM_ERR_MAX_LEVEL 10#
Maximum number of error propagations from the function, in which the error occurred to the caller.
-
CHARM_ERR_MALLOC_FAILURE "Memory allocation failure."#
Message to be printed when
malloc
orcalloc
fails.
Enums
-
enum [anonymous]#
Errors enumeration.
Values:
-
enumerator CHARM_FAILURE = -1#
Exit status returned when CHarm is explicitly asked to terminate the program in case it encounters an error.
-
enumerator CHARM_SUCCESS#
Successful execution of a CHarm function.
-
enumerator CHARM_EMEM#
Memory allocation failure (malloc, calloc).
-
enumerator CHARM_EFUNCARG#
Error in function input/output argument(s).
-
enumerator CHARM_EFILEIO#
Error in file reading/writing.
-
enumerator CHARM_EFFTWINIT#
Error in threads initialization by FFTW.
-
enumerator CHARM_FAILURE = -1#
Functions
-
charm_err *charm_err_init(void)#
Allocates and initializes the
charm_err
structure using default empty values.- Returns:
On success, returned is a pointer to the
charm_err
structure. On error,NULL
is returned.
-
void charm_err_free(charm_err *err)#
Frees the memory associated with
err
. No operation is performed iferr
isNULL
.
-
void charm_err_handler(charm_err *err, _Bool terminate)#
Error handler.
If
err
is not empty, prints detailed information on the error. Ifterminate
is set to Boolean1
, the program subsequently terminates.If
err
is empty, neither an error is printed nor the program is terminated (regardless of theterminate
value).
Before leaving the function,
err
is reset to the default empty values.Note
It is highly recommended to call the error handling function after every call of CHarm routines that take the
charm_err
structure as an input.
-
struct charm_err#
Error structure.
In most cases, it is created by functions from this module that return a pointer to
charm_err
. Experienced users may create the structure on their own, provided that they assign correct values to its members, so that CHarm can properly understood the data in it (see the rules summarized below).Public Members
-
unsigned int level#
Total number of error propagations from the function in which the error was encountered back to the caller.
-
char **file#
charm_err.file[0]
is a pointer to a string with the name of the file in which the error was encountered;charm_err.file[i]
,i = 1, 2, ..., CHARM_ERR_MAX_LEVEL - 1
, are file names through which the error was propagated to the caller.
-
unsigned int *line#
Pointer to an array with line numbers of
charm_err.file[i]
,i = 0, 1, ..., CHARM_ERR_MAX_LEVEL - 1
, at which thecharm_err
structure was modified.
-
char **func#
Same as
charm_err.file
, but with function names.
-
int code#
Error code (see the errors enumerations
CHARM_FAILURE
,CHARM_SUCCESS
, etc.).
-
char *msg#
Pointer to an error message.
-
_Bool issaturated#
Signalizes whether or not the levels of the error structure are saturated due to the error propagations. If true, the structure can no longer store most recent error propagations. This should never happen, though, since
CHARM_ERR_MAX_LEVEL
is chosen large enough.
-
unsigned int level#