Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-07-28 The HDF5 Field Guide

Loading...
Searching...
No Matches
File Access Properties
Property Lists (H5P)

## 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
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_coll_metadata_write (hid_t plist_id, bool *is_collective)
| Retrieves metadata write mode setting.
herr_t | H5Pget_core_write_tracking (hid_t fapl_id, bool *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.
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.
const void * | H5Pget_driver_info (hid_t plist_id)
| Returns a pointer to file driver information.
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, bool *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_fapl_core (hid_t fapl_id, size_t *increment, bool *backing_store)
| Queries core file driver properties.
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.
herr_t | H5Pget_fapl_family (hid_t fapl_id, hsize_t *memb_size, hid_t *memb_fapl_id)
| Returns file access property list information.
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 | 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.
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.
herr_t | H5Pget_fapl_mpio (hid_t fapl_id, MPI_Comm *comm, MPI_Info *info)
| Returns MPI IO communicator information.
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, bool *relax)
| Returns information about the multi-file access property list.
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
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.
herr_t | H5Pget_fapl_ros3_block_caching (hid_t fapl_id, size_t *block_size, size_t *block_cache_size, bool *lock_superblock)
| Queries a File Access Property List for H5FD_ROS3 I/O block caching parameters.
herr_t | H5Pget_fapl_ros3_endpoint (hid_t fapl_id, size_t size, char *endpoint)
| Queries a File Access Property List for H5FD_ROS3 file driver endpoint url.
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.
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.
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.
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, bool *use_file_locking, bool *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, bool *is_enabled, char *location, size_t *location_size, bool *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_mpi_params (hid_t fapl_id, MPI_Comm *comm, MPI_Info *info)
| Get the MPI communicator and info.
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_relax_file_integrity_checks (hid_t plist_id, uint64_t *flags)
| Retrieve relaxed file integrity check flags.
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_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 | 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_coll_metadata_write (hid_t plist_id, bool is_collective)
| Sets metadata write mode to be collective or independent (default).
herr_t | H5Pset_core_write_tracking (hid_t fapl_id, bool 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, bool 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_fapl_core (hid_t fapl_id, size_t increment, bool backing_store)
| Modifies the file access property list to use the H5FD_CORE driver.
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.
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.
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 | 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.
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.
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.
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.
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, bool relax)
| Sets up use of the multi-file driver.
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
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.
herr_t | H5Pset_fapl_ros3_block_caching (hid_t fapl_id, size_t block_size, size_t block_cache_size, bool lock_superblock)
| Modifies the specified File Access Property List to set I/O block caching parameters for the H5FD_ROS3 driver.
herr_t | H5Pset_fapl_ros3_endpoint (hid_t fapl_id, const char *endpoint)
| Modifies the specified File Access Property List to use an alternative endpoint URL when opening files with the H5FD_ROS3 driver.
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.
herr_t | H5Pset_fapl_sec2 (hid_t fapl_id)
| Modifies the file access property list to use the H5FD_SEC2 driver.
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.
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.
herr_t | H5Pset_fapl_stdio (hid_t fapl_id)
| Sets the standard I/O driver.
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.
herr_t | H5Pset_fapl_windows (hid_t fapl_id)
| Sets the Windows I/O driver.
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, bool use_file_locking, bool 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_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_mdc_log_options (hid_t plist_id, bool is_enabled, const char *location, bool 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_mpi_params (hid_t fapl_id, MPI_Comm comm, MPI_Info info)
| Set the MPI communicator and info.
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_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 | 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.

## 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_id | File access property list identifier
  [out] | threshold | Pointer to location of return threshold value
  [out] | alignment | Pointer 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_id | File access property list identifier
  [in,out] | mdc_nelmts | No longer used
  [in,out] | rdcc_nslots | Number of elements (objects) in the raw data chunk cache
  [in,out] | rdcc_nbytes | Total size of the raw data chunk cache, in bytes
  [in,out] | rdcc_w0 | Preemption 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,
|  | bool * | is_collective )

Retrieves metadata write mode setting.

Parameters

  [in] | plist_id | File access property list identifier
  [out] | is_collective | Pointer 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
  - H5Pget_all_coll_metadata_ops()
  - H5Pget_coll_metadata_write()
  - H5Pset_all_coll_metadata_ops()
  - H5Pset_coll_metadata_write()
  - Functions with No Access Property List Parameter that May Generate Metadata Reads

Since
  1.10.0

## ◆ H5Pget_core_write_tracking()

herr_t H5Pget_core_write_tracking | ( | hid_t | fapl_id,
|  | bool * | is_enabled,
|  | size_t * | page_size )

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

