The HDF5 Object Interface

Introduction

The HDF5 Object interface (H5O) provides functions for managing HDF5 objects at a generic level. While specific object types (groups, datasets, datatypes) have their own interfaces (Groups (H5G), Datasets (H5D), Datatypes (H5T)), the H5O interface enables operations that apply to all object types uniformly.

See also: Objects (H5O) Reference Manual

Object Operations

The H5O interface provides several categories of operations:

Object Information: Retrieve metadata about objects using H5Oget_info, H5Oget_info_by_name, H5Oget_info_by_idx, and H5Oget_native_info. These functions return information such as reference counts, modification times, and storage details.

Object Copying: Copy objects between locations or files using H5Ocopy. This creates a complete copy of the source object including all its attributes and, for groups, can optionally copy contained objects recursively.

Object Opening: Open objects by address or index using H5Oopen, H5Oopen_by_idx, or H5Oopen_by_token. This enables access to objects when the specific type is unknown.

Object Linking: Create links to objects using H5Olink, enabling multiple names to reference the same object.

Object Traversal

The H5O interface provides powerful traversal capabilities:

H5Ovisit recursively visits all objects in a group hierarchy
H5Ovisit_by_name performs recursive visitation starting from a named location

These functions invoke a user-supplied callback for each object encountered, enabling custom processing, cataloging, or analysis of file contents.

Object Comments

Objects can have associated comment strings for documentation purposes:

H5Oset_comment and H5Oset_comment_by_name attach comments to objects
H5Oget_comment and H5Oget_comment_by_name retrieve object comments

Reference Counting

HDF5 uses reference counting to manage object lifetimes. The library automatically deletes objects when their reference count reaches zero:

H5Oincr_refcount manually increments an object's reference count
H5Odecr_refcount manually decrements an object's reference count

Attention: Manual manipulation of reference counts should be used with extreme caution. Improper use can lead to memory leaks or premature object deletion.

Cache Control

For performance optimization, the H5O interface provides cache management functions:

H5Orefresh reloads object metadata from disk, discarding cached data
H5Oflush writes object metadata to disk immediately

These functions are particularly useful in SWMR (Single Writer Multiple Reader) scenarios.

Summary

The H5O interface provides essential generic object operations:

Query object metadata and properties across all object types
Copy objects within and between HDF5 files
Traverse object hierarchies with custom processing
Manage object comments for documentation
Control object caching and persistence

Navigate back: Main / HDF5 User Guide