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

# 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

- H5Pcreate
- H5Pget_class
- H5Pcopy
- H5Pclose

File Creation Properties

- H5Pget_version
- H5Pset_userblock
- H5Pget_userblock
- H5Pset_sizes
- H5Pget_sizes
- H5Pset_sym_k
- H5Pget_sym_k
- H5Pset_istore_k
- H5Pget_istore_k

File Access Properties

- H5Pget_driver
- H5Pset_stdio
- H5Pget_stdio
- H5Pset_sec2
- H5Pget_sec2
- H5Pset_alignment
- H5Pget_alignment
- H5Pset_core
- H5Pget_core
- H5Pset_mpi ||
- H5Pget_mpi ||
- H5Pset_family
- H5Pget_family
- H5Pset_cache
- H5Pget_cache
- H5Pset_split
- H5Pget_split

Dataset Creation Properties

- H5Pset_layout
- H5Pget_layout
- H5Pset_chunk
- H5Pget_chunk
- H5Pset_deflate
- H5Pset_filter
- H5Pget_nfilters
- H5Pget_filter
- H5Pset_external
- H5Pget_external_count
- H5Pget_external

Dataset Memory and Transfer Properties

- H5Pset_buffer
- H5Pget_buffer
- H5Pset_preserve
- H5Pget_preserve
- H5Pset_xfer ||
- H5Pget_xfer ||

|| 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:

  H5D_XFER_INDEPENDENT
    Use independent I/O access. (Currently the default mode.)
  H5D_XFER_COLLECTIVE
    Use MPI collective I/O access.
  H5D_XFER_DFLT
    User default I/O access.
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 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 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:
  H5D_COMPACT
    Store raw data and object header contiguously in file. This should only be used for very small amounts of raw data (suggested less than 1KB).
  H5D_CONTIGUOUS
    Store raw data seperately from object header in one large chunk in the file.
  H5D_CHUNKED
    Store raw data seperately from object header in one large chunk in the file and store chunks of the raw data in seperate locations in the file.
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:
  H5D_COMPACT
    Raw data and object header stored contiguously in file.
  H5D_CONTIGUOUS
    Raw data stored seperately from object header in one large chunk in the file.
  H5D_CHUNKED
    Raw data stored seperately from object header in chunks in seperate locations in the file.
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 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 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: 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 SUCCEED (0) if successful; otherwise FAIL (-1).

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

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

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:
  - H5F_LOW_STDIO (0)
  - H5F_LOW_SEC2 (1)
  - H5F_LOW_MPIO (2)
  - H5F_LOW_CORE (3)
  - H5F_LOW_SPLIT (4)
  - H5F_LOW_FAMILY (5)
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` if it is not 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:
  Original version. Edited version below.
  `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: 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:
  Edited version. Original version above.
  `H5Pset_family` sets the file access properties to use the `family` driver; any previously defined driver properties are erased from the property list. See File Families in the HDF5 User's Guide</dite> for a discussion of file families.

  Each member of the file family will use `memb_plist` as its file access property list.

  The `memb_size` argument gives the logical size in bytes of each family member; 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_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<>/code>, 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 SUCCEED (0) if successful; otherwise FAIL (-1).

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

HDF Help Desk
Last modified: 25 August 1998