- - Quick Links - - HDF5 HDF4 Tools Projects Downloads Documentation Publications Contact Us

• LINKS
• Main Website
• What is HDF5?
• Online Brochure
• Downloads
• Documentation
• Software using HDF5
• HDF5 Users
• Sample HDF5 Files
• Acknowledgments
• Licenses

This web site is no longer maintained (but will remain online).
Please see The HDF Group's new Support Portal for the latest information.

HDF5 Tutorial:   Learning The Basics
Discovering the Contents of an HDF5 File

Contents:

• Discovering what is in an HDF5 file

• Programming Example (C, Fortran, Java):

  • Using H5Literate, H5Lvisit, and H5Ovisit
  • Using the H5G API

---

Discovering what is in an HDF5 file

Until now, three ways have been mentioned that can be used to read an existing HDF5 file:

• The HDF-Java browser, HDFView, can be used to open and browse an HDF5 file.
• The h5dump utility can be used to display the contents of an HDF5 file.
• From an application, the H5Dopen function can open a specified dataset, which can then be read using H5Dread.

HDFView and h5dump are standalone tools which cannot be called within an application, and using H5Dopen and H5Dread require that you know the name of the HDF5 dataset. How would an application that has no prior knowledge of an HDF5 file, be able to determine or discover the contents of it, much like HDFView and h5dump?

The answer is that there are ways to discover the contents of an HDF5 file, by using the H5G, H5L and H5O APIs:

• The H5G interface (covered earlier) consists of routines for working with groups. A group is a structure that can be used to organize zero or more HDF5 objects, not unlike a Unix directory.

• The H5L interface consists of link routines. A link is a path between groups. The H5L interface allows objects to be accessed by use of these links.

• The H5O interface consists of routines for working with objects. Datasets, groups, and committed datatypes are all objects in HDF5.

Using just the H5G interface, you can drill your way down, starting from the root group, opening groups and objects until you reach all objects. Functions that enable this are:

• H5Gget_num_objs
• H5Gget_objname_by_idx
• H5Gget_objtype_by_idx

There are also specific H5O and H5L interface routines that simplify the process:

• H5Literate traverses the links in a specified group, in the order of the specified index, using a user-defined callback routine. (A callback function is one that will be called when a certain condition is met, at a certain point in the future.)

• H5Ovisit / H5Lvisit recursively visit all objects/links accessible from a specified object/group.

Programming Examples

Using H5Literate, H5Lvisit and H5Ovisit:

Under HDF5 Examples you will find Examples by API, where examples of using H5Literate and H5Ovisit/H5Lvisit are included.

The h5ex_g_traverse example traverses a file using H5Literate:

[ C Example ] -- h5ex_g_traverse.c
[ Fortran Example ] -- h5ex_g_traverse_F03.f90

The h5ex_g_visit example traverses a file using H5Ovisit and H5Lvisit:

[ C Example ] -- h5ex_g_visit.c
[ Fortran Example ] -- h5ex_g_visit_F03.f90

Using the H5G API:

To use the H5G interface exclusively you would begin with the root group, open it, get the number of objects (NumObj) in the group (see H5Gget_num_objs), and then loop through all of the objects in the group (from 0 to (NumObj - 1)), accessing each by index (see H5Gget_objname_by_idx and H5Gget_objtype_by_idx). If an object is another group, you would then open that group and repeat the process until all objects have been accessed.

The example below gives an idea of what could be done. Simply pass in the name of the HDF5 file as a parameter to this program:

[ C Example ] -- h5getinfo.c
(not tested)

---

- - Last modified: 21 December 2016