HDF5 documents and links Introduction to HDF5 HDF5 User Guide | And in this document, the HDF5 Reference Manual H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes

# H5I: Identifier Interface

## Identifier API Functions

These functions provides tools for working with object identifiers and object names.

The C Interface:

- H5Iinc_ref
- H5Iget_name

- H5Idec_ref
- H5Iget_type

- H5Iget_ref

Alphabetical Listing

- H5Idec_ref
- H5Iget_name

- H5Iget_ref
- H5Iget_type

- H5Iinc_ref

The FORTRAN90 Interfaces:
In general, each FORTRAN90 subroutine performs exactly the same task as the corresponding C function.

- h5iinc_ref_f
- h5iget_name_f

- h5idec_ref_f
- h5iget_type_f

- h5iget_ref_f

Name: H5Idec_ref
Signature:
  int `H5Idec_ref`(hid_t `obj_id`)
Purpose:
  Decrements the reference count for an object.
Description:
  `H5Idec_ref` decrements the reference count of the object identified by `obj_id`.

  The reference count for an object ID is attached to the information about an object in memory and has no relation to the number of links to an object on disk.

  The reference count for a newly created object will be 1. Reference counts for objects may be explicitly modified with this function or with `H5Iinc_ref`. When an object ID's reference count reaches zero, the object will be closed. Calling an object ID's 'close' function decrements the reference count for the ID which normally closes the object, but if the reference count for the ID has been incremented with `H5Iinc_ref`, the object will only be closed when the reference count reaches zero with further calls to this function or the object ID's 'close' function.

  If the object ID was created by a collective parallel call (such as `H5Dcreate`, `H5Gopen`, etc.), the reference count should be modified by all the processes which have copies of the ID. Generally this means that group, dataset, attribute, file and named datatype IDs should be modified by all the processes and that all other types of IDs are safe to modify by individual processes.

  This function is of particular value when an application is maintaining multiple copies of an object ID. The object ID can be incremented when a copy is made. Each copy of the ID can then be safely closed or decremented and the HDF5 object will be closed when the reference count for that that object drops to zero.

Parameters:

hid_t `obj_id`
  IN: Object identifier whose reference count will be modified.

Returns:
  Returns a non-negative reference count of the object ID after decrementing it if successful; otherwise a negative value is returned.
Fortran90 Interface: h5idec_ref_f

      SUBROUTINE h5idec_ref_f(obj_id, ref_count, hdferr)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: obj_id  !Object identifier
        INTEGER, INTENT(OUT) :: ref_count     !Reference count of object ID
        INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                              ! 0 on success, and -1 on failure
      END SUBROUTINE h5idec_ref_f

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 of the object name. That value can then be assigned to `size` for a second `H5Iget_name` call, which will retrieve the actual name.

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

  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.

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, 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

Name: H5Iget_ref
Signature:
  int `H5Iget_ref`(hid_t `obj_id`)
Purpose:
  Retrieves the reference count for an object.
Description:
  `H5Iget_ref` retrieves the reference count of the object identified by `obj_id`.

  The reference count for an object ID is attached to the information about an object in memory and has no relation to the number of links to an object on disk.

  This function can also be used to check if an object ID is still valid. A non-negative return value from this function indicates that the ID is still valid.

Parameters:

hid_t `obj_id`
  IN: Object identifier whose reference count will be retrieved.

Returns:
  Returns a non-negative current reference count of the object ID if successful; otherwise a negative value is returned.
Fortran90 Interface: h5iget_ref_f

      SUBROUTINE h5iget_ref_f(obj_id, ref_count, hdferr)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: obj_id  !Object identifier
        INTEGER, INTENT(OUT) :: ref_count     !Reference count of object ID
        INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                              ! 0 on success, and -1 on failure
      END SUBROUTINE h5iget_ref_f

Name: H5Iget_type
Signature:
  H5I_type_t `H5Iget_type`(hid_t `obj_id`)
Purpose:
  Retrieves the type of an object.
Description:
  `H5Iget_type` retrieves the type of the object identified by `obj_id`.

  Valid types returned by the function are

  `H5I_FILE` | File
  `H5I_GROUP` | Group
  `H5I_DATATYPE` | Datatype
  `H5I_DATASPACE` | Dataspace
  `H5I_DATASET` | Dataset
  `H5I_ATTR` | Attribute

  If no valid type can be determined or the identifier submitted is invalid, the function returns

  `H5I_BADID` | Invalid identifier

  This function is of particular value in determining the type of object closing function (`H5Dclose`, `H5Gclose`, etc.) to call after a call to `H5Rdereference`.

Parameters:

hid_t `obj_id`
  IN: Object identifier whose type is to be determined.

Returns:
  Returns the object type if successful; otherwise `H5I_BADID`.
Fortran90 Interface: h5iget_type_f

      SUBROUTINE h5iget_type_f(obj_id, type, hdferr)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: obj_id  !Object identifier
        INTEGER, INTENT(OUT) :: type          !type of an object.
                                              !possible values are:
                                              !H5I_FILE_F(1)
                                              !H5I_GROUP_F(2)
                                              !H5I_DATATYPE_F(3)
                                              !H5I_DATASPACE_F(4)
                                              !H5I_DATASET_F(5)
                                              !H5I_ATTR_F(6)
                                              !H5I_BADID_F(-1)
        INTEGER, INTENT(OUT) :: hdferr        ! E rror code
                                              ! 0 on success, and -1 on failure
      END SUBROUTINE h5iget_type_f

Name: H5Iinc_ref
Signature:
  int `H5Iinc_ref`(hid_t `obj_id`)
Purpose:
  Increments the reference count for an object.
Description:
  `H5Iinc_ref` increments the reference count of the object identified by `obj_id`.

  The reference count for an object ID is attached to the information about an object in memory and has no relation to the number of links to an object on disk.

  The reference count for a newly created object will be 1. Reference counts for objects may be explicitly modified with this function or with `H5Idec_ref`. When an object ID's reference count reaches zero, the object will be closed. Calling an object ID's 'close' function decrements the reference count for the ID which normally closes the object, but if the reference count for the ID has been incremented with this function, the object will only be closed when the reference count reaches zero with further calls to `H5Idec_ref` or the object ID's 'close' function.

  If the object ID was created by a collective parallel call (such as `H5Dcreate`, `H5Gopen`, etc.), the reference count should be modified by all the processes which have copies of the ID. Generally this means that group, dataset, attribute, file and named datatype IDs should be modified by all the processes and that all other types of IDs are safe to modify by individual processes.

  This function is of particular value when an application is maintaining multiple copies of an object ID. The object ID can be incremented when a copy is made. Each copy of the ID can then be safely closed or decremented and the HDF5 object will be closed when the reference count for that that object drops to zero.

Parameters:

hid_t `obj_id`
  IN: Object identifier whose reference count will be modified.

Returns:
  Returns a non-negative reference count of the object ID after incrementing it if successful; otherwise a negative value is returned.
Fortran90 Interface: h5iinc_ref_f

      SUBROUTINE h5iinc_ref_f(obj_id, ref_count, hdferr)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: obj_id  !Object identifier
        INTEGER, INTENT(OUT) :: ref_count     !Reference count of object ID
        INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                              ! 0 on success, and -1 on failure
      END SUBROUTINE h5iinc_ref_f

HDF5 documents and links Introduction to HDF5 HDF5 User Guide | And in this document, the HDF5 Reference Manual H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes