 |
HDF5
1.10.9-1
C-API Reference
|
|
|
HDF5
1.10.9-1
C-API Reference
|
|
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.
Functions | |
| H5_DLL herr_t | H5Pset_fapl_core (hid_t fapl_id, size_t increment, hbool_t backing_store) |
| Modifies the file access property list to use the H5FD_CORE driver. More... | |
| H5_DLL herr_t | H5Pget_fapl_core (hid_t fapl_id, size_t *increment, hbool_t *backing_store) |
| Queries core file driver properties. More... | |
| H5_DLL herr_t | H5Pset_fapl_direct (hid_t fapl_id, size_t alignment, size_t block_size, size_t cbuf_size) |
| Sets up use of the direct I/O driver. More... | |
| H5_DLL herr_t | H5Pget_fapl_direct (hid_t fapl_id, size_t *boundary, size_t *block_size, size_t *cbuf_size) |
| Retrieves direct I/O driver settings. More... | |
| H5_DLL herr_t | H5Pset_fapl_family (hid_t fapl_id, hsize_t memb_size, hid_t memb_fapl_id) |
| Sets the file access property list to use the family driver. More... | |
| H5_DLL herr_t | H5Pget_fapl_family (hid_t fapl_id, hsize_t *memb_size, hid_t *memb_fapl_id) |
| Returns file access property list information. More... | |
| H5_DLL herr_t | H5Pget_fapl_hdfs (hid_t fapl_id, H5FD_hdfs_fapl_t *fa_out) |
| H5_DLL herr_t | H5Pset_fapl_hdfs (hid_t fapl_id, H5FD_hdfs_fapl_t *fa) |
| H5_DLL herr_t | H5Pset_fapl_log (hid_t fapl_id, const char *logfile, unsigned long long flags, size_t buf_size) |
| Sets up the logging virtual file driver (H5FD_LOG) for use. More... | |
| H5_DLL herr_t | H5Pset_fapl_mpio (hid_t fapl_id, MPI_Comm comm, MPI_Info info) |
| Stores MPI IO communicator information to the file access property list. More... | |
| H5_DLL herr_t | H5Pget_fapl_mpio (hid_t fapl_id, MPI_Comm *comm, MPI_Info *info) |
| Returns MPI IO communicator information. More... | |
| H5_DLL herr_t | H5Pset_fapl_multi (hid_t fapl_id, const H5FD_mem_t *memb_map, const hid_t *memb_fapl, const char *const *memb_name, const haddr_t *memb_addr, hbool_t relax) |
| Sets up use of the multi-file driver. More... | |
| H5_DLL herr_t | H5Pget_fapl_multi (hid_t fapl_id, H5FD_mem_t *memb_map, hid_t *memb_fapl, char **memb_name, haddr_t *memb_addr, hbool_t *relax) |
| Returns information about the multi-file access property list. More... | |
| H5_DLL herr_t | H5Pset_fapl_split (hid_t fapl, const char *meta_ext, hid_t meta_plist_id, const char *raw_ext, hid_t raw_plist_id) |
| Emulates the old split file driver. More... | |
| H5_DLL herr_t | H5Pget_fapl_ros3 (hid_t fapl_id, H5FD_ros3_fapl_t *fa_out) |
| H5_DLL herr_t | H5Pset_fapl_ros3 (hid_t fapl_id, H5FD_ros3_fapl_t *fa) |
| H5_DLL herr_t | H5Pset_fapl_splitter (hid_t fapl_id, H5FD_splitter_vfd_config_t *config_ptr) |
| H5_DLL herr_t | H5Pget_fapl_splitter (hid_t fapl_id, H5FD_splitter_vfd_config_t *config_ptr) |
| herr_t | H5Pset_fapl_stdio (hid_t fapl_id) |
| Sets the standard I/O driver. More... | |
| H5_DLL herr_t | H5Pset_fapl_windows (hid_t fapl_id) |
| Sets the Windows I/O driver. More... | |
| 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. More... | |
| 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. More... | |
| herr_t | H5Pget_core_write_tracking (hid_t fapl_id, hbool_t *is_enabled, size_t *page_size) |
| Gets information about the write tracking feature used by the core VFD. More... | |
| hid_t | H5Pget_driver (hid_t plist_id) |
| Returns low-lever driver identifier. More... | |
| const void * | H5Pget_driver_info (hid_t plist_id) |
| Returns a pointer to file driver information. More... | |
| herr_t | H5Pget_elink_file_cache_size (hid_t plist_id, unsigned *efc_size) |
| Retrieves the size of the external link open file cache. More... | |
| herr_t | H5Pget_evict_on_close (hid_t fapl_id, hbool_t *evict_on_close) |
| Retrieves the file access property list setting that determines whether an HDF5 object will be evicted from the library's metadata cache when it is closed. More... | |
| herr_t | H5Pget_family_offset (hid_t fapl_id, hsize_t *offset) |
| Retrieves a data offset from the file access property list. More... | |
| herr_t | H5Pget_fclose_degree (hid_t fapl_id, H5F_close_degree_t *degree) |
| Returns the file close degree. More... | |
| 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. More... | |
| 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. More... | |
| herr_t | H5Pget_file_locking (hid_t fapl_id, hbool_t *use_file_locking, hbool_t *ignore_when_disabled) |
| Retrieves the file locking property values. More... | |
| herr_t | H5Pget_gc_references (hid_t fapl_id, unsigned *gc_ref) |
| Returns garbage collecting references setting. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| herr_t | H5Pget_mdc_log_options (hid_t plist_id, hbool_t *is_enabled, char *location, size_t *location_size, hbool_t *start_on_access) |
| Gets metadata cache logging options. More... | |
| herr_t | H5Pget_meta_block_size (hid_t fapl_id, hsize_t *size) |
| Returns the current metadata block size setting. More... | |
| herr_t | H5Pget_metadata_read_attempts (hid_t plist_id, unsigned *attempts) |
| Retrieves the number of read attempts from a file access property list. More... | |
| herr_t | H5Pget_multi_type (hid_t fapl_id, H5FD_mem_t *type) |
| Retrieves type of data property for MULTI driver. More... | |
| 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. More... | |
| 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. More... | |
| herr_t | H5Pget_sieve_buf_size (hid_t fapl_id, size_t *size) |
| Returns maximum data sieve buffer size. More... | |
| herr_t | H5Pget_small_data_block_size (hid_t fapl_id, hsize_t *size) |
| Retrieves the current small data block size setting. More... | |
| herr_t | H5Pset_alignment (hid_t fapl_id, hsize_t threshold, hsize_t alignment) |
| Sets alignment properties of a file access property list. More... | |
| 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. More... | |
| herr_t | H5Pset_core_write_tracking (hid_t fapl_id, hbool_t is_enabled, size_t page_size) |
| Sets write tracking information for core driver, H5FD_CORE. More... | |
| herr_t | H5Pset_driver (hid_t plist_id, hid_t driver_id, const void *driver_info) |
| Sets a file driver. More... | |
| 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. More... | |
| herr_t | H5Pset_evict_on_close (hid_t fapl_id, hbool_t evict_on_close) |
| Controls the library's behavior of evicting metadata associated with a closed object. More... | |
| 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. More... | |
| herr_t | H5Pset_fclose_degree (hid_t fapl_id, H5F_close_degree_t degree) |
| Sets the file close degree. More... | |
| 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. More... | |
| 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. More... | |
| herr_t | H5Pset_file_locking (hid_t fapl_id, hbool_t use_file_locking, hbool_t ignore_when_disabled) |
| Sets the file locking property values. More... | |
| herr_t | H5Pset_gc_references (hid_t fapl_id, unsigned gc_ref) |
| Sets garbage collecting references flag. More... | |
| 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. More... | |
| 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. More... | |
| herr_t | H5Pset_mdc_log_options (hid_t plist_id, hbool_t is_enabled, const char *location, hbool_t start_on_access) |
| Sets metadata cache logging options. More... | |
| herr_t | H5Pset_meta_block_size (hid_t fapl_id, hsize_t size) |
| Sets the minimum metadata block size. More... | |
| herr_t | H5Pset_metadata_read_attempts (hid_t plist_id, unsigned attempts) |
| Sets the number of read attempts in a file access property list. More... | |
| 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. More... | |
| 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. More... | |
| herr_t | H5Pset_sieve_buf_size (hid_t fapl_id, size_t size) |
| Sets the maximum size of the data sieve buffer. More... | |
| 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. More... | |
| herr_t | H5Pset_coll_metadata_write (hid_t plist_id, hbool_t is_collective) |
| Sets metadata write mode to collective or independent (default) More... | |
| herr_t | H5Pget_coll_metadata_write (hid_t plist_id, hbool_t *is_collective) |
| Retrieves metadata write mode setting. More... | |
| 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. More... | |
| 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. More... | |
Retrieves the current settings for alignment properties from a file access property list.
| [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 |
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).
| 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.
| [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 |
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.
mdc_nelmts parameter discontinued. Metadata cache configuration is managed with H5Pset_mdc_config() and H5Pget_mdc_config() rdcc_nbytes and rdcc_nslots parameters changed from type int to size_t.Retrieves metadata write mode setting.
| [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) |
H5Pget_coll_metadata_write() retrieves the collective metadata write setting from the file access property into is_collective.
Gets information about the write tracking feature used by the core VFD.
| [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 |
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.
page_size parameter should be a power of two.Returns low-lever driver identifier.
| [in] | plist_id | Property list identifier |
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.
| Driver Name | Driver Identifier | Description | Related Function |
|---|---|---|---|
| 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() |
| 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() |
| Log | H5FD_LOG | This is the H5FD_SEC2 driver with logging capabilities. | H5Pset_fapl_log() |
| 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() |
| 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() |
| 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() |
| 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() |
| 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() |
| 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.
| const void* H5Pget_driver_info | ( | hid_t | plist_id | ) |
Returns a pointer to file driver information.
| [in] | plist_id | File access or data transfer property list identifier |
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.
Retrieves the size of the external link open file cache.
| [in] | plist_id | File access property list identifier |
| [out] | efc_size | External link open file cache size in number of files |
H5Pget_elink_file_cache_size() retrieves the number of files that can be held open in an external link open file cache.
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.
| [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 |
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.
Retrieves a data offset from the file access property list.
| [in] | fapl_id | File access property list identifier |
| [out] | offset | Offset in bytes within the HDF5 file |
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).
Queries core file driver properties.
| [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 |
H5Pget_fapl_core() queries the H5FD_CORE driver properties as set by H5Pset_fapl_core().
| H5_DLL herr_t H5Pget_fapl_direct | ( | hid_t | fapl_id, |
| size_t * | boundary, | ||
| size_t * | block_size, | ||
| size_t * | cbuf_size | ||
| ) |
Retrieves direct I/O driver settings.
| [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 |
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.
Returns file access property list information.
| [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 |
H5Pget_fapl_family() returns file access property list for use with the family driver. This information is returned through the output parameters.
| H5_DLL herr_t H5Pget_fapl_hdfs | ( | hid_t | fapl_id, |
| H5FD_hdfs_fapl_t * | fa_out | ||
| ) |
Returns MPI IO communicator information.
| [in] | fapl_id | File access property list identifier |
| [out] | comm | MPI-2 communicator |
| [out] | info | MPI-2 info object |
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.
| H5_DLL herr_t H5Pget_fapl_multi | ( | hid_t | fapl_id, |
| H5FD_mem_t * | memb_map, | ||
| hid_t * | memb_fapl, | ||
| char ** | memb_name, | ||
| haddr_t * | memb_addr, | ||
| hbool_t * | relax | ||
| ) |
Returns information about the multi-file access property list.
| [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 |
H5Pget_fapl_multi() returns information about the multi-file access property list.
| H5_DLL herr_t H5Pget_fapl_ros3 | ( | hid_t | fapl_id, |
| H5FD_ros3_fapl_t * | fa_out | ||
| ) |
| H5_DLL herr_t H5Pget_fapl_splitter | ( | hid_t | fapl_id, |
| H5FD_splitter_vfd_config_t * | config_ptr | ||
| ) |
| herr_t H5Pget_fclose_degree | ( | hid_t | fapl_id, |
| H5F_close_degree_t * | degree | ||
| ) |
Returns the file close degree.
| [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 |
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.
Retrieves a copy of the file image designated as the initial content and structure of a file.
| [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) |
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.
| 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.
| [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. |
H5Pget_file_image_callbacks() retrieves the callback routines set for working with file images opened with the file access property list fapl_id.
The callbacks must have been previously set with H5Pset_file_image_callbacks() in the file access property list.
Upon the successful return of H5Pset_file_image_callbacks(), the fields in the instance of the H5FD_file_image_callbacks_t struct pointed to by callbacks_ptr will contain the same values as were passed in the most recent H5Pset_file_image_callbacks() call for the file access property list fapl_id.
| herr_t H5Pget_file_locking | ( | hid_t | fapl_id, |
| hbool_t * | use_file_locking, | ||
| hbool_t * | ignore_when_disabled | ||
| ) |
Retrieves the file locking property values.
| [in] | fapl_id | File access property list identifier |
| [out] | use_file_locking | File locking flag |
| [out] | ignore_when_disabled | Ignore when disabled flag |
H5Pget_file_locking() retrieves the file locking property values for the file access property list specified by fapl_id.
Returns garbage collecting references setting.
| [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. |
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().
| 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.
| [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 |
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.
| 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.
| [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 |
in direction applies only to the H5AC_cache_config_t::version field. All other fields are out parameters.The fields of the H5AC_cache_config_t structure are shown below:
(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.
| 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.
| [in] | plist_id | File access property list identifier |
| [out] | config_ptr | Pointer to metadata cache image configuration values |
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:
(Click on a enumerator, field, or type for more information.)
| herr_t H5Pget_mdc_log_options | ( | hid_t | plist_id, |
| hbool_t * | is_enabled, | ||
| char * | location, | ||
| size_t * | location_size, | ||
| hbool_t * | start_on_access | ||
| ) |
Gets metadata cache logging options.
| [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 |
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() / H5Fstop_mdc_logging() functions. H5Pget_mdc_log_options() can be used to examine a file access property list, and H5Fget_mdc_logging_status() will return the current state of the logging flags.
The log format is described in the Metadata Cache Logging document.
Returns the current metadata block size setting.
| [in] | fapl_id | File access property list identifier |
| [out] | size | Minimum size, in bytes, of metadata block allocations |
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.
Retrieves the number of read attempts from a file access property list.
| [in] | plist_id | File access property list identifier |
| [out] | attempts | The number of read attempts |
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():
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:
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.
The first example illustrates the two cases for retrieving the number of read attempts from a default file access property list.
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 acccess.
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 acccess.
| herr_t H5Pget_multi_type | ( | hid_t | fapl_id, |
| H5FD_mem_t * | type | ||
| ) |
Retrieves type of data property for MULTI driver.
| [in] | fapl_id | File access property list or data transfer property list identifier |
| [out] | type | Type of data |
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 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.
| 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.
| [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 |
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.
The example below illustrates the usage of this routine to obtain the object flush property values.
| 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.
| [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 |
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.
Returns maximum data sieve buffer size.
| [in] | fapl_id | File access property list identifier |
| [in] | size | Maximum size, in bytes, of data sieve buffer |
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.
size parameter has changed from type hsize_t to size_t Retrieves the current small data block size setting.
| [in] | fapl_id | File access property list identifier |
| [out] | size | Maximum size, in bytes, of the small data block |
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.
Sets alignment properties of a file access property list.
| [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 |
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 which 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 which 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().
| 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.
| [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 521. |
| [in] | rdcc_nbytes | Total size of the raw data chunk cache in bytes. The default size is 1 MB 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. |
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 is 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().
mdc_nelmts parameter was discontinued. Metadata cache configuration is managed with H5Pset_mdc_config() and H5Pget_mdc_config(). rdcc_nbytes and rdcc_nelmts parameters changed from type int to size_t. Sets metadata write mode to collective or independent (default)
| [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) |
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.
Sets write tracking information for core driver, H5FD_CORE.
| [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. |
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.
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.
page_size is set to 0 (zero). Sets a file driver.
| [in] | plist_id | Property list identifier |
| [in] | driver_id | The new driver identifier |
| [in] | driver_info | Optional struct containing driver properties |
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.
Sets the number of files that can be held open in an external link open file cache.
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 siginificantly 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.
| [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). |
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.
The following code sets up an external link open file cache that will hold open up to 8 files reached through external links:
Controls the library's behavior of evicting metadata associated with a closed object.
| [in] | fapl_id | File access property list identifier |
| [in] | evict_on_close | Whether the HDF5 object should be evicted on close |
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.
Sets offset property for low-level access to a file in a family of files.
| [in] | fapl_id | File access property list identifier |
| [in] | offset | Offset in bytes within the HDF5 file |
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.
Modifies the file access property list to use the H5FD_CORE driver.
| [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 |
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.
| H5_DLL herr_t H5Pset_fapl_direct | ( | hid_t | fapl_id, |
| size_t | alignment, | ||
| size_t | block_size, | ||
| size_t | cbuf_size | ||
| ) |
Sets up use of the direct I/O driver.
| [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 |
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.
Sets the file access property list to use the family driver.
| [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 |
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.
memb_size parameter was changed. | H5_DLL herr_t H5Pset_fapl_hdfs | ( | hid_t | fapl_id, |
| H5FD_hdfs_fapl_t * | fa | ||
| ) |
| H5_DLL herr_t H5Pset_fapl_log | ( | hid_t | fapl_id, |
| const char * | logfile, | ||
| unsigned long long | flags, | ||
| size_t | buf_size | ||
| ) |
Sets up the logging virtual file driver (H5FD_LOG) for use.
| [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) |
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).
| 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.
| Flag | VFD Call | Output and Comments |
|---|---|---|
| H5FD_LOG_LOC_READ | Read | %10a-%10a (%10Zu bytes) (s) ReadStart 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) WrittenStart 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-%10aStart 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 timesStart 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 timesStart 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 sStart 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 sSee also: H5FD_LOG_LOC_READ |
| H5FD_LOG_TIME_WRITE | Close, Write | Total time in write operations: %f sSee also: H5FD_LOG_LOC_WRITE |
| H5FD_LOG_TIME_SEEK | Close, Read, Write | Total time in write operations: %f sSee 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) AllocatedStart of address space End of address space Total size allocation Flavor of allocation |
| 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 |
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. verbosity parameter has been removed. Two new parameters have been added: flags of type unsigned and buf_size of type size_t. Stores MPI IO communicator information to the file access property list.
| [in] | fapl_id | File access property list identifier |
| [in] | comm | MPI-2 communicator |
| [in] | info | MPI-2 info object |
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-2. 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-2. 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.
| H5_DLL herr_t H5Pset_fapl_multi | ( | hid_t | fapl_id, |
| const H5FD_mem_t * | memb_map, | ||
| const hid_t * | memb_fapl, | ||
| const char *const * | memb_name, | ||
| const haddr_t * | memb_addr, | ||
| hbool_t | relax | ||
| ) |
Sets up use of the multi-file driver.
| [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 |
H5Pset_fapl_multi() sets the file access property list fapl_id to use the multi-file driver.
The multi-file driver enables different types of HDF5 data and metadata to be written to separate files. These files are viewed by the HDF5 library and the application as a single virtual HDF5 file with a single HDF5 file address space. The types of data that can be broken out into separate files include raw data, the superblock, B-tree data, global heap data, local heap data, and object headers. At the programmer's discretion, two or more types of data can be written to the same file while other types of data are written to separate files.
The array memb_map maps memory usage types to other memory usage types and is the mechanism that allows the caller to specify how many files are created. The array contains H5FD_MEM_NTYPES entries, which are either the value H5FD_MEM_DEFAULT or a memory usage type. The number of unique values determines the number of files that are opened.
The array memb_fapl contains a property list for each memory usage type that will be associated with a file.
The array memb_name should be a name generator (a printf-style format with a s which will be replaced with the name passed to H5FDopen(), usually from H5Fcreate() or H5Fopen()).
The array memb_addr specifies the offsets within the virtual address space, from 0 (zero) to HADDR_MAX, at which each type of data storage begins.
If relax is set to 1 (TRUE), then opening an existing file for read-only access will not fail if some file members are missing. This allows a file to be accessed in a limited sense if just the meta data is available.
Default values for each of the optional arguments are as follows:
memb_map | The default member map contains the value H5FD_MEM_DEFAULT for each element. |
memb_fapl | The default value is H5P_DEFAULT for each element. |
memb_name | The default string is s-X.h5 where X is one of the following letters:
|
memb_addr | The default setting is that the address space is equally divided among all of the elements:
|
memb_name parameter type changed to const char* const*. | H5_DLL herr_t H5Pset_fapl_ros3 | ( | hid_t | fapl_id, |
| H5FD_ros3_fapl_t * | fa | ||
| ) |
| H5_DLL herr_t H5Pset_fapl_split | ( | hid_t | fapl, |
| const char * | meta_ext, | ||
| hid_t | meta_plist_id, | ||
| const char * | raw_ext, | ||
| hid_t | raw_plist_id | ||
| ) |
Emulates the old split file driver.
| [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 |
H5Pset_fapl_split() is a compatibility function that enables the multi-file driver to emulate the split driver from HDF5 Releases 1.0 and 1.2. The split file driver stored metadata and raw data in separate files but provided no mechanism for separating types of metadata.
fapl is a file access property list identifier.
meta_ext is the filename extension for the metadata file. The extension is appended to the name passed to H5FDopen(), usually from H5Fcreate() or H5Fopen(), to form the name of the metadata file. If the string s is used in the extension, it works like the name generator as in H5Pset_fapl_multi().
meta_plist_id is the file access property list identifier for the metadata file.
raw_ext is the filename extension for the raw data file. The extension is appended to the name passed to H5FDopen(), usually from H5Fcreate() or H5Fopen(), to form the name of the raw data file. If the string s is used in the extension, it works like the name generator as in H5Pset_fapl_multi().
raw_plist_id is the file access property list identifier for the raw data file.
If a user wishes to check to see whether this driver is in use, the user must call H5Pget_driver() and compare the returned value to the string H5FD_MULTI. A positive match will confirm that the multi driver is in use; HDF5 provides no mechanism to determine whether it was called as the special case invoked by H5Pset_fapl_split().
| H5_DLL herr_t H5Pset_fapl_splitter | ( | hid_t | fapl_id, |
| H5FD_splitter_vfd_config_t * | config_ptr | ||
| ) |
Sets the standard I/O driver.
| [in] | fapl_id | File access property list identifier |
H5Pset_fapl_stdio() modifies the file access property list to use the standard I/O driver, H5FDstdio().
Sets the Windows I/O driver.
| [in] | fapl_id | File access property list identifier |
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.
| herr_t H5Pset_fclose_degree | ( | hid_t | fapl_id, |
| H5F_close_degree_t | degree | ||
| ) |
Sets the file close degree.
| [in] | fapl_id | File access property list identifier |
| [in] | degree | Pointer to a location containing the file close degree property, the value of degree |
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. |
Sets an initial file image in a memory buffer.
| [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 |
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.
| 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.
| [in] | fapl_id | File access property list identifier |
| [in,out] | callbacks_ptr | Pointer to the instance of the H5FD_file_image_callbacks_t structure |
fapl_id.H5Pset_file_image_callbacks() sets callback functions for working with file images in memory.
H5Pset_file_image_callbacks() allows an application to control the management of file image buffers through user defined callbacks. These callbacks can be used in the management of file image buffers in property lists and with certain file drivers.
H5Pset_file_image_callbacks() must be used before any file image has been set in the file access property list. Once a file image has been set, the function will fail.
The callback routines set up by H5Pset_file_image_callbacks() are invoked when a new file image buffer is allocated, when an existing file image buffer is copied or resized, or when a file image buffer is released from use.
Some file drivers allow the use of user-defined callback functions for allocating, freeing, and copying the driver’s internal buffer, potentially allowing optimizations such as avoiding large malloc and memcpy operations, or to perform detailed logging.
From the perspective of the HDF5 library, the operations of the image_malloc, image_memcpy, image_realloc, and image_free callbacks must be identical to those of the corresponding C standard library calls (malloc, memcpy, realloc, and free). While the operations must be identical, the file image callbacks have more parameters. The return values of image_malloc and image_realloc are identical to the return values of malloc and realloc. The return values of image_malloc and image_free differ from the return values of memcpy and free in that the return values of image_memcpy and image_free can also indicate failure.
The callbacks and their parameters, along with a struct and an ENUM required for their use, are described below.
Callback struct and ENUM:
The callback functions set up by H5Pset_file_image_callbacks() use a struct and an ENUM that are defined as follows
The struct H5FD_file_image_callbacks_t serves as a container for the callback functions and a pointer to user-supplied data. The struct is defined as follows:
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:
The elements of the H5FD_file_image_op_t are used in the following callbacks:
malloc() call.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.)NULL indicates that HDF5 should invoke the standard C library memcpy() routine when copying buffers.realloc() call.NULL indicates that HDF5 should invoke the standard C library realloc() routine when resizing file image buffers.free() call, except that it will return 0 (SUCCEED) on success and -1 (FAIL) on failure.NULL indicates that HDF5 should invoke the standard C library free() routine when releasing file image buffers.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.NULL, this parameter should be NULL as well.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.| herr_t H5Pset_file_locking | ( | hid_t | fapl_id, |
| hbool_t | use_file_locking, | ||
| hbool_t | ignore_when_disabled | ||
| ) |
Sets the file locking property values.
| [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) |
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.
Sets garbage collecting references flag.
| [in] | fapl_id | File access property list identifier |
| [in] | gc_ref | Flag setting reference garbage collection to on (1) or off (0) |
H5Pset_gc_references() sets the flag for garbage collecting references for the file.
Dataset region references and other reference types use space in an HDF5 file's global heap. If garbage collection is on and the user passes in an uninitialized value in a reference structure, the heap might get corrupted. When garbage collection is off, however, and the user re-uses a reference, the previous heap block will be orphaned and not returned to the free heap space.
When garbage collection is on, the user must initialize the reference structures to 0 or risk heap corruption.
The default value for garbage collecting references is off.
| 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.
| [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 |
H5Pset_libver_bounds() controls the range of library release versions that will be used when creating objects in a file. The object format versions are determined indirectly from the library release versions specified in the call.
This property is set in the file access property list specified by the parameter fapl_id.
The parameter low sets the earliest possible format versions that the library will use when creating objects in the file. Note that earliest possible is different from earliest, as some features introduced in library versions later than 1.0.0 resulted in updates to object formats. The parameter high sets the latest format versions that the library will be allowed to use when creating objects in the file.
The parameters low and high must be one of the enumerated values in the H5F_libver_t struct, which is defined in H5Fpublic.h.
The macro H5F_LIBVER_LATEST is aliased to the highest enumerated value in H5F_libver_t, indicating that this is currently the latest format available.
The library supports the following five 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=H5F_LIBVER_V18 |
|
low=H5F_LIBVER_EARLIEST high=H5F_LIBVER_V110 |
|
low=H5F_LIBVER_V18 high=H5F_LIBVER_V18 |
|
low=H5F_LIBVER_V18 high=H5F_LIBVER_V110 |
|
low=H5F_LIBVER_V110 high=H5F_LIBVER_V110 |
|
| 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.
| [in] | plist_id | File access property list identifier |
| [in] | config_ptr | Pointer to the instance of H5AC_cache_config_t containing the desired configuration |
The fields of the H5AC_cache_config_t structure are shown below:
(Click on a enumerator, field, or type for more information.)
H5Pset_mdc_config() attempts to set the initial metadata cache configuration to the supplied value. It will fail if an invalid configuration is detected. This configuration is used when the file is opened.
See the overview of the metadata cache in the special topics section of the user manual for details on what is being configured. If you have not read and understood that documentation, you really should not be using this API call.
| 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.
| [in] | plist_id | File access property list identifier |
| [out] | config_ptr | Pointer to metadata cache image configuration values |
H5Pset_mdc_image_config() sets the metadata cache image option with configuration values specified by config_ptr for the file access property list specified in plist_id.
H5AC_cache_image_config_t is defined as follows:
(Click on a enumerator, field, or type for more information.)
n will be driven by application behavior, but n = 10 seems a good starting point.| herr_t H5Pset_mdc_log_options | ( | hid_t | plist_id, |
| hbool_t | is_enabled, | ||
| const char * | location, | ||
| hbool_t | start_on_access | ||
| ) |
Sets metadata cache logging options.
| [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 |
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.
Sets the minimum metadata block size.
| [in] | fapl_id | File access property list identifier |
| [in] | size | Minimum size, in bytes, of metadata block allocations |
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.
Sets the number of read attempts in a file access property list.
| [in] | plist_id | File access property list identifier |
| [in] | attempts | The number of read attempts. Must be a value greater than 0 |
0.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:
N, the library will use N.100).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.
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.
| 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.
| [in] | fapl_id | File access property list identifier |
| [in] | type | Type of data to be accessed |
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.
| 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.
| [in] | plist_id | File access property list identifier |
| [in] | func | Callback function |
| [in] | udata | User-defined callback function context |
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:
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.
| 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.
| [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) |
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() or H5Fopen() using the plist_id will fail.
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.
Sets the maximum size of the data sieve buffer.
| [in] | fapl_id | File access property list identifier |
| [in] | size | Maximum size, in bytes, of data sieve buffer |
H5Pset_sieve_buf_size() sets size, the maximum size in bytes of the data sieve buffer, which is used by file drivers that are capable of using data sieving.
The data sieve buffer is used when performing I/O on datasets in the file. Using a buffer which is large enough to hold several pieces of the dataset being read in for hyperslab selections boosts performance by quite a bit.
The default value is set to 64KB, indicating that file I/O for raw data reads and writes will occur in at least 64KB blocks. Setting the value to zero (0) with this API function will turn off the data sieving, even if the VFL driver attempts to use that strategy.
Internally, the library checks the storage sizes of the datasets in the file. It picks the smaller one between the size from the file access property and the size of the dataset to allocate the sieve buffer for the dataset in order to save memory usage.
size parameter has changed from type hsize_t to size_t.Sets the size of a contiguous block reserved for small data.
| [in] | fapl_id | File access property list identifier |
| [in] | size | Maximum size, in bytes, of the small data block. The default size is 2048. |
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.
1.9.1