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

Iterates through links in a group

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

H5L_ITERATE1 ( group_id, idx_type, order, idx_p, op, op_data )

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

<pre><code class="language-c">herr_t H5Literate1 ( hid_t group_id, H5_index_t idx_type, H5_iter_order_t order,
    hsize_t *idx_p, H5L_iterate1_t op, void *op_data )

<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
    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>
group_idINhandleFile or group identifier
idx_typeINchoiceIndex for iteration order
orderINchoiceTraversal order
idx_pINOUTintegerIteration position
opINdelegateUser-defined operator
op_dataINOUTopaqueUser-supplied context
<span class="confluence-anchor-link" id="description"></span>

H5L_ITERATE1 iterates through the links in a file or group, group_id, in the order of the specified index, idx_type, using a user-defined callback routine op.H5L_ITERATE1 does not recursively follow links into subgroups of the specified group.

Three parameters are used to manage progress of the iteration: idx_type, order, and idx_p.

idx_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 idx_type are:

H5_INDEX_NAMELexicographic order
H5_INDEX_CRT_ORDERCreation order

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



H5_ITER_INCIncreasing order
H5_ITER_DECDecreasing order
H5_ITER_NATIVEFastest order

idx_p 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_info1_t struct, and the effect of the callback function’s return value on the application are described in H5L_VISIT.

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.

op is invoked for each link encounter:

<pre><code class="language-c">herr_t (*H5L_iterate_t)
  hid_t              group,
  const char*        name,
  const H5L_info_t*  info,
  void*              ctx
<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>
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:





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

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>

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