HDF5 Reference Manual  H5   H5A   H5D   H5E   H5F   H5G   H5P   H5S   H5T   H5Z   Glossary

H5P: Property List Interface

Property List API Functions

These functions manipulate property list objects to allow objects which require many different parameters to be easily manipulated.
General Property List Operations

File Creation Properties

       File Access Properties        Dataset Creation Properties

Dataset Memory and Transfer Properties


||   Available only in the parallel HDF5 library.
Name: H5Pcreate
Signature:
hid_t H5Pcreate(H5P_class_t type )
Purpose:
Creates a new property as an instance of a property list class.
Description:
H5Pcreate creates a new property as an instance of some property list class. The new property list is initialized with default values for the specified class. The classes are:
H5P_FILE_CREATE
Properties for file creation. See Files in the HDF User's Guide for details about the file creation properties.
H5P_FILE_ACCESS
Properties for file access. See Files in the HDF User's Guide for details about the file creation properties.
H5P_DATASET_CREATE
Properties for dataset creation. See Datasets in the HDF User's Guide for details about dataset creation properties.
H5P_DATASET_XFER
Properties for raw data transfer. See Datasets in the HDF User's Guide for details about raw data transfer properties.
Parameters:
H5P_class_t type
IN: The type of property list to create.
Returns:
Returns a property list identifier (plist) if successful; otherwise Fail (-1).

Name: H5Pclose
Signature:
herr_t H5Pclose(hid_t plist )
Purpose:
Terminates access to a property list.
Description:
H5Pclose terminates access to a property list. All property lists should be closed when the application is finished accessing them. This frees resources used by the property list.
Parameters:
hid_t plist
IN: Identifier of the property list to terminate access to.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_class
Signature:
H5P_class_t H5Pget_class(hid_t plist )
Purpose:
Returns the property list class for a property list.
Description:
H5Pget_class returns the property list class for the property list identied by the plist parameter. Valid property list classes are defined in the description of H5Pcreate().
Parameters:
hid_t plist
IN: Identifier of property list to query.
Returns:
Returns a property list class if successful. Otherwise returns H5P_NO_CLASS (-1).

Name: H5Pcopy
Signature:
hid_t H5Pcopy(hid_t plist )
Purpose:
Copies an existing property list to create a new property list.
Description:
H5Pcopy copies an existing property list to create a new property list. The new property list has the same properties and values as the original property list.
Parameters:
hid_t plist
IN: Identifier of property list to duplicate.
Returns:
Returns a property list identifier if successful; otherwise FAIL (-1).

