Functions for errors handling¶

Apart from the constructor functions (the functions returning pointers to the chemfiles types); all the functions return a status code from the chfl_status enum:

enum chfl_status¶

`chfl_status` list the possible values for the return status code of chemfiles functions.

Values:

CHFL_SUCCESS = 0¶

Status code for successful operations.

CHFL_MEMORY_ERROR = 1¶

Status code for error concerning memory: out of memory, wrong size for pre-allocated buffers, *etc.*

CHFL_FILE_ERROR = 2¶

Status code for error concerning files: the file do not exist, the user does not have rights to open it, *etc.*

CHFL_FORMAT_ERROR = 3¶

Status code for error in file formating, i.e. for invalid files.

CHFL_SELECTION_ERROR = 4¶

Status code for invalid selection strings.

CHFL_GENERIC_ERROR = 5¶

Status code for any other error from Chemfiles.

CHFL_CXX_ERROR = 6¶

Status code for error in the C++ standard library.

The following function allow to handle errors:

const char *chfl_last_error(void)¶

Get the last error message.

// Generate an error
chfl_trajectory_open("noformat", 'r');

const char* error = chfl_last_error();
assert(strcmp(error, "Can not find a format associated with the \"\" extension.") == 0);

Return

A null-terminated string containing the last error message

chfl_status chfl_clear_errors(void)¶

Clear the last error message.

// Generate an error
chfl_trajectory_open("noformat", 'r');

const char* error = chfl_last_error();
assert(strcmp(error, "") != 0);

chfl_clear_errors();

error = chfl_last_error();
assert(strcmp(error, "") == 0);

Return

The operation status code. You can use `chfl_last_error` to learn about the error if the status code is not `CHFL_SUCCESS`.

typedef void (*chfl_warning_callback)(const char *message)¶

Callback type that can be used to process warning events.

chfl_status chfl_set_warning_callback(chfl_warning_callback callback)¶

Set the global warning `callback` to be used for each warning event.

char LAST_WARNING[1024] = {0};

void warning_callback(const char* message) {
    strncpy(LAST_WARNING, message, 1024);
    LAST_WARNING[1023] = '\0';
}

int main() {
    chfl_set_warning_callback(warning_callback);

    // Generate a warning event
    chfl_trajectory_open("noformat", 'r');

    assert(strcmp(LAST_WARNING, "Can not find a format associated with the \"\" extension.") == 0);
    return 0;
}

Return

`CHFL_SUCCESS`