 |
HDF5 2.0.0.258fa78
API Reference
|
|
HDF5 2.0.0.258fa78
API Reference
|
Use the functions in this module to manage HDF5 property lists.
| Function | Purpose |
|---|---|
| H5Pclose | Terminates access to a property list. |
| H5Pcopy | Copies an existing property list to create a new property list. |
| H5Pcreate | Creates a new property list as an instance of a property list class. |
| H5Pencode/H5Pdecode | Encodes/ecodes property list into/from a binary object buffer. |
| H5Pget_class | Returns the property list class identifier for a property list |
Functions | |
| herr_t | H5Pclose (hid_t plist_id) |
| Terminates access to a property list. | |
| hid_t | H5Pcopy (hid_t plist_id) |
| Copies an existing property list to create a new property list. | |
| hid_t | H5Pcreate (hid_t cls_id) |
| Creates a new property list as an instance of a property list class. | |
| hid_t | H5Pdecode (const void *buf) |
| Decodes property list received in a binary object buffer and returns a new property list identifier. | |
| herr_t | H5Pencode2 (hid_t plist_id, void *buf, size_t *nalloc, hid_t fapl_id) |
| Encodes the property values in a property list into a binary buffer. | |
| hid_t | H5Pget_class (hid_t plist_id) |
| Returns the property list class identifier for a property list. | |
Terminates access to a property list.
| [in] | plist_id | Property list identifier |
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.
Copies an existing property list to create a new property list.
| [in] | plist_id | Property list identifier |
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.
Creates a new property list as an instance of a property list class.
| [in] | cls_id | Property list class identifier |
H5Pcreate() creates a new property list as an instance of some property list class. The new property list is initialized with default values for the specified class. The classes are as follows:
| Class Identifier | Class Name | Comments |
|---|---|---|
| H5P_ATTRIBUTE_CREATE | attribute create | Properties for attribute creation |
| H5P_DATASET_ACCESS | dataset access | Properties for dataset access |
| H5P_DATASET_CREATE | dataset create | Properties for dataset creation |
| H5P_DATASET_XFER | data transfer | Properties for raw data transfer |
| H5P_DATATYPE_ACCESS | datatype access | Properties for datatype access |
| H5P_DATATYPE_CREATE | datatype create | Properties for datatype creation |
| H5P_FILE_ACCESS | file access | Properties for file access |
| H5P_FILE_CREATE | file create | Properties for file creation |
| H5P_FILE_MOUNT | file mount | Properties for file mounting |
| H5P_GROUP_ACCESS | group access | Properties for group access |
| H5P_GROUP_CREATE | group create | Properties for group creation |
| H5P_LINK_ACCESS | link access | Properties governing link traversal when accessing objects |
| H5P_LINK_CREATE | link create | Properties governing link creation |
| H5P_OBJECT_COPY | object copy | Properties governing the object copying process |
| H5P_OBJECT_CREATE | object create | Properties for object creation |
| H5P_STRING_CREATE | string create | Properties for character encoding when encoding strings or object names |
| H5P_VOL_INITIALIZE | vol initialize | Properties for VOL initialization |
This property list must eventually be closed with H5Pclose(); otherwise, errors are likely to occur.
| hid_t H5Pdecode | ( | const void * | buf | ) |
Decodes property list received in a binary object buffer and returns a new property list identifier.
| [in] | buf | Buffer holding the encoded property list |
Given a binary property list description in a buffer, H5Pdecode() reconstructs the HDF5 property list and returns an identifier for the new property list. The binary description of the property list is encoded by H5Pencode().
The user is responsible for passing in the correct buffer.
The property list identifier returned by this function should be released with H5Pclose() when the identifier is no longer needed so that resource leaks will not develop.
Encodes the property values in a property list into a binary buffer.
| [in] | plist_id | Property list identifier |
| [out] | buf | Buffer into which the property list will be encoded. If the provided buffer is NULL, the size of the buffer required is returned through nalloc; the function does nothing more. |
| [out] | nalloc | The size of the required buffer |
| [in] | fapl_id | File access property list identifier |
H5Pencode2() encodes the property list plist_id into the binary buffer buf, according to the file format setting specified by the file access property list fapl_id.
If the required buffer size is unknown, buf can be passed in as NULL and the function will set the required buffer size in nalloc. The buffer can then be created and the property list encoded with a subsequent H5Pencode2() call.
If the buffer passed in is not big enough to hold the encoded properties, the H5Pencode2() call can be expected to fail with a segmentation fault.
The file access property list fapl_id is used to control the encoding via the libver_bounds property (see H5Pset_libver_bounds()). If the libver_bounds property is missing, H5Pencode2() proceeds as if the libver_bounds property were set to (H5F_LIBVER_EARLIEST, H5F_LIBVER_LATEST). (Functionally, H5Pencode1() is identical to H5Pencode2() with libver_bounds set to (H5F_LIBVER_EARLIEST, H5F_LIBVER_LATEST).) Properties that do not have encode callbacks will be skipped. There is currently no mechanism to register an encode callback for a user-defined property, so user-defined properties cannot currently be encoded.
Some properties cannot be encoded, particularly properties that are reliant on local context.
Motivation: This function was introduced in HDF5-1.12 as part of the H5Sencode format change to enable 64-bit selection encodings and a dataspace selection that is tied to a file.
Returns the property list class identifier for a property list.
| [in] | plist_id | Property list identifier |
H5Pget_class() returns the property list class identifier for the property list identified by the plist_id parameter.
Note that H5Pget_class() returns a value of hid_t type, an internal HDF5 identifier, rather than directly returning a property list class. That identifier can then be used with either H5Pequal() or H5Pget_class_name() to determine which predefined HDF5 property list class H5Pget_class() has returned.
A full list of valid predefined property list classes appears in the description of H5Pcreate().
Determining the HDF5 property list class name with H5Pequal() requires a series of H5Pequal() calls in an if-else sequence. An iterative sequence of H5Pequal() calls can compare the identifier returned by H5Pget_class() to members of the list of valid property list class names. A pseudo-code snippet might read as follows:
H5Pget_class_name() returns the property list class name directly as a string:
Note that frequent use of H5Pget_class_name() can become a performance problem in a high-performance environment. The H5Pequal() approach is generally much faster.
1.9.7 