Introduction to HDF5 
HDF5 User Guide 
Other HDF5 documents and links 
 And in this document, the HDF5 Reference Manual  
H5   H5A   H5D   H5E   H5F   H5G   H5I   H5P  
H5R   H5S   H5T   H5Z   Tools   Datatypes  

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.

The C Interfaces:
General Property List
Operations

File Creation Properties


 
 
 
 
 
 
||  Indicates functions
    available only in the
    parallel HDF5 library. 		       File Access Properties        Dataset Creation Properties

Dataset Access, Memory, and
Transfer Properties

The FORTRAN90 Interfaces:
In general, each FORTRAN90 subroutine performs exactly the same task as the corresponding C function. The links below go to the C function descriptions, which serve as general descriptions for both. A button, under Non-C API(s) at the end of the C function description, opens an external browser window displaying the FORTRAN90-specific information. You will probably want to adjust the size and location of this external window so that both browser windows are visible and to facilitate moving easily between them.
General Property List Operations

File Creation Properties

       Dataset Creation Properties
 
 
 
||  Available only in the parallel HDF5 library. 		       File Access Properties

Dataset Memory and Transfer Properties

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.
H5P_MOUNT
Properties for file mounting. With this parameter, H5Pcreate creates and returns a new mount property list initialized with default values.

This property list must eventually be closed with H5Pclose; otherwise, errors are likely to occur.

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).
Non-C API(s):
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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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 identified 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).
Non-C API(s):
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 returns a negative value.
Non-C API(s):
Name: H5Pget_version
Signature:
herr_t H5Pget_version(hid_t plist, int * super, 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 * super
OUT: Pointer to location to return super 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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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 currently 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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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 creation property 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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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).
Non-C API(s):
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 is not 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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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
IN: Size of the dims array.
hsize_t * dims
OUT: Array to store the chunk dimensions.
Returns:
Returns chunk dimensionality successful; otherwise returns a negative value.
Non-C API(s):
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 greater than or equal in size to 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: Threshold value. Must be non-negative. Note that setting the threshold value to 0 (zero) has the effect of a special case, forcing everything to be aligned.
hsize_t alignment
IN: Alignment value. Must be a positive value.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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 threshold value.
hsize_t *alignment
OUT: Pointer to location of return alignment value.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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).

The size argument specifies number of bytes reserved for data in the external file. If size is set to H5F_UNLIMITED, the external file can be of unlimited size and no more files can be added to the external files list.

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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
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 returns a negative value.
Non-C API(s):
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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
Name: H5Pset_fill_value
Signature:
herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value )
Purpose:
Sets a dataset fill value.
Description:
H5Pset_fill_value sets the fill value for a dataset creation property list.

The value is interpreted as being of type type_id. This need not be the same type as the dataset, but the library must be able to convert value to the dataset type when the dataset is created.

Notes:
If a fill value is set for a dataset (even if the fill value is all zeros), the fill value will be written to the file. If no fill value is set, then HDF5 relies on the underlying file driver (usually a Unix file system) to initialize unwritten parts of the file to zeros.

Creating a contiguous dataset with a fill value can be a very expensive operation since the optimization has not yet been implemented that would delay the writing of the fill values until after some data has been written.

Parameters:
hid_t plist_id
IN: Property list identifier.
hid_t type_id,
IN: The datatype identifier of value.
const void *value
IN: The fill value.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
Name: H5Pget_fill_value
Signature:
herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id, void *value )
Purpose:
Retrieves a dataset fill value.
Description:
H5Pget_fill_value queries the fill value property of a dataset creation property list.

The fill value is returned through the value pointer.

Memory is allocated by the caller.

The fill value will be converted from its current data type to the type specified by type_id.

Parameters:
hid_t plist_id
IN: Property list identifier.
hid_t type_id,
IN: The datatype identifier of value.
const void *value
IN: The fill value.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
Name: H5Pset_filter
Signature:
herr_t H5Pset_filter(hid_t plist, H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[] )
Purpose:
Adds a filter to the filter pipeline.
Description:
H5Pset_filter adds the specified filter and corresponding properties to the end of an output filter pipeline. If plist is a dataset creation property list, the filter is added to the permanent filter pipeline; if plist is a dataset transfer property list, the filter is added to the transient filter pipeline.

The array cd_values contains cd_nelmts integers which are auxiliary data for the filter. The integer values will be stored in the dataset object header as part of the filter information.

The flags argument is a bit vector with the following fields specifying certain general properties of the filter:

H5Z_FLAG_OPTIONAL    If this bit is set then the filter is optional. If the filter fails (see below) during an H5Dwrite operation then the filter is just excluded from the pipeline for the chunk for which it failed; the filter will not participate in the pipeline during an H5Dread of the chunk. This is commonly used for compression filters: if the compression result would be larger than the input then the compression filter returns failure and the uncompressed data is stored in the file. If this bit is clear and a filter fails then H5Dwrite or H5Dread also fails.
Note:
This function currently supports only the permanent filter pipeline; plist_id must be a dataset creation property list.
Parameters:
hid_t plist
IN: Property list identifier.
H5Z_filter_t filter
IN: Filter to be added to the pipeline.
unsigned int flags
IN: Bit vector specifying certain general properties of the filter.
size_t cd_nelmts
IN: Number of elements in cd_values.
const unsigned int cd_values[]
IN: Auxiliary data for the filter.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
Name: H5Pget_nfilters
Signature:
int H5Pget_nfilters(hid_t plist)
Purpose:
Returns the number of filters in the pipeline.
Description:
H5Pget_nfilters returns the number of filters defined in the filter pipeline associated with the property list plist.

