|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes Collective Calls in Parallel |
| (PDF of complete manual formatted as print volume) | |
The C Interfaces:
A group associates names with objects and provides a mechanism for mapping a name to an object. Since all objects appear in at least one group (with the possible exception of the root object) and since objects can have names in more than one group, the set of all objects in an HDF5 file is a directed graph. The internal nodes (nodes with out-degree greater than zero) must be groups while the leaf nodes (nodes with out-degree zero) are either empty groups or objects of some other type. Exactly one object in every non-empty file is the root object. The root object always has a positive in-degree because it is pointed to by the file super block.
An object name consists of one or more components separated from one another by slashes. An absolute name begins with a slash and the object is located by looking for the first component in the root object, then looking for the second component in the first object, etc., until the entire name is traversed. A relative name does not begin with a slash and the traversal begins at the location specified by the create or access function.
H5Gclose(hid_t group_id)
H5Gclose releases resources used by a group which was
opened by H5Gcreate or H5Gopen.
After closing a group, the group_id cannot be used again.
Failure to release a group with this call will result in resource leaks.
hid_t group_id |
IN: Group identifier to release. |
SUBROUTINE h5gclose_f( gr_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: gr_id ! Group identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5gclose_f
H5Gcreate(hid_t loc_id,
const char *name,
size_t size_hint
)
H5Gcreate creates a new group with the specified
name at the specified location, loc_id.
The location is identified by a file or group identifier.
The name, name, must not already be taken by some
other object and all parent groups must already exist.
size_hint is a hint for the number of bytes to
reserve to store the names which will be eventually added to
the new group. Passing a value of zero for size_hint
is usually adequate since the library is able to dynamically
resize the name heap, but a correct hint may result in better
performance.
If a non-positive value is supplied for size_hint,
then a default size is chosen.
The length of a group name, or of the name of any object within a group, is not limited.
The return value is a group identifier for the open group.
This group identifier should be closed by calling
H5Gclose when it is no longer needed.
hid_t loc_id |
IN: File or group identifier. |
const char *name |
IN: Absolute or relative name of the new group. |
size_t size_hint |
IN: Optional parameter indicating the number of bytes to reserve for the names that will appear in the group. A conservative estimate could result in multiple system-level I/O requests to read the group name heap; a liberal estimate could result in a single large I/O request even when the group has just a few names. HDF5 stores each name with a null terminator. |
SUBROUTINE h5gcreate_f(loc_id, name, gr_id, hdferr, size_hint)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group to be created
INTEGER(HID_T), INTENT(OUT) :: gr_id ! Group identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
INTEGER(SIZE_T), OPTIONAL, INTENT(IN) :: size_hint
! Number of bytes to store the names
! of objects in the group.
! Default value is
! OBJECT_NAMELEN_DEFAULT_F
END SUBROUTINE h5gcreate_f
H5Gget_comment(hid_t loc_id,
const char *name,
size_t bufsize,
char *comment
)
H5Gget_comment retrieves the comment for the the
object specified by loc_id and name.
The comment is returned in the buffer comment.
At most bufsize characters, including a null
terminator, are returned in comment.
The returned value is not null terminated
if the comment is longer than the supplied buffer.
If an object does not have a comment, the empty string is returned.
hid_t loc_id |
IN: Identifier of the file, group, dataset, or named datatype. |
const char *name |
IN: Name of the object in loc_id whose
comment is to be retrieved.
name can be '.' (dot) if loc_id
fully specifies the object for which the associated comment
is to be retrieved.
name is ignored if loc_id
is a dataset or named datatype.
|
size_t bufsize |
IN: Anticipated required size of the
comment buffer. |
char *comment |
OUT: The comment. |
bufsize.
Otherwise returns a negative value.
SUBROUTINE h5gget_comment_f(loc_id, name, size, buffer, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File, group, dataset, or
! named datatype identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the object link
CHARACTER(LEN=size), INTENT(OUT) :: buffer ! Buffer to hold the comment
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5gget_comment_f
H5Gget_linkval(hid_t loc_id,
const char *name,
size_t size,
char *value
)
H5Gget_linkval returns size
characters of the name of the object that the symbolic link name points to.
The parameter loc_id is a file or group identifier.
The parameter name must be a symbolic link pointing to
the desired object and must be defined relative to loc_id.
If size is smaller than the size of the returned object name, then
the name stored in the buffer value will not be null terminated.
This function fails if name is not a symbolic link.
The presence of a symbolic link can be tested by passing zero for
size and NULL for value.
This function should be used only after H5Gget_objinfo has been called
to verify that name is a symbolic link.
hid_t loc_id |
IN: Identifier of the file or group. |
const char *name |
IN: Symbolic link to the object whose name is to be returned. |
size_t size |
IN: Maximum number of characters of value
to be returned. |
char *value |
OUT: A buffer to hold the name of the object being sought. |
value,
if successful.
Otherwise returns a negative value.
SUBROUTINE h5gget_linkval_f(loc_id, name, size, buffer, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the symbolic link
CHARACTER(LEN=size), INTENT(OUT) :: buffer ! Buffer to hold a
! name of the object
! symbolic link points to
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5gget_linkval_f
H5Gget_num_objs(hid_t loc_id,
hsize_t* num_obj)
H5Gget_num_objs returns number of objects in a group.
Group is specified by its identifier loc_id.
If a file identifier is passed in, then the number of objects in the
root group is returned.
hid_t loc_id |
IN: Identifier of the group or the file |
hsize_t *num_obj |
OUT: Number of objects in the group. |
| Release | C |
| 1.6.0 | Function introduced in this release. |
H5Gget_objinfo(hid_t loc_id,
const char *name,
hbool_t follow_link,
H5G_stat_t *statbuf
)
H5Gget_objinfo returns information about the
specified object through the statbuf argument.
A file or group identifier, loc_id,
and an object name, name, relative to loc_id,
are commonly used to specify the object.
However, if the object identifier is already known to the application,
an alternative approach is to use that identifier,
obj_id, in place of loc_id,
and a dot (.) in place of name.
Thus, the alternative versions of the first portion of an
H5Gget_objinfo call would be as follows:
H5Gget_objinfo (loc_id name ...)
H5Gget_objinfo (obj_id . ...)
If the object is a symbolic link and follow_link is
zero (0),
then the information returned describes the link itself;
otherwise the link is followed and the information returned
describes the object to which the link points.
If follow_link is non-zero but the final symbolic link
is dangling (does not point to anything), then an error is returned.
The statbuf fields are undefined for an error.
The existence of an object can be tested by calling this function
with a null statbuf.
H5Gget_objinfo fills in the following data structure
(defined in H5Gpublic.h):
typedef struct H5G_stat_t {
unsigned long fileno[2];
unsigned long objno[2];
unsigned nlink;
H5G_obj_t type;
time_t mtime;
size_t linklen;
H5O_stat_t ohdr;
} H5G_stat_t
where H5O_stat_t (defined in H5Opublic.h) is:
typedef struct H5O_stat_t {
hsize_t size;
hsize_t free;
unsigned nmesgs;
unsigned nchunks;
} H5O_stat_t
The fileno and objno fields contain
four values which uniquely identify an object among those
HDF5 files which are open: if all four values are the same
between two objects, then the two objects are the same
(provided both files are still open).
fileno will change.
H5Fopen calls referencing the same file
actually open the same file, each will get a different
fileno.
The nlink field is the number of hard links to
the object or zero when information is being returned about a
symbolic link (symbolic links do not have hard links but
all other objects always have at least one).
The type field contains the type of the object,
one of
H5G_GROUP,
H5G_DATASET,
H5G_LINK, or
H5G_TYPE.
The mtime field contains the modification time.
If information is being returned about a symbolic link then
linklen will be the length of the link value
(the name of the pointed-to object with the null terminator);
otherwise linklen will be zero.
The fields in the H5O_stat_t struct contain information
about the object header for the object queried:
size
| The total size of all the object header information in the file (for all chunks). |
free
| The size of unused space in the object header. |
nmesgs
| The number of object header messages. |
nchunks
| The number of chunks the object header is broken up into. |
Other fields may be added to this structure in the future.
mtime value of 0 (zero).
hid_t loc_id |
IN: File or group identifier.
Alternative: An object identifier, obj_id. |
const char *name |
IN: Name of the object for which status is being
sought.
Alternative: If the preceding parameter is the object’s direct identifier, i.e., the obj_id,
this parameter should be a dot (.). |
hbool_t follow_link |
IN: Link flag. |
H5G_stat_t *statbuf |
OUT: Buffer in which to return information about the object. |
statbuf (if non-null) initialized.
Otherwise returns a negative value.
| Release | C |
| 1.6.1 |
Two new fields were added to the
H5G_stat_t struct in this release. |
H5Gget_objname_by_idx(hid_t loc_id,
hsize_t idx,
char *name,
size_t size )
H5Gget_objname_by_idx returns a name of the object
specified by the index idx in the group loc_id.
The group is specified by a group identifier loc_id.
If preferred, a file identifier may be passed in loc_id;
that file's root group will be assumed.
idx is the transient index used to iterate through
the objects in the group.
The value of idx is any nonnegative number less than
the total number of objects in the group, which is returned by the
function H5Gget_num_objs.
Note that this is a transient index; an object may have a
different index each time a group is opened.
The object name is returned in the user-specified buffer name.
If the size of the provided buffer name is
less or equal the actual object name length,
the object name is truncated to max_size - 1 characters.
Note that if the size of the object's name is unkown, a
preliminary call to H5Gget_objname_by_idx with name
set to NULL will return the length of the object's name.
A second call to H5Gget_objname_by_idx
can then be used to retrieve the actual name.
hid_t loc_id |
IN: Group or file identifier. |
hsize_t idx |
IN: Transient index identifying object. |
char *name |
IN/OUT: Pointer to user-provided buffer the object name. |
size_t size |
IN: Name length. |
0 if no name is associated with the group identifier.
Otherwise returns a negative value.
| Release | C |
| 1.6.0 | Function introduced in this release. |
H5Gget_objtype_by_idx(hid_t loc_id,
hsize_t idx )
H5Gget_objtype_by_idx returns the type of the object
specified by the index idx in the group loc_id.
The group is specified by a group identifier loc_id.
If preferred, a file identifier may be passed in loc_id;
that file's root group will be assumed.
idx is the transient index used to iterate through
the objects in the group.
This parameter is described in more detail in the discussion of
H5Gget_objname_by_idx.
The object type is returned as the function return value:
H5G_LINK
|
0
| Object is a symbolic link. | |
H5G_GROUP
|
1
| Object is a group. | |
H5G_DATASET
|
2
| Object is a dataset. | |
H5G_TYPE
|
3
| Object is a named datatype. |
hid_t loc_id |
IN: Group or file identifier. |
hsize_t idx |
IN: Transient index identifying object. |
| Release | C |
| 1.6.0 | The function return type changed from int to the enumerated type H5G_obj_t. |
| 1.6.0 | Function introduced in this release. |
H5Giterate(hid_t loc_id,
const char *name,
int *idx,
H5G_iterate_t operator,
void *operator_data
)
H5Giterate iterates over the members of
name in the file or group specified with
loc_id.
For each object in the group, the operator_data
and some additional information, specified below, are
passed to the operator function.
The iteration begins with the idx object in the
group and the next element to be processed by the operator is
returned in idx. If idx
is NULL, then the iterator starts at the first group member;
since no stopping point is returned in this case, the iterator
cannot be restarted if one of the calls to its operator returns
non-zero.
The prototype for H5G_iterate_t is:
typedef herr_t (*H5G_iterate_t)
(hid_t group_id, const char *
member_name, void *operator_data); |
The operation receives the group identifier for the group being
iterated over, group_id, the name of the current
object within the group, member_name, and the
pointer to the operator data passed in to H5Giterate,
operator_data.
The return values from an operator are:
H5Giterate assumes that the membership of the group
identified by name remains unchanged through the
iteration. If the membership changes during the iteration,
the function's behavior is undefined.
hid_t loc_id |
IN: File or group identifier. |
const char *name |
IN: Group over which the iteration is performed. |
int *idx |
IN/OUT: Location at which to begin the iteration. |
H5G_iterate_t operator |
IN: Operation to be performed on an object at each step of the iteration. |
void *operator_data |
IN/OUT: Data associated with the operation. |
H5Giterate.
Instead, that functionality is provided by two FORTRAN functions:
h5gn_members_f
|
Purpose: Returns the number of group members. | |
h5gget_obj_info_idx_f
| Purpose: Returns name and type of the group member identified by its index. |
SUBROUTINE h5gn_members_f(loc_id, name, nmembers, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group
INTEGER, INTENT(OUT) :: nmembers ! Number of members in the group
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5gn_members_f
SUBROUTINE h5gget_obj_info_idx_f(loc_id, name, idx, &
obj_name, obj_type, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group
INTEGER, INTENT(IN) :: idx ! Index of member object
CHARACTER(LEN=*), INTENT(OUT) :: obj_name ! Name of the object
INTEGER, INTENT(OUT) :: obj_type ! Object type :
! H5G_LINK_F
! H5G_GROUP_F
! H5G_DATASET_F
! H5G_TYPE_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5gget_obj_info_idx_f
H5Glink(hid_t loc_id,
H5G_link_t link_type,
const char *current_name,
const char *new_name
)
new_name
to current_name.
H5Glink creates a new name for an object that has some current
name, possibly one of many names it currently has.
If link_type is H5G_LINK_HARD, then
current_name must specify the name of an
existing object and both
names are interpreted relative to loc_id, which is
either a file identifier or a group identifier.
If link_type is H5G_LINK_SOFT, then
current_name can be anything and is interpreted at
lookup time relative to the group which contains the final
component of new_name. For instance, if
current_name is ./foo,
new_name is ./x/y/bar, and a request
is made for ./x/y/bar, then the actual object looked
up is ./x/y/./foo.
hid_t loc_id |
IN: File or group identifier. |
H5G_link_t link_type |
IN: Link type.
Possible values are H5G_LINK_HARD and
H5G_LINK_SOFT. |
const char * current_name |
IN: Name of the existing object if link is a hard link. Can be anything for the soft link. |
const char * new_name |
IN: New name for the object. |
SUBROUTINE h5glink_f(loc_id, link_type, current_name, new_name, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group location identifier
INTEGER, INTENT(IN) :: link_type ! Link type, possible values are:
! H5G_LINK_HARD_F
! H5G_LINK_SOFT_F
CHARACTER(LEN=*), INTENT(IN) :: current_name
! Current object name relative
! to loc_id
CHARACTER(LEN=*), INTENT(IN) :: new_name ! New object name
INTEGER, INTENT(OUT) :: hdferr ! Error code
END SUBROUTINE h5glink_f
H5Glink2(
hid_t curr_loc_id, const char *current_name,
H5G_link_t link_type,
hid_t new_loc_id, const char *new_name )
new_name
to current_name.
H5Glink2 creates a new name for an object that has some current
name, possibly one of many names it currently has.
If link_type is H5G_LINK_HARD, then current_name
must specify the name of an existing object.
In this case, current_name and new_name are interpreted
relative to curr_loc_id and new_loc_id, respectively,
which are either file or group identifiers.
If link_type is H5G_LINK_SOFT, then
current_name can be anything and is interpreted at
lookup time relative to the group which contains the final
component of new_name. For instance, if
current_name is ./foo,
new_name is ./x/y/bar, and a request
is made for ./x/y/bar, then the actual object looked
up is ./x/y/./foo.
hid_t curr_loc_id |
IN: The file or group identifier for the original object. |
const char * current_name |
IN: Name of the existing object if link is a hard link. Can be anything for the soft link. |
H5G_link_t link_type |
IN: Link type.
Possible values are H5G_LINK_HARD and
H5G_LINK_SOFT. |
hid_t new_loc_id |
IN: The file or group identifier for the new link. | const char * new_name |
IN: New name for the object. |
SUBROUTINE h5glink2_f(cur_loc_id, cur_name, link_type, new_loc_id, new_name, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: cur_loc_id ! File or group location identifier
CHARACTER(LEN=*), INTENT(IN) :: cur_name ! Name of the existing object
! is relative to cur_loc_id
! Can be anything for the soft link
INTEGER, INTENT(IN) :: link_type ! Link type, possible values are:
! H5G_LINK_HARD_F
! H5G_LINK_SOFT_F
INTEGER(HID_T), INTENT(IN) :: new_loc_id ! New location identifier
CHARACTER(LEN=*), INTENT(IN) :: new_name ! New object name
INTEGER, INTENT(OUT) :: hdferr ! Error code
END SUBROUTINE h5glink2_f
H5Gmove(hid_t loc_id,
const char *src_name,
const char *dst_name
)
H5Gmove renames an object within an HDF5 file.
The original name, src_name, is unlinked from the
group graph and the new name, dst_name, is inserted
as an atomic operation. Both names are interpreted relative
to loc_id, which is either a file or a group
identifier.
H5Gmove.
See The Group Interface
in the HDF5 User's Guide.
hid_t loc_id |
IN: File or group identifier. |
const char *src_name |
IN: Object's original name. |
const char *dst_name |
IN: Object's new name. |
SUBROUTINE h5gmove_f(loc_id, name, new_name, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Original name of an object
CHARACTER(LEN=*), INTENT(IN) :: new_name ! New name of an object
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5gmove_f
H5Gmove2( hid_t src_loc_id,
const char *src_name, hid_t dst_loc_id,
const char *dst_name )
H5Gmove2 renames an object within an HDF5 file. The original
name, src_name, is unlinked from the group graph and the new
name, dst_name, is inserted as an atomic operation.
src_name and dst_name are interpreted relative to
src_name and dst_name, respectively,
which are either file or group identifiers.
H5Gmove. See The
Group Interface in the HDF5 User's Guide.
hid_t src_loc_id |
IN: Original file or group identifier. |
const char *src_name |
IN: Object's original name. |
hid_t dst_loc_id |
IN: Destination file or group identifier. |
const char *dst_name |
IN: Object's new name. |
SUBROUTINE h5gmove2_f(src_loc_id, src_name, dst_loc_id, dst_name, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: src_loc_id ! File or group identifier
CHARACTER(LEN=*), INTENT(IN) :: src_name ! Original name of an object
! relative to src_loc_id
INTEGER(HID_T), INTENT(IN) :: dst_loc_id ! File or group identifier
CHARACTER(LEN=*), INTENT(IN) :: dst_name ! New name of an object
! relative to dst_loc_id
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5gmove2_f
H5Gopen(hid_t loc_id,
const char *name
)
H5Gopen opens an existing group with the specified
name at the specified location, loc_id.
The location is identified by a file or group identifier
H5Gopen returns a group identifier for the group
that was opened. This group identifier should be released by
calling H5Gclose when it is no longer needed.
hid_t loc_id |
IN: File or group identifier within which group is to be open. |
const char * name |
IN: Name of group to open. |
SUBROUTINE h5gopen_f(loc_id, name, gr_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group to open
INTEGER(HID_T), INTENT(OUT) :: gr_id ! Group identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5gopen_f
H5Gset_comment(hid_t loc_id,
const char *name,
const char *comment
)
H5Gset_comment sets the comment for the
object specified by loc_id and name
to comment.
Any previously existing comment is overwritten.
If comment is the empty string or a
null pointer, the 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, named datatypes, and dataspaces, but not symbolic links.
hid_t loc_id |
IN: Identifier of the file, group, dataset, or named datatype. |
const char *name |
IN: Name of the object whose comment is to be
set or reset.
name can be '.' (dot) if loc_id
fully specifies the object for which the comment is to be set.
name is ignored if loc_id
is a dataset or named datatype.
|
const char *comment |
IN: The new comment. |
SUBROUTINE h5gset_comment_f(loc_id, name, comment, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File, group, dataset, or
! named datatype identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of object
CHARACTER(LEN=*), INTENT(IN) :: comment ! Comment for the object
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5gset_comment_f
H5Gunlink(hid_t loc_id,
const char *name
)
H5Gunlink removes the object specified by
name from the group graph and decrements the
link count for the object to which name points.
This action eliminates any association between name
and the object to which name pointed.
Object headers keep track of how many hard links refer to an object; when the link count reaches zero, the object can be removed from the file. Objects which are open are not removed until all identifiers to the object are closed.
If the link count reaches zero, all file space associated with the object will be released, i.e., identified in memory as freespace. If the any object identifier is open for the object, the space will not be released until after the object identifier is closed.
Note that space identified as freespace is available for re-use only as long as the file remains open; once a file has been closed, the HDF5 library loses track of freespace. See “Freespace Management” in the HDF5 User's Guide for further details.
H5Gunlink.
See The Group Interface
in the HDF5 User's Guide.
hid_t loc_id |
IN: Identifier of the file or group containing the object. |
const char * name |
IN: Name of the object to unlink. |
SUBROUTINE h5gunlink_f(loc_id, name, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the object to unlink
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5gunlink_f
|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes Collective Calls in Parallel |
| (PDF of complete manual formatted as print volume) | |
