![]() |
HDF5
1.13.0
|
Functions | |
H5_DLL 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... | |
H5_DLL 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... | |
H5_DLL hid_t | H5Pget_driver (hid_t plist_id) |
Returns low-lever driver identifier. More... | |
H5_DLL herr_t | H5Pget_fclose_degree (hid_t fapl_id, H5F_close_degree_t *degree) |
Returns the file close degree. More... | |
H5_DLL 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... | |
H5_DLL herr_t | H5Pset_alignment (hid_t fapl_id, hsize_t threshold, hsize_t alignment) |
Sets alignment properties of a file access property list. More... | |
H5_DLL 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... | |
H5_DLL herr_t | H5Pset_driver (hid_t plist_id, hid_t driver_id, const void *driver_info) |
Sets a file driver. More... | |
H5_DLL herr_t | H5Pset_fclose_degree (hid_t fapl_id, H5F_close_degree_t degree) |
Sets the file close degree. More... | |
H5_DLL 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 | 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... | |
const void * | H5Pget_driver_info (hid_t plist_id) |
Returns a pointer to file driver information. 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_gc_references (hid_t fapl_id, unsigned *gc_ref) |
Returns garbage collecting references setting. More... | |
herr_t | H5Pget_multi_type (hid_t fapl_id, H5FD_mem_t *type) |
Retrieves type of data property for MULTI driver. 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.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 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()).
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.
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_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.
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.
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. [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.
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. [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.
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 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.
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. |
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 |
|