Please, help us to better know about our user community by answering the following short survey: https://www.hdfgroup.org/
HDF5  1.12.1
H5O

Detailed Description

Object Interface.

Todo:
Describe concisely what the functions in this module are about.

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. More...
 
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. 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_info3 (hid_t loc_id, H5O_info2_t *oinfo, unsigned fields)
 Retrieves the metadata for an object specified by an identifier. More...
 
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. More...
 
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. More...
 
herr_t H5Oget_native_info (hid_t loc_id, H5O_native_info_t *oinfo, unsigned fields)
 Retrieve native file format information about an object. More...
 
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. More...
 
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. 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 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. More...
 
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. More...
 
herr_t H5Oclose (hid_t object_id)
 Closes an object in an HDF5 file. More...
 
herr_t H5Oflush (hid_t obj_id)
 Flushes all buffers associated with an HDF5 object to disk. More...
 
herr_t H5Orefresh (hid_t oid)
 Refreshes all buffers associated with an HDF5 object. More...
 
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. More...
 
herr_t H5Oenable_mdc_flushes (hid_t object_id)
 Enables flushing of dirty metadata entries from a file’s metadata cache. More...
 
herr_t H5Oare_mdc_flushes_disabled (hid_t object_id, hbool_t *are_disabled)
 Retrieves comment for specified object. More...
 
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. More...
 
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. More...
 
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. More...
 
hid_t H5Oopen_by_addr (hid_t loc_id, haddr_t addr)
 Opens an object using its address within an HDF5 file. More...
 
herr_t H5Oget_info1 (hid_t loc_id, H5O_info1_t *oinfo)
 Retrieves the metadata for an object specified by an identifier. More...
 
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. More...
 
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. More...
 
herr_t H5Oget_info2 (hid_t loc_id, H5O_info1_t *oinfo, unsigned fields)
 Retrieves the metadata for an object specified by an identifier. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

Macro Definition Documentation

◆ H5Oget_info

#define H5Oget_info   H5Oget_info3

H5Oget_info is a macro that is mapped to:

Such macros are provided to facilitate application compatibility. Their use and mappings are fully described in API Compatibility Macros in HDF5; we urge you to read that document closely.

In HDF5 versions 1.12 and after, H5Oget_info is mapped to H5Oget_info3 and H5Oget_info1 is deprecated. In version 1.10 H5Oget_info is identical to H5Oget_info1.

Specific compile-time compatibility flags and the resulting mappings are as follows:

Compatibility setting H5Oget_info
No compatibility flag
 
H5Oget_info3 (in release 1.12)
H5Oget_info1 (in 1.8 or 1.10)
Emulate Release 1.12 H5Oget_info3
Emulate Release 1.10/1.8 interface H5Oget_info1
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.12.0 The macro H5Oget_info and the function H5Oget_info3 were added, and H5Oget_info1 was deprecated.
1.10.5 The macro H5Oget_info was removed. The functions H5Oget_info1 and H5Oget_info are identical in this release. This change was added to restore the broken API compatibility introduced in HDF5-1.10.3.
1.10.3 The function H5Oget_info was renamed H5Oget_info1. The macro H5Oget_info and the function H5Oget_info2 were introduced in this release.
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

#define H5Oget_info_by_idx   H5Oget_info_by_idx3

H5Oget_info_by_idx is a macro that is mapped to:

Such macros are provided to facilitate application compatibility. Their use and mappings are fully described in API Compatibility Macros in HDF5; we urge you to read that document closely.

In HDF5 versions 1.12 and after, H5Oget_info_by_idx is mapped to H5Oget_info_by_idx3 and H5Oget_info_by_idx1 is deprecated. In version 1.10 H5Oget_info_by_idx is identical to H5Oget_info_by_idx1.

Specific compile-time compatibility flags and the resulting mappings are as follows:

Compatibility setting H5Oget_info_by_idx
No compatibility flag
 
