Name: H5Iget_name
Signature:
  ssize_t `H5Iget_name`( hid_t `obj_id`, char *`name`, size_t `size` )
Purpose:
  Retrieves a name of an object based on the object identifier.
Description:
  `H5Iget_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 `H5Iget_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 `H5Iget_name` call, which will retrieve the actual name.

  If the object identified by `obj_id` is an attribute, as determined via `H5Iget_type`, `H5Iget_name` retrieves the name of the object to which that attribute is attached. To retrieve the name of the attribute itself, use `H5Aget_name`.

  If there is no name associated with the object identifier or if the name is `NULL`, `H5Iget_name` returns `0` (zero).

  `H5Iget_name` cannot be used with an object identifier returned by `H5Rdereference`; the function will not be able to determine a valid object name.

  Note that an object in an HDF5 file may have multiple names, varying according to the path through the HDF5 group hierarchy used to reach that object.

Parameters:

hid_t `obj_id` | IN: Identifier of the object. This identifier can refer to a group, dataset, or named datatype.
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.

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.
Fortran90 Interface: h5iget_name_f

      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

History:

Release | C
1.6.0 | Function introduced in this release.