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:
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_CONFIGURATION_ERROR
= 5¶Status code for configuration files errors.
CHFL_OUT_OF_BOUNDS
= 6¶Status code for out of bounds errors.
CHFL_PROPERTY_ERROR
= 7¶Status code for errors related to properties.
CHFL_GENERIC_ERROR
= 254¶Status code for any other error from Chemfiles.
CHFL_CXX_ERROR
= 255¶Status code for error in the C++ standard library.
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);
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);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
. 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.
chfl_warning_callback
)(const char *message)¶Callback type that can be used to process warning events.
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;
}
CHFL_SUCCESS
You can add more configuration file to chemfiles with
chfl_add_configuration()
.
chfl_add_configuration
(const char *path)¶Read configuration data from the file at path
.
By default, chemfiles reads configuration from any file name .chemfilesrc
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 incorectly 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
// ...
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.