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

CreateRead
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 }
#define H5F_ACC_TRUNC
Definition H5Fpublic.h:50
int64_t hid_t
Definition H5Ipublic.h:60
#define H5I_INVALID_HID
Definition H5Ipublic.h:75
#define H5P_LINK_CREATE
Definition H5Ppublic.h:124
herr_t H5Fclose(hid_t file_id)
Terminates access to an HDF5 file.
hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id)
Creates an HDF5 file.
#define H5Gcreate
Definition H5version.h:821
herr_t H5Gclose(hid_t group_id)
Closes the specified group.
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 H5Pset_create_intermediate_group(hid_t plist_id, unsigned crt_intmd)
Specifies in property list whether to create missing intermediate groups.
herr_t H5Pclose(hid_t plist_id)
Terminates access to a property list.
hid_t H5Pcreate(hid_t cls_id)
Creates a new property list as an instance of a property list class.
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
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;
83 printf("HDF5 dataset\n");
84 break;
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 }
#define H5F_ACC_RDONLY
Definition H5Fpublic.h:48
#define H5O_INFO_NUM_ATTRS
Definition H5Opublic.h:83
@ H5O_TYPE_DATASET
Definition H5Opublic.h:110
@ H5O_TYPE_NAMED_DATATYPE
Definition H5Opublic.h:111
@ H5O_TYPE_GROUP
Definition H5Opublic.h:109
#define H5O_INFO_BASIC
Definition H5Opublic.h:81
#define H5P_DEFAULT
Definition H5Ppublic.h:228
hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id)
Opens an existing HDF5 file.
#define H5Oget_info_by_name
Definition H5version.h:947
Definition H5Opublic.h:145
unsigned rc
Definition H5Opublic.h:150
H5O_type_t type
Definition H5Opublic.h:149
hsize_t num_attrs
Definition H5Opublic.h:155
UpdateDelete
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 }
#define H5F_ACC_RDWR
Definition H5Fpublic.h:49
herr_t H5Oincr_refcount(hid_t object_id)
Increments an object reference count.
herr_t H5Oclose(hid_t object_id)
Closes 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.
#define H5Oget_info
Definition H5version.h:921
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 }
int H5Idec_ref(hid_t id)
Decrements the reference count for an object.
herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id)
Removes a link from a group.

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

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_token (hid_t loc_id, H5O_token_t token)
 Opens an object in an HDF5 file using its VOL independent token.
 
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.
 
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 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_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_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_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_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 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 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.
 
herr_t H5Oincr_refcount (hid_t object_id)
 Increments an object reference count.
 
herr_t H5Odecr_refcount (hid_t object_id)
 Decrements an object reference count.
 
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 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.
 
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 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_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.
 
herr_t H5Oclose (hid_t object_id)
 Closes an object in an HDF5 file.
 
herr_t H5Oflush (hid_t obj_id)
 Flushes all buffers associated with an HDF5 object to disk.
 
herr_t H5Orefresh (hid_t oid)
 Refreshes all buffers associated with an HDF5 object.
 
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.
 
herr_t H5Oare_mdc_flushes_disabled (hid_t object_id, hbool_t *are_disabled)
 Retrieves 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_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 H5Otoken_from_str (hid_t loc_id, const char *token_str, H5O_token_t *token)
 Deserializes a string into a connector object token.
 
hid_t H5Oopen_by_addr (hid_t loc_id, haddr_t addr)
 Opens an object using its address within an HDF5 file.
 
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_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_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_info2 (hid_t loc_id, H5O_info1_t *oinfo, unsigned fields)
 Retrieves the metadata for an object specified by an identifier.
 
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_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 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 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 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 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.
 

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_name

#define H5Oget_info_by_name   H5Oget_info_by_name3

◆ 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

Function Documentation

◆ H5Oare_mdc_flushes_disabled()

herr_t H5Oare_mdc_flushes_disabled ( hid_t  object_id,
hbool_t are_disabled 
)

Retrieves comment for specified object.


Parameters
[in]object_idIdentifier of an object in the cache; may be a group, named datatype, or dataset identifier
[out]are_disabledFlushes 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_idObject 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_idObject identifier indicating the location of the source object to be copied
[in]src_nameName of the source object to be copied
[in]dst_loc_idLocation identifier specifying the destination
[in]dst_nameName to be assigned to the new copy
[in]ocpypl_idObject copy property list
[in]lcpl_idLink 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:

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:
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_idLocation 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_idIdentifier 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_idIdentifier 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameThe name of the link to check
[in]lapl_idLink 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_idLocation 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[out]commentThe comment
[in]bufsizeAnticipated 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameName of the object whose comment is to be retrieved
[out]commentThe comment
[in]bufsizeAnticipated required size of the comment buffer
[in]lapl_idLink 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[out]oinfoBuffer 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[out]oinfoBuffer in which to return object information
[in]fieldsFlags 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:

