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
Modules | Functions
H5I

Detailed Description

Use the functions in this module to manage identifiers defined by the HDF5 library. See User-defined ID Types for user-defined identifiers and identifier types.

HDF5 identifiers are usually created as a side-effect of creating HDF5 entities such as groups, datasets, attributes, or property lists.

Identifiers defined by the HDF5 library can be used to retrieve information such as path names and reference counts, and their validity can be checked.

Identifiers can be updated by manipulating their reference counts.

Unused identifiers should be reclaimed by closing the associated item, e.g., HDF5 object, or decrementing the reference count to 0.

Note
Identifiers (of type hid_t) are run-time auxiliaries and not persisted in the file.
CreateRead
15  {
16  __label__ fail_dcpl;
17  hid_t dcpl;
18 
19  // create an ID of a pre-defined ID type
20  if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) {
21  ret_val = EXIT_FAILURE;
22  goto fail_dcpl;
23  }
24 
25  // we can reliably predict the ID type
26  assert(H5Iget_type(dcpl) == H5I_GENPROP_LST);
27  printf("%d\n", H5Iget_type(dcpl));
28 
29  H5Pclose(dcpl);
30 fail_dcpl:;
31  }
hid_t
int64_t hid_t
Definition: H5Ipublic.h:62
H5I_INVALID_HID
#define H5I_INVALID_HID
Definition: H5Ipublic.h:72
H5I_GENPROP_LST
@ H5I_GENPROP_LST
Definition: H5Ipublic.h:51
H5P_DATASET_XFER
#define H5P_DATASET_XFER
Definition: H5Ppublic.h:59
H5Pclose
herr_t H5Pclose(hid_t plist_id)
Terminates access to a property list.
H5Pcreate
hid_t H5Pcreate(hid_t cls_id)
Creates a new property list as an instance of a property list class.
H5Iget_type
H5I_type_t H5Iget_type(hid_t id)
Retrieves the type of an object.
35  {
36  __label__ fail_dcpl;
37  hid_t dcpl;
38 
39  // create an ID of a pre-defined ID type
40  if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) {
41  ret_val = EXIT_FAILURE;
42  goto fail_dcpl;
43  }
44 
45  // this better be valid
46  assert(H5Iis_valid(dcpl) > 0);
47 
48  // this ID is NOT associated with any HDF5 file;
49  // see the error message
50  assert(H5Iget_file_id(dcpl) == H5I_INVALID_HID);
51 
52  H5Pclose(dcpl);
53 fail_dcpl:;
54  }
H5Iis_valid
htri_t H5Iis_valid(hid_t id)
Determines whether an identifier is valid.
H5Iget_file_id
hid_t H5Iget_file_id(hid_t id)
Retrieves an identifier for the file containing the specified object.
UpdateDelete
58  {
59  __label__ fail_rc, fail_dcpl;
60  hid_t dcpl;
61  int rc;
62 
63  // create an ID of a pre-defined ID type
64  if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) {
65  ret_val = EXIT_FAILURE;
66  goto fail_dcpl;
67  }
68 
69  // retrieve the IDs reference count
70  if ((rc = H5Iget_ref(dcpl)) < 0) {
71  ret_val = EXIT_FAILURE;
72  goto fail_rc;
73  }
74  printf("Reference count: %d\n", rc);
75 
76  // bump its reference count (by 1)
77  if ((rc = H5Iinc_ref(dcpl)) < 0) {
78  ret_val = EXIT_FAILURE;
79  goto fail_rc;
80  }
81  printf("Reference count: %d\n", rc);
82 
83 fail_rc:
84  H5Pclose(dcpl);
85 fail_dcpl:;
86  }
H5Iinc_ref
int H5Iinc_ref(hid_t id)
Increments the reference count for an object.
H5Iget_ref
int H5Iget_ref(hid_t id)
Retrieves the reference count for an object.
90  {
91  __label__ fail_rc, fail_dcpl;
92  hid_t dcpl;
93  int rc;
94 
95  // create an ID of a pre-defined ID type
96  if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) {
97  ret_val = EXIT_FAILURE;
98  goto fail_dcpl;
99  }
100 
101  // decrease its reference count (from 1) to 0
102  if ((rc = H5Idec_ref(dcpl)) < 0) {
103  ret_val = EXIT_FAILURE;
104  goto fail_rc;
105  }
106  printf("Reference count: %d\n", rc);
107 
108  // at this point, the ID is no longer valid
109  assert(H5Iis_valid(dcpl) == 0);
110 
111  // dropping the ref. count to 0 has the side-effect of closing
112  // the associated item, and calling H5Pclose would create an error
113  goto fail_dcpl;
114 
115 fail_rc:
116  H5Pclose(dcpl);
117 fail_dcpl:;
118  }
H5Idec_ref
int H5Idec_ref(hid_t id)
Decrements the reference count for an object.

