|
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 |
The C Interface:
H5Idec_ref(hid_t obj_id)
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.
obj_id
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
H5Iget_file_id(hid_t obj_id)
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.
hid_t obj_id |
IN: Identifier of the object whose associated file identifier will be returned. |
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
H5Iget_name(hid_t obj_id,
char *name,
size_t size
)
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.
obj_id
name
name buffer.
0 (zero) if no name is associated with the identifier.
Otherwise returns a negative value.
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
H5Iget_ref(hid_t obj_id)
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.
obj_id
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
H5Iget_type(hid_t obj_id)
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 |
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.
obj_id
H5I_BADID.
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
H5Iinc_ref(hid_t obj_id)
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.
obj_id
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 |