FlagPurpose
H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS Fill in the num_attrs field
H5O_INFO_HDRFill in the num_attrs field
H5O_INFO_META_SIZEFill in the meta_size field
H5O_INFO_ALLH5O_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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[out]oinfoBuffer in which to return object information
[in]fieldsFlags 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:

FlagPurpose
H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS Fill in the num_attrs field
H5O_INFO_HDRFill in the num_attrs field
H5O_INFO_META_SIZEFill in the meta_size field
H5O_INFO_ALLH5O_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++) {
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);
}
@ H5T_STRING
Definition H5Tpublic.h:35
@ H5T_DIR_ASCEND
Definition H5Tpublic.h:159
@ H5_ITER_INC
Definition H5public.h:350
uint64_t hsize_t
Definition H5public.h:301
@ H5_INDEX_CRT_ORDER
Definition H5public.h:374
hid_t H5Aget_type(hid_t attr_id)
Gets an attribute's datatype.
herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf)
Reads the value of an attribute.
hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t aapl_id, hid_t lapl_id)
Opens the nth attribute attached to an object.
herr_t H5Aclose(hid_t attr_id)
Closes the specified attribute.
herr_t H5Oget_info3(hid_t loc_id, H5O_info2_t *oinfo, unsigned fields)
Retrieves the metadata for an object specified by an identifier.
hid_t H5Tget_native_type(hid_t type_id, H5T_direction_t direction)
Returns the native datatype identifier of a specified datatype.
H5T_class_t H5Tget_class(hid_t type_id)
Returns a datatype class.
herr_t H5Tclose(hid_t type_id)
Releases a datatype.
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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]group_nameName of group in which object is located
[in]idx_typeIndex type
[in]orderIteration order
[in]nPosition within the index
[out]oinfoBuffer in which to return object information
[in]lapl_idLink 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]group_nameName of group in which object is located
[in]idx_typeIndex type
[in]orderIteration order
[in]nPosition within the index
[out]oinfoBuffer in which to return object information
[in]fieldsFlags specifying the fields to include in oinfo
[in]lapl_idLink 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, igroup_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:

FlagPurpose
H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS Fill in the num_attrs field
H5O_INFO_HDRFill in the num_attrs field
H5O_INFO_META_SIZEFill in the meta_size field
H5O_INFO_ALLH5O_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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]group_nameName of group in which object is located
[in]idx_typeIndex type
[in]orderIteration order
[in]nPosition within the index
[out]oinfoBuffer in which to return object information
[in]fieldsFlags specifying the fields to include in oinfo
[in]lapl_idLink 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:

FlagPurpose
H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS Fill in the num_attrs field
H5O_INFO_HDRFill in the num_attrs field
H5O_INFO_META_SIZEFill in the meta_size field
H5O_INFO_ALLH5O_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,
CHECK(ret, FAIL, "H5Oget_info_by_idx");
@ H5_INDEX_NAME
Definition H5public.h:373
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.
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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameName of object, relative to loc_id
[out]oinfoBuffer in which to return object information
[in]lapl_idLink 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameName of object, relative to loc_id
[out]oinfoBuffer in which to return object information
[in]fieldsFlags specifying the fields to include in oinfo
[in]lapl_idLink 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:

FlagPurpose
H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS Fill in the num_attrs field
H5O_INFO_HDRFill in the num_attrs field
H5O_INFO_META_SIZEFill in the meta_size field
H5O_INFO_ALLH5O_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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameName of object, relative to loc_id
[out]oinfoBuffer in which to return object information
[in]fieldsFlags specifying the fields to include in oinfo
[in]lapl_idLink 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:

FlagPurpose
H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS Fill in the num_attrs field
H5O_INFO_HDRFill in the num_attrs field
H5O_INFO_META_SIZEFill in the meta_size field
H5O_INFO_ALLH5O_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;
#define H5O_INFO_ALL
Definition H5Opublic.h:84
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.
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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[out]oinfoBuffer in which to return native object information
[in]fieldsFlags 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);
#define H5O_NATIVE_INFO_HDR
Definition H5Opublic.h:91
herr_t H5Oget_native_info(hid_t loc_id, H5O_native_info_t *oinfo, unsigned fields)
Retrieve native file format information about an object.
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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]group_nameName of group in which object is located
[in]idx_typeIndex type
[in]orderIteration order
[in]nPosition within the index
[out]oinfoBuffer in which to return native object information
[in]fieldsFlags to determine which fields in oinfo are filled in
[in]lapl_idLink 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameName of object
[out]oinfoBuffer in which to return native object information
[in]fieldsFlags to determine which fields in oinfo are filled in
[in]lapl_idLink 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
*/
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.
Since
1.12.0