Modules

 User-defined ID Types
 

Functions

H5I_type_t H5Iget_type (hid_t id)
 Retrieves the type of an object. More...
 
hid_t H5Iget_file_id (hid_t id)
 Retrieves an identifier for the file containing the specified object. More...
 
ssize_t H5Iget_name (hid_t id, char *name, size_t size)
 Retrieves a name of an object based on the object identifier. More...
 
int H5Iinc_ref (hid_t id)
 Increments the reference count for an object. More...
 
int H5Idec_ref (hid_t id)
 Decrements the reference count for an object. More...
 
int H5Iget_ref (hid_t id)
 Retrieves the reference count for an object. More...
 
htri_t H5Iis_valid (hid_t id)
 Determines whether an identifier is valid. More...
 

Function Documentation

◆ H5Idec_ref()

int H5Idec_ref ( hid_t  id)

Decrements the reference count for an object.

Parameters
[in]idObject identifier
Returns
Returns a non-negative reference count of the object ID after decrementing it, if successful; otherwise a negative value is returned.

H5Idec_ref() decrements the reference count of the object identified by id.

The reference count for an object ID is attached to the information about an object in memory and has no relation to the number of links to an object on disk.

The reference count for a newly created object will be 1. Reference counts for objects may be explicitly modified with this function or with H5Iinc_ref(). When an object identifier’s reference count reaches zero, the object will be closed. Calling an object identifier’s close function decrements the reference count for the identifier which normally closes the object, but if the reference count for the identifier has been incremented with H5Iinc_ref(), the object will only be closed when the reference count reaches zero with further calls to this function or the object identifier’s close function.

If the object ID was created by a collective parallel call (such as H5Dcreate(), H5Gopen(), etc.), the reference count should be modified by all the processes which have copies of the ID. Generally this means that group, dataset, attribute, file and named datatype IDs should be modified by all the processes and that all other types of IDs are safe to modify by individual processes.

This function is of particular value when an application is maintaining multiple copies of an object ID. The object ID can be incremented when a copy is made. Each copy of the ID can then be safely closed or decremented and the HDF5 object will be closed when the reference count for that that object drops to zero.

Since
1.6.2

◆ H5Iget_file_id()

hid_t H5Iget_file_id ( hid_t  id)

Retrieves an identifier for the file containing the specified object.

Parameters
[in]idObject identifier
Returns
Returns a file identifier if successful; otherwise returns H5I_INVALID_HID.

H5Iget_file_id() returns the identifier of the file associated with the object referenced by id.

Note
Note that the HDF5 library permits an application to close a file while objects within the file remain open. If the file containing the object id is still open, H5Iget_file_id() will retrieve the existing file identifier. If there is no existing file identifier for the file, i.e., the file has been closed, H5Iget_file_id() will reopen the file and return a new file identifier. In either case, the file identifier must eventually be released using H5Fclose().
Since
1.6.3

◆ H5Iget_name()

ssize_t H5Iget_name ( hid_t  id,
char *  name,
size_t  size 
)

Retrieves a name of an object based on the object identifier.

Parameters
[in]idObject identifier
[out]nameA buffer for thename associated with the identifier
[in]sizeThe size of the name buffer; usually the size of the name in bytes plus 1 for a NULL terminator
Returns
ssize_t

H5Iget_name() retrieves a name for the object identified by id.