Name: H5Pget_version
Signature:
herr_t H5Pget_version(hid_t plist, int * boot, int * freelist, int * stab, int * shhdr )
Purpose:
Retrieves the version information of various objects for a file creation property list.
Description:
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.
Parameters:
hid_t plist
IN: Identifier of the file creation property list.
int * boot
OUT: Pointer to location to return boot block version number.
int * freelist
OUT: Pointer to location to return global freelist version number.
int * stab
OUT: Pointer to location to return symbol table version number.
int * shhdr
OUT: Pointer to location to return shared object header version number.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pset_userblock
Signature:
herr_t H5Pset_userblock(hid_t plist, hsize_t size )
Purpose:
Sets user block size.
Description:
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.).
Parameters:
hid_t plist
IN: Identifier of property list to modify.
hsize_t size
IN: Size of the user-block in bytes.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_userblock
Signature:
herr_t H5Pget_userblock(hid_t plist, hsize_t * size )
Purpose:
Retrieves the size of a user block.
Description:
H5Pget_userblock retrieves the size of a user block in a file creation property list.
Parameters:
hid_t plist
IN: Identifier for property list to query.
hsize_t * size
OUT: Pointer to location to return user-block size.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pset_sizes
Signature:
herr_t H5Pset_sizes(hid_t plist, size_t sizeof_addr, size_t sizeof_size )
Purpose:
Sets the byte size of the offsets and lengths used to address objects in an HDF5 file.
Description:
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 sizeof parameters retains the current value. The default value for both values is 4 bytes. Valid values currenly are 2, 4, 8 and 16.
Parameters:
hid_t plist
IN: Identifier of property list to modify.
size_t sizeof_addr
IN: Size of an object offset in bytes.
size_t sizeof_size
IN: Size of an object length in bytes.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_sizes
Signature:
herr_t H5Pget_sizes(hid_t plist, size_t * sizeof_addr, size_t * sizeof_size )
Purpose:
Retrieves the size of the offsets and lengths used in an HDF5 file.
Description:
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.
Parameters:
hid_t plist
IN: Identifier of property list to query.
size_t * size
OUT: Pointer to location to return offset size in bytes.
size_t * size
OUT: Pointer to location to return length size in bytes.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pset_mpi
Signature:
herr_t H5Pset_mpi(hid_t plist, MPI_Comm comm, MPI_Info info )
Purpose:
Retrieves the access mode for parallel I/O and the user supplied communicator and info object.
Description:
H5Pset_mpi stores the access mode for MPIO call and the user supplied communicator and info in the access property list, which can then be used to open file. This function is available only in the parallel HDF5 library and is not a collective function.
Parameters:
hid_t plist
IN: Identifier of property list to modify
MPI_Comm comm
IN: MPI communicator to be used for file open as defined in MPI_FILE_OPEN of MPI-2. This function does not make a duplicated comm. Any modification to comm after this function call returns may have undetermined effect to the access property list. Users should call this function again to setup the property list.
MPI_Info info
IN: MPI info object to be used for file open as defined in MPI_FILE_OPEN of MPI-2. This function does not make a duplicated info. Any modification to info after this function call returns may have undetermined effect to the access property list. Users should call this function again to setup the property list.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_mpi
Signature:
herr_t H5Pget_mpi(hid_t plist, MPI_Comm *comm, MPI_Info *info )
Purpose:
Retrieves the communicator and info object.
Description:
H5Pget_mpi retrieves the communicator and info object that have been set by H5Pset_mpi. This function is available only in the parallel HDF5 library and is not a collective function.
Parameters:
hid_t plist
IN: Identifier of a file access property list that has been set successfully by H5Pset_mpi.
MPI_Comm * comm
OUT: Pointer to location to return the communicator.
MPI_Info * info
OUT: Pointer to location to return the info object.
Returns:
Returns SUCCEED (0) if the file access property list is set to the MPI. Otherwise returns FAIL (-1).

Name: H5Pset_xfer
Signature:
herr_t H5Pset_xfer(hid_t plist, H5D_transfer_t data_xfer_mode )
Purpose:
Sets the transfer mode of the dataset transfer property list.
Description:
H5Pset_xfer sets the transfer mode of the dataset transfer property list. The list can then be used to control the I/O transfer mode during dataset accesses. This function is available only in the parallel HDF5 library and is not a collective function.

Valid data transfer modes are:

Parameters:
hid_t plist
IN: Identifier of a dataset transfer property list
H5D_transfer_t data_xfer_mode
IN: Data transfer mode.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_xfer
Signature:
herr_t H5Pget_xfer(hid_t plist, H5D_transfer_t * data_xfer_mode )
Purpose:
Retrieves the transfer mode from the dataset transfer property list.
Description:
H5Pget_xfer retrieves the transfer mode from the dataset transfer property list. This function is available only in the parallel HDF5 library and is not a collective function.
Parameters:
hid_t plist
IN: Identifier of a dataset transfer property list.
H5D_transfer_t * data_xfer_mode
OUT: Pointer to location to return the data transfer mode.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pset_sym_k
Signature:
herr_t H5Pset_sym_k(hid_t plist, int ik, int lk )
Purpose:
Sets the size of parameters used to control the symbol table nodes.
Description:
H5Pset_sym_k sets the size of parameters used to control the symbol table nodes. 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.

