- Created by Barbara Jones, last modified on Jul 28, 2020
H5L_elink_traverse_t
Sets the access flags and file access property list used to open the specified external link target
Signature:
typedef herr_t (*H5L_elink_traverse_t)(
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
)
Parameters:
const char *parent_file_name | IN: Name of the file containing the external link |
const char *parent_group_name | IN: Name of the group containing the exernal link |
const char *child_file_name | IN: Name of the external link target file |
const char *child_object_name | IN: Name of the external link target object |
unsigned *acc_flags | IN/OUT: File access flags used to open the target file. This should be set to either H5F_ACC_RDWR or H5F_ACC_RDONLY. The initial value of this field will be the flags that would otherwise be used to open the target file as inherited from the parent file or as overridden with H5Pset_elink_acc_flags. After making the callback, the flags returned in this parameter will always be used to open the target file. |
hid_t fapl_id | IN/OUT: Identifier of the file access property list used to open the target file. This will initially be a copy of the property list that would otherwise be used to open the target file, as inherited from the parent file or as overridden with H5Pset_elink_fapl. After making the callback, this property list, including any changes made by the callback function, will always be used to open the target file. |
void *op_data | IN/OUT: Pointer to user-defined input data. This is a pass-through of the data that was passed to H5Pset_elink_cb. |
Motivation:
H5L_elink_traverse_t defines the prototype for a user-defined callback function to be called when traversing an external link. This callback will be executed by the HDF5 Library immediately before opening the target file and 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.
Description:
H5L_elink_traverse_t defines a callback function which may adjust the file access property list and file access flag to use when opening a file through an external link.
The callback is set with H5P_SET_ELINK_CB but will be executed by the HDF5 Library immediately before opening the target file via an external link.
The callback function should return 0 if there are no issues and a negative value in case of an error. If the callback function returns a negative value, the external link will not be traversed and an error will be returned.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Failure Modes:
H5L_elink_traverse_t failure modes are dependent on the implementation of the callback function.
Example Usage:
This example defines a callback function that prints the name of the target file every time an external link is followed.
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;
}
History:
| Release | Change |
|---|---|
| 1.8.3 | C function type introduced in this release. |
--- Last Modified: July 28, 2020 | 10:43 AM