Virtual File Driver Features

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);

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");
}

See also

H5Pset_fapl_subfiling()

H5Pget_fapl_subfiling()

H5free_memory()

Since

2.0.0