In each pipeline, the filters are numbered from 0 through N-1, where N is the value returned by this function. During output to the file, the filters are applied in increasing order; during input from the file, they are applied in decreasing order.

H5Pget_nfilters returns the number of filters in the pipeline, including zero (0) if there are none.

Note:
This function currently supports only the permanent filter pipeline; plist_id must be a dataset creation property list.
Parameters:
hid_t plist
IN: Property list identifier.
Returns:
Returns the number of filters in the pipeline if successful; otherwise returns a negative value.
Name: H5Pget_filter
Signature:
H5Z_filter_t H5Pget_filter(hid_t plist, int filter_number, unsigned int *flags, size_t *cd_nelmts, unsigned int *cd_values, size_t namelen, char name[] )
Purpose:
Returns information about a filter in a pipeline.
Description:
H5Pget_filter returns information about a filter, specified by its filter number, in a filter pipeline, specified by the property list with which it is associated.

If plist is a dataset creation property list, the pipeline is a permanent filter pipeline; if plist is a dataset transfer property list, the pipeline is a transient filter pipeline.

On input, cd_nelmts indicates the number of entries in the cd_values array, as allocated by the caller; on return,cd_nelmts contains the number of values defined by the filter.

filter_number is a value between zero and N-1, as described in H5Pget_nfilters. The function will return a negative value if the filter number is out of range.

If name is a pointer to an array of at least namelen bytes, the filter name will be copied into that array. The name will be null terminated if namelen is large enough. The filter name returned will be the name appearing in the file, the name registered for the filter, or an empty string.

The structure of the flags argument is discussed in H5Pset_filter.

Note:
This function currently supports only the permanent filter pipeline; plist must be a dataset creation property list.
Parameters:
hid_t plist
IN: Property list identifier.
int filter_number
IN: Sequence number within the filter pipeline of the filter for which information is sought.
unsigned int *flags
OUT: Bit vector specifying certain general properties of the filter.
size_t *cd_nelmts
IN/OUT: Number of elements in cd_values.
unsigned int *cd_values
OUT: Auxiliary data for the filter.
size_t namelen
IN: Anticipated number of characters in name.
char name[]
OUT: Name of the filter.
Returns:
Returns the filter identification number if successful. Otherwise returns H5Z_FILTER_ERROR (-1).
Non-C API(s):
Name: H5Pset_meta_block_size
Signature:
herr_t H5Pset_meta_block_size( hid_t fapl_id, hsize_t size )
Purpose:
Sets the minimum metadata block size.
Description:
H5Pset_meta_block_size sets the minimum size, in bytes, of metadata block allocations when H5FD_FEAT_AGGREGATE_METADATA is set by a VFL driver.

Each raw metadata block is initially allocated to be of the given size. Specific metadata objects (e.g., object headers, local heaps, B-trees) are then sub-allocated from this block.

The default setting is 2048 bytes, meaning that the library will attempt to aggregate metadata in at least 2K blocks in the file. Setting the value to 0 (zero) with this function will turn off metadata aggregation, even if the VFL driver attempts to use the metadata aggregation strategy.

Metadata aggregation reduces the number of small data objects in the file that would otherwise be required for metadata. The aggregated block of metadata is usually written in a single write action and always in a contiguous block, potentially significantly improving library and application performance.

Parameters:
hid_t fapl_id
IN: File access property list identifier.
hsize_t size
IN: Minimum size, in bytes, of metadata block allocations.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pget_meta_block_size
Signature:
herr_t H5Pget_meta_block_size( hid_t fapl_id, hsize_t *size )
Purpose:
Returns the current metadata block size setting.
Description:
H5Pget_meta_block_size returns the current minimum size, in bytes, of new metadata block allocations. This setting is retrieved from the file access property list fapl_id.

This value is set by H5Pset_meta_block_size and is retrieved from the file access property list fapl_id.

Parameters:
hid_t fapl_id
IN: File access property list identifier.
hsize_t *size
OUT: Minimum size, in bytes, of metadata block allocations.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pset_sieve_buf_size
Signature:
herr_t H5Pset_sieve_buf_size( hid_t fapl_id, hsize_t size )
Purpose:
Sets the maximum size of the data sieve buffer.
Description:
H5Pset_sieve_buf_size sets size, the maximum size in bytes of the data sieve buffer, which is used by file drivers that are capable of using data sieving.

The data sieve buffer is used when performing I/O on datasets in the file. Using a buffer which is large anough to hold several pieces of the dataset being read in for hyperslab selections boosts performance by quite a bit.

The default value is set to 64KB, indicating that file I/O for raw data reads and writes will occur in at least 64KB blocks. Setting the value to 0 with this API function will turn off the data sieving, even if the VFL driver attempts to use that strategy.

Parameters:
hid_t fapl_id
IN: File access property list identifier.
hsize_t size
IN: Maximum size, in bytes, of data sieve buffer.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pget_sieve_buf_size
Signature:
herr_t H5Pget_sieve_buf_size( hid_t fapl_id, hsize_t *size )

Purpose:
Returns maximum data sieve buffer size.
Description:
H5Pget_sieve_buf_size retrieves, size, the current maximum size of the data sieve buffer.

This value is set by H5Pset_sieve_buf_size and is retrieved from the file access property list fapl_id.

Parameters:
hid_t fapl_id
IN: File access property list identifier.
hsize_t *size
IN: Maximum size, in bytes, of data sieve buffer.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pset_gc_references
Signature:
herr_t H5Pset_gc_reference(hid_t plist, unsigned gc_ref )
Purpose:
Sets garbage collecting references flag.
Description:
H5Pset_gc_references sets the flag for garbage collecting references for the file.