H5Oget_info_by_idx3 for 1.12
H5Oget_info_by_idx1 for 1.8/1.10
Emulate Release 1.12 H5Oget_info_by_idx3
Emulate Release 1.10/1.8 interface H5Oget_info_by_idx1
Version
1.12.0 The macro H5Oget_info_by_idx and function H5Oget_info_by_idx3 were added, and H5Oget_info_by_idx1 was deprecated.
1.10.5 The macro H5Oget_info_by_idx was removed. The functions H5Oget_info_by_idx and H5Oget_info_by_idx1 are identical in this release. This change was added to restore the broken API compatibility introduced in HDF5-1.10.3.
1.10.3 The function H5Oget_info_by_idx was renamed H5Oget_info_by_idx1. The macro H5Oget_info_by_idx and the function H5Oget_info_by_idx2 were introduced in this release.
1.8.11 Fortran subroutine introduced in this release.
Since
1.8.0

◆ H5Oget_info_by_name

#define H5Oget_info_by_name   H5Oget_info_by_name3

H5Oget_info_by_name is a macro that is mapped to:

Such macros are provided to facilitate application compatibility. Their use and mappings are fully described in API Compatibility Macros in HDF5; we urge you to read that document closely.

In HDF5 versions 1.12 and after, H5Oget_info_by_name is mapped to H5Oget_info_by_name3. In version 1.10 H5Oget_info_by_name is identical to H5Oget_info_by_name1.

Specific compile-time compatibility flags and the resulting mappings are as follows:

Compatibility setting H5Oget_info_by_name
No compatibility flag
 
H5Oget_info_by_name3 for 1.12 and above
H5Oget_info_by_name1 for 1.8 or 1.10
Emulate Release 1.12 H5Oget_info_by_name3
Emulate Release 1.10 or 1.8 interface H5Oget_info_by_name1
Version
1.12.0 The macro H5Oget_info_by_name and function H5Oget_info_by_name3 were added and H5Oget_info_by_name1 was deprecated.
1.10.5 The macro H5Oget_info_by_name was removed. The functions H5Oget_info_by_name and H5Oget_info_by_name1 are identical in this release. This change was added to restore the broken API compatibility introduced in HDF5-1.10.3.
1.10.3 The function H5Oget_info_by_name was renamed to H5Oget_info_by_name1. The macro H5Oget_info_by_name and the function H5Oget_info_by_name2 were introduced in this release.
1.8.8 Fortran 2003 subroutine and h5o_info_t derived type introduced in this release.
Since
1.8.0

◆ H5Ovisit

#define H5Ovisit   H5Ovisit3

H5Ovisit is a macro that is mapped to one of the following:

Such macros are provided to facilitate application compatibility. Their use and mappings are fully described in API Compatibility Macros in HDF5; we urge you to read that document closely.

In HDF5 versions 1.12 and after, H5Ovisit is mapped to H5Ovisit3. In version 1.10, H5Ovisit is identical to H5Ovisit1.

Specific compile-time compatibility flags and the resulting mappings are as follows:

Compatibility settings H5Ovisit
No compatibility flag
 
H5Ovisit3 in 1.12 or after
H5Ovisit1 for 1.8 and 1.10
Emulate Release 1.12 H5Ovisit3
Emulate Release 1.10 or 1.8 interface H5Ovisit1
Version
1.12.0 The macro H5Ovisit and function H5Ovisit3 were added, and H5Ovisit1 was deprecated.
1.10.5 The macro H5Ovisit was removed. The functions H5Ovisit and H5Ovisit1 are identical in this release. This change was added to restore the broken API compatibility introduced in HDF5-1.10.3.
1.10.3 The function H5Ovisit was renamed to H5Ovisit1. The macro H5Ovisit and the function H5Ovisit2 were introduced in this release.
1.8.8 Fortran subroutine and data structure added.
Since
1.8.0

◆ H5Ovisit_by_name

#define H5Ovisit_by_name   H5Ovisit_by_name3

H5Ovisit_by_name is a macro that is mapped to one of the following:

