Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
HDF5 Identifiers

Navigate back: Main / HDF5 User Guide

# The HDF5 Identifier Interface

## Introduction

The HDF5 Identifier interface (H5I) manages identifiers (type hid_t) that serve as handles to HDF5 objects and resources. Identifiers provide an abstraction layer between applications and the internal HDF5 library structures, enabling safe and efficient object management.

Every HDF5 object—file, group, dataset, datatype, dataspace, attribute, property list—is accessed through an identifier. The H5I interface provides functions to query, validate, and manage these identifiers and their associated resources.

## Identifier Types

HDF5 defines several built-in identifier types:

- H5I_FILE - File identifiers
- H5I_GROUP - Group identifiers
- H5I_DATATYPE - Datatype identifiers
- H5I_DATASPACE - Dataspace identifiers
- H5I_DATASET - Dataset identifiers
- H5I_ATTR - Attribute identifiers
- H5I_MAP - Map identifiers
- H5I_VFL - Virtual File Layer driver identifiers
- H5I_VOL - Virtual Object Layer connector identifiers
- Property list identifiers (various classes)

Each identifier type is managed independently with its own reference counting system.

## Reference Counting

Identifiers use reference counting to manage object lifetimes. When an identifier is created, its reference count is set to 1. The reference count can be manipulated to control when resources are released:

- H5Iget_ref retrieves the current reference count
- H5Iinc_ref increments the reference count
- H5Idec_ref decrements the reference count

When a reference count reaches zero, the associated resources are automatically released.

## Identifier Validation

The H5I interface provides functions to validate identifiers:

- H5Iis_valid checks if an identifier is valid and has a positive reference count
- H5Iget_type retrieves the type of an identifier
- H5Itype_exists checks if an identifier type is registered

## Querying Identifiers

Applications can retrieve information about objects through their identifiers:

- H5Iget_name retrieves the name of an object (for files, groups, datasets, etc.)
- H5Iget_file_id retrieves the file identifier associated with any object

These functions are particularly useful for debugging and logging.

## User-Defined Identifier Types

Advanced applications can register custom identifier types using H5Iregister. This allows user-defined objects to benefit from HDF5's identifier management:

- Automatic reference counting
- Type safety through identifier types
- Integration with HDF5's resource management

Custom identifier types can be destroyed using H5Idestroy_type when no longer needed.

## Identifier Iteration

The H5I interface allows iteration over all identifiers of a given type:

- H5Iiterate iterates over identifiers of a specified type with a callback function
- H5Inmembers returns the number of identifiers of a given type

This is useful for resource tracking, debugging, and cleanup operations.

## Summary

The H5I identifier interface provides essential functionality:

- Safe handles to HDF5 objects and resources
- Reference counting for automatic resource management
- Type checking and validation
- Object information retrieval
- Support for user-defined identifier types
- Iteration capabilities for resource tracking

Proper identifier management is fundamental to writing robust HDF5 applications that efficiently manage memory and avoid resource leaks.

Navigate back: Main / HDF5 User Guide