Last modified: 4 April 2016
Name: H5Pset_file_space
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 an HDF5 file’s file space to meet specific needs.

Description:
  `H5Pset_file_space` sets the file space management strategy for the file associated with `fcpl_id` as specified in `strategy` and sets the file-space threshold to `threshold`.

  Available strategies are described in the “Parameters:” section below.

  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 `threshold` for the file.

  Passing `0` (zero) for `strategy` or `thresold` indicates that 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 that are 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 any of 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 greater than or equal to 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 (Not yet available.)

History:

  Release | Change
  1.10.0 | C function introduced in this release.