Fortran VFD (H5VFD) Interface

Detailed Description

See also

H5FD, C-API

Modules
module	h5vfd
	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=default_max_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

See also

H5FDsubfiling_get_file_mapping() (C API)

H5Pset_fapl_subfiling_f() for setting up subfiling VFD