Error handling module:

  • defines, initializes, frees and resets the charm_err structure,

  • tests whether an charm_err structure is empty, and

  • handles errors.


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.



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.


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.


Maximum number of characters in charm_err.msg, including the terminating null character.


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 or calloc fails.


enum [anonymous]#

Errors enumeration.


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.


Error in threads initialization by FFTW.


charm_err *charm_err_init(void)#

Allocates and initializes the charm_err structure using default empty values.


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 if err is NULL.

void charm_err_reset(charm_err *err)#

Resets err to the default empty values.

void charm_err_handler(charm_err *err, _Bool terminate)#

Error handler.

  • If err is not empty, prints detailed information on the error. If terminate is set to Boolean 1, the program subsequently terminates.

  • If err is empty, neither an error is printed nor the program is terminated (regardless of the terminate value).

Before leaving the function, err is reset to the default empty values.


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.

_Bool charm_err_isempty(const charm_err *err)#

Returns boolean 1 if err is empty or 0 otherwise.

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 the charm_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.