Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5  1.14.4.3
API Reference
 
Loading...
Searching...
No Matches
File Access Properties

Detailed Description

Use file access properties to modify the default behavior of the HDF5 library when accessing files. The properties include selecting a virtual file driver (VFD), configuring the metadata cache (MDC), control file locking, etc. These properties are not persisted with files, and can be adjusted at runtime before a file is created or opened.

File access property list functions (H5P)
Function Purpose
H5Pset_alignment/H5Pget_alignment Sets/retrieves alignment properties.
H5Pset_cache/H5Pget_cache Sets/retrieves metadata cache and raw data chunk cache parameters.
H5Pset_core_write_tracking/H5Pget_core_write_tracking Sets/retrieves write tracking information for core driver.
H5Pset_elink_file_cache_size/H5Pget_elink_file_cache_size Sets/retrieves the size of the external link open file cache from the specified file access property list.
H5Pset_evict_on_close/H5Pget_evict_on_close Set/get the file access property list setting that determines whether an HDF5 object will be evicted from the library's metadata cache when it is closed.
H5Pset_gc_references/H5Pget_gc_references Sets/retrieves garbage collecting references flag.
H5Pset_family_offset Sets offset property for low-level access to a file in a family of files.
H5Pget_family_offset Retrieves a data offset from the file access property list.
H5Pset_fclose_degree/H5Pget_fclose_degree Sets/retrieves file close degree property.
H5Pset_file_image Sets an initial file image in a memory buffer.
H5Pget_file_image Retrieves a copy of the file image designated as the initial content and structure of a file.
H5Pset_file_image_callbacks/H5Pget_file_image_callbacks Sets/gets the callbacks for working with file images.
H5Pset_file_locking/H5Pget_file_locking Sets/retrieves file locking property values.
H5Pset_meta_block_size/H5Pget_meta_block_size Sets the minimum metadata blocksize or retrieves the current metadata block size setting.
H5Pset_metadata_read_attempts/H5Pget_metadata_read_attempts Sets/gets the number of read attempts from a file access property list.
H5Pset_mdc_config/H5Pget_mdc_config Set/get the initial metadata cache configuration in the indicated file access property list.
H5Pset_mdc_image_config/H5Pget_mdc_image_config Set/get the metadata cache image option for a file access property list.
H5Pset_mdc_log_options/H5Pget_mdc_log_options Set/get the metadata cache logging options.
H5Pset_multi_type/H5Pget_multi_type Sets/gets the type of data property for the MULTI driver.
H5Pset_object_flush_cb/H5Pget_object_flush_cb Set/get the object flush property values from the file access property list.
H5Pset_page_buffer_size/H5Pget_page_buffer_size Set/get the maximum size for the page buffer.
H5Pset_sieve_buf_size/H5Pget_sieve_buf_size Sets/retrieves maximum size of data sieve buffer.
H5Pset_libver_bounds Sets bounds on library versions, and indirectly format versions, to be used when creating objects.
H5Pget_libver_bounds Retrieves library version bounds settings that indirectly control the format versions used when creating objects.
H5Pset_small_data_block_size Sets the size of a contiguous block reserved for small data.
H5Pget_small_data_block_size Retrieves the current small data block size setting.
H5Pset_vol Sets the file VOL connector for a file access property list.
H5Pget_vol_cap_flags Retrieves the capability flags for the VOL connector that will be used with a file access property list.
H5Pget_vol_id Retrieves the identifier of the current VOL connector.
H5Pget_vol_info Retrieves a copy of the VOL information for a connector.
H5Pset_mpi_params/H5Pget_mpi_params Sets/retrieves the MPI communicator and info.
H5Pset_coll_metadata_write/H5Pget_coll_metadata_write Sets/retrieves metadata write mode setting.
File driver property list functions (H5P)
Function Purpose
H5Pset_driver Sets a file driver.
H5Pget_driver Returns the identifier for the driver used to create a file.
H5Pget_driver_info Returns a pointer to file driver information.
H5Pset_driver_by_name Sets a file driver according to a given driver name.
H5Pset_driver_by_value Sets a file driver according to a given driver value.
H5Pget_driver_config_str Retrieves a string representation of the configuration for the driver.
H5Pset_fapl_core/H5Pget_fapl_core Sets the driver for buffered memory files (in RAM) or retrieves information regarding the driver.
H5Pset_fapl_direct/H5Pget_fapl_direct Sets up use of the direct I/O driver or retrieves the direct I/O driver settings.
H5Pset_fapl_family/H5Pget_fapl_family Sets driver for file families, designed for systems that do not support files larger than 2 gigabytes, or retrieves information regarding driver.
H5Pset_fapl_hdfs/H5Pget_fapl_hdfs .
H5Pset_fapl_ioc/H5Pget_fapl_ioc Modifies/queries the file driver properties of the I/O concentrator driver.
H5Pset_fapl_log The logging driver is a clone of the standard SEC2 (H5FD_SEC2) driver with additional facilities for logging metrics and activity to a file.
H5Pset_fapl_mirror/H5Pget_fapl_mirror Modifies/queries the file driver properties of the mirror driver.
H5Pset_fapl_mpio/H5Pget_fapl_mpio Sets driver for files on parallel file systems (MPI I/O) or retrieves information regarding the driver.
H5Pset_fapl_mpiposix/H5Pget_fapl_mpiposix No longer available.
H5Pset_fapl_multi/H5Pget_fapl_multi Sets driver for multiple files, separating categories of metadata and raw data, or retrieves information regarding driver.
H5Pset_fapl_onion/H5Pget_fapl_onion Modifies/queries the file driver properties of the onion driver.
H5Pset_fapl_ros3/H5Pget_fapl_ros3 Modifies/queries the file driver properties of the ros3 driver.
H5Pset_fapl_sec2 Sets driver for unbuffered permanent files or retrieves information regarding driver.
H5Pset_fapl_split Sets driver for split files, a limited case of multi driver with one metadata file and one raw data file.
H5Pset_fapl_splitter/H5Pget_fapl_splitter Modifies/queries the file driver properties of the splitter driver.
H5Pset_fapl_stdio Sets driver for buffered permanent files.
H5Pset_fapl_subfiling/H5Pget_fapl_subfiling Modifies/queries the file driver properties of the subfiling driver.
H5Pset_fapl_windows Sets the Windows I/O driver.
H5Pset_multi_type Specifies type of data to be accessed via the MULTI driver enabling more direct access.
H5Pget_multi_type Retrieves type of data property for MULTI driver.

Functions

H5_DLL herr_t H5Pset_fapl_core (hid_t fapl_id, size_t increment, hbool_t backing_store)
 Modifies the file access property list to use the H5FD_CORE driver.
 
H5_DLL herr_t H5Pget_fapl_core (hid_t fapl_id, size_t *increment, hbool_t *backing_store)
 Queries core file driver properties.
 
H5_DLL herr_t H5Pset_fapl_direct (hid_t fapl_id, size_t alignment, size_t block_size, size_t cbuf_size)
 Sets up use of the direct I/O driver.
 
H5_DLL herr_t H5Pget_fapl_direct (hid_t fapl_id, size_t *boundary, size_t *block_size, size_t *cbuf_size)
 Retrieves direct I/O driver settings.
 
H5_DLL herr_t H5Pset_fapl_family (hid_t fapl_id, hsize_t memb_size, hid_t memb_fapl_id)
 Sets the file access property list to use the family driver.
 
H5_DLL herr_t H5Pget_fapl_family (hid_t fapl_id, hsize_t *memb_size, hid_t *memb_fapl_id)
 Returns file access property list information.
 
H5_DLL herr_t H5Pset_fapl_hdfs (hid_t fapl_id, H5FD_hdfs_fapl_t *fa)
 Modifies the file access property list to use the H5FD_HDFS driver.
 
H5_DLL herr_t H5Pget_fapl_hdfs (hid_t fapl_id, H5FD_hdfs_fapl_t *fa_out)
 Queries a File Access Property List for H5FD_HDFS file driver properties.
 
H5_DLL herr_t H5Pset_fapl_log (hid_t fapl_id, const char *logfile, unsigned long long flags, size_t buf_size)
 Sets up the logging virtual file driver (H5FD_LOG) for use.
 
H5_DLL herr_t H5Pget_fapl_mirror (hid_t fapl_id, H5FD_mirror_fapl_t *fa_out)
 Queries a File Access Property List for H5FD_MIRROR file driver properties.
 
H5_DLL herr_t H5Pset_fapl_mirror (hid_t fapl_id, H5FD_mirror_fapl_t *fa)
 Modifies the file access property list to use the H5FD_MIRROR driver.
 
H5_DLL herr_t H5Pset_fapl_mpio (hid_t fapl_id, MPI_Comm comm, MPI_Info info)
 Stores MPI IO communicator information to the file access property list.
 
H5_DLL herr_t H5Pget_fapl_mpio (hid_t fapl_id, MPI_Comm *comm, MPI_Info *info)
 Returns MPI IO communicator information.
 
H5_DLL herr_t H5Pset_fapl_multi (hid_t fapl_id, const H5FD_mem_t *memb_map, const hid_t *memb_fapl, const char *const *memb_name, const haddr_t *memb_addr, hbool_t relax)
 Sets up use of the multi-file driver.
 
H5_DLL herr_t H5Pget_fapl_multi (hid_t fapl_id, H5FD_mem_t *memb_map, hid_t *memb_fapl, char **memb_name, haddr_t *memb_addr, hbool_t *relax)
 Returns information about the multi-file access property list.
 
H5_DLL herr_t H5Pset_fapl_split (hid_t fapl, const char *meta_ext, hid_t meta_plist_id, const char *raw_ext, hid_t raw_plist_id)
 Emulates the old split file driver.
 
H5_DLL herr_t H5Pget_fapl_onion (hid_t fapl_id, H5FD_onion_fapl_info_t *fa_out)
 get the onion info from the file access property list
 
H5_DLL herr_t H5Pset_fapl_onion (hid_t fapl_id, const H5FD_onion_fapl_info_t *fa)
 set the onion info for the file access property list
 
H5_DLL herr_t H5Pget_fapl_ros3 (hid_t fapl_id, H5FD_ros3_fapl_t *fa_out)
 Queries a File Access Property List for H5FD_ROS3 file driver properties.
 
H5_DLL herr_t H5Pset_fapl_ros3 (hid_t fapl_id, const H5FD_ros3_fapl_t *fa)
 Modifies the specified File Access Property List to use the H5FD_ROS3 driver.
 
H5_DLL herr_t H5Pget_fapl_ros3_token (hid_t fapl_id, size_t size, char *token)
 Queries a File Access Property List for H5FD_ROS3 file driver session/security token.
 
H5_DLL herr_t H5Pset_fapl_ros3_token (hid_t fapl_id, const char *token)
 Modifies the specified File Access Property List to use the H5FD_ROS3 driver by adding the specified session/security token.
 
H5_DLL herr_t H5Pset_fapl_sec2 (hid_t fapl_id)
 Modifies the file access property list to use the H5FD_SEC2 driver.
 
H5_DLL herr_t H5Pset_fapl_splitter (hid_t fapl_id, H5FD_splitter_vfd_config_t *config_ptr)
 Sets the file access property list to use the splitter driver.
 
H5_DLL herr_t H5Pget_fapl_splitter (hid_t fapl_id, H5FD_splitter_vfd_config_t *config_ptr)
 Gets splitter driver properties from the the file access property list.
 
herr_t H5Pset_fapl_stdio (hid_t fapl_id)
 Sets the standard I/O driver.
 
H5_DLL herr_t H5Pset_fapl_ioc (hid_t fapl_id, H5FD_ioc_config_t *vfd_config)
 Modifies the specified File Access Property List to use the H5FD_IOC driver.
 
H5_DLL herr_t H5Pget_fapl_ioc (hid_t fapl_id, H5FD_ioc_config_t *config_out)
 Queries a File Access Property List for H5FD_IOC file driver properties.
 
H5_DLL herr_t H5Pset_fapl_subfiling (hid_t fapl_id, const H5FD_subfiling_config_t *vfd_config)
 Modifies the specified File Access Property List to use the H5FD_SUBFILING driver.
 
H5_DLL herr_t H5Pget_fapl_subfiling (hid_t fapl_id, H5FD_subfiling_config_t *config_out)
 Queries a File Access Property List for H5FD_SUBFILING file driver properties.
 
H5_DLL herr_t H5Pset_fapl_windows (hid_t fapl_id)
 Sets the Windows I/O driver.
 
herr_t H5Pget_alignment (hid_t fapl_id, hsize_t *threshold, hsize_t *alignment)
 Retrieves the current settings for alignment properties from a file access property list.
 
herr_t H5Pget_cache (hid_t plist_id, int *mdc_nelmts, size_t *rdcc_nslots, size_t *rdcc_nbytes, double *rdcc_w0)
 Queries the raw data chunk cache parameters.
 
herr_t H5Pget_core_write_tracking (hid_t fapl_id, hbool_t *is_enabled, size_t *page_size)
 Gets information about the write tracking feature used by the core VFD.
 
hid_t H5Pget_driver (hid_t plist_id)
 Returns low-lever driver identifier.
 
const void * H5Pget_driver_info (hid_t plist_id)
 Returns a pointer to file driver information.
 
ssize_t H5Pget_driver_config_str (hid_t fapl_id, char *config_buf, size_t buf_size)
 Retrieves a string representation of the configuration for the driver set on the given FAPL. The returned string can be used to configure the same driver in an identical way.
 
herr_t H5Pget_elink_file_cache_size (hid_t plist_id, unsigned *efc_size)
 Retrieves the size of the external link open file cache.
 
herr_t H5Pget_evict_on_close (hid_t fapl_id, hbool_t *evict_on_close)
 Retrieves the file access property list setting that determines whether an HDF5 object will be evicted from the library's metadata cache when it is closed.
 
herr_t H5Pget_family_offset (hid_t fapl_id, hsize_t *offset)
 Retrieves a data offset from the file access property list.
 
herr_t H5Pget_fclose_degree (hid_t fapl_id, H5F_close_degree_t *degree)
 Returns the file close degree.
 
herr_t H5Pget_file_image (hid_t fapl_id, void **buf_ptr_ptr, size_t *buf_len_ptr)
 Retrieves a copy of the file image designated as the initial content and structure of a file.
 
herr_t H5Pget_file_image_callbacks (hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks_ptr)
 Retrieves callback routines for working with file images.
 
herr_t H5Pget_file_locking (hid_t fapl_id, hbool_t *use_file_locking, hbool_t *ignore_when_disabled)
 Retrieves the file locking property values.
 
herr_t H5Pget_gc_references (hid_t fapl_id, unsigned *gc_ref)
 Returns garbage collecting references setting.
 
herr_t H5Pget_libver_bounds (hid_t plist_id, H5F_libver_t *low, H5F_libver_t *high)
 Retrieves library version bounds settings that indirectly control the format versions used when creating objects.
 
herr_t H5Pget_mdc_config (hid_t plist_id, H5AC_cache_config_t *config_ptr)
 Get the current initial metadata cache configuration from the provided file access property list.
 
herr_t H5Pget_mdc_image_config (hid_t plist_id, H5AC_cache_image_config_t *config_ptr)
 Retrieves the metadata cache image configuration values for a file access property list.
 
herr_t H5Pget_mdc_log_options (hid_t plist_id, hbool_t *is_enabled, char *location, size_t *location_size, hbool_t *start_on_access)
 Gets metadata cache logging options.
 
herr_t H5Pget_meta_block_size (hid_t fapl_id, hsize_t *size)
 Returns the current metadata block size setting.
 
herr_t H5Pget_metadata_read_attempts (hid_t plist_id, unsigned *attempts)
 Retrieves the number of read attempts from a file access property list.
 
herr_t H5Pget_multi_type (hid_t fapl_id, H5FD_mem_t *type)
 Retrieves type of data property for MULTI driver.
 
herr_t H5Pget_object_flush_cb (hid_t plist_id, H5F_flush_cb_t *func, void **udata)
 Retrieves the object flush property values from the file access property list.
 
herr_t H5Pget_page_buffer_size (hid_t plist_id, size_t *buf_size, unsigned *min_meta_perc, unsigned *min_raw_perc)
 Retrieves the maximum size for the page buffer and the minimum percentage for metadata and raw data pages.
 
herr_t H5Pget_sieve_buf_size (hid_t fapl_id, size_t *size)
 Returns maximum data sieve buffer size.
 
herr_t H5Pget_small_data_block_size (hid_t fapl_id, hsize_t *size)
 Retrieves the current small data block size setting.
 
herr_t H5Pget_vol_id (hid_t plist_id, hid_t *vol_id)
 Returns the identifier of the current VOL connector.
 
herr_t H5Pget_vol_info (hid_t plist_id, void **vol_info)
 Returns a copy of the VOL information for a connector.
 
herr_t H5Pset_alignment (hid_t fapl_id, hsize_t threshold, hsize_t alignment)
 Sets alignment properties of a file access property list.
 
herr_t H5Pset_cache (hid_t plist_id, int mdc_nelmts, size_t rdcc_nslots, size_t rdcc_nbytes, double rdcc_w0)
 Sets the raw data chunk cache parameters.
 
herr_t H5Pset_core_write_tracking (hid_t fapl_id, hbool_t is_enabled, size_t page_size)
 Sets write tracking information for core driver, H5FD_CORE.
 
herr_t H5Pset_driver (hid_t plist_id, hid_t driver_id, const void *driver_info)
 Sets a file driver.
 
herr_t H5Pset_driver_by_name (hid_t plist_id, const char *driver_name, const char *driver_config)
 Sets a file driver according to a given driver name.
 
herr_t H5Pset_driver_by_value (hid_t plist_id, H5FD_class_value_t driver_value, const char *driver_config)
 Sets a file driver according to a given driver value (ID).
 
