Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
Property List Class Root
Property Lists (H5P)

## Detailed Description

Use the functions in this module to manage HDF5 property lists.

Property list class root functions (H5P)
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.

## Function Documentation

## ◆ H5Pclose()

herr_t H5Pclose | ( | hid_t | plist_id | ) |

Terminates access to a property list.

Parameters

  [in] | plist_id | Property list identifier

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

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.

Since
  1.0.0

## ◆ H5Pcopy()

hid_t H5Pcopy | ( | hid_t | plist_id | ) |

Copies an existing property list to create a new property list.

Parameters

  [in] | plist_id | Property list identifier

Returns
  Returns a property list identifier if successful; otherwise returns H5I_INVALID_HID.

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.

Since
  1.0.0

## ◆ H5Pcreate()

hid_t H5Pcreate | ( | hid_t | cls_id | ) |

Creates a new property list as an instance of a property list class.

Parameters

  [in] | cls_id | Property list class identifier

Returns
  Returns a property list identifier if successful; otherwise returns H5I_INVALID_HID.

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.

Version
  1.12.0 The H5P_VOL_INITIALIZE property list class was added
  1.8.15 For each class, the class name returned by H5Pget_class_name() was added. The list of possible Fortran values was updated.
  1.8.0 The following property list classes were added at this release: H5P_DATASET_ACCESS, H5P_GROUP_CREATE, H5P_GROUP_ACCESS, H5P_DATATYPE_CREATE, H5P_DATATYPE_ACCESS, H5P_ATTRIBUTE_CREATE

Since
  1.0.0

## ◆ H5Pdecode()

hid_t H5Pdecode | ( | const void * | buf | ) |

Decodes property list received in a binary object buffer and returns a new property list identifier.

Parameters

  [in] | buf | Buffer holding the encoded property list

Returns
  Returns an object identifier if successful; otherwise returns H5I_INVALID_HID.

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.

Note
  Some properties cannot be encoded and therefore will not be available in the decoded property list. These properties are discussed in H5Pencode().

Since
  1.10.0

## ◆ H5Pencode2()

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.

Parameters

  [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

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

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_V18, H5F_LIBVER_LATEST). (Functionally, H5Pencode1() is identical to H5Pencode2() with libver_bounds set to (H5F_LIBVER_V18, 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.

Since
  1.12.0

## ◆ H5Pget_class()

hid_t H5Pget_class | ( | hid_t | plist_id | ) |

Returns the property list class identifier for a property list.

Parameters

  [in] | plist_id | Property list identifier

Returns
  Returns a property list class identifier if successful; otherwise returns H5I_INVALID_HID.

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:

plist_class_id = H5Pget_class (dsetA_plist);
if H5Pequal (plist_class_id, H5P_OBJECT_CREATE) = true;
[ H5P_OBJECT_CREATE is the property list class ]
[ returned by H5Pget_class. ]
else if H5Pequal (plist_class_id, H5P_DATASET_CREATE) = true;
[ H5P_DATASET_CREATE is the property list class. ]
else if H5Pequal (plist_class_id, H5P_DATASET_XFER) = true;
[ H5P_DATASET_XFER is the property list class. ]
.
. [ Continuing the iteration until a match is found. ]
.
H5P_OBJECT_CREATE
#define H5P_OBJECT_CREATE
Definition H5Ppublic.h:48
H5P_DATASET_XFER
#define H5P_DATASET_XFER
Definition H5Ppublic.h:68
H5P_DATASET_CREATE
#define H5P_DATASET_CREATE
Definition H5Ppublic.h:60
H5Pequal
htri_t H5Pequal(hid_t id1, hid_t id2)
Compares two property lists or classes for equality.
H5Pget_class
hid_t H5Pget_class(hid_t plist_id)
Returns the property list class identifier for a property list.

H5Pget_class_name() returns the property list class name directly as a string:

plist_class_id = H5Pget_class (dsetA_plist);
plist_class_name = H5Pget_class_name (plist_class_id)
H5Pget_class_name
char * H5Pget_class_name(hid_t pclass_id)
Retrieves the name of a class.

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.

Version
  1.6.0 Return type changed in this release.

Since
  1.0.0