Please, help us to better know about our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5  1.10.9-1
C-API Reference
File Creation Properties

Detailed Description

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_file_space_page_size (hid_t plist_id, hsize_t *fsp_size)
 Retrieves the file space page size for a file creation property list. More...
 
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. More...
 
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 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. More...
 
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. 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...
 
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_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. More...
 
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. More...
 

Function Documentation

◆ H5Pget_file_space()

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.

Parameters
[in]plist_idFile creation property list identifier
[out]strategyPointer to the file space handling strategy
[out]thresholdPointer to the free-space section size threshold value
Returns
Returns a non-negative value if successful; otherwise returns a negative value.
Deprecated:
When was this function deprecated?

Maps to the function H5Pget_file_space_strategy()

◆ H5Pget_file_space_page_size()

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.

Parameters
[in]plist_idFile creation property list identifier
[out]fsp_sizeFile space page size
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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

Since
1.10.1

◆ H5Pget_file_space_strategy()

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.

Parameters
[in]plist_idFile creation property list identifier
[out]strategyThe file space handling strategy
[out]persistThe boolean value indicating whether free space is persistent or not
[out]thresholdThe free-space section size threshold value
Returns
Returns a non-negative value if successful; otherwise returns a negative 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:

Since
1.10.1

◆ H5Pget_istore_k()

herr_t H5Pget_istore_k ( hid_t  plist_id,
unsigned *  ik 
)

Queries the 1/2 rank of an indexed storage B-tree.

Parameters
[in]plist_idFile creation property list identifier
[out]ikPointer to location to return the chunked storage B-tree 1/2 rank (Default value of B-tree 1/2 rank: 32)
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

See also
H5Pset_istore_k()
Version
1.6.4 ik parameter type changed to unsigned.
Since
1.0.0

◆ H5Pget_shared_mesg_index()

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.

Parameters
[in]plist_idFile creation property list identifier
[in]index_numIndex being configured
[out]mesg_type_flagsTypes of messages that may be stored in this index
[out]min_mesg_sizeMinimum message size
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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

Since
1.8.0

◆ H5Pget_shared_mesg_nindexes()

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.

Parameters
[in]plist_idFile creation property list identifier
[out]nindexesNumber of shared object header message indexes available in files created with this property list
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

Since
1.8.0

◆ H5Pget_shared_mesg_phase_change()

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.

Parameters
[in]plist_idFile creation property list identifier
[out]max_listThreshold above which storage of a shared object header message index shifts from list to B-tree
[out]min_btreeThreshold below which storage of a shared object header message index reverts to list format
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

Since
1.8.0

◆ H5Pget_sizes()

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.

Parameters
[in]plist_idFile creation property list identifier
[out]sizeof_addrPointer to location to return offset size in bytes
[out]sizeof_sizePointer to location to return length size in bytes
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

Since
1.0.0

◆ H5Pget_sym_k()

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.

Parameters
[in]plist_idFile creation property list identifier
[out]ikPointer to location to return the symbol table's B-tree 1/2 rank (Default value of B-tree 1/2 rank: 16)
[out]lkPointer to location to return the symbol table's leaf node 1/2 size (Default value of leaf node 1/2 size: 4)
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

See also
H5Pset_sym_k()
Version
1.6.4 ik parameter type changed to unsigned
1.6.0 The ik parameter has changed from type int to unsigned
Since
1.0.0

◆ H5Pget_userblock()

herr_t H5Pget_userblock ( hid_t  plist_id,
hsize_t size 
)

Retrieves the size of a user block.

Parameters
[in]plist_idFile creation property list identifier
[out]sizePointer to location to return user-block size
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

H5Pget_userblock() retrieves the size of a user block in a file creation property list.

Since
1.0.0

◆ H5Pget_version()

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)

Parameters
[in]plist_idProperty list identifier
[out]bootPointer to location to return super block version number
[out]freelistPointer to location to return global freelist version number
[out]stabPointer to location to return symbol table version number
[out]shhdrPointer to location to return shared object header version number
Returns
Returns a non-negative value if successful; otherwise returns a negative value.
Deprecated:
Deprecated in favor of the function H5Fget_info()

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.