Parameters

  [in] | fapl_id | File access property list identifier
  [out] | is_enabled | Whether the feature is enabled
  [out] | page_size | Size, 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_id | Property 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_id | File access property list identifier
  [out] | config_buf | Driver configuration string output buffer
  [in] | buf_size | Size 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_id | File 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_id | File access property list identifier
  [out] | efc_size | External 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,
|  | bool * | 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_id | File access property list identifier
  [out] | evict_on_close | Pointer 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_id | File access property list identifier
  [out] | offset | Offset 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()

herr_t H5Pget_fapl_core | ( | hid_t | fapl_id,
|  | size_t * | increment,
|  | bool * | backing_store )

Queries core file driver properties.

Parameters

  [in] | fapl_id | File access property list identifier
  [out] | increment | Size, in bytes, of memory increments
  [out] | backing_store | Boolean 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()

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_id | File access property list identifier
  [out] | boundary | Required memory alignment boundary
  [out] | block_size | File system block size
  [out] | cbuf_size | Copy 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()

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_id | File access property list identifier
  [out] | memb_size | Size in bytes of each file member
  [out] | memb_fapl_id | Identifier 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()

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_id | File access property list identifier
  [out] | fa_out | Pointer 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_id | File access property list identifier
  [out] | config_out | Pointer 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()

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_id | File access property list identifier
  [out] | fa_out | Pointer 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()

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

Returns MPI IO communicator information.

Parameters

  [in] | fapl_id | File access property list identifier
  [out] | comm | MPI communicator
  [out] | info | MPI 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()

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,
|  | bool * | relax )

Returns information about the multi-file access property list.

Parameters

  [in] | fapl_id | File access property list identifier
  [out] | memb_map | Maps memory usage types to other memory usage types
  [out] | memb_fapl | Property list for each memory usage type
  [out] | memb_name | Name generator for names of member files
  [out] | memb_addr | The offsets within the virtual address space, from 0 (zero) to HADDR_MAX, at which each type of data storage begins
  [out] | relax | Allows 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()

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_id | File access property list identifier
  [out] | fa_out | The 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()

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_id | File access property list identifier
  [out] | fa_out | Pointer to H5FD_ROS3 driver configuration structure.

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

## ◆ H5Pget_fapl_ros3_block_caching()

herr_t H5Pget_fapl_ros3_block_caching | ( | hid_t | fapl_id,
|  | size_t * | block_size,
|  | size_t * | block_cache_size,
|  | bool * | lock_superblock )

Queries a File Access Property List for H5FD_ROS3 I/O block caching parameters.

Parameters

  [in] | fapl_id | File access property list identifier
  [out] | block_size | Pointer for returning the currently set size, in bytes, of a cached I/O block. May be `NULL`, in which case no value is returned.
  [out] | block_cache_size | Pointer for returning the currently set maximum size, in bytes, of the H5FD_ROS3 I/O block cache. This is an upper limit of the amount of bytes which will be allocated for caching I/O blocks, excluding a small amount of additional metadata bytes allocated for each block. May be `NULL`, in which case no value is returned.
  [out] | lock_superblock | Pointer for returning the currently set boolean value for whether the I/O block containing a file's superblock metadata should be locked in the I/O block cache. This will prevent that block from being evicted from the block cache when trying to make space for other I/O blocks. May be `NULL`, in which case no value is returned.

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

Since
  2.2.0

## ◆ H5Pget_fapl_ros3_endpoint()

herr_t H5Pget_fapl_ros3_endpoint | ( | hid_t | fapl_id,
|  | size_t | size,
|  | char * | endpoint )

Queries a File Access Property List for H5FD_ROS3 file driver endpoint url.

Parameters

  [in] | fapl_id | File access property list identifier
  [in] | size | Size of the provided char array for storing the endpoint url.
  [out] | endpoint | Alternate endpoint url.

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

Since
  2.0.0

## ◆ H5Pget_fapl_ros3_token()

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_id | File access property list identifier
  [in] | size | Size of the provided char array for storing the session/security token.
  [out] | token | Session/security token.

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

Since
  1.14.2

## ◆ H5Pget_fapl_splitter()

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_id | File access property list identifier
  [out] | config_ptr | Configuration 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.12.1, back-ported to 1.10.7

## ◆ 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_id | File access property list identifier
  [out] | config_out | Pointer 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.

The ioc_fapl_id field of the returned structure will be the ID of a copied or newly-created property list which should be closed with H5Pclose() when the configuration structure is no longer in use. An application should also be sure to close this property list ID first if a different property list ID will be assigned to the ioc_fapl_id field.

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_id | File access property list identifier
  [out] | degree | Pointer 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_id | File access property list identifier
  [in,out] | buf_ptr_ptr | On 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_ptr | On 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.

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_id | File access property list identifier
  [in,out] | callbacks_ptr | Pointer 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 H5Pget_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.

