 |
HDF5 1.14.5
API Reference
|
|
HDF5 1.14.5
API Reference
|
Use file creation properties to control aspects of file creation such as setting a file space management strategy or creating a user block. Unlike file access properties, creation properties are stored with the file, and cannot be changed once a file has been created.
| Function | Purpose |
|---|---|
| H5Pset_userblock/H5Pget_userblock | Sets/retrieves size of userblock. |
| H5Pset_sizes/H5Pget_sizes | Sets/retrieves byte size of offsets and lengths used to address objects in HDF5 file. |
| H5Pset_sym_k/H5Pget_sym_k | Sets/retrieves size of parameters used to control symbol table nodes. |
| H5Pset_istore_k/H5Pget_istore_k | Sets/retrieves size of parameter used to control B-trees for indexing chunked datasets. |
| H5Pset_file_space_page_size/H5Pget_file_space_page_size | Sets or retrieves the file space page size used in paged aggregation and paged buffering. |
| H5Pset_file_space_strategy/H5Pget_file_space_strategy | Sets or retrieves the file space handling strategy, the persisting free-space and the free-space section size. |
| H5Pset_shared_mesg_nindexes/H5Pget_shared_mesg_nindexes | Sets or retrieves number of shared object header message indexes in file creation property list. |
| H5Pset_shared_mesg_index | Configures the specified shared object header message index. |
| H5Pget_shared_mesg_index | Retrieves the configuration settings for a shared message index. |
| H5Pset_shared_mesg_phase_change/H5Pget_shared_mesg_phase_change | Sets or retrieves shared object header message storage phase change thresholds. |
| H5Pget_version |
Functions | |
| herr_t | H5Pget_file_space_page_size (hid_t plist_id, hsize_t *fsp_size) |
| Retrieves the file space page size for a file creation property list. | |
| herr_t | H5Pget_file_space_strategy (hid_t plist_id, H5F_fspace_strategy_t *strategy, hbool_t *persist, hsize_t *threshold) |
| Retrieves the file space handling strategy, persisting free-space condition and threshold value for a file creation property list. | |
| herr_t | H5Pget_istore_k (hid_t plist_id, unsigned *ik) |
| Queries the 1/2 rank of an indexed storage B-tree. | |
| herr_t | H5Pget_shared_mesg_index (hid_t plist_id, unsigned index_num, unsigned *mesg_type_flags, unsigned *min_mesg_size) |
| Retrieves the configuration settings for a shared message index. | |
| herr_t | H5Pget_shared_mesg_nindexes (hid_t plist_id, unsigned *nindexes) |
| Retrieves the number of shared object header message indexes in file creation property list. | |
| herr_t | H5Pget_shared_mesg_phase_change (hid_t plist_id, unsigned *max_list, unsigned *min_btree) |
| Retrieves shared object header message phase change information. | |
| herr_t | H5Pget_sizes (hid_t plist_id, size_t *sizeof_addr, size_t *sizeof_size) |
| Retrieves the size of the offsets and lengths used in an HDF5 file. | |
| herr_t | H5Pget_sym_k (hid_t plist_id, unsigned *ik, unsigned *lk) |
| Retrieves the size of the symbol table B-tree 1/2 rank and the symbol table leaf node 1/2 size. | |
| herr_t | H5Pget_userblock (hid_t plist_id, hsize_t *size) |
| Retrieves the size of a user block. | |
| herr_t | H5Pset_file_space_page_size (hid_t plist_id, hsize_t fsp_size) |
| Sets the file space page size for a file creation property list. | |
| herr_t | H5Pset_file_space_strategy (hid_t plist_id, H5F_fspace_strategy_t strategy, hbool_t persist, hsize_t threshold) |
| Sets the file space handling strategy and persisting free-space values for a file creation property list. | |
| herr_t | H5Pset_istore_k (hid_t plist_id, unsigned ik) |
| Sets the size of the parameter used to control the B-trees for indexing chunked datasets. | |
| herr_t | H5Pset_shared_mesg_index (hid_t plist_id, unsigned index_num, unsigned mesg_type_flags, unsigned min_mesg_size) |
| Configures the specified shared object header message index. | |
| herr_t | H5Pset_shared_mesg_nindexes (hid_t plist_id, unsigned nindexes) |
| Sets number of shared object header message indexes. | |
| herr_t | H5Pset_shared_mesg_phase_change (hid_t plist_id, unsigned max_list, unsigned min_btree) |
| Sets shared object header message storage phase change thresholds. | |
| herr_t | H5Pset_sizes (hid_t plist_id, size_t sizeof_addr, size_t sizeof_size) |
| Sets the byte size of the offsets and lengths used to address objects in an HDF5 file. | |
| herr_t | H5Pset_sym_k (hid_t plist_id, unsigned ik, unsigned lk) |
| herr_t | H5Pset_userblock (hid_t plist_id, hsize_t size) |
| Sets user block size. | |
| herr_t | H5Pget_version (hid_t plist_id, unsigned *boot, unsigned *freelist, unsigned *stab, unsigned *shhdr) |
| Retrieves the version information of various objects for a file creation property list(deprecated) | |
| herr_t | H5Pset_file_space (hid_t plist_id, H5F_file_space_type_t strategy, hsize_t threshold) |
| Sets the file space handling strategy and the free-space section size threshold. | |
| herr_t | H5Pget_file_space (hid_t plist_id, H5F_file_space_type_t *strategy, hsize_t *threshold) |
| Retrieves the file space handling strategy, and threshold value for a file creation property list. | |
| herr_t H5Pget_file_space | ( | hid_t | plist_id, |
| H5F_file_space_type_t * | strategy, | ||
| hsize_t * | threshold | ||
| ) |
Retrieves the file space handling strategy, and threshold value for a file creation property list.
| [in] | plist_id | File creation property list identifier |
| [out] | strategy | Pointer to the file space handling strategy |
| [out] | threshold | Pointer to the free-space section size threshold value |
Maps to the function H5Pget_file_space_strategy()
Retrieves the file space page size for a file creation property list.
| [in] | plist_id | File creation property list identifier |
| [out] | fsp_size | File space page size |
H5Pget_file_space_page_size() retrieves the file space page size for paged aggregation in the parameter fsp_size.
The library default is 4KB (4096) if fsp_size is not previously set via a call to H5Pset_file_space_page_size().
| herr_t H5Pget_file_space_strategy | ( | hid_t | plist_id, |
| H5F_fspace_strategy_t * | strategy, | ||
| hbool_t * | persist, | ||
| hsize_t * | threshold | ||
| ) |
Retrieves the file space handling strategy, persisting free-space condition and threshold value for a file creation property list.
| [in] | plist_id | File creation property list identifier |
| [out] | strategy | The file space handling strategy |
| [out] | persist | The boolean value indicating whether free space is persistent or not |
| [out] | threshold | The free-space section size threshold value |
H5Pget_file_space_strategy() retrieves the file space handling strategy, the persisting free-space condition and the threshold value in the parameters strategy, persist and threshold respectively.
The library default values returned when H5Pset_file_space_strategy() has not been called are:
strategy - H5F_FSPACE_STRATEGY_FSM_AGGR persist - 0 threshold - 1Queries the 1/2 rank of an indexed storage B-tree.
| [in] | plist_id | File creation property list identifier |
| [out] | ik | Pointer to location to return the chunked storage B-tree 1/2 rank (Default value of B-tree 1/2 rank: 32) |
H5Pget_istore_k() queries the 1/2 rank of an indexed storage B-tree.
The argument ik may be the null pointer (NULL). This function is valid only for file creation property lists.
ik parameter type changed to unsigned. | herr_t H5Pget_shared_mesg_index | ( | hid_t | plist_id, |
| unsigned | index_num, | ||
| unsigned * | mesg_type_flags, | ||
| unsigned * | min_mesg_size | ||
| ) |
Retrieves the configuration settings for a shared message index.
| [in] | plist_id | File creation property list identifier |
| [in] | index_num | Index being configured |
| [out] | mesg_type_flags | Types of messages that may be stored in this index |
| [out] | min_mesg_size | Minimum message size |
H5Pget_shared_mesg_index() retrieves the message type and minimum message size settings from the file creation property list plist_id for the shared object header message index specified by index_num.
index_num specifies the index. index_num is zero-indexed, so in a file with three indexes, they will be numbered 0, 1, and 2.
mesg_type_flags and min_mesg_size will contain, respectively, the types of messages and the minimum size, in bytes, of messages that can be stored in this index.
Valid message types are described in H5Pset_shared_mesg_index().
Retrieves the number of shared object header message indexes in file creation property list.
| [in] | plist_id | File creation property list identifier |
| [out] | nindexes | Number of shared object header message indexes available in files created with this property list |
H5Pget_shared_mesg_nindexes() retrieves the number of shared object header message indexes in the specified file creation property list plist_id.
If the value of nindexes is 0 (zero), shared object header messages are disabled in files created with this property list.
| herr_t H5Pget_shared_mesg_phase_change | ( | hid_t | plist_id, |
| unsigned * | max_list, | ||
| unsigned * | min_btree | ||
| ) |
Retrieves shared object header message phase change information.
| [in] | plist_id | File creation property list identifier |
| [out] | max_list | Threshold above which storage of a shared object header message index shifts from list to B-tree |
| [out] | min_btree | Threshold below which storage of a shared object header message index reverts to list format |
H5Pget_shared_mesg_phase_change() retrieves the threshold values for storage of shared object header message indexes in a file. These phase change thresholds determine the point at which the index storage mechanism changes from a more compact list format to a more performance-oriented B-tree format, and vice-versa.
By default, a shared object header message index is initially stored as a compact list. When the number of messages in an index exceeds the specified max_list threshold, storage switches to a B-tree format for improved performance. If the number of messages subsequently falls below the min_btree threshold, the index will revert to the list format.
If max_list is set to 0 (zero), shared object header message indexes in the file will always be stored as B-trees.
plist_id specifies the file creation property list.
Retrieves the size of the offsets and lengths used in an HDF5 file.
| [in] | plist_id | File creation property list identifier |
| [out] | sizeof_addr | Pointer to location to return offset size in bytes |
| [out] | sizeof_size | Pointer to location to return length size in bytes |
H5Pget_sizes() retrieves the size of the offsets and lengths used in an HDF5 file. This function is only valid for file creation property lists.
Retrieves the size of the symbol table B-tree 1/2 rank and the symbol table leaf node 1/2 size.
| [in] | plist_id | File creation property list identifier |
| [out] | ik | Pointer to location to return the symbol table's B-tree 1/2 rank (Default value of B-tree 1/2 rank: 16) |
| [out] | lk | Pointer to location to return the symbol table's leaf node 1/2 size (Default value of leaf node 1/2 size: 4) |
H5Pget_sym_k() retrieves the size of the symbol table B-tree 1/2 rank and the symbol table leaf node 1/2 size.
This function is valid only for file creation property lists.
If a parameter value is set to NULL, that parameter is not retrieved.
ik parameter type changed to unsigned ik parameter has changed from type int to unsigned Retrieves the size of a user block.
| [in] | plist_id | File creation property list identifier |
| [out] | size | Pointer to location to return user-block size |
H5Pget_userblock() retrieves the size of a user block in a file creation property list.
| herr_t H5Pget_version | ( | hid_t | plist_id, |
| unsigned * | boot, | ||
| unsigned * | freelist, | ||
| unsigned * | stab, | ||
| unsigned * | shhdr | ||
| ) |
Retrieves the version information of various objects for a file creation property list(deprecated)
| [in] | plist_id | Property list identifier |
| [out] | boot | Pointer to location to return super block version number |
| [out] | freelist | Pointer to location to return global freelist version number |
| [out] | stab | Pointer to location to return symbol table version number |
| [out] | shhdr | Pointer to location to return shared object header version number |
H5Pget_version() retrieves the version information of various objects for a file creation property list. Any pointer parameters which are passed as NULL are not queried.
boot, freelist, stab, shhdr parameter types changed to unsigned.| herr_t H5Pset_file_space | ( | hid_t | plist_id, |
| H5F_file_space_type_t | strategy, | ||
| hsize_t | threshold | ||
| ) |
Sets the file space handling strategy and the free-space section size threshold.
| [in] | plist_id | File creation property list identifier |
| [in] | strategy | The file space handling strategy to be used. See: H5F_fspace_strategy_t |
| [in] | threshold | The smallest free-space section size that the free space manager will track |
Maps to the function H5Pset_file_space_strategy().
Sets the file space page size for a file creation property list.
| [in] | plist_id | File creation property list identifier |
| [in] | fsp_size | File space page size |
H5Pset_file_space_page_size() sets the file space page size fsp_size used in paged aggregation and paged buffering.
fsp_size has a minimum size of 512. Setting a value less than 512 will return an error. The library default size for the file space page size when not set is 4096.
The size set via this routine may not be changed for the life of the file.
| herr_t H5Pset_file_space_strategy | ( | hid_t | plist_id, |
| H5F_fspace_strategy_t | strategy, | ||
| hbool_t | persist, | ||
| hsize_t | threshold | ||
| ) |
Sets the file space handling strategy and persisting free-space values for a file creation property list.
| [in] | plist_id | File creation property list identifier |
| [in] | strategy | The file space handling strategy to be used. See: H5F_fspace_strategy_t |
| [in] | persist | A boolean value to indicate whether free space should be persistent or not |
| [in] | threshold | The smallest free-space section size that the free space manager will track |
H5Pset_file_space_strategy() sets the file space handling strategy, specifies persisting free-space or not (persist), and sets the free-space section size threshold in the file creation property list plist_id.
H5F_fspace_strategy_t is a struct defined in H5Fpublic.h as follows:
This setting cannot be changed for the life of the file.
As the H5F_FSPACE_STRATEGY_AGGR and H5F_FSPACE_STRATEGY_NONE strategies do not use the free-space managers, the persist and threshold settings will be ignored for those strategies.
Sets the size of the parameter used to control the B-trees for indexing chunked datasets.
| [in] | plist_id | File creation property list identifier |
| [in] | ik | 1/2 rank of chunked storage B-tree |
H5Pset_istore_k() sets the size of the parameter used to control the B-trees for indexing chunked datasets. This function is valid only for file creation property lists.
ik is one half the rank of a tree that stores chunked raw data. On average, such a tree will be 75% full, or have an average rank of 1.5 times the value of ik.
The HDF5 library uses (ik*2) as the maximum # of entries before splitting a B-tree node. Since only 2 bytes are used in storing # of entries for a B-tree node in an HDF5 file, (ik*2) cannot exceed 65536. The default value for ik is 32.
ik parameter type changed to unsigned. | herr_t H5Pset_shared_mesg_index | ( | hid_t | plist_id, |
| unsigned | index_num, | ||
| unsigned | mesg_type_flags, | ||
| unsigned | min_mesg_size | ||
| ) |
Configures the specified shared object header message index.
| [in] | plist_id | File creation property list identifier |
| [in] | index_num | Index being configured |
| [in] | mesg_type_flags | Types of messages that should be stored in this index |
| [in] | min_mesg_size | Minimum message size |
H5Pset_shared_mesg_index() is used to configure the specified shared object header message index, setting the types of messages that may be stored in the index and the minimum size of each message.
plist_id specifies the file creation property list.
index_num specifies the index to be configured. index_num is zero-indexed, so in a file with three indexes, they will be numbered 0, 1, and 2.
mesg_type_flags and min_mesg_size specify, respectively, the types and minimum size of messages that can be stored in this index.
Valid message types are as follows:
| H5O_SHMESG_NONE_FLAG | No shared messages |
| H5O_SHMESG_SDSPACE_FLAG | Simple dataspace message |
| H5O_SHMESG_DTYPE_FLAG | Datatype message |
| H5O_SHMESG_FILL_FLAG | Fill value message |
| H5O_SHMESG_PLINE_FLAG | Filter pipeline message |
| H5O_SHMESG_ATTR_FLAG | Attribute message |
| H5O_SHMESG_ALL_FLAG | All message types; i.e., equivalent to the following: (H5O_SHMESG_SDSPACE_FLAG | H5O_SHMESG_DTYPE_FLAG | H5O_SHMESG_FILL_FLAG | H5O_SHMESG_PLINE_FLAG | H5O_SHMESG_ATTR_FLAG) |
Sets number of shared object header message indexes.
| [in] | plist_id | File creation property list identifier |
| [in] | nindexes | Number of shared object header message indexes to be available in files created with this property list (nindexes must be <= H5O_SHMESG_MAX_NINDEXES (8)) |
H5Pset_shared_mesg_nindexes() sets the number of shared object header message indexes in the specified file creation property list.
This setting determines the number of shared object header message indexes, nindexes, that will be available in files created with this property list. These indexes can then be configured with H5Pset_shared_mesg_index().
If nindexes is set to 0 (zero), shared object header messages are disabled in files created with this property list.
There is a limit of H5O_SHMESG_MAX_NINDEXES (8) that can be set with H5Pset_shared_mesg_nindexes(). An error will occur if specifying a value of nindexes that is greater than this value.
Sets shared object header message storage phase change thresholds.
| [in] | plist_id | File creation property list identifier |
| [in] | max_list | Threshold above which storage of a shared object header message index shifts from list to B-tree |
| [in] | min_btree | Threshold below which storage of a shared object header message index reverts to list format |
H5Pset_shared_mesg_phase_change() sets threshold values for storage of shared object header message indexes in a file. These phase change thresholds determine the point at which the index storage mechanism changes from a more compact list format to a more performance-oriented B-tree format, and vice-versa.
By default, a shared object header message index is initially stored as a compact list. When the number of messages in an index exceeds the threshold value of max_list, storage switches to a B-tree for improved performance. If the number of messages subsequently falls below the min_btree threshold, the index will revert to the list format.
If max_list is set to 0 (zero), shared object header message indexes in the file will be created as B-trees and will never revert to lists.
plist_id specifies the file creation property list.
Sets the byte size of the offsets and lengths used to address objects in an HDF5 file.
| [in] | plist_id | File creation property list identifier |
| [in] | sizeof_addr | Size of an object offset in bytes |
| [in] | sizeof_size | Size of an object length in bytes |
H5Pset_sizes() sets the byte size of the offsets and lengths used to address objects in an HDF5 file. This function is only valid for file creation property lists. Passing in a value of 0 for one of the parameters retains the current value. The default value for both values is the same as sizeof(hsize_t) in the library (normally 8 bytes). Valid values currently are 2, 4, 8 and 16.
| [in] | plist_id | File creation property list identifier |
| [in] | ik | Symbol table tree rank |
| [in] | lk | Symbol table node size |
H5Pset_sym_k() sets the size of parameters used to control the symbol table nodes.
This function is valid only for file creation property lists. Passing in a value of zero (0) for one of the parameters retains the current value.
ik is one half the rank of a B-tree that stores a symbol table for a group. Internal nodes of the symbol table are on average 75% full. That is, the average rank of the tree is 1.5 times the value of ik. The HDF5 library uses (ik*2) as the maximum # of entries before splitting a B-tree node. Since only 2 bytes are used in storing # of entries for a B-tree node in an HDF5 file, (ik*2) cannot exceed 65536. The default value for ik is 16.
lk is one half of the number of symbols that can be stored in a symbol table node. A symbol table node is the leaf of a symbol table tree which is used to store a group. When symbols are inserted randomly into a group, the group's symbol table nodes are 75% full on average. That is, they contain 1.5 times the number of symbols specified by lk. The default value for lk is 4.
ik parameter type changed to unsigned. ik parameter has changed from type int to unsigned.Sets user block size.
| [in] | plist_id | File creation property list identifier |
| [in] | size | Size of the user-block in bytes |
H5Pset_userblock() sets the user block size of a file creation property list. The default user block size is 0; it may be set to any power of 2 equal to 512 or greater (512, 1024, 2048, etc.).
1.9.7