Dataset region references and other reference types use space in an HDF5 file's global heap. If garbage collection is on and the user passes in an uninitialized value in a reference structure, the heap might get corrupted. When garbage collection is off, however, and the user re-uses a reference, the previous heap block will be orphaned and not returned to the free heap space.

When garbage collection is on, the user must initialize the reference structures to 0 or risk heap corruption.

The default value for garbage collecting references is off.

Parameters:
hid_t plist
IN: File access property list identifier.
unsigned gc_ref
IN: Flag setting reference garbage collection to on (1) or off (0).
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
Name: H5Pget_gc_references
Signature:
herr_t H5Pget_gc_references(hid_t plist, unsigned *gc_ref )
Purpose:
Returns garbage collecting references setting.
Description:
H5Pget_gc_references returns the current setting for the garbage collection references property from the specified file access property list. The garbage collection references property is set by H5Pset_gc_references.
Parameters:
hid_t plist
IN: File access property list identifier.
unsigned gc_ref
OUT: Flag returning the state of reference garbage collection. A returned value of 1 indicates that garbage collection is on while 0 indicates that garbage collection is off.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
Name: H5Pset_cache
Signature:
herr_t H5Pset_cache(hid_t plist_id, int mdc_nelmts, int rdcc_nelmts, size_t rdcc_nbytes, double rdcc_w0 )
Purpose:
Sets the meta data cache and raw data chunk cache parameters.
Description:
H5Pset_cache sets the number of elements (objects) in the meta data cache and the number of elements, the total number of bytes, and the preemption policy value in the raw data chunk cache.

The plist_id is a file access property list. The number of elements (objects) in the meta data cache and the raw data chunk cache are mdc_nelmts and rdcc_nelmts, respectively. The total size of the raw data chunk cache and the preemption policy are rdcc_nbytes and rdcc_w0.

Any (or all) of the H5Pget_cache 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_id
IN: Identifier of the file access property list.
int mdc_nelmts
IN: Number of elements (objects) in the meta data cache.
int rdcc_nelmts
IN: Number of elements (objects) in the raw data chunk cache.
size_t rdcc_nbytes
IN: Total size of the raw data chunk cache, in bytes.
double rdcc_w0
IN: Preemption policy.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
Name: H5Pget_cache
Signature:
herr_t H5Pget_cache(hid_t plist_id, int *mdc_nelmts, int *rdcc_nelmts, size_t *rdcc_nbytes, double *rdcc_w0 )
Purpose:
Queries the meta data cache and raw data chunk cache parameters.
Description:
H5Pget_cache retrieves the maximum possible number of elements in the meta data cache and raw data chunk cache, the maximum possible number of bytes in the raw data chunk cache, and the preemption policy value.

Any (or all) arguments may be null pointers, in which case the corresponding datum is not returned.

Parameters:
hid_t plist_id
IN: Identifier of the file access property list.
int *mdc_nelmts
IN/OUT: Number of elements (objects) in the meta data cache.
int *rdcc_nelmts
IN/OUT: Number of elements (objects) in the raw data chunk 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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
Name: H5Pset_hyper_cache
Signature:
herr_t H5Pset_hyper_cache(hid_t plist, unsigned cache, unsigned limit )
Purpose:
Indicates whether to cache hyperslab blocks during I/O.
Description:
Given a dataset transfer property list, H5Pset_hyper_cache indicates whether to cache hyperslab blocks during I/O, a process which can significantly increase I/O speeds.

When working with hyperslab selections, it is possible to significantly speed up I/O operations by retrieving an entire hyperslab from the file in one operation and caching it in memory. The cache parameter specifies whether to turn caching on for hyperslab I/O operations. If cache is set to 1, caching is turned on; if set to 0, caching is turned off.

The parameter limit sets the maximum size of the hyperslab block to cache. If a block is smaller than that limit, it may still not be cached if no memory is available. Setting limit to 0 (zero) indicates no limitation on the size of block to attempt to cache.

The default is to cache blocks with no limit on block size for serial I/O and to not cache blocks for parallel I/O.

Parameters:
hid_t plist
IN: Dataset transfer property list identifier.
unsigned cache
IN: A flag indicating whether caching is to be set to on (1) or off (0).
unsigned limit
IN: Maximum size of the hyperslab block to cache. 0 (zero) indicates no limit.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
Name: H5Pget_hyper_cache
Signature:
herr_t H5Pget_hyper_cache(hid_t plist, unsigned *cache, unsigned *limit )
Purpose:
Returns information regarding the caching of hyperslab blocks during I/O.
Description:
Given a dataset transfer property list, H5Pget_hyper_cache returns instructions regarding the caching of hyperslab blocks during I/O. These parameters are set with the H5Pset_hyper_cache function.
Parameters:
hid_t plist
IN: Dataset transfer property list identifier.
unsigned *cache
OUT: A flag indicating whether caching is set to on (1) or off (0).
unsigned *limit
OUT: Maximum size of the hyperslab block to cache. 0 (zero) indicates no limit.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
Name: H5Pset_btree_ratios
Signature:
herr_t H5Pset_btree_ratios(hid_t plist, double left, double middle, double right )
Purpose:
Sets B-tree split ratios for a dataset transfer property list.
Description:
H5Pset_btree_ratios sets the B-tree split ratios for a dataset transfer property list. The split ratios determine what percent of children go in the first node when a node splits.

The ratio left is used when the splitting node is the left-most node at its level in the tree; the ratio right is used when the splitting node is the right-most node at its level; and the ratio middle is used for all other cases.

