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

| HDF5 Last Updated on 2025-11-11 The HDF5 Field Guide

- Main Page
- Getting started
- User Guide
- Reference Manual
- Cookbook
- Technical Notes
- RFCs
- Specifications
- Glossary
- Full-Text Search
- About

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

## Detailed Description

You can create and customize user-defined property list classes using the functions described below. Arbitrary user-defined properties can also be inserted into existing property lists as so-called temporary properties.

Property list class root (Advanced) functions (H5P)
Function | Purpose
--- | ---
H5Pclose_class | Closes an existing property list class.
H5Pcopy_prop | Copies a property from one list or class to another.
H5Pcreate_class | Creates a new property list class.
H5Pequal | Compares two property lists or classes for equality.
H5Pexist | Queries whether a property name exists in a property list or class.
H5Pget_class_name | Retrieves the name of a class.
H5Pget_class_parent | Retrieves the parent class of a property class.
H5Pget_nprops | Queries the number of properties in a property list or class.
H5Pget_size | Queries the size of a property value in bytes.
H5Pinsert | Registers a temporary property with a property list.
H5Pisa_class | Determines whether a property list is a member of a class.
H5Piterate | Iterates over properties in a property class or list
H5Pregister/H5Punregister | Registers/removes a permanent property with/from a property list class
H5Premove | Removes a property from a property list.
H5Pset/H5Pget | Sets/queries a property list value

## Functions
herr_t | H5Pclose_class (hid_t plist_id)
| Closes an existing property list class.
herr_t | H5Pcopy_prop (hid_t dst_id, hid_t src_id, const char *name)
| Copies a property from one list or class to another.
hid_t | H5Pcreate_class (hid_t parent, const char *name, H5P_cls_create_func_t create, void *create_data, H5P_cls_copy_func_t copy, void *copy_data, H5P_cls_close_func_t close, void *close_data)
| Creates a new property list class.
herr_t | H5Pencode1 (hid_t plist_id, void *buf, size_t *nalloc)
| Encodes the property values in a property list into a binary buffer.
htri_t | H5Pequal (hid_t id1, hid_t id2)
| Compares two property lists or classes for equality.
htri_t | H5Pexist (hid_t plist_id, const char *name)
| Queries whether a property name exists in a property list or class.
herr_t | H5Pget (hid_t plist_id, const char *name, void *value)
| Queries the value of a property.
char * | H5Pget_class_name (hid_t pclass_id)
| Retrieves the name of a class.
hid_t | H5Pget_class_parent (hid_t pclass_id)
| Retrieves the parent class of a property class.
herr_t | H5Pget_nprops (hid_t id, size_t *nprops)
| Queries the number of properties in a property list or class.
herr_t | H5Pget_size (hid_t id, const char *name, size_t *size)
| Queries the size of a property value in bytes.
herr_t | H5Pinsert1 (hid_t plist_id, const char *name, size_t size, void *value, H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_delete, H5P_prp_copy_func_t prp_copy, H5P_prp_close_func_t prp_close)
| Registers a temporary property with a property list.
herr_t | H5Pinsert2 (hid_t plist_id, const char *name, size_t size, void *value, H5P_prp_set_func_t set, H5P_prp_get_func_t get, H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t copy, H5P_prp_compare_func_t compare, H5P_prp_close_func_t close)
| Registers a temporary property with a property list.
htri_t | H5Pisa_class (hid_t plist_id, hid_t pclass_id)
| Determines whether a property list is a member of a class.
int | H5Piterate (hid_t id, int *idx, H5P_iterate_t iter_func, void *iter_data)
| Iterates over properties in a property class or list.
herr_t | H5Pregister1 (hid_t cls_id, const char *name, size_t size, void *def_value, H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t prp_copy, H5P_prp_close_func_t prp_close)
| Registers a permanent property with a property list class.
herr_t | H5Pregister2 (hid_t cls_id, const char *name, size_t size, void *def_value, H5P_prp_create_func_t create, H5P_prp_set_func_t set, H5P_prp_get_func_t get, H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t copy, H5P_prp_compare_func_t compare, H5P_prp_close_func_t close)
| Registers a permanent property with a property list class.
herr_t | H5Premove (hid_t plist_id, const char *name)
| Removes a property from a property list.
herr_t | H5Pset (hid_t plist_id, const char *name, const void *value)
| Sets a property list value.
herr_t | H5Punregister (hid_t pclass_id, const char *name)
| Removes a property from a property list class.

## Function Documentation

## ◆ H5Pclose_class()