herr_t H5Pset_elink_file_cache_size (hid_t plist_id, unsigned efc_size)
 Sets the number of files that can be held open in an external link open file cache.
 
herr_t H5Pset_evict_on_close (hid_t fapl_id, hbool_t evict_on_close)
 Controls the library's behavior of evicting metadata associated with a closed object.
 
herr_t H5Pset_family_offset (hid_t fapl_id, hsize_t offset)
 Sets offset property for low-level access to a file in a family of files.
 
herr_t H5Pset_fclose_degree (hid_t fapl_id, H5F_close_degree_t degree)
 Sets the file close degree.
 
herr_t H5Pset_file_image (hid_t fapl_id, void *buf_ptr, size_t buf_len)
 Sets an initial file image in a memory buffer.
 
herr_t H5Pset_file_image_callbacks (hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks_ptr)
 Sets the callbacks for working with file images.
 
herr_t H5Pset_file_locking (hid_t fapl_id, hbool_t use_file_locking, hbool_t ignore_when_disabled)
 Sets the file locking property values.
 
herr_t H5Pset_gc_references (hid_t fapl_id, unsigned gc_ref)
 Sets garbage collecting references flag.
 
herr_t H5Pset_libver_bounds (hid_t plist_id, H5F_libver_t low, H5F_libver_t high)
 Controls the range of library release versions used when creating objects in a file.
 
herr_t H5Pset_mdc_config (hid_t plist_id, H5AC_cache_config_t *config_ptr)
 Set the initial metadata cache configuration in the indicated File Access Property List to the supplied value.
 
herr_t H5Pset_mdc_log_options (hid_t plist_id, hbool_t is_enabled, const char *location, hbool_t start_on_access)
 Sets metadata cache logging options.
 
herr_t H5Pset_meta_block_size (hid_t fapl_id, hsize_t size)
 Sets the minimum metadata block size.
 
herr_t H5Pset_metadata_read_attempts (hid_t plist_id, unsigned attempts)
 Sets the number of read attempts in a file access property list.
 
herr_t H5Pset_multi_type (hid_t fapl_id, H5FD_mem_t type)
 Specifies type of data to be accessed via the MULTI driver, enabling more direct access.
 
herr_t H5Pset_object_flush_cb (hid_t plist_id, H5F_flush_cb_t func, void *udata)
 Sets a callback function to invoke when an object flush occurs in the file.
 
herr_t H5Pset_sieve_buf_size (hid_t fapl_id, size_t size)
 Sets the maximum size of the data sieve buffer.
 
herr_t H5Pset_small_data_block_size (hid_t fapl_id, hsize_t size)
 Sets the size of a contiguous block reserved for small data.
 
herr_t H5Pset_vol (hid_t plist_id, hid_t new_vol_id, const void *new_vol_info)
 Set the file VOL connector for a file access property list.
 
herr_t H5Pget_vol_cap_flags (hid_t plist_id, uint64_t *cap_flags)
 Query the capability flags for the VOL connector that will be used with this file access property list (FAPL).
 
herr_t H5Pset_coll_metadata_write (hid_t plist_id, hbool_t is_collective)
 Sets metadata write mode to be collective or independent (default)
 
herr_t H5Pget_coll_metadata_write (hid_t plist_id, hbool_t *is_collective)
 Retrieves metadata write mode setting.
 
herr_t H5Pget_mpi_params (hid_t fapl_id, MPI_Comm *comm, MPI_Info *info)
 Get the MPI communicator and info.
 
herr_t H5Pset_mpi_params (hid_t fapl_id, MPI_Comm comm, MPI_Info info)
 Set the MPI communicator and info.
 
herr_t H5Pset_mdc_image_config (hid_t plist_id, H5AC_cache_image_config_t *config_ptr)
 Sets the metadata cache image option for a file access property list.
 
herr_t H5Pset_page_buffer_size (hid_t plist_id, size_t buf_size, unsigned min_meta_per, unsigned min_raw_per)
 Sets the maximum size for the page buffer and the minimum percentage for metadata and raw data pages.
 
herr_t H5Pset_relax_file_integrity_checks (hid_t plist_id, uint64_t flags)
 Relax file integrity checks that may issue errors for some valid files.
 
herr_t H5Pget_relax_file_integrity_checks (hid_t plist_id, uint64_t *flags)
 Retrieve relaxed file integrity check flags.
 

Function Documentation

◆ H5Pget_alignment()

herr_t H5Pget_alignment ( hid_t  fapl_id,
hsize_t threshold,
hsize_t alignment 
)

Retrieves the current settings for alignment properties from a file access property list.

Parameters
[in]fapl_idFile access property list identifier
[out]thresholdPointer to location of return threshold value
[out]alignmentPointer to location of return alignment value
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_alignment() retrieves the current settings for alignment properties from a file access property list. The threshold and/or alignment pointers may be null pointers (NULL).

Since
1.0.0

◆ H5Pget_cache()

herr_t H5Pget_cache ( hid_t  plist_id,
int *  mdc_nelmts,
size_t *  rdcc_nslots,
size_t *  rdcc_nbytes,
double *  rdcc_w0 
)

Queries the raw data chunk cache parameters.

Parameters
[in]plist_idFile access property list identifier
[in,out]mdc_nelmtsNo longer used
[in,out]rdcc_nslotsNumber of elements (objects) in the raw data chunk cache
[in,out]rdcc_nbytesTotal size of the raw data chunk cache, in bytes
[in,out]rdcc_w0Preemption policy
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_cache() retrieves the maximum possible number of elements in the raw data chunk cache, the maximum possible number of bytes in the raw data chunk cache, and the preemption policy value.

Any (or all) arguments may be null pointers, in which case the corresponding datum is not returned.

Note that the mdc_nelmts parameter is no longer used.

Version
1.8.0 Use of the mdc_nelmts parameter discontinued. Metadata cache configuration is managed with H5Pset_mdc_config() and H5Pget_mdc_config()
1.6.0 The rdcc_nbytes and rdcc_nslots parameters changed from type int to size_t.
Since
1.0.0

◆ H5Pget_coll_metadata_write()

herr_t H5Pget_coll_metadata_write ( hid_t  plist_id,
hbool_t is_collective 
)

Retrieves metadata write mode setting.

Parameters
[in]plist_idFile access property list identifier
[out]is_collectivePointer to a boolean value indicating whether metadata writes are collective (>0) or independent (0). Default mode: Independent (0)
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_coll_metadata_write() retrieves the collective metadata write setting from the file access property into is_collective.

See also
Since
1.10.0

◆ H5Pget_core_write_tracking()

herr_t H5Pget_core_write_tracking ( hid_t  fapl_id,
hbool_t is_enabled,
size_t *  page_size 
)

Gets information about the write tracking feature used by the core VFD.

Parameters
[in]fapl_idFile access property list identifier
[out]is_enabledWhether the feature is enabled
[out]page_sizeSize, in bytes, of write aggregation pages
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_core_write_tracking() retrieves information about the write tracking feature used by the core VFD.

When a file is created or opened for writing using the core virtual file driver (VFD) with the backing store option turned on, the VFD can be configured to track changes to the file and only write out the modified bytes. To avoid a large number of small writes, the changes can be aggregated into pages of a user-specified size. The core VFD is also known as the memory VFD. The driver identifier is H5FD_CORE.

Note
This function is only for use with the core VFD and must be used after the call to H5Pset_fapl_core(). It is an error to use this function with any other VFD.
This function only applies to the backing store write operation, which typically occurs when the file is flushed or closed. This function has no relationship to the increment parameter passed to H5Pset_fapl_core().
For optimum performance, the page_size parameter should be a power of two.
Since
1.8.13

◆ H5Pget_driver()

hid_t H5Pget_driver ( hid_t  plist_id)

Returns low-lever driver identifier.

Parameters
[in]plist_idProperty list identifier
Returns
Returns a low level driver identifier if successful; otherwise returns H5I_INVALID_HID.

H5Pget_driver() returns the identifier of the low-level file driver associated with the file access property list or data transfer property list plist_id.

Valid driver identifiers distributed with HDF5 are listed and described in the following table.

Supported file drivers
Driver Name Driver Identifier Description Related API
POSIX H5FD_SEC2 This driver uses POSIX file-system functions like read and write to perform I/O to a single, permanent file on local disk with no system buffering. This driver is POSIX-compliant and is the default file driver for all systems. H5Pset_fapl_sec2
Memory H5FD_CORE With this driver, an application can work with a file in memory for faster reads and writes. File contents are kept in memory until the file is closed. At closing, the memory version of the file can be written back to disk or abandoned. H5Pset_fapl_core
Log H5FD_LOG This is the H5FD_SEC2 driver with logging capabilities. H5Pset_fapl_log
Family H5FD_FAMILY With this driver, the HDF5 file's address space is partitioned into pieces and sent to separate storage files using an underlying driver of the user's choice. This driver is for systems that do not support files larger than 2 gigabytes. H5Pset_fapl_family
Multi H5FD_MULTI With this driver, data can be stored in multiple files according to the type of the data. I/O might work better if data is stored in separate files based on the type of data. The Split driver is a special case of this driver. H5Pset_fapl_multi / H5Pset_fapl_split
STDIO H5FD_STDIO This driver uses functions from the standard C stdio.h to perform I/O to a single, permanent file on local disk with additional system buffering. H5Pset_fapl_stdio
Split H5FD_SPLITTER This file driver splits a file into two parts. One part stores metadata, and the other part stores raw data. This splitting a file into two parts is a limited case of the Multi driver. H5Pset_fapl_splitter
Parallel H5FD_MPIO This is the standard HDF5 file driver for parallel file systems. This driver uses the MPI standard for both communication and file I/O. H5Pset_fapl_mpio
Direct H5FD_DIRECT This is the H5FD_SEC2 driver except data is written to or read from the file synchronously without being cached by the system. H5Pset_fapl_direct
Mirror H5FD_MIRROR Serial I/O to file using Unix “stdio” functions. H5Pset_fapl_mirror
HDFS H5FD_HDFS Read-Only access to Hadoop Distributed File System (HDFS). H5Pset_fapl_hdfs
ros3 H5FD_ROS3 Read-Only access to Amazon's S3 service. H5Pset_fapl_ros3
Subfiling H5FD_SUBFILING Derived from other "stacked" VFDs such as the splitter, mirror, and family VFDs. H5Pset_fapl_subfiling
IOC H5FD_IOC Relays VFD calls to one VFD, and write calls to another VFD. Maintains two files. H5Pset_fapl_ioc
Onion H5FD_ONION Provide in-file provenance and revision/version control. H5Pset_fapl_onion
Windows H5FD_WINDOWS This driver was modified in HDF5-1.8.8 to be a wrapper of the POSIX driver, H5FD_SEC2. This change should not affect user applications. H5Pset_fapl_windows
Parallel POSIX H5FD_MPIPOSIX This driver is no longer available
Stream H5FD_STREAM This driver is no longer available.
     This list does not include custom drivers that might be
     defined and registered by a user.

     The returned driver identifier is only valid as long as the
     file driver remains registered.
Since
1.2.0

◆ H5Pget_driver_config_str()

ssize_t H5Pget_driver_config_str ( hid_t  fapl_id,
char *  config_buf,
size_t  buf_size 
)

Retrieves a string representation of the configuration for the driver set on the given FAPL. The returned string can be used to configure the same driver in an identical way.

Parameters
[in]fapl_idFile access property list identifier
[out]config_bufDriver configuration string output buffer
[in]buf_sizeSize of driver configuration string output buffer
Returns
Returns the length of the driver configuration string on success (not including the NUL terminator). Returns negative on failure.

H5Pget_driver_config_str() retrieves a string representation of the configuration for the driver set on the given FAPL. The returned string can be used to configure the same driver in an identical way.

If config_buf is NULL, the length of the driver configuration string is simply returned. The caller can then allocate a buffer of the appropriate size and call this routine again.

Since
1.14.0

◆ H5Pget_driver_info()

const void * H5Pget_driver_info ( hid_t  plist_id)

Returns a pointer to file driver information.

Parameters
[in]plist_idFile access or data transfer property list identifier
Returns
Returns a pointer to a struct containing low-level driver information. Otherwise returns NULL. NULL is also returned if no driver-specific properties have been registered. No error is pushed on the stack in this case.

H5Pget_driver_info() returns a pointer to file driver-specific information for the low-level driver associated with the file access or data transfer property list plist_id.

The pointer returned by this function points to an “uncopied” struct. Driver-specific versions of that struct are defined for each low-level driver in the relevant source code file H5FD*.c. For example, the struct used for the MULTI driver is H5FD_multi_fapl_t defined in H5FDmulti.c.

If no driver-specific properties have been registered, H5Pget_driver_info() returns NULL.

Note
H5Pget_driver_info() and H5Pset_driver() are used only when creating a virtual file driver (VFD) in the virtual file layer (VFL).
Version
1.10.1 Return value was changed from void * to const void *.
1.8.2 Function publicized in this release; previous releases described this function only in the virtual file driver documentation.
Since
1.4.0

◆ H5Pget_elink_file_cache_size()

herr_t H5Pget_elink_file_cache_size ( hid_t  plist_id,
unsigned *  efc_size 
)

Retrieves the size of the external link open file cache.

Parameters
[in]plist_idFile access property list identifier
[out]efc_sizeExternal link open file cache size in number of files
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_elink_file_cache_size() retrieves the number of files that can be held open in an external link open file cache.

Since
1.8.7

◆ H5Pget_evict_on_close()

herr_t H5Pget_evict_on_close ( hid_t  fapl_id,
hbool_t evict_on_close 
)

Retrieves the file access property list setting that determines whether an HDF5 object will be evicted from the library's metadata cache when it is closed.

Parameters
[in]fapl_idFile access property list identifier
[out]evict_on_closePointer to a variable that will indicate if the object will be evicted on close
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

The library's metadata cache is fairly conservative about holding on to HDF5 object metadata (object headers, chunk index structures, etc.), which can cause the cache size to grow, resulting in memory pressure on an application or system. When enabled, the "evict on close" property will cause all metadata for an object to be immediately evicted from the cache as long as it is not referenced by any other open object.

See H5Pset_evict_on_close() for additional notes on behavior.

Since
1.10.1

◆ H5Pget_family_offset()

herr_t H5Pget_family_offset ( hid_t  fapl_id,
hsize_t offset 
)

Retrieves a data offset from the file access property list.

Parameters
[in]fapl_idFile access property list identifier
[out]offsetOffset in bytes within the HDF5 file
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_family_offset() retrieves the value of offset from the file access property list fapl_id so that the user application can retrieve a file handle for low-level access to a particular member of a family of files. The file handle is retrieved with a separate call to H5Fget_vfd_handle() (or, in special circumstances, to H5FDget_vfd_handle(), see HDF5 Virtual File Layer).

Since
1.6.0

◆ H5Pget_fapl_core()

H5_DLL herr_t H5Pget_fapl_core ( hid_t  fapl_id,
size_t *  increment,
hbool_t backing_store 
)

Queries core file driver properties.

Parameters
[in]fapl_idFile access property list identifier
[out]incrementSize, in bytes, of memory increments
[out]backing_storeBoolean flag indicating whether to write the file contents to disk when the file is closed
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_fapl_core() queries the H5FD_CORE driver properties as set by H5Pset_fapl_core().

Since
1.4.0

◆ H5Pget_fapl_direct()

H5_DLL herr_t H5Pget_fapl_direct ( hid_t  fapl_id,
size_t *  boundary,
size_t *  block_size,
size_t *  cbuf_size 
)

Retrieves direct I/O driver settings.

Parameters
[in]fapl_idFile access property list identifier
[out]boundaryRequired memory alignment boundary
[out]block_sizeFile system block size
[out]cbuf_sizeCopy buffer size
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_fapl_direct() retrieves the required memory alignment (alignment), file system block size (block_size), and copy buffer size (cbuf_size) settings for the direct I/O driver, H5FD_DIRECT, from the file access property list fapl_id.

See H5Pset_fapl_direct() for discussion of these values, requirements, and important considerations.

Since
1.8.0

◆ H5Pget_fapl_family()

H5_DLL herr_t H5Pget_fapl_family ( hid_t  fapl_id,
hsize_t memb_size,
hid_t memb_fapl_id 
)

Returns file access property list information.

Parameters
[in]fapl_idFile access property list identifier
[out]memb_sizeSize in bytes of each file member
[out]memb_fapl_idIdentifier of file access property list for each family member
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_fapl_family() returns file access property list for use with the family driver. This information is returned through the output parameters.

Since
1.4.0

◆ H5Pget_fapl_hdfs()

H5_DLL herr_t H5Pget_fapl_hdfs ( hid_t  fapl_id,
H5FD_hdfs_fapl_t fa_out 
)

Queries a File Access Property List for H5FD_HDFS file driver properties.

Parameters
[in]fapl_idFile access property list identifier
[out]fa_outPointer to H5FD_HDFS driver configuration structure
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_fapl_hdfs() queries the H5FD_HDFS driver properties as set by H5Pset_fapl_hdfs().

Since
1.10.6

◆ H5Pget_fapl_ioc()

H5_DLL herr_t H5Pget_fapl_ioc ( hid_t  fapl_id,
H5FD_ioc_config_t config_out 
)

Queries a File Access Property List for H5FD_IOC file driver properties.

Parameters
[in]fapl_idFile access property list identifier
[out]config_outPointer to H5FD_ioc_config_t structure through which the H5FD_IOC file driver properties will be returned.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_fapl_ioc() queries the specified File Access Property List for H5FD_IOC driver properties as set by H5Pset_fapl_ioc(). If the H5FD_IOC driver has not been set on the File Access Property List, a default configuration is returned. An HDF5 application may use this functionality to manually configure the H5FD_IOC driver by calling H5Pget_fapl_ioc() on a newly-created File Access Property List, adjusting the default values and then calling H5Pset_fapl_ioc() with the configured H5FD_ioc_config_t structure.

