Description:

H5F_GET_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 H5F_GET_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).

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 non-null, 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:

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.

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.

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+1sections, the routine retrieves free-space section information in sect_info for only nsects sections. The value in ret is the same as nsects.