A node which is the only node at its level in the tree uses the ratio right when it splits.

All ratios are real numbers between 0 and 1, inclusive.

Parameters:
hid_t plist
IN: The dataset transfer property list identifier.
double left
IN: The B-tree split ratio for left-most nodes.
double right
IN: The B-tree split ratio for right-most nodes and lone nodes.
double middle
IN: The B-tree split ratio for all other nodes.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
Name: H5Pget_btree_ratios
Signature:
herr_t H5Pget_btree_ratios(hid_t plist, double *left, double *middle, double *right )
Purpose:
Gets B-tree split ratios for a dataset transfer property list.
Description:
H5Pget_btree_ratios returns the B-tree split ratios for a dataset transfer property list.

The B-tree split ratios are returned through the non-NULL arguments left, middle, and right, as set by the H5Pset_btree_ratios function.

Parameters:
hid_t plist
IN: The dataset transfer property list identifier.
double left
OUT: The B-tree split ratio for left-most nodes.
double right
OUT: The B-tree split ratio for right-most nodes and lone nodes.
double middle
OUT: The B-tree split ratio for all other nodes.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
Name: H5Pset_buffer
Signature:
herr_t H5Pset_buffer(hid_t plist, hsize_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 supplies pointers to application-allocated buffers. If the buffer size is smaller than the entire amount of data being transferred between the application and the file, and a type conversion buffer or background buffer is required, then strip mining will be used.

Note that there are minimum size requirements for the buffer. Strip mining can only break the data up along the first dimension, so the buffer must be large enough to accommodate a complete slice that encompasses all of the remaining dimensions. For example, when strip mining a 100x200x300 hyperslab of a simple data space, the buffer must be large enough to hold 1x200x300 data elements. When strip mining a 100x200x300x150 hyperslab of a simple data space, the buffer must be large enough to hold 1x200x300x150 data elements.

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.
hsize_t size
IN: Size, in bytes, of 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 a non-negative value if successful; otherwise returns a negative value.
Name: H5Pget_buffer
Signature:
hsize_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, in bytes, 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 a non-negative value if successful; otherwise returns a negative value.
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 returns a negative value.
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 from zero to 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 a non-negative value if successful; otherwise returns a negative value.
Non-C API(s):
Name: H5Pset_vlen_mem_manager
Signature:
herr_t H5Pset_vlen_mem_manager(hid_t plist, H5MM_allocate_t alloc, void *alloc_info, H5MM_free_t free, void *free_info )
Purpose:
Sets the memory manager for variable-length datatype allocation in H5Dread and H5Dvlen_reclaim.
Description:
H5Pset_vlen_mem_manager sets the memory manager for variable-length datatype allocation in H5Dread and free in H5Dvlen_reclaim.

The alloc and free parameters identify the memory management routines to be used. If the user has defined custom memory management routines, alloc and/or free should be set to make those routine calls (i.e., the name of the routine is used as the value of the parameter); if the user prefers to use the system's malloc and/or free, the alloc and free parameters, respectively, should be set to NULL

The prototypes for these user-defined functions would appear as follows:
     typedef void *(*H5MM_allocate_t)(size_t size, void *alloc_info) ;
     typedef void (*H5MM_free_t)(void *mem, void *free_info) ;
The alloc_info and free_info parameters can be used to pass along any required information to the user's memory management routines.

In summary, if the user has defined custom memory management routines, the name(s) of the routines are passed in the alloc and free parameters and the custom routines' parameters are passed in the alloc_info and free_info parameters. If the user wishes to use the system malloc and free functions, the alloc and/or free parameters are set to NULL and the alloc_info and free_info parameters are ignored.

Parameters:
hid_t plist
IN: Identifier for the dataset transfer property list.
H5MM_allocate_t alloc
IN: User's allocate routine, or   NULL for system   malloc.
void *alloc_info
IN: Extra parameter for user's allocation routine.
Contents are ignored if preceding parameter is   NULL.
H5MM_free_t free
IN: User's free routine, or   NULL for system free.
void *free_info
IN: Extra parameter for user's free routine.
Contents are ignored if preceding parameter is   NULL.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Name: H5Pget_vlen_mem_manager
Signature:
herr_t H5Pget_vlen_mem_manager(hid_t plist, H5MM_allocate_t *alloc, void **alloc_info, H5MM_free_t *free, void **free_info )
Purpose:
Gets the memory manager for variable-length datatype allocation in H5Dread and H5Dvlen_reclaim.
Description:
H5Pget_vlen_mem_manager is the companion function to H5Pset_vlen_mem_manager, returning the parameters set by that function.
Parameters:
hid_t plist
IN: Identifier for the dataset transfer property list.
H5MM_allocate_t alloc
OUT: User's allocate routine, or   NULL for system   malloc.
void *alloc_info
OUT: Extra parameter for user's allocation routine.
Contents are ignored if preceding parameter is   NULL.
H5MM_free_t free
OUT: User's free routine, or   NULL for system free.
void *free_info
OUT: Extra parameter for user's free routine.
Contents are ignored if preceding parameter is   NULL.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Name: H5Pset_fapl_family
Signature:
herr_t H5Pset_fapl_family ( hid_t fapl_id, hsize_t memb_size, hid_t memb_fapl_id )
Purpose:
Sets the file access property list to use the family driver.
Description:
H5Pset_fapl_family sets the file access property list identifier, fapl_id, to use the family driver.

memb_size is the size in bytes of each file member and is used only when creating a new file.

memb_fapl_id is the identifier of the file access property list to be used for each family member.

Parameters:
hid_t fapl_id
IN: File access property list identifier.
hsize_t memb_size
IN: Size in bytes of each file member.
hid_t memb_fapl_id
IN: Identifier of file access property list for each family member.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pget_fapl_family
Signature:
herr_t H5Pget_fapl_family ( hid_t fapl_id, hsize_t *memb_size, hid_t *memb_fapl_id )
Purpose:
Returns file access property list information.
Description:
H5Pget_fapl_family returns file access property list for use with the family driver. This information is returned through the output parameters.
Parameters:
hid_t fapl_id
IN: File access property list identifier.
hsize_t *memb_size
OUT: Size in bytes of each file member.
hid_t *memb_fapl_id
OUT: Identifier of file access property list for each family member.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pset_fapl_log
Signature:
herr_t H5Pset_fapl_log( hid_t fapl_id, char *logfile, int verbosity )
Purpose:
Sets up the use of the logging driver.
Description:
H5Pset_fapl_log modifies the file access property list to use the logging driver H5FD_LOG. There are no driver-specific properties.

logfile is the name of the file in which the logging entries are to be recorded.

verbosity indicates the extent of the logging activity intended. Valid values are as follows:

0   Performs no logging.
1   Records where writes and reads occur in the file.
2   Records where writes and reads occur in the file and what kind of data is written at each location: raw data or any of several types of metadata (object headers, superblock, B-tree data, local headers, or global headers).
Parameters:
hid_t fapl_id
IN: File access property list identifier.
char *logfile
IN: Name of the log file.
int verbosity
IN: The extent of logging activity intended.
Returns:
Returns non-negative if successful. Otherwise returns negative.
Name: H5Pset_fapl_mpio
Signature:
herr_t H5Pset_fapl_mpio( hid_t fapl_id, MPI_Comm comm, MPI_Info info )
Purpose:
Stores MPI IO communicator information to the file access property list.
Description:
H5Pset_fapl_mpio stores the user-supplied MPI IO parameters comm, for communicator, and info, for information, in the file access property list fapl_id. That property list can then be used to create and/or open the file.

H5Pset_fapl_mpio is available only in the parallel HDF5 library and is not a collective function.

comm is the MPI communicator to be used for file open as defined in MPI_FILE_OPEN of MPI-2. This function does not create a duplicated communicator. Modifications to comm after this function call returns may have an undetermined effect on the access property list. Users should not modify the communicator while it is defined in a property list.

info is the MPI info object to be used for file open as defined in MPI_FILE_OPEN of MPI-2. This function does not create a duplicated info object. Any modification to the info object after this function call returns may have an undetermined effect on the access property list. Users should not modify the info while it is defined in a property list.

Parameters:
hid_t fapl_id
IN: File access property list identifier.
MPI_Comm comm
IN: MPI-2 communicator.
MPI_Info info
IN: MPI-2 info object.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Non-C API(s):
Name: H5Pget_fapl_mpio
Signature:
herr_t H5Pget_fapl_mpio( hid_t fapl_id, MPI_Comm *comm, MPI_Info *info )
Purpose:
Returns MPI communicator information.
Description:
If the file access property list is set to the H5FD_MPIO driver, H5Pget_fapl_mpio returns the MPI communicator and information through the comm and info pointers, if those values are non-null.

Neither comm nor info is copied, so they are valid only until the file access property list is either modified or closed.

Parameters:
hid_t fapl_id
IN: File access property list identifier.
MPI_Comm *comm
OUT: MPI-2 communicator.
MPI_Info *info
OUT: MPI-2 info object.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Non-C API(s):
Name: H5Pset_dxpl_mpio
Signature:
herr_t H5Pset_dxpl_mpio( hid_t dxpl_id, H5FD_mpio_xfer_t xfer_mode )
Purpose:
Sets data transfer mode.
Description:
H5Pset_dxpl_mpio sets the data transfer property list dxpl_id to use transfer mode xfer_mode. The property list can then be used to control the I/O transfer mode during data I/O operations.

Valid transfer modes are as follows:

H5FD_MPIO_INDEPENDENT
Use independent I/O access (default).
H5FD_MPIO_COLLECTIVE
Use collective I/O access.
Parameters:
hid_t dxpl_id
IN: Data transfer property list identifier.
H5FD_mpio_xfer_t xfer_mode
IN: Transfer mode.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Non-C API(s):
Name: H5Pget_dxpl_mpio
Signature:
herr_t H5Pget_dxpl_mpio( hid_t dxpl_id, H5FD_mpio_xfer_t *xfer_mode )
Purpose:
Returns the data transfer mode.
Description:
H5Pget_dxpl_mpio queries the data transfer mode currently set in the data transfer property list dxpl_id.

Upon return, xfer_mode contains the data transfer mode, if it is non-null.

H5Pget_dxpl_mpio is not a collective function.

Parameters:
hid_t dxpl_id
IN: Data transfer property list identifier.
H5FD_mpio_xfer_t *xfer_mode
OUT: Data transfer mode.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Non-C API(s):
Name: H5Pset_fapl_multi
Signature:
herr_t H5Pset_fapl_multi( hid_t fapl_id, const H5FD_mem_t *memb_map, const hid_t *memb_fapl, const char **memb_name, const haddr_t *memb_addr, hbool_t relax )
Purpose:
Sets up use of the multi-file driver.
Description:
H5Pset_fapl_multi sets the file access property list fapl_id to use the multi-file driver.

The multi-file driver enables different types of HDF5 data and metadata to be written to separate files. These files are viewed by the HDF5 library and the application as a single virtual HDF5 file with a single HDF5 file address space. The types of data that can be broken out into separate files include raw data, the superblock, B-tree data, global heap data, local heap data, and object headers. At the programmer's discretion, two or more types of data can be written to the same file while other types of data are written to separate files.

The array memb_map maps memory usage types to other memory usage types and is the mechanism that allows the caller to specify how many files are created. The array contains H5FD_MEM_NTYPES entries, which are either the value H5FD_MEM_DEFAULT or a memory usage type. The number of unique values determines the number of files that are opened.

The array memb_fapl contains a property list for each memory usage type that will be associated with a file.

The array memb_name should be a name generator (a printf-style format with a %s which will be replaced with the name passed to H5FDopen, usually from H5Fcreate or H5Fopen).

The array memb_addr specifies the offsets within the virtual address space, from 0 (zero) to HADDR_MAX, at wihch each type of data storage begins.

If relax is set to TRUE (or 1), then opening an existing file for read-only access will not fail if some file members are missing. This allows a file to be accessed in a limited sense if just the meta data is available.

Default values for each of the optional arguments are as follows:

memb_map
The default member map contains the value H5FD_MEM_DEFAULT for each element.
memb_fapl
The default value is H5P_DEFAULT for each element.
memb_name
The default string is   %s-X.h5   where   X   is one of the following letters: s    for H5FD_MEM_SUPER
b    for H5FD_MEM_BTREE
r    for H5FD_MEM_DRAW
g    for H5FD_MEM_GHEAP
l    for H5FD_MEM_LHEAP
o    for H5FD_MEM_OHDR
memb_addr
The default value is HADDR_UNDEF for each element.
Parameters:
hid_t fapl_id
IN: File access property list identifier.
const H5FD_mem_t *memb_map
IN: Maps memory usage types to other memory usage types.
const hid_t *memb_fapl
IN: Property list for each memory usage type.
const char **memb_name
IN: Name generator for names of member files.
const haddr_t *memb_addr
IN: The offsets within the virtual address space, from 0 (zero) to HADDR_MAX, at wihch each type of data storage begins.
hbool_t relax
IN: Allows read-only access to incomplete file sets when TRUE.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Example:
The following code sample sets up a multi-file access property list that partitions data into meta and raw files, each being one-half of the address: 
                  H5FD_mem_t mt, memb_map[H5FD_MEM_NTYPES];
                  hid_t memb_fapl[H5FD_MEM_NTYPES];
                  const char *memb[H5FD_MEM_NTYPES];
                  haddr_t memb_addr[H5FD_MEM_NTYPES];
 
                  // The mapping...
                  for (mt=0; mt<H5FD_MEM_NTYPES; mt++) {
                     memb_map[mt] = H5FD_MEM_SUPER;
                  }
                  memb_map[H5FD_MEM_DRAW] = H5FD_MEM_DRAW;
 
                  // Member information
                  memb_fapl[H5FD_MEM_SUPER] = H5P_DEFAULT;
                  memb_name[H5FD_MEM_SUPER] = "%s.meta";
                  memb_addr[H5FD_MEM_SUPER] = 0;
 
                  memb_fapl[H5FD_MEM_DRAW] = H5P_DEFAULT;
                  memb_name[H5FD_MEM_DRAW] = "%s.raw";
                  memb_addr[H5FD_MEM_DRAW] = HADDR_MAX/2;
 
                  hid_t fapl = H5Pcreate(H5P_FILE_ACCESS);
                  H5Pset_fapl_multi(fapl, memb_map, memb_fapl,
                                  memb_name, memb_addr, TRUE);
Name: H5Pget_fapl_multi
Signature:
herr_t H5Pget_fapl_multi( hid_t fapl_id, const H5FD_mem_t *memb_map, const hid_t *memb_fapl, const char **memb_name, const haddr_t *memb_addr, hbool_t *relax )
Purpose:
Returns information about the multi-file access property list.
Description:
H5Pget_fapl_multi returns information about the multi-file access property list.
Parameters:
hid_t fapl_id
IN: File access property list identifier.
const H5FD_mem_t *memb_map
OUT: Maps memory usage types to other memory usage types.
const hid_t *memb_fapl
OUT: Property list for each memory usage type.
const char **memb_name
OUT: Name generator for names of member files.
const haddr_t *memb_addr
OUT:
hbool_t *relax
OUT: Allows read-only access to incomplete file sets when TRUE.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pset_dxpl_multi
Signature:
herr_t H5Pset_dxpl_multi( hid_t dxpl_id, const hid_t *memb_dxpl )
Purpose:
Sets the data transfer property list for the multi-file driver.
Description:
H5Pset_dxpl_multi sets the data transfer property list dxpl_id to use the multi-file driver for each memory usage type memb_dxpl[].

H5Pset_dxpl_multi can only be used after the member map has been set with H5Pset_fapl_multi.

Parameters:
hid_t dxpl_id,
IN: Data transfer property list identifier.
const hid_t *memb_dxpl
IN: Array of data access property lists.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pget_dxpl_multi
Signature:
herr_t H5Pget_dxpl_multi( hid_t dxpl_id, const hid_t *memb_dxpl )

Purpose:
Returns multi-file data transfer property list information.
Description:
H5Pget_dxpl_multi returns the data transfer property list information for the multi-file driver.
Parameters:
hid_t dxpl_id,
IN: Data transfer property list identifier.
const hid_t *memb_dxpl
OUT: Array of data access property lists.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pset_fapl_split
Signature:
herr_t H5Pset_fapl_split( hid_t fapl_id, const char *meta_ext, hid_t meta_plist_id, const char *raw_ext, hid_t raw_plist_id )
Purpose:
Emulates the old split file driver.
Description:
H5Pset_fapl_split is a compatability function that enables the multi-file driver to emulate the split driver from HDF5 Releases 1.0 and 1.2. The split file driver stored metadata and raw data in separate files but provided no mechanism for separating types of metadata.

fapl_id is a file access property list identifier.

meta_ext is the filename extension for the metadata file. The extension is appended to the name passed to H5FDopen, usually from H5Fcreate or H5Fopen, to form the name of the metadata file. If the string %s is used in the extension, it works like the name generator as in H5Pset_fapl_multi.

meta_plist_id is the file access property list identifier for the metadata file.

raw_ext is the filename extension for the raw data file. The extension is appended to the name passed to H5FDopen, usually from H5Fcreate or H5Fopen, to form the name of the rawdata file. If the string %s is used in the extension, it works like the name generator as in H5Pset_fapl_multi.

raw_plist_id is the file access property list identifier for the raw data file.

If a user wishes to check to see whether this driver is in use, the user must call H5Pget_driver and compare the returned value to the string H5FD_MULTI. A positive match will confirm that the multi driver is in use; HDF5 provides no mechanism to determine whether it was called as the special case invoked by H5Pset_fapl_split.

Parameters:
hid_t fapl_id,
IN: File access property list identifier.
const char *meta_ext,
IN: Metadata filename extension.
hid_t meta_plist_id,
IN: File access property list identifier for the metadata file.
const char *raw_ext,
IN: Raw data filename extension.
hid_t raw_plist_id
IN: File access property list identifier for the raw data file.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Example: 
/* Example 1: Both metadata and rawdata files are in the same  */
/*    directory.   Use Station1-m.h5 and Station1-r.h5 as      */
/*    the metadata and rawdata files.                          */
hid_t fapl, fid;
fapl = H5Pcreate(H5P_FILE_ACCESS);
H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "-r.h5", H5P_DEFAULT);
fid=H5Fcreate("Station1",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);