herr_t H5Pclose_class | ( | hid_t | plist_id | ) |

Closes an existing property list class.

Parameters

  [in] | plist_id | Property list class identifier

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

H5Pclose_class() removes a property list class from the library. Existing property lists of this class will continue to exist, but new ones are not able to be created.

Since
  1.4.0

## ◆ H5Pcopy_prop()

herr_t H5Pcopy_prop | ( | hid_t | dst_id,
|  | hid_t | src_id,
|  | const char * | name )

Copies a property from one list or class to another.

Parameters

  [in] | dst_id | Identifier of the destination property list or class
  [in] | src_id | Identifier of the source property list or class
  [in] | name | Name of the property to copy

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

H5Pcopy_prop() copies a property from one property list or class to another.

If a property is copied from one class to another, all the property information will be first deleted from the destination class and then the property information will be copied from the source class into the destination class.

If a property is copied from one list to another, the property will be first deleted from the destination list (generating a call to the close callback for the property, if one exists) and then the property is copied from the source list to the destination list (generating a call to the copy callback for the property, if one exists).

If the property does not exist in the class or list, this call is equivalent to calling H5Pregister() or H5Pinsert() (for a class or list, as appropriate) and the create callback will be called in the case of the property being copied into a list (if such a callback exists for the property).

Since
  1.6.0

## ◆ H5Pcreate_class()

hid_t H5Pcreate_class | ( | hid_t | parent,
|  | const char * | name,
|  | H5P_cls_create_func_t | create,
|  | void * | create_data,
|  | H5P_cls_copy_func_t | copy,
|  | void * | copy_data,
|  | H5P_cls_close_func_t | close,
|  | void * | close_data )

Creates a new property list class.

Parameters

  [in] | parent | Property list class identifier
  [in] | name | Name of property list class to register
  [in] | create | Callback routine called when a property list is created
  [in] | create_data | Pointer to user-defined class create data, to be passed along to class create callback
  [in] | copy | Callback routine called when a property list is copied
  [in] | copy_data | Pointer to user-defined class copy data, to be passed along to class copy callback
  [in] | close | Callback routine called when a property list is being closed
  [in] | close_data | Pointer to user-defined class close data, to be passed along to class close callback

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

H5Pcreate_class() registers a new property list class with the library. The new property list class can inherit from an existing property list class, `parent`, or may be derived from the default “empty” class, NULL. New classes with inherited properties from existing classes may not remove those existing properties, only add or remove their own class properties. Property list classes defined and supported in the HDF5 library distribution are listed and briefly described in H5Pcreate(). The `create`, `copy`, `close` functions are called when a property list of the new class is created, copied, or closed, respectively.

H5Pclose_class() must be used to release the property list class identifier returned by this function.

Since
  1.4.0

## ◆ H5Pencode1()

herr_t H5Pencode1 | ( | hid_t | plist_id,
|  | void * | buf,
|  | size_t * | nalloc )

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

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

Deprecated
  As of HDF5-1.12 this function has been deprecated in favor of H5Pencode2() or the macro H5Pencode().

H5Pencode1() encodes the property list `plist_id` into the binary buffer `buf`.

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 H5Pencode1() call.

If the buffer passed in is not big enough to hold the encoded properties, the H5Pencode1() call can be expected to fail with a segmentation fault.

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.

Since
  1.10.0

## ◆ H5Pequal()

htri_t H5Pequal | ( | hid_t | id1,
|  | hid_t | id2 )

Compares two property lists or classes for equality.

Parameters

  [in] | id1 | First property object to be compared
  [in] | id2 | Second property object to be compared

Returns
  Returns zero (false), a positive (true) or a negative (failure) value.

H5Pequal() compares two property lists or classes to determine whether they are equal to one another.

Either both `id1` and `id2` must be property lists or both must be classes; comparing a list to a class is an error.

Since
  1.4.0

## ◆ H5Pexist()

htri_t H5Pexist | ( | hid_t | plist_id,
|  | const char * | name )

Queries whether a property name exists in a property list or class.

Parameters

  [in] | plist_id | Identifier for the property list or class to query
  [in] | name | Name of property to check for

Returns
  Returns zero (false), a positive (true) or a negative (failure) value.

H5Pexist() determines whether a property exists within a property list or class.

Since
  1.4.0

## ◆ H5Pget()

herr_t H5Pget | ( | hid_t | plist_id,
|  | const char * | name,
|  | void * | value )

Queries the value of a property.

Parameters

  [in] | plist_id | Property list identifier
  [in] | name | Name of property to query
  [out] | value | Pointer to a location to which to copy the value of the property

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

