H5P_SET_ELINK_CB is used to specify a callback function that is executed by the HDF5 library when traversing an external link. This provides a mechanism to set specific access permissions, modify the file access property list, modify the parent or target file, or take any other user-defined action. This callback function is used in situations where the HDF5 library's default behavior is not suitable.

H5P_SET_ELINK_CB sets a user-defined external link traversal callback function in the link access property list lapl_id. The callback function func must conform to the prototype specified in H5L_elink_traverse_t.

The callback function may adjust the file access property list and file access flags to use when opening a file through an external link. The callback will be executed by the HDF5 library immediately before opening the target file.

The callback will be made after the file access property list set by H5P_SET_ELINK_FAPL and the file access flag set by H5P_SET_ELINK_ACC_FLAGS are applied, so changes made by this callback function will take precedence.

If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.

Examples of this kind of routine include callbacks such as H5P_SET_ELINK_CB and H5P_SET_TYPE_CONV_CB and functions such as H5T_CONVERT and H5E_WALK2.

Exiting the routine in its normal fashion allows the HDF5 C library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.

Returns a non-negative value if successful; otherwise returns a negative value.

H5P_SET_ELINK_CB will fail if the link access property list identifier, lapl_id, is invalid or if the function pointer, func, is NULL.

An invalid function pointer, func, will cause a segmentation fault or other failure when an attempt is subsequently made to traverse an external link.

This example defines a callback function that prints the name of the target file every time an external link is followed, and sets this callback function on lapl_id.

herr_t elink_callback(const char *parent_file_name, const char
        *parent_group_name, const char *child_file_name, const char
        *child_object_name, unsigned *acc_flags, hid_t fapl_id, void *op_data) {
    puts(child_file_name);
    return 0;
}

int main(void) {
    hid_t lapl_id = H5Pcreate(H5P_LINK_ACCESS);
    H5Pset_elink_cb(lapl_id, elink_callback, NULL);
    ...
}