Last modified: 4 April 2016
Name: H5Fget_free_sections
Signature:
  ssize_t `H5Fget_free_sections`( hid_t `fcpl_id`, H5F_mem_t `type`, size_t `nsects`, H5F_sect_info_t * `sect_info` )

Purpose:
  Retrieves free-space section information for a file.

Description:
  `H5Fget_free_sections` retrieves free-space section information for the free-space manager with `type` that is associated with file `fcpl_id`. If `type` is H5FD_MEM_DEFAULT, this routine retrieves free-space section information for all the free-space managers in the file.

  This routine retrieves free-space section information for `nsects` sections or at most the maximum number of sections in the specified free-space manager. If the number of sections is not known, a preliminary `H5Fget_free_sections()` call can be made by setting `sect_info` to NULL and the total number of free-space sections for the specified free-space manager will be returned. Users can then allocate space for entries in `sect_info`, each of which is defined as an `H5F_sect_info_t` struct (see Parameters section).

Parameters:

  hid_t `fcpl_id` |  | IN: The file creation property list identifier.
  H5F_mem_t `type` |  | IN: The file memory allocation type. Valid values are as follows:
  `H5FD_MEM_DEFAULT` | The default file memory allocation type.
  `H5FD_MEM_SUPER` | File memory allocated for Superblock.
  `H5FD_MEM_BTREE` | File memory allocated for B-tree.
  `H5FD_MEM_DRAW` | File memory allocated for raw data.
  `H5FD_MEM_GHEAP` | File memory allocated for Global Heap.
  `H5FD_MEM_LHEAP` | File memory allocated for Local Heap.
  `H5FD_MEM_OHDR` | File memory allocated for Object Header.
  There are other file memory allocation types that are mapped to the above six basic types.
  hsize_t `nsects` |  | IN: The number of free-space sections.
  H5F_sect_info_t *`sect_info` |  | IN/OUT: Pointer to instances of `H5F_sect_info_t` in which the free-space section information is to be returned. An H5F_sect_info_t struct is defined as follows (in `H5Fpublic.h`):
              typedef struct H5F_sect_info_t {
                  haddr_t     addr;     /* address of the     */
                                        /* free-space section */
                  hsize_t     size;     /* size of the        */
                                        /* free-space section */
              } H5F_sect_info_t;

Returns:
  Returns the number of free-space sections for the specified free-space manager in the file; otherwise returns a negative value.

Failure Modes:
  This routine will fail when the following is true:
  - The library fails to retrieve the file creation property list associated with `fcpl_id`.
  - If the parameter `sect_info` is nonnull, but the parameter `nsects` is equal to 0.
  - The library fails to retrieve free-space section information for the file associated with the file creation property list `fcpl_id`.

Example Usage:
  The first example shows that the first call to `H5Fget_free_sections()` returns the total number of free-space sections in `nsects` for all the free-space managers in the file that is associated with `fcpl`. The second call to `H5Fget_free_sections()` retrieves free-space section information in `sect_info` for `nsects` sections. The value in `ret` is the same as `nsects`.

      nsects = H5Fget_free_sections(fcpl, H5FD_MEM_DEFAULT, 0, NULL);
      :
      : Allocate space for entries in sect_info
      :
      ret = H5F_get_free_sections(fcpl, H5FD_MEM_DEFAULT, nsects, sect_info);

  The second example shows that the first call to `H5Fget_free_sections()` returns the total number of free-space sections in `nsects` for the `H5FD_MEM_SUPER` free-space manager in the file that is associated with `fcpl`. Even though there are `nsects` sections for the specified free-space manager, the second call to `H5Fget_free_sections()` retrieves free-space section information in `sect_info` for `nsects-1` sections as requested. The value in `ret` is the same as `nsects`.

      nsects = H5Fget_free_sections(fcpl, H5FD_MEM_SUPER, 0, NULL);
      :
      : Allocate space for entries in sect_info
      :
      ret = H5F_get_free_sections(fcpl, H5FD_MEM_SUPER, nsects-1, sect_info);

  The third example shows that the first call to `H5Fget_free_sections()` returns the total number of free-space sections in `nsects` for the `H5FD_MEM_BTREE` free-space manager in the file that is associated with `fcpl`. Even though the second call to `H5Fget_free_sections()` requests `nsects+1` sections, the routine retrieves free-space section information in `sect_info` for only `nsects` sections. The value in `ret` is the same as `nsects`.

      nsects = H5Fget_free_sections(fcpl, H5FD_MEM_BTREE, 0, NULL);
      :
      : Allocate space for entries in sect_info
      :
      ret = H5F_get_free_sections(fcpl, H5FD_MEM_BTREE, nsects+1, sect_info);

See Also:
  `H5Pset_file_space`
  `H5Pget_file_space`

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