Up to size characters of the name are returned in name; additional characters, if any, are not returned to the user application.

If the length of the name, which determines the required value of size, is unknown, a preliminary H5Iget_name() call can be made. The return value of this call will be the size in bytes of the object name. That value, plus 1 for a NULL terminator, is then assigned to size for a second H5Iget_name() call, which will retrieve the actual name.

If the object identified by id is an attribute, as determined via H5Iget_type(), H5Iget_name() retrieves the name of the object to which that attribute is attached. To retrieve the name of the attribute itself, use H5Aget_name().

If there is no name associated with the object identifier or if the name is NULL, H5Iget_name() returns 0 (zero).

Note
Note that an object in an HDF5 file may have multiple paths if there are multiple links pointing to it. This function may return any one of these paths. When possible, H5Iget_name() returns the path with which the object was opened.
Since
1.6.0

◆ H5Iget_ref()

int H5Iget_ref ( hid_t  id)

Retrieves the reference count for an object.

Parameters
[in]idObject identifier
Returns
Returns a non-negative current reference count of the object identifier if successful; otherwise a negative value is returned.

H5Iget_ref() retrieves the reference count of the object identified by id.

The reference count for an object identifier is attached to the information about an object in memory and has no relation to the number of links to an object on disk.

The function H5Iis_valid() is used to determine whether a specific object identifier is valid.

Since
1.6.2

◆ H5Iget_type()

H5I_type_t H5Iget_type ( hid_t  id)

Retrieves the type of an object.

Parameters
[in]idObject identifier
Returns
Returns the object type if successful; otherwise H5I_BADID.

H5Iget_type() retrieves the type of the object identified by id. If no valid type can be determined or the identifier submitted is invalid, the function returns H5I_BADID.

This function is of particular use in determining the type of object closing function (H5Dclose(), H5Gclose(), etc.) to call after a call to H5Rdereference().

Note
Note that this function returns only the type of object that id would identify if it were valid; it does not determine whether id is valid identifier. Validity can be determined with a call to H5Iis_valid().

◆ H5Iinc_ref()

int H5Iinc_ref ( hid_t  id)

Increments the reference count for an object.

Parameters
[in]idObject identifier
Returns
Returns a non-negative reference count of the object ID after incrementing it if successful; otherwise a negative value is returned.

H5Iinc_ref() increments the reference count of the object identified by id.

The reference count for an object ID is attached to the information about an object in memory and has no relation to the number of links to an object on disk.

The reference count for a newly created object will be 1. Reference counts for objects may be explicitly modified with this function or with H5Idec_ref(). When an object ID's reference count reaches zero, the object will be closed. Calling an object ID's close function decrements the reference count for the ID which normally closes the object, but if the reference count for the ID has been incremented with this function, the object will only be closed when the reference count reaches zero with further calls to H5Idec_ref() or the object ID's close function.

If the object ID was created by a collective parallel call (such as H5Dcreate(), H5Gopen(), etc.), the reference count should be modified by all the processes which have copies of the ID. Generally this means that group, dataset, attribute, file and named datatype IDs should be modified by all the processes and that all other types of IDs are safe to modify by individual processes.

This function is of particular value when an application is maintaining multiple copies of an object ID. The object ID can be incremented when a copy is made. Each copy of the ID can then be safely closed or decremented and the HDF5 object will be closed when the reference count for that that object drops to zero.

Since
1.6.2

◆ H5Iis_valid()

htri_t H5Iis_valid ( hid_t  id)

Determines whether an identifier is valid.

Parameters
[in]idObject identifier
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

H5Iis_valid() determines whether the identifier id is valid.

Valid identifiers are those that have been obtained by an application and can still be used to access the original target. Examples of invalid identifiers include:

  • Out of range values: negative, for example
  • Previously-valid identifiers that have been released: for example, a dataset identifier for which the dataset has been closed

H5Iis_valid() can be used with any type of identifier: object identifier, property list identifier, attribute identifier, error message identifier, etc. When necessary, a call to H5Iget_type() can determine the type of the object that id identifies.

Since
1.8.3