<span class="confluence-anchor-link" id="summary"></span>

Iterates through links in a group

<span class="confluence-anchor-link" id="procedure"></span>
Procedure:

H5L_ITERATE(group, index_type, order, position, op, ctx)

<span class="confluence-anchor-link" id="signature"></span>
Signature:

<pre><code class="language-c">herr_t H5Literate
(
  hid_t           group,
  H5_index_t      index_type,
  H5_iter_order_t order,
  hsize_t*        position,
  H5L_iterate_t   op,
  void*           ctx
)</code></pre>

<pre><code class="language-fortran">SUBROUTINE h5literate_f(group,index_type, order, position,
           op, ctx, return_value, hdferr)
    INTEGER(HID_T) , INTENT(IN) :: group
    INTEGER , INTENT(IN) :: index_type
    INTEGER , INTENT(IN) :: order
    INTEGER(HSIZE_T), INTENT(INOUT) :: position
    TYPE(C_FUNPTR) , INTENT(IN) :: op
    TYPE(C_PTR) , INTENT(IN) :: ctx
    INTEGER , INTENT(OUT) :: return_value
    INTEGER , INTENT(OUT) :: hdferr</code></pre>
<span class="confluence-anchor-link" id="parameters"></span>
Parameters:
NameModeKindDescription
groupINhandleFile or group identifier
index_typeINchoiceIndex for iteration order
orderINchoiceTraversal order
positionINOUTintegerIteration position
opINdelegateUser-defined operator
ctxINOUTopaqueUser-supplied context
<span class="confluence-anchor-link" id="description"></span>
Description:

H5L_ITERATE iterates through the links in a group, group, in the order of the specified index, index_type, using a user-defined callback routine op.H5L_ITERATE 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 position.

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.

The choices for index_type are:

NameMeaning
H5_INDEX_NAMELexicographic order
H5_INDEX_CRT_ORDERCreation order

order specifies the order in which objects are to be inspected along the index index_type. The choices for order are:

Name

Meaning

H5_ITER_INCIncreasing order
H5_ITER_DECDecreasing order
H5_ITER_NATIVEFastest order

position tracks the iteration and allows an iteration to be resumed if it was stopped before all members were processed. 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 H5L_VISIT.

ctx 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 ctx parameter.

op is invoked for each link encounter:

Signature:
<pre><code class="language-c">herr_t (*H5L_iterate_t)
(
  hid_t              group,
  const char*        name,
  const H5L_info_t*  info,
  void*              ctx
)</code>
</pre>
Info:
<pre><code class="language-c">typedef struct {
    H5L_type_t     type;         /* Type of link                   */
    hbool_t        corder_valid; /* Indicates whether creation     */
                                 /* order is valid                 */
    int64_t        corder;       /* Creation order                 */
    H5T_cset_t     cset;         /* Character set of link name     */
    union {
        haddr_t    address;      /* Address hard link points to    */
        size_t     val_size;     /* Size of soft link or           */
                                 /* user-defined link value        */
    } u;
} H5L_info_t;</code></pre>
Returns:
Return valueMeaning
0Continue iteration
> 0Stop iteration; successful termination
< 0Stop iteration; abnormal termination

ctx is passed to and from each iteration and can be used to supply or aggregate information across iterations.

The behavior of H5L_ITERATE is undefined if the link membership of group changes during the iteration. This does not limit the ability to change link destinations while iterating, but caution is advised.

For recursive behavior, see the following:

H5L_VISIT

H5L_VISIT_BY_NAME

H5O_VISIT

H5O_VISIT_BY_NAME

<span class="confluence-anchor-link" id="returns"></span>
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. 

<span class="confluence-anchor-link" id="example"></span>
Example:

<span class="confluence-anchor-link" id="history"></span>
History:
ReleaseChange
1.8.8Fortran subroutine added.
1.8.0C function introduced.