HDF5  1.13.0
File Access Properties

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...
 

Detailed Description

Function Documentation

◆ H5Pget_alignment()

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

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


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

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

Since
1.0.0

◆ H5Pget_cache()

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

Queries the raw data chunk cache parameters.


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

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

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

Note that the mdc_nelmts parameter is no longer used.

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

◆ H5Pget_core_write_tracking()

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

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


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

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

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

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

◆ H5Pget_driver()

hid_t H5Pget_driver ( hid_t  plist_id)

Returns low-lever driver identifier.


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

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

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

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.

Since
1.4.0

◆ H5Pget_driver_info()

const void* H5Pget_driver_info ( hid_t  plist_id)

Returns a pointer to file driver information.


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

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

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

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

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

◆ H5Pget_family_offset()

herr_t H5Pget_family_offset ( hid_t  fapl_id,
hsize_t *  offset 
)

Retrieves a data offset from the file access property list.


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

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

Todo:
References the VFL documentation.
Since
1.6.0

◆ H5Pget_fclose_degree()

herr_t H5Pget_fclose_degree ( hid_t  fapl_id,
H5F_close_degree_t degree 
)

Returns the file close degree.


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

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

Since
1.6.0

◆ H5Pget_gc_references()

herr_t H5Pget_gc_references ( hid_t  fapl_id,
unsigned *  gc_ref 
)

Returns garbage collecting references setting.


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

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

Since
1.2.0

◆ H5Pget_libver_bounds()

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

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


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

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

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

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

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

◆ H5Pget_multi_type()

herr_t H5Pget_multi_type ( hid_t  fapl_id,
H5FD_mem_t type 
)

Retrieves type of data property for MULTI driver.


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

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

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

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

Since
1.6.0

◆ H5Pset_alignment()

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

Sets alignment properties of a file access property list.


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

H5Pset_alignment() sets the alignment properties of a file access property list so that any file object greater than or equal in size to threshold bytes will be aligned on an address 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().

Since
1.0.0

◆ H5Pset_cache()

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

Sets the raw data chunk cache parameters.


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

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

The raw data chunk cache inserts chunks into the cache by first computing a hash value using the address of a chunk and then by using that hash value as the chunk’s index into the table of cached chunks. In other words, the size of this hash table and the number of possible hash values 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.

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

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

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

The raw data chunk cache inserts chunks into the cache by first computing a hash value using the address of a chunk and then by using that hash value as the chunk’s index into the table of cached chunks. In other words, the size of this hash table and the number of possible hash values 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.

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

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

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

The raw data chunk cache inserts chunks into the cache by first computing a hash value using the address of a chunk and then by using that hash value as the chunk’s index into the table of cached chunks. In other words, the size of this hash table and the number of possible hash values 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.

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

◆ H5Pset_driver()

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

Sets a file driver.


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

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

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

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

◆ H5Pset_fclose_degree()

herr_t H5Pset_fclose_degree ( hid_t  fapl_id,
H5F_close_degree_t  degree 
)

Sets the file close degree.


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

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

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

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

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

◆ H5Pset_libver_bounds()

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

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


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

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

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

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

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

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

The library supports the following 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
  • The library will create objects with the earliest possible format versions.
  • The library will allow objects to be created with the latest format versions available to library release 1.8.x.
  • API calls that create objects or features that are available to versions of the library greater than 1.8.x release will fail.
low=H5F_LIBVER_EARLIEST
high=H5F_LIBVER_V110
  • The library will create objects with the earliest possible format versions.
  • The library will allow objects to be created with the latest format versions available to library release 1.10.x. Since 1.10.x is also H5F_LIBVER_LATEST, there is no upper limit on the format versions to use. For example, if a newer format version is required to support a feature e.g. virtual dataset, this setting will allow the object to be created.
  • This is the library default setting and provides the greatest format compatibility.
low=H5F_LIBVER_V18
high=H5F_LIBVER_V18
  • The library will create objects with the latest format versions available to library release 1.8.x.
  • API calls that create objects or features that are available to versions of the library greater than 1.8.x release will fail.
  • Earlier versions of the library may not be able to access objects created with this setting.
low=H5F_LIBVER_V18
high=H5F_LIBVER_V110
  • The library will create objects with the latest format versions available to library release 1.8.x.
  • The library will allow objects to be created with the latest format versions available to library release 1.10.x. Since 1.10.x is also H5F_LIBVER_LATEST, there is no upper limit on the format versions to use. For example, if a newer format version is required to support a feature e.g. virtual dataset, this setting will allow the object to be created.
  • Earlier versions of the library may not be able to access objects created with this setting.
low=H5F_LIBVER_V110
high=H5F_LIBVER_V110
  • The library will create objects with the latest format versions available to library release 1.10.x.
  • The library will allow objects to be created with the latest format versions available to library release 1.10.x. Since 1.10.x is also H5F_LIBVER_LATEST, there is no upper limit on the format versions to use. For example, if a newer format version is required to support a feature e.g. virtual dataset, this setting will allow the object to be created.
  • This setting allows users to take advantage of the latest features and performance enhancements in the library. However, objects written with this setting may be accessible to a smaller range of library versions than would be the case if low is set to H5F_LIBVER_EARLIEST.
  • Earlier versions of the library may not be able to access objects created with this setting.
Version
1.10.2 H5F_LIBVER_V18 added to the enumerated defines in H5F_libver_t.
Since
1.8.0