H5Pget() retrieves a copy of the value for a property in a property list. If there is a `get` callback routine registered for this property, the copy of the value of the property will first be passed to that routine and any changes to the copy of the value will be used when returning the property value from this routine.

This routine may be called for zero-sized properties with the `value` set to NULL. The `get` routine will be called with a NULL value if the callback exists.

The property name must exist or this routine will fail.

If the `get` callback routine returns an error, `value` will not be modified.

Since
  1.4.0

## ◆ H5Pget_class_name()

char * H5Pget_class_name | ( | hid_t | pclass_id | ) |

Retrieves the name of a class.

Parameters

  [in] | pclass_id | Property list class identifier

Returns
  Returns a pointer to an allocated string containing the class name if successful, and NULL if not successful.

H5Pget_class_name() retrieves the name of a generic property list class. The pointer to the name must be freed by the user with a call to H5free_memory() after each successful call.

Class Name (class identifier) Returned | Property List Class | Expanded Name of the Property List Class | The Class Identifier Used with H5Pcreate | Comments
--- | --- | --- | --- | ---
attribute create | acpl | Attribute Creation Property List | H5P_ATTRIBUTE_CREATE |
dataset access | dapl | Dataset Access Property List | H5P_DATASET_ACCESS |
dataset create | dcpl | Dataset Creation Property List | H5P_DATASET_CREATE |
data transfer | dxpl | Data Transfer Property List | H5P_DATASET_XFER |
datatype access |  |  | H5P_DATATYPE_ACCESS | This class can be created, but there are no properties in the class currently.
datatype create |  |  | H5P_DATATYPE_CREATE | This class can be created, but there are no properties in the class currently.
file access | fapl | File Access Property List | H5P_FILE_ACCESS |
file create | fcpl | File Creation Property List | H5P_FILE_CREATE |
file mount | fmpl | File Mount Property List | H5P_FILE_MOUNT |
group access |  |  | H5P_GROUP_ACCESS | This class can be created, but there are no properties in the class currently.
group create | gcpl | Group Creation Property List | H5P_GROUP_CREATE |
link access | lapl | Link Access Property List | H5P_LINK_ACCESS |
link create | lcpl | Link Creation Property List | H5P_LINK_CREATE |
object copy | ocpypl | Object Copy Property List | H5P_OBJECT_COPY |
object create | ocpl | Object Creation Property List | H5P_OBJECT_CREATE |
string create | strcpl | String Creation Property List | H5P_STRING_CREATE |

Since
  1.4.0

## ◆ H5Pget_class_parent()

hid_t H5Pget_class_parent | ( | hid_t | pclass_id | ) |

Retrieves the parent class of a property class.

Parameters

  [in] | pclass_id | Property list class identifier

Returns
  Returns a parent class object identifier if successful; otherwise returns H5I_INVALID_HID.

H5Pget_class_parent() retrieves an identifier for the parent class of a property class.

Since
  1.4.0

## ◆ H5Pget_nprops()

herr_t H5Pget_nprops | ( | hid_t | id,
|  | size_t * | nprops )

Queries the number of properties in a property list or class.

Parameters

  [in] | id | Identifier for property object to query
  [out] | nprops | Number of properties in object

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

H5Pget_nprops() retrieves the number of properties in a property list or property list class.

If `id` is a property list identifier, the current number of properties in the list is returned in `nprops`.

If `id` is a property list class identifier, the number of registered properties in the class is returned in `nprops`.

Since
  1.4.0

## ◆ H5Pget_size()

herr_t H5Pget_size | ( | hid_t | id,
|  | const char * | name,
|  | size_t * | size )

Queries the size of a property value in bytes.

Parameters

  [in] | id | Identifier of property object to query
  [in] | name | Name of property to query
  [out] | size | Size of property in bytes

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

H5Pget_size() retrieves the size of a property's value in bytes. This function operates on both property lists and property classes.

Zero-sized properties are allowed and return 0.

Since
  1.4.0

## ◆ H5Pinsert1()

herr_t H5Pinsert1 | ( | hid_t | plist_id,
|  | const char * | name,
|  | size_t | size,
|  | void * | value,
|  | H5P_prp_set_func_t | prp_set,
|  | H5P_prp_get_func_t | prp_get,
|  | H5P_prp_delete_func_t | prp_delete,
|  | H5P_prp_copy_func_t | prp_copy,
|  | H5P_prp_close_func_t | prp_close )

Registers a temporary property with a property list.

