Last modified: 4 December 2015

Signature:

herr_t H5Pset_file_space( hid_t fcpl_id, H5F_file_space_type_t strategy, hsize_t threshold )

Purpose:

Sets the file space management strategy and/or free-space section threshold for an HDF5 file.

Motivation:

H5Pset_file_space provides the means for applications to manage the HDF5 file's file space for their specific needs.

Description:

H5Pset_file_space sets the file space management strategy for the file associated with fcpl_id to strategy. There are four strategies that applications can select and they are described in the Parameters section.

This routine can also set the free-space section threshold to threshold so that the library’s free-space managers will track only free-space sections whose size is greater than or equal to the value of threshold for the file.

Passing a zero value for strategy or thresold indicates the corresponding parameter's value should not be modified as a result of the call.

Note: The file space management strategy and/or free-space section threshold set via this routine cannot be changed once the file is created.

Parameters:

hid_t fcpl_id

IN: The file creation property list identifier.

H5F_file_space_type_t strategy

IN: The strategy for file space management.

Valid values are as follows:

H5F_FILE_SPACE_ALL_PERSIST
With this strategy, the free-space managers track the free space that results from the manipulation of HDF5 objects in the HDF5 file. The free space information is saved when the file is closed, and reloaded when the file is reopened.
When space is needed for file metadata or raw data, the HDF5 library first requests space from the library's free-space managers. If the request is not satisfied, the library requests space from the aggregators. If the request is still not satisfied, the library requests space from the virtual file driver. That is, the library will use all of the mechanisms for allocating space.

H5F_FILE_SPACE_ALL (Default file space management strategy)
With this strategy, the free-space managers track the free space that results from the manipulation of HDF5 objects in the HDF5 file. The free space information is NOT saved when the file is closed and the free space that exists upon file closing becomes unaccounted space in the file.
Like the previous strategy, the library will try all of the mechanisms for allocating space. When space is needed for file metadata or raw data, the library first requests space from the free-space managers. If the request is not satisfied, the library requests space from the aggregators. If the request is still not satisfied, the library requests space from the virtual file driver.

H5F_FILE_SPACE_AGGR_VFD
With this strategy, the library does not track free space that results from the manipulation of HDF5 obejcts in the HDF5 file and the free space becomes unaccounted space in the file.
When space is needed for file metadata or raw data, the library first requests space from the aggregators. If the request is not satisfied, the library requests space from the virtual file driver.

H5F_FILE_SPACE_VFD
With this strategy, the library does not track free space that results from the manipulation of HDF5 obejcts in the HDF5 file and the free space becomes unaccounted space in the file.
When space is needed for file metadata or raw data, the library requests space from the virtual file driver.

Passing a value of zero (0) indicates that the value of strategy is not to be modified.

hsize_t threshold

IN: The free-space section threshold. The library default is 1, which is to track all free-space sections.

Passing a value of zero (0) indicates that the value of threshold is not to be modified.

Returns:

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

Failure Modes:

This routine will fail when the following is true:

strategy is not one of the valid values listed above.
The library fails to retrieve the file creation property list associated with fcpl_id.
The library fails to set the strategy and/or threshold in the file creation property list associated with fcpl_id.

Example Usage:

The first example sets the file space management strategy for the file associated with fcpl to H5F_FILE_SPACE_ALL_PERSIST. It also sets the free-space section threshold to 10, which means that the library's free-space managers will track only free-space sections whose size is >= 10 for the file.

H5Pset_file_space(fcpl, H5F_FILE_SPACE_ALL_PERSIST, (hsize_t)10);

The second example sets the file space management strategy for the file associated with fcpl to H5F_FILE_SPACE_VFD. It does not change the free-space section threshold in use for the file.

H5Pset_file_space(fcpl, H5F_FILE_SPACE_VFD, (hsize_t)0);

See Also:

H5Pget_file_space

H5Fget_free_sections
H5Fget_freespace
H5Fget_info

h5repack
h5dump
h5stat

HDF5 Guide to File Space Management

History:

Release	Change
1.10.0	C function introduced in this release.