/* Example 2: metadata and rawdata files are in different      */
/*    directories.  Use PointA-m.h5 and /pfs/PointA-r.h5 as    */
/*    the metadata and rawdata files.                          */
hid_t fapl, fid;
fapl = H5Pcreate(H5P_FILE_ACCESS);
H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "/pfs/%s-r.h5", H5P_DEFAULT);
fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
Name: H5Pset_fapl_sec2
Signature:
herr_t H5Pset_fapl_sec2( hid_t fapl_id )
Purpose:
Sets the sec2 driver.
Description:
H5Pset_fapl_sec2 modifies the file access property list to use the H5FD_SEC2 driver.
Parameters:
hid_t fapl_id
IN: File access property list identifier.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pset_fapl_stdio
Signature:
herr_t H5Pset_fapl_stdio( hid_t fapl_id )
Purpose:
Sets the standard I/O driver.
Description:
H5Pset_fapl_stdio modifies the file access property list to use the standard I/O driver, H5FD_STDIO.
Parameters:
hid_t fapl_id
IN: File access property list identifier.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pset_fapl_stream
Signature:
herr_t H5Pset_fapl_stream( hid_t fapl_id, H5FD_stream_fapl_t *fapl )
Purpose:
Sets up the use of the streaming I/O driver.
Description:
H5Pset_fapl_stream sets up the use of the streaming I/O driver.