Parameters

  [in] | plist_id | Property list identifier
  [in] | name | Name of property to create
  [in] | size | Size of property in bytes
  [in] | value | Initial value for the property
  [in] | prp_set | Callback routine called before a new value is copied into the property's value
  [in] | prp_get | Callback routine called when a property value is retrieved from the property
  [in] | prp_delete | Callback routine called when a property is deleted from a property list
  [in] | prp_copy | Callback routine called when a property is copied from an existing property list
  [in] | prp_close | Callback routine called when a property list is being closed and the property value will be disposed of

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

Deprecated
  As of HDF5-1.8 this function was deprecated in favor of H5Pinsert2() or the macro H5Pinsert().

H5Pinsert1() creates a new property in a property list. The property will exist only in this property list and copies made from it.

The initial property value must be provided in `value` and the property value will be set accordingly.

The name of the property must not already exist in this list, or this routine will fail.

The `prp_set` and `prp_get` callback routines may be set to NULL if they are not needed.

Zero-sized properties are allowed and do not store any data in the property list. The default value of a zero-size property may be set to NULL. They may be used to indicate the presence or absence of a particular piece of information.

The `prp_set` routine is called before a new value is copied into the property. The H5P_prp_set_func_t callback function is defined as H5P_prp_cb2_t. The `prp_set` routine may modify the value pointer to be set and those changes will be used when setting the property's value. If the `prp_set` routine returns a negative value, the new property value is not copied into the property and the `set` routine returns an error value. The `prp_set` routine will be called for the initial value.

Note: The `prp_set` callback function may be useful to range check the value being set for the property or may perform some transformation or translation of the value set. The `prp_get` callback would then reverse the transformation or translation. A single `prp_get` or `prp_set` callback could handle multiple properties by performing different actions based on the property name or other properties in the property list.

The `prp_get` routine is called when a value is retrieved from a property value. The H5P_prp_get_func_t callback function is defined as H5P_prp_cb2_t.

The `prp_get` routine may modify the value to be returned from the query and those changes will be preserved. If the `prp_get` routine returns a negative value, the query routine returns an error value.

The `prp_delete` routine is called when a property is being deleted from a property list. The H5P_prp_delete_func_t callback function is defined as H5P_prp_cb2_t.

The `prp_copy` routine is called when a new property list with this property is being created through a `prp_copy` operation. The H5P_prp_copy_func_t callback function is defined as H5P_prp_cb1_t.

The `prp_copy` routine may modify the value to be set and those changes will be stored as the new value of the property. If the `prp_copy` routine returns a negative value, the new property value is not copied into the property and the prp_copy routine returns an error value.

The `prp_close` routine is called when a property list with this property is being closed. The H5P_prp_close_func_t callback function is defined as H5P_prp_cb1_t.

The `prp_close` routine may modify the value passed in, the value is not used by the library when the close routine returns. If the `prp_close` routine returns a negative value, the property list `prp_close` routine returns an error value but the property list is still closed.

Note: There is no `prp_create` callback routine for temporary property list objects; the initial value is assumed to have any necessary setup already performed on it.

The H5P_prp_cb1_t is as follows:

typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value);

The H5P_prp_cb2_t is as follows:

typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value);

Since
  1.4.0

## ◆ H5Pinsert2()

herr_t H5Pinsert2 | ( | hid_t | plist_id,
|  | const char * | name,
|  | size_t | size,
|  | void * | value,
|  | H5P_prp_set_func_t | set,
|  | H5P_prp_get_func_t | get,
|  | H5P_prp_delete_func_t | prp_del,
|  | H5P_prp_copy_func_t | copy,
|  | H5P_prp_compare_func_t | compare,
|  | H5P_prp_close_func_t | close )

Registers a temporary property with a property list.

Parameters

  [in] | plist_id | Property list identifier
  [in] | name | Name of property to create
  [in] | size | Size of property in bytes
  [in] | value | Initial value for the property
  [in] | set | Callback routine called before a new value is copied into the property's value
  [in] | get | Callback routine called when a property value is retrieved from the property
  [in] | prp_del | Callback routine called when a property is deleted from a property list
  [in] | copy | Callback routine called when a property is copied from an existing property list
  [in] | compare | Callback routine called when a property is compared with another property list
  [in] | close | Callback routine called when a property list is being closed and the property value will be disposed of

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

H5Pinsert2() creates a new property in a property list. The property will exist only in this property list and copies made from it.

The initial property value must be provided in `value` and the property value will be set accordingly.

The name of the property must not already exist in this list, or this routine will fail.

The `set` and `get` callback routines may be set to NULL if they are not needed.