Since
1.14.0

◆ H5Pget_fapl_mirror()

H5_DLL herr_t H5Pget_fapl_mirror ( hid_t  fapl_id,
H5FD_mirror_fapl_t fa_out 
)

Queries a File Access Property List for H5FD_MIRROR file driver properties.

Parameters
[in]fapl_idFile access property list identifier
[out]fa_outPointer to H5FD_MIRROR driver configuration structure
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_fapl_mirror() queries the H5FD_MIRROR driver properties as set by H5Pset_fapl_mirror().

Since
1.10.7

◆ H5Pget_fapl_mpio()

H5_DLL herr_t H5Pget_fapl_mpio ( hid_t  fapl_id,
MPI_Comm *  comm,
MPI_Info *  info 
)

Returns MPI IO communicator information.

Parameters
[in]fapl_idFile access property list identifier
[out]commMPI communicator
[out]infoMPI info object
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

If the file access property list is set to the H5FD_MPIO driver, H5Pget_fapl_mpio() returns duplicates of the stored MPI communicator and Info object through the comm and info pointers, if those values are non-null.

Since the MPI communicator and Info object are duplicates of the stored information, future modifications to the access property list will not affect them. It is the responsibility of the application to free these objects.

Version
1.4.5 Handling of the MPI Communicator and Info object changed at this release. A duplicate of each of these is now stored in the property list instead of pointers to each.
Since
1.4.0

◆ H5Pget_fapl_multi()

H5_DLL herr_t H5Pget_fapl_multi ( hid_t  fapl_id,
H5FD_mem_t memb_map,
hid_t memb_fapl,
char **  memb_name,
haddr_t memb_addr,
hbool_t relax 
)

Returns information about the multi-file access property list.

Parameters
[in]fapl_idFile access property list identifier
[out]memb_mapMaps memory usage types to other memory usage types
[out]memb_faplProperty list for each memory usage type
[out]memb_nameName generator for names of member files
[out]memb_addrThe offsets within the virtual address space, from 0 (zero) to HADDR_MAX, at which each type of data storage begins
[out]relaxAllows read-only access to incomplete file sets when true
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_fapl_multi() returns information about the multi-file access property list.

Since
1.4.0

◆ H5Pget_fapl_onion()

H5_DLL herr_t H5Pget_fapl_onion ( hid_t  fapl_id,
H5FD_onion_fapl_info_t fa_out 
)

get the onion info from the file access property list


Parameters
[in]fapl_idFile access property list identifier
[out]fa_outThe pointer to the structure H5FD_onion_fapl_info_t
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_fapl_onion() retrieves the structure H5FD_onion_fapl_info_t from the file access property list that is set for the onion VFD driver.

Since
1.14.0

◆ H5Pget_fapl_ros3()

H5_DLL herr_t H5Pget_fapl_ros3 ( hid_t  fapl_id,
H5FD_ros3_fapl_t fa_out 
)

Queries a File Access Property List for H5FD_ROS3 file driver properties.

Parameters
[in]fapl_idFile access property list identifier
[out]fa_outPointer to H5FD_ROS3 driver configuration structure.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

◆ H5Pget_fapl_ros3_token()

H5_DLL herr_t H5Pget_fapl_ros3_token ( hid_t  fapl_id,
size_t  size,
char *  token 
)

Queries a File Access Property List for H5FD_ROS3 file driver session/security token.

Parameters
[in]fapl_idFile access property list identifier
[in]sizeSize of the provided char array for storing the session/security token.
[out]tokenSession/security token.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Since
1.14.2

◆ H5Pget_fapl_splitter()

H5_DLL herr_t H5Pget_fapl_splitter ( hid_t  fapl_id,
H5FD_splitter_vfd_config_t config_ptr 
)

Gets splitter driver properties from the the file access property list.

Parameters
[in]fapl_idFile access property list identifier
[out]config_ptrConfiguration options for the VFD
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_splitter() sets the file access property list identifier, fapl_id, to use the splitter driver.

The splitter VFD echoes file manipulation (e.g. create, truncate) and write calls to a second file.

Note
The splitter VFD should not be confused with the split VFD, which is a simplification of the multi VFD and creates separate files for metadata and data.
Since
1.10.7, 1.12.1

◆ H5Pget_fapl_subfiling()

H5_DLL herr_t H5Pget_fapl_subfiling ( hid_t  fapl_id,
H5FD_subfiling_config_t config_out 
)

Queries a File Access Property List for H5FD_SUBFILING file driver properties.

Parameters
[in]fapl_idFile access property list identifier
[out]config_outPointer to H5FD_subfiling_config_t structure through which the H5FD_SUBFILING file driver properties will be returned.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_fapl_subfiling() queries the specified File Access Property List for H5FD_SUBFILING driver properties as set by H5Pset_fapl_subfiling(). If the H5FD_SUBFILING driver has not been set on the File Access Property List, a default configuration is returned. An HDF5 application may use this functionality to manually configure the H5FD_SUBFILING driver by calling H5Pget_fapl_subfiling() on a newly-created File Access Property List, adjusting the default values and then calling H5Pset_fapl_subfiling() with the configured H5FD_subfiling_config_t structure.

Note
H5Pget_fapl_subfiling() returns the H5FD_SUBFILING driver properties as they were initially set for the File Access Property List using H5Pset_fapl_subfiling(). Alternatively, the driver properties can be modified at runtime according to values set for the H5FD_SUBFILING_STRIPE_SIZE, H5FD_SUBFILING_IOC_PER_NODE and H5FD_SUBFILING_IOC_SELECTION_CRITERIA environment variables. However, driver properties set through environment variables will not be reflected in what is returned by H5Pget_fapl_subfiling(), so an application may need to check those environment variables to get accurate values for the H5FD_SUBFILING driver properties.
Since
1.14.0

◆ H5Pget_fclose_degree()

herr_t H5Pget_fclose_degree ( hid_t  fapl_id,
H5F_close_degree_t degree 
)

Returns the file close degree.

Parameters
[in]fapl_idFile access property list identifier
[out]degreePointer to a location to which to return the file close degree property, the value of degree
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_fclose_degree() returns the current setting of the file close degree property degree in the file access property list fapl_id. The value of degree determines how aggressively H5Fclose() deals with objects within a file that remain open when H5Fclose() is called to close that file.

Since
1.6.0

◆ H5Pget_file_image()

herr_t H5Pget_file_image ( hid_t  fapl_id,
void **  buf_ptr_ptr,
size_t *  buf_len_ptr 
)

Retrieves a copy of the file image designated as the initial content and structure of a file.

Parameters
[in]fapl_idFile access property list identifier
[in,out]buf_ptr_ptrOn input, NULL or a pointer to a pointer to a buffer that contains the file image.
On successful return, if buf_ptr_ptr is not NULL, *buf_ptr_ptr will contain a pointer to a copy of the initial image provided in the last call to H5Pset_file_image() for the supplied fapl_id. If no initial image has been set, *buf_ptr_ptr will be NULL.
[in,out]buf_len_ptrOn input, NULL or a pointer to a buffer specifying the required size of the buffer to hold the file image.
On successful return, if buf_len_ptr was not passed in as NULL, buf_len_ptr will return the required size in bytes of the buffer to hold the initial file image in the supplied file access property list, fapl_id. If no initial image is set, the value of *buf_len_ptr will be set to 0 (zero)
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_file_image() allows an application to retrieve a copy of the file image designated for a VFD to use as the initial contents of a file.

If file image callbacks are defined, H5Pget_file_image() will use them when allocating and loading the buffer to return to the application (see H5Pset_file_image_callbacks()). If file image callbacks are not defined, the function will use malloc and memcpy. When malloc and memcpy are used, it is the caller's responsibility to discard the returned buffer with a call to free.

It is the responsibility of the calling application to free the buffer whose address is returned in buf_ptr_ptr. This can be accomplished with free if file image callbacks have not been set (see H5Pset_file_image_callbacks()) or with the appropriate method if file image callbacks have been set.

See also
H5LTopen_file_image(), H5Fget_file_image(), H5Pset_file_image(), H5Pset_file_image_callbacks(), H5Pget_file_image_callbacks(), H5FD_file_image_callbacks_t, H5FD_file_image_op_t, HDF5 File Image Operations.
Since
1.8.9

◆ H5Pget_file_image_callbacks()

herr_t H5Pget_file_image_callbacks ( hid_t  fapl_id,
H5FD_file_image_callbacks_t callbacks_ptr 
)

Retrieves callback routines for working with file images.

Parameters
[in]fapl_idFile access property list identifier
[in,out]callbacks_ptrPointer to the instance of the H5FD_file_image_callbacks_t struct in which the callback routines are to be returned
Struct fields must be initialized to NULL before the call is made.
Struct field contents upon return will match those passed in in the last H5Pset_file_image_callbacks() call for the file access property list fapl_id.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_file_image_callbacks() retrieves the callback routines set for working with file images opened with the file access property list fapl_id.

The callbacks must have been previously set with H5Pset_file_image_callbacks() in the file access property list.

Upon the successful return of H5Pset_file_image_callbacks(), the fields in the instance of the H5FD_file_image_callbacks_t struct pointed to by callbacks_ptr will contain the same values as were passed in the most recent H5Pset_file_image_callbacks() call for the file access property list fapl_id.

See also
H5LTopen_file_image(), H5Fget_file_image(), H5Pset_file_image(), H5Pset_file_image_callbacks(), H5Pget_file_image_callbacks(), H5FD_file_image_callbacks_t, H5FD_file_image_op_t, HDF5 File Image Operations.
Since
1.8.9

◆ H5Pget_file_locking()

herr_t H5Pget_file_locking ( hid_t  fapl_id,
hbool_t use_file_locking,
hbool_t ignore_when_disabled 
)

Retrieves the file locking property values.

Parameters
[in]fapl_idFile access property list identifier
[out]use_file_lockingFile locking flag
[out]ignore_when_disabledIgnore when disabled flag
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_file_locking() retrieves the file locking property values for the file access property list specified by fapl_id.

Since
1.10.7

◆ H5Pget_gc_references()

herr_t H5Pget_gc_references ( hid_t  fapl_id,
unsigned *  gc_ref 
)

Returns garbage collecting references setting.

Parameters
[in]fapl_idFile access property list identifier
[out]gc_refFlag returning the state of reference garbage collection. A returned value of 1 indicates that garbage collection is on while 0 indicates that garbage collection is off.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_gc_references() returns the current setting for the garbage collection references property from the specified file access property list. The garbage collection references property is set by H5Pset_gc_references().

Since
1.2.0

◆ H5Pget_libver_bounds()

herr_t H5Pget_libver_bounds ( hid_t  plist_id,
H5F_libver_t low,
H5F_libver_t high 
)

Retrieves library version bounds settings that indirectly control the format versions used when creating objects.

Parameters
[in]plist_idFile access property list identifier
[out]lowThe earliest version of the library that will be used for writing objects
[out]highThe latest version of the library that will be used for writing objects
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_libver_bounds() retrieves the lower and upper bounds on the HDF5 library release versions that indirectly determine the object format versions used when creating objects in the file.

This property is retrieved from the file access property list specified by the parameter fapl_id.

The value returned in the parameters low and high is one of the enumerated values in the H5F_libver_t struct, which is defined in H5Fpublic.h.

Version
1.10.2 Add H5F_LIBVER_V18 to the enumerated defines in H5F_libver_t
Since
1.8.0

◆ H5Pget_mdc_config()

herr_t H5Pget_mdc_config ( hid_t  plist_id,
H5AC_cache_config_t config_ptr 
)

Get the current initial metadata cache configuration from the provided file access property list.

Parameters
[in]plist_idFile access property list identifier
[in,out]config_ptrPointer to the instance of H5AC_cache_config_t in which the current metadata cache configuration is to be reported
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Note
The in direction applies only to the H5AC_cache_config_t::version field. All other fields are out parameters.

The fields of the H5AC_cache_config_t structure are shown below:

typedef struct H5AC_cache_config_t {
/* general configuration fields: */
int version;
size_t initial_size;
size_t max_size;
size_t min_size;
long int epoch_length;
/* size increase control fields: */
double increment;
size_t max_increment;
/* size decrease control fields: */
double decrement;
size_t max_decrement;
double empty_reserve;
/* parallel configuration fields: */
#define H5AC__MAX_TRACE_FILE_NAME_LEN
Definition H5ACpublic.h:432
H5C_cache_incr_mode
Definition H5Cpublic.h:26
H5C_cache_decr_mode
Definition H5Cpublic.h:42
H5C_cache_flash_incr_mode
Definition H5Cpublic.h:34
bool hbool_t
Definition H5public.h:249
Definition H5ACpublic.h:462
enum H5C_cache_flash_incr_mode flash_incr_mode
Definition H5ACpublic.h:615
double lower_hr_threshold
Definition H5ACpublic.h:585
hbool_t apply_max_increment
Definition H5ACpublic.h:607
hbool_t evictions_enabled
Definition H5ACpublic.h:526
double decrement
Definition H5ACpublic.h:657
enum H5C_cache_decr_mode decr_mode
Definition H5ACpublic.h:638
size_t initial_size
Definition H5ACpublic.h:550
hbool_t open_trace_file
Definition H5ACpublic.h:478
hbool_t apply_empty_reserve
Definition H5ACpublic.h:683
hbool_t set_initial_size
Definition H5ACpublic.h:546
size_t max_decrement
Definition H5ACpublic.h:673
double flash_multiple
Definition H5ACpublic.h:620
int epochs_before_eviction
Definition H5ACpublic.h:677
int metadata_write_strategy
Definition H5ACpublic.h:707
double upper_hr_threshold
Definition H5ACpublic.h:643
size_t dirty_bytes_threshold
Definition H5ACpublic.h:696
char trace_file_name[1024+1]
Definition H5ACpublic.h:511
double flash_threshold
Definition H5ACpublic.h:629
double empty_reserve
Definition H5ACpublic.h:687
hbool_t rpt_fcn_enabled
Definition H5ACpublic.h:470
int version
Definition H5ACpublic.h:465
double min_clean_fraction
Definition H5ACpublic.h:556
hbool_t apply_max_decrement
Definition H5ACpublic.h:669
double increment
Definition H5ACpublic.h:595
long int epoch_length
Definition H5ACpublic.h:573
hbool_t close_trace_file
Definition H5ACpublic.h:499
size_t max_increment
Definition H5ACpublic.h:611
enum H5C_cache_incr_mode incr_mode
Definition H5ACpublic.h:580
size_t max_size
Definition H5ACpublic.h:565
size_t min_size
Definition H5ACpublic.h:569

(Click on a enumerator, field, or type for more information.)

H5Pget_mdc_config() gets the initial metadata cache configuration contained in a file access property list and loads it into the instance of H5AC_cache_config_t pointed to by the config_ptr parameter. This configuration is used when the file is opened.

Note that the version field of *config_ptr must be initialized; this allows the library to support earlier versions of the H5AC_cache_config_t structure.

See the overview of the metadata cache in the special topics section of the user guide for details on the configuration data returned. If you haven't read and understood that documentation, the results of this call will not make much sense.

Since
1.8.0

◆ H5Pget_mdc_image_config()

herr_t H5Pget_mdc_image_config ( hid_t  plist_id,
H5AC_cache_image_config_t config_ptr 
)

Retrieves the metadata cache image configuration values for a file access property list.

Parameters
[in]plist_idFile access property list identifier
[out]config_ptrPointer to metadata cache image configuration values
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_mdc_image_config() retrieves the metadata cache image values into config_ptr for the file access property list specified in plist_id.

H5AC_cache_image_config_t is defined as follows:

typedef struct H5AC_cache_image_config_t {
int version;
Definition H5ACpublic.h:732
hbool_t save_resize_status
Definition H5ACpublic.h:743
int version
Definition H5ACpublic.h:733
hbool_t generate_image
Definition H5ACpublic.h:739
int entry_ageout
Definition H5ACpublic.h:748

(Click on a enumerator, field, or type for more information.)

Since
1.10.1

◆ H5Pget_mdc_log_options()

herr_t H5Pget_mdc_log_options ( hid_t  plist_id,
hbool_t is_enabled,
char *  location,
size_t *  location_size,
hbool_t start_on_access 
)

Gets metadata cache logging options.

Parameters
[in]plist_idFile access property list identifier
[out]is_enabledFlag whether logging is enabled
[out]locationLocation of log in UTF-8/ASCII (file path/name) (On Windows, this must be ASCII)
[out]location_sizeSize in bytes of the location string
[out]start_on_accessWhether the logging begins as soon as the file is opened or created
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

The metadata cache is a central part of the HDF5 library through which all file metadata reads and writes take place. File metadata is normally invisible to the user and is used by the library for purposes such as locating and indexing data. File metadata should not be confused with user metadata, which consists of attributes created by users and attached to HDF5 objects such as datasets via Attributes (H5A) API calls.

Due to the complexity of the cache, a trace/logging feature has been created that can be used by HDF5 developers for debugging and performance analysis. The functions that control this functionality will normally be of use to a very limited number of developers outside of The HDF Group. The functions have been documented to help users create logs that can be sent with bug reports.

Control of the log functionality is straightforward. Logging is enabled via the H5Pset_mdc_log_options() function, which will modify the file access property list used to open or create a file. This function has a flag that determines whether logging begins at file open or starts in a paused state. Log messages can then be controlled via the H5Fstart_mdc_logging() / H5Fstop_mdc_logging() functions. H5Pget_mdc_log_options() can be used to examine a file access property list, and H5Fget_mdc_logging_status() will return the current state of the logging flags.

The log format is described in the Metadata Cache Logging document.

Since
1.10.0

◆ H5Pget_meta_block_size()

herr_t H5Pget_meta_block_size ( hid_t  fapl_id,
hsize_t size 
)

Returns the current metadata block size setting.

Parameters
[in]fapl_idFile access property list identifier
[out]sizeMinimum size, in bytes, of metadata block allocations
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

Returns the current minimum size, in bytes, of new metadata block allocations. This setting is retrieved from the file access property list fapl_id.

This value is set by H5Pset_meta_block_size() and is retrieved from the file access property list fapl_id.

Since
1.4.0

◆ H5Pget_metadata_read_attempts()

herr_t H5Pget_metadata_read_attempts ( hid_t  plist_id,
unsigned *  attempts 
)

Retrieves the number of read attempts from a file access property list.

Parameters
[in]plist_idFile access property list identifier
[out]attemptsThe number of read attempts
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_metadata_read_attempts() retrieves the number of read attempts that is set in the file access property list plist_id.

For a default file access property list, the value retrieved will depend on whether the user sets the number of attempts via H5Pset_metadata_read_attempts():

  • If the number of attempts is set to N, the value returned will be N.
  • If the number of attempts is not set, the value returned will be the default for non-SWMR access (1). SWMR is short for single-writer/multiple-reader.

For the file access property list of a specified HDF5 file, the value retrieved will depend on how the file is opened and whether the user sets the number of read attempts via H5Pset_metadata_read_attempts():

  • For a file opened with SWMR access:

    • If the number of attempts is set to N, the value returned will be N.
    • If the number of attempts is not set, the value returned will be the default for SWMR access (100).
  • For a file opened without SWMR access, the value retrieved will always be the default for non-SWMR access (1). The value set via H5Pset_metadata_read_attempts() does not have any effect on non-SWMR access.
Failure Modes

When the input property list is not a file access property list.

When the library is unable to retrieve the number of read attempts from the file access property list.

Examples

The first example illustrates the two cases for retrieving the number of read attempts from a default file access property list.

/* Get a copy of file access property list */
/* Retrieve the # of read attempts from the file access property list */
/*
* The value returned in "attempts" will be 1 (default for non-SWMR access).
*/
/* Set the # of read attempts to 20 */
/* Retrieve the # of read attempts from the file access property list */
/*
* The value returned in "attempts" will be 20 as set.
*/
/* Close the property list */
H5Pclose(fapl);
#define H5P_FILE_ACCESS
Definition H5Ppublic.h:64
herr_t H5Pget_metadata_read_attempts(hid_t plist_id, unsigned *attempts)
Retrieves the number of read attempts from a file access property list.
herr_t H5Pset_metadata_read_attempts(hid_t plist_id, unsigned attempts)
Sets the number of read attempts in a file access property list.
herr_t H5Pclose(hid_t plist_id)
Terminates access to a property list.
hid_t H5Pcreate(hid_t cls_id)
Creates a new property list as an instance of a property list class.

The second example illustrates the two cases for retrieving the number of read attempts from the file access property list of a file opened with SWMR access.

/* Open the file with SWMR access and default file access property list */
/* Get the file's file access property list */
file_fapl = H5Fget_access_plist(fid);
/* Retrieve the # of read attempts from the file's file access property list */
H5Pget_metadata_read_attempts(file_fapl, &attempts);
/*
* The value returned in "attempts" will be 100 (default for SWMR access).
*/
/* Close the property list */
H5Pclose(file_fapl);
/* Close the file */
H5Fclose(fid);
/* Create a copy of file access property list */
/* Set the # of read attempts */
/* Open the file with SWMR access and the non-default file access property list */
fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), fapl);
/* Get the file's file access property list */
file_fapl = H5Fget_access_plist(fid);
/* Retrieve the # of read attempts from the file's file access property list */
H5Pget_metadata_read_attempts(file_fapl, &attempts);
/*
* The value returned in "attempts" will be 20.
*/
/* Close the property lists */
H5Pclose(file_fapl);
H5Pclose(fapl);
/* Close the file */
H5Fclose(fid);
#define H5F_ACC_RDONLY
Definition H5Fpublic.h:48
#define H5F_ACC_SWMR_READ
Definition H5Fpublic.h:60
#define H5P_DEFAULT
Definition H5Ppublic.h:228
hid_t H5Fget_access_plist(hid_t file_id)
Returns a file access property list identifier.
hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id)
Opens an existing HDF5 file.
herr_t H5Fclose(hid_t file_id)
Terminates access to an HDF5 file.