fapl_id is the identifier for the file access property list currently in use.

fapl is the file access property list.

The H5FD_stream_fapl_t struct contains the following elements:

size_t increment
H5FD_STREAM_SOCKET_TYPE socket
hbool_t do_socket_io
unsigned int backlog
H5FD_stream_broadcast_t broadcast_fn
void * broadcast_arg
  • increment specifies how much memory to allocate each time additional memory is required.
  • socket is an external socket descriptor; if a valid socket argument is provided, that socket will be used.
  • do_socket_io is a boolean value specifying whether to perform I/O on socket.
  • backlog is the argument for the listen call.
  • broadcast_fn is the broadcast callback function.
  • broadcast_arg is the user argument to the broadcast callback function.

H5Pset_fapl_stream and H5Pget_fapl_stream are not intended for use in a parallel environment.

Parameters:
hid_t fapl_id
IN: File access property list identifier.
H5FD_stream_fapl_t *fapl
IN: The streaming I/O file access property list.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pget_fapl_stream
Signature:
herr_t H5Pget_fapl_stream( hid_t fapl_id, H5FD_stream_fapl_t *fapl )
Purpose:
Returns the streaming I/O driver settings.
Description:
H5Pget_fapl_stream returns the file access properties set for the use of the streaming I/O driver.