Zero-sized properties are allowed and do not store any data in the property list. The default value of a zero-size property may be set to NULL. They may be used to indicate the presence or absence of a particular piece of information.

The `set` routine is called before a new value is copied into the property. The H5P_prp_set_func_t callback function is defined as follows:

typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value);

The parameters to the callback function are defined as follows:

hid_t `prop_id` | IN: The identifier of the property list being modified
`const char * name` | IN: The name of the property being modified
`size_t size` | IN: The size of the property in bytes
`void * value` | IN: Pointer to new value pointer for the property being modified

The `set` routine may modify the value pointer to be set and those changes will be used when setting the property's value. If the `set` routine returns a negative value, the new property value is not copied into the property and the `set` routine returns an error value. The `set` routine will be called for the initial value.

Note: The `set` callback function may be useful to range check the value being set for the property or may perform some transformation or translation of the value set. The `get` callback would then reverse the transformation or translation. A single `get` or `set` callback could handle multiple properties by performing different actions based on the property name or other properties in the property list.

The `get` routine is called when a value is retrieved from a property value. The H5P_prp_get_func_t callback function is defined as follows:

typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value);

The parameters to the above callback function are:

hid_t `prop_id` | IN: The identifier of the property list being queried
`const char * name` | IN: The name of the property being queried
`size_t size` | IN: The size of the property in bytes
`void * value` | IN: The value of the property being returned

The `get` routine may modify the value to be returned from the query and those changes will be preserved. If the `get` routine returns a negative value, the query routine returns an error value.

The `prp_del` routine is called when a property is being deleted from a property list. The H5P_prp_delete_func_t callback function is defined as follows:

typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value);

The parameters to the above callback function are:

hid_t `prop_id` | IN: The identifier of the property list the property is being deleted from
`const char * name` | IN: The name of the property in the list
`size_t size` | IN: The size of the property in bytes
`void * value` | IN: The value for the property being deleted

The `prp_del` routine may modify the value passed in, but the value is not used by the library when the `prp_del` routine returns. If the `prp_del` routine returns a negative value, the property list `prp_del` routine returns an error value but the property is still deleted.

The `copy` routine is called when a new property list with this property is being created through a `copy` operation.

The H5P_prp_copy_func_t callback function is defined as follows:

typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value);

The parameters to the above callback function are:

`const char * name` | IN: The name of the property being copied
`size_t size` | IN: The size of the property in bytes
`void * value` | IN/OUT: The value for the property being copied

The `copy` routine may modify the value to be set and those changes will be stored as the new value of the property. If the `copy` routine returns a negative value, the new property value is not copied into the property and the copy routine returns an error value.

The `compare` routine is called when a property list with this property is compared to another property list with the same property.

The H5P_prp_compare_func_t callback function is defined as follows:

typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size);

The parameters to the callback function are defined as follows:

`const void * value1` | IN: The value of the first property to compare
`const void * value2` | IN: The value of the second property to compare
`size_t size` | IN: The size of the property in bytes

The `compare` routine may not modify the values. The `compare` routine should return a positive value if `value1` is greater than `value2`, a negative value if `value2` is greater than `value1` and zero if `value1` and `value2` are equal.

The `close` routine is called when a property list with this property is being closed.

The H5P_prp_close_func_t callback function is defined as follows:

typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value);

The parameters to the callback function are defined as follows:

`const char * name` | IN: The name of the property in the list
`size_t size` | IN: The size of the property in bytes
`void * value` | IN: The value for the property being closed

The `close` routine may modify the value passed in, the value is not used by the library when the close routine returns. If the `close` routine returns a negative value, the property list `close` routine returns an error value but the property list is still closed.

Note: There is no `create` callback routine for temporary property list objects; the initial value is assumed to have any necessary setup already performed on it.

Since
  1.8.0

## ◆ H5Pisa_class()

htri_t H5Pisa_class | ( | hid_t | plist_id,
|  | hid_t | pclass_id )

Determines whether a property list is a member of a class.

Parameters

  [in] | plist_id | Property list identifier
  [in] | pclass_id | Property list class identifier

Returns
  Returns zero (false), a positive (true) or a negative (failure) value.

H5Pisa_class() checks to determine whether the property list `plist_id` is a member of the property list class `pclass_id`.

See also
  H5Pcreate()

Since
  1.6.0

## ◆ H5Piterate()

int H5Piterate | ( | hid_t | id,
|  | int * | idx,
|  | H5P_iterate_t | iter_func,
|  | void * | iter_data )

Iterates over properties in a property class or list.