The third example illustrates the two cases for retrieving the number of read attempts from the file access property list of a file opened with non-SWMR access.

/* Open the file with non-SWMR access and default file access property list */
/* Get the file's file access property list */
file_fapl = H5Fget_access_plist(fid);
/* Retrieve the # of read attempts from the file's file access property list */
H5Pget_metadata_read_attempts(file_fapl, &attempts);
/*
* The value returned in "attempts" will be 1 (default for non-SWMR access).
*/
/* Close the property list */
H5Pclose(file_fapl);
/* Close the file */
H5Fclose(fid);
/* Create a copy of file access property list */
/* Set the # of read attempts */
/* Open the file with non-SWMR access and the non-default file access property list */
fid = H5Fopen(FILE, H5F_ACC_RDONLY, fapl);
/* Get the file's file access property list */
file_fapl = H5Fget_access_plist(fid);
/* Retrieve the # of read attempts from the file's file access property list */
H5Pget_metadata_read_attempts(file_fapl, &attempts);
/*
* The value returned in "attempts" will be 1 (default for non-SWMR access).
*/
/* Close the property lists */
H5Pclose(file_fapl);
H5Pclose(fapl);
/* Close the file */
H5Fclose(fid);

Since
1.10.0

◆ H5Pget_mpi_params()

herr_t H5Pget_mpi_params ( hid_t  fapl_id,
MPI_Comm *  comm,
MPI_Info *  info 
)

Get the MPI communicator and info.

Parameters
[in]fapl_idFile access property list identifier
[out]commMPI communicator
[out]infoMPI info object
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_mpi_params() gets the MPI communicator and info stored in the file access property list fapl_id.

Since
1.12.0

◆ H5Pget_multi_type()

herr_t H5Pget_multi_type ( hid_t  fapl_id,
H5FD_mem_t type 
)

Retrieves type of data property for MULTI driver.

Parameters
[in]fapl_idFile access property list or data transfer property list identifier
[out]typeType of data
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_multi_type() retrieves the type of data setting from the file access or data transfer property list fapl_id. This enables a user application to specify the type of data the application wishes to access so that the application can retrieve a file handle for low-level access to the particular member of a set of MULTI files in which that type of data is stored. The file handle is retrieved with a separate call to H5Fget_vfd_handle() (or, in special circumstances, to H5FDget_vfd_handle(); see the Virtual File Layer documentation for more information.

The type of data returned in type will be one of those listed in the discussion of the type parameter in the description of the function H5Pset_multi_type().

Use of this function is only appropriate for an HDF5 file written as a set of files with the MULTI file driver.

Since
1.6.0

◆ H5Pget_object_flush_cb()

herr_t H5Pget_object_flush_cb ( hid_t  plist_id,
H5F_flush_cb_t func,
void **  udata 
)

Retrieves the object flush property values from the file access property list.

Parameters
[in]plist_idFile access property list identifier
[in]funcThe user-defined callback function
[in]udataThe user-defined input data for the callback function
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_object_flush_cb() gets the user-defined callback function that is set in the file access property list fapl_id and stored in the parameter func. The callback is invoked whenever an object flush occurs in the file. This routine also obtains the user-defined input data that is passed along to the callback function in the parameter udata.

Example

The example below illustrates the usage of this routine to obtain the object flush property values.

hid_t fapl_id;
unsigned counter;
H5F_object_flush_t *ret_cb;
unsigned *ret_counter;
/* Create a copy of the file access property list */
/* Set up the object flush property values */
/* flush_cb: callback function to invoke when an object flushes (see below) */
/* counter: user data to pass along to the callback function */
H5Pset_object_flush_cb(fapl_id, flush_cb, &counter);
/* Open the file */
file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);
/* Get the file access property list for the file */
fapl = H5Fget_access_plist(file_id);
/* Retrieve the object flush property values for the file */
H5Pget_object_flush_cb(fapl, &ret_cb, &ret_counter);
/* ret_cb will point to flush_cb() */
/* ret_counter will point to counter */
/*
.
.
.
.
.
.
*/
/* The callback function for the object flush property */
static herr_t
flush_cb(hid_t obj_id, void *_udata)
{
unsigned *flush_ct = (unsigned *)_udata;
++(*flush_ct);
return 0;
}
#define H5F_ACC_RDWR
Definition H5Fpublic.h:49
int64_t hid_t
Definition H5Ipublic.h:60
int herr_t
Definition H5public.h:235
herr_t H5Pset_object_flush_cb(hid_t plist_id, H5F_flush_cb_t func, void *udata)
Sets a callback function to invoke when an object flush occurs in the file.
herr_t H5Pget_object_flush_cb(hid_t plist_id, H5F_flush_cb_t *func, void **udata)
Retrieves the object flush property values from the file access property list.
Since
1.10.0

◆ H5Pget_page_buffer_size()

herr_t H5Pget_page_buffer_size ( hid_t  plist_id,
size_t *  buf_size,
unsigned *  min_meta_perc,
unsigned *  min_raw_perc 
)

Retrieves the maximum size for the page buffer and the minimum percentage for metadata and raw data pages.

Parameters
[in]plist_idFile access property list identifier
[out]buf_sizeMaximum size, in bytes, of the page buffer
[out]min_meta_percMinimum metadata percentage to keep in the page buffer before allowing pages containing metadata to be evicted
[out]min_raw_percMinimum raw data percentage to keep in the page buffer before allowing pages containing raw data to be evicted
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_page_buffer_size() retrieves buf_size, the maximum size in bytes of the page buffer, min_meta_perc, the minimum metadata percentage, and min_raw_perc, the minimum raw data percentage.

Since
1.10.1

◆ H5Pget_relax_file_integrity_checks()

herr_t H5Pget_relax_file_integrity_checks ( hid_t  plist_id,
uint64_t *  flags 
)

Retrieve relaxed file integrity check flags.

Parameters
[in]plist_idFile access property list identifier
[out]flagsRelaxed file integrity check flags
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_relax_file_integrity_checks() retrieves the relaxed file integrity check value into flags for the file access property list specified in plist_id.

Since
1.14.4

◆ H5Pget_sieve_buf_size()

herr_t H5Pget_sieve_buf_size ( hid_t  fapl_id,
size_t *  size 
)

Returns maximum data sieve buffer size.

Parameters
[in]fapl_idFile access property list identifier
[out]sizeMaximum size, in bytes, of data sieve buffer
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_sieve_buf_size() retrieves, size, the current maximum size of the data sieve buffer.

This value is set by H5Pset_sieve_buf_size() and is retrieved from the file access property list fapl_id.

Version
1.6.0 The size parameter has changed from type hsize_t to size_t
Since
1.4.0

◆ H5Pget_small_data_block_size()

herr_t H5Pget_small_data_block_size ( hid_t  fapl_id,
hsize_t size 
)

Retrieves the current small data block size setting.

Parameters
[in]fapl_idFile access property list identifier
[out]sizeMaximum size, in bytes, of the small data block
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_small_data_block_size() retrieves the current setting for the size of the small data block.

If the returned value is zero (0), the small data block mechanism has been disabled for the file.

Since
1.4.4

◆ H5Pget_vol_cap_flags()

herr_t H5Pget_vol_cap_flags ( hid_t  plist_id,
uint64_t *  cap_flags 
)

Query the capability flags for the VOL connector that will be used with this file access property list (FAPL).

Parameters
[in]plist_idFile access property list identifier
[out]cap_flagsFlags that indicate the VOL connector capabilities
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_vol_cap_flags() queries the current VOL connector information for a FAPL to retrieve the capability flags for the VOL connector stack, as will be used by a file open or create operation that uses this FAPL.

Note
This routine supports the use of the HDF5_VOL_CONNECTOR environment variable to override the VOL connector set programmatically for the FAPL (with H5Pset_vol).
The H5VL_CAP_FLAG_ASYNC flag can be checked to see if asynchronous operations are supported by the VOL connector stack.
Since
1.14.0

◆ H5Pget_vol_id()

herr_t H5Pget_vol_id ( hid_t  plist_id,
hid_t vol_id 
)

Returns the identifier of the current VOL connector.

Parameters
[in]plist_idFile access property list identifier
[out]vol_idCurrent VOL connector identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_vol_id() returns the VOL connector identifier vol_id for the file access property list plist_id. This identifier should be closed with H5VLclose().

Since
1.12.0

◆ H5Pget_vol_info()

herr_t H5Pget_vol_info ( hid_t  plist_id,
void **  vol_info 
)

Returns a copy of the VOL information for a connector.

Parameters
[in]plist_idFile access property list identifier
[out]vol_infoThe VOL information for a connector
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pget_vol_info() returns a copy of the VOL information vol_info for a connector specified by the file access property list plist_id.

Since
1.12.0

◆ H5Pset_alignment()

herr_t H5Pset_alignment ( hid_t  fapl_id,
hsize_t  threshold,
hsize_t  alignment 
)

Sets alignment properties of a file access property list.

Parameters
[in]fapl_idFile access property list identifier
[in]thresholdThreshold value. Note that setting the threshold value to 0 (zero) has the effect of a special case, forcing everything to be aligned
[in]alignmentAlignment value
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_alignment() sets the alignment properties of a file access property list so that any file object greater than or equal in size to threshold bytes will be aligned on an address that is a multiple of alignment. The addresses are relative to the end of the user block; the alignment is calculated by subtracting the user block size from the absolute file address and then adjusting the address to be a multiple of alignment.

Default values for threshold and alignment are one, implying no alignment. Generally the default values will result in the best performance for single-process access to the file. For MPI IO and other parallel systems, choose an alignment that is a multiple of the disk block size.

If the file space handling strategy is set to H5F_FSPACE_STRATEGY_PAGE, then the alignment set via this routine is ignored. The file space handling strategy is set by H5Pset_file_space_strategy().

Since
1.0.0

◆ H5Pset_cache()

herr_t H5Pset_cache ( hid_t  plist_id,
int  mdc_nelmts,
size_t  rdcc_nslots,
size_t  rdcc_nbytes,
double  rdcc_w0 
)

Sets the raw data chunk cache parameters.

Parameters
[in]plist_idFile access property list identifier
[in]mdc_nelmtsNo longer used; any value passed is ignored
[in]rdcc_nslotsThe number of chunk slots in the raw data chunk cache for this dataset. Increasing this value reduces the number of cache collisions, but slightly increases the memory used. Due to the hashing strategy, this value should ideally be a prime number. As a rule of thumb, this value should be at least 10 times the number of chunks that can fit in rdcc_nbytes bytes. For maximum performance, this value should be set approximately 100 times that number of chunks. The default value is 521.
[in]rdcc_nbytesTotal size of the raw data chunk cache in bytes. The default size is 1 MB per dataset.
[in]rdcc_w0The chunk preemption policy for all datasets. This must be between 0 and 1 inclusive and indicates the weighting according to which chunks which have been fully read or written are penalized when determining which chunks to flush from cache. A value of 0 means fully read or written chunks are treated no differently than other chunks (the preemption is strictly LRU), while a value of 1 means fully read or written chunks are always preempted before other chunks. If your application only reads or writes data once, this can be safely set to 1. Otherwise, this should be set lower depending on how often you re-read or re-write the same data. The default value is 0.75. If the value passed is H5D_CHUNK_CACHE_W0_DEFAULT, then the property will not be set on the dataset access property list, and the parameter will come from the file access property list.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_cache() sets the number of elements, the total number of bytes, and the preemption policy value for all datasets in a file on the file's file access property list.

The raw data chunk cache inserts chunks into the cache by first computing a hash value using the address of a chunk and then by using that hash value as the chunk's index into the table of cached chunks. In other words, the size of this hash table and the number of possible hash values are determined by the rdcc_nslots parameter. If a different chunk in the cache has the same hash value, a collision will occur, which will reduce efficiency. If inserting the chunk into the cache would cause the cache to be too big, then the cache will be pruned according to the rdcc_w0 parameter.

The mdc_nelmts parameter is no longer used; any value passed in that parameter will be ignored.

Motivation: Setting raw data chunk cache parameters can be done with H5Pset_cache(), H5Pset_chunk_cache(), or a combination of both. H5Pset_cache() is used to adjust the chunk cache parameters for all datasets via a global setting for the file, and H5Pset_chunk_cache() is used to adjust the chunk cache parameters for individual datasets. When both are used, parameters set with H5Pset_chunk_cache() will override any parameters set with H5Pset_cache().

Note
Optimum chunk cache parameters may vary widely depending on different data layout and access patterns. For datasets with low performance requirements for example, changing the cache settings can save memory.
Note: Raw dataset chunk caching is not currently supported when using the MPI I/O and MPI POSIX file drivers in read/write mode; see H5Pset_fapl_mpio(). When using this file driver, all calls to H5Dread() and H5Dwrite() will access the disk directly, and H5Pset_cache() will have no effect on performance.
Raw dataset chunk caching is supported when these drivers are used in read-only mode.
Version
1.8.0 The use of the mdc_nelmts parameter was discontinued. Metadata cache configuration is managed with H5Pset_mdc_config() and H5Pget_mdc_config().
1.6.0 The rdcc_nbytes and rdcc_nelmts parameters changed from type int to size_t.
Since
1.0.0

◆ H5Pset_coll_metadata_write()

herr_t H5Pset_coll_metadata_write ( hid_t  plist_id,
hbool_t  is_collective 
)

