H5I: Identifier Interface

Identifier API Functions

The C Interface:

H5Iget_name H5Iget_type

H5Iget_file_id H5Iget_ref

H5Iinc_ref H5Idec_ref

Alphabetical Listing

H5Idec_ref H5Iget_file_id

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.

h5iget_name_f h5iget_type_f

H5Iget_file_id h5iget_ref_f

h5iinc_ref_f h5idec_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
	

History:

Release	C		Fortran90
1.6.2	Function introduced in this release.		Fortran subroutine introduced in this release.

Name: H5Iget_file_id

Signature:

hid_t H5Iget_file_id(hid_t obj_id)

Purpose:

Retrieves an identifier for the file containing the specified object.

Description:

H5Iget_file_id returns the identifier of the file associated with the object referenced by obj_id.

obj_id can be a file, group, dataset, named datatype, or attribute identifier.

Note that the HDF5 Library permits an application to close a file while objects within the file remain open. If the file containing the object obj_id is still open, H5Iget_file_id will retrieve the existing file identifier. If there is no existing file identifier for the file, i.e., the file has been closed, H5Iget_file_id will reopen the file and return a new file identifier. In either case, the file identifier must eventually be released using H5Fclose.

Parameters:

hid_t obj_id

IN: Identifier of the object whose associated file identifier will be returned.

Returns:

Returns a file identifier on success, negative on failure.

Fortran90 Interface:

SUBROUTINE h5iget_file_id_f(obj_id, file_id, hdferr) 

  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN)  :: obj_id     ! Object identifier 
  INTEGER(HID_T), INTENT(OUT) :: file_id    ! File identifier
  INTEGER, INTENT(OUT) :: hdferr            ! Error code

END SUBROUTINE h5iget_file_id_f
    

History:

Release	C		Fortran90
1.6.3	Function introduced in this release.		Fortran subroutine introduced in this release.

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.

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
	

History:

Release	C		Fortran90
1.6.2	Function introduced in this release.		Fortran subroutine introduced in this release.

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
                                        !H5I_GROUP_F
                                        !H5I_DATATYPE_F
                                        !H5I_DATASPACE_F
                                        !H5I_DATASET_F
                                        !H5I_ATTR_F
                                        !H5I_BADID_F
  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
	

History:

Release	C		Fortran90
1.6.2	Function introduced in this release.		Fortran subroutine introduced in this release.

The HDF Group Help Desk:
Describes HDF5 Release 1.6.10, November 2009