Last modified: 11 August 2009

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.