Since
  1.8.9

## ◆ H5Pget_file_locking()

herr_t H5Pget_file_locking | ( | hid_t | fapl_id,
|  | bool * | use_file_locking,
|  | bool * | ignore_when_disabled )

Retrieves the file locking property values.

Parameters

  [in] | fapl_id | File access property list identifier
  [out] | use_file_locking | File locking flag
  [out] | ignore_when_disabled | Ignore 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_id | File access property list identifier
  [out] | gc_ref | Flag 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_id | File access property list identifier
  [out] | low | The earliest version of the library that will be used for writing objects
  [out] | high | The 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_id | File access property list identifier
  [in,out] | config_ptr | Pointer 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 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;
bool rpt_fcn_enabled;
bool open_trace_file;
bool close_trace_file;
char trace_file_name[H5AC__MAX_TRACE_FILE_NAME_LEN + 1];
bool evictions_enabled;
bool set_initial_size;
size_t initial_size;
double min_clean_fraction;
size_t max_size;
size_t min_size;
long int epoch_length;
/* size increase control fields: */
enum H5C_cache_incr_mode incr_mode;
double lower_hr_threshold;
double increment;
bool apply_max_increment;
size_t max_increment;
enum H5C_cache_flash_incr_mode flash_incr_mode;
double flash_multiple;
double flash_threshold;
/* size decrease control fields: */
enum H5C_cache_decr_mode decr_mode;
double upper_hr_threshold;
double decrement;
bool apply_max_decrement;
size_t max_decrement;
int epochs_before_eviction;
bool apply_empty_reserve;
double empty_reserve;
/* parallel configuration fields: */
size_t dirty_bytes_threshold;
int metadata_write_strategy;
} H5AC_cache_config_t;

(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_id | File access property list identifier
  [out] | config_ptr | Pointer 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;
bool generate_image;
bool save_resize_status;
int entry_ageout;
} H5AC_cache_image_config_t;

(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,
|  | bool * | is_enabled,
|  | char * | location,
|  | size_t * | location_size,
|  | bool * | start_on_access )

Gets metadata cache logging options.