H5Pset_fapl_stream and H5Pget_fapl_stream are not intended for use in a parallel environment.

Parameters:
hid_t fapl_id
IN: File access property list identifier.
H5FD_stream_fapl_t *fapl
OUT: The streaming I/O file access property list.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pget_driver
Signature:
hid_t H5Pget_driver( hid_t plist_id )
Purpose:
Returns low-lever driver identifier.
Description:
H5Pget_driver returns the identifier of the low-level file driver associated with the file access property list or data transfer propert list plist_id.

Valid driver identifiers with the standard HDF5 library distribution include the following: 

           H5FD_CORE
           H5FD_DPSS
           H5FD_FAMILY
           H5FD_GASS
           H5FD_LOG
           H5FD_MPIO
           H5FD_MULTI
           H5FD_SEC2
           H5FD_STDIO
           H5FD_STREAM
If a user defines and registers custom drivers or if additional drivers are defined in an HDF5 distribution, this list will be longer.

The returned driver identifier is only valid as long as the file driver remains registered.

Parameters:
hid_t plist_id
IN: File access or data transfer property list identifier.
Returns:
Returns a vaild low-level driver identifier if successful. Otherwise returns a negative value.
Name: H5Pset_fapl_gass
Signature:
herr_t H5Pset_fapl_gass( hid_t fapl_id, GASS_Info info )
Purpose:
Stores user-supplied GASS information.
Description:
H5Pset_fapl_gass stores user-supplied GASS information, the GASS_Info struct data as passed in info, to the file access property list fapl_id. fapl_id can then be used to create and/or open the file.

