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
Objects (H5O)

## Detailed Description

Use the functions in this module to manage HDF5 objects.

HDF5 objects (groups, datasets, datatype objects) are usually created using functions in the object-specific modules (Groups (H5G), Datasets (H5D), Datatypes (H5T)). However, new objects can also be created by copying existing objects.

Many functions in this module are variations on object introspection, that is, the retrieval of detailed information about HDF5 objects in a file. Objects in an HDF5 file can be "visited" in an iterative fashion.

HDF5 objects are usually updated using functions in the object-specific modules. However, there are certain generic object properties, such as reference counts, that can be manipulated using functions in this module.

HDF5 objects are deleted as a side effect of rendering them unreachable from the root group. The net effect is the diminution of the object's reference count to zero, which can (but should not usually) be affected by a function in this module.

Create | Read
--- | ---
16 { 17 __label__ fail_file; 18 hid_t file, group; 19 char src_path[] = "/a/few/groups"; 20 21 if ((file = H5Fcreate("o1.h5", H5F_ACC_TRUNC, H5P_DEFAULTx2)) == H5I_INVALID_HID) { 22 ret_val = EXIT_FAILURE; 23 goto fail_file; 24 } 25 26 // create a few groups 27 { 28 __label__ fail_group, fail_lcpl; 29 hid_t lcpl; 30 if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) { 31 ret_val = EXIT_FAILURE; 32 goto fail_lcpl; 33 } 34 if (H5Pset_create_intermediate_group(lcpl, 1) < 0) { 35 ret_val = EXIT_FAILURE; 36 goto fail_group; 37 } 38 if ((group = H5Gcreate(file, src_path, lcpl, H5P_DEFAULTx2)) == H5I_INVALID_HID) { 39 ret_val = EXIT_FAILURE; 40 goto fail_group; 41 } 42 43 H5Gclose(group); 44fail_group: 45 H5Pclose(lcpl); 46fail_lcpl:; 47 } 48 49 // create a copy 50 if (H5Ocopy(file, ".", file, "copy of", H5P_DEFAULTx2) < 0) { 51 ret_val = EXIT_FAILURE; 52 } 53 54 H5Fclose(file); 55fail_file:; 56 } | 60 { 61 __label__ fail_info, fail_file; 62 hid_t file; 63 char path[] = "/a/few/groups"; 64 H5O_info2_t info; 65 66 if ((file = H5Fopen("o1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) { 67 ret_val = EXIT_FAILURE; 68 goto fail_file; 69 } 70 71 // retrieve information about the object 72 if (H5Oget_info_by_name(file, path, &info, H5O_INFO_BASIC | H5O_INFO_NUM_ATTRS, H5P_DEFAULT) < 0) { 73 ret_val = EXIT_FAILURE; 74 goto fail_info; 75 } 76 77 // determine the object type 78 switch (info.type) { 79 case H5O_TYPE_GROUP: 80 printf("HDF5 group\n"); 81 break; 82 case H5O_TYPE_DATASET: 83 printf("HDF5 dataset\n"); 84 break; 85 case H5O_TYPE_NAMED_DATATYPE: 86 printf("HDF5 datatype\n"); 87 break; 88 default: 89 printf("UFO?\n"); 90 break; 91 } 92 // print basic information 93 printf("Reference count: %u\n", info.rc); 94 printf("Attribute count: %lld\n", info.num_attrs); 95 96fail_info: 97 H5Fclose(file); 98fail_file:; 99 }
Update | Delete
103 { 104 __label__ fail_obj, fail_incr, fail_file; 105 hid_t file, obj; 106 char path[] = "/a/few/groups"; 107 H5O_info2_t info; 108 109 if ((file = H5Fopen("o1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { 110 ret_val = EXIT_FAILURE; 111 goto fail_file; 112 } 113 114 // open an object by path name 115 if ((obj = H5Oopen(file, path, H5P_DEFAULT)) == H5I_INVALID_HID) { 116 ret_val = EXIT_FAILURE; 117 goto fail_obj; 118 } 119 120 // bump its reference count (by 1) 121 if (H5Oincr_refcount(obj) < 0) { 122 ret_val = EXIT_FAILURE; 123 goto fail_incr; 124 } 125 126 // confirm the new reference count 127 if (H5Oget_info(obj, &info, H5O_INFO_BASIC) < 0) { 128 ret_val = EXIT_FAILURE; 129 goto fail_incr; 130 } 131 printf("Reference count: %u\n", info.rc); 132 133fail_incr: 134 H5Oclose(obj); 135fail_obj: 136 H5Fclose(file); 137fail_file:; 138 } | 142 { 143 __label__ fail_obj, fail_delete, fail_file; 144 hid_t file, obj; 145 char path[] = "/a/few/groups"; 146 H5O_info2_t info; 147 148 if ((file = H5Fopen("o1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { 149 ret_val = EXIT_FAILURE; 150 goto fail_file; 151 } 152 153 // open an object by path name 154 if ((obj = H5Oopen(file, path, H5P_DEFAULT)) == H5I_INVALID_HID) { 155 ret_val = EXIT_FAILURE; 156 goto fail_obj; 157 } 158 159 // render it inaccessible from the root group by deleting the one and 160 // only link to it; this drops the reference count by 1 161 if (H5Ldelete(file, path, H5P_DEFAULT) < 0) { 162 ret_val = EXIT_FAILURE; 163 goto fail_delete; 164 } 165 166 // confirm the new reference count 167 if (H5Oget_info(obj, &info, H5O_INFO_BASIC) < 0) { 168 ret_val = EXIT_FAILURE; 169 goto fail_delete; 170 } 171 printf("Reference count: %u\n", info.rc); 172 173 // if we close the file at this point, we'd be creating a tombstone, 174 // an object that cannot be reached and that cannot be reclaimed by the 175 // freespace manager; decrement the reference count to zero to prevent that 176 if (H5Idec_ref(obj) < 0) { 177 ret_val = EXIT_FAILURE; 178 goto fail_delete; 179 } 180 else 181 // attempting to close the object would be like a double H5Oclose and fail 182 goto fail_obj; 183 184fail_delete: 185 H5Oclose(obj); 186fail_obj: 187 H5Fclose(file); 188fail_file:; 189 }

## Macros
#define | H5Oget_info H5Oget_info3
#define | H5Oget_info_by_idx H5Oget_info_by_idx3
#define | H5Oget_info_by_name H5Oget_info_by_name3
#define | H5Ovisit H5Ovisit3
#define | H5Ovisit_by_name H5Ovisit_by_name3

## Functions
herr_t | H5Oare_mdc_flushes_disabled (hid_t object_id, bool *are_disabled)
| Retrieves comment for specified object.
herr_t | H5Oclose (hid_t object_id)
| Closes an object in an HDF5 file.
herr_t | H5Ocopy (hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id)
| Copies an object in an HDF5 file.
herr_t | H5Odecr_refcount (hid_t object_id)
| Decrements an object reference count.
herr_t | H5Odisable_mdc_flushes (hid_t object_id)
| Prevents metadata entries for an HDF5 object from being flushed from the metadata cache to storage.
herr_t | H5Oenable_mdc_flushes (hid_t object_id)
| Enables flushing of dirty metadata entries from a file's metadata cache.
htri_t | H5Oexists_by_name (hid_t loc_id, const char *name, hid_t lapl_id)
| Determines whether a link resolves to an actual object.
herr_t | H5Oflush (hid_t obj_id)
| Flushes all buffers associated with an HDF5 object to disk.
ssize_t | H5Oget_comment (hid_t obj_id, char *comment, size_t bufsize)
| Retrieves comment for specified object.
ssize_t | H5Oget_comment_by_name (hid_t loc_id, const char *name, char *comment, size_t bufsize, hid_t lapl_id)
| Retrieves comment for specified object.
herr_t | H5Oget_info1 (hid_t loc_id, H5O_info1_t *oinfo)
| Retrieves the metadata for an object specified by an identifier.
herr_t | H5Oget_info2 (hid_t loc_id, H5O_info1_t *oinfo, unsigned fields)
| Retrieves the metadata for an object specified by an identifier.
herr_t | H5Oget_info3 (hid_t loc_id, H5O_info2_t *oinfo, unsigned fields)
| Retrieves the metadata for an object specified by an identifier.
herr_t | H5Oget_info_by_idx1 (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_info1_t *oinfo, hid_t lapl_id)
| Retrieves the metadata for an object, identifying the object by an index position.
herr_t | H5Oget_info_by_idx2 (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_info1_t *oinfo, unsigned fields, hid_t lapl_id)
| Retrieves the metadata for an object, identifying the object by an index position.
herr_t | H5Oget_info_by_idx3 (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_info2_t *oinfo, unsigned fields, hid_t lapl_id)
| Retrieves the metadata for an object, identifying the object by an index position.
herr_t | H5Oget_info_by_name1 (hid_t loc_id, const char *name, H5O_info1_t *oinfo, hid_t lapl_id)
| Retrieves the metadata for an object, identifying the object by location and relative name.
herr_t | H5Oget_info_by_name2 (hid_t loc_id, const char *name, H5O_info1_t *oinfo, unsigned fields, hid_t lapl_id)
| Retrieves the metadata for an object, identifying the object by location and relative name.
herr_t | H5Oget_info_by_name3 (hid_t loc_id, const char *name, H5O_info2_t *oinfo, unsigned fields, hid_t lapl_id)
| Retrieves the metadata for an object, identifying the object by location and relative name.
herr_t | H5Oget_native_info (hid_t loc_id, H5O_native_info_t *oinfo, unsigned fields)
| Retrieve native file format information about an object.
herr_t | H5Oget_native_info_by_idx (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_native_info_t *oinfo, unsigned fields, hid_t lapl_id)
| Retrieve native file format information about an object according to the order of an index.
herr_t | H5Oget_native_info_by_name (hid_t loc_id, const char *name, H5O_native_info_t *oinfo, unsigned fields, hid_t lapl_id)
| Retrieve native file format information about an object given its name.
herr_t | H5Oincr_refcount (hid_t object_id)
| Increments an object reference count.
herr_t | H5Olink (hid_t obj_id, hid_t new_loc_id, const char *new_name, hid_t lcpl_id, hid_t lapl_id)
| Creates a hard link to an object in an HDF5 file.
hid_t | H5Oopen (hid_t loc_id, const char *name, hid_t lapl_id)
| Opens an object in an HDF5 file by location identifier and path name.
hid_t | H5Oopen_by_addr (hid_t loc_id, haddr_t addr)
| Opens an object using its address within an HDF5 file.
hid_t | H5Oopen_by_idx (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id)
| Opens the nth object in a group.
hid_t | H5Oopen_by_token (hid_t loc_id, H5O_token_t token)
| Opens an object in an HDF5 file using its VOL independent token.
herr_t | H5Orefresh (hid_t oid)
| Refreshes all buffers associated with an HDF5 object.
herr_t | H5Oset_comment (hid_t obj_id, const char *comment)
| Sets comment for specified object.
herr_t | H5Oset_comment_by_name (hid_t loc_id, const char *name, const char *comment, hid_t lapl_id)
| Sets comment for specified object.
herr_t | H5Otoken_cmp (hid_t loc_id, const H5O_token_t *token1, const H5O_token_t *token2, int *cmp_value)
| Compares two VOL connector object tokens.
herr_t | H5Otoken_from_str (hid_t loc_id, const char *token_str, H5O_token_t *token)
| Deserializes a string into a connector object token.
herr_t | H5Otoken_to_str (hid_t loc_id, const H5O_token_t *token, char **token_str)
| Serializes a connector's object token into a string.
herr_t | H5Ovisit1 (hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate1_t op, void *op_data)
| Recursively visits all objects accessible from a specified object.
herr_t | H5Ovisit2 (hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate1_t op, void *op_data, unsigned fields)
| Recursively visits all objects accessible from a specified object.
herr_t | H5Ovisit3 (hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate2_t op, void *op_data, unsigned fields)
| Recursively visits all objects accessible from a specified object.
herr_t | H5Ovisit_by_name1 (hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate1_t op, void *op_data, hid_t lapl_id)
| Recursively visits all objects starting from a specified object.
herr_t | H5Ovisit_by_name2 (hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate1_t op, void *op_data, unsigned fields, hid_t lapl_id)
| Recursively visits all objects starting from a specified object.
herr_t | H5Ovisit_by_name3 (hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate2_t op, void *op_data, unsigned fields, hid_t lapl_id)
| Recursively visits all objects accessible from a specified object.

## Macro Definition Documentation

## ◆ H5Oget_info

#define H5Oget_info H5Oget_info3

H5Oget_info() is a macro that is mapped to either H5Oget_info1() or H5Oget_info2() or H5Oget_info3().

See also
  API Compatibility Macros

## ◆ H5Oget_info_by_idx

#define H5Oget_info_by_idx H5Oget_info_by_idx3

H5Oget_info_by_idx() is a macro that is mapped to either H5Oget_info_by_idx1() or H5Oget_info_by_idx2() or H5Oget_info_by_idx3().

See also
  API Compatibility Macros

## ◆ H5Oget_info_by_name

#define H5Oget_info_by_name H5Oget_info_by_name3

H5Oget_info_by_name() is a macro that is mapped to either H5Oget_info_by_name1() or H5Oget_info_by_name2() or H5Oget_info_by_name3().

See also
  API Compatibility Macros

## ◆ H5Ovisit

#define H5Ovisit H5Ovisit3

H5Ovisit() is a macro that is mapped to either H5Ovisit1() or H5Ovisit2() or H5Ovisit3().

See also
  API Compatibility Macros

## ◆ H5Ovisit_by_name

#define H5Ovisit_by_name H5Ovisit_by_name3

H5Ovisit_by_name() is a macro that is mapped to either H5Ovisit_by_name1() or H5Ovisit_by_name2() or H5Ovisit_by_name3().

See also
  API Compatibility Macros

## Function Documentation

## ◆ H5Oare_mdc_flushes_disabled()

herr_t H5Oare_mdc_flushes_disabled | ( | hid_t | object_id,
|  | bool * | are_disabled )

Retrieves comment for specified object.

Parameters

  [in] | object_id | Identifier of an object in the cache; may be a group, named datatype, or dataset identifier
  [out] | are_disabled | Flushes enabled/disabled

Returns
  `are_disabled` will be set to `1` if an object has had flushes disabled and `0` if it has not had flushes disabled.
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5Oare_mdc_flushes_disabled() determines if an HDF5 object (dataset, group, committed datatype) has had flushes of metadata entries disabled.

The H5Oenable_mdc_flushes(), H5Odisable_mdc_flushes() and associated flush functions can be used to control the flushing of entries from a file's metadata cache. Metadata cache entries can be controlled at both the individual HDF5 object level (datasets, groups, committed datatypes) and the entire metadata cache level.

Note
  HDF5 objects include datasets, groups, and committed datatypes. Only hid_t identifiers that represent these objects can be passed to the function.
  Passing in a hid_t identifier that represents any other HDF5 entity is considered an error.
  It is an error to pass an HDF5 file identifier (obtained from H5Fopen() or H5Fcreate()) to this function.

Since
  1.10.0

## ◆ H5Oclose()

herr_t H5Oclose | ( | hid_t | object_id | ) |

Closes an object in an HDF5 file.

Parameters

  [in] | object_id | Object identifier

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

H5Oclose() closes the group, dataset, or named datatype specified by object_id.

This function is the companion to H5Oopen(), and has the same effect as calling H5Gclose(), H5Dclose(), or H5Tclose().

H5Oclose() is not used to close a dataspace, attribute, property list, or file.

Version
  1.8.8 Fortran subroutine introduced in this release.

Since
  1.8.0

## ◆ H5Ocopy()

herr_t H5Ocopy | ( | hid_t | src_loc_id,
|  | const char * | src_name,
|  | hid_t | dst_loc_id,
|  | const char * | dst_name,
|  | hid_t | ocpypl_id,
|  | hid_t | lcpl_id )

Copies an object in an HDF5 file.

Parameters

  [in] | src_loc_id | Object identifier indicating the location of the source object to be copied
  [in] | src_name | Name of the source object to be copied
  [in] | dst_loc_id | Location identifier specifying the destination
  [in] | dst_name | Name to be assigned to the new copy
  [in] | ocpypl_id | Object copy property list
  [in] | lcpl_id | Link creation property list identifier

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

H5Ocopy() copies the group, dataset or committed datatype specified by `src_name` from the file or group specified by `src_loc_id` to the destination location `dst_loc_id`.

The destination location, as specified in dst_loc_id, may be a group in the current file or a location in a different file. If dst_loc_id is a file identifier, the copy will be placed in that file's root group.

The copy will be created with the path specified in `dst_name`, which must not pre-exist in the destination location. If `dst_name` already exists at the location `dst_loc_id`, H5Ocopy() will fail. If `dst_name` is an absolute path, the copy will be created relative to the file's root group.

The copy of the object is created with the property lists specified by `ocpypl_id` and `lcpl_id`. H5P_DEFAULT can be passed in for these property lists. The default behavior:

- of the link creation property list is to NOT create intermediate groups.
- of the flags specified by the object creation property list is described in H5Pset_copy_object().

These property lists or flags can be modified to govern the behavior of H5Ocopy() as follows:

- A flag controlling the creation of intermediate groups that may not yet exist is set in the link creation property list `lcpl_id` with H5Pset_create_intermediate_group().
- Copying of committed datatypes can be tuned through the use of H5Pset_copy_object(), H5Padd_merge_committed_dtype_path(), H5Pset_mcdt_search_cb(), and related functions.
- Flags controlling other aspects of object copying are set in the object copy property list `ocpypl_id` with H5Pset_copy_object().

H5Ocopy() will always try to make a copy of the object specified in `src_name`.

- If the object specified by `src_name` is a group containing a soft or external link, the default is that the new copy will contain a soft or external link with the same value as the original. See H5Pset_copy_object() for optional settings.
- If the path specified in `src_name` is or contains a soft link or an external link, H5Ocopy() will copy the target object. Use H5Lcopy() if the intent is to create a new soft or external link with the same value as the original link.

H5Ocopy() can be used to copy an object in an HDF5 file. If an object has been changed since it was opened, it should be written back to the file before using H5Ocopy(). The object can be written back either by closing the object (H5Gclose(), H5Oclose(), H5Dclose(), or H5Tclose()) or by flushing the HDF5 file (H5Fflush()).

See Also:
  - Functions to modify the behavior of H5Ocopy():
    - H5Padd_merge_committed_dtype_path()
    - H5Pset_copy_object()
    - H5Pset_create_intermediate_group()
    - H5Pset_mcdt_search_cb()
  - Copying Committed Datatypes with H5Ocopy - A comprehensive discussion of copying committed datatypes (PDF) in Advanced Topics in HDF5

Version
  1.8.9 Fortran subroutine introduced in this release.

Since
  1.8.0

## ◆ H5Odecr_refcount()

herr_t H5Odecr_refcount | ( | hid_t | object_id | ) |

Decrements an object reference count.

Parameters

  [in] | object_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.

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

H5Odecr_refcount() decrements the hard link reference count for an object. It should be used any time a user-defined link that references an object by address is deleted. In general, H5Oincr_refcount() will have been used previously, when the link was created.

An object's reference count is the number of hard links in the file that point to that object. See the “Programming Model” section of the HDF5 Groups chapter in the HDF5 User Guide for a more complete discussion of reference counts.

If a user application needs to determine an object's reference count, an H5Oget_info() call is required; the reference count is returned in the `rc` field of the H5O_info_t `struct`.

Warning
  This function must be used with care!
  Improper use can lead to inaccessible data, wasted space in the file, or file corruption.

Version
  1.8.11 Fortran subroutine introduced in this release.

Since
  1.8.0

## ◆ H5Odisable_mdc_flushes()

herr_t H5Odisable_mdc_flushes | ( | hid_t | object_id | ) |

Prevents metadata entries for an HDF5 object from being flushed from the metadata cache to storage.

Parameters

  [in] | object_id | Identifier of the object that will have flushes disabled; may be a group, named datatype, or dataset identifier

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

H5Odisable_mdc_flushes(), H5Oenable_mdc_flushes() and associated flush functions can be used to control the flushing of entries from a file's metadata cache.

This function prevents an object's or cache's dirty metadata entries from being flushed from the cache by the usual cache eviction/flush policy. Instead, users must manually flush the cache or entries for individual objects via the appropriate H5Fflush(), H5Dflush(), H5Gflush(), H5Tflush(), and H5Oflush() calls.

Metadata cache entries can be controlled at both the individual HDF5 object level (datasets, groups, committed datatypes) and the entire metadata cache level.

Note
  HDF5 objects include datasets, groups, and committed datatypes. Only hid_t identifiers that represent these objects can be passed to the function. Passing in a hid_t identifier that represents any other HDF5 entity is considered an error. It is an error to pass an HDF5 file identifier (obtained from H5Fopen() or H5Fcreate()) to this function. Misuse of this function can cause the cache to exhaust available memory. Objects can be returned to the default automatic flush behavior with H5Oenable_mdc_flushes(). Flush prevention only pertains to new or dirty metadata entries. Clean entries can be evicted from the cache. Calling this function on an object that has already had flushes disabled will return an error.

Since
  1.10.0

## ◆ H5Oenable_mdc_flushes()

herr_t H5Oenable_mdc_flushes | ( | hid_t | object_id | ) |

Enables flushing of dirty metadata entries from a file's metadata cache.

Parameters

  [in] | object_id | Identifier of the object that will have flushes re-enabled; may be a group, named datatype, or dataset identifier

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

H5Oenable_mdc_flushes(), H5Odisable_mdc_flushes() and associated flush functions can be used to control the flushing of entries from a file's metadata cache.

This function allows an object or cache's dirty metadata entries to be flushed from the cache by the usual cache eviction/flush policy.

Metadata cache entries can be controlled at both the individual HDF5 object level (datasets, groups, committed datatypes) and the entire metadata cache level.

Note
  HDF5 objects include datasets, groups, and committed datatypes. Only hid_t identifiers that represent these objects can be passed to the function. Passing in a hid_t identifier that represents any other HDF5 entity is considered an error. It is an error to pass an HDF5 file identifier (obtained from H5Fopen() or H5Fcreate()) to this function. Using this function on an object that has not had flushes disabled is considered an error. The state of an object can be determined with H5Oare_mdc_flushes_disabled(). An object will be returned to the default flush algorithm when it is closed. All objects will be returned to the default flush algorithm when the file is closed. An object's entries will not necessarily be flushed as a result of calling this function.

Since
  1.10.0

## ◆ H5Oexists_by_name()

htri_t H5Oexists_by_name | ( | hid_t | loc_id,
|  | const char * | name,
|  | hid_t | lapl_id )

Determines whether a link resolves to an actual object.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | The name of the link to check
  [in] | lapl_id | Link access property list identifier

Returns
  Returns a positive value if the object pointed to by the `loc_id` and `name` combination exists.
  Returns 0 if the object pointed to by the `loc_id` and `name` combination does not exist.
  Returns a negative value when the function fails.

H5Oexists_by_name() allows an application to determine whether the link `name` in the group or file specified with `loc_id` resolves to an HDF5 object to open or if the link dangles. The link may be of any type, but hard links will always resolve to objects and do not need to be verified.

Note that H5Oexists_by_name() verifies only that the target object exists. If `name` includes either a relative path or an absolute path to the target link, intermediate steps along the path must be verified before the existence of the target link can be safely checked. If the path is not verified and an intermediate element of the path does not exist, H5Oexists_by_name() will fail. The example in the next paragraph illustrates one step-by-step method for verifying the existence of a link with a relative or absolute path.

Example
  Use the following steps to verify the existence of the link `datasetD` in the `group` group1/group2/softlink_to_group3/, where `group1` is a member of the group specified by `loc_id:`

  - First, use H5Lexists() to verify that a link named `group1` exists.
  - If `group1` exists, use H5Oexists_by_name() to verify that the link `group1` resolves to an object.
  - If `group1` exists, use H5Lexists() again, this time with the name set to `group1/group2`, to verify that the link `group2` exists in `group1`.
  - If the `group2` link exists, use H5Oexists_by_name() to verify that `group1/group2` resolves to an object.
  - If `group2` exists, use H5Lexists() again, this time with the name set to `group1/group2/softlink_to_group3`, to verify that the link `softlink_to_group3` exists in `group2`.
  - If the `softlink_to_group3` link exists, use H5Oexists_by_name() to verify that `group1/group2/softlink_to_group3` resolves to an object.
  - If `softlink_to_group3` exists, you can now safely use H5Lexists with the name set to `group1/group2/softlink_to_group3/datasetD` to verify that the target link, `datasetD`, exists.
  - And finally, if the link `datasetD` exists, use H5Oexists_by_name to verify that `group1/group2/softlink_to_group3/datasetD` resolves to an object.

  If the link to be verified is specified with an absolute path, the same approach should be used, but starting with the first link in the file's root group. For instance, if `datasetD` were in `/group1/group2/softlink_to_group3`, the first call to H5Lexists() would have name set to `/group1`.

  Note that this is an outline and does not include all the necessary details. Depending on circumstances, for example, an application may need to verify the type of an object also.

Warning
  Failure Modes:
  If `loc_id` and `name` both exist, but the combination does not resolve to an object, the function will return 0 (zero); the function does not fail in this case.
  If either the location or the link specified by the `loc_id` and `name` combination does not exist, the function will fail, returning a negative value.
  Note that verifying the existence of an object within an HDF5 file is a multistep process. An application can be certain the object does not exist only if H5Lexists() and H5Oexists_by_name() have been used to verify the existence of the links and groups in the hierarchy above that object. The example above, in the function description, provides a step-by-step description of that verification process.

Version
  1.8.11 Fortran subroutine introduced in this release.

Since
  1.8.5

## ◆ H5Oflush()

herr_t H5Oflush | ( | hid_t | obj_id | ) |

Flushes all buffers associated with an HDF5 object to disk.

Parameters

  [in] | obj_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.

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

H5Oflush() causes all buffers associated with an object to be immediately flushed to disk without removing the data from the cache.

The object associated with `object_id` can be any named object in an HDF5 file, including a dataset, a group, or a committed datatype.

Warning
  H5Oflush doesn't work correctly with parallel. It causes an assertion failure in metadata cache during H5Fclose().

Note
  HDF5 does not possess full control over buffering. H5Oflush() flushes the internal HDF5 buffers and then asks the operating system (the OS) to flush the system buffers for the open files. After that, the OS is responsible for ensuring that the data is actually flushed to disk.

See also
  H5Dflush(), H5Drefresh(), H5Oflush(), H5Grefresh(), H5Oflush(), H5Orefresh(), H5Tflush(), H5Trefresh()
  H5DOappend(), H5Fstart_swmr_write(), H5Pget_append_flush(), H5Pget_object_flush_cb(), H5Pset_append_flush(), H5Pset_object_flush_cb()
  H5Oare_mdc_flushes_disabled(), H5Odisable_mdc_flushes(), H5Oenable_mdc_flushes()

Since
  1.10.0

## ◆ H5Oget_comment()

ssize_t H5Oget_comment | ( | hid_t | obj_id,
|  | char * | comment,
|  | size_t | bufsize )

Retrieves comment for specified object.

Parameters

  [in] | obj_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [out] | comment | The comment
  [in] | bufsize | Anticipated required size of the comment buffer

Returns
  Upon success, returns the number of characters in the comment, not including the `NULL` terminator, or zero (`0`) if the object has no comment. The value returned may be larger than `bufsize`. Otherwise returns a negative value.

H5Oget_comment() retrieves the comment for the specified object in the buffer `comment`.

The target object is specified by an identifier, `object_id`.

The size in bytes of the buffer `comment`, including the `NULL` terminator, is specified in `bufsize`. If `bufsize` is unknown, a preliminary H5Oget_comment() call with the pointer `comment` set to `NULL` will return the size of the comment without the `NULL` terminator.

If `bufsize` is set to a smaller value than described above, only `bufsize` bytes of the comment, without a `NULL` terminator, are returned in `comment`.

If an object does not have a comment, an empty string is returned in `comment`.

Version
  1.8.11 Fortran subroutine introduced in this release.

Since
  1.8.0

## ◆ H5Oget_comment_by_name()

ssize_t H5Oget_comment_by_name | ( | hid_t | loc_id,
|  | const char * | name,
|  | char * | comment,
|  | size_t | bufsize,
|  | hid_t | lapl_id )

Retrieves comment for specified object.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Name of the object whose comment is to be retrieved
  [out] | comment | The comment
  [in] | bufsize | Anticipated required size of the `comment` buffer
  [in] | lapl_id | Link access property list identifier

Returns
  Upon success, returns the number of characters in the comment, not including the `NULL` terminator, or zero (`0`) if the object has no comment. The value returned may be larger than `bufsize`. Otherwise returns a negative value.

H5Oget_comment_by_name() retrieves the comment for an object in the buffer `comment`.

The target object is specified by `loc_id` and `name`. `loc_id` can specify any object in the file. `name` can be one of the following:

- The name of the object relative to `loc_id`
- An absolute name of the object, starting from `/`, the file's root group
- A dot (``.), if `loc_id` fully specifies the object

The size in bytes of the comment, including the `NULL` terminator, is specified in `bufsize`. If `bufsize` is unknown, a preliminary H5Oget_comment_by_name() call with the pointer `comment` set to `NULL` will return the size of the comment without the `NULL` terminator.

If `bufsize` is set to a smaller value than described above, only `bufsize` bytes of the comment, without a `NULL` terminator, are returned in `comment`.

If an object does not have a comment, an empty string is returned in `comment`.

`lapl_id` contains a link access property list identifier. A link access property list can come into play when traversing links to access an object.

Version
  1.8.11 Fortran subroutine introduced in this release.

Since
  1.8.0

## ◆ H5Oget_info1()

herr_t H5Oget_info1 | ( | hid_t | loc_id,
|  | H5O_info1_t * | oinfo )

Retrieves the metadata for an object specified by an identifier.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [out] | oinfo | Buffer in which to return object information

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 the function H5Oget_info3() or the macro H5Oget_info.

H5Oget_info1() specifies an object by its identifier, `loc_id` , and retrieves the metadata describing that object in `oinfo`.

Note
  If you are iterating through a lot of different objects to retrieve information via the H5Oget_info() family of routines, you may see memory building up. This can be due to memory allocation for metadata, such as object headers and messages, when the iterated objects are put into the metadata cache.
  If the memory buildup is not desirable, you can configure a smaller cache via H5Fset_mdc_config() or set the file access property list via H5Pset_mdc_config(). A smaller sized cache will force metadata entries to be evicted from the cache, thus freeing the memory associated with the entries.

Version
  1.10.5 The macro H5Oget_info was removed and the function H5Oget_info1() was copied to H5Oget_info().
  1.10.3 Function H5Oget_info() was copied to H5Oget_info1(), and the macro H5Oget_info was created.
  1.8.15 Added a note about the valid values for the `version` field in the H5O_hdr_info_t structure.
  1.8.11 Fortran subroutine introduced in this release.
  1.8.10 Added H5O_type_t structure to the Description section.
  Separated H5O_hdr_info_t structure from H5O_info_t in the Description section.
  Clarified the definition and implementation of the time fields.

Since
  1.8.0

## ◆ H5Oget_info2()

herr_t H5Oget_info2 | ( | hid_t | loc_id,
|  | H5O_info1_t * | oinfo,
|  | unsigned | fields )

Retrieves the metadata for an object specified by an identifier.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [out] | oinfo | Buffer in which to return object information
  [in] | fields | Flags specifying the fields to include in `oinfo`

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 the function H5Oget_info3() or the macro H5Oget_info().

H5Oget_info2() specifies an object by its identifier, `loc_id` , and retrieves the metadata describing that object in `oinfo` , an H5O_info1_t `struct`. This `struct` type is described in H5Oget_info1().

The `fields` parameter contains flags to determine which fields will be filled in the H5O_info1_t `struct` returned in `oinfo`. These flags are defined in the H5Opublic.h file:

Flag | Purpose
--- | ---
H5O_INFO_BASIC | Fill in the fileno, addr, type, and rc fields
H5O_INFO_TIME | Fill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS | Fill in the num_attrs field
H5O_INFO_HDR | Fill in the num_attrs field
H5O_INFO_META_SIZE | Fill in the meta_size field
H5O_INFO_ALL | H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE

Note
  If you are iterating through a lot of different objects to retrieve information via the H5Oget_info() family of routines, you may see memory building up. This can be due to memory allocation for metadata, such as object headers and messages, when the iterated objects are put into the metadata cache.
  If the memory buildup is not desirable, you can configure a smaller cache via H5Fset_mdc_config() or set the file access property list via H5Pset_mdc_config(). A smaller sized cache will force metadata entries to be evicted from the cache, thus freeing the memory associated with the entries.

Since
  1.10.3

## ◆ H5Oget_info3()

herr_t H5Oget_info3 | ( | hid_t | loc_id,
|  | H5O_info2_t * | oinfo,
|  | unsigned | fields )

Retrieves the metadata for an object specified by an identifier.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [out] | oinfo | Buffer in which to return object information
  [in] | fields | Flags specifying the fields to include in `oinfo`

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

H5Oget_info3() specifies an object by its identifier, `loc_id` , and retrieves the metadata describing that object in `oinfo`.

The `fields` parameter contains flags to determine which fields will be filled in the H5O_info2_t `struct` returned in `oinfo`. These flags are defined in the H5Opublic.h file:

Flag | Purpose
--- | ---
H5O_INFO_BASIC | Fill in the fileno, addr, type, and rc fields
H5O_INFO_TIME | Fill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS | Fill in the num_attrs field
H5O_INFO_HDR | Fill in the num_attrs field
H5O_INFO_META_SIZE | Fill in the meta_size field
H5O_INFO_ALL | H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE

Example
  An example snippet from examples/h5_attribute.c:

  /*
  * Find string attribute by iterating through all attributes
  */
  ret = H5Oget_info3(dataset, &oinfo, H5O_INFO_NUM_ATTRS);
  for (i = 0; i < (unsigned)oinfo.num_attrs; i++) {
  attr = H5Aopen_by_idx(dataset, ".", H5_INDEX_CRT_ORDER, H5_ITER_INC, (hsize_t)i, H5P_DEFAULT,
  H5P_DEFAULT);
  atype = H5Aget_type(attr);
  type_class = H5Tget_class(atype);
  if (type_class == H5T_STRING) {
  atype_mem = H5Tget_native_type(atype, H5T_DIR_ASCEND);
  ret = H5Aread(attr, atype_mem, string_out);
  printf("Found string attribute; its index is %d , value = %s \n", i, string_out);
  ret = H5Tclose(atype_mem);
  }
  ret = H5Aclose(attr);
  ret = H5Tclose(atype);
  }

Note
  If you are iterating through a lot of different objects to retrieve information via the H5Oget_info() family of routines, you may see memory building up. This can be due to memory allocation for metadata, such as object headers and messages, when the iterated objects are put into the metadata cache.
  If the memory buildup is not desirable, you can configure a smaller cache via H5Fset_mdc_config() or set the file access property list via H5Pset_mdc_config(). A smaller sized cache will force metadata entries to be evicted from the cache, thus freeing the memory associated with the entries.

Since
  1.12.0

## ◆ H5Oget_info_by_idx1()

herr_t H5Oget_info_by_idx1 | ( | hid_t | loc_id,
|  | const char * | group_name,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | hsize_t | n,
|  | H5O_info1_t * | oinfo,
|  | hid_t | lapl_id )

Retrieves the metadata for an object, identifying the object by an index position.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | group_name | Name of group in which object is located
  [in] | idx_type | Index type
  [in] | order | Iteration order
  [in] | n | Position within the index
  [out] | oinfo | Buffer in which to return object information
  [in] | lapl_id | Link access property list identifier

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 the function H5Oget_info_by_idx3() or the macro H5Oget_info_by_idx().

H5Oget_info_by_idx1() retrieves the metadata describing an object in the `struct` `oinfo`, as specified by the location, `loc_id`, group name, `group_name`, the index by which objects in that group are tracked, `idx_type`, the order by which the index is to be traversed, `order`, and an object's position `n` within that index.

If `loc_id` fully specifies the group in which the object resides, `group_name` can be a dot (``.).

The link access property list, `lapl_id`, is not currently used; it should be passed in as H5P_DEFAULT.

Version
  1.10.5 The macro H5Oget_info_by_idx was removed and the function H5Oget_info_by_idx() was copied to H5Oget_info_by_idx1().
  1.10.3 Function H5Oget_info_by_idx() was copied to H5Oget_info_by_idx1() and the macro H5Oget_info_by_idx was created.
  1.8.11 Fortran subroutine introduced in this release.

Since
  1.8.0

## ◆ H5Oget_info_by_idx2()

herr_t H5Oget_info_by_idx2 | ( | hid_t | loc_id,
|  | const char * | group_name,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | hsize_t | n,
|  | H5O_info1_t * | oinfo,
|  | unsigned | fields,
|  | hid_t | lapl_id )

Retrieves the metadata for an object, identifying the object by an index position.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | group_name | Name of group in which object is located
  [in] | idx_type | Index type
  [in] | order | Iteration order
  [in] | n | Position within the index
  [out] | oinfo | Buffer in which to return object information
  [in] | fields | Flags specifying the fields to include in `oinfo`
  [in] | lapl_id | Link access property list identifier

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

Deprecated
  As of HDF5-1.12 this function is deprecated in favor of the function H5Oget_info_by_idx3() or the macro H5Oget_info_by_idx.

H5Oget_info_by_idx2() retrieves the metadata describing an object in the `struct` `oinfo`, as specified by the location, `loc_id`, group name, `group_name`, the index by which objects in that group are tracked, `idx_type`, the order by which the index is to be traversed, `order`, and an object's position `n` within that index.

`oinfo`, in which the object information is returned, is a `struct` of type H5O_info1_t. This and other `struct` types used by H5Oget_info_by_idx2() are described in H5Oget_info_by_idx1().

If `loc_id` fully specifies the group in which the object resides, i`group_name` can be a dot (``.).

The `fields` parameter contains flags to determine which fields will be filled in the H5O_info1_t `struct` returned in `oinfo`. These flags are defined in the H5Opublic.h file:

Flag | Purpose
--- | ---
H5O_INFO_BASIC | Fill in the fileno, addr, type, and rc fields
H5O_INFO_TIME | Fill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS | Fill in the num_attrs field
H5O_INFO_HDR | Fill in the num_attrs field
H5O_INFO_META_SIZE | Fill in the meta_size field
H5O_INFO_ALL | H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE

The link access property list, `lapl_id`, is not currently used; it should be passed in as H5P_DEFAULT.

Since
  1.10.3

## ◆ H5Oget_info_by_idx3()

herr_t H5Oget_info_by_idx3 | ( | hid_t | loc_id,
|  | const char * | group_name,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | hsize_t | n,
|  | H5O_info2_t * | oinfo,
|  | unsigned | fields,
|  | hid_t | lapl_id )

Retrieves the metadata for an object, identifying the object by an index position.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | group_name | Name of group in which object is located
  [in] | idx_type | Index type
  [in] | order | Iteration order
  [in] | n | Position within the index
  [out] | oinfo | Buffer in which to return object information
  [in] | fields | Flags specifying the fields to include in `oinfo`
  [in] | lapl_id | Link access property list identifier

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

H5Oget_info_by_idx3() retrieves the metadata describing an object in the `struct` `oinfo`, as specified by the location, `loc_id`, group name, `group_name`, the index by which objects in that group are tracked, `idx_type`, the order by which the index is to be traversed, `order`, and an object's position `n` within that index.

If `loc_id` fully specifies the group in which the object resides, `group_name` can be a dot (``.).

The `fields` parameter contains flags to determine which fields will be filled in the H5O_info2_t `struct` returned in `oinfo`. These flags are defined in the H5Opublic.h file:

Flag | Purpose
--- | ---
H5O_INFO_BASIC | Fill in the fileno, addr, type, and rc fields
H5O_INFO_TIME | Fill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS | Fill in the num_attrs field
H5O_INFO_HDR | Fill in the num_attrs field
H5O_INFO_META_SIZE | Fill in the meta_size field
H5O_INFO_ALL | H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE

The link access property list, `lapl_id`, is not currently used; it should be passed in as H5P_DEFAULT.

Example
  An example snippet from test/titerate.c:
  ret = H5Oget_info_by_idx3(root_group, ".", H5_INDEX_NAME, H5_ITER_INC, (hsize_t)i, &oinfo,
  H5O_INFO_BASIC, H5P_DEFAULT);
  CHECK(ret, FAIL, "H5Oget_info_by_idx");

Since
  1.12.0

## ◆ H5Oget_info_by_name1()

herr_t H5Oget_info_by_name1 | ( | hid_t | loc_id,
|  | const char * | name,
|  | H5O_info1_t * | oinfo,
|  | hid_t | lapl_id )

Retrieves the metadata for an object, identifying the object by location and relative name.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Name of object, relative to `loc_id`
  [out] | oinfo | Buffer in which to return object information
  [in] | lapl_id | Link access property list identifier

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 the function H5Oget_info_by_name2() or the macro H5Oget_info_by_name.

H5Oget_info_by_name1() specifies an object's location and name, `loc_id` and `name`, respectively, and retrieves the metadata describing that object in `oinfo`, an H5O_info1_t `struct`.

The `struct` H5O_info1_t is defined in H5Opublic.h and described in the H5Oget_info1() function entry.

The link access property list, `lapl_id`, is not currently used; it should be passed in as H5P_DEFAULT.

Version
  1.10.5 The macro H5Oget_info_by_name was removed and the function H5Oget_info_by_name1() was copied to H5Oget_info_by_name().
  1.10.3 Function H5Oget_info_by_name() was copied to H5Oget_info_by_name1() and the macro H5Oget_info_by_name was created.
  1.8.8 Fortran 2003 subroutine and `h5o_info_t` derived type introduced in this release.

Since
  1.8.0

## ◆ H5Oget_info_by_name2()

herr_t H5Oget_info_by_name2 | ( | hid_t | loc_id,
|  | const char * | name,
|  | H5O_info1_t * | oinfo,
|  | unsigned | fields,
|  | hid_t | lapl_id )

Retrieves the metadata for an object, identifying the object by location and relative name.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Name of object, relative to `loc_id`
  [out] | oinfo | Buffer in which to return object information
  [in] | fields | Flags specifying the fields to include in `oinfo`
  [in] | lapl_id | Link access property list identifier

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 the function H5Oget_info_by_name3() or the macro H5Oget_info_by_name().

H5Oget_info_by_name2() specifies an object's location and name, `loc_id` and `name`, respectively, and retrieves the metadata describing that object in `oinfo`, an H5O_info1_t `struct`.

The `struct` H5O_info1_t is defined in H5Opublic.h and described in the H5Oget_info1() function entry.

The `fields` parameter contains flags to determine which fields will be filled in the H5O_info1_t `struct` returned in `oinfo`. These flags are defined in the H5Opublic.h file:

Flag | Purpose
--- | ---
H5O_INFO_BASIC | Fill in the fileno, addr, type, and rc fields
H5O_INFO_TIME | Fill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS | Fill in the num_attrs field
H5O_INFO_HDR | Fill in the num_attrs field
H5O_INFO_META_SIZE | Fill in the meta_size field
H5O_INFO_ALL | H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE

The link access property list, `lapl_id`, is not currently used; it should be passed in as H5P_DEFAULT.

Since
  1.10.3

## ◆ H5Oget_info_by_name3()

herr_t H5Oget_info_by_name3 | ( | hid_t | loc_id,
|  | const char * | name,
|  | H5O_info2_t * | oinfo,
|  | unsigned | fields,
|  | hid_t | lapl_id )

Retrieves the metadata for an object, identifying the object by location and relative name.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Name of object, relative to `loc_id`
  [out] | oinfo | Buffer in which to return object information
  [in] | fields | Flags specifying the fields to include in `oinfo`
  [in] | lapl_id | Link access property list identifier

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

H5Oget_info_by_name3() specifies an object's location and name, `loc_id` and `name`, respectively, and retrieves the metadata describing that object in `oinfo`, an H5O_info2_t struct.

The `fields` parameter contains flags to determine which fields will be filled in the H5O_info2_t `struct` returned in `oinfo`. These flags are defined in the H5Opublic.h file:

Flag | Purpose
--- | ---
H5O_INFO_BASIC | Fill in the fileno, addr, type, and rc fields
H5O_INFO_TIME | Fill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS | Fill in the num_attrs field
H5O_INFO_HDR | Fill in the num_attrs field
H5O_INFO_META_SIZE | Fill in the meta_size field
H5O_INFO_ALL | H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE

The link access property list, `lapl_id`, is not currently used; it should be passed in as H5P_DEFAULT.

Example
  An example snippet from test/vol.c:
  if (H5Oget_info_by_name3(fid, NATIVE_VOL_TEST_GROUP_NAME, &object_info, H5O_INFO_ALL, H5P_DEFAULT) < 0)
  TEST_ERROR;

Since
  1.12.0

## ◆ H5Oget_native_info()

herr_t H5Oget_native_info | ( | hid_t | loc_id,
|  | H5O_native_info_t * | oinfo,
|  | unsigned | fields )

Retrieve native file format information about an object.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [out] | oinfo | Buffer in which to return native object information
  [in] | fields | Flags to determine which fields in `oinfo` are filled in

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

H5Oget_native_info() retrieves the native file format information for an object specified by `loc_id`.

The `fields` parameter indicates which fields to fill in H5O_native_info_t. Possible values defined in H5Opublic.h are:

#define H5O_NATIVE_INFO_HDR 0x0008u
#define H5O_NATIVE_INFO_META_SIZE 0x0010u
#define H5O_NATIVE_INFO_ALL (H5O_NATIVE_INFO_HDR | H5O_NATIVE_INFO_META_SIZE)

Example
  An example snippet from test/tfile.c:

  ret = H5Oget_native_info(group, &ninfo, H5O_NATIVE_INFO_HDR);

Since
  1.12.0

## ◆ H5Oget_native_info_by_idx()

herr_t H5Oget_native_info_by_idx | ( | hid_t | loc_id,
|  | const char * | group_name,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | hsize_t | n,
|  | H5O_native_info_t * | oinfo,
|  | unsigned | fields,
|  | hid_t | lapl_id )

Retrieve native file format information about an object according to the order of an index.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | group_name | Name of group in which object is located
  [in] | idx_type | Index type
  [in] | order | Iteration order
  [in] | n | Position within the index
  [out] | oinfo | Buffer in which to return native object information
  [in] | fields | Flags to determine which fields in `oinfo` are filled in
  [in] | lapl_id | Link access property list identifier

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

H5Oget_native_info_by_idx() retrieves the native file format information for an object specified by `loc_id`, group name, `group_name`, the index by which objects in the group are tracked, `idx_type`, the order by which the index is to be traversed, `order` , and an object's position `n` within that index.

The `fields` parameter indicates which fields to fill in H5O_native_info_t. Possible values defined in H5Opublic.h are:

#define H5O_NATIVE_INFO_HDR 0x0008u
#define H5O_NATIVE_INFO_META_SIZE 0x0010u
#define H5O_NATIVE_INFO_ALL (H5O_NATIVE_INFO_HDR | H5O_NATIVE_INFO_META_SIZE)

The link access property list, `lapl_id`, is not currently used; it should be passed in as H5P_DEFAULT.

Since
  1.12.0

## ◆ H5Oget_native_info_by_name()

herr_t H5Oget_native_info_by_name | ( | hid_t | loc_id,
|  | const char * | name,
|  | H5O_native_info_t * | oinfo,
|  | unsigned | fields,
|  | hid_t | lapl_id )

Retrieve native file format information about an object given its name.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Name of object
  [out] | oinfo | Buffer in which to return native object information
  [in] | fields | Flags to determine which fields in `oinfo` are filled in
  [in] | lapl_id | Link access property list identifier

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

H5Oget_native_info_by_name() retrieves the native file format information for an object specified by `loc_id` and the name `name`.

The `fields` parameter which fields to fill in H5O_native_info_t. Possible values defined in H5Opublic.h are:

#define H5O_NATIVE_INFO_HDR 0x0008u
#define H5O_NATIVE_INFO_META_SIZE 0x0010u
#define H5O_NATIVE_INFO_ALL (H5O_NATIVE_INFO_HDR | H5O_NATIVE_INFO_META_SIZE)

Example
  An example snippet from test/tfile.c:
  /*
  * Make sure the root group still has the correct object header version
  */
  ret = H5Oget_native_info_by_name(file, "/", &ninfo, H5O_NATIVE_INFO_HDR, H5P_DEFAULT);

Since
  1.12.0

## ◆ H5Oincr_refcount()

herr_t H5Oincr_refcount | ( | hid_t | object_id | ) |

Increments an object reference count.

Parameters

  [in] | object_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.

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

H5Oincr_refcount() increments the hard link reference count for an object. It should be used any time a user-defined link that references an object by address is added. When the link is deleted, H5Odecr_refcount() should be used.

An object's reference count is the number of hard links in the file that point to that object. See the “Programming Model” section of the HDF5 Groups chapter in the – HDF5 User Guide for a complete discussion of reference counts.

If a user application needs to determine an object's reference count, an H5Oget_info() call is required; the reference count is returned in the `rc` field of the H5O_info_t `struct`.

Warning
  This function must be used with care!
  Improper use can lead to inaccessible data, wasted space in the file, or file corruption.

Version
  1.8.11 Fortran subroutine introduced in this release.

Since
  1.8.0

## ◆ H5Olink()

herr_t H5Olink | ( | hid_t | obj_id,
|  | hid_t | new_loc_id,
|  | const char * | new_name,
|  | hid_t | lcpl_id,
|  | hid_t | lapl_id )

Creates a hard link to an object in an HDF5 file.

Parameters

  [in] | obj_id | Object to be linked
  [in] | new_loc_id | Location identifier at which object is to be linked; may be a file, group, dataset, named datatype or attribute identifier.
  [in] | new_name | Name of link to be created, relative to `new_loc_id`.
  [in] | lcpl_id | Link creation property list identifier
  [in] | lapl_id | Link access property list identifier

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

H5Olink() creates a new hard link to an object in an HDF5 file. `new_loc_id` and ``new_link_name` specify` the location and name of the new link, while `object_id` identifies the object that the link points to.

H5Olink() is designed for two purposes:

- To create the first hard link to an object that has just been created with H5Dcreate_anon(), H5Gcreate_anon(), or H5Tcommit_anon().
- To add additional structure to an existing file so that, for example, an object can be shared among multiple groups.

`lcpl` and `lapl` are the link creation and access property lists associated with the new link.

Example:
  To create a new link to an object while simultaneously creating missing intermediate groups: Suppose that an application must create the group C with the path /A/B01/C but may not know at run time whether the groups A and B01 exist. The following code ensures that those groups are created if they are missing:

  // Creates a link creation property list (LCPL).
  hid_t lcpl_id = H5Pcreate(H5P_LINK_CREATE);
  // Sets "create missing intermediate groups" property in that LCPL.
  int status = H5Pset_create_intermediate_group(lcpl_id, true);
  // Creates a group without linking it into the file structure.
  hid_t gid = H5Gcreate_anon(file_id, H5P_DEFAULT, H5P_DEFAULT);
  // Links group into file structure.
  status = H5Olink(gid, file_id, "/A/B01/C", lcpl_id, H5P_DEFAULT);
  hid_t
  int64_t hid_t
  Definition H5Ipublic.h:60
  H5P_LINK_CREATE
  #define H5P_LINK_CREATE
  Definition H5Ppublic.h:116
  H5P_DEFAULT
  #define H5P_DEFAULT
  Definition H5Ppublic.h:220
  H5Gcreate_anon
  hid_t H5Gcreate_anon(hid_t loc_id, hid_t gcpl_id, hid_t gapl_id)
  Creates a new empty group without linking it into the file structure.
  H5Olink
  herr_t H5Olink(hid_t obj_id, hid_t new_loc_id, const char *new_name, hid_t lcpl_id, hid_t lapl_id)
  Creates a hard link to an object in an HDF5 file.
  H5Pset_create_intermediate_group
  herr_t H5Pset_create_intermediate_group(hid_t plist_id, unsigned crt_intmd)
  Specifies in property list whether to create missing intermediate groups.
  H5Pcreate
  hid_t H5Pcreate(hid_t cls_id)
  Creates a new property list as an instance of a property list class.

  Note that unless the object is intended to be temporary, the H5O_LINK call is mandatory if an object created with one of the H5*_CREATE_ANON functions (or with H5T_COMMIT_ANON) is to be retained in the file; without an H5O_LINK call, the object will not be linked into the HDF5 file structure and will be deleted when the file is closed.

Version
  1.8.1 Fortran subroutine introduced in this release.

Since
  1.8.0

## ◆ H5Oopen()

hid_t H5Oopen | ( | hid_t | loc_id,
|  | const char * | name,
|  | hid_t | lapl_id )

Opens an object in an HDF5 file by location identifier and path name.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Path to the object; relative to `loc_id`
  [in] | lapl_id | Link access property list identifier

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

H5Oopen() opens a group, dataset, or committed (named) datatype specified by a location, `loc_id`, and a path name, `name`, in an HDF5 file.

This function opens the object in the same manner as H5Gopen(), H5Topen(), and H5Dopen(). However, H5Oopen() does not require the type of object to be known beforehand. This can be useful with user-defined links, for instance, when only a path may be known.

H5Oopen() cannot be used to open a dataspace, attribute, property list, or file.

Once an object of an unknown type has been opened with H5Oopen(), the type of that object can be determined by means of an H5Iget_type() call.

`loc_id` may be a file, group, dataset, named datatype, or attribute. If an attribute is specified for `loc_id` then the object where the attribute is attached will be accessed.

`name` must be the path to that object relative to `loc_id`.

`lapl_id` is the link access property list associated with the link pointing to the object. If default link access properties are appropriate, this can be passed in as H5P_DEFAULT.

When it is no longer needed, the opened object should be closed with H5Oclose(), H5Gclose(), H5Tclose(), or H5Dclose().

Version
  1.8.1 Fortran subroutine introduced in this release.

Since
  1.8.0

## ◆ H5Oopen_by_addr()

hid_t H5Oopen_by_addr | ( | hid_t | loc_id,
|  | haddr_t | addr )

Opens an object using its address within an HDF5 file.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | addr | Object's address in the file

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

Deprecated
  As of HDF5-1.12 this function has been deprecated in favor of the function H5Oopen_by_token().

H5Oopen_by_addr() opens a group, dataset, or committed (named) datatype using its address within an HDF5 file, `addr`. The resulting opened object is identical to an object opened with H5Oopen() and should be closed with H5Oclose() or an object-type-specific closing function (such as H5Gclose()) when no longer needed.

`loc_id` is a location identifier in the file.

The object's address within the file, `addr`, is the byte offset of the first byte of the object header from the beginning of the HDF5 file space, i.e., from the beginning of the superblock (see the “HDF5 Storage Model” section of the The HDF5 Data Model and File Structure chapter of the HDF5 User's Guide.)

`addr` can be obtained via either of two function calls. H5Gget_objinfo() returns the object's address in the `objno` field of the H5G_stat_t `struct`; H5Lget_info() returns the address in the `address` field of the H5L_info_t `struct`.

The address of the HDF5 file on a physical device has no effect on H5Oopen_by_addr(), nor does the use of any file driver. As stated above, the object address is its offset within the HDF5 file; HDF5's file drivers will transparently map this to an address on a storage device.

Warning
  This function must be used with care!
  Improper use can lead to inaccessible data, wasted space in the file, or file corruption.
  This function is dangerous if called on an invalid address. The risk can be safely overcome by retrieving the object address with H5Gget_objinfo() or H5Lget_info() immediately before calling H5Oopen_by_addr(). The immediacy of the operation can be important; if time has elapsed and the object has been deleted from the file, the address will be invalid, and file corruption can result.

Version
  1.8.4 Fortran subroutine added in this release.

Since
  1.8.0

## ◆ H5Oopen_by_idx()

hid_t H5Oopen_by_idx | ( | hid_t | loc_id,
|  | const char * | group_name,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | hsize_t | n,
|  | hid_t | lapl_id )

Opens the nth object in a group.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | group_name | Name of group, relative to `loc_id`, in which object is located
  [in] | idx_type | Index type
  [in] | order | Iteration order
  [in] | n | Object to open
  [in] | lapl_id | Link access property list identifier

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

H5Oopen_by_idx() opens the nth object in the group specified by `loc_id` and `group_name`.

`loc_id` specifies a location identifier. `group_name` specifies the group relative to `loc_id` in which the object can be found. If `loc_id` fully specifies the group in which the object resides, `group_name` can be a dot (.).

The specific object to be opened within the group is specified by the three parameters: `idx_type`, `order` and `n`.

`idx_type` specifies the type of index by which objects are ordered. Valid index types include the following:

H5_INDEX_NAME | Lexicographic order on name
H5_INDEX_CRT_ORDER | Index on creation order

`order` specifies the order in which the objects are to be referenced for the purposes of this function. Valid orders include the following:

H5_ITER_INC | Increasing order
H5_ITER_DEC | Decreasing order
H5_ITER_NATIVE | Fastest available order

Note that for H5_ITER_NATIVE, rather than implying a particular order, it instructs the HDF5 library to iterate through the objects in the fastest available order, i.e., in a natural order.

`n` specifies the position of the object within the index. Note that this count is zero-based; 0 (zero) indicates that the function will return the value of the first object; if `n` is 5, the function will return the value of the sixth object; etc.

`lapl_id` specifies the link access property list to be used in accessing the object.

An object opened with this function should be closed when it is no longer needed so that resource leaks will not develop. H5Oclose() can be used to close groups, datasets, or committed datatypes.

Version
  1.8.1 Fortran subroutine introduced in this release.

Since
  1.8.0

## ◆ H5Oopen_by_token()

hid_t H5Oopen_by_token | ( | hid_t | loc_id,
|  | H5O_token_t | token )

Opens an object in an HDF5 file using its VOL independent token.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | token | Object token

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

H5Oopen_by_token() opens an object specified by the object identifier, `loc_id` and object token, `token`.

Since
  1.12.0

## ◆ H5Orefresh()

herr_t H5Orefresh | ( | hid_t | oid | ) |

Refreshes all buffers associated with an HDF5 object.

Parameters

  [in] | oid | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.

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

H5Orefresh() causes all buffers associated with an object to be cleared and immediately re-loaded with updated contents from disk.

This function essentially closes the object, evicts all metadata associated with it from the cache, and then re-opens the object. The reopened object is automatically re-registered with the same identifier.

The object associated with `oid` can be any named object in an HDF5 file including a dataset, a group, or a committed datatype.

Since
  1.10.0

## ◆ H5Oset_comment()

herr_t H5Oset_comment | ( | hid_t | obj_id,
|  | const char * | comment )

Sets comment for specified object.

Parameters

  [in] | obj_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | comment | The new comment

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

H5Oset_comment() sets the comment for the specified object to the contents of `comment`. Any previously existing comment is overwritten.

The target object is specified by an identifier, `obj_id`. If `comment` is an empty string or a null pointer, any existing comment message is removed from the object.

Comments should be relatively short, null-terminated, ASCII strings.

Comments can be attached to any object that has an object header. Datasets, groups, and committed (named) datatypes have object headers. Symbolic links do not have object headers.

If a comment is being added to an object attribute, this comment will be attached to the object to which the attribute belongs and not to the attribute itself.

Version
  1.8.11 Fortran subroutine introduced in this release.

Since
  1.8.0

## ◆ H5Oset_comment_by_name()

herr_t H5Oset_comment_by_name | ( | hid_t | loc_id,
|  | const char * | name,
|  | const char * | comment,
|  | hid_t | lapl_id )

Sets comment for specified object.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | name | Name of the object whose comment is to be set or reset
  [in] | comment | The new comment
  [in] | lapl_id | Link access property list identifier

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

H5Oset_comment_by_name() sets the comment for the specified object to the contents of `comment`. Any previously existing comment is overwritten.

The target object is specified by `loc_id` and `name`. `loc_id` can specify any object in the file. `name` can be one of the following:

- The name of the object specified as a path relative to `loc_id`
- An absolute name of the object, starting from `/`, the file's root group
- A dot (``.), if `loc_id` fully specifies the object

If `comment` is an empty string or a null pointer, any existing comment message is removed from the object.

Comments should be relatively short, null-terminated, ASCII strings.

Comments can be attached to any object that has an object header. Datasets, groups, and committed (named) datatypes have object headers. Symbolic links do not have object headers.

If a comment is being added to an object attribute, this comment will be attached to the object to which the attribute belongs and not to the attribute itself.

`lapl_id` contains a link access property list identifier. A link access property list can come into play when traversing links to access an object.

Version
  1.8.11 Fortran subroutine introduced in this release.

Since
  1.8.0

## ◆ H5Otoken_cmp()

herr_t H5Otoken_cmp | ( | hid_t | loc_id,
|  | const H5O_token_t * | token1,
|  | const H5O_token_t * | token2,
|  | int * | cmp_value )

Compares two VOL connector object tokens.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | token1 | First object token
  [in] | token2 | Second object token
  [out] | cmp_value | Comparison value

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

H5Otoken_cmp() compares two VOL connector object tokens, `token1` and `token2` for the file or group identifier specified by `loc_id`. Both object tokens must be from the same VOL connector class.

H5O_token_t is defined in H5public.h as follows:

typedef struct H5O_token_t {
uint8_t __data[H5O_MAX_TOKEN_SIZE];
} H5O_token_t;

A comparison value, `cmp_value`, is returned, which indicates the result of the comparison:

cmp_value | Result
--- | ---
> 0 | `token1` > `token2`
< 0 | `token1` < `token2`
0 | `token1` = `token2`

Example
  An example snippet from test/links.c:
  if (H5Otoken_cmp(file, &oinfo1.token, &oinfo2.token, &token_cmp) < 0)
  FAIL_STACK_ERROR;
  if (token_cmp) {
  H5_FAILED();
  puts(" Hard link test failed. Link seems not to point to the ");
  puts(" expected file location.");
  TEST_ERROR;
  } /* end if */

Since
  1.12.0

## ◆ H5Otoken_from_str()

herr_t H5Otoken_from_str | ( | hid_t | loc_id,
|  | const char * | token_str,
|  | H5O_token_t * | token )

Deserializes a string into a connector object token.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | token_str | Object token string
  [out] | token | Connector object token

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

H5Otoken_from_str() deserializes a string, `token_str`, into a connector object token, `token`, for the object specified by the location identifier, `loc_id`.

Since
  1.12.0

## ◆ H5Otoken_to_str()

herr_t H5Otoken_to_str | ( | hid_t | loc_id,
|  | const H5O_token_t * | token,
|  | char ** | token_str )

Serializes a connector's object token into a string.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | token | Connector object token
  [out] | token_str | String for connector object token `token`

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

H5Otoken_to_str() serializes a connector's object token specified by `token` and the location identifier for the object, `loc_id`, into a string, `token_str`.

Since
  1.12.0

## ◆ H5Ovisit1()

herr_t H5Ovisit1 | ( | hid_t | obj_id,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | H5O_iterate1_t | op,
|  | void * | op_data )

Recursively visits all objects accessible from a specified object.

Parameters

  [in] | obj_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | idx_type | Index type
  [in] | order | Iteration order
  [in] | op | Callback function passing data regarding the object to the calling application
  [in] | op_data | User-defined pointer to data required by the application for its processing of the object

Returns
  On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.
  On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

Deprecated
  As of HDF5-1.12 this function has been deprecated in favor of the function H5Ovisit3() or the macro H5Ovisit.

H5Ovisit1() is a recursive iteration function to visit the object `obj_id` and, if `obj_id` is a group, all objects in and below it in an HDF5 file, thus providing a mechanism for an application to perform a common set of operations across all of those objects or a dynamically selected subset. For non-recursive iteration across the members of a group, see H5Literate1().

If `obj_id` is a group identifier, that group serves as the root of a recursive iteration. If `obj_id` is a file identifier, that file's root group serves as the root of the recursive iteration. If `obj_id` is an attribute identifier, then the object where the attribute is attached will be iterated. If `obj_id` is any other type of object, such as a dataset or named datatype, there is no iteration.

Two parameters are used to establish the iteration: `idx_type` and `order`.

`idx_type` specifies the index to be used. If the links in a group have not been indexed by the index type, they will first be sorted by that index then the iteration will begin; if the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly.

Note that the index type passed in `idx_type` is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alphanumeric order by name, or name order. (Name order is the native order used by the HDF5 library and is always available.)

`order` specifies the order in which objects are to be inspected along the index specified in `idx_type`.

H5Lvisit1() and H5Ovisit1() are companion functions: one for examining and operating on links; the other for examining and operating on the objects that those links point to. Both functions ensure that by the time the function completes successfully, every link or object below the specified point in the file has been presented to the application for whatever processing the application requires. These functions assume that the membership of the group being iterated over remains unchanged through the iteration; if any of the links in the group change during the iteration, the resulting behavior is undefined.

Version
  1.10.5 The macro H5Ovisit was removed and the function H5Ovisit1() was copied to H5Ovisit().
  1.10.3 Function H5Ovisit() was copied to H5Ovisit1(), and the macro H5Ovisit was created.
  1.8.8 Fortran subroutine introduced in this release.

Since
  1.8.0

## ◆ H5Ovisit2()

herr_t H5Ovisit2 | ( | hid_t | obj_id,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | H5O_iterate1_t | op,
|  | void * | op_data,
|  | unsigned | fields )

Recursively visits all objects accessible from a specified object.

Parameters

  [in] | obj_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | idx_type | Index type
  [in] | order | Iteration order
  [in] | op | Callback function passing data regarding the object to the calling application
  [in] | op_data | User-defined pointer to data required by the application for its processing of the object
  [in] | fields | Flags specifying the fields to be retrieved to the callback `op`

Returns
  On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.
  On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

Deprecated
  As of HDF5-1.12 this function has been deprecated in favor of the function H5Ovisit3() or the macro H5Ovisit.

H5Ovisit2() is a recursive iteration function to visit the object `obj_id` and, if `obj_id` is a group, all objects in and below it in an HDF5 file, thus providing a mechanism for an application to perform a common set of operations across all of those objects or a dynamically selected subset. For non-recursive iteration across the members of a group, see H5Literate1().

If `obj_id` is a group identifier, that group serves as the root of a recursive iteration. If `obj_id` is a file identifier, that file's root group serves as the root of the recursive iteration. If `obj_id` is an attribute identifier, then the object where the attribute is attached will be iterated. If `obj_id` is any other type of object, such as a dataset or named datatype, there is no iteration.

Two parameters are used to establish the iteration: `idx_type` and `order`.

`idx_type` specifies the index to be used. If the links in a group have not been indexed by the index type, they will first be sorted by that index then the iteration will begin; if the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly.

Note that the index type passed in `idx_type` is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alphanumeric order by name, or name order. (Name order is the native order used by the HDF5 library and is always available.)

`order` specifies the order in which objects are to be inspected along the index specified in `idx_type`.

The `fields` parameter contains flags to determine which fields will be retrieved by the `op` callback function. These flags are defined in the H5Opublic.h file:

Flag | Purpose
--- | ---
H5O_INFO_BASIC | Fill in the fileno, addr, type, and rc fields
H5O_INFO_TIME | Fill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS | Fill in the num_attrs field
H5O_INFO_HDR | Fill in the num_attrs field
H5O_INFO_META_SIZE | Fill in the meta_size field
H5O_INFO_ALL | H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE

H5Lvisit() and H5Ovisit() are companion functions: one for examining and operating on links; the other for examining and operating on the objects that those links point to. Both functions ensure that by the time the function completes successfully, every link or object below the specified point in the file has been presented to the application for whatever processing the application requires. These functions assume that the membership of the group being iterated over remains unchanged through the iteration; if any of the links in the group change during the iteration, the resulting behavior is undefined.

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.10.3

## ◆ H5Ovisit3()

herr_t H5Ovisit3 | ( | hid_t | obj_id,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | H5O_iterate2_t | op,
|  | void * | op_data,
|  | unsigned | fields )

Recursively visits all objects accessible from a specified object.

Parameters

  [in] | obj_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | idx_type | Index type
  [in] | order | Iteration order
  [in] | op | Callback function passing data regarding the object to the calling application
  [in] | op_data | User-defined pointer to data required by the application for its processing of the object
  [in] | fields | Flags specifying the fields to be retrieved to the callback `op`

Returns
  On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.
  On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

H5Ovisit3() is a recursive iteration function to visit the object `obj_id` and, if `obj_id` is a group, all objects in and below it in an HDF5 file, thus providing a mechanism for an application to perform a common set of operations across all of those objects or a dynamically selected subset. For non-recursive iteration across the members of a group, see H5Literate2().

If `obj_id` is a group identifier, that group serves as the root of a recursive iteration. If `obj_id` is a file identifier, that file's root group serves as the root of the recursive iteration. If `obj_id` is an attribute identifier, then the object where the attribute is attached will be iterated. If `obj_id` is any other type of object, such as a dataset or named datatype, there is no iteration.

Two parameters are used to establish the iteration: `idx_type` and `order`.

`idx_type` specifies the index to be used. If the links in a group have not been indexed by the index type, they will first be sorted by that index then the iteration will begin; if the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly.

Note that the index type passed in `idx_type` is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alphanumeric order by name, or name order. (Name order is the native order used by the HDF5 library and is always available.)

`order` specifies the order in which objects are to be inspected along the index specified in `idx_type`.

The H5Ovisit3() `op_data` parameter is a user-defined pointer to the data required to process objects in the course of the iteration. This pointer is passed back to each step of the iteration in the callback function's `op_data` parameter.

The `fields` parameter contains flags to determine which fields will be retrieved by the `op` callback function. These flags are defined in the H5Opublic.h file:

Flag | Purpose
--- | ---
H5O_INFO_BASIC | Fill in the fileno, addr, type, and rc fields
H5O_INFO_TIME | Fill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS | Fill in the num_attrs field
H5O_INFO_HDR | Fill in the num_attrs field
H5O_INFO_META_SIZE | Fill in the meta_size field
H5O_INFO_ALL | H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE

H5Lvisit2() and H5Ovisit3() are companion functions: one for examining and operating on links; the other for examining and operating on the objects that those links point to. Both functions ensure that by the time the function completes successfully, every link or object below the specified point in the file has been presented to the application for whatever processing the application requires. These functions assume that the membership of the group being iterated over remains unchanged through the iteration; if any of the links in the group change during the iteration, the resulting behavior is undefined.

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.

Example
  An example snippet from test/links.c:
  /* Visit all the objects reachable from the root group (with file ID) */
  udata.idx = 0;
  udata.info = new_format ? ovisit0_new : ovisit0_old;
  if (H5Ovisit3(fid, H5_INDEX_NAME, H5_ITER_INC, visit_obj_cb, &udata, H5O_INFO_BASIC) < 0)
  FAIL_STACK_ERROR;

Since
  1.12.0

## ◆ H5Ovisit_by_name1()

herr_t H5Ovisit_by_name1 | ( | hid_t | loc_id,
|  | const char * | obj_name,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | H5O_iterate1_t | op,
|  | void * | op_data,
|  | hid_t | lapl_id )

Recursively visits all objects starting from a specified object.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | obj_name | Name of the object, generally relative to `loc_id`, that will serve as root of the iteration
  [in] | idx_type | Index type
  [in] | order | Iteration order
  [in] | op | Callback function passing data regarding the object to the calling application
  [in] | op_data | User-defined pointer to data required by the application for its processing of the object
  [in] | lapl_id | Link access property list identifier

Returns
  On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.
  On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

Deprecated
  As of HDF5-1.12 this function has been deprecated in favor of the function H5Ovisit_by_name3() or the macro H5Ovisit_by_name.

H5Ovisit_by_name1() is a recursive iteration function to visit the object specified by the `loc_id` / `obj_name` parameter pair and, if that object is a group, all objects in and below it in an HDF5 file, thus providing a mechanism for an application to perform a common set of operations across all of those objects or a dynamically selected subset. For non-recursive iteration across the members of a group, see H5Literate1().

The object serving as the root of the iteration is specified by the `loc_id` / `obj_name` parameter pair. `loc_id` specifies a file or an object in a file; if `loc_id` is an attribute identifier, the object where the attribute is attached will be used. `obj_name` specifies either an object in the file (with an absolute name based on the file's root group) or an object name relative to `loc_id`. If `loc_id` fully specifies the object that is to serve as the root of the iteration, `obj_name` should be '``.' (a dot). (Note that when `loc_id` fully specifies the object that is to serve as the root of the iteration, the user may wish to consider using H5Ovisit1() instead of H5Ovisit_by_name1().)

Two parameters are used to establish the iteration: `idx_type` and `order`.

`idx_type` specifies the index to be used. If the links in a group have not been indexed by the index type, they will first be sorted by that index then the iteration will begin; if the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly.

Note that the index type passed in `idx_type` is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alphanumeric order by name, or name order. (Name order is the native order used by the HDF5 library and is always available.)

`order` specifies the order in which objects are to be inspected along the index specified in `idx_type`.

The `op` callback function and the effect of the callback function's return value on the application are described in H5Ovisit1().

The H5O_info1_t `struct` is defined in H5Opublic.h and described in the H5Oget_info1() function entry.

The H5Ovisit_by_name1() `op_data` parameter is a user-defined pointer to the data required to process objects in the course of the iteration. This pointer is passed back to each step of the iteration in the callback function's `op_data` parameter.

`lapl_id` is a link access property list. In the general case, when default link access properties are acceptable, this can be passed in as H5P_DEFAULT. An example of a situation that requires a non-default link access property list is when the link is an external link; an external link may require that a link prefix be set in a link access property list (see H5Pset_elink_prefix()).

H5Lvisit_by_name1() and H5Ovisit_by_name1() are companion functions: one for examining and operating on links; the other for examining and operating on the objects that those links point to. Both functions ensure that by the time the function completes successfully, every link or object below the specified point in the file has been presented to the application for whatever processing the application requires.

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.

Version
  1.10.5 The macro H5Ovisit_by_name was removed and the function H5Ovisit_by_name1() was copied to H5Ovisit_by_name.
  1.10.3 The H5Ovisit_by_name() function was renamed to H5Ovisit_by_name1(), and the macro H5Ovisit_by_name was created.
  1.8.11 Fortran subroutine introduced in this release.

Since
  1.8.0

## ◆ H5Ovisit_by_name2()

herr_t H5Ovisit_by_name2 | ( | hid_t | loc_id,
|  | const char * | obj_name,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | H5O_iterate1_t | op,
|  | void * | op_data,
|  | unsigned | fields,
|  | hid_t | lapl_id )

Recursively visits all objects starting from a specified object.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | obj_name | Name of the object, generally relative to `loc_id`, that will serve as root of the iteration
  [in] | idx_type | Index type
  [in] | order | Iteration order
  [in] | op | Callback function passing data regarding the object to the calling application
  [in] | op_data | User-defined pointer to data required by the application for its processing of the object
  [in] | fields | Flags specifying the fields to be retrieved to the callback function `op`
  [in] | lapl_id | Link access property list identifier

Returns
  On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.
  On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

Deprecated
  As of HDF5-1.12 this function has been deprecated in favor of the function H5Ovisit_by_name3() or the macro H5Ovisit_by_name.

H5Ovisit_by_name2() is a recursive iteration function to visit the object specified by the `loc_id` / `obj_name` parameter pair and, if that object is a group, all objects in and below it in an HDF5 file, thus providing a mechanism for an application to perform a common set of operations across all of those objects or a dynamically selected subset. For non-recursive iteration across the members of a group, see H5Literate.

The object serving as the root of the iteration is specified by the `loc_id` / `obj_name` parameter pair. `loc_id` specifies a file or an object in a file; if `loc_id` is an attribute identifier, the object where the attribute is attached will be used. `obj_name` specifies either an object in the file (with an absolute name based in the file's root group) or an object name relative to `loc_id`. If `loc_id` fully specifies the object that is to serve as the root of the iteration, `obj_name` should be '``.' (a dot). (Note that when `loc_id` fully specifies the object that is to serve as the root of the iteration, the user may wish to consider using H5Ovisit2() instead of H5Ovisit_by_name.)

Two parameters are used to establish the iteration: `idx_type` and `order`.

`idx_type` specifies the index to be used. If the links in a group have not been indexed by the index type, they will first be sorted by that index then the iteration will begin; if the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly.

Note that the index type passed in `idx_type` is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alphanumeric order by name, or name order. (Name order is the native order used by the HDF5 library and is always available.)

`order` specifies the order in which objects are to be inspected along the index specified in `idx_type`.

The `op` callback function and the effect of the callback function's return value on the application are described in H5Ovisit2().

The H5O_info1_t `struct` is defined in H5Opublic.h and described in the H5Oget_info1() function entry.

The H5Ovisit_by_name2() `op_data` parameter is a user-defined pointer to the data required to process objects in the course of the iteration. This pointer is passed back to each step of the iteration in the callback function's `op_data` parameter.

`lapl_id` is a link access property list. In the general case, when default link access properties are acceptable, this can be passed in as H5P_DEFAULT. An example of a situation that requires a non-default link access property list is when the link is an external link; an external link may require that a link prefix be set in a link access property list (see H5Pset_elink_prefix()).

The `fields` parameter contains flags to determine which fields will be retrieved by the `op` callback function. These flags are defined in the H5Opublic.h file:

Flag | Purpose
--- | ---
H5O_INFO_BASIC | Fill in the fileno, addr, type, and rc fields
H5O_INFO_TIME | Fill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS | Fill in the num_attrs field
H5O_INFO_HDR | Fill in the num_attrs field
H5O_INFO_META_SIZE | Fill in the meta_size field
H5O_INFO_ALL | H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE

H5Lvisit_by_name and H5Ovisit_by_name are companion functions: one for examining and operating on links; the other for examining and operating on the objects that those links point to. Both functions ensure that by the time the function completes successfully, every link or object below the specified point in the file has been presented to the application for whatever processing the application requires.

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.10.3

## ◆ H5Ovisit_by_name3()

herr_t H5Ovisit_by_name3 | ( | hid_t | loc_id,
|  | const char * | obj_name,
|  | H5_index_t | idx_type,
|  | H5_iter_order_t | order,
|  | H5O_iterate2_t | op,
|  | void * | op_data,
|  | unsigned | fields,
|  | hid_t | lapl_id )

Recursively visits all objects accessible from a specified object.

Parameters

  [in] | loc_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
  [in] | obj_name | Name of the object, generally relative to `loc_id`, that will serve as root of the iteration
  [in] | idx_type | Index type
  [in] | order | Iteration order
  [in] | op | Callback function passing data regarding the object to the calling application
  [in] | op_data | User-defined pointer to data required by the application for its processing of the object
  [in] | fields | Flags specifying the fields to be retrieved to the callback function `op`
  [in] | lapl_id | Link access property list identifier

Returns
  On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.
  On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

H5Ovisit_by_name3() is a recursive iteration function to visit the object specified by the `loc_id` / `obj_name` parameter pair and, if that object is a group, all objects in and below it in an HDF5 file, thus providing a mechanism for an application to perform a common set of operations across all of those objects or a dynamically selected subset. For non-recursive iteration across the members of a group, see H5Literate2().

The object serving as the root of the iteration is specified by the `loc_id` / `obj_name` parameter pair. `loc_id` specifies a file or an object in a file; if `loc_id` is an attribute identifier, the object where the attribute is attached will be used. `obj_name` specifies either an object in the file (with an absolute name based on the file's root group) or an object name relative to `loc_id`. If `loc_id` fully specifies the object that is to serve as the root of the iteration, `obj_name` should be '``.' (a dot). (Note that when `loc_id` fully specifies the object that is to serve as the root of the iteration, the user may wish to consider using H5Ovisit3() instead of H5Ovisit_by_name3().)

Two parameters are used to establish the iteration: `idx_type` and `order`.

`idx_type` specifies the index to be used. If the links in a group have not been indexed by the index type, they will first be sorted by that index then the iteration will begin; if the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly.

Note that the index type passed in `idx_type` is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alphanumeric order by name, or name order. (Name order is the native order used by the HDF5 library and is always available.)

`order` specifies the order in which objects are to be inspected along the index specified in `idx_type`.

The H5Ovisit_by_name3() `op_data` parameter is a user-defined pointer to the data required to process objects in the course of the iteration. This pointer is passed back to each step of the iteration in the callback function's `op_data` parameter.

`lapl_id` is a link access property list. In the general case, when default link access properties are acceptable, this can be passed in as H5P_DEFAULT. An example of a situation that requires a non-default link access property list is when the link is an external link; an external link may require that a link prefix be set in a link access property list (see H5Pset_elink_prefix()).

The `fields` parameter contains flags to determine which fields will be retrieved by the `op` callback function. These flags are defined in the H5Opublic.h file:

Flag | Purpose
--- | ---
H5O_INFO_BASIC | Fill in the fileno, addr, type, and rc fields
H5O_INFO_TIME | Fill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS | Fill in the num_attrs field
H5O_INFO_HDR | Fill in the num_attrs field
H5O_INFO_META_SIZE | Fill in the meta_size field
H5O_INFO_ALL | H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE

H5Lvisit_by_name2() and H5Ovisit_by_name3() are companion functions: one for examining and operating on links; the other for examining and operating on the objects that those links point to. Both functions ensure that by the time the function completes successfully, every link or object below the specified point in the file has been presented to the application for whatever processing the application requires.

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.

Example
  An example snippet from test/links.c:
  /* Visit all the objects reachable from the root group (with file ID) */
  udata.idx = 0;
  udata.info = new_format ? ovisit0_new : ovisit0_old;
  if (H5Ovisit_by_name3(fid, "/", H5_INDEX_NAME, H5_ITER_INC, visit_obj_cb, &udata, H5O_INFO_BASIC,
  H5P_DEFAULT) < 0)
  FAIL_STACK_ERROR;

Since
  1.12.0