Please, help us to better know about our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5  1.8.23
C-API Reference
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 (H5G, H5D, 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 effected 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:90
#define H5I_INVALID_HID
Definition: H5Ipublic.h:66
int hid_t
Definition: H5Ipublic.h:60
#define H5P_LINK_CREATE
Definition: H5Ppublic.h:227
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.
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:272
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.
60 {
61 __label__ fail_info, fail_file;
62 hid_t file;
63 char path[] = "/a/few/groups";
64 H5O_info2_t info;
65
66 if ((file = H5Fopen("o1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) {
67 ret_val = EXIT_FAILURE;
68 goto fail_file;
69 }
70
71 // retrieve information about the object
72 if (H5Oget_info_by_name(file, path, &info, H5O_INFO_BASIC | H5O_INFO_NUM_ATTRS, H5P_DEFAULT) < 0) {
73 ret_val = EXIT_FAILURE;
74 goto fail_info;
75 }
76
77 // determine the object type
78 switch (info.type) {
79 case H5O_TYPE_GROUP:
80 printf("HDF5 group\n");
81 break;
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:88
@ H5O_TYPE_DATASET
Definition: H5Opublic.h:137
@ H5O_TYPE_NAMED_DATATYPE
Definition: H5Opublic.h:138
@ H5O_TYPE_GROUP
Definition: H5Opublic.h:136
#define H5P_DEFAULT
Definition: H5Ppublic.h:255
hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id)
Opens an existing HDF5 file.
herr_t H5Oget_info_by_name(hid_t loc_id, const char *name, H5O_info_t *oinfo, hid_t lapl_id)
Retrieves the metadata for an object, identifying the object by location and relative name.
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:89
herr_t H5Oget_info(hid_t loc_id, H5O_info_t *oinfo)
Retrieves the metadata for an object specified by an identifier.
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.
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.

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. More...
 
hid_t H5Oopen_by_addr (hid_t loc_id, haddr_t addr)
 Opens an object using its address within an HDF5 file. More...
 
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. More...
 
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. More...
 
herr_t H5Oget_info (hid_t loc_id, H5O_info_t *oinfo)
 Retrieves the metadata for an object specified by an identifier. More...
 
herr_t H5Oget_info_by_name (hid_t loc_id, const char *name, H5O_info_t *oinfo, hid_t lapl_id)
 Retrieves the metadata for an object, identifying the object by location and relative name. More...
 
herr_t H5Oget_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_info_t *oinfo, hid_t lapl_id)
 Retrieves the metadata for an object, identifying the object by an index position. More...
 
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. More...
 
herr_t H5Oincr_refcount (hid_t object_id)
 Increments an object reference count. More...
 
herr_t H5Odecr_refcount (hid_t object_id)
 Decrements an object reference count. More...
 
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. More...
 
herr_t H5Oset_comment (hid_t obj_id, const char *comment)
 Sets comment for specified object. More...
 
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. More...
 
ssize_t H5Oget_comment (hid_t obj_id, char *comment, size_t bufsize)
 Retrieves comment for specified object. More...
 
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. More...
 
herr_t H5Ovisit (hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate_t op, void *op_data)
 Recursively visits all objects accessible from a specified object. More...
 
herr_t H5Ovisit_by_name (hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate_t op, void *op_data, hid_t lapl_id)
 Recursively visits all objects accessible from a specified object. More...
 
herr_t H5Oclose (hid_t object_id)
 Closes an object in an HDF5 file. More...
 

Function Documentation

◆ 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’s 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

◆ 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 negatvie 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 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 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 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 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

◆ 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, the 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, the 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_info()

herr_t H5Oget_info ( hid_t  loc_id,
H5O_info_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.

H5Oget_info() specifies an object by its identifier, loc_id , and retrieves the metadata describing that object in oinfo , defined as a struct of type H5O_info_t :

typedef struct H5O_info_t {
unsigned long fileno;
unsigned rc;
time_t atime;
time_t mtime;
time_t ctime;
time_t btime;
/* Extra metadata storage for obj & attributes */
struct {
H5O_type_t
Definition: H5Opublic.h:134
unsigned long haddr_t
Definition: H5public.h:368
unsigned long long hsize_t
Definition: H5public.h:334
Definition: H5public.h:456
Definition: H5Opublic.h:148
Definition: H5Opublic.h:171
haddr_t addr
Definition: H5Opublic.h:173
struct H5O_info_t::@4 meta_size
unsigned rc
Definition: H5Opublic.h:175
time_t ctime
Definition: H5Opublic.h:178
time_t mtime
Definition: H5Opublic.h:177
H5O_hdr_info_t hdr
Definition: H5Opublic.h:181
H5O_type_t type
Definition: H5Opublic.h:174
time_t atime
Definition: H5Opublic.h:176
unsigned long fileno
Definition: H5Opublic.h:172
H5_ih_info_t attr
Definition: H5Opublic.h:185
hsize_t num_attrs
Definition: H5Opublic.h:180
time_t btime
Definition: H5Opublic.h:179
H5_ih_info_t obj
Definition: H5Opublic.h:184

Note the following about H5O_info_t :

  • Of the four time fields (atime, mtime, ctime, and btime) only ctime has been implemented.
  • The atime value is the last time the object was read or written.
  • The mtime value is the last time the raw data in the object was changed.
  • The ctime value is the last time the metadata for the object was changed.
  • The btime value is the time the object was created.
  • The fields nested in the meta_size field are for internal library use only.

The H5O_type_t enum indicates the object type and is defined in H5Opublic.h as follows:

typedef enum H5O_type_t {
@ H5O_TYPE_UNKNOWN
Definition: H5Opublic.h:135
@ H5O_TYPE_NTYPES
Definition: H5Opublic.h:139

Note that the object retrieved as indicated by loc_id refers only to the types specified by H5O_type_t.

An H5O_hdr_info_t struct holds object header metadata and is defined in H5Opublic.h as follows:

typedef struct H5O_hdr_info_t {
unsigned version;
unsigned nmesgs;
unsigned nchunks;
unsigned flags;
struct {
} space;
struct {
uint64_t present;
uint64_t shared;
} mesg;
unsigned nmesgs
Definition: H5Opublic.h:150
unsigned nchunks
Definition: H5Opublic.h:151
hsize_t total
Definition: H5Opublic.h:154
unsigned version
Definition: H5Opublic.h:149
uint64_t shared
Definition: H5Opublic.h:161
hsize_t meta
Definition: H5Opublic.h:155
uint64_t present
Definition: H5Opublic.h:160
unsigned flags
Definition: H5Opublic.h:152
hsize_t free
Definition: H5Opublic.h:157
hsize_t mesg
Definition: H5Opublic.h:156
struct H5O_hdr_info_t::@2 space

Valid values for the version field are H5O_VERSION_1 and H5O_VERSION_2. Version 2 of the object header is smaller and more efficient than version 1.

Please be aware that the information held by H5O_hdr_info_t may only be useful to developers with extensive HDF5 experience.

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.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_info_by_idx()

herr_t H5Oget_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_info_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.

H5Oget_info_by_idx() 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 (.).

idx_type is of type H5_index_t, defined in H5public.h as:

typedef enum H5_index_t {
H5_index_t
Definition: H5public.h:444
@ H5_INDEX_CRT_ORDER
Definition: H5public.h:447
@ H5_INDEX_UNKNOWN
Definition: H5public.h:445
@ H5_INDEX_NAME
Definition: H5public.h:446
@ H5_INDEX_N
Definition: H5public.h:448

order is of type H5_iter_order_t defined in H5public.h as:

typedef enum {
H5_iter_order_t
Definition: H5public.h:421
@ H5_ITER_NATIVE
Definition: H5public.h:425
@ H5_ITER_DEC
Definition: H5public.h:424
@ H5_ITER_UNKNOWN
Definition: H5public.h:422
@ H5_ITER_INC
Definition: H5public.h:423
@ H5_ITER_N
Definition: H5public.h:426

oinfo, in which the object information is returned, is a struct of type H5O_info_t .

typedef struct H5O_info_t {
unsigned long fileno;
unsigned rc;
time_t atime;
time_t mtime;
time_t ctime;
time_t btime;
/* Extra metadata storage for obj & attributes */
struct {

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

Version
1.8.11 Fortran subroutine introduced in this release.
Since
1.8.0

◆ H5Oget_info_by_name()

herr_t H5Oget_info_by_name ( hid_t  loc_id,
const char *  name,
H5O_info_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.

H5Oget_info_by_name() 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_info_t is defined in H5Opublic.h and described in the H5Oget_info() function entry.

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

Version
1.8.8 Fortran 2003 subroutine and h5o_info_t derived type introduced in this release.
Since
1.8.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’s 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

◆ 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 a negative value.

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 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 a negative value.

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 super block (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 a negative value.

H5Open_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

◆ 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 the 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 the 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

◆ H5Ovisit()

herr_t H5Ovisit ( hid_t  obj_id,
H5_index_t  idx_type,
H5_iter_order_t  order,
H5O_iterate_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.

H5Ovisit() 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. Valid values include the following:

H5_INDEX_NAMELexicographic order on name
H5_INDEX_CRT_ORDERIndex on creation order

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. Valid values include the following:

H5_ITER_INCIncreasing order
H5_ITER_DECDecreasing order
H5_ITER_NATIVEFastest available order

The prototype of the callback function op is as follows (as defined in the source code file H5Opublic.h):

typedef herr_t (*H5O_iterate_t)(hid_t obj, const char *name, const H5O_info_t *info, void *op_data);
herr_t(* H5O_iterate_t)(hid_t obj, const char *name, const H5O_info_t *info, void *op_data)
Definition: H5Opublic.h:210
int herr_t
Definition: H5public.h:232

The parameters of this callback function have the following values or meanings:

obj Object that serves as root of the iteration; same value as the H5Ovisit() obj_id parameter
name Name of object, relative to obj, being examined at current step of the iteration
info H5O_info1_t struct containing information regarding that object
op_data User-defined pointer to data required by the application in processing the object

The H5O_info_t struct is defined in H5Opublic.h:

typedef struct H5O_info_t {
unsigned long fileno;
unsigned rc;
time_t atime;
time_t mtime;
time_t ctime;
time_t btime;
/* Extra metadata storage for obj & attributes */
struct {

The return values from an operator are:

  • Zero causes the visit iterator to continue, returning zero when all group members have been processed.
  • A positive value causes the visit iterator to immediately return that positive value, indicating short-circuit success.
  • A negative value causes the visit iterator to immediately return that value, indicating failure.

The H5Ovisit() 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.

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.

Note
Programming Note for C++ Developers Using C Functions:
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as H5Pset_elink_cb() and H5Pset_type_conv_cb() and functions such as H5Tconvert() and H5Ewalk2().
Exiting the routine in its normal fashion allows the HDF5 C library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
Version
1.8.8 Fortran subroutine introduced in this release.
Since
1.8.0

◆ H5Ovisit_by_name()

herr_t H5Ovisit_by_name ( hid_t  loc_id,
const char *  obj_name,
H5_index_t  idx_type,
H5_iter_order_t  order,
H5O_iterate_t  op,
void *  op_data,
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]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_name() 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 H5Ovisit() 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. Valid values include the following:

H5_INDEX_NAMELexicographic order on name
H5_INDEX_CRT_ORDERIndex on creation order

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. Valid values include the following:

H5_ITER_INCIncreasing order
H5_ITER_DECDecreasing order
H5_ITER_NATIVEFastest available order

The op callback function and the effect of the callback function’s return value on the application are described in H5Ovisit().

The H5O_info_t struct is defined in H5Opublic.h and described in the H5Oget_info() function entry.

The H5Ovisit_by_name() 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_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.

Note
Programming Note for C++ Developers Using C Functions:
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as H5Pset_elink_cb() and H5Pset_type_conv_cb() and functions such as H5Tconvert() and H5Ewalk2().
Exiting the routine in its normal fashion allows the HDF5 C library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
Version
1.8.11 Fortran subroutine introduced in this release.
Since
1.8.0