Parameters

  [in] | id | Identifier of property object to iterate over
  [in,out] | idx | Index of the property to begin with
  [in] | iter_func | Function pointer to function to be called with each property iterated over
  [in,out] | iter_data | Pointer to iteration data from user

Returns
  On success: the return value of the last call to `iter_func` if it was non-zero; zero if all properties have been processed. On Failure, a negative value

H5Piterate() iterates over the properties in the property object specified in `id`, which may be either a property list or a property class, performing a specified operation on each property in turn.

For each property in the object, `iter_func` and the additional information specified below are passed to the H5P_iterate_t operator function.

The iteration begins with the `idx-th` property in the object; the next element to be processed by the operator is returned in `idx`. If `idx` is NULL, the iterator starts at the first property; since no stopping point is returned in this case, the iterator cannot be restarted if one of the calls to its operator returns non-zero.

The operation `iter_func` receives the property list or class identifier for the object being iterated over, `id`, the name of the current property within the object, `name`, and the pointer to the operator data passed in to H5Piterate(), `iter_data`.

Warning
  H5Piterate() assumes that the properties in the object identified by `id` remain unchanged through the iteration. If the membership changes during the iteration, the function's behavior is undefined.

Since
  1.4.0

## ◆ H5Pregister1()

herr_t H5Pregister1 | ( | hid_t | cls_id,
|  | const char * | name,
|  | size_t | size,
|  | void * | def_value,
|  | H5P_prp_create_func_t | prp_create,
|  | H5P_prp_set_func_t | prp_set,
|  | H5P_prp_get_func_t | prp_get,
|  | H5P_prp_delete_func_t | prp_del,
|  | H5P_prp_copy_func_t | prp_copy,
|  | H5P_prp_close_func_t | prp_close )

Registers a permanent property with a property list class.

Parameters

  [in] | cls_id | Property list class identifier
  [in] | name | Name of property to register
  [in] | size | Size of property in bytes
  [in] | def_value | Default value for property in newly created property lists
  [in] | prp_create | Callback routine called when a property list is being created and the property value will be initialized
  [in] | prp_set | Callback routine called before a new value is copied into the property's value
  [in] | prp_get | Callback routine called when a property value is retrieved from the property
  [in] | prp_del | Callback routine called when a property is deleted from a property list
  [in] | prp_copy | Callback routine called when a property is copied from a property list
  [in] | prp_close | Callback routine called when a property list is being closed and the property value will be disposed of

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

Deprecated
  As of HDF5-1.8 this function was deprecated in favor of H5Pregister2() or the macro H5Pregister().

H5Pregister1() registers a new property with a property list class. The property will exist in all property list objects of that class after this routine is finished. The name of the property must not already exist. The default property value must be provided and all new property lists created with this property will have the property value set to the default provided. Any of the callback routines may be set to NULL if they are not needed.

Zero-sized properties are allowed and do not store any data in the property list. These may be used as flags to indicate the presence or absence of a particular piece of information. The default pointer for a zero-sized property may be set to NULL. The property `prp_create` and `prp_close` callbacks are called for zero-sized properties, but the `prp_set` and `prp_get` callbacks are never called.

The `prp_create` routine is called when a new property list with this property is being created. The H5P_prp_create_func_t callback function is defined as H5P_prp_cb1_t.

The `prp_create` routine may modify the value to be set and those changes will be stored as the initial value of the property. If the `prp_create` routine returns a negative value, the new property value is not copied into the property and the `prp_create` routine returns an error value.

The `prp_set` routine is called before a new value is copied into the property. The H5P_prp_set_func_t callback function is defined as H5P_prp_cb2_t.

The `prp_set` routine may modify the value pointer to be set and those changes will be used when setting the property's value. If the `prp_set` routine returns a negative value, the new property value is not copied into the property and the `prp_set` routine returns an error value. The `prp_set` routine will not be called for the initial value; only the `prp_create` routine will be called.

Note: The `prp_set` callback function may be useful to range check the value being set for the property or may perform some transformation or translation of the value set. The `prp_get` callback would then reverse the transformation or translation. A single `prp_get` or `prp_set` callback could handle multiple properties by performing different actions based on the property name or other properties in the property list.

The `prp_get` routine is called when a value is retrieved from a property value. The H5P_prp_get_func_t callback function is defined as H5P_prp_cb2_t.

The `prp_get` routine may modify the value to be returned from the query and those changes will be returned to the calling routine. If the `prp_set` routine returns a negative value, the query routine returns an error value.