ik is one half the rank of a 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.

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.

Parameters:
hid_t plist
IN: Identifier for property list to query.
int ik
IN: Symbol table tree rank.
int lk
IN: Symbol table node size.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_sym_k
Signature:
herr_t H5Pget_sym_k(hid_t plist, int * ik, int * lk )
Purpose:
Retrieves the size of the symbol table B-tree 1/2 rank and the symbol table leaf node 1/2 size.
Description:
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 only valid for file creationproperty lists. If a parameter valued is set to NULL, that parameter is not retrieved. See the description for H5Pset_sym_k for more information.
Parameters:
hid_t plist
IN: Property list to query.
int * ik
OUT: Pointer to location to return the symbol table's B-tree 1/2 rank.
int * size
OUT: Pointer to location to return the symbol table's leaf node 1/2 size.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pset_istore_k
Signature:
herr_t H5Pset_istore_k(hid_t plist, int ik )
Purpose:
Sets the size of the parameter used to control the B-trees for indexing chunked datasets.
Description:
H5Pset_istore_k sets the size of the parameter used to control the B-trees for indexing chunked datasets. 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.

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.

Parameters:
hid_t plist
IN: Identifier of property list to query.
int ik
IN: 1/2 rank of chunked storage B-tree.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_istore_k
Signature:
herr_t H5Pget_istore_k(hid_t plist, int * ik )
Purpose:
Queries the 1/2 rank of an indexed storage B-tree.
Description:
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 only valid for file creation property lists.

See H5Pset_istore_k for details.

Parameters:
hid_t plist
IN: Identifier of property list to query.
int * ik
OUT: Pointer to location to return the chunked storage B-tree 1/2 rank.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pset_layout
Signature:
herr_t H5Pset_layout(hid_t plist, H5D_layout_t layout )
Purpose:
Sets the type of storage used store the raw data for a dataset.
Description:
H5Pset_layout sets the type of storage used store the raw data for a dataset. This function is only valid for dataset creation property lists. Valid parameters for layout are:
Parameters:
hid_t plist
IN: Identifier of property list to query.
H5D_layout_t layout
IN: Type of storage layout for raw data.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_layout
Signature:
H5D_layout_t H5Pget_layout(hid_t plist)
Purpose:
Returns the layout of the raw data for a dataset.
Description:
H5Pget_layout returns the layout of the raw data for a dataset. This function is only valid for dataset creation property lists. Valid types for layout are:
Parameters:
hid_t plist
IN: Identifier for property list to query.
Returns:
Returns the layout type of a a dataset creation property list if successful. Otherwise returns H5D_LAYOUT_ERROR (-1).

Name: H5Pset_chunk
Signature:
herr_t H5Pset_chunk(hid_t plist, int ndims, const hsize_t * dim )
Purpose:
Sets the size of the chunks used to store a chunked layout dataset.
Description:
H5Pset_chunk sets the size of the chunks used to store a chunked layout dataset. This function is only valid for dataset creation property lists. The ndims parameter currently must be the same size as the rank of the dataset. The values of the dim array define the size of the chunks to store the dataset's raw data. As a side-effect, the layout of the dataset is changed to H5D_CHUNKED, if it isn't already.
Parameters:
hid_t plist
IN: Identifier for property list to query.
int ndims
IN: The number of dimensions of each chunk.
const hsize_t * dim
IN: An array containing the size of each chunk.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_chunk
Signature:
int H5Pget_chunk(hid_t plist, int max_ndims, hsize_t * dims )
Purpose:
Retrieves the size of chunks for the raw data of a chunked layout dataset.
Description:
H5Pget_chunk retrieves the size of chunks for the raw data of a chunked layout dataset. This function is only valid for dataset creation property lists. At most, max_ndims elements of dims will be initialized.
Parameters:
hid_t plist
IN: Identifier of property list to query.
int max_ndims
OUT: Size of the dims array.
hsize_t * dims
OUT: Array to store the chunk dimensions.
Returns:
Returns chunk dimensionality successful; otherwise FAIL (-1).