Parameters

  [in] | plist_id | File access property list identifier
  [out] | is_enabled | Flag whether logging is enabled
  [out] | location | Location of log in UTF-8/ASCII (file path/name) (On Windows, this must be ASCII)
  [out] | location_size | Size in bytes of the location string
  [out] | start_on_access | Whether 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 Design: 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_id | File access property list identifier
  [out] | size | Minimum 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_id | File access property list identifier
  [out] | attempts | The 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 */
  fapl = H5Pcreate(H5P_FILE_ACCESS);
  /* Retrieve the # of read attempts from the file access property list */
  H5Pget_metadata_read_attempts(fapl, &attempts);
  /*
  * The value returned in "attempts" will be 1 (default for non-SWMR access).
  */
  /* Set the # of read attempts to 20 */
  H5Pset_metadata_read_attempts(fapl, 20);
  /* Retrieve the # of read attempts from the file access property list */
  H5Pget_metadata_read_attempts(fapl, &attempts);
  /*
  * The value returned in "attempts" will be 20 as set.
  */
  /* Close the property list */
  H5Pclose(fapl);
  H5P_FILE_ACCESS
  #define H5P_FILE_ACCESS
  Definition H5Ppublic.h:56
  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.
  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.
  H5Pclose
  herr_t H5Pclose(hid_t plist_id)
  Terminates access to a property list.
  H5Pcreate
  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 */
  fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), H5P_DEFAULT);
  /* 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 */
  fapl = H5Pcreate(H5P_FILE_ACCESS);
  /* Set the # of read attempts */
  H5Pset_metadata_read_attempts(fapl, 20);
  /* 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);
  H5F_ACC_RDONLY
  #define H5F_ACC_RDONLY
  Definition H5Fpublic.h:28
  H5F_ACC_SWMR_READ
  #define H5F_ACC_SWMR_READ
  Definition H5Fpublic.h:49
  H5P_DEFAULT
  #define H5P_DEFAULT
  Definition H5Ppublic.h:220
  H5Fget_access_plist
  hid_t H5Fget_access_plist(hid_t file_id)
  Returns a file access property list identifier.
  H5Fopen
  hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id)
  Opens an existing HDF5 file.
  H5Fclose
  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 */
  fid = H5Fopen(FILE, H5F_ACC_RDONLY, H5P_DEFAULT);
  /* 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 */
  fapl = H5Pcreate(H5P_FILE_ACCESS);
  /* Set the # of read attempts */
  H5Pset_metadata_read_attempts(fapl, 20);
  /* 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_id | File access property list identifier
  [out] | comm | MPI communicator
  [out] | info | MPI 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_id | File access property list or data transfer property list identifier
  [out] | type | Type 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_id | File access property list identifier
  [in] | func | The user-defined callback function
  [in] | udata | The 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 */
  fapl_id = H5Pcreate(H5P_FILE_ACCESS);
  /* 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;
  }
  H5F_ACC_RDWR
  #define H5F_ACC_RDWR
  Definition H5Fpublic.h:29
  hid_t
  int64_t hid_t
  Definition H5Ipublic.h:60
  herr_t
  int herr_t
  Definition H5public.h:269
  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.
  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.

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_id | File access property list identifier
  [out] | buf_size | Maximum size, in bytes, of the page buffer
  [out] | min_meta_perc | Minimum metadata percentage to keep in the page buffer before allowing pages containing metadata to be evicted
  [out] | min_raw_perc | Minimum 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_id | File access property list identifier
  [out] | flags | Relaxed 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_id | File access property list identifier
  [out] | size | Maximum 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_id | File access property list identifier
  [out] | size | Maximum 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_id | File access property list identifier
  [out] | cap_flags | Flags 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_id | File access property list identifier
  [out] | vol_id | Current 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_id | File access property list identifier
  [out] | vol_info | The 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_id | File access property list identifier
  [in] | threshold | Threshold value. Note that setting the threshold value to 0 (zero) has the effect of a special case, forcing everything to be aligned
  [in] | alignment | Alignment 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_id | File access property list identifier
  [in] | mdc_nelmts | No longer used; any value passed is ignored
  [in] | rdcc_nslots | The 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 8191.
  [in] | rdcc_nbytes | Total size of the raw data chunk cache in bytes. The default size is 8 MiB per dataset.
  [in] | rdcc_w0 | The 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,
|  | bool | is_collective )

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

Parameters

  [in] | plist_id | File access property list identifier
  [out] | is_collective | 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.

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
  - H5Pget_all_coll_metadata_ops()
  - H5Pget_coll_metadata_write()
  - H5Pset_all_coll_metadata_ops()
  - H5Pset_coll_metadata_write()
  - Functions with No Access Property List Parameter that May Generate Metadata Reads

Since
  1.10.0

## ◆ H5Pset_core_write_tracking()

herr_t H5Pset_core_write_tracking | ( | hid_t | fapl_id,
|  | bool | is_enabled,
|  | size_t | page_size )

Sets write tracking information for core driver, H5FD_CORE.

Parameters

  [in] | fapl_id | File access property list identifier
  [in] | is_enabled | Boolean value specifying whether feature is enabled
  [in] | page_size | Positive 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_id | Property list identifier
  [in] | driver_id | The new driver identifier
  [in] | driver_info | Optional 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_id | Property list identifier
  [in] | driver_name | The new driver name
  [in] | driver_config | Optional 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_id | Property list identifier
  [in] | driver_value | The new driver value (ID)
  [in] | driver_config | Optional 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_id | File access property list identifier
  [in] | efc_size | External 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);
  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.

Since
  1.8.7

## ◆ H5Pset_evict_on_close()

herr_t H5Pset_evict_on_close | ( | hid_t | fapl_id,
|  | bool | evict_on_close )

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

Parameters

  [in] | fapl_id | File access property list identifier
  [in] | evict_on_close | Whether 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_id | File access property list identifier
  [in] | offset | Offset 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()

herr_t H5Pset_fapl_core | ( | hid_t | fapl_id,
|  | size_t | increment,
|  | bool | backing_store )

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

Parameters

  [in] | fapl_id | File access property list identifier
  [in] | increment | Size, in bytes, of memory increments
  [in] | backing_store | Boolean 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()

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_id | File access property list identifier
  [in] | alignment | Required memory alignment boundary
  [in] | block_size | File system block size
  [in] | cbuf_size | Copy 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()

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_id | File access property list identifier
  [in] | memb_size | Size in bytes of each file member
  [in] | memb_fapl_id | Identifier 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.

The family file driver uses snprintf to generate the member file names, passing the member number as an unsigned int. The file name used with the family file driver must therefore contain a single printf format specifier that indicates a variable of the correct width and produces unique strings for each member number passed as a parameter to snprintf. For example one might insert %06d into the file name string. There must be no other format specifiers in the string.

If this file driver is for the source file of a virtual dataset (VDS) printf-style mapping, special care must be taken. In this case the VDS code expands the file name with snprintf first, then the family driver second. This means that, while the format specifier for the VDS block number is inserted normally, the format specifier for the family file driver member number must be escaped such that it is only recognized as a format specifier the second time it is run through snprintf. As an example one may use %%06d as the member file number format specifier in the source file name.

Version
  1.8.0 Behavior of the `memb_size` parameter was changed.

Since
  1.4.0

## ◆ H5Pset_fapl_hdfs()

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_id | File access property list identifier
  [in] | fa | Pointer 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_id | File access property list identifier
  [in] | vfd_config | Pointer 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()

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_id | File access property list identifier
  [in] | logfile | Name of the log file
  [in] | flags | Flags specifying the types of logging activity
  [in] | buf_size | The 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
  Flag | VFD Call | Output 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
  Flavor | Description
  --- | ---
  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()

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_id | File access property list identifier
  [in] | fa | Pointer 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()

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_id | File access property list identifier
  [in] | comm | MPI communicator
  [in] | info | MPI 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()

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,
|  | bool | relax )

Sets up use of the multi-file driver.

Parameters

  [in] | fapl_id | File access property list identifier
  [in] | memb_map | Maps memory usage types to other memory usage types
  [in] | memb_fapl | Property list for each memory usage type
  [in] | memb_name | Name generator for names of member files
  [in] | memb_addr | The offsets within the virtual address space, from 0 (zero) to HADDR_MAX, at which each type of data storage begins
  [in] | relax | Allows 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()). There must be no other format specifiers in the string.

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: `s` for H5FD_MEM_SUPER `b` for H5FD_MEM_BTREE `r` for H5FD_MEM_DRAW `g` for H5FD_MEM_GHEAP `l` for H5FD_MEM_LHEAP `o` for H5FD_MEM_OHDR
`memb_addr` | The default setting is that the address space is equally divided among all of the elements: H5FD_MEM_SUPER -> 0 * (HADDR_MAX/6) H5FD_MEM_BTREE -> 1 * (HADDR_MAX/6) H5FD_MEM_DRAW -> 2 * (HADDR_MAX/6) H5FD_MEM_GHEAP -> 3 * (HADDR_MAX/6) H5FD_MEM_LHEAP -> 4 * (HADDR_MAX/6) H5FD_MEM_OHDR -> 5 * (HADDR_MAX/6)

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:
  H5FD_mem_t mt, memb_map[H5FD_MEM_NTYPES];
  hid_t memb_fapl[H5FD_MEM_NTYPES];
  const char *memb[H5FD_MEM_NTYPES];
  haddr_t memb_addr[H5FD_MEM_NTYPES];
  // The mapping...
  for (mt=0; mt<H5FD_MEM_NTYPES; mt++) {
  memb_map[mt] = H5FD_MEM_SUPER;
  }
  memb_map[H5FD_MEM_DRAW] = H5FD_MEM_DRAW;
  // Member information
  memb_fapl[H5FD_MEM_SUPER] = H5P_DEFAULT;
  memb_name[H5FD_MEM_SUPER] = "%s.meta";
  memb_addr[H5FD_MEM_SUPER] = 0;
  memb_fapl[H5FD_MEM_DRAW] = H5P_DEFAULT;
  memb_name[H5FD_MEM_DRAW] = "%s.raw";
  memb_addr[H5FD_MEM_DRAW] = HADDR_MAX/2;
  hid_t fapl = H5Pcreate(H5P_FILE_ACCESS);
  H5Pset_fapl_multi(fapl, memb_map, memb_fapl,
  memb_name, memb_addr, true);
  H5FD_mem_t
  enum H5F_mem_t H5FD_mem_t
  Definition H5FDpublic.h:273
  H5FD_MEM_NTYPES
  @ H5FD_MEM_NTYPES
  Definition H5Fpublic.h:163
  H5FD_MEM_DRAW
  @ H5FD_MEM_DRAW
  Definition H5Fpublic.h:158
  H5FD_MEM_SUPER
  @ H5FD_MEM_SUPER
  Definition H5Fpublic.h:156
  HADDR_MAX
  #define HADDR_MAX
  Definition H5public.h:386
  haddr_t
  uint64_t haddr_t
  Definition H5public.h:372
  H5Pset_fapl_multi
  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, bool 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()

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_id | File access property list identifier
  [in] | fa | The 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()

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_id | File access property list identifier
  [in] | fa | Pointer to H5FD_ROS3 driver configuration structure.

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

Note
  As of HDF5 2.0.0, as a side effect of calling this function, if the page buffer size has not been set on fapl_id, it is set to 64 MiB. To set a different page buffer size, simply call H5Pset_page_buffer() with fapl_id and your desired page buffer size. To disable the page buffer, call H5Pset_page_buffer() with a size of
  1. Disabling the page buffer with the ROS3 driver may cause severe performance degradation.

## ◆ H5Pset_fapl_ros3_block_caching()

herr_t H5Pset_fapl_ros3_block_caching | ( | hid_t | fapl_id,
|  | size_t | block_size,
|  | size_t | block_cache_size,
|  | bool | lock_superblock )

Modifies the specified File Access Property List to set I/O block caching parameters for the H5FD_ROS3 driver.

Parameters

  [in] | fapl_id | File access property list identifier
  [in] | block_size | Specifies the size, in bytes, of a cached I/O block. The default value is HDF5_ROS3_VFD_DEFAULT_BLOCK_SIZE.
  [in] | block_cache_size | Specifies the total size, in bytes, of the I/O block cache. The default value is HDF5_ROS3_VFD_DEFAULT_BLOCK_CACHE_SIZE.
  [in] | lock_superblock | Specifies whether or not to keep the I/O block containing a file's superblock metadata locked in the I/O block cache and unable to be evicted. The default value is `true`.

H5Pset_fapl_ros3_block_caching() sets parameters that control how the H5FD_ROS3 driver caches I/O to reduce requests to S3. By default, the H5FD_ROS3 driver performs I/O in large, fixed-size (HDF5_ROS3_VFD_DEFAULT_BLOCK_SIZE bytes, by default) blocks which are cached in memory and used to serve I/O requests. This function can be used to modify the default parameters to better suit a particular I/O pattern.

For `block_size`, the macro HDF5_ROS3_VFD_DEFAULT_BLOCK_SIZE may be used to specify that the default block size is desired. For `block_cache_size`, the macro HDF5_ROS3_VFD_DEFAULT_BLOCK_CACHE_SIZE may be used to specify that the default block cache size is desired. Setting either `block_size` or `block_cache_size` to 0 will disable I/O block caching in the H5FD_ROS3 driver. This can be useful for reading small amounts of data from a file when the default `block_size` is much larger than the amount of data being read.

`block_cache_size` is an upper limit of the amount of bytes which will be allocated for caching I/O blocks, excluding a small amount of additional metadata bytes allocated for each block. The block cache will only keep whole blocks, so `block_cache_size` should be set to some multiple of `block_size`. If `block_cache_size` is specified as a value smaller than `block_size`, `block_size` will be adjusted down to be equal to `block_cache_size` and the block cache will only hold a single cached I/O block.

`lock_superblock` determines whether the I/O block containing a file's superblock metadata should be locked in the block cache and prevented from being evicted when trying to make space for other I/O blocks. Depending on the layout of a file, this can be useful for keeping specific often-used metadata in the block cache.

Note
  The H5FD_ROS3 driver only performs I/O block caching when a file does NOT use paged file space allocation. If a file uses paged file space allocation, the library's existing page buffering mechanism will be used instead.

Remarks
  The value chosen for `block_size` involves a tradeoff between the number of S3 requests the H5FD_ROS3 driver might issue and how many bytes may be transferred as a result of those requests. Larger `block_size` values may result in less S3 requests being made, while potentially increasing the total number of bytes transferred if more data than necessary is cached. If `block_cache_size` is too small, I/O blocks may be evicted from the block cache and re-cached later, possibly resulting in the transferring of significantly more bytes than the size of the file.
  The value chosen for `block_cache_size` involves a tradeoff between performance and memory usage, with larger `block_cache_size` values causing more memory to be used to cache more I/O blocks.

Warning
  When `lock_superblock` is specified as `true`, the first I/O block cached when attempting to locate a file's superblock is assumed to contain the superblock metadata. If a file contains a user block that is as large as, or larger than, `block_size`, this will cause the I/O block containing the file's superblock metadata to NOT be locked in the I/O block cache. For this case, `block_size` should be adjusted accordingly to be at least as large as the user block plus some bytes for the superblock metadata.

Since
  2.2.0

## ◆ H5Pset_fapl_ros3_endpoint()

herr_t H5Pset_fapl_ros3_endpoint | ( | hid_t | fapl_id,
|  | const char * | endpoint )

Modifies the specified File Access Property List to use an alternative endpoint URL when opening files with the H5FD_ROS3 driver.

Parameters

  [in] | fapl_id | File access property list identifier
  [in] | endpoint | Alternate endpoint url.

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

H5Pset_fapl_ros3_endpoint() modifies an existing File Access Property List which is used by H5FD_ROS3 driver by adding or updating the endpoint url of the property list. When not specified, the H5FD_ROS3 driver uses the standard s3.<region-code>.amazonaws.com, unless an alternative endpoint URL is specified in the AWS_ENDPOINT_URL_S3 or AWS_ENDPOINT_URL environment variable. Be aware, to set the endpoint 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_endpoint().

Note, the endpoint url is only needed when you want to access a S3 bucket using an alternate url. For example, this can be useful when using s3:// object URIs to access files which are located somewhere other than the standard s3.<region-code>.amazonaws.com.

Since
  2.0.0

## ◆ H5Pset_fapl_ros3_token()

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_id | File access property list identifier
  [in] | token | Session/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()

herr_t H5Pset_fapl_sec2 | ( | hid_t | fapl_id | ) |

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

Parameters

  [in] | fapl_id | File 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()

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] | fapl | File access property list identifier
  [in] | meta_ext | Metadata filename extension
  [in] | meta_plist_id | File access property list identifier for the metadata file
  [in] | raw_ext | Raw 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(). There must be no other format specifiers in the string.

`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;
  fapl = H5Pcreate(H5P_FILE_ACCESS);
  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;
  fapl = H5Pcreate(H5P_FILE_ACCESS);
  H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "/pfs/%s-r.h5", H5P_DEFAULT);
  fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
  H5F_ACC_TRUNC
  #define H5F_ACC_TRUNC
  Definition H5Fpublic.h:30
  H5Pset_fapl_split
  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.
  H5Fcreate
  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()

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_id | File access property list identifier
  [in] | config_ptr | Configuration 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.12.1, back-ported to 1.10.7

## ◆ H5Pset_fapl_stdio()

herr_t H5Pset_fapl_stdio | ( | hid_t | fapl_id | ) |

Sets the standard I/O driver.

Parameters

  [in] | fapl_id | File 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_id | File access property list identifier
  [in] | vfd_config | Pointer 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()

herr_t H5Pset_fapl_windows | ( | hid_t | fapl_id | ) |

Sets the Windows I/O driver.

Parameters

  [in] | fapl_id | File 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_id | File access property list identifier
  [in] | degree | Pointer 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_id | File access property list identifier
  [in] | buf_ptr | Pointer to the initial file image, or NULL if no initial file image is desired
  [in] | buf_len | Size 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 before using this feature set. See the “See Also” section below for links to other elements of HDF5 file image operations.

See also
  - H5LTopen_file_image()
  - H5Fget_file_image()
  - H5Pget_file_image()
  - H5Pset_file_image_callbacks()
  - H5Pget_file_image_callbacks()
  - HDF5 File Image
  - Within H5Pset_file_image_callbacks():
  - Callback H5FD_file_image_callbacks_t
  - Callback H5FD_file_image_op_t

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 before using this feature set. See the “See Also” section below for links to other elements of HDF5 file image operations.

Parameters

  [in] | fapl_id | File access property list identifier
  [in,out] | callbacks_ptr | Pointer 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 Enumeration Datatypes:

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

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_NO_OP,
H5FD_FILE_IMAGE_OP_PROPERTY_LIST_SET,
H5FD_FILE_IMAGE_OP_PROPERTY_LIST_COPY,
H5FD_FILE_IMAGE_OP_PROPERTY_LIST_GET,
H5FD_FILE_IMAGE_OP_PROPERTY_LIST_CLOSE,
H5FD_FILE_IMAGE_OP_FILE_OPEN,
H5FD_FILE_IMAGE_OP_FILE_RESIZE,
H5FD_FILE_IMAGE_OP_FILE_CLOSE
} H5FD_file_image_op_t;

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,
|  | bool | use_file_locking,
|  | bool | ignore_when_disabled )

Sets the file locking property values.

Parameters

  [in] | fapl_id | File access property list identifier
  [in] | use_file_locking | Toggle to specify file locking (or not)
  [in] | ignore_when_disabled | Toggle 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_id | File access property list identifier
  [in] | gc_ref | Flag 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 reuses 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_id | File access property list identifier
  [in] | low | The earliest version of the library that will be used for writing objects
  [in] | high | The 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.

H5F_LIBVER_LATEST is equivalent to the highest explicitly numbered API 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=H5F_LIBVER_V200` `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 2.0.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.

The default settings are `low=H5F_LIBVER_V18`, `high=H5F_LIBVER_LATEST`.

Note
  H5F_LIBVER_LATEST:
  Since 2.0.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 2.0.x series, this setting will allow the object to be created.

Version
  2.0.0 Default setting for `low` changed to H5F_LIBVER_V18
  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_id | File access property list identifier
  [in] | config_ptr | Pointer 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:

typedef struct H5AC_cache_config_t {
/* general configuration fields: */
int version;
bool rpt_fcn_enabled;
bool open_trace_file;
bool close_trace_file;
char trace_file_name[H5AC__MAX_TRACE_FILE_NAME_LEN + 1];
bool evictions_enabled;
bool set_initial_size;
size_t initial_size;
double min_clean_fraction;
size_t max_size;
size_t min_size;
long int epoch_length;
/* size increase control fields: */
enum H5C_cache_incr_mode incr_mode;
double lower_hr_threshold;
double increment;
bool apply_max_increment;
size_t max_increment;
enum H5C_cache_flash_incr_mode flash_incr_mode;
double flash_multiple;
double flash_threshold;
/* size decrease control fields: */
enum H5C_cache_decr_mode decr_mode;
double upper_hr_threshold;
double decrement;
bool apply_max_decrement;
size_t max_decrement;
int epochs_before_eviction;
bool apply_empty_reserve;
double empty_reserve;
/* parallel configuration fields: */
size_t dirty_bytes_threshold;
int metadata_write_strategy;
} H5AC_cache_config_t;