Sets metadata write mode to be collective or independent (default)

Parameters
[in]plist_idFile access property list identifier
[out]is_collectiveBoolean value indicating whether metadata writes are collective (>0) or independent (0). Default mode: Independent (0)
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_coll_metadata_write() tells the HDF5 library whether to perform metadata writes collectively (1) or independently (0).

If collective access is selected, then on a flush of the metadata cache, all processes will divide the metadata cache entries to be flushed evenly among themselves and issue a single MPI-IO collective write operation. This is the preferred method when the size of the metadata created by the application is large.

If independent access is selected, the library uses the default method for doing metadata I/O either from process zero or independently from each process.

See also
Since
1.10.0

◆ H5Pset_core_write_tracking()

herr_t H5Pset_core_write_tracking ( hid_t  fapl_id,
hbool_t  is_enabled,
size_t  page_size 
)

Sets write tracking information for core driver, H5FD_CORE.

Parameters
[in]fapl_idFile access property list identifier
[in]is_enabledBoolean value specifying whether feature is enabled
[in]page_sizePositive integer specifying size, in bytes, of write aggregation pages Value of 1 (one) enables tracking with no paging.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

When a file is created or opened for writing using the core virtual file driver (VFD) with the backing store option turned on, the core driver can be configured to track changes to the file and write out only the modified bytes.

This write tracking feature is enabled and disabled with is_enabled. The default setting is that write tracking is disabled, or off.

To avoid a large number of small writes, changes can be aggregated into pages of a user-specified size, page_size.

Setting page_size to 1 enables tracking with no page aggregation.

The backing store option is set via the function H5Pset_fapl_core.

Attention

This function is only for use with the core VFD and must be used after the call to H5Pset_fapl_core(). It is an error to use this function with any other VFD.

It is an error to use this function when the backing store flag has not been set using H5Pset_fapl_core().

This function only applies to the backing store write operation which typically occurs when the file is flushed or closed. This function has no relationship to the increment parameter passed to H5Pset_fapl_core().

For optimum performance, the page_size parameter should be a power of two.

It is an error to set the page size to 0.

Version
1.8.14 C function modified in this release to return error if page_size is set to 0 (zero).
Since
1.8.13

◆ H5Pset_driver()

herr_t H5Pset_driver ( hid_t  plist_id,
hid_t  driver_id,
const void *  driver_info 
)

Sets a file driver.

Parameters
[in]plist_idProperty list identifier
[in]driver_idThe new driver identifier
[in]driver_infoOptional struct containing driver properties
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_driver() sets the file driver, driver_id, for a file access or data transfer property list, plist_id, and supplies an optional struct containing the driver-specific properties, driver_info.

The driver properties will be copied into the property list and the reference count on the driver will be incremented, allowing the caller to close the driver identifier but still use the property list.

Version
1.8.2 Function publicized in this release; previous releases described this function only in the virtual file driver documentation.
Since
1.4.0

◆ H5Pset_driver_by_name()

herr_t H5Pset_driver_by_name ( hid_t  plist_id,
const char *  driver_name,
const char *  driver_config 
)

Sets a file driver according to a given driver name.

Parameters
[in]plist_idProperty list identifier
[in]driver_nameThe new driver name
[in]driver_configOptional string containing driver properties
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_driver_by_name() sets the file driver, by the name driver_name, for a file access or data transfer property list, plist_id, and supplies an optional string containing the driver-specific properties, driver_config. The driver properties string will be copied into the property list.

If the driver specified by driver_name is not currently registered, an attempt will be made to load the driver as a plugin.

Since
1.14.0

◆ H5Pset_driver_by_value()

herr_t H5Pset_driver_by_value ( hid_t  plist_id,
H5FD_class_value_t  driver_value,
const char *  driver_config 
)

Sets a file driver according to a given driver value (ID).

Parameters
[in]plist_idProperty list identifier
[in]driver_valueThe new driver value (ID)
[in]driver_configOptional string containing driver properties
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_driver_by_value() sets the file driver, by the value driver_value, for a file access or data transfer property list, plist_id, and supplies an optional string containing the driver-specific properties, driver_config. The driver properties string will be copied into the property list.

If the driver specified by driver_value is not currently registered, an attempt will be made to load the driver as a plugin.

Since
1.14.0

◆ H5Pset_elink_file_cache_size()

herr_t H5Pset_elink_file_cache_size ( hid_t  plist_id,
unsigned  efc_size 
)

Sets the number of files that can be held open in an external link open file cache.

Motivation

The external link open file cache holds files open after they have been accessed via an external link. This cache reduces the number of times such files are opened when external links are accessed repeatedly and can significantly improves performance in certain heavy-use situations and when low-level file opens or closes are expensive.

H5Pset_elink_file_cache_size() sets the number of files that will be held open in an external link open file cache. H5Pget_elink_file_cache_size() retrieves the size of an existing cache; and H5Fclear_elink_file_cache() clears an existing cache without closing it.

Parameters
[in]plist_idFile access property list identifier
[in]efc_sizeExternal link open file cache size in number of files Default setting is 0 (zero).
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_elink_file_cache_size() specifies the number of files that will be held open in an external link open file cache.

The default external link open file cache size is 0 (zero), meaning that files accessed via an external link are not held open. Setting the cache size to a positive integer turns on the cache; setting the size back to zero turns it off.

With this property set, files are placed in the external link open file cache cache when they are opened via an external link. Files are then held open until either they are evicted from the cache or the parent file is closed. This property setting can improve performance when external links are repeatedly accessed.

When the cache is full, files will be evicted using a least recently used (LRU) scheme; the file which has gone the longest time without being accessed through the parent file will be evicted and closed if nothing else is holding that file open.

Files opened through external links inherit the parent file's file access property list by default, and therefore inherit the parent file's external link open file cache setting.

When child files contain external links of their own, the caches can form a graph of cached external files. Closing the last external reference to such a graph will recursively close all files in the graph, even if cycles are present.

Example

The following code sets up an external link open file cache that will hold open up to 8 files reached through external links:

status = H5Pset_elink_file_cache_size(fapl_id, 8);
herr_t H5Pset_elink_file_cache_size(hid_t plist_id, unsigned efc_size)
Sets the number of files that can be held open in an external link open file cache.
Since
1.8.7

◆ H5Pset_evict_on_close()

herr_t H5Pset_evict_on_close ( hid_t  fapl_id,
hbool_t  evict_on_close 
)

Controls the library's behavior of evicting metadata associated with a closed object.

Parameters
[in]fapl_idFile access property list identifier
[in]evict_on_closeWhether the HDF5 object should be evicted on close
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

The library's metadata cache is fairly conservative about holding on to HDF5 object metadata(object headers, chunk index structures, etc.), which can cause the cache size to grow, resulting in memory pressure on an application or system. When enabled, the "evict on close" property will cause all metadata for an object to be evicted from the cache as long as metadata is not referenced by any other open object.

This function only applies to file access property lists.

The default library behavior is to not evict on object or file close.

When applied to a file access property list, any subsequently opened object will inherit the "evict on close" property and will have its metadata evicted when the object is closed.

Since
1.10.1

◆ H5Pset_family_offset()

herr_t H5Pset_family_offset ( hid_t  fapl_id,
hsize_t  offset 
)

Sets offset property for low-level access to a file in a family of files.

Parameters
[in]fapl_idFile access property list identifier
[in]offsetOffset in bytes within the HDF5 file
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_family_offset() sets the offset property in the file access property list fapl_id so that the user application can retrieve a file handle for low-level access to a particular member of a family of files. The file handle is retrieved with a separate call to H5Fget_vfd_handle() (or, in special circumstances, to H5FDget_vfd_handle(); see HDF5 Virtual File Layer).

The value of offset is an offset in bytes from the beginning of the HDF5 file, identifying a user-determined location within the HDF5 file. The file handle the user application is seeking is for the specific member-file in the associated family of files to which this offset is mapped.

Use of this function is only appropriate for an HDF5 file written as a family of files with the FAMILY file driver.

Since
1.6.0

◆ H5Pset_fapl_core()

H5_DLL herr_t H5Pset_fapl_core ( hid_t  fapl_id,
size_t  increment,
hbool_t  backing_store 
)

Modifies the file access property list to use the H5FD_CORE driver.

Parameters
[in]fapl_idFile access property list identifier
[in]incrementSize, in bytes, of memory increments
[in]backing_storeBoolean flag indicating whether to write the file contents to disk when the file is closed
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_core() modifies the file access property list to use the H5FD_CORE driver.

The H5FD_CORE driver enables an application to work with a file in memory, speeding reads and writes as no disk access is made. File contents are stored only in memory until the file is closed. The backing_store parameter determines whether file contents are ever written to disk.

increment specifies the increment by which allocated memory is to be increased each time more memory is required.

While using H5Fcreate() to create a core file, if the backing_store is set to 1 (true), the file contents are flushed to a file with the same name as this core file when the file is closed or access to the file is terminated in memory.

The application is allowed to open an existing file with H5FD_CORE driver. While using H5Fopen() to open an existing file, if the backing_store is set to 1 (true) and the flags for H5Fopen() is set to H5F_ACC_RDWR, any change to the file contents are saved to the file when the file is closed. If backing_store is set to 0 (false) and the flags for H5Fopen() is set to H5F_ACC_RDWR, any change to the file contents will be lost when the file is closed. If the flags for H5Fopen() is set to H5F_ACC_RDONLY, no change to the file is allowed either in memory or on file.

Note
Currently this driver cannot create or open family or multi files.
Since
1.4.0

◆ H5Pset_fapl_direct()

H5_DLL herr_t H5Pset_fapl_direct ( hid_t  fapl_id,
size_t  alignment,
size_t  block_size,
size_t  cbuf_size 
)

Sets up use of the direct I/O driver.

Parameters
[in]fapl_idFile access property list identifier
[in]alignmentRequired memory alignment boundary
[in]block_sizeFile system block size
[in]cbuf_sizeCopy buffer size
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_direct() sets the file access property list, fapl_id, to use the direct I/O driver, H5FD_DIRECT. With this driver, data is written to or read from the file synchronously without being cached by the system.

File systems usually require the data address in memory, the file address, and the size of the data to be aligned. The HDF5 library's direct I/O driver is able to handle unaligned data, though that will consume some additional memory resources and may slow performance. To get better performance, use the system function posix_memalign to align the data buffer in memory and the HDF5 function H5Pset_alignment() to align the data in the file. Be aware, however, that aligned data I/O may cause the HDF5 file to be bigger than the actual data size would otherwise require because the alignment may leave some holes in the file.

alignment specifies the required alignment boundary in memory.

block_size specifies the file system block size. A value of 0 (zero) means to use HDF5 library's default value of 4KB.

cbuf_size specifies the copy buffer size.

Since
1.8.0

◆ H5Pset_fapl_family()

H5_DLL herr_t H5Pset_fapl_family ( hid_t  fapl_id,
hsize_t  memb_size,
hid_t  memb_fapl_id 
)

Sets the file access property list to use the family driver.

Parameters
[in]fapl_idFile access property list identifier
[in]memb_sizeSize in bytes of each file member
[in]memb_fapl_idIdentifier of file access property list for each family member
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_family() sets the file access property list identifier, fapl_id, to use the family driver.

memb_size is the size in bytes of each file member. This size will be saved in file when the property list fapl_id is used to create a new file. If fapl_id is used to open an existing file, memb_size has to be equal to the original size saved in file. A failure with an error message indicating the correct member size will be returned if memb_size does not match the size saved. If any user does not know the original size, H5F_FAMILY_DEFAULT can be passed in. The library will retrieve the saved size.

memb_fapl_id is the identifier of the file access property list to be used for each family member.

Version
1.8.0 Behavior of the memb_size parameter was changed.
Since
1.4.0

◆ H5Pset_fapl_hdfs()

H5_DLL herr_t H5Pset_fapl_hdfs ( hid_t  fapl_id,
H5FD_hdfs_fapl_t fa 
)

Modifies the file access property list to use the H5FD_HDFS driver.

Parameters
[in]fapl_idFile access property list identifier
[in]faPointer to H5FD_HDFS driver configuration structure
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_hdfs() modifies the file access property list to use the H5FD_HDFS driver.

Since
1.10.6

◆ H5Pset_fapl_ioc()

H5_DLL herr_t H5Pset_fapl_ioc ( hid_t  fapl_id,
H5FD_ioc_config_t vfd_config 
)

Modifies the specified File Access Property List to use the H5FD_IOC driver.

Parameters
[in]fapl_idFile access property list identifier
[in]vfd_configPointer to H5FD_IOC driver configuration structure. May be NULL.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_ioc() modifies the File Access Property List to use the H5FD_IOC driver.

The H5FD_IOC driver is a reference implementation of an "I/O concentrator" file driver that works in conjunction with the H5FD_SUBFILING driver and provides the I/O backend for servicing I/O requests to subfiles.

Typically, an HDF5 application won't need to call this routine directly. The H5FD_IOC driver is usually set up as a side effect of an HDF5 application using the H5FD_SUBFILING driver, but this routine is provided in case the application wishes to manually configure the H5FD_IOC driver.

Note
The vfd_config parameter may be NULL. In this case, the driver will be setup with default settings. Note that in this case, it is assumed the parent H5FD_SUBFILING driver was also setup with default settings. If the two drivers differ in configuration settings, application behavior may not be as expected.
Since
1.14.0

◆ H5Pset_fapl_log()

H5_DLL herr_t H5Pset_fapl_log ( hid_t  fapl_id,
const char *  logfile,
unsigned long long  flags,
size_t  buf_size 
)

Sets up the logging virtual file driver (H5FD_LOG) for use.

Parameters
[in]fapl_idFile access property list identifier
[in]logfileName of the log file
[in]flagsFlags specifying the types of logging activity
[in]buf_sizeThe size of the logging buffers, in bytes (see description)
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_log() modifies the file access property list to use the logging driver, H5FD_LOG. The logging virtual file driver (VFD) is a clone of the standard SEC2 (H5FD_SEC2) driver with additional facilities for logging VFD metrics and activity to a file.

logfile is the name of the file in which the logging entries are to be recorded.

The actions to be logged are specified in the parameter flags using the pre-defined constants described in the following table. Multiple flags can be set through the use of a logical OR contained in parentheses. For example, logging read and write locations would be specified as (H5FD_LOG_LOC_READ|H5FD_LOG_LOC_WRITE).

Table1: Logging Flags
H5FD_LOG_LOC_READ Track the location and length of every read, write, or seek operation.
H5FD_LOG_LOC_WRITE
H5FD_LOG_LOC_SEEK
H5FD_LOG_LOC_IO Track all I/O locations and lengths. The logical equivalent of the following: (H5FD_LOG_LOC_READ | H5FD_LOG_LOC_WRITE | H5FD_LOG_LOC_SEEK)
H5FD_LOG_FILE_READ Track the number of times each byte is read or written.
H5FD_LOG_FILE_WRITE
H5FD_LOG_FILE_IO Track the number of times each byte is read and written. The logical equivalent of the following: (H5FD_LOG_FILE_READ | H5FD_LOG_FILE_WRITE)
H5FD_LOG_FLAVOR Track the type, or flavor, of information stored at each byte.
H5FD_LOG_NUM_READ Track the total number of read, write, seek, or truncate operations that occur.
H5FD_LOG_NUM_WRITE
H5FD_LOG_NUM_SEEK
H5FD_LOG_NUM_TRUNCATE
H5FD_LOG_NUM_IO Track the total number of all types of I/O operations. The logical equivalent of the following: (H5FD_LOG_NUM_READ | H5FD_LOG_NUM_WRITE | H5FD_LOG_NUM_SEEK | H5FD_LOG_NUM_TRUNCATE)
H5FD_LOG_TIME_OPEN Track the time spent in open, stat, read, write, seek, or close operations.
H5FD_LOG_TIME_STAT
H5FD_LOG_TIME_READ
H5FD_LOG_TIME_WRITE
H5FD_LOG_TIME_SEEK
H5FD_LOG_TIME_CLOSE
H5FD_LOG_TIME_IO Track the time spent in each of the above operations. The logical equivalent of the following: (H5FD_LOG_TIME_OPEN | H5FD_LOG_TIME_STAT | H5FD_LOG_TIME_READ | H5FD_LOG_TIME_WRITE | H5FD_LOG_TIME_SEEK | H5FD_LOG_TIME_CLOSE)
H5FD_LOG_ALLOC Track the allocation of space in the file.
H5FD_LOG_ALL Track everything. The logical equivalent of the following: (H5FD_LOG_ALLOC | H5FD_LOG_TIME_IO | H5FD_LOG_NUM_IO | H5FD_LOG_FLAVOR | H5FD_LOG_FILE_IO | H5FD_LOG_LOC_IO)

The logging driver can track the number of times each byte in the file is read from or written to (using H5FD_LOG_FILE_READ and H5FD_LOG_FILE_WRITE) and what kind of data is at that location (e.g., metadata, raw data; using H5FD_LOG_FLAVOR). This information is tracked in internal buffers of size buf_size, which must be at least the maximum size in bytes of the file to be logged while the log driver is in use.
One buffer of size buf_size will be created for each of H5FD_LOG_FILE_READ, H5FD_LOG_FILE_WRITE and H5FD_LOG_FLAVOR when those flags are set; these buffers will not grow as the file increases in size.

Output:
This section describes the logging driver (LOG VFD) output.
The table, immediately below, describes output of the various logging driver flags and function calls. A list of valid flavor values, describing the type of data stored, follows the table.
Table2: Logging Output
FlagVFD CallOutput and Comments
H5FD_LOG_LOC_READ Read %10a-%10a (%10Zu bytes) (s) Read

Start position
End position
Number of bytes
Flavor of read