Name: H5Pset_alignment
Signature:
herr_t H5Pset_alignment(hid_t plist, hsize_t threshold, hsize_t alignment )
Purpose:
Sets alignment properties of a file access property list.
Description:
H5Pset_alignment sets the alignment properties of a file access property list so that any file object >= THRESHOLD bytes will be aligned on an address which is a multiple of ALIGNMENT. The addresses are relative to the end of the user block; the alignment is calculated by subtracting the user block size from the absolute file address and then adjusting the address to be a multiple of ALIGNMENT.

Default values for THRESHOLD and ALIGNMENT are one, implying no alignment. Generally the default values will result in the best performance for single-process access to the file. For MPI-IO and other parallel systems, choose an alignment which is a multiple of the disk block size.

Parameters:
hid_t plist
IN: Identifier for a file access property list.
hsize_t threshold
IN: Threshhold value.
hsize_t alignment
IN: Alignment value.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_alignment
Signature:
herr_t H5Pget_alignment(hid_t plist, hsize_t *threshold, hsize_t *alignment )
Purpose:
Retrieves the current settings for alignment properties from a file access property list.
Description:
H5Pget_alignment retrieves the current settings for alignment properties from a file access property list. The threshold and/or alignment pointers may be null pointers (NULL).
Parameters:
hid_t plist
IN: Identifier of a file access property list.
hsize_t *threshold
OUT: Pointer to location of return threshhold value.
hsize_t *alignment
OUT: Pointer to location of return alignment value.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pset_external
Signature:
herr_t H5Pset_external(hid_t plist, const char *name, off_t offset, hsize_t size )
Purpose:
Adds an external file to the list of external files.
Description:
H5Pset_external adds an external file to the list of external files.

If a dataset is split across multiple files then the files should be defined in order. The total size of the dataset is the sum of the SIZE arguments for all the external files. If the total size is larger than the size of a dataset then the dataset can be extended (provided the data space also allows the extending).

Parameters:
hid_t plist
IN: Identifier of a dataset creation property list.
const char *name
IN: Name of an external file.
off_t offset
IN: Offset, in bytes, from the beginning of the file to the location in the file where the data starts.
hsize_t size
IN: Number of bytes reserved in the file for the data.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_external_count
Signature:
int H5Pget_external_count(hid_t plist, )
Purpose:
Returns the number of external files for a dataset.
Description:
H5Pget_external_count returns the number of external files for the specified dataset.
Parameters:
hid_t plist
IN: Identifier of a dataset creation property list.
Returns:
Returns the number of external files if successful; otherwise FAIL (-1).

Name: H5Pget_external
Signature:
herr_t H5Pget_external(hid_t plist, int idx, size_t name_size, char *name, off_t *offset, hsize_t *size )
Purpose:
Returns information about an external file.
Description:
H5Pget_external returns information about an external file. The external file is specified by its index, idx, which is a number from zero to N-1, where N is the value returned by H5Pget_external_count(). At most name_size characters are copied into the name array. If the external file name is longer than name_size with the null terminator, the return value is not null terminated (similar to strncpy()).

If name_size is zero or name is the null pointer, the external file name is not returned. If offset or size are null pointers then the corresponding information is not returned.

Parameters:
hid_t plist
IN: Identifier of a dataset creation property list.
int idx
IN: External file index.
size_t name_size
IN: Maximum length of name array.
char *name
OUT: Name of the external file.
off_t *offset
OUT: Pointer to a location to return an offset value.
hsize_t *size
OUT: Pointer to a location to return the size of the external file data.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_driver
Signature:
H5F_driver_t H5Pget_driver(hid_t plist, )
Purpose:
Returns a low-level file driver identifier.
Description:
H5Pget_driver returns the identifier of the low-level file driver. Valid identifiers are:
Parameters:
hid_t plist
IN: Identifier of a file access property list.
Returns:
Returns a low-level driver identifier if successful. Otherwise returns H5F_LOW_ERROR (-1).

