The HDF5 Link Interface

Introduction

The HDF5 Link interface (H5L) provides functions for creating, querying, and manipulating links between objects in an HDF5 file. Links are the primary mechanism for organizing objects in the HDF5 file hierarchy and enabling navigation between related data.

Link Types

HDF5 supports three types of links:

Hard Links: Direct references to objects within the same file. An object exists as long as at least one hard link points to it. Hard links cannot cross file boundaries.

Soft Links (Symbolic Links): Path-based references that store the path to an object as a string. Soft links can "dangle" if the target object is deleted or moved.

External Links: References to objects in other HDF5 files. External links store both the filename and the path to the object within that file.

Creating Links

Links can be created using several methods:

H5Lcreate_hard creates hard links to objects
H5Lcreate_soft creates soft (symbolic) links using path strings
H5Lcreate_external creates links to objects in other HDF5 files

Link Operations

The H5L interface provides functions for:

Querying: H5Lexists checks if a link exists, H5Lget_info retrieves link information
Moving/Copying: H5Lmove and H5Lcopy relocate or duplicate links
Deleting: H5Ldelete removes links from the file
Iterating: H5Literate and H5Lvisit traverse links in groups

Link Traversal

The H5L interface includes powerful traversal functions that can iterate over all links in a group or recursively visit all links in a group hierarchy:

H5Literate iterates over links in a group using a group identifier
H5Lvisit recursively visits all links in a group and its subgroups using a group identifier
H5Literate_by_name and H5Lvisit_by_name provide the same functionality but accept a location identifier and group name, allowing traversal without first opening the group

These functions accept callbacks that are invoked for each link, enabling custom processing.

User-Defined Link Types

HDF5 allows registration of custom link types through H5Lregister. User-defined links can implement custom traversal and access behaviors. Use H5Lunregister to remove user-defined link classes and H5Lis_registered to check if a link class is registered.

Summary

The H5L interface provides flexible mechanisms for organizing and navigating HDF5 files:

Hard links provide reference-counted object management
Soft links enable flexible, path-based references
External links connect objects across multiple files
Iteration functions enable systematic traversal of file hierarchies
User-defined links support extensibility for custom use cases

Navigate back: Main / HDF5 User Guide