Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5  1.15.0.f39b228
API Reference
Property List Class Root (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.

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

+ Collaboration diagram for Property List Class Root (Advanced):

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...
 
herr_t H5Pencode1 (hid_t plist_id, void *buf, size_t *nalloc)
 Encodes the property values in a property list into a binary buffer. 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, 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_idProperty list identifier
[out]bufBuffer 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]nallocThe 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]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:196
int herr_t
Definition: H5public.h:235

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);
int64_t hid_t
Definition: H5Ipublic.h:60
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:212

◆ 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)
Callback function for comparing property values.
Definition: H5Ppublic.h:261

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 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_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