Returns a name of an object specified by an index
Procedure:
H5G_GET_OBJNAME_BY_IDX(loc_id, idx, name, size)
Signature:
ssize_t H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char *name, size_t size )
Parameters:
hid_t loc_id | IN: Group or file identifier |
hsize_t idx | IN: Transient index identifying object |
char *name | IN/OUT: Pointer to user-provided buffer the object name |
size_t size | IN: Name length |
Description:
H5G_GET_OBJNAME_BY_IDX returns a name of the object specified by the index idx in the group loc_id.
The group is specified by a group identifier loc_id. If preferred, a file identifier may be passed in loc_id; that file's root group will be assumed.
idx is the transient index used to iterate through the objects in the group. The value of idx is any nonnegative number less than the total number of objects in the group, which is returned by the function H5G_GET_NUM_OBJS. Note that this is a transient index; an object may have a different index each time a group is opened.
The object name is returned in the user-specified buffer name.
If the size of the provided buffer name is less or equal the actual object name length, the object name is truncated to max_size - 1 characters.
Note that if the size of the object's name is unkown, a preliminary call to H5G_GET_OBJNAME_BY_IDX with name set to NULL will return the length of the object's name. A second call to H5G_GET_OBJNAME_BY_IDX can then be used to retrieve the actual name.
Returns:
Returns the size of the object name if successful, or 0 if no name is associated with the group identifier. Otherwise returns a negative value.
Example:
History:
| Release | Change |
|---|
| 1.6.0 | Function introduced in this release. |
| 1.8.0 | Function deprecated in this release. |
--- Last Modified: April 25, 2019 | 11:25 AM
