|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5DS H5IM H5LT H5PT H5TB H5 H5A H5D H5E H5F H5G H5I H5L H5O H5P H5R H5S H5T H5Z Tools Datatypes Fortran Compatibility Macros |
The C Interfaces:
H5Oclose(
hid_t object_id
)
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.
hid_t object_id
|
IN: Object identifier |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Ocopy(
hid_t src_loc_id,
const char *src_name,
hid_t dst_loc_id,
const char *dst_name,
hid_t ocp_plist_id,
hid_t lcpl_id
)
H5Ocopy copies the group, dataset or named 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 new copy will be created with the name dst_name.
dst_name must not pre-exist in the destination location;
if dst_name already exists at the location
dst_loc_id, H5Ocopy will fail.
The new copy of the object is created with the creation property lists
specified by ocp_plist_id and lcpl_id.
Several flags are available to govern the behavior of
H5Ocopy.
These flags are set in the creation property list
cplist_id with
H5Pset_copy_object and
H5Pset_create_intermediate_group.
All of the available flags are described at
H5Pset_copy_object.
hid_t src_loc_id
|
Object identifier indicating the location of the source object to be copied |
const char *src_name
|
Name of the source object to be copied |
hid_t dst_loc_id
|
Location identifier specifying the destination |
const char *dst_name
|
Name to be assigned to the new copy |
hid_t ocp_plist_id
|
Object copy property list |
hid_t lcpl_id
|
Link creation property list for the new hard link |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Odecr_refcount(
hid_t object_id
)
H5Odecr_refcount decrements the hard link reference count
for an object. It should be used any time a user-defined link
that references an object by address is deleted.
In general, H5Oincr_refcount will have been used
previously, when the link was created.
An object’s reference count is the number of hard links in the file that point to that object. See the “Programming Model” section of the “HDF5 Groups” chapter in the HDF5 User’s Guide for a more complete discussion of reference counts.
If a user application needs to determine an object’s
reference count, an
H5Gget_objinfo
call is required; the reference count is returned in the
nlink field of the H5G_stat_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. |
hid_t object_id
|
IN: Object identifier |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Oget_comment(
hid_t object_id,
char *comment,
size_t bufsize,
)
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 comment, including the NULL
terminator, is specified in bufsize.
If bufsize is unknown,
a preliminary H5Oget_comment call
with the pointer comment set to NULL
will return the size of the comment
without the NULL terminator.
If bufsize is set to a smaller value than described above,
only bufsize bytes of the comment,
without a NULL terminator, are returned in
comment.
If an object does not have a comment, the empty string
is returned in comment.
hid_t object_id |
IN: Identifier for the target object. |
char *comment |
OUT: The comment. |
size_t bufsize |
IN: 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.
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Oget_comment_by_name(
hid_t loc_id,
const char *name,
char *comment,
size_t bufsize,
hid_t lapl_id
)
H5Oget_comment_by_name retrieves the comment for an
object in the buffer comment.
The target object is specified by loc_id and
name.
loc_id can specify any object in the file.
name can be one of the following:
— The name of the object relative to
loc_id
— An absolute name of the object,
starting from /, the file’s root group
— A dot (.),
if loc_id fully specifies the object
The size in bytes of the comment, including the NULL
terminator, is specified in bufsize.
If bufsize is unknown,
a preliminary H5Oget_comment_by_name call
with the pointer comment set to NULL
will return the size of the comment
without the NULL terminator.
If bufsize is set to a smaller value than described above,
only bufsize bytes of the comment,
without a NULL terminator, are returned in
comment.
If an object does not have a comment, the empty string
is returned in comment.
lapl_id contains a link access property list identifier.
A link access propety list can come into play when traversing links
to access an object.
hid_t loc_id |
IN: Identifier of a file, group, dataset, or named datatype. |
const char *name |
IN: Name of the object whose comment is to be
retrieved, specified as a path relative to loc_id.
name can be '.' (a dot) if loc_id
fully specifies the object for which the associated comment
is to be retrieved.
|
char *comment |
OUT: The comment. |
size_t bufsize |
IN: Anticipated required size of the
comment buffer. |
hid_t lapl_id |
IN: 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.
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Oget_info(
hid_t object_id,
H5O_info_t *object_info
)
H5Oget_info specifies an object by its identifier,
object_id, and retrieves the metadata describing that object
in the struct object_info
The struct H5O_info_t is defined (in H5Opublic.h)
as follows :
typedef struct H5O_info_t {
unsigned long fileno; /* File number that object is */
/* located in */
haddr_t addr; /* Object address in file */
H5O_type_t type; /* Basic object type (group, */
/* dataset, etc.) */
unsigned rc; /* Reference count of object */
time_t atime; /* Access time */
time_t mtime; /* Modification time */
time_t ctime; /* Change time */
time_t btime; /* Birth time */
hsize_t num_attrs; /* # of attributes attached to object */
struct {
unsigned version; /* Version number of header format in */
/* file */
unsigned nmesgs; /* Number of object header messages */
unsigned nchunks; /* Number of object header chunks */
unsigned flags; /* Object header status flags */
struct {
hsize_t total; /* Total space for storing object */
/* header in file */
hsize_t meta; /* Space within header for object */
/* header metadata information */
hsize_t mesg; /* Space within header for actual */
/* message information */
hsize_t free; /* Free space within object header */
} space;
struct {
uint64_t present; /* Flags to indicate presence of */
/* message type in header */
uint64_t shared; /* Flags to indicate message type is */
/* shared in header */
} mesg;
} hdr;
/* Extra metadata storage for obj & attributes */
struct {
H5_ih_info_t obj; /* v1/v2 B-tree & local/fractal heap */
/* for groups, B-tree for chunked */
/* datasets */
H5_ih_info_t attr; /* v2 B-tree & heap for attributes */
} meta_size;
} H5O_info_t;
hid_t object_id |
IN: Identifier for target object |
H5O_info_t *object_info |
OUT: Buffer in which to return object information |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Oget_info_by_idx(
hid_t loc_id,
const char *group_name,
H5_index_t index_field,
H5_iter_order_t order,
hsize_t n,
H5O_info_t *object_info,
hid_t lapl_id
)
H5Oget_info_by_idx specifies a location,
loc_id;
a group name, group_name;
an index by which obects in that group are tracked,
index_field;
the order by which the index is to be traversed, order;
and an object’s position n within that index
and retrieves the metadata describing that object
in the struct object_info
object_info, in which the object information is returned,
is a struct of type H5O_info_t. This struct type is
described in the H5Oget_info
function entry.
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 NULL.
hid_t loc_id |
IN: File or group identifier specifying location of group in which object is located |
const char *group_name |
IN: Name of group in which object is located |
H5_index_t index_field |
IN: Index or field that determines the order |
H5_iter_order_t order |
IN: Order within field or index |
hsize_t n |
IN: Object for which information is to be returned |
H5O_info_t *object_info |
OUT: Buffer in which to return object information |
hid_t lapl_id |
IN: Link access property list (Not currently used; pass as NULL.) |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Oget_info_by_name(
hid_t loc_id,
const char *object_name,
H5O_info_t *object_info,
hid_t lapl_id
)
H5Oget_info_by_name specifies an object’s
location and name, loc_id and object_name,
respectively, and retrieves the metadata describing that object
in the struct object_info.
The struct H5O_info_t is defined (in H5Opublic.h)
as follows:
typedef struct H5O_info_t {
unsigned long fileno; /* File number that object is */
/* located in */
haddr_t addr; /* Object address in file */
H5O_type_t type; /* Basic object type (group, */
/* dataset, etc.) */
unsigned rc; /* Reference count of object */
time_t atime; /* Access time */
time_t mtime; /* Modification time */
time_t ctime; /* Change time */
time_t btime; /* Birth time */
hsize_t num_attrs; /* # of attributes attached to object */
struct {
unsigned version; /* Version number of header format in */
/* file */
unsigned nmesgs; /* Number of object header messages */
unsigned nchunks; /* Number of object header chunks */
unsigned flags; /* Object header status flags */
struct {
hsize_t total; /* Total space for storing object */
/* header in file */
hsize_t meta; /* Space within header for object */
/* header metadata information */
hsize_t mesg; /* Space within header for actual */
/* message information */
hsize_t free; /* Free space within object header */
} space;
struct {
uint64_t present; /* Flags to indicate presence of */
/* message type in header */
uint64_t shared; /* Flags to indicate message type is */
/* shared in header */
} mesg;
} hdr;
/* Extra metadata storage for obj & attributes */
struct {
H5_ih_info_t obj; /* v1/v2 B-tree & local/fractal heap */
/* for groups, B-tree for chunked */
/* datasets */
H5_ih_info_t attr; /* v2 B-tree & heap for attributes */
} meta_size;
} H5O_info_t;
lapl_id,
is not currently used; it should be passed in as NULL.
hid_t loc_id |
IN: File or group identifier specifying location of group in which object is located |
const char *name |
IN: Name of group, relative to
loc_id |
H5O_info_t *object_info |
OUT: Buffer in which to return object information |
hid_t lapl_id |
IN: Link access property list (Not currently used; pass as NULL.) |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Oincr_refcount(
hid_t object_id
)
H5Oincr_refcount increments the hard link reference count
for an object. It should be used any time a user-defined link
that references an object by address is added. When the
link is deleted, H5Odecr_refcount should be used.
An object’s reference count is the number of hard links in the file that point to that object. See the “Programming Model” section of the “HDF5 Groups” chapter in the HDF5 User’s Guide for a more complete discussion of reference counts.
If a user application needs to determine an object’s
reference count, an
H5Gget_objinfo
call is required; the reference count is returned in the
nlink field of the H5G_stat_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. |
hid_t object_id
|
IN: Object identifier |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Olink(
hid_t object_id,
hid_t new_loc_id,
const char *new_link_name,
hid_t lcpl,
hid_t lapl
)
H5Olink creates a new hard link to an object in
an HDF5 file.
new_loc_id and new_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:
H5*create_anon
functions or with H5Tcommit_anon.
| |
|
|
lcpl and lapl are the
link creation and access property lists associated with the
new link.
hid_t object_id |
IN: Object to be linked. |
hid_t new_loc_id |
IN: File or group identifier specifying location at which object is to be linked. |
const char *new_link_name |
IN: Name of link to be created, relative to
new_loc_id. |
hid_t lcpl_id |
IN: Link creation property list identifier. |
hid_t lapl_id |
IN: Link access property list identifier. |
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:
hid_t lcpl_id = H5Pcreate(H5P_LINK_CREATE); /* Creates a link creation
* property list (LCPL). */
int status = H5Pset_create_intermediate_group(lcpl_id, TRUE);
/* Sets "create missing intermediate
* groups" property in that LCPL. */
hid_t gid = H5Gcreate_anon(file_id, H5P_DEFAULT, H5P_DEFAULT);
/* Creates a group without linking
* it into the file structure. */
status = H5Olink(obj_id, file_id, "/A/B01/C", lcpl_id, H5P_DEFAULT);
/* Links group into file structure.*/
Note that unless the object is intended to be temporary,
the H5Olink call is mandatory if an object created
with one of the H5*create_anon functions
(or with H5Tcommit_anon)
is to be retained in the file;
without an H5Olink call, the object will not be linked into
the HDF5 file structure and will be deleted when the file is closed.
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Oopen(
hid_t loc_id,
const char *name,
hid_t lapl_id
)
H5Oopen opens a group, dataset, or named datatype
specified by a location, loc_id, and a path name,
name, in an HDF5 file.
This function opens the object in the same manner as
H5Gopen, H5Topen, and H5Dopen.
However, H5Oopen does not require the type of object
to be known beforehand. This can be useful with user-defined links,
for instance, when only a path may be known.
H5Oopen cannot be used to open a
dataspace, attribute, property list, or file.
Once an object of unknown type has been opened with
H5Oopen, the type of that object can be determined
by means of an
H5Iget_type
call.
loc_id can be either a file or group identifier.
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.
hid_t loc_id
|
IN: File or group identifier |
const char *name
|
IN: Path to the object,
relative to loc_id.
|
hid_t lapl_id
|
IN: Access property list identifier for the link pointing to the object |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Oopen_by_addr(
hid_t loc_id,
haddr_t addr
)
H5Oopen_by_addr opens a group, dataset, or 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 can be either the file identifier or a
group identifier in the file. In either case, the HDF5 Library
uses the identifier only to identify the file.
The object’s address within the file, addr, is the
byte offset of the first byte of the object header from the beginning
of the HDF5 file space, i.e., from the beginning of the super block
(see the “HDF5 Storage Model” section of the
“The
HDF5 Data Model and File Structure” chapter
of the HDF5 User’ 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_linkinfo
returns the address in the address field of the
H5L_linkinfo_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.
This function is dangerous if called on an invalid address.
The risk can be safely overcome by retrieving the object address
with |
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 loc_id
|
IN: File or group identifier |
haddr_t addr
|
IN: Object’s address in the file |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Oopen_by_idx(
hid_t loc_id,
const char *group_name,
H5_index_t index_field,
H5_iter_order_t order,
hsize_t n,
hid_t lapl_id
)
H5Oopen_by_idx description...
If loc_id fully specifies the group in which the object
resides, group_name can be a dot (.).
hid_t loc_id |
IN: File or group identifier specifying location of group in which object is located |
const char *group_name |
IN: Name of group in which object is located |
H5_index_t index_field |
IN: Index or field that determines the order |
H5_iter_order_t order |
IN: Order within field or index |
hsize_t n |
IN: Object to open |
hid_t lapl_id |
IN: Link access property list |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Oset_comment(
hid_t object_id,
const char *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, object_id.
If comment is the empty string or a
null pointer, any existing comment message is removed from the object.
Comments should be relatively short, null-terminated, ASCII strings.
Comments can be attached to any object that has an object header, e.g., datasets, groups, and named datatypes, but not symbolic links.
hid_t object_id |
IN: Identifier of the target object |
const char *comment |
IN: The new comment. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Oset_comment_by_name(
hid_t loc_id,
const char *name,
const char *comment,
hid_t lapl_id
)
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 relative to
loc_id
— An absolute name of the object,
starting from /, the file’s root group
— A dot (.),
if loc_id fully specifies the object
If comment is the empty string or a
null pointer, any existing comment message is removed from the object.
Comments should be relatively short, null-terminated, ASCII strings.
Comments can be attached to any object that has an object header, e.g., datasets, groups, and named datatypes, but not symbolic links.
lapl_id contains a link access property list identifier.
A link access propety list can come into play when traversing links
to access an object.
hid_t loc_id |
IN: Identifier of a file, group, dataset, or named datatype. |
const char *name |
IN: Name of the object whose comment is to be
set or reset, specified as a path relative to loc_id.
name can be '.' (a dot) if loc_id
fully specifies the object for which the comment is to be set.
|
const char *comment |
IN: The new comment. |
hid_t lapl_id |
IN: Link access property list identifier. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Ovisit(
hid_t group_id,
H5_index_t index_type,
H5_iter_order_t order,
H5O_iterate_t op,
void *op_data
)
H5Ovisit is a recursive iteration function
to visit the object object_id and,
if object_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 H5Literate.
The group serving as the root of the iteration is specified by
it’s group identifier, group_id
Two parameters are used to establish the iteration:
index_type and order.
index_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
unnecesary, so the iteration may begin more quickly.
Valid values include the following:
H5_INDEX_NAME
| Alpha-numeric index on name | |
H5_INDEX_CRT_ORDER
| Index on creation order |
Note that the index type passed in index_type is a
best effort setting.
If the application passes in a value indicating iteration in
creation order and a group is encountered that was not tracked
in creation order, that group will be iterated over in
alpha-numeric order by name, or name order.
(Name order is the native order used by the HDF5 Library
and is always available.)
order specifies the order in which objects are to be
inspected along the index specified in index_type.
Valid values include the following:
H5_ITER_INC
| Increasing order | |
H5_ITER_DEC
| Decreasing order | |
H5_ITER_NATIVE
| Fastest available order |
The protoype of the callback function op is as follows
(as defined in the source code file H5Opublic.h):
(*H5O_iterate_t)(
hid_t o_id,
const char *name,
const H5O_info_t *info,
void *op_data)
The parameters of this callback function have the following values or meanings:
|
o_id
|
Object that serves as root of the iteration; same value
as the H5Ovisit group_id parameter
|
|
name
|
Name of object, relative to o_id,
being examined at current step of the iteration
|
|
info
| H5O_info_t struct containing information regarding that object |
|
op_data
|
User-defined pointer to data required by the application
in processing the object;
a pass-through of the op_data pointer provided
with the H5Ovisit_by_name function call
|
The H5O_info_t struct is defined (in H5Opublic.h)
as follows:
typedef struct {
unsigned long fileno; /* File number that object is */
/* located in */
haddr_t addr; /* Object address in file */
H5O_type_t type; /* Basic object type (group, */
/* dataset, etc.) */
unsigned rc; /* Reference count of object */
time_t atime; /* Access time */
time_t mtime; /* Modification time */
time_t ctime; /* Change time */
time_t btime; /* Birth time */
hsize_t num_attrs; /* Number of attributes attached */
/* to object */
struct {
unsigned version; /* Version number of header format */
/* in file */
unsigned nmesgs; /* Number of object header messages */
unsigned nchunks; /* Number of object header chunks */
unsigned flags; /* Object header status flags */
struct {
hsize_t total; /* Total space for storing */
/* object header in file */
hsize_t meta; /* Space within header for object */
/* header metadata information */
hsize_t mesg; /* Space within header for actual */
/* message information */
hsize_t free; /* Free space within object header */
} space;
struct {
uint64_t present; /* Flags to indicate presence of */
/* message type in header */
uint64_t shared; /* Flags to indicate whether */
/* message type is shared in header*/
} mesg;
} hdr;
/* Extra metadata storage for obj & attributes */
struct {
H5_ih_info_t obj; /* v1/v2 B-tree & local/fractal */
/* heap for groups; */
/* B-tree for chunked datasets */
H5_ih_info_t attr; /* v2 B-tree & heap for attributes */
} meta_size;
} H5O_info_t;
The H5Ovisit op_data parameter is a
user-defined pointer to the data required to process objects
in the course of the iteration.
This pointer is passed back to each step of the iteration in
the callback function’s op_data parameter.
H5Lvisit and
H5Ovisit
are companion functions:
one for examining and operating on links;
the other for examining and operating on the objects that
those links point to.
Both functions ensure that by the time the function completes
successfully, every link or object below the specified point in the
file has been presented to the application for whatever
processing the application requires.
hid_t object_id
|
IN: Identifier of the object at which the recursive iteration begins. |
H5_index_t index_type
|
IN: Type of index; valid values include:
H5_INDEX_NAME
H5_INDEX_CRT_ORDER
|
H5_iter_order_t order
|
IN: Order in which index is traversed;
valid values include:
H5_ITER_DEC
H5_ITER_INC
H5_ITER_NATIVE
|
H5O_iterate_t op
|
IN: Callback function passing data regarding the object to the calling application |
void *op_data
|
IN: User-defined pointer to data required by the application for its processing of the object |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Ovisit_by_name(
hid_t loc_id,
const char *object_name,
H5_index_t index_type,
H5_iter_order_t order,
H5O_iterate_t op,
void *op_data,
hid_t lapl_id
)
H5Ovisit_by_name is a recursive iteration function
to visit the object specified by the loc_id /
object_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 / object_name parameter pair.
loc_id specifies a file or an object in a file;
object_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, object_name should
be '.' (a dot).
(Note that when loc_id fully specifies the the
object that is to serve as the root of the iteration,
the user may wish to consider using
H5Ovisit
instead of H5Ovisit_by_name.)
Two parameters are used to establish the iteration:
index_type and order.
index_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
unnecesary, so the iteration may begin more quickly.
Valid values include the following:
H5_INDEX_NAME
| Alpha-numeric index on name | |
H5_INDEX_CRT_ORDER
| Index on creation order |
Note that the index type passed in index_type is a
best effort setting.
If the application passes in a value indicating iteration in
creation order and a group is encountered that was not tracked
in creation order, that group will be iterated over in
alpha-numeric order by name, or name order.
(Name order is the native order used by the HDF5 Library
and is always available.)
order specifies the order in which objects are to be
inspected along the index specified in index_type.
Valid values include the following:
H5_ITER_INC
| Increasing order | |
H5_ITER_DEC
| Decreasing order | |
H5_ITER_NATIVE
| Fastest available order |
The protoype of the callback function op is as follows
(as defined in the source code file H5Opublic.h):
(*H5O_iterate_t)(
hid_t o_id,
const char *name,
const H5O_info_t *info,
void *op_data)
The parameters of this callback function have the following values or meanings:
|
g_id
|
Object that serves as root of the iteration,
i.e., identifier of the Object specified by the
H5Ovisit_by_name loc_id /
object_name parameter pair
|
|
name
|
Name of object, relative to o_id,
being examined at current step of the iteration
|
|
info
| H5O_info_t struct containing information regarding that object |
|
op_data
|
User-defined pointer to data required by the application
in processing the object;
a pass-through of the op_data pointer provided
with the H5Ovisit_by_name function call
|
The H5O_info_t struct is defined (in H5Opublic.h)
as follows:
typedef struct {
unsigned long fileno; /* File number that object is */
/* located in */
haddr_t addr; /* Object address in file */
H5O_type_t type; /* Basic object type (group, */
/* dataset, etc.) */
unsigned rc; /* Reference count of object */
time_t atime; /* Access time */
time_t mtime; /* Modification time */
time_t ctime; /* Change time */
time_t btime; /* Birth time */
hsize_t num_attrs; /* Number of attributes attached */
/* to object */
struct {
unsigned version; /* Version number of header format */
/* in file */
unsigned nmesgs; /* Number of object header messages */
unsigned nchunks; /* Number of object header chunks */
unsigned flags; /* Object header status flags */
struct {
hsize_t total; /* Total space for storing */
/* object header in file */
hsize_t meta; /* Space within header for object */
/* header metadata information */
hsize_t mesg; /* Space within header for actual */
/* message information */
hsize_t free; /* Free space within object header */
} space;
struct {
uint64_t present; /* Flags to indicate presence of */
/* message type in header */
uint64_t shared; /* Flags to indicate whether */
/* message type is shared in header*/
} mesg;
} hdr;
/* Extra metadata storage for obj & attributes */
struct {
H5_ih_info_t obj; /* v1/v2 B-tree & local/fractal */
/* heap for groups; */
/* B-tree for chunked datasets */
H5_ih_info_t attr; /* v2 B-tree & heap for attributes */
} meta_size;
} H5O_info_t;
The H5Ovisit_by_name op_data parameter is a
user-defined pointer to the data required to process objects
in the course of the iteration.
This pointer is passed back to each step of the iteration in
the callback function’s op_data parameter.
lapl_id is a link access property list.
In the general case, when default link access properties are
acceptable, this can be passed in as H5P_DEFAULT.
An example of a situation that requires a non-default link access
property list is when the link is an external link; an external link
may require that a link prefix be set in a link access property list
(see
H5Pset_elink_prefix).
H5Lvisit_by_name and
H5Ovisit_by_name
are companion functions:
one for examining and operating on links;
the other for examining and operating on the objects that
those links point to.
Both functions ensure that by the time the function completes
successfully, every link or object below the specified point in the
file has been presented to the application for whatever
processing the application requires.
hid_t loc_id
|
IN: Identifier of a file or group |
const char *object_name
|
IN: Name of the object,
generally relative to loc_id,
that will serve as root of the iteration
|
H5_index_t index_type
|
IN: Type of index; valid values include:
H5_INDEX_NAME
H5_INDEX_CRT_ORDER
|
H5_iter_order_t order
|
IN: Order in which index is traversed;
valid values include:
H5_ITER_DEC
H5_ITER_INC
H5_ITER_NATIVE
|
H5O_iterate_t op
|
IN: Callback function passing data regarding the object to the calling application |
void *op_data
|
IN: User-defined pointer to data required by the application for its processing of the object |
hid_t lapl_id
|
IN: Link access property list identifier |
| Release | C |
| 1.8.0 | Function introduced in this release. |
|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5DS H5IM H5LT H5PT H5TB H5 H5A H5D H5E H5F H5G H5I H5L H5O H5P H5R H5S H5T H5Z Tools Datatypes Fortran Compatibility Macros |
