Miscelaneous functions

Error 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:

enumerator CHFL_SUCCESS

Status code for successful operations.

enumerator CHFL_MEMORY_ERROR

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

enumerator CHFL_FILE_ERROR

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

enumerator CHFL_FORMAT_ERROR

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

enumerator CHFL_SELECTION_ERROR

Status code for invalid selection strings.

enumerator CHFL_CONFIGURATION_ERROR

Status code for configuration files errors.

enumerator CHFL_OUT_OF_BOUNDS

Status code for out of bounds errors.

enumerator CHFL_PROPERTY_ERROR

Status code for errors related to properties.

enumerator CHFL_GENERIC_ERROR

Status code for any other error from Chemfiles.

enumerator CHFL_CXX_ERROR

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

const char *chfl_last_error(void)

Get the last error message.

The last error message is a thread local variable, so you need to call this function in the thread from where the error happened.

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

const char* error = chfl_last_error();
assert(strcmp(error, "file at 'noformat' does not have an extension, provide a format name to read it") == 0);

Return

A null-terminated string containing the last error message

chfl_status chfl_clear_errors(void)

Clear the thread local last error message.

The last error message is a thread local variable, so this function will only clear it in the thread where it is called.

// 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.

Format list and Metadata

chfl_status chfl_formats_list(chfl_format_metadata **metadata, uint64_t *count)

Get the list of formats known by chemfiles, as well as all associated metadata.

This function allocate memory for all known formats, and set metadata to this new array. Users of this function are responsible with cleaning up this memory using chfl_free. The number of known formats (and thus the size of the metadata array) is set in count.

chfl_format_metadata* formats = NULL;
uint64_t count = 0;
chfl_formats_list(&formats, &count);

for (uint64_t i=0; i<count; i++) {
    printf("%s (%s)\n", formats[i].name, formats[i].extension == NULL ? "" : formats[i].extension);
}

// the user is responsible with freeing the memory
chfl_free(formats);

Return

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

struct chfl_format_metadata

A chfl_format_metadata contains metadata associated with one format.

Public Members

const char *name

Name of the format.

const char *extension

Extension associated with the format, or NULL if there is no extension associated.

const char *description

Extended, user-facing description of the format.

const char *reference

URL pointing to the format definition/reference.

bool read

Is reading files in this format implemented?

bool write

Is writing files in this format implemented?

bool memory

Does this format support in-memory IO?

bool positions

Does this format support storing atomic positions?

bool velocities

Does this format support storing atomic velocities?

bool unit_cell

Does this format support storing unit cell information?

bool atoms

Does this format support storing atom names or types?

bool bonds

Does this format support storing bonds between atoms?

bool residues

Does this format support storing residues?

Warnings

The chemfiles library send warnings when it encounters malformed files, or any other condition that the user might want to know about. By default, these warnings are printed to the standard error stream. chfl_set_warning_callback() allow to redirect these warning by giving it a callback function to be called on each warning event.

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, "file at 'noformat' does not have an extension, provide a format name to read it") == 0);
    return 0;
}

Return

CHFL_SUCCESS

Configuration files

You can add more configuration file to chemfiles with chfl_add_configuration().

chfl_status chfl_add_configuration(const char *path)

Read configuration data from the file at path.

By default, chemfiles reads configuration from any file named .chemfiles.toml or chemfiles.toml in the current directory or any parent directory. This function can be used to add data from another configuration file.

This function will fail if there is no file at path, or if the file is incorrectly formatted. Data from the new configuration file will overwrite any existing data.

chfl_add_configuration("local-file.toml");

// reading a frame will now use atom names from the configuration
// ...

Return

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