Return to the "Advanced Topics" page.
The purpose of this topic is to describe how identifiers behave and how they should be treated by application programs.
When an application program uses the HDF5 library to create or open an item, a unique identifier is returned. The items that return a unique identifier when they are created or opened include the following: dataset, group, datatype, dataspace, file, attribute, property list, referenced object, error stack, and error message.
An application may open one of the items listed above more than once at the same time. For example, an application might open a group twice, receiving two identifiers. Information from one dataset in the group could be handled through one identifier, and the information from another dataset in the group is handled by a different identifier.
An application program should track every identifier it receives
as a result of creating or opening one of the items listed above. In
order for an application to close properly, it must release every
identifier it has opened. If an application opened a group twice for
example, it would need to issue two H5Gclose commands,
one for each identifier. Not releasing identifiers causes resource
leaks. Until an identifier is released, the item associated with
the identifier is still open.
The library considers a file open until all of the identifiers
associated with the file and with the file�s various items have been
released. The identifiers associated with these open items must be
released separately. This means that an application can close a file
and still work with one or more portions of the file. Suppose an
application opened a file, a group within the file, and two datasets
within the group. If the application closed the file with
H5Fclose,
then the file would be considered closed to the application, but the
group and two datasets would still be open.
There are several exceptions to the above file closing rule. One
is when the H5close function is used instead of H5Fclose.
H5close
causes a general shutdown of the library: all data is written to disk,
all identifiers are closed, and all memory used by the library is
cleaned up. Another exception occurs on parallel processing systems.
Suppose on a parallel system an application has opened a file, a group
in the file, and two datasets in the group. If the application uses
the H5Fclose function to close the file, the call will fail with an
error. The open group and datasets must be closed before the file can
be closed. A third exception is when the file access property list
includes the property H5F_CLOSE_STRONG. This property causes the closing
of all of the file�s open items when the file is closed with H5Fclose.
For more information about H5close, H5Fclose,
and H5Pset_fclose_degree,
see the
HDF5 Reference Manual
Some of the functions that return identifiers are listed below.
H5AcreateH5Acreate_by_nameH5Aget_typeH5AopenH5Aopen_by_idxH5Aopen_by_nameH5DcreateH5Dcreate_anonH5Dget_access_plistH5Dget_create_plistH5Dget_spaceH5Dget_typeH5DopenH5Ecreate_msgH5Ecreate_stackH5FcreateH5FopenH5FreopenH5GcreateH5Gcreate_anonH5GopenH5OopenH5Oopen_by_addrH5Oopen_by_idxH5PcreateH5RdereferenceH5Rget_regionH5ScreateH5Screate_simpleH5TcopyH5TcreateH5TdecodeH5Tget_member_typeH5Tget_superH5TopenReturn to the "Advanced Topics" page.