Name: H5Pset_stdio
Signature:
herr_t H5Pset_stdio(hid_t plist)
Purpose:
Sets the low level file driver to use the functions declared in the stdio.h.
Description:
H5Pset_stdio sets the low level file driver to use the functions declared in the stdio.h file: fopen(), fseek() or fseek64(), fread(), fwrite(), and fclose().
Parameters:
hid_t plist
IN: Identifier of a file access property list.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_stdio
Signature:
herr_t H5Pget_stdio(hid_t plist)
Purpose:
Determines whether the file access property list is set to the stdio driver.
Description:
H5Pget_stdio checks to determine whether the file access property list is set to the stdio driver. In the future, additional arguments may be added to this function to match those added to H5Pset_stdio().
Parameters:
hid_t plist
IN: Identifier of a file access property list.
Returns:
Returns SUCCEED (0) if the file access propety list is set to the stdio driver. Otherwise returns FAIL (-1).

Name: H5Pset_sec2
Signature:
herr_t H5Pset_sec2(hid_t plist, )
Purpose:
Sets the low-level file driver to use the declared functions.
Description:
H5Pset_sec2 sets the low-level file driver to use the functions declared in the unistd.h file: open(), lseek() or lseek64(), read(), write(), and close().
Parameters:
hid_t plist
IN: Identifier of a file access property list.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_sec2
Signature:
returntype H5Pget_sec2(hid_t plist)
Purpose:
Checks whether the file access propety list is set to the sec2 driver.
Description:
H5Pget_sec2 checks to determine whether the file access property list is set to the sec2 driver. In the future, additional arguments may be added to this function to match those added to H5Pset_sec2().
Parameters:
hid_t plist
IN: Identifier of a file access property list.
Returns:
Returns SUCCEED (0) if the file access propety list is set to the sec2 driver. Otherwise returns FAIL (-1).

Name: H5Pset_core
Signature:
herr_t H5Pset_core(hid_t plist, size_t increment )
Purpose:
Sets the low-level file driver to use malloc() and free().
Description:
H5Pset_core sets the low-level file driver to use malloc() and free(). This driver is restricted to temporary files which are not larger than the amount of virtual memory available. The INCREMENT argument determines the file block size and memory will be allocated in multiples of INCREMENT bytes. A liberal INCREMENT results in fewer calls to realloc() and probably less memory fragmentation.
Parameters:
hid_t plist
IN: Identifier of a file access property list.
size_t increment
IN: File block size in bytes.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name:
Signature:
herr_t H5Pget_core(hid_t plist, size_t *increment )
Purpose:
Determines whether the file access property list is set to the core driver.
Description:
H5Pget_core checks to determine whether the file access property list is set to the core driver. On success, the block size is returned through the INCREMENT argument if it isn't the null pointer. In the future, additional arguments may be added to this function to match those added to H5Pset_core().
Parameters:
hid_t plist
IN: Identifier of the file access property list.
size_t *increment
OUT: Pointer to a location to return the file block size (in bytes).
Returns:
Returns SUCCEED (0) if the file access propety list is set to the core driver. Otherwise returns FAIL (-1).

