Objects (H5O)

Detailed Description

Use the functions in this module to manage HDF5 objects.

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

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

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

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

Create	Read
{ __label__ fail_file; hid_t file, group; char src_path[] = "/a/few/groups"; if ((file = H5Fcreate("o1.h5", H5F_ACC_TRUNC, H5P_DEFAULTx2)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_file; } // create a few groups { __label__ fail_group, fail_lcpl; hid_t lcpl; if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_lcpl; } if (H5Pset_create_intermediate_group(lcpl, 1) < 0) { ret_val = EXIT_FAILURE; goto fail_group; } if ((group = H5Gcreate(file, src_path, lcpl, H5P_DEFAULTx2)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_group; } H5Gclose(group); fail_group: H5Pclose(lcpl); fail_lcpl:; } // create a copy if (H5Ocopy(file, ".", file, "copy of", H5P_DEFAULTx2) < 0) { ret_val = EXIT_FAILURE; } H5Fclose(file); fail_file:; }	{ __label__ fail_info, fail_file; hid_t file; char path[] = "/a/few/groups"; H5O_info2_t info; if ((file = H5Fopen("o1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_file; } // retrieve information about the object if (H5Oget_info_by_name(file, path, &info, H5O_INFO_BASIC | H5O_INFO_NUM_ATTRS, H5P_DEFAULT) < 0) { ret_val = EXIT_FAILURE; goto fail_info; } // determine the object type switch (info.type) { case H5O_TYPE_GROUP: printf("HDF5 group\n"); break; case H5O_TYPE_DATASET: printf("HDF5 dataset\n"); break; case H5O_TYPE_NAMED_DATATYPE: printf("HDF5 datatype\n"); break; default: printf("UFO?\n"); break; } // print basic information printf("Reference count: %u\n", info.rc); printf("Attribute count: %lld\n", info.num_attrs); fail_info: H5Fclose(file); fail_file:; }
Update	Delete
{ __label__ fail_obj, fail_incr, fail_file; hid_t file, obj; char path[] = "/a/few/groups"; H5O_info2_t info; if ((file = H5Fopen("o1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_file; } // open an object by path name if ((obj = H5Oopen(file, path, H5P_DEFAULT)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_obj; } // bump its reference count (by 1) if (H5Oincr_refcount(obj) < 0) { ret_val = EXIT_FAILURE; goto fail_incr; } // confirm the new reference count if (H5Oget_info(obj, &info, H5O_INFO_BASIC) < 0) { ret_val = EXIT_FAILURE; goto fail_incr; } printf("Reference count: %u\n", info.rc); fail_incr: H5Oclose(obj); fail_obj: H5Fclose(file); fail_file:; }	{ __label__ fail_obj, fail_delete, fail_file; hid_t file, obj; char path[] = "/a/few/groups"; H5O_info2_t info; if ((file = H5Fopen("o1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_file; } // open an object by path name if ((obj = H5Oopen(file, path, H5P_DEFAULT)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_obj; } // render it inaccessible from the root group by deleting the one and // only link to it; this drops the reference count by 1 if (H5Ldelete(file, path, H5P_DEFAULT) < 0) { ret_val = EXIT_FAILURE; goto fail_delete; } // confirm the new reference count if (H5Oget_info(obj, &info, H5O_INFO_BASIC) < 0) { ret_val = EXIT_FAILURE; goto fail_delete; } printf("Reference count: %u\n", info.rc); // if we close the file at this point, we'd be creating a tombstone, // an object that cannot be reached and that cannot be reclaimed by the // freespace manager; decrement the reference count to zero to prevent that if (H5Idec_ref(obj) < 0) { ret_val = EXIT_FAILURE; goto fail_delete; } else // attempting to close the object would be like a double H5Oclose and fail goto fail_obj; fail_delete: H5Oclose(obj); fail_obj: H5Fclose(file); fail_file:; }

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

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

Macro Definition Documentation

H5Oget_info

#define H5Oget_info   H5Oget_info3

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

See also

API Compatibility Macros

H5Oget_info_by_idx

#define H5Oget_info_by_idx   H5Oget_info_by_idx3

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

See also

API Compatibility Macros

H5Oget_info_by_name

#define H5Oget_info_by_name   H5Oget_info_by_name3

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

See also

API Compatibility Macros

H5Ovisit

#define H5Ovisit   H5Ovisit3

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

See also

API Compatibility Macros

H5Ovisit_by_name

#define H5Ovisit_by_name   H5Ovisit_by_name3

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

See also

API Compatibility Macros

Function Documentation

H5Oare_mdc_flushes_disabled()

herr_t H5Oare_mdc_flushes_disabled	(	hid_t	object_id,
		hbool_t *	are_disabled
	)

Retrieves comment for specified object.

---

Parameters

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

Returns

are_disabled will be set to 1 if an object has had flushes disabled and 0 if it has not had flushes disabled.

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

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

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

Note

HDF5 objects include datasets, groups, and committed datatypes. Only hid_t identifiers that represent these objects can be passed to the function.

Passing in a hid_t identifier that represents any other HDF5 entity is considered an error.

It is an error to pass an HDF5 file identifier (obtained from H5Fopen() or H5Fcreate()) to this function.

Since

1.10.0

H5Oclose()

herr_t H5Oclose

(

hid_t

object_id

)

Closes an object in an HDF5 file.

---

Parameters

[in]

object_id

Object identifier

Returns

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

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

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

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

Version

1.8.8 Fortran subroutine introduced in this release.

Since

1.8.0

H5Ocopy()

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

Copies an object in an HDF5 file.

---

Parameters

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

Returns

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

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

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

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

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

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

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

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

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

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

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

See Also:

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

Version

1.8.9 Fortran subroutine introduced in this release.

Since

1.8.0

H5Odecr_refcount()

herr_t H5Odecr_refcount

(

hid_t

object_id

)

Decrements an object reference count.

---

Parameters

[in]

object_id

Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.

Returns

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

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

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

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

Warning

This function must be used with care!

Improper use can lead to inaccessible data, wasted space in the file, or file corruption.

Version

1.8.11 Fortran subroutine introduced in this release.

Since

1.8.0

H5Odisable_mdc_flushes()

herr_t H5Odisable_mdc_flushes

(

hid_t

object_id

)

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

---

Parameters

[in]

object_id

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

Returns

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

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

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

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

Note

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

Since

1.10.0

H5Oenable_mdc_flushes()

herr_t H5Oenable_mdc_flushes

(

hid_t

object_id

)

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

---

Parameters

[in]

object_id

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

Returns

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

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

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

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

Note

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

Since

1.10.0

H5Oexists_by_name()

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

Determines whether a link resolves to an actual object.

---

Parameters

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

Returns

Returns a positive value if the object pointed to by the loc_id and name combination exists.

Returns 0 if the object pointed to by the loc_id and name combination does not exist.

Returns a negative value when the function fails.

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

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

Example

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

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

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

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

Warning

Failure Modes:

If loc_id and name both exist, but the combination does not resolve to an object, the function will return 0 (zero); the function does not fail in this case.

If either the location or the link specified by the loc_id and name combination does not exist, the function will fail, returning a negative value.

Note that verifying the existence of an object within an HDF5 file is a multistep process. An application can be certain the object does not exist only if H5Lexists() and H5Oexists_by_name() have been used to verify the existence of the links and groups in the hierarchy above that object. The example above, in the function description, provides a step-by-step description of that verification process.

Version

1.8.11 Fortran subroutine introduced in this release.

Since

1.8.5

H5Oflush()

herr_t H5Oflush

(

hid_t

obj_id

)

Flushes all buffers associated with an HDF5 object to disk.

---

Parameters

[in]

obj_id

Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.

Returns

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

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

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

Warning

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

Note

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

See also

H5Dflush(), H5Drefresh(), H5Oflush(), H5Grefresh(), H5Oflush(), H5Orefresh(), H5Tflush(), H5Trefresh()

H5DOappend(), H5Fstart_swmr_write(), H5Pget_append_flush(), H5Pget_object_flush_cb(), H5Pset_append_flush(), H5Pset_object_flush_cb()

H5Oare_mdc_flushes_disabled(), H5Odisable_mdc_flushes(), H5Oenable_mdc_flushes()

Since

1.10.0

H5Oget_comment()

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

Retrieves comment for specified object.

---

Parameters

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

Returns

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

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

The target object is specified by an identifier, object_id.

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

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

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

Version

1.8.11 Fortran subroutine introduced in this release.

Since

1.8.0

H5Oget_comment_by_name()

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

Retrieves comment for specified object.

---

Parameters

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

Returns

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

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

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

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

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

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

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

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

Version

1.8.11 Fortran subroutine introduced in this release.

Since

1.8.0

H5Oget_info1()

herr_t H5Oget_info1	(	hid_t	loc_id,
		H5O_info1_t *	oinfo
	)

Retrieves the metadata for an object specified by an identifier.

---

Parameters

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

Returns

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

Deprecated:

As of HDF5-1.12 this function has been deprecated in favor of the function H5Oget_info3() or the macro H5Oget_info.

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

Note

If you are iterating through a lot of different objects to retrieve information via the H5Oget_info() family of routines, you may see memory building up. This can be due to memory allocation for metadata, such as object headers and messages, when the iterated objects are put into the metadata cache.

If the memory buildup is not desirable, you can configure a smaller cache via H5Fset_mdc_config() or set the file access property list via H5Pset_mdc_config(). A smaller sized cache will force metadata entries to be evicted from the cache, thus freeing the memory associated with the entries.

Version

1.10.5 The macro H5Oget_info was removed and the function H5Oget_info1() was copied to H5Oget_info().

1.10.3 Function H5Oget_info() was copied to H5Oget_info1(), and the macro H5Oget_info was created.

1.8.15 Added a note about the valid values for the version field in the H5O_hdr_info_t structure.

1.8.11 Fortran subroutine introduced in this release.

1.8.10 Added H5O_type_t structure to the Description section.
Separated H5O_hdr_info_t structure from H5O_info_t in the Description section.
Clarified the definition and implementation of the time fields.

Since

1.8.0

H5Oget_info2()

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

Retrieves the metadata for an object specified by an identifier.

---

Parameters

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

Returns

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

Deprecated:

As of HDF5-1.12 this function has been deprecated in favor of the function H5Oget_info3() or the macro H5Oget_info().

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

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

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

Note

If you are iterating through a lot of different objects to retrieve information via the H5Oget_info() family of routines, you may see memory building up. This can be due to memory allocation for metadata, such as object headers and messages, when the iterated objects are put into the metadata cache.

If the memory buildup is not desirable, you can configure a smaller cache via H5Fset_mdc_config() or set the file access property list via H5Pset_mdc_config(). A smaller sized cache will force metadata entries to be evicted from the cache, thus freeing the memory associated with the entries.

Since

1.10.3

H5Oget_info3()

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

Retrieves the metadata for an object specified by an identifier.

---

Parameters

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

Returns

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

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

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

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

Example

An example snippet from examples/h5_attribute.c:

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

Note

If you are iterating through a lot of different objects to retrieve information via the H5Oget_info() family of routines, you may see memory building up. This can be due to memory allocation for metadata, such as object headers and messages, when the iterated objects are put into the metadata cache.

If the memory buildup is not desirable, you can configure a smaller cache via H5Fset_mdc_config() or set the file access property list via H5Pset_mdc_config(). A smaller sized cache will force metadata entries to be evicted from the cache, thus freeing the memory associated with the entries.

Since

1.12.0

H5Oget_info_by_idx1()

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

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

---

Parameters

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

Returns

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

Deprecated:

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

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

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

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

Version

1.10.5 The macro H5Oget_info_by_idx was removed and the function H5Oget_info_by_idx() was copied to H5Oget_info_by_idx1().

1.10.3 Function H5Oget_info_by_idx() was copied to H5Oget_info_by_idx1() and the macro H5Oget_info_by_idx was created.

1.8.11 Fortran subroutine introduced in this release.

Since

1.8.0

H5Oget_info_by_idx2()

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

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

---

Parameters

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

Returns

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

Deprecated:

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

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

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

If loc_id fully specifies the group in which the object resides, 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:

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

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

Since

1.10.3

H5Oget_info_by_idx3()

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

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

---

Parameters

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

Returns

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

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

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

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

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

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

Example

An example snippet from test/titerate.c:

 
        ret = H5Oget_info_by_idx3(root_group, ".", H5_INDEX_NAME, H5_ITER_INC, (hsize_t)i, &oinfo,
                                  H5O_INFO_BASIC, H5P_DEFAULT);
        CHECK(ret, FAIL, "H5Oget_info_by_idx");
 

Since

1.12.0

H5Oget_info_by_name1()

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

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

---

Parameters

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

Returns

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

Deprecated:

As of HDF5-1.12 this function has been deprecated in favor of the function H5Oget_info_by_name2() or the macro H5Oget_info_by_name.

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

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

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

Version

1.10.5 The macro H5Oget_info_by_name was removed and the function H5Oget_info_by_name1() was copied to H5Oget_info_by_name().

1.10.3 Function H5Oget_info_by_name() was copied to H5Oget_info_by_name1() and the macro H5Oget_info_by_name was created.

1.8.8 Fortran 2003 subroutine and h5o_info_t derived type introduced in this release.

Since

1.8.0

H5Oget_info_by_name2()

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

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

---

Parameters

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

Returns

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

Deprecated:

As of HDF5-1.12 this function has been deprecated in favor of the function H5Oget_info_by_name3() or the macro H5Oget_info_by_name().

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

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

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

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

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

Since

1.10.3

H5Oget_info_by_name3()

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

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

---

Parameters

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

Returns

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

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

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

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

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

Example

An example snippet from test/vol.c:

 
    if (H5Oget_info_by_name3(fid, NATIVE_VOL_TEST_GROUP_NAME, &object_info, H5O_INFO_ALL, H5P_DEFAULT) < 0)
        TEST_ERROR;
 

Since

1.12.0

H5Oget_native_info()

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

Retrieve native file format information about an object.

---

Parameters

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

Returns

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

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

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

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

Example

An example snippet from test/tfile.c:

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

Since

1.12.0

H5Oget_native_info_by_idx()

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

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

---

Parameters

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

Returns

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

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

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

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

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

Since

1.12.0

H5Oget_native_info_by_name()

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

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

---

Parameters

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

Returns

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

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

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

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

Example

An example snippet from test/tfile.c:

 
    /*
     * Make sure the root group still has the correct object header version
     */
    ret = H5Oget_native_info_by_name(file, "/", &ninfo, H5O_NATIVE_INFO_HDR, H5P_DEFAULT);
 

Since

1.12.0

H5Oincr_refcount()

herr_t H5Oincr_refcount

(

hid_t

object_id

)

Increments an object reference count.

---

Parameters

[in]

object_id

Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.

Returns

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

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

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

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

Warning

This function must be used with care!

Improper use can lead to inaccessible data, wasted space in the file, or file corruption.

Version

1.8.11 Fortran subroutine introduced in this release.

Since

1.8.0

H5Olink()

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

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

---

Parameters

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

Returns

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

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

H5Olink() is designed for two purposes:

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

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

Example:

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

// Creates a link creation property list (LCPL).
hid_t lcpl_id = H5Pcreate(H5P_LINK_CREATE);
 
// Sets "create missing intermediate groups" property in that LCPL.
int status = H5Pset_create_intermediate_group(lcpl_id, true);
 
// Creates a group without linking it into the file structure.
hid_t gid  = H5Gcreate_anon(file_id, H5P_DEFAULT, H5P_DEFAULT);
 
// Links group into file structure.
status = H5Olink(gid, file_id, "/A/B01/C", lcpl_id, H5P_DEFAULT);

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

Version

1.8.1 Fortran subroutine introduced in this release.

Since

1.8.0

H5Oopen()

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

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

---

Parameters

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

Returns

Returns an object identifier if successful; otherwise returns H5I_INVALID_HID.

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

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

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

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

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

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

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

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

Version

1.8.1 Fortran subroutine introduced in this release.

Since

1.8.0

H5Oopen_by_addr()

hid_t H5Oopen_by_addr	(	hid_t	loc_id,
		haddr_t	addr
	)

Opens an object using its address within an HDF5 file.

---

Parameters

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

Returns

Returns an object identifier if successful; otherwise returns H5I_INVALID_HID.

Deprecated:

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

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

loc_id is a location identifier in the file.

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

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

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

Warning

This function must be used with care!

Improper use can lead to inaccessible data, wasted space in the file, or file corruption.

This function is dangerous if called on an invalid address. The risk can be safely overcome by retrieving the object address with H5Gget_objinfo() or H5Lget_info() immediately before calling H5Oopen_by_addr(). The immediacy of the operation can be important; if time has elapsed and the object has been deleted from the file, the address will be invalid, and file corruption can result.

Version

1.8.4 Fortran subroutine added in this release.

Since

1.8.0

H5Oopen_by_idx()

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

Opens the nth object in a group.

---

Parameters

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

Returns

Returns an object identifier if successful; otherwise returns H5I_INVALID_HID.

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

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

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

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

H5_INDEX_NAME	Lexicographic order on name
H5_INDEX_CRT_ORDER	Index on creation order

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

H5_ITER_INC	Increasing order
H5_ITER_DEC	Decreasing order
H5_ITER_NATIVE	Fastest available order

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

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

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

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

Version

1.8.1 Fortran subroutine introduced in this release.

Since

1.8.0

H5Oopen_by_token()

hid_t H5Oopen_by_token	(	hid_t	loc_id,
		H5O_token_t	token
	)

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

---

Parameters

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

Returns

Returns an object identifier if successful; otherwise returns H5I_INVALID_HID.

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

Since

1.12.0

H5Orefresh()

herr_t H5Orefresh

(

hid_t

oid

)

Refreshes all buffers associated with an HDF5 object.

---

Parameters

[in]

oid

Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute.

Returns

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

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

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

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

Since

1.10.0

H5Oset_comment()

herr_t H5Oset_comment	(	hid_t	obj_id,
		const char *	comment
	)

Sets comment for specified object.

---

Parameters

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

Returns

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

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

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

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

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

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

Version

1.8.11 Fortran subroutine introduced in this release.

Since

1.8.0

H5Oset_comment_by_name()

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

Sets comment for specified object.

---

Parameters

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

Returns

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

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

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

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

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

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

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

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

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

Version

1.8.11 Fortran subroutine introduced in this release.

Since

1.8.0

H5Otoken_cmp()

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

Compares two VOL connector object tokens.

---

Parameters

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

Returns

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

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

H5O_token_t is defined in H5public.h as follows:

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

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

cmp_value	Result
> 0	token1 > token2
< 0	token1 < token2
0	token1 = token2

Example

An example snippet from test/links.c:

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

Since

1.12.0

H5Otoken_from_str()

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

Deserializes a string into a connector object token.

---

Parameters

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

Returns

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

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

Since

1.12.0

H5Otoken_to_str()

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

Serializes a connector's object token into a string.

---

Parameters

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

Returns

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

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

Since

1.12.0

H5Ovisit1()

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

Recursively visits all objects accessible from a specified object.

---

Parameters

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

Returns

On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.

On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

Deprecated:

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

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

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

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

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

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

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

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

Version

1.10.5 The macro H5Ovisit was removed and the function H5Ovisit1() was copied to H5Ovisit().

1.10.3 Function H5Ovisit() was copied to H5Ovisit1(), and the macro H5Ovisit was created.

1.8.8 Fortran subroutine introduced in this release.

Since

1.8.0

H5Ovisit2()

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

Recursively visits all objects accessible from a specified object.

---

Parameters

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

Returns

On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.

On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

Deprecated:

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

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

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

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

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

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

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

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

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

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

Attention

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

Since

1.10.3

H5Ovisit3()

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

Recursively visits all objects accessible from a specified object.

---

Parameters

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

Returns

On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.

On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

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

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

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

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

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

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

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

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

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

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

Attention

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

Example

An example snippet from test/links.c:

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

Since

1.12.0

H5Ovisit_by_name1()

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

Recursively visits all objects starting from a specified object.

---

Parameters

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

Returns

On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.

On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

Deprecated:

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

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

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

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

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

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

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

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

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

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

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

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

Attention

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

Version

1.10.5 The macro H5Ovisit_by_name was removed and the function H5Ovisit_by_name1() was copied to H5Ovisit_by_name.

1.10.3 The H5Ovisit_by_name() function was renamed to H5Ovisit_by_name1(), and the macro H5Ovisit_by_name was created.

1.8.11 Fortran subroutine introduced in this release.

Since

1.8.0

H5Ovisit_by_name2()

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

Recursively visits all objects starting from a specified object.

---

Parameters

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

Returns

On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.

On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

Deprecated:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Attention

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

Since

1.10.3

H5Ovisit_by_name3()

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

Recursively visits all objects accessible from a specified object.

---

Parameters

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

Returns

On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.

On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

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

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

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

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

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

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

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

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

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

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

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

Attention

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

Example

An example snippet from test/links.c:

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

Since

1.12.0