Such macros are provided to facilitate application compatibility. Their use and mappings are fully described in API Compatibility Macros in HDF5; we urge you to read that document closely.

In HDF5 versions 1.12 and after, H5Ovisit_by_name is mapped to H5Ovisit_by_name3. In version 1.10, H5Ovisit_by_name is identical to H5Ovisit_by_name1.

Specific compile-time compatibility flags and the resulting mappings are as follows:

Compatibility settings H5Ovisit_by_name
No compatibility flag
 
H5Ovisit_by_name3 for 1.12 and above
H5Ovisit_by_name1 for 1.10 or 1.8
Emulate Release 1.12 interface H5Ovisit_by_name3
Emulate Release 1.10 or 1.8 interface H5Ovisit_by_name1
Version
1.12.0 The macro H5Ovisit_by_name and function H5Ovisit_by_name3 were added.
1.10.5 The macro H5Ovisit_by_name was removed. The functions H5Ovisit_by_name and H5Ovisit_by_name1 are identical in this release. This change was added to restore the broken API compatibility introduced in HDF5-1.10.3.
1.10.3 The function H5Ovisit_by_name was renamed to H5Ovisit_by_name1. The macro H5Ovisit_by_name and the function H5Ovisit_by_name2 were introduced in this release.
1.8.8 Fortran subroutine introduced in this release.
Since
1.8.0

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

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

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

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:
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, 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_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 , defined as a struct of type H5O_info1_t :