Adds (%f s) and seek time if H5FD_LOG_TIME_SEEK is also set.
H5FD_LOG_LOC_READ Read Error Error! Reading: %10a-%10a (%10Zu bytes)

Same parameters as non-error entry.
H5FD_LOG_LOC_WRITE Write %10a-%10a (%10Zu bytes) (s) Written

Start position
End position
Number of bytes
Flavor of write

Adds (%f s) and seek time if H5FD_LOG_TIME_SEEK is also set.
H5FD_LOG_LOC_WRITE Write Error Error! Writing: %10a-%10a (%10Zu bytes)

Same parameters as non-error entry.
H5FD_LOG_LOC_SEEK Read, Write Seek: From %10a-%10a

Start position
End position

Adds (%f s) and seek time if H5FD_LOG_TIME_SEEK is also set.
H5FD_LOG_FILE_READ Close Begins with:
Dumping read I/O information

Then, for each range of identical values, there is this line:
Addr %10-%10 (%10lu bytes) read from %3d times

Start address
End address
Number of bytes
Number of times read

Note: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read.
H5FD_LOG_FILE_WRITE Close Begins with:
Dumping read I/O information

Then, for each range of identical values, there is this line:
Addr %10-%10 (%10lu bytes) written to %3d times

Start address
End address
Number of bytes
Number of times written

Note: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read.
H5FD_LOG_FLAVOR Close Begins with:
Dumping I/O flavor information

Then, for each range of identical values, there is this line:
Addr %10-%10 (%10lu bytes) flavor is s

Start address
End address
Number of bytes
Flavor

Note: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read.
H5FD_LOG_NUM_READ Close Total number of read operations: %11u
H5FD_LOG_NUM_WRITE Close Total number of write operations: %11u
H5FD_LOG_NUM_SEEK Close Total number of seek operations: %11u
H5FD_LOG_NUM_TRUNCATE Close Total number of truncate operations: %11u
H5FD_LOG_TIME_OPEN Open Open took: (%f s)
H5FD_LOG_TIME_READ Close, Read Total time in read operations: %f s

See also: H5FD_LOG_LOC_READ
H5FD_LOG_TIME_WRITE Close, Write Total time in write operations: %f s

See also: H5FD_LOG_LOC_WRITE
H5FD_LOG_TIME_SEEK Close, Read, Write Total time in write operations: %f s

See also: H5FD_LOG_LOC_SEEK or H5FD_LOG_LOC_WRITE
H5FD_LOG_TIME_CLOSE Close Close took: (%f s)
H5FD_LOG_TIME_STAT Open Stat took: (%f s)
H5FD_LOG_ALLOC Alloc %10-%10 (%10Hu bytes) (%s) Allocated

Start of address space
End of address space
Total size allocation
Flavor of allocation
Flavors:
The flavor describes the type of stored information. The following table lists the flavors that appear in log output and briefly describes each. These terms are provided here to aid in the construction of log message parsers; a full description is beyond the scope of this document.
Table3: Flavors of logged data
FlavorDescription
H5FD_MEM_NOLIST Error value
H5FD_MEM_DEFAULT Value not yet set.
May also be a datatype set in a larger allocation that will be suballocated by the library.
H5FD_MEM_SUPER Superblock data
H5FD_MEM_BTREE B-tree data
H5FD_MEM_DRAW Raw data (for example, contents of a dataset)
H5FD_MEM_GHEAP Global heap data
H5FD_MEM_LHEAP Local heap data
H5FD_MEM_OHDR Object header data
Version
1.8.7 The flags parameter has been changed from unsigned int to unsigned long long. The implementation of the H5FD_LOG_TIME_OPEN, H5FD_LOG_TIME_READ, H5FD_LOG_TIME_WRITE, and H5FD_LOG_TIME_SEEK flags has been finished. New flags were added: H5FD_LOG_NUM_TRUNCATE and H5FD_LOG_TIME_STAT.
1.6.0 The verbosity parameter has been removed. Two new parameters have been added: flags of type unsigned and buf_size of type size_t.
Since
1.4.0

◆ H5Pset_fapl_mirror()

H5_DLL herr_t H5Pset_fapl_mirror ( hid_t  fapl_id,
H5FD_mirror_fapl_t fa 
)

Modifies the file access property list to use the H5FD_MIRROR driver.

Parameters
[in]fapl_idFile access property list identifier
[in]faPointer to H5FD_MIRROR driver configuration structure
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_mirror() modifies the file access property list to use the H5FD_MIRROR driver.

Since
1.10.7

◆ H5Pset_fapl_mpio()

H5_DLL herr_t H5Pset_fapl_mpio ( hid_t  fapl_id,
MPI_Comm  comm,
MPI_Info  info 
)

Stores MPI IO communicator information to the file access property list.

Parameters
[in]fapl_idFile access property list identifier
[in]commMPI communicator
[in]infoMPI info object
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_mpio() stores the user-supplied MPI IO parameters comm, for communicator, and info, for information, in the file access property list fapl_id. That property list can then be used to create and/or open a file.

H5Pset_fapl_mpio() is available only in the parallel HDF5 library and is not a collective function.

comm is the MPI communicator to be used for file open, as defined in MPI_File_open of MPI. This function makes a duplicate of the communicator, so modifications to comm after this function call returns have no effect on the file access property list.

info is the MPI Info object to be used for file open, as defined in MPI_File_open() of MPI. This function makes a duplicate copy of the Info object, so modifications to the Info object after this function call returns will have no effect on the file access property list.

If the file access property list already contains previously-set communicator and Info values, those values will be replaced and the old communicator and Info object will be freed.

Note
Raw dataset chunk caching is not currently supported when using this file driver in read/write mode. All calls to H5Dread() and H5Dwrite() will access the disk directly, and H5Pset_cache() and H5Pset_chunk_cache() will have no effect on performance.
Raw dataset chunk caching is supported when this driver is used in read-only mode.
Version
1.4.5 Handling of the MPI Communicator and Info object changed at this release. A duplicate of each of these is now stored in the property list instead of pointers to each.
Since
1.4.0

◆ H5Pset_fapl_multi()

H5_DLL herr_t H5Pset_fapl_multi ( hid_t  fapl_id,
const H5FD_mem_t memb_map,
const hid_t memb_fapl,
const char *const *  memb_name,
const haddr_t memb_addr,
hbool_t  relax 
)

Sets up use of the multi-file driver.

Parameters
[in]fapl_idFile access property list identifier
[in]memb_mapMaps memory usage types to other memory usage types
[in]memb_faplProperty list for each memory usage type
[in]memb_nameName generator for names of member files
[in]memb_addrThe offsets within the virtual address space, from 0 (zero) to HADDR_MAX, at which each type of data storage begins
[in]relaxAllows read-only access to incomplete file sets when true
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_multi() sets the file access property list fapl_id to use the multi-file driver.

The multi-file driver enables different types of HDF5 data and metadata to be written to separate files. These files are viewed by the HDF5 library and the application as a single virtual HDF5 file with a single HDF5 file address space. The types of data that can be broken out into separate files include raw data, the superblock, B-tree data, global heap data, local heap data, and object headers. At the programmer's discretion, two or more types of data can be written to the same file while other types of data are written to separate files.

The array memb_map maps memory usage types to other memory usage types and is the mechanism that allows the caller to specify how many files are created. The array contains H5FD_MEM_NTYPES entries, which are either the value H5FD_MEM_DEFAULT or a memory usage type. The number of unique values determines the number of files that are opened.

The array memb_fapl contains a property list for each memory usage type that will be associated with a file.

The array memb_name should be a name generator (a printf-style format with a s which will be replaced with the name passed to H5FDopen(), usually from H5Fcreate() or H5Fopen()).

The array memb_addr specifies the offsets within the virtual address space, from 0 (zero) to HADDR_MAX, at which each type of data storage begins.

If relax is set to 1 (true), then opening an existing file for read-only access will not fail if some file members are missing. This allows a file to be accessed in a limited sense if just the meta data is available.

Default values for each of the optional arguments are as follows:

memb_map The default member map contains the value H5FD_MEM_DEFAULT for each element.
memb_fapl The default value is H5P_DEFAULT for each element.
memb_name The default string is s-X.h5 where X is one of the following letters:
memb_addr The default setting is that the address space is equally divided among all of the elements:
Example:
The following code sample sets up a multi-file access property list that partitions data into meta and raw files, each being one-half of the address:
const char *memb[H5FD_MEM_NTYPES];
// The mapping...
for (mt=0; mt<H5FD_MEM_NTYPES; mt++) {
memb_map[mt] = H5FD_MEM_SUPER;
}
// Member information
memb_name[H5FD_MEM_SUPER] = "%s.meta";
memb_addr[H5FD_MEM_SUPER] = 0;
memb_name[H5FD_MEM_DRAW] = "%s.raw";
memb_addr[H5FD_MEM_DRAW] = HADDR_MAX/2;
H5Pset_fapl_multi(fapl, memb_map, memb_fapl,
memb_name, memb_addr, true);
enum H5F_mem_t H5FD_mem_t
Definition H5FDpublic.h:260
@ H5FD_MEM_NTYPES
Definition H5Fpublic.h:168
@ H5FD_MEM_DRAW
Definition H5Fpublic.h:163
@ H5FD_MEM_SUPER
Definition H5Fpublic.h:161
#define HADDR_MAX
Definition H5public.h:334
uint64_t haddr_t
Definition H5public.h:325
H5_DLL herr_t H5Pset_fapl_multi(hid_t fapl_id, const H5FD_mem_t *memb_map, const hid_t *memb_fapl, const char *const *memb_name, const haddr_t *memb_addr, hbool_t relax)
Sets up use of the multi-file driver.
Version
1.6.3 memb_name parameter type changed to const char* const*.
Since
1.4.0

◆ H5Pset_fapl_onion()

H5_DLL herr_t H5Pset_fapl_onion ( hid_t  fapl_id,
const H5FD_onion_fapl_info_t fa 
)

set the onion info for the file access property list


Parameters
[in]fapl_idFile access property list identifier
[in]faThe pointer to the structure H5FD_onion_fapl_info_t
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_onion() sets the structure H5FD_onion_fapl_info_t for the file access property list that is set for the onion VFD driver.

Since
1.14.0

◆ H5Pset_fapl_ros3()

H5_DLL herr_t H5Pset_fapl_ros3 ( hid_t  fapl_id,
const H5FD_ros3_fapl_t fa 
)

Modifies the specified File Access Property List to use the H5FD_ROS3 driver.

Parameters
[in]fapl_idFile access property list identifier
[in]faPointer to H5FD_ROS3 driver configuration structure.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

◆ H5Pset_fapl_ros3_token()

H5_DLL herr_t H5Pset_fapl_ros3_token ( hid_t  fapl_id,
const char *  token 
)

Modifies the specified File Access Property List to use the H5FD_ROS3 driver by adding the specified session/security token.

Parameters
[in]fapl_idFile access property list identifier
[in]tokenSession/security token.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_ros3_token() modifies an existing File Access Property List which is used by H5FD_ROS3 driver by adding or updating the session/security token of the property list. Be aware, to set the token first you need to create a proper File Access Property List using H5Pset_fapl_ros() and use this list as input argument of the function H5Pset_fapl_ros3_token().

Note, the session token is only needed when you want to access a S3 bucket using temporary security credentials.

Since
1.14.2

◆ H5Pset_fapl_sec2()

H5_DLL herr_t H5Pset_fapl_sec2 ( hid_t  fapl_id)

Modifies the file access property list to use the H5FD_SEC2 driver.

Parameters
[in]fapl_idFile access property list identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_sec2() modifies the file access property list to use the H5FD_SEC2 driver.

Since
1.4.0

◆ H5Pset_fapl_split()

H5_DLL herr_t H5Pset_fapl_split ( hid_t  fapl,
const char *  meta_ext,
hid_t  meta_plist_id,
const char *  raw_ext,
hid_t  raw_plist_id 
)

Emulates the old split file driver.

Parameters
[in]faplFile access property list identifier
[in]meta_extMetadata filename extension
[in]meta_plist_idFile access property list identifier for the metadata file
[in]raw_extRaw data filename extension
[in]raw_plist_id
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_split() is a compatibility function that enables the multi-file driver to emulate the split driver from HDF5 Releases 1.0 and 1.2. The split file driver stored metadata and raw data in separate files but provided no mechanism for separating types of metadata.

fapl is a file access property list identifier.

meta_ext is the filename extension for the metadata file. The extension is appended to the name passed to H5FDopen(), usually from H5Fcreate() or H5Fopen(), to form the name of the metadata file. If the string s is used in the extension, it works like the name generator as in H5Pset_fapl_multi().

meta_plist_id is the file access property list identifier for the metadata file.

raw_ext is the filename extension for the raw data file. The extension is appended to the name passed to H5FDopen(), usually from H5Fcreate() or H5Fopen(), to form the name of the raw data file. If the string s is used in the extension, it works like the name generator as in H5Pset_fapl_multi().

raw_plist_id is the file access property list identifier for the raw data file.

If a user wishes to check to see whether this driver is in use, the user must call H5Pget_driver() and compare the returned value to the string H5FD_MULTI. A positive match will confirm that the multi driver is in use; HDF5 provides no mechanism to determine whether it was called as the special case invoked by H5Pset_fapl_split().

Example:
// Example 1: Both metadata and raw data files are in the same
// directory. Use Station1-m.h5 and Station1-r.h5 as
// the metadata and raw data files.
hid_t fapl, fid;
H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "-r.h5", H5P_DEFAULT);
fid=H5Fcreate("Station1",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
// Example 2: metadata and raw data files are in different
// directories. Use PointA-m.h5 and /pfs/PointA-r.h5 as
// the metadata and raw data files.
hid_t fapl, fid;
H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "/pfs/%s-r.h5", H5P_DEFAULT);
fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
#define H5F_ACC_TRUNC
Definition H5Fpublic.h:50
H5_DLL herr_t H5Pset_fapl_split(hid_t fapl, const char *meta_ext, hid_t meta_plist_id, const char *raw_ext, hid_t raw_plist_id)
Emulates the old split file driver.
hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id)
Creates an HDF5 file.
Since
1.4.0

◆ H5Pset_fapl_splitter()

H5_DLL herr_t H5Pset_fapl_splitter ( hid_t  fapl_id,
H5FD_splitter_vfd_config_t config_ptr 
)

Sets the file access property list to use the splitter driver.

Parameters
[in]fapl_idFile access property list identifier
[in]config_ptrConfiguration options for the VFD
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_splitter() sets the file access property list identifier, fapl_id, to use the splitter driver.

The splitter VFD echoes file manipulation (e.g. create, truncate) and write calls to a second, write-only file.

Note
The splitter VFD should not be confused with the split VFD, which is a simplification of the multi VFD and creates separate files for metadata and data.
Since
1.10.7, 1.12.1

◆ H5Pset_fapl_stdio()

herr_t H5Pset_fapl_stdio ( hid_t  fapl_id)

Sets the standard I/O driver.

Parameters
[in]fapl_idFile access property list identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_stdio() modifies the file access property list to use the stdio VFD, which uses I/O calls from stdio.h.

Note
This VFD was designed to be a "demo" VFD that shows how to write your own VFD. Most applications should not use this VFD and should instead use the POSIX I/O VFD (sec2).
Since
1.4.0

◆ H5Pset_fapl_subfiling()

H5_DLL herr_t H5Pset_fapl_subfiling ( hid_t  fapl_id,
const H5FD_subfiling_config_t vfd_config 
)

Modifies the specified File Access Property List to use the H5FD_SUBFILING driver.

Parameters
[in]fapl_idFile access property list identifier
[in]vfd_configPointer to H5FD_SUBFILING driver configuration structure. May be NULL.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_subfiling() modifies the File Access Property List to use the H5FD_SUBFILING driver.

The H5FD_SUBFILING driver is an MPI-based file driver that allows an HDF5 application to distribute a logical HDF5 file across a collection of "subfiles" in equal-sized data segment "stripes". I/O to the logical HDF5 file is then directed to the appropriate "subfile" according to the H5FD_SUBFILING configuration and a system of I/O concentrators, which are MPI ranks operating worker threads.

By allowing a configurable stripe size, number of I/O concentrators and method for selecting MPI ranks as I/O concentrators, the H5FD_SUBFILING driver aims to enable an HDF5 application to find a middle ground between the single shared file and file-per-process approaches to parallel file I/O for the particular machine the application is running on. In general, the goal is to avoid some of the complexity of the file-per-process approach while also minimizing the locking issues of the single shared file approach on a parallel file system.

Note
Since the H5FD_SUBFILING driver is an MPI-based file driver, the HDF5 application should ensure that H5Pset_mpi_params() is called before this routine so that the appropriate MPI communicator and info objects will be setup for use by the H5FD_SUBFILING and H5FD_IOC drivers.
The current architecture of the H5FD_SUBFILING driver requires that the HDF5 application must have been initialized with MPI_Init_thread() using a value of MPI_THREAD_MULTIPLE for the thread support level.
The vfd_config parameter may be NULL. In this case, the reference implementation I/O concentrator VFD will be used with the default settings of one I/O concentrator per node and a stripe size of 32MiB. Refer to the H5FD_subfiling_config_t documentation for information about configuration for the H5FD_SUBFILING driver.
Since
1.14.0

◆ H5Pset_fapl_windows()

H5_DLL herr_t H5Pset_fapl_windows ( hid_t  fapl_id)

Sets the Windows I/O driver.

Parameters
[in]fapl_idFile access property list identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fapl_windows() sets the default HDF5 Windows I/O driver on Windows systems.

Since the HDF5 library uses this driver, H5FD_WINDOWS, by default on Windows systems, it is not normally necessary for a user application to call H5Pset_fapl_windows(). While it is not recommended, there may be times when a user chooses to set a different HDF5 driver, such as the standard I/O driver (H5FD_STDIO) or the sec2 driver (H5FD_SEC2), in a Windows application. H5Pset_fapl_windows() is provided so that the application can return to the Windows I/O driver when the time comes.

