HDF5 1.14.5
API Reference
|
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 |
---|---|
hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id) Creates an HDF5 file. herr_t H5Ocopy(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id) Copies an object in an HDF5 file. herr_t H5Pset_create_intermediate_group(hid_t plist_id, unsigned crt_intmd) Specifies in property list whether to create missing intermediate groups. hid_t H5Pcreate(hid_t cls_id) Creates a new property list as an instance of a property list class. | 72 if (H5Oget_info_by_name(file, path, &info, H5O_INFO_BASIC | H5O_INFO_NUM_ATTRS, H5P_DEFAULT) < 0) {
hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id) Opens an existing HDF5 file. Definition H5Opublic.h:145 |
Update | Delete |
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. | herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id) Removes a link from a group. |
Macros | |
#define | H5Oget_info H5Oget_info3 |
#define | H5Oget_info_by_idx H5Oget_info_by_idx3 |
#define | H5Oget_info_by_name H5Oget_info_by_name3 |
#define | H5Ovisit H5Ovisit3 |
#define | H5Ovisit_by_name H5Ovisit_by_name3 |
Functions | |
hid_t | H5Oopen (hid_t loc_id, const char *name, hid_t lapl_id) |
Opens an object in an HDF5 file by location identifier and path name. | |
hid_t | H5Oopen_by_token (hid_t loc_id, H5O_token_t token) |
Opens an object in an HDF5 file using its VOL independent token. | |
hid_t | H5Oopen_by_idx (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id) |
Opens the nth object in a group. | |
htri_t | H5Oexists_by_name (hid_t loc_id, const char *name, hid_t lapl_id) |
Determines whether a link resolves to an actual object. | |
herr_t | H5Oget_info3 (hid_t loc_id, H5O_info2_t *oinfo, unsigned fields) |
Retrieves the metadata for an object specified by an identifier. | |
herr_t | H5Oget_info_by_name3 (hid_t loc_id, const char *name, H5O_info2_t *oinfo, unsigned fields, hid_t lapl_id) |
Retrieves the metadata for an object, identifying the object by location and relative name. | |
herr_t | H5Oget_info_by_idx3 (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_info2_t *oinfo, unsigned fields, hid_t lapl_id) |
Retrieves the metadata for an object, identifying the object by an index position. | |
herr_t | H5Oget_native_info (hid_t loc_id, H5O_native_info_t *oinfo, unsigned fields) |
Retrieve native file format information about an object. | |
herr_t | H5Oget_native_info_by_name (hid_t loc_id, const char *name, H5O_native_info_t *oinfo, unsigned fields, hid_t lapl_id) |
Retrieve native file format information about an object given its name. | |
herr_t | H5Oget_native_info_by_idx (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_native_info_t *oinfo, unsigned fields, hid_t lapl_id) |
Retrieve native file format information about an object according to the order of an index. | |
herr_t | H5Olink (hid_t obj_id, hid_t new_loc_id, const char *new_name, hid_t lcpl_id, hid_t lapl_id) |
Creates a hard link to an object in an HDF5 file. | |
herr_t | H5Oincr_refcount (hid_t object_id) |
Increments an object reference count. | |
herr_t | H5Odecr_refcount (hid_t object_id) |
Decrements an object reference count. | |
herr_t | H5Ocopy (hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id) |
Copies an object in an HDF5 file. | |
herr_t | H5Oset_comment (hid_t obj_id, const char *comment) |
Sets comment for specified object. | |
herr_t | H5Oset_comment_by_name (hid_t loc_id, const char *name, const char *comment, hid_t lapl_id) |
Sets comment for specified object. | |
ssize_t | H5Oget_comment (hid_t obj_id, char *comment, size_t bufsize) |
Retrieves comment for specified object. | |
ssize_t | H5Oget_comment_by_name (hid_t loc_id, const char *name, char *comment, size_t bufsize, hid_t lapl_id) |
Retrieves comment for specified object. | |
herr_t | H5Ovisit3 (hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate2_t op, void *op_data, unsigned fields) |
Recursively visits all objects accessible from a specified object. | |
herr_t | H5Ovisit_by_name3 (hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate2_t op, void *op_data, unsigned fields, hid_t lapl_id) |
Recursively visits all objects accessible from a specified object. | |
herr_t | H5Oclose (hid_t object_id) |
Closes an object in an HDF5 file. | |
herr_t | H5Oflush (hid_t obj_id) |
Flushes all buffers associated with an HDF5 object to disk. | |
herr_t | H5Orefresh (hid_t oid) |
Refreshes all buffers associated with an HDF5 object. | |
herr_t | H5Odisable_mdc_flushes (hid_t object_id) |
Prevents metadata entries for an HDF5 object from being flushed from the metadata cache to storage. | |
herr_t | H5Oenable_mdc_flushes (hid_t object_id) |
Enables flushing of dirty metadata entries from a file's metadata cache. | |
herr_t | H5Oare_mdc_flushes_disabled (hid_t object_id, hbool_t *are_disabled) |
Retrieves comment for specified object. | |
herr_t | H5Otoken_cmp (hid_t loc_id, const H5O_token_t *token1, const H5O_token_t *token2, int *cmp_value) |
Compares two VOL connector object tokens. | |
herr_t | H5Otoken_to_str (hid_t loc_id, const H5O_token_t *token, char **token_str) |
Serializes a connector's object token into a string. | |
herr_t | H5Otoken_from_str (hid_t loc_id, const char *token_str, H5O_token_t *token) |
Deserializes a string into a connector object token. | |
hid_t | H5Oopen_by_addr (hid_t loc_id, haddr_t addr) |
Opens an object using its address within an HDF5 file. | |
herr_t | H5Oget_info1 (hid_t loc_id, H5O_info1_t *oinfo) |
Retrieves the metadata for an object specified by an identifier. | |
herr_t | H5Oget_info_by_name1 (hid_t loc_id, const char *name, H5O_info1_t *oinfo, hid_t lapl_id) |
Retrieves the metadata for an object, identifying the object by location and relative name. | |
herr_t | H5Oget_info_by_idx1 (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_info1_t *oinfo, hid_t lapl_id) |
Retrieves the metadata for an object, identifying the object by an index position. | |
herr_t | H5Oget_info2 (hid_t loc_id, H5O_info1_t *oinfo, unsigned fields) |
Retrieves the metadata for an object specified by an identifier. | |
herr_t | H5Oget_info_by_name2 (hid_t loc_id, const char *name, H5O_info1_t *oinfo, unsigned fields, hid_t lapl_id) |
Retrieves the metadata for an object, identifying the object by location and relative name. | |
herr_t | H5Oget_info_by_idx2 (hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_info1_t *oinfo, unsigned fields, hid_t lapl_id) |
Retrieves the metadata for an object, identifying the object by an index position. | |
herr_t | H5Ovisit1 (hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate1_t op, void *op_data) |
Recursively visits all objects accessible from a specified object. | |
herr_t | H5Ovisit_by_name1 (hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate1_t op, void *op_data, hid_t lapl_id) |
Recursively visits all objects starting from a specified object. | |
herr_t | H5Ovisit2 (hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate1_t op, void *op_data, unsigned fields) |
Recursively visits all objects accessible from a specified object. | |
herr_t | H5Ovisit_by_name2 (hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate1_t op, void *op_data, unsigned fields, hid_t lapl_id) |
Recursively visits all objects starting from a specified object. | |
#define H5Oget_info H5Oget_info3 |
H5Oget_info() is a macro that is mapped to either H5Oget_info1() or H5Oget_info2() or H5Oget_info3().
#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().
#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().
#define H5Ovisit H5Ovisit3 |
H5Ovisit() is a macro that is mapped to either H5Ovisit1() or H5Ovisit2() or H5Ovisit3().
#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().
Retrieves comment for specified object.
[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 |
are_disabled
will be set to 1
if an object has had flushes disabled and 0
if it has not had flushes disabled. 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.
Closes an object in an HDF5 file.
[in] | object_id | Object identifier |
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.
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.
[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 |
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:
These property lists or flags can be modified to govern the behavior of H5Ocopy() as follows:
lcpl_id
with H5Pset_create_intermediate_group().ocpypl_id
with H5Pset_copy_object().H5Ocopy() will always try to make a copy of the object specified in src_name
.
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.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()).
Decrements an object reference count.
[in] | object_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
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
.
Prevents metadata entries for an HDF5 object from being flushed from the metadata cache to storage.
[in] | object_id | Identifier of the object that will have flushes disabled; may be a group, named datatype, or dataset identifier |
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.
Enables flushing of dirty metadata entries from a file's metadata cache.
[in] | object_id | Identifier of the object that will have flushes re-enabled; may be a group, named datatype, or dataset identifier |
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.
Determines whether a link resolves to an actual object.
[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 |
loc_id
and name
combination exists. loc_id
and name
combination does not exist. 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.
datasetD
in the group
group1/group2/softlink_to_group3/, where group1
is a member of the group specified by loc_id:
group1
exists.group1
exists, use H5Oexists_by_name() to verify that the link group1
resolves to an object.group1
exists, use H5Lexists() again, this time with the name set to group1/group2
, to verify that the link group2
exists in group1
.group2
link exists, use H5Oexists_by_name() to verify that group1/group2
resolves to an object.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
.softlink_to_group3
link exists, use H5Oexists_by_name() to verify that group1/group2/softlink_to_group3
resolves to an object.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.datasetD
exists, use H5Oexists_by_name to verify that group1/group2/softlink_to_group3/datasetD
resolves to an object.datasetD
were in /group1/group2/softlink_to_group3
, the first call to H5Lexists() would have name set to /group1
.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. loc_id
and name
combination does not exist, the function will fail, returning a negative value. Flushes all buffers associated with an HDF5 object to disk.
[in] | obj_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
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.
Retrieves comment for specified object.
[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 |
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
.
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.
[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 |
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:
loc_id
/
, the file's root group
.), if loc_id
fully specifies the objectThe 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.
herr_t H5Oget_info1 | ( | hid_t | loc_id, |
H5O_info1_t * | oinfo | ||
) |
Retrieves the metadata for an object specified by an identifier.
[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 |
H5Oget_info1() specifies an object by its identifier, loc_id
, and retrieves the metadata describing that object in oinfo
.
version
field in the H5O_hdr_info_t structure. herr_t H5Oget_info2 | ( | hid_t | loc_id, |
H5O_info1_t * | oinfo, | ||
unsigned | fields | ||
) |
Retrieves the metadata for an object specified by an identifier.
[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 |
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 |
herr_t H5Oget_info3 | ( | hid_t | loc_id, |
H5O_info2_t * | oinfo, | ||
unsigned | fields | ||
) |
Retrieves the metadata for an object specified by an identifier.
[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 |
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 |
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.
[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 |
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.
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.
[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 |
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.
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.
[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 |
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.
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.
[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 |
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.
h5o_info_t
derived type introduced in this release.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.
[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 |
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.
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.
[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 |
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.
herr_t H5Oget_native_info | ( | hid_t | loc_id, |
H5O_native_info_t * | oinfo, | ||
unsigned | fields | ||
) |
Retrieve native file format information about an object.
[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 |
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:
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.
[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 |
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:
The link access property list, lapl_id
, is not currently used; it should be passed in as H5P_DEFAULT.
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.
[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 |
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:
Increments an object reference count.
[in] | object_id | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
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
.
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.
[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 |
H5Olink() creates a new hard link to an object in an HDF5 file. new_loc_id
and
the location and name of the new link, while new_link_name
specifyobject_id
identifies the object that the link points to.
H5Olink() is designed for two purposes:
lcpl
and lapl
are the link creation and access property lists associated with the new link.
Opens an object in an HDF5 file by location identifier and path name.
[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 |
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().
Opens an object using its address within an HDF5 file.
[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 |
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.
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.
[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 |
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.
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.
[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 |
H5Oopen_by_token() opens an object specified by the object identifier, loc_id
and object token, token
.
Refreshes all buffers associated with an HDF5 object.
[in] | oid | Location identifier of object. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
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.
Sets comment for specified object.
[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 |
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.
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.
[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 |
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:
loc_id
/
, the file's root group
.), if loc_id
fully specifies the objectIf 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.
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.
[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 |
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:
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 |
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.
[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 |
H5Otoken_from_str() deserializes a string, token_str
, into a connector object token, token
, for the object specified by the location identifier, loc_id
.
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.
[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 |
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
.
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.
[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 |
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.
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.
[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 |
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.
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.
[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 |
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.
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.
[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 |
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.
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.
[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 |
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.
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.
[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 |
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.