Name: H5Pset_split
Signature:
herr_t H5Pset_split(hid_t plist, const char *meta_ext, hid_t meta_plist, const char *raw_ext, hid_t raw_plist )
Purpose:
Sets the low-level driver to split meta data from raw data.
Description:
H5Pset_split sets the low-level driver to split meta data from raw data, storing meta data in one file and raw data in another file. The meta file will have a name which is formed by adding meta_extension (recommended default value: .meta) to the end of the base name and will be accessed according to the meta_properties. The raw file will have a name which is formed by appending raw_extension (recommended default value: .raw) to the base name and will be accessed according to the raw_properties. Additional parameters may be added to this function in the future.
Parameters:
hid_t plist
IN: Identifier of the file access property list.
const char *meta_ext
IN: Name of the extension for the metafile filename. Recommended default value: .meta.
hid_t meta_plist
IN: Identifier of the meta file access property list.
const char *raw_ext
IN: Name extension for the raw file filename. Recommended default value: .raw.
hid_t raw_plist
IN: Identifier of the raw file access property list.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_split
Signature:
herr_t H5Pget_split(hid_t plist, size_t meta_ext_size, char *meta_ext, hid_t *meta_properties, size_t raw_ext_size, char *raw_ext, hid_t *raw_properties )
Purpose:
Determines whether the file access property list is set to the split driver.
Description:
H5Pget_split checks to determine whether the file access property list is set to the split driver. On successful return, meta_properties and raw_properties will point to copies of the meta and raw access property lists which should be closed by calling H5Pclose() when the application is finished with them, but if the meta and/or raw file has no property list then a negative value is returned for that property list identifier. Also, if meta_extension and/or raw_extension are non-null pointers, at most meta_ext_size or raw_ext_size characters of the meta or raw file name extension will be copied to the specified buffer. If the actual name is longer than what was requested then the result will not be null terminated (similar to strncpy()). In the future, additional arguments may be added to this function to match those added to H5Pset_split().
Parameters:
hid_t plist
IN: Identifier of the file access property list.
size_t meta_ext_size
IN: Number of characters of the meta file extension to be copied to the meta_ext buffer.
OUT *meta_ext
IN: Meta file extension.
hid_t *meta_properties
OUT: Pointer to a copy of the meta file access property list.
size_t raw_ext_size
IN: Number of characters of the raw file extension to be copied to the raw_ext buffer.
char *raw_ext
OUT: Raw file extension.
hid_t *raw_properties
OUT: Pointer to a copy of the raw file access property list.
Returns:
Returns SUCCEED (0) if the file access propety list is set to the split driver. Otherwise returns FAIL (-1).

Name: H5Pset_family
Signature:
herr_t H5Pset_family(hid_t plist, hsize_t memb_size, hid_t memb_plist )
Purpose:
Sets the file access properties list to the family driver.
Description:
H5Pset_family sets the file access properties to use the family driver; any previously defined driver properties are erased from the property list. Each member of the file family will use member_properties as its file access property list. The memb_size argument gives the logical size in bytes of each family member but the actual size could be smaller depending on whether the file contains holes. The member size is only used when creating a new file or truncating an existing file; otherwise the member size comes from the size of the first member of the family being opened. Note: if the size of the off_t type is four bytes then the maximum family member size is usually 2^31-1 because the byte at offset 2,147,483,647 is generally inaccessable. Additional parameters may be added to this function in the future.
Parameters:
hid_t plist
IN: Identifier of the file access property list.
hsize_t memb_size
IN: Logical size, in bytes, of each family member.
hid_t memb_plist
IN: Identifier of the file access property list for each member of the family.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_family
Signature:
herr_t H5Pget_family(hid_t tid, hsize_t *memb_size, hid_t *memb_plist )
Purpose:
Determines whether the file access property list is set to the family driver.
Description:
H5Pget_family checks to determine whether the file access property list is set to the family driver. On successful return, access_properties will point to a copy of the member access property list which should be closed by calling H5Pclose() when the application is finished with it. If memb_size is non-null then it will contain the logical size in bytes of each family member. In the future, additional arguments may be added to this function to match those added to H5Pset_family().
Parameters:
hid_t plist
IN: Identifier of the file access property list.
hsize_t *memb_size
OUT: Logical size, in bytes, of each family member.
hid_t *memb_plist
OUT: Identifier of the file access property list for each member of the family.
Returns:
Returns SUCCEED (0) if the file access propety list is set to the family driver. Otherwise returns FAIL (-1).

