- Created by Mike McGreevy, last modified by Barbara Jones on Apr 08, 2021
H5F_GET_FREE_SECTIONS
Retrieves free-space section information for a file
Procedure:
H5F_GET_FREE_SECTIONS (file_id, type, nsects, sect_info)
Signature:
ssize_t H5Fget_free_sections(hid_t file_id, H5F_mem_t type, size_t nsects, H5F_sect_info_t *sect_info/*out*/)
Parameters:
hid_t file_id | IN: The file identifier | ||||||||||||||
H5F_mem_t type | IN: The file memory allocation type Valid values are as follows:
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 returnedAn H5F_sect_info_t struct is defined as follows (in 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; |
Description:
H5F_GET_FREE_SECTIONS retrieves free-space section information for the free-space manager with type that is associated with file identifier file_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 associated with
file_id. - If the parameter
sect_infois non-null, but the parameternsectsis equal to 0. - The library fails to retrieve free-space section information for the file specified by
file_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.
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+1sections, 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);
History:
| Release | Change |
|---|---|
| 1.10.0 | C function introduced in this release. |
--- Last Modified: April 08, 2021 | 09:39 AM