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

Detailed Description

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

CreateRead
15  {
16  __label__ fail_dcpl;
17  hid_t dcpl;
18 
19  // every property list is created as an instance of a suitable
20  // property list class
21  if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) {
22  ret_val = EXIT_FAILURE;
23  goto fail_dcpl;
24  }
25 
26  // ...
27 
28  H5Pclose(dcpl);
29 fail_dcpl:;
30  }
int64_t hid_t
Definition: H5Ipublic.h:62
#define H5I_INVALID_HID
Definition: H5Ipublic.h:77
#define H5P_DATASET_CREATE
Definition: H5Ppublic.h:57
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.
34  {
35  __label__ fail_dcpl, fail_plist_cls_id;
36  hid_t dcpl, plist_cls_id;
37 
38  if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) {
39  ret_val = EXIT_FAILURE;
40  goto fail_dcpl;
41  }
42  // to perform introspection on any kind of property list,
43  // we need to determine its property list class by obtaining a handle
44  if ((plist_cls_id = H5Pget_class(dcpl)) == H5I_INVALID_HID) {
45  ret_val = EXIT_FAILURE;
46  goto fail_plist_cls_id;
47  }
48  // Compare the handle to the handles of built-in or user-defined
49  // property list classes
50  assert(H5Pequal(plist_cls_id, H5P_DATASET_CREATE) > 0);
51 
52 fail_plist_cls_id:
53  H5Pclose(dcpl);
54 fail_dcpl:;
55  }
htri_t H5Pequal(hid_t id1, hid_t id2)
Compares two property lists or classes for equality.
hid_t H5Pget_class(hid_t plist_id)
Returns the property list class identifier for a property list.
UpdateDelete
59  {
60  __label__ fail_dcpl, fail_prop;
61  hid_t dcpl;
62 
63  if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) {
64  ret_val = EXIT_FAILURE;
65  goto fail_dcpl;
66  }
67 
68  // a property list is updated by adding (or removing) properties
69  if (H5Pset_fill_time(dcpl, H5D_FILL_TIME_NEVER) < 0) {
70  ret_val = EXIT_FAILURE;
71  goto fail_prop;
72  }
73 
74 fail_prop:
75  H5Pclose(dcpl);
76 fail_dcpl:;
77  }
@ H5D_FILL_TIME_NEVER
Definition: H5Dpublic.h:107
herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time)
Sets the time when fill values are written to a dataset.
81  {
82  __label__ fail_dcpl;
83  hid_t dcpl;
84 
85  if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) {
86  ret_val = EXIT_FAILURE;
87  goto fail_dcpl;
88  }
89 
90  // a property list is "deleted" by closing it
91  H5Pclose(dcpl);
92 fail_dcpl:;
93  }

Functions

herr_t H5Pclose (hid_t plist_id)
 Terminates access to a property list. More...
 
hid_t H5Pcopy (hid_t plist_id)
 Copies an existing property list to create a new property list. More...
 
hid_t H5Pcreate (hid_t cls_id)
 Creates a new property list as an instance of a property list class. More...
 
hid_t H5Pdecode (const void *buf)
 Decodes property list received in a binary object buffer and returns a new property list identifier. More...
 
herr_t H5Pencode2 (hid_t plist_id, void *buf, size_t *nalloc, hid_t fapl_id)
 Encodes the property values in a property list into a binary buffer. More...
 
hid_t H5Pget_class (hid_t plist_id)
 Returns the property list class identifier for 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()

herr_t H5Pclose ( hid_t  plist_id)

Terminates access to a property list.

Parameters
[in]plist_idProperty list identifier
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

H5Pclose() terminates access to a property list. All property lists should be closed when the application is finished accessing them. This frees resources used by the property list.

Since
1.0.0

◆ H5Pcopy()

hid_t H5Pcopy ( hid_t  plist_id)

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

Parameters
[in]plist_idProperty list identifier
Returns
Returns a property list identifier if successful; otherwise returns H5I_INVALID_HID.

H5Pcopy() copies an existing property list to create a new property list. The new property list has the same properties and values as the original property list.

Since
1.0.0

◆ H5Pcreate()

hid_t H5Pcreate ( hid_t  cls_id)

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

Parameters
[in]cls_idProperty list class identifier
Returns
Returns a property list identifier if successful; otherwise returns H5I_INVALID_HID.

H5Pcreate() creates a new property list as an instance of some property list class. The new property list is initialized with default values for the specified class. The classes are as follows:

Class Identifier Class Name Comments
H5P_ATTRIBUTE_CREATE attribute create Properties for attribute creation
H5P_DATASET_ACCESS dataset access Properties for dataset access
H5P_DATASET_CREATE dataset create Properties for dataset creation
H5P_DATASET_XFER data transfer Properties for raw data transfer
H5P_DATATYPE_ACCESS datatype access Properties for datatype access
H5P_DATATYPE_CREATE datatype create Properties for datatype creation
H5P_FILE_ACCESS file access Properties for file access
H5P_FILE_CREATE file create Properties for file creation
H5P_FILE_MOUNT file mount Properties for file mounting
H5P_GROUP_ACCESS group access Properties for group access
H5P_GROUP_CREATE group create Properties for group creation
H5P_LINK_ACCESS link access Properties governing link traversal when accessing objects
H5P_LINK_CREATE link create Properties governing link creation
H5P_OBJECT_COPY object copy Properties governing the object copying process
H5P_OBJECT_CREATE object create Properties for object creation
H5P_STRING_CREATE string create Properties for character encoding when encoding strings or object names
H5P_VOL_INITIALIZE vol initialize Properties for VOL initialization

This property list must eventually be closed with H5Pclose(); otherwise, errors are likely to occur.

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

◆ H5Pdecode()

hid_t H5Pdecode ( const void *  buf)

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

Parameters
[in]bufBuffer holding the encoded property list
Returns
Returns an object identifier if successful; otherwise returns a negative value.

Given a binary property list description in a buffer, H5Pdecode() reconstructs the HDF5 property list and returns an identifier for the new property list. The binary description of the property list is encoded by H5Pencode().

The user is responsible for passing in the correct buffer.

The property list identifier returned by this function should be released with H5Pclose() when the identifier is no longer needed so that resource leaks will not develop.

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

◆ 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

◆ H5Pencode2()

herr_t H5Pencode2 ( hid_t  plist_id,
void *  buf,
size_t *  nalloc,
hid_t  fapl_id 
)

Encodes the property values in a property list into a binary buffer.

Parameters
[in]plist_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
[in]fapl_idFile access property list identifier
Returns
Returns a non-negative value if successful; otherwise returns a negative value.

H5Pencode2() encodes the property list plist_id into the binary buffer buf, according to the file format setting specified by the file access property list fapl_id.

If the required buffer size is unknown, buf can be passed in as NULL and the function will set the required buffer size in nalloc. The buffer can then be created and the property list encoded with a subsequent H5Pencode2() call.

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

The file access property list fapl_id is used to control the encoding via the libver_bounds property (see H5Pset_libver_bounds()). If the libver_bounds property is missing, H5Pencode2() proceeds as if the libver_bounds property were set to (H5F_LIBVER_EARLIEST, H5F_LIBVER_LATEST). (Functionally, H5Pencode1() is identical to H5Pencode2() with libver_bounds set to (H5F_LIBVER_EARLIEST, H5F_LIBVER_LATEST).) Properties that do not have encode callbacks will be skipped. There is currently no mechanism to register an encode callback for a user-defined property, so user-defined properties cannot currently be encoded.

Some properties cannot be encoded, particularly properties that are reliant on local context.

Motivation: This function was introduced in HDF5-1.12 as part of the H5Sencode format change to enable 64-bit selection encodings and a dataspace selection that is tied to a file.

Since
1.12.0

◆ H5Pget_class()

hid_t H5Pget_class ( hid_t  plist_id)

Returns the property list class identifier for a property list.

Parameters
[in]plist_idProperty list identifier
Returns
Returns a property list class identifier if successful; otherwise returns H5I_INVALID_HID.

H5Pget_class() returns the property list class identifier for the property list identified by the plist_id parameter.

Note that H5Pget_class() returns a value of hid_t type, an internal HDF5 identifier, rather than directly returning a property list class. That identifier can then be used with either H5Pequal() or H5Pget_class_name() to determine which predefined HDF5 property list class H5Pget_class() has returned.

A full list of valid predefined property list classes appears in the description of H5Pcreate().

Determining the HDF5 property list class name with H5Pequal() requires a series of H5Pequal() calls in an if-else sequence. An iterative sequence of H5Pequal() calls can compare the identifier returned by H5Pget_class() to members of the list of valid property list class names. A pseudo-code snippet might read as follows:

plist_class_id = H5Pget_class (dsetA_plist);
if H5Pequal (plist_class_id, H5P_OBJECT_CREATE) = TRUE;
[ H5P_OBJECT_CREATE is the property list class ]
[ returned by H5Pget_class. ]
else if H5Pequal (plist_class_id, H5P_DATASET_CREATE) = TRUE;
[ H5P_DATASET_CREATE is the property list class. ]
else if H5Pequal (plist_class_id, H5P_DATASET_XFER) = TRUE;
[ H5P_DATASET_XFER is the property list class. ]
.
. [ Continuing the iteration until a match is found. ]
.
#define H5P_OBJECT_CREATE
Definition: H5Ppublic.h:54
#define H5P_DATASET_XFER
Definition: H5Ppublic.h:59

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

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

Note that frequent use of H5Pget_class_name() can become a performance problem in a high-performance environment. The H5Pequal() approach is generally much faster.

Version
1.6.0 Return type changed in this release.
Since
1.0.0