The `prp_del` routine is called when a property is being deleted from a property list. The H5P_prp_delete_func_t callback function is defined as H5P_prp_cb2_t.

The `prp_del` routine may modify the value passed in, but the value is not used by the library when the `prp_del` routine returns. If the `prp_del` routine returns a negative value, the property list deletion routine returns an error value but the property is still deleted.

The `prp_copy` routine is called when a new property list with this property is being created through a `prp_copy` operation. The H5P_prp_copy_func_t callback function is defined as H5P_prp_cb1_t.

The `prp_copy` routine may modify the value to be set and those changes will be stored as the new value of the property. If the `prp_copy` routine returns a negative value, the new property value is not copied into the property and the `prp_copy` routine returns an error value.

The `prp_close` routine is called when a property list with this property is being closed. The H5P_prp_close_func_t callback function is defined as H5P_prp_cb1_t.

The `prp_close` routine may modify the value passed in, but the value is not used by the library when the `prp_close` routine returns. If the `prp_close` routine returns a negative value, the property list close routine returns an error value but the property list is still closed.

The H5P_prp_cb1_t is as follows:

typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value);

The H5P_prp_cb2_t is as follows:

typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value);

Since
  1.4.0

## ◆ H5Pregister2()

herr_t H5Pregister2 | ( | hid_t | cls_id,
|  | const char * | name,
|  | size_t | size,
|  | void * | def_value,
|  | H5P_prp_create_func_t | create,
|  | H5P_prp_set_func_t | set,
|  | H5P_prp_get_func_t | get,
|  | H5P_prp_delete_func_t | prp_del,
|  | H5P_prp_copy_func_t | copy,
|  | H5P_prp_compare_func_t | compare,
|  | H5P_prp_close_func_t | close )

Registers a permanent property with a property list class.

Parameters

  [in] | cls_id | Property list class identifier
  [in] | name | Name of property to register
  [in] | size | Size of property in bytes
  [in] | def_value | Default value for property in newly created property lists
  [in] | create | Callback routine called when a property list is being created and the property value will be initialized
  [in] | set | Callback routine called before a new value is copied into the property's value
  [in] | get | Callback routine called when a property value is retrieved from the property
  [in] | prp_del | Callback routine called when a property is deleted from a property list
  [in] | copy | Callback routine called when a property is copied from a property list
  [in] | compare | Callback routine called when a property is compared with another property list
  [in] | close | Callback routine called when a property list is being closed and the property value will be disposed of

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

H5Pregister2() registers a new property with a property list class. The `cls_id` identifier can be obtained by calling H5Pcreate_class(). The property will exist in all property list objects of `cl_id` created after this routine finishes. The name of the property must not already exist, or this routine will fail. The default property value must be provided and all new property lists created with this property will have the property value set to the default value. Any of the callback routines may be set to NULL if they are not needed.

Zero-sized properties are allowed and do not store any data in the property list. These may be used as flags to indicate the presence or absence of a particular piece of information. The default pointer for a zero-sized property may be set to NULL. The property `create` and `close` callbacks are called for zero-sized properties, but the `set` and `get` callbacks are never called.

The `create` routine is called when a new property list with this property is being created. The H5P_prp_create_func_t callback function is defined as follows:

typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value);

The parameters to this callback function are defined as follows:

`const char * name` | IN: The name of the property being modified
`size_t size` | IN: The size of the property in bytes
`void * value` | IN/OUT: The default value for the property being created, which will be passed to H5Pregister2()

The `create` routine may modify the value to be set and those changes will be stored as the initial value of the property. If the `create` routine returns a negative value, the new property value is not copied into the property and the `create` routine returns an error value.

The `set` routine is called before a new value is copied into the property. The H5P_prp_set_func_t callback function is defined as follows:

typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value);

The parameters to this callback function are defined as follows:

hid_t `prop_id` | IN: The identifier of the property list being modified
`const char * name` | IN: The name of the property being modified
`size_t size` | IN: The size of the property in bytes
`void *value` | IN/OUT: Pointer to new value pointer for the property being modified

The `set` routine may modify the value pointer to be set and those changes will be used when setting the property's value. If the `set` routine returns a negative value, the new property value is not copied into the property and the `set` routine returns an error value. The `set` routine will not be called for the initial value; only the `create` routine will be called.

Note: The `set` callback function may be useful to range check the value being set for the property or may perform some transformation or translation of the value set. The `get` callback would then reverse the transformation or translation. A single `get` or `set` callback could handle multiple properties by performing different actions based on the property name or other properties in the property list.

