Please, help us to better know about our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5  1.10.9-1
C-API Reference
General Property List Operations (Advanced)

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.

Create

Read

97  {
98  __label__ fail_cls, fail_prop;
99  hid_t plist_cls, plist;
100  int izero = 0;
101  double dzero = 0.0;
102 
103  // create a new property list class
104  if ((plist_cls = H5Pcreate_class(H5P_ROOT, "int & double", NULL, NULL, NULL, NULL, NULL, NULL)) ==
105  H5I_INVALID_HID) {
106  ret_val = EXIT_FAILURE;
107  goto fail_cls;
108  }
109  // add a permanent integer property
110  if (H5Pregister2(plist_cls, "int", sizeof(int), &izero, NULL, NULL, NULL, NULL, NULL, NULL, NULL) <
111  0) {
112  ret_val = EXIT_FAILURE;
113  goto fail_prop;
114  }
115  // add a permanent double property
116  if (H5Pregister2(plist_cls, "double", sizeof(double), &dzero, NULL, NULL, NULL, NULL, NULL, NULL,
117  NULL) < 0) {
118  ret_val = EXIT_FAILURE;
119  goto fail_prop;
120  }
121  // create an instance of this user-defined property list class
122  if ((plist = H5Pcreate(plist_cls)) < 0) {
123  ret_val = EXIT_FAILURE;
124  goto fail_prop;
125  }
126 
127  // ...
128 
129  H5Pclose(plist);
130 fail_prop:
131  H5Pclose_class(plist_cls);
132 fail_cls:;
133  }
int64_t hid_t
Definition: H5Ipublic.h:62
#define H5I_INVALID_HID
Definition: H5Ipublic.h:72
#define H5P_ROOT
Definition: H5Ppublic.h:53
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 H5Pclose_class(hid_t plist_id)
Closes an existing 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 H5Pclose(hid_t plist_id)
Terminates access to a property list.
hid_t H5Pcreate(hid_t cls_id)
Creates a new property list as an instance of a property list class.
137  {
138  __label__ fail_cls, fail_prop, fail_plist;
139  hid_t plist_cls, plist;
140  size_t nprops;
141 
142  if ((plist_cls = H5Pcreate_class(H5P_ROOT, "ud_plist", NULL, NULL, NULL, NULL, NULL, NULL)) ==
143  H5I_INVALID_HID) {
144  ret_val = EXIT_FAILURE;
145  goto fail_cls;
146  }
147  if ((plist = H5Pcreate(plist_cls)) < 0) {
148  ret_val = EXIT_FAILURE;
149  goto fail_prop;
150  }
151  if (H5Pinsert2(plist, "temp", 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL) < 0) {
152  ret_val = EXIT_FAILURE;
153  goto fail_plist;
154  }
155  // count the registered properties of this class
156  if (H5Pget_nprops(plist_cls, &nprops) < 0) {
157  ret_val = EXIT_FAILURE;
158  goto fail_plist;
159  }
160  // this will be 0 as there are no registered properties
161  printf("Property list class has %lu registered properties.\n", nprops);
162 
163  // count the properties in this property list
164  if (H5Pget_nprops(plist, &nprops) < 0) {
165  ret_val = EXIT_FAILURE;
166  goto fail_plist;
167  }
168  // will be 1 as there is one temporary property
169  printf("Property list has %lu property.\n", nprops);
170 
171 fail_plist:
172  H5Pclose(plist);
173 fail_prop:
174  H5Pclose_class(plist_cls);
175 fail_cls:;
176  }
herr_t H5Pget_nprops(hid_t id, size_t *nprops)
Queries the number of properties in a property list or class.
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.
UpdateDelete
180  {
181  __label__ fail_cls, fail_prop, fail_plist;
182  hid_t plist_cls, plist;
183 
184  if ((plist_cls = H5Pcreate_class(H5P_ROOT, "ud_plist", NULL, NULL, NULL, NULL, NULL, NULL)) ==
185  H5I_INVALID_HID) {
186  ret_val = EXIT_FAILURE;
187  goto fail_cls;
188  }
189  // create an instance of this user-defined property list class
190  if ((plist = H5Pcreate(plist_cls)) < 0) {
191  ret_val = EXIT_FAILURE;
192  goto fail_prop;
193  }
194  // insert a temporary property
195  if (H5Pinsert2(plist, "temp", 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL) < 0) {
196  ret_val = EXIT_FAILURE;
197  goto fail_plist;
198  }
199 
200 fail_plist:
201  H5Pclose(plist);
202 fail_prop:
203  H5Pclose_class(plist_cls);
204 fail_cls:;
205  }
209  {
210  __label__ fail_cls;
211  hid_t plist_cls;
212 
213  if ((plist_cls = H5Pcreate_class(H5P_ROOT, "int & double", NULL, NULL, NULL, NULL, NULL, NULL)) ==
214  H5I_INVALID_HID) {
215  ret_val = EXIT_FAILURE;
216  goto fail_cls;
217  }
218  // ...
219 
220  // a user defined property list class is destroyed by closing the handle
221  H5Pclose_class(plist_cls);
222 fail_cls:;
223  }

