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
Virtual File Driver Features
File Drivers (H5FD)

## Detailed Description

## Functions
herr_t | H5FDdriver_query (hid_t driver_id, unsigned long *flags)
| Allows querying a VFD ID for features before the file is opened.
herr_t | H5FDonion_get_revision_count (const char *filename, hid_t fapl_id, uint64_t *revision_count)
| get the number of revisions
H5_DLL herr_t | H5FDsubfiling_get_file_mapping (hid_t file_id, char ***filenames, size_t *len)
| Retrieve the subfile names for an HDF5 file using the subfiling VFD.

## Function Documentation

## ◆ H5FDdriver_query()

herr_t H5FDdriver_query | ( | hid_t | driver_id,
|  | unsigned long * | flags )

Allows querying a VFD ID for features before the file is opened.

Parameters

  [in] | driver_id | Virtual File Driver (VFD) ID
  [out] | flags | VFD flags supported

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

Queries a virtual file driver (VFD) for feature flags. Takes a VFD hid_t so it can be used before the file is opened. For example, this could be used to check if a VFD supports SWMR.

Note
  The flags obtained here are just those of the base driver and do not take any configuration options (e.g., set via a fapl call) into consideration.

Since
  1.10.2

## ◆ H5FDonion_get_revision_count()

herr_t H5FDonion_get_revision_count | ( | const char * | filename,
|  | hid_t | fapl_id,
|  | uint64_t * | revision_count )

get the number of revisions

Parameters

  [in] | filename | The name of the onion file
  [in] | fapl_id | The ID of the file access property list
  [out] | revision_count | The number of revisions

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5FDonion_get_revision_count() returns the number of revisions for an onion file. It takes the file name and file access property list that is set for the onion VFD driver.

Since
  1.14.0

## ◆ H5FDsubfiling_get_file_mapping()

H5_DLL herr_t H5FDsubfiling_get_file_mapping | ( | hid_t | file_id,
|  | char *** | filenames,
|  | size_t * | len )

Retrieve the subfile names for an HDF5 file using the subfiling VFD.

Parameters

  [in] | file_id | File identifier
  [out] | filenames | Pointer to an array of C strings containing the subfile names. Memory is allocated by the function and must be freed by the caller.
  [out] | len | Pointer to the number of subfiles in the `filenames` array.

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5FDsubfiling_get_file_mapping() retrieves the names of all physical subfiles that collectively make up a logical HDF5 file using the subfiling Virtual File Driver (VFD). The subfiling VFD distributes file data across multiple subfiles to improve parallel I/O performance, particularly systems where metadata operations can become a bottleneck.

The function returns an array of subfile names corresponding to the physical files stored on the file system. Each MPI rank may be responsible for different subfiles, and this function provides visibility into which subfiles are associated with the calling rank.

Typical use cases include:

- File management: Understanding the physical storage layout for backup and archival
- Performance analysis: Identifying subfile distribution patterns
- File fusion: Providing subfile lists to tools like h5fuse for recombining files
- Debugging: Troubleshooting subfiling configuration and I/O patterns
- Storage optimization: Analyzing subfile sizes and distribution

Note
  Memory management: The caller must call H5free_memory() on each string in the `filenames` array, and then call H5free_memory() on the `filenames` array itself:
  for (size_t i = 0; i < len; i++) {
  H5free_memory(filenames[i]);
  }
  H5free_memory(filenames);
  H5free_memory
  herr_t H5free_memory(void *mem)
  Frees memory allocated by the HDF5 library.

Note
  VFD requirement: This function only works with files that use the subfiling VFD. Calling it on files using other VFDs will result in an error. This function will not be accessible if support for the subfiling VFD is unavailable or disabled.

Note
  MPI context: The function returns subfiles associated with the calling MPI rank. Different ranks may receive different subfile lists depending on the subfiling configuration and I/O concentrator (IOC) assignment.

Note

Warning

Example
  #include "hdf5.h"
  hid_t file_id;
  char **subfile_names = NULL;
  size_t num_subfiles;
  herr_t ret;
  // Open file with subfiling VFD (setup not shown)
  // ...
  // Get subfile mapping
  ret = H5FDsubfiling_get_file_mapping(file_id, &subfile_names, &num_subfiles);
  if (ret >= 0) {
  printf("Found %zu subfiles:\n", num_subfiles);
  for (size_t i = 0; i < num_subfiles; i++) {
  printf(" %s\n", subfile_names[i]);
  H5free_memory(subfile_names[i]); // Free each string
  }
  H5free_memory(subfile_names); // Free the array
  } else {
  printf("Error getting file mapping\n");
  }
  hid_t
  int64_t hid_t
  Definition H5Ipublic.h:60
  herr_t
  int herr_t
  Definition H5public.h:269
  H5FDsubfiling_get_file_mapping
  H5_DLL herr_t H5FDsubfiling_get_file_mapping(hid_t file_id, char ***filenames, size_t *len)
  Retrieve the subfile names for an HDF5 file using the subfiling VFD.

See also
  H5Pset_fapl_subfiling()
  H5Pget_fapl_subfiling()
  H5free_memory()

Since
  2.0.0