◆ H5Oincr_refcount()

herr_t H5Oincr_refcount ( hid_t  object_id)

Increments an object reference count.


Parameters
[in]object_idLocation 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_idObject to be linked
[in]new_loc_idLocation identifier at which object is to be linked; may be a file, group, dataset, named datatype or attribute identifier.
[in]new_nameName of link to be created, relative to new_loc_id.
[in]lcpl_idLink creation property list identifier
[in]lapl_idLink 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).
// 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.
// Links group into file structure.
status = H5Olink(gid, file_id, "/A/B01/C", lcpl_id, H5P_DEFAULT);
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.
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.
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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]namePath to the object; relative to loc_id
[in]lapl_idLink 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]addrObject'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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]group_nameName of group, relative to loc_id, in which object is located
[in]idx_typeIndex type
[in]orderIteration order
[in]nObject to open
[in]lapl_idLink 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_NAMELexicographic order on name
H5_INDEX_CRT_ORDERIndex 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_INCIncreasing order
H5_ITER_DECDecreasing order
H5_ITER_NATIVEFastest 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]tokenObject 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]oidLocation 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]commentThe 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]nameName of the object whose comment is to be set or reset
[in]commentThe new comment
[in]lapl_idLink 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]token1First object token
[in]token2Second object token
[out]cmp_valueComparison 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 {
#define H5O_MAX_TOKEN_SIZE
Definition H5public.h:395
Definition H5public.h:404
uint8_t __data[(16)]
Definition H5public.h:405

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 */
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.
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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]token_strObject token string
[out]tokenConnector 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]tokenConnector object token
[out]token_strString 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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]idx_typeIndex type
[in]orderIteration order
[in]opCallback function passing data regarding the object to the calling application
[in]op_dataUser-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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]idx_typeIndex type
[in]orderIteration order
[in]opCallback function passing data regarding the object to the calling application
[in]op_dataUser-defined pointer to data required by the application for its processing of the object
[in]fieldsFlags 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:

FlagPurpose
H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS Fill in the num_attrs field
H5O_INFO_HDRFill in the num_attrs field
H5O_INFO_META_SIZEFill in the meta_size field
H5O_INFO_ALLH5O_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.

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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]idx_typeIndex type
[in]orderIteration order
[in]opCallback function passing data regarding the object to the calling application
[in]op_dataUser-defined pointer to data required by the application for its processing of the object
[in]fieldsFlags 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:

FlagPurpose
H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS Fill in the num_attrs field
H5O_INFO_HDRFill in the num_attrs field
H5O_INFO_META_SIZEFill in the meta_size field
H5O_INFO_ALLH5O_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.

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;
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.
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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]obj_nameName of the object, generally relative to loc_id, that will serve as root of the iteration
[in]idx_typeIndex type
[in]orderIteration order
[in]opCallback function passing data regarding the object to the calling application
[in]op_dataUser-defined pointer to data required by the application for its processing of the object
[in]lapl_idLink 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.

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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]obj_nameName of the object, generally relative to loc_id, that will serve as root of the iteration
[in]idx_typeIndex type
[in]orderIteration order
[in]opCallback function passing data regarding the object to the calling application
[in]op_dataUser-defined pointer to data required by the application for its processing of the object
[in]fieldsFlags specifying the fields to be retrieved to the callback function op
[in]lapl_idLink 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:

FlagPurpose
H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS Fill in the num_attrs field
H5O_INFO_HDRFill in the num_attrs field
H5O_INFO_META_SIZEFill in the meta_size field
H5O_INFO_ALLH5O_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.

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_idLocation identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]obj_nameName of the object, generally relative to loc_id, that will serve as root of the iteration
[in]idx_typeIndex type
[in]orderIteration order
[in]opCallback function passing data regarding the object to the calling application
[in]op_dataUser-defined pointer to data required by the application for its processing of the object
[in]fieldsFlags specifying the fields to be retrieved to the callback function op
[in]lapl_idLink 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:

FlagPurpose
H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
H5O_INFO_NUM_ATTRS Fill in the num_attrs field
H5O_INFO_HDRFill in the num_attrs field
H5O_INFO_META_SIZEFill in the meta_size field
H5O_INFO_ALLH5O_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.

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,
FAIL_STACK_ERROR;
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.
Since
1.12.0