(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_id | File access property list identifier
  [out] | config_ptr | Pointer 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:

typedef struct H5AC_cache_image_config_t {
int version;
bool generate_image;
bool save_resize_status;
int entry_ageout;
} H5AC_cache_image_config_t;

(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,
|  | bool | is_enabled,
|  | const char * | location,
|  | bool | start_on_access )

Sets metadata cache logging options.

Parameters

  [in] | plist_id | File access property list identifier
  [in] | is_enabled | Whether logging is enabled
  [in] | location | Location of log in UTF-8/ASCII (file path/name) (On Windows, this must be ASCII)
  [in] | start_on_access | Whether 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://support.hdfgroup.org/releases/hdf5/documentation/advanced_topics/FineTuningMetadataCache.md).

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_id | File access property list identifier
  [in] | size | Minimum 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_id | File access property list identifier
  [in] | attempts | The 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 */
fapl = H5Pcreate(H5P_FILE_ACCESS);
/* Set the # of read attempts */
H5Pset_metadata_read_attempts(fapl, 20);
/* 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 */
fapl = H5Pcreate(H5P_FILE_ACCESS);
/* Set the # of read attempts */
H5Pset_metadata_read_attempts(fapl, 20);
/* 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_id | File access property list identifier
  [in] | comm | MPI communicator
  [in] | info | MPI 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_id | File access property list identifier
  [in] | type | Type 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_id | File access property list identifier
  [in] | func | Callback function
  [in] | udata | User-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)
H5F_flush_cb_t
herr_t(* H5F_flush_cb_t)(hid_t object_id, void *udata)
Definition H5Fpublic.h:238

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 */
fapl_id = H5Pcreate(H5P_FILE_ACCESS);
/* 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;
}
H5Dopen2
hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id)
Opens an existing dataset.
H5Dflush
herr_t H5Dflush(hid_t dset_id)
Flushes all buffers associated with a dataset to disk.
H5Gflush
herr_t H5Gflush(hid_t group_id)
Flushes all buffers associated with a group to disk.
H5Gcreate2
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_id | File access property list identifier
  [in] | buf_size | Maximum size, in bytes, of the page buffer
  [in] | min_meta_per | Minimum metadata percentage to keep in the page buffer before allowing pages containing metadata to be evicted (Default is 0)
  [in] | min_raw_per | Minimum 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.

The arguments min_meta_perc and min_raw_perc are to prevent one type of data from evicting hot pages of the other type, that is, pushing them out of the buffer. Setting a minimum percentage for each type reserves a portion of the page buffer for that type, ensuring both metadata and raw data can maintain a presence in the buffer.

The following constraints apply to min_meta_perc and min_raw_perc:

- Each must be between 0 and 100 inclusive
- Their sum must not exceed 100, that is, together they can't reserve more than the entire page buffer.

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.

Note
  As of HDF5 2.0.0, the default page buffer size (0) may be overridden in some circumstances, such as when using the ROS3 file driver. To forcibly disable the page buffer, call this function with buf_size set to 0. To return this setting to the overridable default, call this function with buf_size set to H5F_PAGE_BUFFER_SIZE_DEFAULT. This macro is only available in HDF5 2.0.0 and later.

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_id | File access property list identifier
  [in] | flags | Relaxed 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_id | File access property list identifier
  [in] | size | Maximum 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 64KiB, indicating that file I/O for raw data reads and writes will occur in at least 64KiB 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_id | File access property list identifier
  [in] | size | Maximum 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_id | File access property list identifier
  [in] | new_vol_id | VOL connector identifier
  [in] | new_vol_info | Optional 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