Retrieves value of the nth link in a group, according to the order within an index
Procedure:
H5L_GET_VAL_BY_IDX ( loc_id, group_name, index_type, order, n, link_val, size, lapl_id )
Signature:
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 )
Parameters:
hid_t loc_id | IN: 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_type | IN: Type of index; valid values include:
NAME Indexed by name
CORDER Indexed by creation order |
H5_iter_order_t order | IN: 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 n | IN: Link for which to retrieve information |
void *link_val | OUT: Pointer to buffer in which link value is returned |
size_t size | IN: Size in bytes of link_val |
hid_t lapl_id | IN: Link access property list |
Description:
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:
Returns a non-negative value if successful; otherwise returns a negative value.
Example:
History:
| Release | Change |
|---|
| 1.8.0 | Function introduced in this release. |
--- Last Modified: September 27, 2019 | 01:57 PM
