Retrieves a name of an object based on the object identifier
Procedure:
H5I_GET_NAME(obj_id, name, size)
Signature:
ssize_t H5Iget_name( hid_t obj_id, char *name, size_t size )
SUBROUTINE h5iget_name_f(obj_id, buf, buf_size, name_size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier
CHARACTER(LEN=*), INTENT(OUT) :: buf ! Buffer to hold object name
INTEGER(SIZE_T), INTENT(IN) :: buf_size ! Buffer size
INTEGER(SIZE_T), INTENT(OUT) :: name_size ! Name size
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success, and -1 on failure
END SUBROUTINE h5iget_name_f
Parameters:
hid_t obj_id | IN: Identifier of the object This identifier can refer to a file, group, dataset, named datatype or attribute. |
char *name | OUT: A name associated with the identifier |
size_t size | IN: The size of the name buffer; must be the size of the name in bytes plus 1 for a NULL terminator |
Description:
H5I_GET_NAME retrieves a name for the object identified by obj_id.
Up to size characters of the name are returned in name; additional characters, if any, are not returned to the user application.
If the length of the name, which determines the required value of size, is unknown, a preliminary H5I_GET_NAME call can be made. The return value of this call will be the size in bytes of the object name. That value, plus 1 for a NULL terminator, is then assigned to size for a second H5I_GET_NAME call, which will retrieve the actual name.
If the object identified by obj_id is an attribute, as determined via H5I_GET_TYPE, H5I_GET_NAME retrieves the name of the object to which that attribute is attached. To retrieve the name of the attribute itself, use H5A_GET_NAME.
If there is no name associated with the object identifier or if the name is NULL, H5I_GET_NAME returns 0 (zero).
Note that an object in an HDF5 file may have multiple paths if there are multiple links pointing to it. This function may return any one of these paths. When possible, H5I_GET_NAME returns the path with which the object was opened.
Returns:
Returns the length of the name if successful, returning 0 (zero) if no name is associated with the identifier. Otherwise returns a negative value.
Example:
History:
| Release | Change |
|---|
| 1.6.0 | Function introduced in this release. |
--- Last Modified: April 25, 2019 | 12:04 PM