Version
1.6.4 boot, freelist, stab, shhdr parameter types changed to unsigned.

◆ H5Pset_file_space()

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.

Parameters
[in]plist_idFile creation property list identifier
[in]strategyThe file space handling strategy to be used. See: H5F_fspace_strategy_t
[in]thresholdThe smallest free-space section size that the free space manager will track
Returns
Returns a non-negative value if successful; otherwise returns a negative value.
Deprecated:
When was this function deprecated?

Maps to the function H5Pset_file_space_strategy().

◆ H5Pset_file_space_page_size()

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.

Parameters
[in]plist_idFile creation property list identifier
[in]fsp_sizeFile space page size
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

Since
1.10.1

◆ H5Pset_file_space_strategy()

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.

Parameters
[in]plist_idFile creation property list identifier
[in]strategyThe file space handling strategy to be used. See: H5F_fspace_strategy_t
[in]persistA boolean value to indicate whether free space should be persistent or not
[in]thresholdThe smallest free-space section size that the free space manager will track
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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:

typedef enum H5F_fspace_strategy_t {
1,
H5F_fspace_strategy_t
Definition: H5Fpublic.h:200
@ H5F_FSPACE_STRATEGY_NTYPES
Definition: H5Fpublic.h:207
@ H5F_FSPACE_STRATEGY_NONE
Definition: H5Fpublic.h:206
@ H5F_FSPACE_STRATEGY_FSM_AGGR
Definition: H5Fpublic.h:201
@ H5F_FSPACE_STRATEGY_PAGE
Definition: H5Fpublic.h:203
@ H5F_FSPACE_STRATEGY_AGGR
Definition: H5Fpublic.h:205

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.

Since
1.10.1

◆ H5Pset_istore_k()

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.

Parameters
[in]plist_idFile creation property list identifier
[in]ik1/2 rank of chunked storage B-tree
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

Version
1.6.4 ik parameter type changed to unsigned.
Since
1.0.0

◆ H5Pset_shared_mesg_index()

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.

Parameters
[in]plist_idFile creation property list identifier
[in]index_numIndex being configured
[in]mesg_type_flagsTypes of messages that should be stored in this index
[in]min_mesg_sizeMinimum message size
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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)
Since
1.8.0

◆ H5Pset_shared_mesg_nindexes()

herr_t H5Pset_shared_mesg_nindexes ( hid_t  plist_id,
unsigned  nindexes 
)

Sets number of shared object header message indexes.

Parameters
[in]plist_idFile creation property list identifier
[in]nindexesNumber of shared object header message indexes to be available in files created with this property list (nindexes must be <= H5O_SHMESG_MAX_NINDEXES (8))
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

Since
1.8.0

◆ H5Pset_shared_mesg_phase_change()

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.

Parameters
[in]plist_idFile creation property list identifier
[in]max_listThreshold above which storage of a shared object header message index shifts from list to B-tree
[in]min_btreeThreshold below which storage of a shared object header message index reverts to list format
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

Since
1.8.0

◆ H5Pset_sizes()

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.

Parameters
[in]plist_idFile creation property list identifier
[in]sizeof_addrSize of an object offset in bytes
[in]sizeof_sizeSize of an object length in bytes
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

Since
1.0.0

◆ H5Pset_sym_k()

herr_t H5Pset_sym_k ( hid_t  plist_id,
unsigned  ik,
unsigned  lk 
)
Parameters
[in]plist_idFile creation property list identifier
[in]ikSymbol table tree rank
[in]lkSymbol table node size
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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.

Version
1.6.4 ik parameter type changed to unsigned.
1.6.0 The ik parameter has changed from type int to unsigned.
Since
1.0.0

◆ H5Pset_userblock()

herr_t H5Pset_userblock ( hid_t  plist_id,
hsize_t  size 
)

Sets user block size.

Parameters
[in]plist_idFile creation property list identifier
[in]sizeSize of the user-block in bytes
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

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

Since
1.0.0