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

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
User-defined ID Types
Identifiers (H5I)

## Detailed Description

The Identifiers (H5I) module contains functions to define new identifier types. For convenience, handles of type hid_t can then be associated with the new identifier types and user objects.

New identifier types can be created by registering a new identifier type with the HDF5 library. Once a new identifier type has bee registered, it can be used to generate identifiers for user objects.

User-defined identifier types can be searched and iterated.

Like library-defined identifiers, user-defined identifiers and identifier types are reference counted, and the reference counts can be manipulated accordingly.

User-defined identifiers no longer in use should be deleted or reclaimed, and identifier types should be destroyed if they are no longer required.

Create | Read
--- | ---
122 herr_t free_func(void *obj) 123 { 124 printf("Calling free_func...\n"); 125 H5free_memory(obj); 126 return 0; 127 } 128 129 { 130 __label__ fail_id, fail_obj, fail_register; 131 H5I_type_t type; 132 int *obj; 133 hid_t obj_id; 134 135 // register a new ID type 136 if ((type = H5Iregister_type2(1024, &free_func)) < 0) { 137 ret_val = EXIT_FAILURE; 138 goto fail_register; 139 } 140 printf("New identifier type ID: %d\n", type); 141 142 // create a new object 143 if ((obj = H5allocate_memory(10 * sizeof(int), 0)) == NULL) { 144 ret_val = EXIT_FAILURE; 145 goto fail_obj; 146 } 147 148 // obtain an ID for the new object 149 if ((obj_id = H5Iregister(type, obj)) == H5I_INVALID_HID) { 150 ret_val = EXIT_FAILURE; 151 goto fail_id; 152 } 153 printf("New object identifier: %ld\n", obj_id); 154 155fail_id: 156 H5Iclear_type(type, 1); 157fail_obj: 158 H5Idestroy_type(type); 159fail_register:; 160 } | 164 { 165 __label__ fail_query, fail_register; 166 H5I_type_t type; 167 hsize_t count; 168 169 // register a new ID type 170 if ((type = H5Iregister_type2(1024, NULL)) < 0) { 171 ret_val = EXIT_FAILURE; 172 goto fail_register; 173 } 174 printf("New FOO identifier type ID: %d\n", type); 175 176 // return the number of identifiers of TYPE currently in use 177 if (H5Inmembers(type, &count) < 0) { 178 ret_val = EXIT_FAILURE; 179 goto fail_query; 180 } 181 printf("%llu FOO identifiers in use\n", count); 182 183fail_query: 184 H5Idestroy_type(type); 185fail_register:; 186 }
Update | Delete
190 { 191 __label__ fail_id, fail_register; 192 H5I_type_t type; 193 int obj = 42; 194 hid_t obj_id; 195 196 // register a new ID type 197 if ((type = H5Iregister_type2(1024, NULL)) < 0) { 198 ret_val = EXIT_FAILURE; 199 goto fail_register; 200 } 201 printf("New identifier type ID: %d\n", type); 202 203 // obtain an ID for the new object 204 if ((obj_id = H5Iregister(type, &obj)) == H5I_INVALID_HID) { 205 ret_val = EXIT_FAILURE; 206 goto fail_id; 207 } 208 printf("New object identifier: %ld\n", obj_id); 209 210 // bump the reference count 211 assert(H5Iinc_ref(obj_id) == 2); 212 213 // force the deletion of all IDs regardless of reference count 214 H5Iclear_type(type, 1); 215fail_id: 216 H5Idestroy_type(type); 217fail_register:; 218 } | 222 { 223 __label__ fail_register; 224 H5I_type_t type; 225 226 // register a new ID type 227 if ((type = H5Iregister_type2(1024, NULL)) < 0) { 228 ret_val = EXIT_FAILURE; 229 goto fail_register; 230 } 231 printf("New identifier type ID: %d\n", type); 232 233 // decrementing the identifier type's ref. count to 0 triggers 234 // the type to be destroyed 235 assert(H5Idec_type_ref(type) == 0); 236 237fail_register:; 238 }

## Functions
herr_t | H5Iclear_type (H5I_type_t type, bool force)
| Deletes all identifiers of the given type.
int | H5Idec_type_ref (H5I_type_t type)
| Decrements the reference count on an identifier type.
herr_t | H5Idestroy_type (H5I_type_t type)
| Removes an identifier type and all identifiers within that type.
int | H5Iget_type_ref (H5I_type_t type)
| Retrieves the reference count on an ID type.
int | H5Iinc_type_ref (H5I_type_t type)
| Increments the reference count on an ID type.
herr_t | H5Iiterate (H5I_type_t type, H5I_iterate_func_t op, void *op_data)
| Calls a callback for each member of the identifier type specified.
herr_t | H5Inmembers (H5I_type_t type, hsize_t *num_members)
| Returns the number of identifiers in a given identifier type.
void * | H5Iobject_verify (hid_t id, H5I_type_t type)
| Returns the object referenced by an ID.
hid_t | H5Iregister (H5I_type_t type, const void *object)
| Registers an object under a type and returns an ID for it.
H5I_type_t | H5Iregister_type1 (size_t hash_size, unsigned reserved, H5I_free_t free_func)
| Creates and returns a new ID type.
H5I_type_t | H5Iregister_type2 (unsigned reserved, H5I_free_t free_func)
| Creates and returns a new ID type.
void * | H5Iremove_verify (hid_t id, H5I_type_t type)
| Removes an ID from its type.
void * | H5Isearch (H5I_type_t type, H5I_search_func_t func, void *key)
| Finds the memory referred to by an ID within the given ID type such that some criterion is satisfied.
htri_t | H5Itype_exists (H5I_type_t type)
| Determines whether an identifier type is registered.

## Function Documentation

## ◆ H5Iclear_type()

herr_t H5Iclear_type | ( | H5I_type_t | type,
|  | bool | force )

Deletes all identifiers of the given type.

Parameters

  [in] | type | Identifier of identifier type which is to be cleared of identifiers
  [in] | force | Whether or not to force deletion of all identifiers

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

H5Iclear_type() deletes all identifiers of the type identified by the argument `type`.

The identifier type's free function is first called on all of these identifiers to free their memory, then they are removed from the type.

If the `force` flag is set to false, only those identifiers whose reference counts are equal to 1 will be deleted, and all other identifiers will be entirely unchanged. If the force flag is true, all identifiers of this type will be deleted.

Since
  1.8.0

## ◆ H5Idec_type_ref()

int H5Idec_type_ref | ( | H5I_type_t | type | ) |

Decrements the reference count on an identifier type.

Parameters

  [in] | type | The identifier of the type whose reference count is to be decremented

Returns
  Returns the current reference count on success, negative on failure.

H5Idec_type_ref() decrements the reference count on an identifier type. The reference count is used by the library to indicate when an identifier type can be destroyed. If the reference count reaches zero, this function will destroy it.

The type parameter is the identifier for the identifier type whose reference count is to be decremented. This identifier must have been created by a call to H5Iregister_type().

Since
  1.8.0

## ◆ H5Idestroy_type()

herr_t H5Idestroy_type | ( | H5I_type_t | type | ) |

Removes an identifier type and all identifiers within that type.

Parameters

  [in] | type | Identifier of identifier type which is to be destroyed

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

H5Idestroy_type deletes an entire identifier type `type`. All identifiers of this type are destroyed and no new identifiers of this type can be registered.

The type's free function is called on all of the identifiers which are deleted by this function, freeing their memory. In addition, all memory used by this type's hash table is freed.

Since the H5I_type_t values of destroyed identifier types are reused when new types are registered, it is a good idea to set the variable holding the value of the destroyed type to H5I_UNINIT.

Since
  1.8.0

## ◆ H5Iget_type_ref()

int H5Iget_type_ref | ( | H5I_type_t | type | ) |

Retrieves the reference count on an ID type.

Parameters

  [in] | type | The identifier of the type whose reference count is to be retrieved

Returns
  Returns the current reference count on success, negative on failure.

H5Iget_type_ref() retrieves the reference count on an ID type. The reference count is used by the library to indicate when an ID type can be destroyed.

The type parameter is the identifier for the ID type whose reference count is to be retrieved. This identifier must have been created by a call to H5Iregister_type().

Since
  1.8.0

## ◆ H5Iinc_type_ref()

int H5Iinc_type_ref | ( | H5I_type_t | type | ) |

Increments the reference count on an ID type.

Parameters

  [in] | type | The identifier of the type whose reference count is to be incremented

Returns
  Returns the current reference count on success, negative on failure.

H5Iinc_type_ref() increments the reference count on an ID type. The reference count is used by the library to indicate when an ID type can be destroyed.

The type parameter is the identifier for the ID type whose reference count is to be incremented. This identifier must have been created by a call to H5Iregister_type().

Since
  1.8.0

## ◆ H5Iiterate()

herr_t H5Iiterate | ( | H5I_type_t | type,
|  | H5I_iterate_func_t | op,
|  | void * | op_data )

Calls a callback for each member of the identifier type specified.

Parameters

  [in] | type | The identifier type
  [in] | op | The callback function
  [in,out] | op_data | The data for the callback function

Returns
  The last value returned by `op`

H5Iiterate() calls the callback function `op` for each member of the identifier type `type`. The callback function type for `op`, H5I_iterate_func_t, is defined in H5Ipublic.h as:

typedef herr_t (*H5I_iterate_func_t)(hid_t id, void *udata);

`op` takes as parameters the identifier and a pass through of `op_data`, and returns an herr_t.

A positive return from op will cause the iteration to stop and H5Iiterate() will return the value returned by `op`. A negative return from `op` will cause the iteration to stop and H5Iiterate() will return failure. A zero return from `op` will allow iteration to continue, as long as there are other identifiers remaining in type.

Warning
  Adding or removing members of the identifier type during iteration will lead to undefined behavior.

Attention
  Leaving callback functions:
  The callback function must return normally, even in the case of error. Returning with H5_ITER_ERROR, instead of leaving by means of exceptions, exit() function, etc... will allow the HDF5 library to manage its resources and maintain a consistent state. See C++ Developers using HDF5 C-API functions warning for detail.

Since
  1.12.0

## ◆ H5Inmembers()

herr_t H5Inmembers | ( | H5I_type_t | type,
|  | hsize_t * | num_members )

Returns the number of identifiers in a given identifier type.

Parameters

  [in] | type | The identifier type
  [out] | num_members | Number of identifiers of the specified identifier type

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

H5Inmembers() returns the number of identifiers of the identifier type specified in `type`.

The number of identifiers is returned in `num_members`. If no identifiers of this type have been registered, the type does not exist, or it has been destroyed, `num_members` is returned with the value 0.

Since
  1.8.0

## ◆ H5Iobject_verify()

void * H5Iobject_verify | ( | hid_t | id,
|  | H5I_type_t | type )

Returns the object referenced by an ID.

Parameters

  [in] | id | ID to be dereferenced
  [in] | type | The identifier type

Returns
  Pointer to the object referenced by `id` on success, NULL on failure.

H5Iobject_verify() returns a pointer to the memory referenced by id after verifying that `id` is of type `type`. This function is analogous to dereferencing a pointer in C with type checking.

Note
  H5Iobject_verify() does not change the ID it is called on in any way (as opposed to H5Iremove_verify(), which removes the ID from its type's hash table).

See also
  H5Iregister()

Since
  1.8.0

## ◆ H5Iregister()

hid_t H5Iregister | ( | H5I_type_t | type,
|  | const void * | object )

Registers an object under a type and returns an ID for it.

Parameters

  [in] | type | The identifier of the type of the new ID
  [in] | object | Pointer to object for which a new ID is created

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

H5Iregister() creates and returns a new ID for an object.

The `type` parameter is the identifier for the ID type to which this new ID will belong. This identifier must have been created by a call to H5Iregister_type().

The `object` parameter is a pointer to the memory which the new ID will be a reference to. This pointer will be stored by the library and returned via a call to H5Iobject_verify().

Since
  1.8.0

## ◆ H5Iregister_type1()

H5I_type_t H5Iregister_type1 | ( | size_t | hash_size,
|  | unsigned | reserved,
|  | H5I_free_t | free_func )

Creates and returns a new ID type.

Parameters

  [in] | hash_size | Minimum hash table size (in entries) used to store IDs for the new type (unused in 1.8.13 and later)
  [in] | reserved | Number of reserved IDs for the new type
  [in] | free_func | Function used to deallocate space for a single ID

Returns
  Returns the type identifier on success, negative on failure.

H5Iregister_type1() allocates space for a new ID type and returns an identifier for it.

The `hash_size` parameter indicates the minimum size of the hash table used to store IDs in the new type. This parameter is unused in 1.8.13 and later, when the implementation of ID storage changed.

The `reserved` parameter indicates the number of IDs in this new type to be reserved. Reserved IDs are valid IDs which are not associated with any storage within the library.

The `free_func` parameter is a function pointer to a function which returns an herr_t and accepts a `void*`. The purpose of this function is to deallocate memory for a single ID. It will be called by H5Iclear_type() and H5Idestroy_type() on each ID. This function is NOT called by H5Iremove_verify(). The `void*` will be the same pointer which was passed in to the H5Iregister() function. The `free_func` function should return 0 on success and -1 on failure.

Since
  1.8.0

Deprecated
  2.0.0 Deprecated in favor of the function H5Iregister_type2()

## ◆ H5Iregister_type2()

H5I_type_t H5Iregister_type2 | ( | unsigned | reserved,
|  | H5I_free_t | free_func )

Creates and returns a new ID type.

Parameters

  [in] | reserved | Number of reserved IDs for the new type
  [in] | free_func | Function used to deallocate space for a single ID

Returns
  Returns the type identifier on success, negative on failure.

H5Iregister_type2() allocates space for a new ID type and returns an identifier for it.

The `reserved` parameter indicates the number of IDs in this new type to be reserved. Reserved IDs are valid IDs which are not associated with any storage within the library.

The `free_func` parameter is a function pointer to a function which returns an herr_t and accepts a `void*`. The purpose of this function is to deallocate memory for a single ID. It will be called by H5Iclear_type() and H5Idestroy_type() on each ID. This function is NOT called by H5Iremove_verify(). The `void*` will be the same pointer which was passed in to the H5Iregister() function. The `free_func` function should return 0 on success and -1 on failure.

Since
  2.0.0

## ◆ H5Iremove_verify()

void * H5Iremove_verify | ( | hid_t | id,
|  | H5I_type_t | type )

Removes an ID from its type.

Parameters

  [in] | id | The ID to be removed from its type
  [in] | type | The identifier type

Returns
  Returns a pointer to the memory referred to by `id` on success, NULL on failure.

H5Iremove_verify() first ensures that `id` belongs to `type`. If so, it removes `id` from its type and returns the pointer to the memory it referred to. This pointer is the same pointer that was placed in storage by H5Iregister(). If id does not belong to `type`, then NULL is returned.

The `id` parameter is the ID which is to be removed from its type.

The `type` parameter is the identifier for the ID type which `id` is supposed to belong to. This identifier must have been created by a call to H5Iregister_type().

Note
  This function does NOT deallocate the memory that `id` refers to. The pointer returned by H5Iregister() must be deallocated by the user to avoid memory leaks.

Since
  1.8.0

## ◆ H5Isearch()

void * H5Isearch | ( | H5I_type_t | type,
|  | H5I_search_func_t | func,
|  | void * | key )

Finds the memory referred to by an ID within the given ID type such that some criterion is satisfied.

Parameters

  [in] | type | The identifier of the type to be searched
  [in] | func | The function defining the search criteria
  [in] | key | A key for the search function

Returns
  Returns a pointer to the object which satisfies the search function on success, NULL on failure.

H5Isearch() searches through a given ID type to find an object that satisfies the criteria defined by `func`. If such an object is found, the pointer to the memory containing this object is returned. Otherwise, NULL is returned. To do this, `func` is called on every member of type `type`. The first member to satisfy `func` is returned.

The `type` parameter is the identifier for the ID type which is to be searched. This identifier must have been created by a call to H5Iregister_type().

The parameter `func` is a function pointer to a function which takes three parameters. The first parameter is a `void*` and will be a pointer to the object to be tested. This is the same object that was placed in storage using H5Iregister(). The second parameter is a hid_t and is the ID of the object to be tested. The last parameter is a `void*`. This is the `key` parameter and can be used however the user finds helpful, or it can be ignored if it is not needed. `func` returns 0 if the object it is testing does not pass its criteria. A non-zero value should be returned if the object does pass its criteria. H5I_search_func_t is defined in H5Ipublic.h and is shown below.

typedef int (*H5I_search_func_t)(void *obj, hid_t id, void *key);

The `key` parameter will be passed to the search function as a parameter. It can be used to further define the search at run-time.

Since
  1.8.0

## ◆ H5Itype_exists()

htri_t H5Itype_exists | ( | H5I_type_t | type | ) |

Determines whether an identifier type is registered.

Parameters

  [in] | type | Identifier type

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

H5Itype_exists() determines whether the given identifier type, `type`, is registered with the library.

Since
  1.8.0