Last modified: 18 June 2013
Name: H5Pset_elink_cb
Signature:
  herr_t `H5Pset_elink_cb`( hid_t `lapl_id`, H5L_elink_traverse_t `func`, void *`op_data` )

Purpose:
  Sets the external link traversal callback function in a link access property list.

Motivation:
  `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.

Description:
  `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.

Programming Note for C++ Developers Using C Functions:

  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.

Note:
  A file close degree property setting (`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`.

Parameters:

  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.

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

Failure Modes:
  `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.

Example Usage:
  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);
          ...
      }

See Also:
  `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

  `H5L_elink_traverse_t`

History:

  Release | Change
  1.8.3 | C function introduced in this release.