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.