The GASS_Info object, info, is used for file open operations when using GASS in the Globus environment.

Any modification to info after this function call returns may have undetermined effect to the access property list. Users must call H5Pset_fapl_gass again to setup the property list.

Note:
H5Pset_fapl_gass is an experimental function. It is designed for use only when accessing files via the GASS facility of the Globus environment. For further information, see http//www.globus.org/.
Parameters:
hid_t fapl_id,
IN: File access property list identifier.
GASS_Info info
IN: Pointer to the GASS information structure.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pget_fapl_gass
Signature:
herr_t H5Pget_fapl_gass( hid_t fapl_id, GASS_Info *info )
Purpose:
Retrieves GASS information.
Description:
If the file access property list fapl_id is set for use of the H5FD_GASS driver, H5Pget_fapl_gass returns the GASS_Info object through the info pointer.

The GASS_Info information is copied, so it is valid only until the file access property list is modified or closed.

Note:
H5Pget_fapl_gass is an experimental function. It is designed for use only when accessing files via the GASS facility of the Globus environment. For further information, see http//www.globus.org/.
Parameters:
hid_t fapl_id,
IN: File access property list identifier.
GASS_Info *info
OUT: Pointer to the GASS information structure.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pset_fapl_srb
Signature:
herr_t H5Pset_fapl_srb( hid_t fapl_id, SRB_Info info )
Purpose:
Saves SRB connection handler and sets SRB settings.
Description:
H5Pset_fapl_srb stores the SRB client-to-server connection handler SRB_CONN after the connection is established and other user-supplied SRB information.

The user-supplied SRB information is contained in the SRB_Info struct pointed to by info and is stored in the file access property list fapl_id. This information can then be used to create or open a file.

Note:
H5Pset_fapl_gass is an experimental function. It is designed for use only when accessing files via the Storage Resource Broker (SRB). For further information, see http//www.npaci.edu/Research/DI/srb/.
Parameters:
hid_t fapl_id
IN: File access property list identifier.
SRB_Info info
IN: Pointer to the SRB information structure.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pget_fapl_srb
Signature:
herr_t H5Pget_fapl_srb( hid_t fapl_id, SRB_Info *info )
Purpose:
Retrieves SRB information.
Description:
If the file access property list fapl_id is set for use of the H5FD_SRB driver, H5Pget_fapl_srb returns the SRB_Info object through the info pointer.

The SRB_Info information is copied, so it is valid only until the file access property list is modified or closed.

Note:
H5Pset_fapl_gass is an experimental function. It is designed for use only when accessing files via the Storage Resource Broker (SRB). For further information, see http//www.npaci.edu/Research/DI/srb/.
Parameters:
hid_t fapl_id
IN: File access property list identifier.
SRB_Info *info
OUT: Pointer to the SRB information structure.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pset_fapl_core
Signature:
herr_t H5Pset_fapl_core( hid_t fapl_id, size_t increment, hbool_t backing_store )
Purpose:
Modifies the file access property list to use the H5FD_CORE driver.
Description:
H5Pset_fapl_core modifies the file access property list to use the H5FD_CORE driver.

The H5FD_CORE driver enables an application to work with a file in memory, speeding reads and writes as no disk access is made. File contents are stored only in memory until the file is closed. The backing_store parameter determines whether file contents are ever written to disk.

increment specifies the increment by which allocated memory is to be increased each time more memory is required.

If backing_store is set to 1 (TRUE), the file contents are flushed to a file with the same name as this core file when the file is closed or access to the file is terminated in memory.

Note:
There is currently no means for reading a file from disk then using the H5FD_CORE driver to manipulate the file.
Parameters:
hid_t fapl_id
IN: File access property list identifier.
size_t increment
IN: Size, in bytes, of memory increments.
hbool_t backing_store
IN: Boolean flag indicating whether to write the file contents to disk when the file is closed.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Name: H5Pget_fapl_core
Signature:
herr_t H5Pget_fapl_core( hid_t fapl_id, size_t *increment, hbool_t *backing_store )
Purpose:
Queries core file driver properties.
Description:
H5Pget_fapl_core queries the H5FD_CORE driver properties as set by H5Pset_fapl_core.
Parameters:
hid_t fapl_id
IN: File access property list identifier.
size_t *increment
OUT: Size, in bytes, of memory increments.
hbool_t *backing_store
OUT: Boolean flag indicating whether to write the file contents to disk when the file is closed.
Returns:
Returns a non-negative value if successful. Otherwise returns a negative value.
Introduction to HDF5 
HDF5 User Guide 
Other HDF5 documents and links 
 And in this document, the HDF5 Reference Manual  
H5   H5A   H5D   H5E   H5F   H5G   H5I   H5P  
H5R   H5S   H5T   H5Z   Tools   Datatypes  
HDF Help Desk
Last modified: 25 April 2002
Describes HDF5 Release 1.5, Unreleased Development Branch