H5Pset_elink_cb
(
hid_t lapl_id
,
H5L_elink_traverse_t func
,
void *op_data
)
H5Pset_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.
H5Pset_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
H5Pset_elink_fapl
and the file access flag set by
H5Pset_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
H5Pset_elink_cb
and H5Pset_type_conv_cb
and functions such as H5Tconvert
and
H5Ewalk2
.
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.
H5Pset_fclose_degree
)
in this callback function or an associated property list will be ignored.
A file opened by means of traversing an external link
is always opened with the weak file close degree property setting,
H5F_CLOSE_WEAK
.
hid_t lapl_id
| IN: Link access property list identifier. | |
H5L_elink_traverse_t func
| IN: User-defined external link traversal callback function. | |
void *op_data
| IN: User-defined input data for the callback function. |
H5Pset_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.
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); ... }
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
Release | Change |
1.8.3 | C function introduced in this release. |