The `get` routine is called when a value is retrieved from a property value. The H5P_prp_get_func_t callback function is defined as follows:

typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value);

The parameters to the callback function are defined as follows:

hid_t `prop_id` | IN: The identifier of the property list being queried
`const char * name` | IN: The name of the property being queried
`size_t size` | IN: The size of the property in bytes
`void * value` | IN/OUT: The value of the property being returned

The `get` routine may modify the value to be returned from the query and those changes will be returned to the calling routine. If the `set` routine returns a negative value, the query routine returns an error value.

The `prp_del` routine is called when a property is being deleted from a property list. The H5P_prp_delete_func_t callback function is defined as follows:

typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value);

The parameters to the callback function are defined as follows:

hid_t `prop_id` | IN: The identifier of the property list the property is being deleted from
`const char * name` | IN: The name of the property in the list
`size_t size` | IN: The size of the property in bytes
`void * value` | IN: The value for the property being deleted

The `prp_del` routine may modify the value passed in, but the value is not used by the library when the `prp_del` routine returns. If the `prp_del` routine returns a negative value, the property list delete routine returns an error value but the property is still deleted.

The `copy` routine is called when a new property list with this property is being created through a `copy` operation. The H5P_prp_copy_func_t callback function is defined as follows:

typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value);

The parameters to the callback function are defined as follows:

`const char * name` | IN: The name of the property being copied
`size_t size` | IN: The size of the property in bytes
`void * value` | IN/OUT: The value for the property being copied

The `copy` routine may modify the value to be set and those changes will be stored as the new value of the property. If the `copy` routine returns a negative value, the new property value is not copied into the property and the `copy` routine returns an error value.

The `compare` routine is called when a property list with this property is compared to another property list with the same property. The H5P_prp_compare_func_t callback function is defined as follows:

typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size);

The parameters to the callback function are defined as follows:

`const void * value1` | IN: The value of the first property to compare
`const void * value2` | IN: The value of the second property to compare
`size_t size` | IN: The size of the property in bytes

The `compare` routine may not modify the values. The `compare` routine should return a positive value if `value1` is greater than `value2`, a negative value if `value2` is greater than `value1` and zero if `value1` and `value2` are equal.

The `close` routine is called when a property list with this property is being closed. The H5P_prp_close_func_t callback function is defined as follows:

typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value);

The parameters to the callback function are defined as follows:

`const char * name` | IN: The name of the property in the list
`size_t size` | IN: The size of the property in bytes
`void * value` | IN: The value for the property being closed

The `close` routine may modify the value passed in, but the value is not used by the library when the `close` routine returns. If the `close` routine returns a negative value, the property list close routine returns an error value but the property list is still closed.

Since
  1.8.0

## ◆ H5Premove()

herr_t H5Premove | ( | hid_t | plist_id,
|  | const char * | name )

Removes a property from a property list.

Parameters

  [in] | plist_id | Property list identifier
  [in] | name | Name of property to remove

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

H5Premove() removes a property from a property list. Both properties which were in existence when the property list was created (i.e. properties registered with H5Pregister()) and properties added to the list after it was created (i.e. added with H5Pinsert1() may be removed from a property list. Properties do not need to be removed from a property list before the list itself is closed; they will be released automatically when H5Pclose() is called.

If a `close` callback exists for the removed property, it will be called before the property is released.

Since
  1.4.0

## ◆ H5Pset()

herr_t H5Pset | ( | hid_t | plist_id,
|  | const char * | name,
|  | const void * | value )

Sets a property list value.

Parameters

  [in] | plist_id | Property list identifier
  [in] | name | Name of property to modify
  [in] | value | Pointer to value to set the property to

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

H5Pset() sets a new value for a property in a property list. If there is a `set` callback routine registered for this property, the `value` will be passed to that routine and any changes to the `value` will be used when setting the property value. The information pointed to by the `value` pointer (possibly modified by the `set` callback) is copied into the property list value and may be changed by the application making the H5Pset() call without affecting the property value.

The property name must exist or this routine will fail.

If the `set` callback routine returns an error, the property value will not be modified.

This routine may not be called for zero-sized properties and will return an error in that case.

Since
  1.4.0

## ◆ H5Punregister()

herr_t H5Punregister | ( | hid_t | pclass_id,
|  | const char * | name )

Removes a property from a property list class.

Parameters

  [in] | pclass_id | Property list class identifier
  [in] | name | Name of property to remove

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

H5Punregister() removes a property from a property list class. Future property lists created of that class will not contain this property; existing property lists containing this property are not affected.

Since
  1.4.0