Functions

herr_t H5Pclose_class (hid_t plist_id)
 Closes an existing property list class. More...
 
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. More...
 
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. More...
 
htri_t H5Pequal (hid_t id1, hid_t id2)
 Compares two property lists or classes for equality. More...
 
htri_t H5Pexist (hid_t plist_id, const char *name)
 Queries whether a property name exists in a property list or class. More...
 
herr_t H5Pget (hid_t plist_id, const char *name, void *value)
 Queries the value of a property. More...
 
char * H5Pget_class_name (hid_t pclass_id)
 Retrieves the name of a class. More...
 
hid_t H5Pget_class_parent (hid_t pclass_id)
 Retrieves the parent class of a property class. More...
 
herr_t H5Pget_nprops (hid_t id, size_t *nprops)
 Queries the number of properties in a property list or class. More...
 
herr_t H5Pget_size (hid_t id, const char *name, size_t *size)
 Queries the size of a property value in bytes. More...
 
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. More...
 
htri_t H5Pisa_class (hid_t plist_id, hid_t pclass_id)
 Determines whether a property list is a member of a class. More...
 
int H5Piterate (hid_t id, int *idx, H5P_iterate_t iter_func, void *iter_data)
 Iterates over properties in a property class or list. More...
 
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. More...
 
herr_t H5Premove (hid_t plist_id, const char *name)
 Removes a property from a property list. More...
 
herr_t H5Pset (hid_t plist_id, const char *name, const void *value)
 Sets a property list value. More...
 
herr_t H5Punregister (hid_t pclass_id, const char *name)
 Removes a property from a property list class. More...
 
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. More...
 
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. More...
 

Function Documentation

◆ H5Pclose_class()

herr_t H5Pclose_class ( hid_t  plist_id)

Closes an existing property list class.

Parameters
[in]plist_idProperty 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_idIdentifier of the destination property list or class
[in]src_idIdentifier of the source property list or class
[in]nameName 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]parentProperty list class identifier
[in]nameName of property list class to register
[in]createCallback routine called when a property list is created
[in]create_dataPointer to user-defined class create data, to be passed along to class create callback
[in]copyCallback routine called when a property list is copied
[in]copy_dataPointer to user-defined class copy data, to be passed along to class copy callback
[in]closeCallback routine called when a property list is being closed
[in]close_dataPointer 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 routine is called when a new property list of this class is being created. The H5P_cls_create_func_t callback function is defined as follows:

typedef herr_t (*H5P_cls_create_func_t)(hid_t prop_id, void *create_data);
herr_t(* H5P_cls_create_func_t)(hid_t prop_id, void *create_data)
Definition: H5Ppublic.h:113
int herr_t
Definition: H5public.h:208

The parameters to this callback function are defined as follows:

hid_t prop_id IN: The identifier of the property list being created
void * create_data IN: User pointer to any class creation data required

The create routine is called after any registered create function is called for each property value. If the create routine returns a negative value, the new list is not returned to the user and the property list creation routine returns an error value.

The copy routine is called when an existing property list of this class is copied. The H5P_cls_copy_func_t callback function is defined as follows:

typedef herr_t (*H5P_cls_copy_func_t)(hid_t new_prop_id, hid_t old_prop_id, void *copy_data);
herr_t(* H5P_cls_copy_func_t)(hid_t new_prop_id, hid_t old_prop_id, void *copy_data)
Definition: H5Ppublic.h:120

The parameters to this callback function are defined as follows:

hid_t prop_id IN: The identifier of the property list created by copying
void * copy_data IN: User pointer to any class copy data required

The copy routine is called after any registered copy function is called for each property value. If the copy routine returns a negative value, the new list is not returned to the user and the property list copy routine returns an error value.

The close routine is called when a property list of this class is being closed. The H5P_cls_close_func_t callback function is defined as follows:

typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data);
herr_t(* H5P_cls_close_func_t)(hid_t prop_id, void *close_data)
Definition: H5Ppublic.h:127

The parameters to this callback function are defined as follows:

hid_t prop_id IN: The identifier of the property list being closed
void * close_data IN: User pointer to any class close data required

The close routine is called before any registered close function is called for each property value. If the close routine returns a negative value, the property list close routine returns an error value but the property list is still closed.

H5Pclose_class() can be used to release the property list class identifier returned by this function so that resources leaks will not develop.

Since
1.4.0

◆ H5Pequal()

htri_t H5Pequal ( hid_t  id1,
hid_t  id2 
)

Compares two property lists or classes for equality.

Parameters
[in]id1First property object to be compared
[in]id2Second 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_idIdentifier for the property list or class to query
[in]nameName 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_idProperty list identifier
[in]nameName of property to query
[out]valuePointer 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_idProperty 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_idProperty 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]idIdentifier for property object to query
[out]npropsNumber 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]idIdentifier of property object to query
[in]nameName of property to query
[out]sizeSize 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_idProperty list identifier
[in]nameName of property to create
[in]sizeSize of property in bytes
[in]valueInitial value for the property
[in]prp_setCallback routine called before a new value is copied into the property's value
[in]prp_getCallback routine called when a property value is retrieved from the property
[in]prp_deleteCallback routine called when a property is deleted from a property list
[in]prp_copyCallback routine called when a property is copied from an existing property list
[in]prp_closeCallback 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);
herr_t(* H5P_prp_cb1_t)(const char *name, size_t size, void *value)
Callback function for H5Pregister2(),H5Pregister1(),H5Pinsert2(),H5Pinsert1()
Definition: H5Ppublic.h:143

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);
herr_t(* H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value)
Callback function for H5Pregister2(),H5Pregister1(),H5Pinsert2(),H5Pinsert1()
Definition: H5Ppublic.h:159

◆ 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_idProperty list identifier
[in]nameName of property to create
[in]sizeSize of property in bytes
[in]valueInitial value for the property
[in]setCallback routine called before a new value is copied into the property's value
[in]getCallback routine called when a property value is retrieved from the property
[in]prp_delCallback routine called when a property is deleted from a property list
[in]copyCallback routine called when a property is copied from an existing property list
[in]compareCallback routine called when a property is compared with another property list
[in]closeCallback 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);
int(* H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size)
Definition: H5Ppublic.h:172

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_idProperty list identifier
[in]pclass_idProperty 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]idIdentifier of property object to iterate over
[in,out]idxIndex of the property to begin with
[in]iter_funcFunction pointer to function to be called with each property iterated over
[in,out]iter_dataPointer 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 prototype for the H5P_iterate_t operator is as follows:

typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data);
herr_t(* H5P_iterate_t)(hid_t id, const char *name, void *iter_data)
Definition: H5Ppublic.h:182

The operation 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. The valid return values from an operator are as follows:

Zero Causes the iterator to continue, returning zero when all properties have been processed
Positive Causes the iterator to immediately return that positive value, indicating short-circuit success. The iterator can be restarted at the index of the next property
Negative Causes the iterator to immediately return that value, indicating failure. The iterator can be restarted at the index of the next property

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_idProperty list class identifier
[in]nameName of property to register
[in]sizeSize of property in bytes
[in]def_valueDefault value for property in newly created property lists
[in]prp_createCallback routine called when a property list is being created and the property value will be initialized
[in]prp_setCallback routine called before a new value is copied into the property's value
[in]prp_getCallback routine called when a property value is retrieved from the property
[in]prp_delCallback routine called when a property is deleted from a property list
[in]prp_copyCallback routine called when a property is copied from a property list
[in]prp_closeCallback 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);

◆ 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_idProperty list class identifier
[in]nameName of property to register
[in]sizeSize of property in bytes
[in]def_valueDefault value for property in newly created property lists
[in]createCallback routine called when a property list is being created and the property value will be initialized
[in]setCallback routine called before a new value is copied into the property's value
[in]getCallback routine called when a property value is retrieved from the property
[in]prp_delCallback routine called when a property is deleted from a property list
[in]copyCallback routine called when a property is copied from a property list
[in]compareCallback routine called when a property is compared with another property list
[in]closeCallback 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_idProperty list identifier
[in]nameName 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_idProperty list identifier
[in]nameName of property to modify
[in]valuePointer 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_idProperty list class identifier
[in]nameName 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