Last modified: 4 December 2015
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. The H5F_mem_t ENUM is fully described in H5F_mem_t.html.

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:

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

History:
Release     Change
1.10.0 C function introduced in this release.