Last modified: 11 August 2009
Name: H5L_elink_traverse_t
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 )

Purpose:
Sets the access flags and file access property list used to open the specified external link target.

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

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.

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;
}

See Also:
H5Pset_elink_cb,   H5Pget_elink_cb

H5Pset_elink_fapl,   H5Pset_elink_acc_flags,   H5Lcreate_external

H5Fopen for discussion of H5F_ACC_RDWR and H5F_ACC_RDONLY file access flags

History:
Release     Change
1.8.3 C function type introduced in this release.