Last modified: 26 September 2014
Name: H5Literate
Signature:
  herr_t `H5Literate`( hid_t `group_id`, H5_index_t `index_type`, H5_iter_order_t `order`, hsize_t *`idx`, H5L_iterate_t `op`, void *`op_data` )

Purpose:
  Iterates through links in a group.

Description:
  `H5Literate` iterates through the links in a group, specified by `group_id`, in the order of the specified index, `index_type`, using a user-defined callback routine `op`. `H5Literate` does not recursively follow links into subgroups of the specified group.

  Three parameters are used to manage progress of the iteration: `index_type`, `order`, and `idx`.

  `index_type` specifies the index to be used. If the links have not been indexed by the index type, they will first be sorted by that index then the iteration will begin; if the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly. Valid values include the following:

  | `H5_INDEX_NAME` | Alpha-numeric index on name
  | `H5_INDEX_CRT_ORDER` | Index on creation order

  `order` specifies the order in which objects are to be inspected along the index specified in `index_type`. Valid values include the following:

  | `H5_ITER_INC` | Increasing order
  | `H5_ITER_DEC` | Decreasing order
  | `H5_ITER_NATIVE` | Fastest available order

  `idx` allows an interrupted iteration to be resumed; it is passed in by the application with a starting point and returned by the library with the point at which the iteration stopped.

  The `op` callback function, the related H5L_info_t struct, and the effect of the callback function’s return value on the application are described in `H5Lvisit`.

  `op_data` is a user-defined pointer to the data required to process links in the course of the iteration. This pointer is passed back to each step of the iteration in the `op` callback function’s `op_data` parameter.

  As mentioned above, `H5Literate` is not recursive. In particular, if a member of `group_id` is found to be a group, call it `subgroup_a`, `H5Literate` does not examine the members of `subgroup_a`. When recursive iteration is required, the application can do either of the following:

  - Use one of the following recursive routines instead of `H5Literate`:
    `H5Lvisit`
    `H5Lvisit_by_name`
    `H5Ovisit`
    `H5Ovisit_by_name`
  - Handle the recursion manually, explicitly calling `H5Literate` on discovered subgroups.

  `H5Literate` assumes that the membership of the group being iterated over remains unchanged through the iteration; if any of the links in the group change during the iteration, the function’s behavior is undefined. Note, however, that objects pointed to by the links can be modified.

  `H5Literate` is the same as deprecated function `H5Giterate`, except that `H5Giterate` always proceeded in alphanumeric order.

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.

Parameters:

  hid_t `group_id` | IN: Identifier specifying subject group
  H5_index_t `index_type` | IN: Type of index which determines the order
  H5_iter_order_t `order` | IN: Order within index
  hsize_t *`idx` | IN: Iteration position at which to start OUT: Position at which an interrupted iteration may be restarted
  H5L_iterate_t `op` | IN: Callback function passing data regarding the link to the calling application
  void *`op_data` | IN: User-defined pointer to data required by the application for its processing of the link

Returns:
  On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.

  On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

Fortran2003 Interface: h5literate_f
Programming Note for Fortran Developers:

  The integer type of the callback function must match the C integer type. Therefore, for portability, all Fortran callback functions used by `h5literate_f` should be declared as `INTEGER(KIND=C_INT)`.

History:

  Release | Change
  1.8.8 | Fortran subroutine added.
  1.8.0 | C function introduced.