Retrieves value of the nth link in a group, according to the order within an index


H5L_GET_VAL_BY_IDX ( loc_id, group_name, index_type, order, n, link_val, size, lapl_id )


<pre><code class="language-c">herr_t H5Lget_val_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_type, H5_iter_order_t order, hsize_t n, void *link_val, size_t size, hid_t lapl_id )</code></pre>

hid_t loc_idIN: Location identifier of subject group; may be a file, group, dataset, named datatype or attribute identifier
const char *group_name    IN: Name of subject group
H5_index_t index_typeIN: Type of index; valid values include: 
    NAME     Indexed by name 
    CORDER   Indexed by creation order
H5_iter_order_t orderIN: Order within field or index; valid values include: 
    H5_ITER_INC     Iterate in increasing order 
    H5_ITER_DEC     Iterate in decreasing order 
    H5_ITER_NATIVE  Iterate in fastest order
hsize_t nIN: Link for which to retrieve information
void *link_valOUT: Pointer to buffer in which link value is returned
size_t sizeIN: Size in bytes of link_val
hid_t lapl_idIN: Link access property list


H5L_GET_VAL_BY_IDX retrieves the value of the nth link in a group, according to the specified order, order, within an index, index.

  • For soft links, the value is the path name of the object pointed to.
  • For external links, this is a compound value containing file and path name information; to use this external link information, it must first be decoded with H5L_UNPACK_ELINK_VAL
  • For user-defined links, this value will be described in the definition of the user-defined link type.
  • This function will fail if called on a hard link.

loc_id specifies the location identifier of the group specified by group_name.

group_name specifies the group in which the link exists. If loc_id already specifies the group in which the link exists, group_name must be a dot (.).

The size in bytes of link_val is specified in size. The size value can be determined through a call to H5L_GET_INFO_BY_IDX1; it is returned in the val_size field of the H5L_info_t struct. If size is smaller than the size of the returned value, then the string stored in link_val will be truncated to size bytes. For soft links, this means that the value will not be null terminated.

If the type of the link is unknown or uncertain, H5L_GET_VAL_BY_IDX should be called only after the type has been determined via a call to H5L_GET_INFO_BY_IDX1.


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


Coming Soon!

Release    Change
1.8.0Function introduced in this release.