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:
             

Alphabetical Listing
             

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


Name: H5Iclear_type
Signature:
herr_t H5Iclear_type(H5I_type_t type, hbool_t force)
Purpose:
Deletes all IDs of the given type
Description:
H5Iclear_type deletes all IDs of the type identified by the argument type.

The type’s free function is first called on all of these IDs to free their memory, then they are removed from the type.

If the force flag is set to false, only those IDs whose reference counts are equal to 1 will be deleted, and all other IDs will be entirely unchanged. If the force flag is true, all IDs of this type will be deleted.

Parameters:
Returns:
Returns non-negative on success, negative on failure.
Fortran90 Interface:
This function is not supported in FORTRAN 90.

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:
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: H5Idec_type_ref
Signature:
int H5Idec_type_ref(H5I_type_t type)
Purpose:
Decrements the reference count on an ID type.
Description:
H5Idec_type_ref decrements the reference count on an ID type. The reference count is used by the library to indicate when an ID type can be destroyed. If the reference count reaches zero, this function will destroy it.

The type parameter is the identifier for the ID type whose reference count is to be decremented. This identifier must have been created by a call to H5Iregister_type.

Parameters:
Returns:
Returns the current reference count on success, negative on failure.
Fortran90 Interface:
This function is not supported in FORTRAN 90.

Name: H5Idestroy_type
Signature:
herr_t H5Idestroy_type(H5I_type_t type)
Purpose:
Removes the type type and all IDs within that type.
Description:
H5Idestroy_type deletes an entire ID type. All IDs of this type are destroyed and no new IDs of this type can be registered.

The type’s free function is called on all of the IDs which are deleted by this function, freeing their memory. In addition, all memory used by this type’s hash table is freed.

Since the H5I_type_t values of destroyed ID types are reused when new types are registered, it is a good idea to set the variable holding the value of the destroyed type to H5I_UNINIT.

Parameters:
Returns:
Returns non-negative on success, negative on failure.
Fortran90 Interface:
This function is not supported in FORTRAN 90.

Name: H5Iget_file_id
Signature:
hid_t H5Iget_file_id(hid_t obj_id)
Purpose:
Retrieves the ID of the file associated with the object referenced by obj_id.
Description:
H5Iget_file_id returns the ID of the file associated with the object referenced by obj_id. The retrieved file ID must be closed using H5Fclose.

Currently, obj_id can be the ID of one of the following objects: a file, a named datatype, a group, a dataset, or an attribute.

Parameters:
Returns:
Returns the file ID on success, negative on failure.
Fortran90 Interface:
This function is currently not supported in FORTRAN 90.

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:
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:
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:
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: H5Iget_type_ref
Signature:
int H5Iget_type_ref(H5I_type_t type)
Purpose:
Retrieves the reference count on an ID type.
Description:
H5Iget_type_ref retrieves the reference count on an ID type. The reference count is used by the library to indicate when an ID type can be destroyed.

The type parameter is the identifier for the ID type whose reference count is to be retrieved. This identifier must have been created by a call to H5Iregister_type.

Parameters:
Returns:
Returns the current reference count on success, negative on failure.
Fortran90 Interface:
This function is not supported in FORTRAN 90.

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

Name: H5Iinc_type_ref
Signature:
int H5Iinc_type_ref(H5I_type_t type)
Purpose:
Increments the reference count on an ID type.
Description:
H5Iinc_type_ref increments the reference count on an ID type. The reference count is used by the library to indicate when an ID type can be destroyed.

The type parameter is the identifier for the ID type whose reference count is to be incremented. This identifier must have been created by a call to H5Iregister_type.

Parameters:
Returns:
Returns the current reference count on success, negative on failure.
Fortran90 Interface:
This function is not supported in FORTRAN 90.

Name: H5Inmembers
Signature:
int H5Inmembers(H5I_type_t type)
Purpose:
Returns the number of IDs in a given type.
Description:
H5Inmembers returns the number of IDs of a given ID type. If no IDs of this type have been registered, H5Inmembers returns 0. If the type does not exist or has been destroyed, H5Inmembers also returns 0.
Parameters:
Returns:
Returns number of members on success, zero if type is not a valid ID type.
Fortran90 Interface:
This function is not supported in FORTRAN 90.

Name: H5Iobject_verify
Signature:
void * H5Iobject_verify(hid_t id, H5I_type_t id_type)
Purpose:
Returns the object referenced by id.
Description:
H5Iobject_verify returns a pointer to the memory referenced by id after verifying that id is of type id_type. This function is analogous to dereferencing a pointer in C with type checking.

