Last modified: 4 April 2016
Name: H5Pget_file_space
Signature:
  herr_t `H5Pget_file_space`( hid_t `fcpl_id`, H5F_file_space_type_t *`strategy`, hsize_t *`threshold` )

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

Motivation:
  `H5Pget_file_space` provides the means for applications to manage an HDF5 file’s file space to meet specific needs.

Description:
  `H5Pget_file_space` retrieves the file space management strategy and/or the free-space threshold specified for a file.

  The first parameter, `fcpl_id`, is the file creation property list identifier associated with an HDF5 file.

  If `strategy` is non-null, this routine will retrieve the existing file space management strategy in use for the file and store it in `strategy`.

  If `threshold` is non-null, this routine will retrieve the existing free-space section threshold used by the library’s free space managers for the file and store it in `threshold`.

  Any pointer parameters which are passed as `NULL` are not queried.

Parameters:

  hid_t `fcpl_id` |  | IN: The file creation property list identifier.
  H5F_file_space_type_t *`strategy`
  |  | IN/OUT: The file space management strategy currently in use for the file. Valid values for `strategy` are described in the `strategy` parameter description in the `H5Pset_file_space` entry.
  hsize_t *`threshold` |  | IN/OUT: The current free-space section threshold.

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

Failure Modes:
  This routine will fail when either of the following is true:
  - The library fails to retrieve the file creation property list associated with `fcpl_id`.
  - The library fails to retrieve the strategy and/or threshold in the file creation property list associated with `fcpl_id`.

Example Usage:
  The first example retrieves the file space management handling strategy in use for the file associated with `fcpl` in the parameter `strategy`. It also retrieves the free-space section threshold in use for the file in the parameter `threshold`.

      H5Pget_file_space(fcpl, &strategy, &threshold);

  The second example retrieves the file space management strategy for the file associated with `fcpl` in the parameter `strategy`. Since the second parameter is null, this routine does not retrieve the free-space section threshold in use for the file.

      H5Pset_file_space(fcpl, &strategy, NULL);

See Also:
  `H5Pset_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.