typedef struct H5O_info1_t {
unsigned long fileno;
haddr_t addr;
unsigned rc;
time_t atime;
time_t mtime;
time_t ctime;
time_t btime;
hsize_t num_attrs;
/* Extra metadata storage for obj & attributes */
struct {

Note the following about H5O_info1_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:

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 {
hsize_t total;
hsize_t meta;
hsize_t mesg;
hsize_t free;
} space;
struct {
uint64_t present;
uint64_t shared;
} mesg;

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.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 , an H5O_info2_t struct.

The H5O_info2_t struct is defined in H5Opublic.h as follows :

typedef struct H5O_info2_t {
unsigned long fileno; /* File number that object is located in */
H5O_token_t token; /* Token representing the object */
H5O_type_t type; /* Basic object type (group, dataset, etc.) */
unsigned rc; /* Reference count of object */
time_t atime; /* Access time */
time_t mtime; /* Modification time */
time_t ctime; /* Change time */
time_t btime; /* Birth time */
hsize_t num_attrs; /* # of attributes attached to object */

Note the following about H5O_info2_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 H5O_token_t is defined in H5public.h as follows:

typedef struct H5O_token_t {

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

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

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

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

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

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

typedef struct H5O_info1_t {
unsigned long fileno;
haddr_t addr;
unsigned rc;
time_t atime;
time_t mtime;
time_t ctime;
time_t btime;
hsize_t num_attrs;
/* 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.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 (.).

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

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

oinfo, in which the object information is returned, is a struct of type H5O_info2_t, which is defined in H5Opublic.h in the HDF5 source code:

typedef struct H5O_info2_t {
unsigned long fileno; /* File number that object is located in */
H5O_token_t token; /* Token representing the object */
H5O_type_t type; /* Basic object type (group, dataset, etc.) */
unsigned rc; /* Reference count of object */
time_t atime; /* Access time */
time_t mtime; /* Modification time */
time_t ctime; /* Change time */
time_t btime; /* Birth time */
hsize_t num_attrs; /* # of attributes attached to object */

Note the following about H5O_info2_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.

H5O_token_t is defined in H5public.h as follows:

typedef struct H5O_token_t {

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

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

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:
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 group, 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 group, 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 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 group, 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.

oinfo, in which the object information is returned, is a struct of type H5O_info2_t, which is defined in H5Opublic.h in the HDF5 source code:

typedef struct H5O_info2_t {
unsigned long fileno; /* File number that object is located in */
H5O_token_t token; /* Token representing the object */
H5O_type_t type; /* Basic object type (group, dataset, etc.) */
unsigned rc; /* Reference count of object */
time_t atime; /* Access time */
time_t mtime; /* Modification time */
time_t ctime; /* Change time */
time_t btime; /* Birth time */
hsize_t num_attrs; /* # of attributes attached to object */

Note the following about H5O_info2_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 H5O_token_t is defined in H5public.h as follows:

typedef struct H5O_token_t {

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

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

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:
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 information is retrieved into the buffer specified by oinfo, which is defined as a struct of type H5O_native_info_t in H5Opublic.h:

typedef struct H5O_native_info_t {
/* Extra metadata storage for obj & attributes */
struct {

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 /* Fill in the hdr field */
#define H5O_NATIVE_INFO_META_SIZE 0x0010u /* Fill in the meta_size field */
#define H5O_NATIVE_INFO_ALL (H5O_NATIVE_INFO_HDR | H5O_NATIVE_INFO_META_SIZE)
Example
An example snippet from test/tfile.c:
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 information is retrieved into the buffer specified by oinfo, which is defined as a struct of type H5O_native_info_t in H5Opublic.h:

typedef struct H5O_native_info_t {
/* Extra metadata storage for obj & attributes */
struct {

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

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

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 /* Fill in the hdr field */
#define H5O_NATIVE_INFO_META_SIZE 0x0010u /* Fill in the meta_size field */
#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 information is retrieved into the buffer specified by oinfo, which is defined as a struct of type H5O_native_info_t in H5Opublic.h:

typedef struct H5O_native_info_t {
/* Extra metadata storage for obj & attributes */
struct {

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 /* Fill in the hdr field */
#define H5O_NATIVE_INFO_META_SIZE 0x0010u /* Fill in the meta_size field */
#define H5O_NATIVE_INFO_ALL (H5O_NATIVE_INFO_HDR | H5O_NATIVE_INFO_META_SIZE)
Example
An example snippet from test/tfile.c:
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’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);
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.
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 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

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

Example
An example snippet from examples/h5_extlink.c:
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 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

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

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:
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. 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 alpha-numeric 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_iterate1_t)(hid_t obj, const char *name, const H5O_info1_t *info, void *op_data);

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 H5Ovisit1() 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_info1_t struct is defined in H5Opublic.h:

typedef struct H5O_info1_t {
unsigned long fileno;
haddr_t addr;
unsigned rc;
time_t atime;
time_t mtime;
time_t ctime;
time_t btime;
hsize_t num_attrs;
/* 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 H5Ovisit1() 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.

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.

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.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. 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 alpha-numeric 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_iterate1_t)(hid_t obj, const char *name, const H5O_info1_t *info, void *op_data);

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 H5Ovisit1() 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; a pass-through of the op_data pointer provided with the H5Ovisit() function call

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

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 H5Ovisit2() 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

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.
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. 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 alpha-numeric 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_iterate2_t)(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data);

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_info2_t struct containing information regarding that object
op_data User-defined pointer to data required by the application in processing the object; a pass-through of the op_data pointer provided with the H5Ovisit() function call

The H5O_info2_t struct is defined in H5Opublic.h as follows:

typedef struct H5O_info2_t {
unsigned long fileno; /* File number that object is located in */
H5O_token_t token; /* Token representing the object */
H5O_type_t type; /* Basic object type (group, dataset, etc.) */
unsigned rc; /* Reference count of object */
time_t atime; /* Access time */
time_t mtime; /* Modification time */
time_t ctime; /* Change time */
time_t btime; /* Birth time */
hsize_t num_attrs; /* # of attributes attached to object */

H5O_token_t is defined in H5public.h as follows:

typedef struct H5O_token_t {

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

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

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

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.
Example
An example snippet from test/links.c:
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 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 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. 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 alpha-numeric 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 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.

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.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. 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 alpha-numeric 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 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.

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.
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 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 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. 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 alpha-numeric 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_iterate2_t)(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data);

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

obj Object that serves as root of the iteration
name Name of object, relative to obj, being examined at current step of the iteration
info H5O_info2_t struct containing information regarding that object
op_data User-defined pointer to data required by the application in processing the object

The H5O_info2_t struct is defined in H5Opublic.h as follows:

typedef struct H5O_info2_t {
unsigned long fileno; /* File number that object is located in */
H5O_token_t token; /* Token representing the object */
H5O_type_t type; /* Basic object type (group, dataset, etc.) */
unsigned rc; /* Reference count of object */
time_t atime; /* Access time */
time_t mtime; /* Modification time */
time_t ctime; /* Change time */
time_t btime; /* Birth time */
hsize_t num_attrs; /* # of attributes attached to object */

H5O_token_t is defined in H5public.h as follows:

typedef struct H5O_token_t {

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

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.

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.
Example
An example snippet from test/links.c:
Since
1.12.0
H5O_info1_t::atime
time_t atime
Definition: H5Opublic.h:1866
H5O_hdr_info_t::free
hsize_t free
Definition: H5Opublic.h:134
H5O_native_info_t::meta_size
struct H5O_native_info_t::@8 meta_size
H5Pcreate
hid_t H5Pcreate(hid_t cls_id)
Creates a new property list as an instance of a property list class.
H5O_MAX_TOKEN_SIZE
#define H5O_MAX_TOKEN_SIZE
Definition: H5public.h:438
H5O_info1_t::fileno
unsigned long fileno
Definition: H5Opublic.h:1862
H5O_hdr_info_t::meta
hsize_t meta
Definition: H5Opublic.h:132
H5O_token_t::__data
uint8_t __data[(16)]
Definition: H5public.h:448
H5O_info1_t::btime
time_t btime
Definition: H5Opublic.h:1869
H5O_iterate2_t
herr_t(* H5O_iterate2_t)(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data)
Definition: H5Opublic.h:185
H5O_native_info_t::obj
H5_ih_info_t obj
Definition: H5Opublic.h:170
H5O_hdr_info_t::mesg
hsize_t mesg
Definition: H5Opublic.h:133
H5O_TYPE_DATASET
@ H5O_TYPE_DATASET
Definition: H5Opublic.h:113
H5_ITER_NATIVE
@ H5_ITER_NATIVE
Definition: H5public.h:395
H5O_hdr_info_t::version
unsigned version
Definition: H5Opublic.h:126
H5_INDEX_CRT_ORDER
@ H5_INDEX_CRT_ORDER
Definition: H5public.h:417
H5O_info2_t::num_attrs
hsize_t num_attrs
Definition: H5Opublic.h:157
H5_ITER_DEC
@ H5_ITER_DEC
Definition: H5public.h:394
H5O_TYPE_GROUP
@ H5O_TYPE_GROUP
Definition: H5Opublic.h:112
H5_INDEX_N
@ H5_INDEX_N
Definition: H5public.h:418
H5O_info2_t::rc
unsigned rc
Definition: H5Opublic.h:152
H5_INDEX_UNKNOWN
@ H5_INDEX_UNKNOWN
Definition: H5public.h:415
H5_iter_order_t
H5_iter_order_t
Definition: H5public.h:391
H5O_hdr_info_t::nchunks
unsigned nchunks
Definition: H5Opublic.h:128
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.
H5O_info2_t::mtime
time_t mtime
Definition: H5Opublic.h:154
H5O_info1_t::hdr
H5O_hdr_info_t hdr
Definition: H5Opublic.h:1871
H5_ITER_N
@ H5_ITER_N
Definition: H5public.h:396
H5O_info2_t::type
H5O_type_t type
Definition: H5Opublic.h:151
hid_t
int64_t hid_t
Definition: H5Ipublic.h:61
H5O_info2_t::atime
time_t atime
Definition: H5Opublic.h:153
H5_ih_info_t
Definition: H5public.h:426
H5O_hdr_info_t::space
struct H5O_hdr_info_t::@6 space
H5O_iterate1_t
herr_t(* H5O_iterate1_t)(hid_t obj, const char *name, const H5O_info1_t *info, void *op_data)
Definition: H5Opublic.h:1884
H5O_TYPE_UNKNOWN
@ H5O_TYPE_UNKNOWN
Definition: H5Opublic.h:111
H5_INDEX_NAME
@ H5_INDEX_NAME
Definition: H5public.h:416
H5O_native_info_t::hdr
H5O_hdr_info_t hdr
Definition: H5Opublic.h:167
H5O_info2_t
Definition: H5Opublic.h:148
H5O_info2_t::token
H5O_token_t token
Definition: H5Opublic.h:150
H5O_info1_t::meta_size
struct H5O_info1_t::@9 meta_size
H5O_info2_t::ctime
time_t ctime
Definition: H5Opublic.h:155
H5O_info1_t
Definition: H5Opublic.h:1861
H5O_info1_t::obj
H5_ih_info_t obj
Definition: H5Opublic.h:1874
H5O_TYPE_MAP
@ H5O_TYPE_MAP
Definition: H5Opublic.h:115
H5O_info1_t::num_attrs
hsize_t num_attrs
Definition: H5Opublic.h:1870
H5P_DEFAULT
#define H5P_DEFAULT
Definition: H5Ppublic.h:103
H5O_info1_t::addr
haddr_t addr
Definition: H5Opublic.h:1863
H5O_hdr_info_t
Definition: H5Opublic.h:125
H5O_info2_t::fileno
unsigned long fileno
Definition: H5Opublic.h:149
H5Gcreate_anon
hid_t H5Gcreate_anon(hid_t loc_id, hid_t gcpl_id, hid_t gapl_id)
Creates a new empty group without linking it into the file structure.
H5O_hdr_info_t::total
hsize_t total
Definition: H5Opublic.h:131
H5_ITER_UNKNOWN
@ H5_ITER_UNKNOWN
Definition: H5public.h:392
herr_t
int herr_t
Definition: H5public.h:202
H5O_TYPE_NTYPES
@ H5O_TYPE_NTYPES
Definition: H5Opublic.h:116
H5O_TYPE_NAMED_DATATYPE
@ H5O_TYPE_NAMED_DATATYPE
Definition: H5Opublic.h:114
H5Pset_create_intermediate_group
herr_t H5Pset_create_intermediate_group(hid_t plist_id, unsigned crt_intmd)
Specifies in property list whether to create missing intermediate groups.
H5O_info2_t::btime
time_t btime
Definition: H5Opublic.h:156
H5O_info1_t::rc
unsigned rc
Definition: H5Opublic.h:1865
H5O_hdr_info_t::shared
uint64_t shared
Definition: H5Opublic.h:138
H5O_hdr_info_t::present
uint64_t present
Definition: H5Opublic.h:137
H5O_native_info_t::attr
H5_ih_info_t attr
Definition: H5Opublic.h:171
H5P_LINK_CREATE
#define H5P_LINK_CREATE
Definition: H5Ppublic.h:70
H5O_info1_t::attr
H5_ih_info_t attr
Definition: H5Opublic.h:1875
H5O_info1_t::mtime
time_t mtime
Definition: H5Opublic.h:1867
H5O_info1_t::type
H5O_type_t type
Definition: H5Opublic.h:1864
H5O_hdr_info_t::flags
unsigned flags
Definition: H5Opublic.h:129
H5O_token_t
Definition: H5public.h:447
H5O_info1_t::ctime
time_t ctime
Definition: H5Opublic.h:1868
H5_index_t
H5_index_t
Definition: H5public.h:414
H5O_native_info_t
Definition: H5Opublic.h:166
H5O_hdr_info_t::nmesgs
unsigned nmesgs
Definition: H5Opublic.h:127
H5O_type_t
H5O_type_t
Definition: H5Opublic.h:110
H5_ITER_INC
@ H5_ITER_INC
Definition: H5public.h:393