Name: H5Pset_cache
Signature:
herr_t H5Pset_cache(hid_t plist, int mdc_nelmts, size_t rdcc_nbytes, double rdcc_w0 )
Purpose:
Sets the number of elements in the meta data cache and the total number of bytes in the raw data chunk cache.
Description:
H5Pset_cache sets the number of elements (objects) in the meta data cache and the total number of bytes in the raw data chunk cache.

Sets or queries the meta data cache and raw data chunk cache parameters. The plist is a file access property list. The number of elements (objects) in the meta data cache is mdc_nelmts. The total size of the raw data chunk cache and the preemption policy is rdcc_nbytes and w0. For H5Pget_cache() any (or all) of the pointer arguments may be null pointers.

The RDCC_W0 value should be between 0 and 1 inclusive and indicates how much chunks that have been fully read are favored for preemption. A value of zero means fully read chunks are treated no differently than other chunks (the preemption is strictly LRU) while a value of one means fully read chunks are always preempted before other chunks.

Parameters:
hid_t plist
IN: Identifier of the file access property list.
int mdc_nelmts
IN: Number of elements (objects) in the meta data cache.
size_t rdcc_nbytes
IN: Total size of the raw data chunk cache, in bytes.
double rdcc_w0
IN: Preemption policy.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_cache
Signature:
herr_t H5Pget_cache(hid_t plist, int *mdc_nelmts, size_t *rdcc_nbytes, double *rdcc_w0 )
Purpose:
Retrieves maximun sizes of meta data cache and RDCC_WO.
Description:
Retrieves the maximum possible number of elements in the meta data cache and the maximum possible number of bytes and the RDCC_W0 value in the raw data chunk cache. Any (or all) arguments may be null pointers in which case the corresponding datum is not returned.
Parameters:
hid_t plist
IN: Identifier of the file access property list.
int *mdc_nelmts
IN/OUT: Number of elements (objects) in the meta data cache.
size_t *rdcc_nbytes
IN/OUT: Total size of the raw data chunk cache, in bytes.
double *rdcc_w0
IN/OUT: Preemption policy.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pset_buffer
Signature:
herr_t H5Pset_buffer(hid_t plist, size_t size, void *tconv, void *bkg )
Purpose:
Sets type conversion and background buffers.
Description:
Given a dataset transfer property list, H5Pset_buffer sets the maximum size for the type conversion buffer and background buffer and optionally supply pointers to application-allocated buffers. If the buffer size is smaller than the entire amount of data being transfered between application and file, and a type conversion buffer or background buffer is required then strip mining will be used. However, certain restrictions apply for the size of buffer which can be used for strip mining. For instance, when strip mining a 100x200x300 hyperslab of a simple data space the buffer must be large enough to hold a 1x200x300 slab.

If TCONV and/or BKG are null pointers then buffers will be allocated and freed during the data transfer.

The default value for the maximum buffer is 1 Mb.

Parameters:
hid_t plist
IN: Identifier for the dataset transfer property list.
size_t size
IN: Size for the type conversion and background buffers.
void tconv
IN: Pointer to application-allocated type conversion buffer.
void bkg
IN: Pointer to application-allocated background buffer.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_buffer
Signature:
size_t H5Pget_buffer(hid_t plist, void **tconv, void **bkg )
Purpose:
Reads buffer settings.
Description:
H5Pget_buffer reads values previously set with H5Pset_buffer().
Parameters:
hid_t plist
IN: Identifier for the dataset transfer property list.
void **tconv
OUT: Address of the pointer to application-allocated type conversion buffer.
void **bkg
OUT: Address of the pointer to application-allocated background buffer.
Returns:
Returns buffer size if successful; otherwise 0 on failure.

Name: H5Pset_preserve
Signature:
herr_t H5Pset_preserve(hid_t plist, hbool_t status )
Purpose:
Sets the dataset transfer property list status to TRUE or FALSE.
Description:
H5Pset_preserve sets the dataset transfer property list status to TRUE or FALSE.