H5Iregister(H5I_type_t type, void *object) takes an H5I_type_t and a void pointer to an object, returning an hid_t of that type. This hid_t can then be passed to H5Iobject_verify along with its type to retrieve the object.

H5Iobject_verify does not change the ID it is called on in any way (as opposed to H5Iremove_verify, which removes the ID from its type’s hash table).

Parameters:
Returns:
Pointer to the object referenced by id on success, NULL on failure.
Fortran90 Interface:
This function is not supported in FORTRAN 90.

Name: H5Iregister
Signature:
hid_t H5Iregister(H5I_type_t type, void *object)
Purpose:
Creates and returns a new ID.
Description:
H5Iregister allocates space for a new ID and returns an identifier for it.

The type parameter is the identifier for the ID type to which this new ID will belong. This identifier must have been created by a call to H5Iregister_type.

The object parameter is a pointer to the memory which the new ID will be a reference to. This pointer will be stored by the library and returned to you via a call to H5Iobject_verify.

Parameters:
Returns:
Returns the new ID on success, negative on failure.
Fortran90 Interface:
This function is not supported in FORTRAN 90.

Name: H5Iregister_type
Signature:
H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func)
Purpose:
Creates and returns a new ID type.
Description:
H5Iregister_type allocates space for a new ID type and returns an identifier for it.

The hash_size parameter indicates the minimum size of the hash table used to store IDs in the new type.

The reserved parameter indicates the number of IDs in this new type to be reserved. Reserved IDs are valid IDs which are not associated with any storage within the library.

The free_func parameter is a function pointer to a function which returns an herr_t and accepts a void *. The purpose of this function is to deallocate memory for a single ID. It will be called by H5Iclear_type and H5Idestroy_type on each ID. This function is NOT called by H5Iremove_verify. The void * will be the same pointer which was passed in to the H5Iregister function. The free_func function should return 0 on success and -1 on failure.

Parameters:
Returns:
Returns the type identifier on success, negative on failure.
Fortran90 Interface:
This function is not supported in FORTRAN 90.

Name: H5Iremove_verify
Signature:
void *H5Iremove_verify(hid_t id, H5I_type_t id_type)
Purpose:
Removes an ID from internal storage.
Description:
H5Iremove_verify first ensures that id belongs to id_type. If so, it removes id from internal storage and returns the pointer to the memory it referred to. This pointer is the same pointer that was placed in storage by H5Iregister. If id does not belong to id_type, then NULL is returned.

The id parameter is the ID which is to be removed from internal storage. Note: this function does NOT deallocate the memory that id refers to. The pointer returned by H5Iregister must be deallocated by the user to avoid memory leaks.

The type parameter is the identifier for the ID type which id is supposed to belong to. This identifier must have been created by a call to H5Iregister_type.

Parameters:
Returns:
Returns a pointer to the memory referred to by id on success, NULL on failure.
Fortran90 Interface:
This function is not supported in FORTRAN 90.

Name: H5Isearch
Signature:
void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key)
Purpose:
Finds the memory referred to by an ID within the given ID type such that some criterion is satisfied.
Description:
H5Isearch searches through a give ID type to find an object that satisfies the criteria defined by func. If such an object is found, the pointer to the memory containing this object is returned. Otherwise, NULL is returned. To do this, func is called on every member of type. The first member to satisfy func is returned.

The type parameter is the identifier for the ID type which is to be searched. This identifier must have been created by a call to H5Iregister_type.

The parameter func is a function pointer to a function which takes three parameters. The first parameter is a void *. It will be a pointer the object to be tested. This is the same object that was placed in storage using H5Iregister. The second parameter is a hid_t. It is the ID of the object to be tested. The last parameter is a void *. This is the key parameter and can be used however the user finds helpful. Or it can simply be ignored if it is not needed. func returns 0 if the object it is testing does not pass its criteria. A non-zero value should be returned if the object does pass its criteria.

The key parameter will be passed to the search function as a parameter. It can be used to further define the search at run-time.

Parameters:
Returns:
Returns a pointer to the object which satisfies the search function on success, NULL on failure.
Fortran90 Interface:
This function is not supported in FORTRAN 90.

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  

HDF Help Desk
Describes HDF5 Release 1.7, the unreleased development branch; working toward HDF5 Release 1.8.0