 |
HDF5
1.8.23
C-API Reference
|
|
|
HDF5
1.8.23
C-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.
Functions | |
| herr_t | H5Pget_istore_k (hid_t plist_id, unsigned *ik) |
| Queries the 1/2 rank of an indexed storage B-tree. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| herr_t | H5Pget_userblock (hid_t plist_id, hsize_t *size) |
| Retrieves the size of a user block. More... | |
| 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) More... | |
| 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. More... | |
| 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. More... | |
| herr_t | H5Pset_shared_mesg_nindexes (hid_t plist_id, unsigned nindexes) |
| Sets number of shared object header message indexes. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
Queries 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. 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.4