When reading or writing compound data types and the destination is partially initialized and the read/write is intended to initialize the other members, one must set this property to TRUE. Otherwise the I/O pipeline treats the destination datapoints as completely uninitialized.

Parameters:
hid_t plist
IN: Identifier for the dataset transfer property list.
hbool_t status
IN: Status of for the dataset transfer property list (TRUE/FALSE).
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_preserve
Signature:
int H5Pget_preserve(hid_t plist)
Purpose:
Checks status of the dataset transfer property list.
Description:
H5Pget_preserve checks the status of the dataset transfer property list.
Parameters:
hid_t plist
IN: Identifier for the dataset transfer property list.
Returns:
Returns TRUE or FALSE if successful; otherwise FAIL (-1).

Name: H5Pset_compression
Signature:
herr_t H5Pset_compression(hid_t plist, H5Z_method_t method, unsigned int flags, size_t cd_size, const void *client_data )
Purpose:
Sets compression method.
Description:
H5Pset_compression sets the compression method in a dataset creation property list. This is a catch-all function for defining compresion methods and is intended to be called from a wrapper such as H5Pset_deflate(). The dataset creation property list plist is adjusted to use the specified compression method. The flags is an 8-bit vector which is stored in the file as part of the compression message and passed to the compress and uncompress functions. The client_data is a byte array of length cd_size which is copied to the file and passed to the compress and uncompress methods.

The FLAGS, CD_SIZE, and CLIENT_DATA are copied to the property list and eventually to the file and passed to the compression functions.

See Compression in the HDF5 User's Guide for further information.

Parameters:
hid_t plist
IN: Identifier for the dataset creation property list.
H5Z_method_t method
IN: Compression method, an integer from 16 to 225.
unsigned int flags
IN: Compression flags.
size_t cd_size
IN: Size of the byte array client_data.
const void *client_data
IN: Client data byte array passed to the compression method.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_compression
Signature:
H5Z_method_t H5Pget_compression(hid_t plist, unsigned int *flags, size_t *cd_size, void *client_data )
Purpose:
Gets compression method.
Description:
H5Pget_compression gets the compression method information from a dataset creation property list. The CLIENT_DATA buffer is initially CD_SIZE bytes. On return, CLIENT_DATA will be initialized with at most that many bytes, and CD_SIZE will contain the actual size of the client data, which might be larger than its original value.
Parameters:
hid_t plist
IN: Identifier for the dataset creation property list.
unsigned int *flags
OUT: Compression flags.
size_t *cd_size
IN/OUT: Size of the client_data array.
void *client_data
OUT: Byte array for the client data.
Returns:
Returns compression method if successful; otherwise FAIL (-1).

Name: H5Pset_deflate
Signature:
herr_t H5Pset_deflate(hid_t plist, int level )
Purpose:
Sets compression method and compression level.
Description:
H5Pset_deflate sets the compression method for a dataset creation property list to H5D_COMPRESS_DEFLATE and the compression level to LEVEL which should be a value between zero and nine, inclusive. Lower compression levels are faster but result in less compression. This is the same algorithm as used by the GNU gzip program.
Parameters:
hid_t plist
IN: Identifier for the dataset creation property list.
int level
IN: Compression level.
Returns:
Returns SUCCEED (0) if successful; otherwise FAIL (-1).

Name: H5Pget_deflate
Signature:
int H5Pget_deflate(hid_t plist )
Purpose:
Returns the deflate compression level from a dataset creation property list.
Description:
H5Pget_deflate returns the deflate compression level from a dataset creation property list that uses that method.
Parameters:
hid_t plist
IN: Identifier for the dataset creation property list.
Returns:
Returns compression level, a value between 0 and 9, if successful. Otherwise returns FAIL (-1).

HDF5 Reference Manual  H5   H5A   H5D   H5E   H5F   H5G   H5P   H5S   H5T   H5Z   Glossary

HDF Help Desk
Last modified: 14 July 1998