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
Fortran VFD (H5VFD) Interface

## Detailed Description

See also
  Virtual File Driver Features, C-API

## Modules
module | h5fd
| This module contains Fortran interfaces for H5VFD (Virtual File Driver) functions.

## Functions/Subroutines
subroutine | h5fdsubfiling_get_file_mapping_f (file_id, filenames, num_files, hdferr)
| Retrieve the list of subfile names for a HDF5 file for the subfiling VFD.

## Function/Subroutine Documentation

## ◆ h5fdsubfiling_get_file_mapping_f()

subroutine h5fdsubfiling_get_file_mapping_f | ( | integer(hid_t), intent(in) | file_id,
|  | character(len=:), dimension(:), intent(out), allocatable | filenames,
|  | integer(size_t), intent(out) | num_files,
|  | integer, intent(out) | hdferr )

Retrieve the list of subfile names for a HDF5 file for the subfiling VFD.

This function retrieves the names of all subfiles associated with an HDF5 file that uses the subfiling Virtual File Driver (VFD). The subfiling VFD distributes file data across multiple subfiles to improve parallel I/O performance on shared file systems.

The returned filenames correspond to the physical subfiles stored on the file system that collectively make up the logical HDF5 file. This information is useful for:

- File management and backup operations
- Understanding the physical storage layout
- Tools like h5fuse for recombining subfiles
- Debugging subfiling configurations

Parameters

  file_id | [in] HDF5 file identifier for a file using the subfiling VFD
  filenames | [out] Allocatable array of subfile names. Memory is automatically allocated by the function and must be deallocated by the caller. See Compiler Compatibility note below.
  num_files | [out] Number of subfiles in the filenames array
  hdferr | [out] Error code: 0 on success -1 on failure

Since
  2.0.0

Note
  Memory Management: The filenames array is automatically allocated. The caller is responsible for deallocating when it is no longer needed:
  DEALLOCATE(filenames)
  Compiler Compatibility:
  - With H5_FORTRAN_HAVE_CHAR_ALLOC: Variable-length character strings (Fortran 2003+)
  - Without H5_FORTRAN_HAVE_CHAR_ALLOC: Fixed-length 8192 character strings (older compilers), filenames longer than 8192 characters will cause the function to fail with hdferr = -1.

Note
  This function will not be accessible if support for the subfiling VFD is unavailable or disabled.

Note
  Optimized Allocation: The function uses knowledge of the subfiling filename template to estimate optimal string lengths, typically reducing memory usage compared to the maximum 8192 character limit. Subfile names follow the pattern: basename.subfile_<inode>_<index>_of_<total>

Example Usage:
  USE hdf5
  IMPLICIT NONE
  INTEGER(HID_T) :: file_id
  CHARACTER(LEN=:), ALLOCATABLE, DIMENSION(:) :: subfile_names
  INTEGER(SIZE_T) :: num_subfiles
  INTEGER :: hdferr
  INTEGER :: i
  ! Open file with subfiling VFD (file_id setup not shown)
  ! Get subfile mapping
  CALL h5fdsubfiling_get_file_mapping_f(file_id, subfile_names, num_subfiles, hdferr)
  IF (hdferr == 0) THEN
  print *, 'Found', num_subfiles, 'subfiles:'
  DO i = 1, num_subfiles
  print *, ' ', trim(subfile_names(i))
  END DO
  ! Clean up
  DEALLOCATE(subfile_names)
  ELSE
  print *, 'Error getting file mapping:', hdferr
  END IF
  hdf5
  Definition HDF5.F90:26

See also
  H5FDsubfiling_get_file_mapping() (C API)
  H5Pset_fapl_subfiling_f() for setting up subfiling VFD