- Created by Barbara Jones, last modified on Mar 17, 2020
H5P_ENCODE2
Encodes the property values in a property list into a binary buffer
Procedure:
H5P_ENCODE2 ( plist_id, buf, nalloc, fapl_id )
Signature:
herr_t H5Pencode2 ( hid_t plist_id, void *buf, size_t *nalloc, hid_t fapl_id )
Parameters:
hid_t plist_id | IN: Identifier of the property list to be encoded |
void *buf | OUT: 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. |
size_t *nalloc | OUT: The size of the required buffer |
hid_t fapl_id | IN: File access property list |
Description:
H5P_ENCODE2 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 H5P_ENCODE2 call.
If the buffer passed in is not big enough to hold the encoded properties, the H5P_ENCODE2 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 H5P_SET_LIBVER_BOUNDS). If the libver_bounds property is missing, H5P_ENCODE2 proceeds as if the libver_bounds property were set to (H5F_LIBVER_EARLIEST, H5F_LIBVER_LATEST). (Functionally, H5P_ENCODE1 is identical to H5P_ENCODE2 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. See the New Features in HDF5 Release 1.12 as well as the H5Sencode / H5Sdecode Format Change RFC.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Example:
/* Encode property list to plist_buf */
if(H5Pencode2(dcpl, NULL, &plist_buf_size, fapl) < 0)
History:
| Release | Change |
|---|---|
| 1.12.0 | Function introduced in this release. |
--- Last Modified: March 17, 2020 | 02:32 PM