Only the Windows driver is tested on Windows systems; other drivers are used at the application's and the user's risk.

Furthermore, the Windows driver is tested and available only on Windows systems; it is not available on non-Windows systems.

Since
1.8.0

◆ H5Pset_fclose_degree()

herr_t H5Pset_fclose_degree ( hid_t  fapl_id,
H5F_close_degree_t  degree 
)

Sets the file close degree.

Parameters
[in]fapl_idFile access property list identifier
[in]degreePointer to a location containing the file close degree property, the value of degree
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_fclose_degree() sets the file close degree property degree in the file access property list fapl_id.

The value of degree determines how aggressively H5Fclose() deals with objects within a file that remain open when H5Fclose() is called to close that file. degree can have any one of four valid values:

Degree name H5Fclose behavior with no open object in file H5Fclose behavior with open object(s) in file
H5F_CLOSE_WEAK Actual file is closed. Access to file identifier is terminated; actual file close is delayed until all objects in file are closed
H5F_CLOSE_SEMI Actual file is closed. Function returns FAILURE
H5F_CLOSE_STRONG Actual file is closed. All open objects remaining in the file are closed then file is closed
H5F_CLOSE_DEFAULT The VFL driver chooses the behavior. Currently, all VFL drivers set this value to H5F_CLOSE_WEAK, except for the MPI-I/O driver, which sets it to H5F_CLOSE_SEMI.

Warning
If a file is opened multiple times without being closed, each open operation must use the same file close degree setting. For example, if a file is already open with H5F_CLOSE_WEAK, an H5Fopen() call with H5F_CLOSE_STRONG will fail.
Since
1.6.0

◆ H5Pset_file_image()

herr_t H5Pset_file_image ( hid_t  fapl_id,
void *  buf_ptr,
size_t  buf_len 
)

Sets an initial file image in a memory buffer.

Parameters
[in]fapl_idFile access property list identifier
[in]buf_ptrPointer to the initial file image, or NULL if no initial file image is desired
[in]buf_lenSize of the supplied buffer, or 0 (zero) if no initial image is desired
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_file_image() allows an application to provide a file image to be used as the initial contents of a file. Calling H5Pset_file_image()makes a copy of the buffer specified in buf_ptr of size buf_len.

