|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5DS H5IM H5LT H5PT H5TB H5 H5A H5D H5E H5F H5G H5I H5L H5O H5P H5R H5S H5T H5Z Tools Datatypes Fortran Compatibility Macros |
The C Interface:
H5Iclear_type(
H5I_type_t type,
hbool_t force
)
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.
H5I_type_t type |
IN: Identifier of ID type which is to be cleared of IDs |
hbool_t force |
IN: Whether or not to force deletion of all IDs |
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.
hid_t obj_id |
IN: Object identifier whose reference count will be modified. |
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
| Release | C |
| 1.6.2 |
Function introduced in this release. Fortran subroutine introduced in this release. |
H5Idec_type_ref(
H5I_type_t type
)
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.
H5I_type_t type |
IN: The identifier of the type whose reference count is to be decremented |
H5Idestroy_type(
H5I_type_t type
)
type and all IDs within that type.
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.
H5I_type_t type |
IN: Identifier of ID type which is to be destroyed |
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
| Release | C |
| 1.6.3 |
Function introduced in this release. Fortran subroutine introduced in this release. |
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 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).
Note that an object in an HDF5 file may have multiple paths if there
are multiple links pointing to it. This function may return any one
of these paths.
When possible, H5Iget_name returns the path with
which the object was opened.
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. |
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
| Release | C |
| 1.6.0 | Function introduced in this release. |
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.
hid_t obj_id |
IN: Object identifier whose reference count will be retrieved. |
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
| Release | C |
| 1.6.2 |
Function introduced in this release. Fortran subroutine introduced in this release. |
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.
hid_t obj_id |
IN: Object identifier whose type is to be determined. |
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
H5Iget_type_ref(
H5I_type_t type
)
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.
H5I_type_t type |
IN: The identifier of the type whose reference count is to be retrieved |
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.
hid_t obj_id |
IN: Object identifier whose reference count will be modified. |
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
| Release | C |
| 1.6.2 |
Function introduced in this release. Fortran subroutine introduced in this release. |
H5Iinc_type_ref(
H5I_type_t type
)
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.
H5I_type_t type |
IN: The identifier of the type whose reference count is to be incremented |
H5Inmembers(
H5I_type_t type,
hsize_t *num_members
)
H5Inmembers returns the number of identifiers of
the identifier type specified in type.
The number of identifiers is returned in num_members.
If no identifiers of this type have been registered,
the type does not exist, or it has been destroyed,
num_members is returned with the value 0.
H5I_type_t type |
IN: Identifier for the identifier type whose member count will be retrieved |
hsize_t *num_members |
OUT: Number of identifiers of the specified identifier type. |
H5Iobject_verify(
hid_t id,
H5I_type_t id_type
)
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).
hid_t id |
IN: ID to be dereferenced |
H5I_type_t type |
IN: ID type to which id should belong |
NULL on failure.
H5Iregister(
H5I_type_t type,
void *object
)
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.
H5I_type_t type |
IN: The identifier of the type to which the new ID will belong |
void *object |
IN: Pointer to memory for the library to store |
H5Iregister_type(
size_t hash_size,
unsigned reserved,
H5I_free_t free_func
)
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.
size_t hash_size |
IN: Size of the hash table (in entries) used to store IDs for the new type |
unsigned reserved |
IN: Number of reserved IDs for the new type |
H5I_free_t free_func |
IN: Function used to deallocate space for a single ID |
H5Iremove_verify(
hid_t id,
H5I_type_t id_type
)
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.
hid_t id |
IN: The ID to be removed from internal storage |
H5I_type_t type |
IN: The identifier of the type whose reference count is to be retrieved |
id
on success, NULL on failure.
H5Isearch(
H5I_type_t type,
H5I_search_func_t func,
void *key
)
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.
H5I_type_t type |
IN: The identifier of the type to be searched |
H5I_search_func_t func |
IN: The function defining the search criteria |
void *key |
IN: A key for the search function |
NULL on failure.
H5Itype_exists(
H5I_type_t type
)
H5Itype_exists determines whether the given
identifier type, type, is registered with the library.
H5I_type_t type |
IN: Identifier type. |
1 if the type is registered and
0 if not.
Returns a negative value on failure.
| Release | C |
| 1.8.0 | Function introduced in this release. |
|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5DS H5IM H5LT H5PT H5TB H5 H5A H5D H5E H5F H5G H5I H5L H5O H5P H5R H5S H5T H5Z Tools Datatypes Fortran Compatibility Macros |