Motivation:
H5Pset_file_image() and other elements of HDF5 are used to load an image of an HDF5 file into system memory and open that image as a regular HDF5 file. An application can then use the file without the overhead of disk I/O.
Recommended Reading:
This function is part of the file image operations feature set. It is highly recommended to study the guide [HDF5 File Image Operations] (https://portal.hdfgroup.org/documentation/hdf5-docs/advanced_topics/file_image_ops.html ) before using this feature set. See the “See Also” section below for links to other elements of HDF5 file image operations.
See also
Version
1.8.13 Fortran subroutine added in this release.
Since
1.8.9

◆ H5Pset_file_image_callbacks()

herr_t H5Pset_file_image_callbacks ( hid_t  fapl_id,
H5FD_file_image_callbacks_t callbacks_ptr 
)

Sets the callbacks for working with file images.

Note
Motivation: H5Pset_file_image_callbacks() and other elements of HDF5 are used to load an image of an HDF5 file into system memory and open that image as a regular HDF5 file. An application can then use the file without the overhead of disk I/O.
Recommended Reading: This function is part of the file image operations feature set. It is highly recommended to study the guide [HDF5 File Image Operations] (https://portal.hdfgroup.org/documentation/hdf5-docs/advanced_topics/file_image_ops.html ) before using this feature set. See the “See Also” section below for links to other elements of HDF5 file image operations.
Parameters
[in]fapl_idFile access property list identifier
[in,out]callbacks_ptrPointer to the instance of the H5FD_file_image_callbacks_t structure
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Failure Modes: Due to interactions between this function and H5Pset_file_image() and H5Pget_file_image(), H5Pset_file_image_callbacks() will fail if a file image has already been set in the target file access property list, fapl_id.

H5Pset_file_image_callbacks() sets callback functions for working with file images in memory.

H5Pset_file_image_callbacks() allows an application to control the management of file image buffers through user defined callbacks. These callbacks can be used in the management of file image buffers in property lists and with certain file drivers.

H5Pset_file_image_callbacks() must be used before any file image has been set in the file access property list. Once a file image has been set, the function will fail.

The callback routines set up by H5Pset_file_image_callbacks() are invoked when a new file image buffer is allocated, when an existing file image buffer is copied or resized, or when a file image buffer is released from use.

Some file drivers allow the use of user-defined callback functions for allocating, freeing, and copying the driver's internal buffer, potentially allowing optimizations such as avoiding large malloc and memcpy operations, or to perform detailed logging.

From the perspective of the HDF5 library, the operations of the image_malloc, image_memcpy, image_realloc, and image_free callbacks must be identical to those of the corresponding C standard library calls (malloc, memcpy, realloc, and free). While the operations must be identical, the file image callbacks have more parameters. The return values of image_malloc and image_realloc are identical to the return values of malloc and realloc. The return values of image_malloc and image_free differ from the return values of memcpy and free in that the return values of image_memcpy and image_free can also indicate failure.

The callbacks and their parameters, along with a struct and an ENUM required for their use, are described below.

Callback struct and ENUM:

The callback functions set up by H5Pset_file_image_callbacks() use a struct and an ENUM that are defined as follows

The struct H5FD_file_image_callbacks_t serves as a container for the callback functions and a pointer to user-supplied data. The struct is defined as follows:

typedef struct {
void *(*image_malloc)(size_t size, H5FD_file_image_op_t file_image_op, void *udata);
void *(*image_memcpy)(void *dest, const void *src, size_t size, H5FD_file_image_op_t file_image_op,
void *udata);
void *(*image_realloc)(void *ptr, size_t size, H5FD_file_image_op_t file_image_op, void *udata);
herr_t (*image_free)(void *ptr, H5FD_file_image_op_t file_image_op, void *udata);
void *(*udata_copy)(void *udata);
herr_t (*udata_free)(void *udata);
void *udata;
H5FD_file_image_op_t
Definition H5FDpublic.h:266
Definition H5FDpublic.h:302

Elements of the H5FD_file_image_op_t are used by the callbacks to invoke certain operations on file images. The ENUM is defined as follows:

typedef enum {
@ H5FD_FILE_IMAGE_OP_PROPERTY_LIST_CLOSE
Definition H5FDpublic.h:278
@ H5FD_FILE_IMAGE_OP_NO_OP
Definition H5FDpublic.h:267
@ H5FD_FILE_IMAGE_OP_FILE_OPEN
Definition H5FDpublic.h:281
@ H5FD_FILE_IMAGE_OP_FILE_RESIZE
Definition H5FDpublic.h:289
@ H5FD_FILE_IMAGE_OP_PROPERTY_LIST_GET
Definition H5FDpublic.h:275
@ H5FD_FILE_IMAGE_OP_FILE_CLOSE
Definition H5FDpublic.h:292
@ H5FD_FILE_IMAGE_OP_PROPERTY_LIST_COPY
Definition H5FDpublic.h:272
@ H5FD_FILE_IMAGE_OP_PROPERTY_LIST_SET
Definition H5FDpublic.h:268

The elements of the H5FD_file_image_op_t are used in the following callbacks:

  • The image_malloc callback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C library malloc() call.
  • Signature in H5FD_file_image_callbacks_t:
    void *(*image_malloc)(size_t size, H5FD_file_image_op_t file_image_op, void *udata);

  • The image_memcpy callback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C library memcopy() call, except that it returns a NULL on failure. (The memcpy C Library routine is defined to return the dest parameter in all cases.)
  • Setting image_memcpy to NULL indicates that HDF5 should invoke the standard C library memcpy() routine when copying buffers.
  • Signature in H5FD_file_image_callbacks_t:
    void *(*image_memcpy)(void *dest, const void *src, size_t size, H5FD_file_image_op_t file_image_op,
    void *udata);

  • The image_realloc callback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C library realloc() call.
  • Setting image_realloc to NULL indicates that HDF5 should invoke the standard C library realloc() routine when resizing file image buffers.
  • Signature in H5FD_file_image_callbacks_t:
    void *(*image_realloc)(void *ptr, size_t size, H5FD_file_image_op_t file_image_op, void *udata);

  • The image_free callback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C library free() call, except that it will return 0 (SUCCEED) on success and -1 (FAIL) on failure.
  • Setting image_free to NULL indicates that HDF5 should invoke the standard C library free() routine when releasing file image buffers.
  • Signature in H5FD_file_image_callbacks_t:
    herr_t (*image_free)(void *ptr, H5FD_file_image_op_t file_image_op, void *udata);

  • The udata_copy callback contains a pointer to a function that, from the perspective of HDF5, allocates a buffer of suitable size, copies the contents of the supplied udata into the new buffer, and returns the address of the new buffer. The function returns NULL on failure. This function is necessary if a non-NULL udata parameter is supplied, so that property lists containing the image callbacks can be copied. If the udata parameter below is NULL, then this parameter should be NULL as well.
  • Signature in H5FD_file_image_callbacks_t:
    void *(*udata_copy)(void *udata);

  • The udata_free callback contains a pointer to a function that, from the perspective of HDF5, frees a user data block. This function is necessary if a non-NULL udata parameter is supplied so that property lists containing image callbacks can be discarded without a memory leak. If the udata parameter below is NULL, this parameter should be NULL as well.
  • Signature in H5FD_file_image_callbacks_t:
    herr_t (*udata_free)(void *udata);
  • **udata**, the final field in the H5FD_file_image_callbacks_t struct, provides a pointer to user-defined data. This pointer will be passed to the image_malloc, image_memcpy, image_realloc, and image_free callbacks. Define udata as NULL if no user-defined data is provided.
Since
1.8.9

◆ H5Pset_file_locking()

herr_t H5Pset_file_locking ( hid_t  fapl_id,
hbool_t  use_file_locking,
hbool_t  ignore_when_disabled 
)

Sets the file locking property values.

Parameters
[in]fapl_idFile access property list identifier
[in]use_file_lockingToggle to specify file locking (or not)
[in]ignore_when_disabledToggle to ignore when disabled (or not)
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_file_locking() overrides the default file locking flag setting that was set when the library was configured.

This setting can be overridden by the HDF5_USE_FILE_LOCKING environment variable.

File locking is used when creating/opening a file to prevent problematic file accesses.

Since
1.10.7

◆ H5Pset_gc_references()

herr_t H5Pset_gc_references ( hid_t  fapl_id,
unsigned  gc_ref 
)

Sets garbage collecting references flag.

Parameters
[in]fapl_idFile access property list identifier
[in]gc_refFlag setting reference garbage collection to on (1) or off (0)
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_gc_references() sets the flag for garbage collecting references for the file.

Dataset region references and other reference types use space in an HDF5 file's global heap. If garbage collection is on and the user passes in an uninitialized value in a reference structure, the heap might get corrupted. When garbage collection is off, however, and the user re-uses a reference, the previous heap block will be orphaned and not returned to the free heap space.

When garbage collection is on, the user must initialize the reference structures to 0 or risk heap corruption.

The default value for garbage collecting references is off.

Since
1.2.0

◆ H5Pset_libver_bounds()

herr_t H5Pset_libver_bounds ( hid_t  plist_id,
H5F_libver_t  low,
H5F_libver_t  high 
)

Controls the range of library release versions used when creating objects in a file.

Parameters
[in]plist_idFile access property list identifier
[in]lowThe earliest version of the library that will be used for writing objects
[in]highThe latest version of the library that will be used for writing objects
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_libver_bounds() controls the range of library release versions that will be used when creating objects in a file. The object format versions are determined indirectly from the library release versions specified in the call.

This property is set in the file access property list specified by the parameter fapl_id.

The parameter low sets the earliest possible format versions that the library will use when creating objects in the file. Note that earliest possible is different from earliest, as some features introduced in library versions later than 1.0.0 resulted in updates to object formats. The parameter high sets the latest format versions that the library will be allowed to use when creating objects in the file.

The parameters low and high must be one of the enumerated values in the H5F_libver_t struct, which is defined in H5Fpublic.h.

The macro H5F_LIBVER_LATEST is aliased to the highest enumerated value in H5F_libver_t, indicating that this is currently the latest format available.

The library supports the following pairs of (low, high) combinations as derived from the values in H5F_libver_t:

Value of low and high Result
low=H5F_LIBVER_EARLIEST
high=<any other version but not H5F_LIBVER_LATEST>
  • The library will create objects with the earliest possible format versions.
  • The library will allow objects to be created with the latest format versions available to library release specified in the high value.
  • API calls that create objects or features that are available to versions of the library greater than the specified version in high will fail.
low=H5F_LIBVER_V18
high=<any version higher than low but not H5F_LIBVER_LATEST>
  • The library will create objects with the latest format versions available to library release 1.8.x.
  • The library will allow objects to be created with the latest format versions available to library release specified in the high value.
  • API calls that create objects or features that are available to versions of the library greater than the specified version in high will fail.
  • Earlier versions of the library may not be able to access objects created with this setting.
low=H5F_LIBVER_V110
high=<any version higher than low but not H5F_LIBVER_LATEST>
  • The library will create objects with the latest format versions available to library release 1.10.x.
  • The library will allow objects to be created with the latest format versions available to library release specified in the high value.
  • API calls that create objects or features that are available to versions of the library greater than version specified in high will fail.
  • Earlier versions of the library may not be able to access objects created with this setting.
low=H5F_LIBVER_V112
high=<any version higher than low but not H5F_LIBVER_LATEST>
  • The library will create objects with the latest format versions available to library release 1.12.x.
  • The library will allow objects to be created with the latest format versions available to library release specified in the high value.
  • API calls that create objects or features that are available to versions of the library greater than version specified in high will fail.
  • Earlier versions of the library may not be able to access objects created with this setting.
low=H5F_LIBVER_V114
high=<any version higher than low but not H5F_LIBVER_LATEST>
  • The library will create objects with the latest format versions available to library release 1.14.x.
  • The library will allow objects to be created with the latest format versions available to library release specified in the high value.
  • API calls that create objects or features that are available to versions of the library greater than version specified in high will fail.
  • Earlier versions of the library may not be able to access objects created with this setting.
low=high
  • The library will create objects with the latest format versions available to library release specified.
  • The objects written with this setting may be accessible to a smaller range of library versions than would be the case if low is set to H5F_LIBVER_EARLIEST.
  • API calls that create objects or features that are available to versions of the library greater than the specified release will fail.
  • Earlier versions of the library may not be able to access objects created with this setting.
low=H5F_LIBVER_EARLIEST
high=H5F_LIBVER_LATEST
  • The library will create objects with the earliest possible format versions.
  • The library will allow objects to be created with the latest format versions available to the latest release. See note H5F_LIBVER_LATEST below the table.
  • This is the library default setting and provides the greatest format compatibility.
low=<any version lower than high>
high=H5F_LIBVER_LATEST
  • The library will create objects with the latest format versions available to library release low.
  • The library will allow objects to be created with the latest format versions available to the latest release. See note H5F_LIBVER_LATEST below the table.
  • This setting allows users to take advantage of the latest features and performance enhancements in the library.
  • Earlier versions of the library may not be able to access objects created with this setting.
low=H5F_LIBVER_LATEST
high=H5F_LIBVER_LATEST
  • The library will create objects with the latest format versions available to the latest release.
  • The library will allow objects to be created with the latest format versions available to the latest release. See note H5F_LIBVER_LATEST below the table.
  • This setting allows users to take advantage of the latest features and performance enhancements in the library. However, objects written with this setting may be accessible to a smaller range of library versions than would be the case if low is set to H5F_LIBVER_EARLIEST.
  • Earlier versions of the library may not be able to access objects created with this setting.
Note
H5F_LIBVER_LATEST:
Since 1.14.x is also H5F_LIBVER_LATEST, there is no upper limit on the format versions to use. That is, if a newer format version is required to support a feature in 1.14.x series, this setting will allow the object to be created.
Version
1.10.2 H5F_LIBVER_V18 added to the enumerated defines in H5F_libver_t.
Since
1.8.0

◆ H5Pset_mdc_config()

herr_t H5Pset_mdc_config ( hid_t  plist_id,
H5AC_cache_config_t config_ptr 
)

Set the initial metadata cache configuration in the indicated File Access Property List to the supplied value.

Parameters
[in]plist_idFile access property list identifier
[in]config_ptrPointer to the instance of H5AC_cache_config_t containing the desired configuration
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

The fields of the H5AC_cache_config_t structure are shown below:

(Click on a enumerator, field, or type for more information.)

H5Pset_mdc_config() attempts to set the initial metadata cache configuration to the supplied value. It will fail if an invalid configuration is detected. This configuration is used when the file is opened.

See the overview of the metadata cache in the special topics section of the user manual for details on what is being configured. If you have not read and understood that documentation, you really should not be using this API call.

Since
1.8.0

◆ H5Pset_mdc_image_config()

herr_t H5Pset_mdc_image_config ( hid_t  plist_id,
H5AC_cache_image_config_t config_ptr 
)

Sets the metadata cache image option for a file access property list.

Parameters
[in]plist_idFile access property list identifier
[out]config_ptrPointer to metadata cache image configuration values
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_mdc_image_config() sets the metadata cache image option with configuration values specified by config_ptr for the file access property list specified in plist_id.

H5AC_cache_image_config_t is defined as follows:

(Click on a enumerator, field, or type for more information.)

Limitations: While it is an obvious error to request a cache image when
opening the file read only, it is not in general possible to test for this error in the H5Pset_mdc_image_config() call. Rather than fail the subsequent file open, the library silently ignores the file image request in this case.
It is also an error to request a cache image on a file that does not support superblock extension messages (i.e. a superblock version less than 2). As above, it is not always possible to detect this error in the H5Pset_mdc_image_config() call, and thus the request for a cache image will fail silently in this case as well.
Creation of cache images is currently disabled in parallel – as above, any request for a cache image in this context will fail silently.
Files with cache images may be read in parallel applications, but note that the load of the cache image is a collective operation triggered by the first operation that accesses metadata after file open (or, if persistent free space managers are enabled, on the first allocation or deallocation of file space, or read of file space manager status, whichever comes first). Thus the parallel process may deadlock if any process does not participate in this access.
In long sequences of file closes and opens, infrequently accessed metadata can accumulate in the cache image to the point where the cost of storing and restoring this metadata exceeds the benefit of retaining frequently used metadata in the cache image. When implemented, the H5AC_cache_image_config_t::entry_ageout should address this problem. In the interim, not requesting a cache image every n file close/open cycles may be an acceptable work around. The choice of n will be driven by application behavior, but n = 10 seems a good starting point.
Since
1.10.1

◆ H5Pset_mdc_log_options()

herr_t H5Pset_mdc_log_options ( hid_t  plist_id,
hbool_t  is_enabled,
const char *  location,
hbool_t  start_on_access 
)

Sets metadata cache logging options.

Parameters
[in]plist_idFile access property list identifier
[in]is_enabledWhether logging is enabled
[in]locationLocation of log in UTF-8/ASCII (file path/name) (On Windows, this must be ASCII)
[in]start_on_accessWhether the logging will begin as soon as the file is opened or created
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

The metadata cache is a central part of the HDF5 library through which all file metadata reads and writes take place. File metadata is normally invisible to the user and is used by the library for purposes such as locating and indexing data. File metadata should not be confused with user metadata, which consists of attributes created by users and attached to HDF5 objects such as datasets via H5A API calls.

Due to the complexity of the cache, a trace/logging feature has been created that can be used by HDF5 developers for debugging and performance analysis. The functions that control this functionality will normally be of use to a very limited number of developers outside of The HDF Group. The functions have been documented to help users create logs that can be sent with bug reports.

Control of the log functionality is straightforward. Logging is enabled via the H5Pset_mdc_log_options() function, which will modify the file access property list used to open or create a file. This function has a flag that determines whether logging begins at file open or starts in a paused state. Log messages can then be controlled via the H5Fstart_mdc_logging() and H5Fstop_mdc_logging() function.

H5Pget_mdc_log_options() can be used to examine a file access property list, and H5Fget_mdc_logging_status() will return the current state of the logging flags.

The log format is described in [Metadata Cache Logging] (https://portal.hdfgroup.org/display/HDF5/Fine-tuning+the+Metadata+Cache).

Since
1.10.0

◆ H5Pset_meta_block_size()

herr_t H5Pset_meta_block_size ( hid_t  fapl_id,
hsize_t  size 
)

Sets the minimum metadata block size.

Parameters
[in]fapl_idFile access property list identifier
[in]sizeMinimum size, in bytes, of metadata block allocations
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_meta_block_size() sets the minimum size, in bytes, of metadata block allocations when H5FD_FEAT_AGGREGATE_METADATA is set by a VFL driver.

Each raw metadata block is initially allocated to be of the given size. Specific metadata objects (e.g., object headers, local heaps, B-trees) are then sub-allocated from this block.

The default setting is 2048 bytes, meaning that the library will attempt to aggregate metadata in at least 2K blocks in the file. Setting the value to zero (0) with this function will turn off metadata aggregation, even if the VFL driver attempts to use the metadata aggregation strategy.

Metadata aggregation reduces the number of small data objects in the file that would otherwise be required for metadata. The aggregated block of metadata is usually written in a single write action and always in a contiguous block, potentially significantly improving library and application performance.

Since
1.4.0

◆ H5Pset_metadata_read_attempts()

herr_t H5Pset_metadata_read_attempts ( hid_t  plist_id,
unsigned  attempts 
)

Sets the number of read attempts in a file access property list.

Parameters
[in]plist_idFile access property list identifier
[in]attemptsThe number of read attempts. Must be a value greater than 0
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Failure Modes:
  • When the user sets the number of read attempts to 0.
  • When the input property list is not a file access property list.
  • When the library is unable to set the number of read attempts in the file access property list.

    H5Pset_metadata_read_attempts() sets the number of reads that the library will try when reading checksummed metadata in an HDF5 file opened with SWMR access. When reading such metadata, the library will compare the checksum computed for the metadata just read with the checksum stored within the piece of checksum. When performing SWMR operations on a file, the checksum check might fail when the library reads data on a system that is not atomic. To remedy such situations, the library will repeatedly read the piece of metadata until the check passes or finally fails the read when the allowed number of attempts is reached.

    The number of read attempts used by the library will depend on how the file is opened and whether the user sets the number of read attempts via this routine:

    • For a file opened with SWMR access:
      • If the user sets the number of attempts to N, the library will use N.
      • If the user does not set the number of attempts, the library will use the default for SWMR access (100).
    • For a file opened with non-SWMR access, the library will always use the default for non-SWMR access (1). The value set via this routine does not have any effect during non-SWMR access.

Example: The first example illustrates the case in setting the number of read attempts for a file opened with SWMR access.

/* Create a copy of file access property list */
/* Set the # of read attempts */
/* Open the file with SWMR access and the non-default file access property list */
fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), fapl);
/* Get the file's file access property list */
file_fapl = H5Fget_access_plist(fid);
/* Retrieve the # of read attempts from the file's file access property list */
H5Pget_metadata_read_attempts(file_fapl, &attempts);
/*
* The value returned in "attempts" will be 20.
* The library will use 20 as the number of read attempts
* when reading checksummed metadata in the file
*/
/* Close the property list */
H5Pclose(fapl);
H5Pclose(file_fapl);
/* Close the file */
H5Fclose(fid);

Example: The second example illustrates the case in setting the number of read attempts for a file opened with non-SWMR access. The value set in the file access property list does not have any effect.

/* Create a copy of file access property list */
/* Set the # of read attempts */
/* Open the file with SWMR access and the non-default file access property list */
fid = H5Fopen(FILE, H5F_ACC_RDONLY, fapl);
/* Get the file's file access property list */
file_fapl = H5Fget_access_plist(fid);
/* Retrieve the # of read attempts from the file's file access property list */
H5Pget_metadata_read_attempts(file_fapl, &attempts);
/*
* The value returned in "attempts" will be 1 (default for non-SWMR access).
* The library will use 1 as the number of read attempts
* when reading checksummed metadata in the file
*/
/* Close the property lists */
H5Pclose(fapl);
H5Pclose(file_fapl);
/* Close the file */
H5Fclose(fid);
Note
Motivation: On a system that is not atomic, the library might possibly read inconsistent metadata with checksum when performing single-writer/multiple-reader (SWMR) operations for an HDF5 file. Upon encountering such situations, the library will try reading the metadata again to obtain consistent data. This routine provides the means to set the number of read attempts other than the library default.
Since
1.10.0

◆ H5Pset_mpi_params()

herr_t H5Pset_mpi_params ( hid_t  fapl_id,
MPI_Comm  comm,
MPI_Info  info 
)

Set the MPI communicator and info.

Parameters
[in]fapl_idFile access property list identifier
[in]commMPI communicator
[in]infoMPI info object
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_mpi_params() sets the MPI communicator and info stored in the file access property list fapl_id.

Since
1.12.0

◆ H5Pset_multi_type()

herr_t H5Pset_multi_type ( hid_t  fapl_id,
H5FD_mem_t  type 
)

Specifies type of data to be accessed via the MULTI driver, enabling more direct access.

Parameters
[in]fapl_idFile access property list identifier
[in]typeType of data to be accessed
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_multi_type() sets the type of data property in the file access property list fapl_id. This setting enables a user application to specify the type of data the application wishes to access so that the application can retrieve a file handle for low-level access to the particular member of a set of MULTI files in which that type of data is stored. The file handle is retrieved with a separate call to H5Fget_vfd_handle() (or, in special circumstances, to H5FDget_vfd_handle(); see HDF5 Virtual File Layer.

The type of data specified in type may be one of the following:

H5FD_MEM_SUPER Super block data
H5FD_MEM_BTREE B-tree data
H5FD_MEM_DRAW Dataset raw data
H5FD_MEM_GHEAP Global heap data
H5FD_MEM_LHEAP Local Heap data
H5FD_MEM_OHDR Object header data

This function is for use only when accessing an HDF5 file written as a set of files with the MULTI file driver.

Since
1.6.0

◆ H5Pset_object_flush_cb()

herr_t H5Pset_object_flush_cb ( hid_t  plist_id,
H5F_flush_cb_t  func,
void *  udata 
)

Sets a callback function to invoke when an object flush occurs in the file.

Parameters
[in]plist_idFile access property list identifier
[in]funcCallback function
[in]udataUser-defined callback function context
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_object_flush_cb() sets the callback function to invoke in the file access property list plist_id whenever an object flush occurs in the file. Library objects are group, dataset, and committed datatype.

The callback function func must conform to the prototype defined below:

typedef herr_t (*H5F_flush_cb_t)(hid_t object_id, void *user_data)
herr_t(* H5F_flush_cb_t)(hid_t object_id, void *udata)
Definition H5Fpublic.h:242

The parameters of the callback function, per the above prototypes, are defined as follows:

  • object_id is the identifier of the object which has just been flushed.
  • user_data is the user-defined input data for the callback function.

Example: The example below illustrates the usage of this routine to set the callback function to invoke when an object flush occurs.

hid_t file_id, fapl_id;
hid_t dataset_id, dapl_id;
unsigned counter;
/* Create a copy of the file access property list */
/* Set up the object flush property values */
/* flush_cb: callback function to invoke when an object flushes (see below) */
/* counter: user data to pass along to the callback function */
H5Pset_object_flush_cb(fapl_id, flush_cb, &counter);
/* Open the file */
file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);
/* Create a group */
gid = H5Gcreate2(fid, “group”, H5P_DEFAULT, H5P_DEFAULT_H5P_DEFAULT);
/* Open a dataset */
dataset_id = H5Dopen2(file_id, DATASET, H5P_DEFAULT);
/* The flush will invoke flush_cb() with counter */
H5Dflush(dataset_id);
/* counter will be equal to 1 */
/* ... */
/* The flush will invoke flush_cb() with counter */
H5Gflush(gid);
/* counter will be equal to 2 */
/* ... */
/* The callback function for object flush property */
static herr_t
flush_cb(hid_t obj_id, void *_udata)
{
unsigned *flush_ct = (unsigned *)_udata;
++(*flush_ct);
return 0;
}
hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id)
Opens an existing dataset.
herr_t H5Dflush(hid_t dset_id)
Flushes all buffers associated with a dataset to disk.
herr_t H5Gflush(hid_t group_id)
Flushes all buffers associated with a group to disk.
hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id)
Creates a new group and links it into the file.
Since
1.10.0

◆ H5Pset_page_buffer_size()

herr_t H5Pset_page_buffer_size ( hid_t  plist_id,
size_t  buf_size,
unsigned  min_meta_per,
unsigned  min_raw_per 
)

Sets the maximum size for the page buffer and the minimum percentage for metadata and raw data pages.

Parameters
[in]plist_idFile access property list identifier
[in]buf_sizeMaximum size, in bytes, of the page buffer
[in]min_meta_perMinimum metadata percentage to keep in the page buffer before allowing pages containing metadata to be evicted (Default is 0)
[in]min_raw_perMinimum raw data percentage to keep in the page buffer before allowing pages containing raw data to be evicted (Default is 0)
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_page_buffer_size() sets buf_size, the maximum size in bytes of the page buffer. The default value is zero, meaning that page buffering is disabled. When a non-zero page buffer size is set, the library will enable page buffering if that size is larger or equal than a single page size if a paged file space strategy is enabled using the functions H5Pset_file_space_strategy() and H5Pset_file_space_page_size().

The page buffer layer captures all I/O requests before they are issued to the VFD and "caches" them in fixed sized pages. Once the total number of pages exceeds the page buffer size, the library evicts pages from the page buffer by writing them to the VFD. At file close, the page buffer is flushed writing all the pages to the file.

If a non-zero page buffer size is set, and the file space strategy is not set to paged or the page size for the file space strategy is larger than the page buffer size, the subsequent call to H5Fcreate() using the plist_id will fail.

Note
As of HDF5 1.14.4, this property will be ignored when an existing file is being opened and the file space strategy stored in the file isn't paged. This was previously a failure.
As of HDF5 1.14.4, if a file with a paged file space strategy is opened with a page size that is smaller than the file's page size, the page cache size will be rounded up to the file's page size. This was previously a failure.

The function also allows setting the minimum percentage of pages for metadata and raw data to prevent a certain type of data to evict hot data of the other type.

Since
1.10.1

◆ H5Pset_relax_file_integrity_checks()

herr_t H5Pset_relax_file_integrity_checks ( hid_t  plist_id,
uint64_t  flags 
)

Relax file integrity checks that may issue errors for some valid files.

Parameters
[in]plist_idFile access property list identifier
[in]flagsRelaxed integrity checks flag. Valid values are:
  • H5F_RFIC_UNUSUAL_NUM_UNUSED_NUMERIC_BITS suppresses integrity checks for detecting unusually high values for the number of unused bits in numeric datatype classes (H5T_INTEGER, H5T_FLOAT, and H5T_BITFIELD). Integrity checks are triggered when the precision for a datatype (i.e. the number of bits containing actual data) is less than half of the datatype's size and the datatype is greater than 1 byte in size. For example, a datatype with a precision of 15 bits and a size of 4 bytes (i.e. 32 bits) will issue an error, but a datatype with 17 bits of precision and a size of 4 bytes will not issue an error, nor will a datatype with a precision of 1, 2, or 3 bits and a size of 1 byte issue an error.
  • H5F_RFIC_ALL relaxes all integrity checks above.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

Incorrectly encoded or corrupted metadata in a native HDF5 format file can cause incorrect library behavior when the metadata has no checksum. Integrity checks within the library detect these circumstances and issue errors when incorrect metadata is found. Unfortunately, some of the integrity checks for detecting these circumstances may incorrectly issue an error for a valid HDF5 file that was intentionally created with these configurations. Setting the appropriate flag(s) with this routine will relax the file integrity checks for these valid files and suppress errors when accessing objects with these configurations.

The library will also issue errors when these configurations are used to create objects, preventing applications from unintentionally creating them. Setting the appropriate flag with this routine will also suppress those errors on creation, although using this routine and the appropriate flag(s) will still be required when accessing files created with these configurations.

A more complete solution that avoids errors on both object creation and access is to use the H5Pset_libver_bounds routine with a low bound of at least H5F_LIBVER_V18 when creating objects with these configurations. This will cause the library to checksum a file's metadata, allowing accidental data corruption to be correctly detected and errors correctly issued without ambiguity.

Since
1.14.4

◆ H5Pset_sieve_buf_size()

herr_t H5Pset_sieve_buf_size ( hid_t  fapl_id,
size_t  size 
)

Sets the maximum size of the data sieve buffer.

Parameters
[in]fapl_idFile access property list identifier
[in]sizeMaximum size, in bytes, of data sieve buffer
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_sieve_buf_size() sets size, the maximum size in bytes of the data sieve buffer, which is used by file drivers that are capable of using data sieving.

The data sieve buffer is used when performing I/O on datasets in the file. Using a buffer which is large enough to hold several pieces of the dataset being read in for hyperslab selections boosts performance by quite a bit.

The default value is set to 64KB, indicating that file I/O for raw data reads and writes will occur in at least 64KB blocks. Setting the value to zero (0) with this API function will turn off the data sieving, even if the VFL driver attempts to use that strategy.

Internally, the library checks the storage sizes of the datasets in the file. It picks the smaller one between the size from the file access property and the size of the dataset to allocate the sieve buffer for the dataset in order to save memory usage.

Version
1.6.0 The size parameter has changed from type hsize_t to size_t.
Since
1.4.0

◆ H5Pset_small_data_block_size()

herr_t H5Pset_small_data_block_size ( hid_t  fapl_id,
hsize_t  size 
)

Sets the size of a contiguous block reserved for small data.

Parameters
[in]fapl_idFile access property list identifier
[in]sizeMaximum size, in bytes, of the small data block. The default size is 2048.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_small_data_block_size() reserves blocks of size bytes for the contiguous storage of the raw data portion of small datasets. The HDF5 library then writes the raw data from small datasets to this reserved space, thus reducing unnecessary discontinuities within blocks of meta data and improving I/O performance.

A small data block is actually allocated the first time a qualifying small dataset is written to the file. Space for the raw data portion of this small dataset is suballocated within the small data block. The raw data from each subsequent small dataset is also written to the small data block until it is filled; additional small data blocks are allocated as required.

The HDF5 library employs an algorithm that determines whether I/O performance is likely to benefit from the use of this mechanism with each dataset as storage space is allocated in the file. A larger size will result in this mechanism being employed with larger datasets.

The small data block size is set as an allocation property in the file access property list identified by fapl_id.

Setting size to zero (0) disables the small data block mechanism.

Since
1.4.4

◆ H5Pset_vol()

herr_t H5Pset_vol ( hid_t  plist_id,
hid_t  new_vol_id,
const void *  new_vol_info 
)

Set the file VOL connector for a file access property list.

Parameters
[in]plist_idFile access property list identifier
[in]new_vol_idVOL connector identifier
[in]new_vol_infoOptional VOL information
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Pset_vol() sets the VOL connector new_vol_id for a file access property list plist_id using the (optional) VOL information in new_vol_info.

Since
1.12.0