Describes HDF5 Release 1.8.20, November 2017.
and the Board of Trustees of the University of Illinois
The C Interfaces:
| * Use of these functions is deprecated in Release 1.8.0. | ||||
| * Use of these functions is deprecated in Release 1.8.0. | ||||
Groups in HDF5:
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.
Locating objects in the HDF5 file hierarchy:
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.
Group implementations in HDF5:
The original HDF5 group implementation provided
a single indexed structure for link storage.
A new group implementation, in HDF5 Release 1.8.0,
enables more efficient compact storage for very small groups,
improved link indexing for large groups,
and other advanced features.
H5Pset_char_encoding)
and is required for all link types other than hard or soft links,
e.g., external and user-defined links
(see the H5L APIs).
The original group structure and the newer structures are not directly interoperable. By default, a group will be created in the original indexed format. An existing group can be changed to a compact-or-indexed format if the need arises; there is no capability to change back. As stated above, once in the compact-or-indexed format, a group can switch between compact and indexed as needed.
Groups will be initially created in the compact-or-indexed format only when one or more of the following conditions is met:
H5Pset_libver_bounds).
Currently, that would require an H5Pset_libver_bounds
call with the low parameter set to
H5F_LIBVER_LATEST.
When this property is set for an HDF5 file, all objects in the file will be created using the latest available format; no effort will be made to create a file that can be read by older libraries.
H5P_CRT_ORDER_TRACKED, has been set
in the group creation property list
(see
H5Pset_link_creation_order).
An existing group, currently in the original indexed format, will be converted to the compact-or-indexed format upon the occurrence of any of the following events:
The compact-or-indexed format offers performance improvements
that will be most notable at the extremes,
i.e., in groups with zero members
and in groups with tens of thousands of members.
But measurable differences may sometimes appear
at a threshold as low as eight group members.
Since these performance thresholds and criteria differ from
application to application, tunable settings are provided to
govern the switch between the compact and indexed formats
(see
H5Pset_link_phase_change).
Optimal thresholds will depend on the application and the
operating environment.
Future versions of HDF5 will retain the ability to create, read, write, and manipulate all groups stored in either the original indexed format or the compact-or-indexed format.
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
hid_t H5Gcreate(
hid_t loc_id,
const char *name,
size_t size_hint )
| [1] |
hid_t H5Gcreate(
hid_t loc_id,
const char *name,
hid_t lcpl_id,
hid_t gcpl_id,
hid_t gapl_id )
| [2] |
H5Gcreate is a macro that is mapped to either
H5Gcreate1 or
H5Gcreate2,
depending on the HDF5 Library configuration and application
compile-time compatibility macro mapping options.
This macro is provided to facilitate application compatibility. For example:
H5Gcreate macro
will be mapped to H5Gcreate1 and
will use the H5Gcreate1 syntax
(first signature above)
if the application is coded for HDF5 Release 1.6.x.
H5Gcreate macro
will be mapped to H5Gcreate2 and
will use the H5Gcreate2 syntax
(second signature above)
if the application is coded for HDF5 Release 1.8.x.
Macro use and compatibility macro mapping options are fully described in “API Compatibility Macros in HDF5.”
When both the HDF5 Library and the application are built
without specific compatibility macro mapping options, the
default behavior occurs and
H5Gcreate is mapped to the most recent version of
the function, currently
H5Gcreate2.
If the library and/or application is compiled for Release 1.6
emulation, H5Gcreate will be mapped to
H5Gcreate1.
Function mapping flags can be used to override these settings
on a function-by-function basis when the application is compiled.
The H5Gcreate function mapping flags are shown:
h5cc flag
| macro maps to |
|---|---|
-DH5Acreate_vers=1
| H5Acreate1
|
-DH5Acreate_vers=2
| H5Acreate2
|
A group created with this macro should be closed with
H5Gclose when the group is no longer needed so
that resource leaks will not develop.
H5Gcreate interface
and the only interface available prior to HDF5 Release 1.8.0.
This signature and the corresponding function are now deprecated
but will remain directly callable as
H5Gcreate1.
Signature [2] above was introduced with HDF5 Release 1.8.0
and is the recommended and default interface.
It is directly callable as
H5Gcreate2.
Deprecated functions may not be available in all installations of the HDF5 libary. See “API Compatibility Macros in HDF5” for details.
SUBROUTINE h5gcreate_f(loc_id, name, grp_id, hdferr, &
size_hint, lcpl_id, gcpl_id, gapl_id)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group
INTEGER(HID_T), INTENT(OUT) :: grp_id ! Group identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
INTEGER(SIZE_T), OPTIONAL, INTENT(IN) :: size_hint
! Parameter indicating the number of
! bytes to reserve for the names that
! will appear in the group.
! Note, set to OBJECT_NAMELEN_DEFAULT_F
! if using any of the optional
! parameters lcpl_id, gcpl_id,
! and/or gapl_id when not
! using keywords in specifying the
! optional parameters.
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id
! Property list for link creation
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gcpl_id
! Property list for group creation
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gapl_id
! Property list for group access
END SUBROUTINE h5gcreate_f
| Release | C |
| 1.8.0 | The function
H5Gcreate renamed to H5Gcreate1
and deprecated in this release.
The macro H5Gcreate
and the function H5Gcreate2
introduced in this release. |
H5Gcreate1(
hid_t loc_id,
const char *name,
size_t size_hint
)
H5Gcreate and
deprecated in favor of the functions
H5Gcreate2 and
H5Gcreate_anon,
or the new macro
H5Gcreate.
H5Gcreate1 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.
name can be a relative path based at loc_id
or an absolute path from the root of the file.
Use of this function requires that any intermediate groups
specified in the path already exist.
The length of a group name, or of the name of any object within a group, is not limited.
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 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.
See H5Gcreate_anon
for a discussion of the differences between H5Gcreate1
and H5Gcreate_anon.
hid_t loc_id |
IN: File or group identifier. |
const char *name |
IN: Absolute or relative name of the o 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. |
H5Gcreate.
| Release | C |
| 1.8.0 |
Function H5Gcreate renamed to
H5Gcreate1 and deprecated
in this release. |
H5Gcreate2(
hid_t loc_id,
const char *name,
hid_t lcpl_id,
hid_t gcpl_id,
hid_t gapl_id
)
H5Gcreate2 creates a new group in a file. After
a group has been created, links to datasets and to other groups
can be added.
The loc_id and name parameters specify
where the group is located. loc_id may be a file
identifier or a group identifier in the file.
name is the link to the group; name
may be either an absolute path in the file (the links from the
root group to the new group) or a relative path from
loc_id (the link(s) from the group specified by
loc_id to the new group). See the
“Accessing objects
by location and name” topic for more information.
lcpl_id, gcpl_id, and
gapl_id are property list identifiers. These property
lists govern how the link to the group is created, how the group
is created, and how the group can be accessed in the future,
respectively. H5P_DEFAULT can be passed in if the
default properties are appropriate for these property lists.
Currently, there are no APIs for the group access
property list; use H5P_DEFAULT. See
“H5P: Property List Interface”
for the functions that can be used with each property list.
To conserve and release resources, the group should be closed when access is no longer required.
hid_t loc_id
|
IN: File or group identifier |
const char *name
|
IN: Absolute or relative name of the link to the new group |
hid_t lcpl_id
|
IN: Link creation property list identifier |
hid_t gcpl_id
|
IN: Group creation property list identifier |
hid_t gapl_id
|
IN: Group access property list identifier
(No group access properties have been implemented at this time; use H5P_DEFAULT.)
|
H5Gcreate.
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Gcreate_anon(
hid_t loc_id,
hid_t gcpl_id,
hid_t gapl_id
)
H5Gcreate_anon creates a new empty group
in the file specified by loc_id.
With default settings, H5Gcreate_anon provides
similar functionality to that provided by H5Gcreate,
with the differences described below.
The new group’s creation and access properties are specified in
gcpl_id and gapl_id, respectively.
H5Gcreate_anon returns a new group identifier.
This identifier must be linked into the HDF5 file structure
with H5Olink
or it will be deleted from the file when the file is closed.
The differences between this function and H5Gcreate1
are as follows:
H5Gcreate1 does not provide for the use of
custom property lists;
H5Gcreate1 always uses default properties.
H5Gcreate_anon neither provides the new
group’s name nor links it into the HDF5 file structure;
those actions must be performed separately through a call to
H5Olink,
which offers greater control over linking.
H5Gcreate_anon does not directly provide
a hint mechanism for the group’s heap size.
Comparable information can be included in the group creation
property list gcpl_id through a
H5Pset_local_heap_size_hint call.
A group created with this function should be closed with
H5Gclose when the group is no longer needed so
that resource leaks will not develop.
hid_t loc_id
|
IN: File or group identifier specifying the file in which the new group is to be created |
hid_t gcpl_id
|
IN: Group creation property list identifier
( H5P_DEFAULT for the default property list)
|
hid_t gapl_id
|
IN: Group access property list identifier
(No group access properties have been implemented at this time; use H5P_DEFAULT.)
|
SUBROUTINE h5gcreate_anon_f(loc_id, grp_id, hdferr, gcpl_id, gapl_id)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
INTEGER(HID_T), INTENT(OUT) :: grp_id ! Group identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gcpl_id
! Property list for group creation
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gapl_id
! Property list for group access
END SUBROUTINE h5gcreate_anon_f
H5GcreateH5Olink
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Gget_comment(hid_t loc_id,
const char *name,
size_t bufsize,
char *comment
)
H5Oget_comment.
H5Gget_comment retrieves the comment for the the
object specified by loc_id and name.
The comment is returned in the buffer comment.
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
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 the size of the comment is unknown, a preliminary
H5Gget_comment call will return the size of the
comment, including space for the null terminator.
If an object does not have a comment, the empty string
is returned in comment.
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 must be '.' (dot) if loc_id
fully specifies the object for which the associated comment
is to be retrieved.
|
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
| Release | C |
| 1.8.0 | Function deprecated in this release. |
H5Gget_create_plist(hid_t group_id)
H5Gget_create_plist returns an identifier
for the group creation property list associated with the
group specified by group_id.
The creation property list identifier should be released with
H5Pclose.
hid_t group_id |
IN: Identifier of the group. |
SUBROUTINE h5gget_create_plist_f(grp_id, gcpl_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: grp_id ! Group identifier
INTEGER(HID_T), INTENT(OUT) :: gcpl_id ! Property list for group creation
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5gget_create_plist_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Gget_info(
hid_t group_id,
H5G_info_t *group_info
)
H5Gget_info retrieves information about the group
specified by group_id.
The information is returned in the group_info struct.
group_info is an H5G_info_t struct
and is defined (in H5Gpublic.h) as follows:
H5G_storage_type_t storage_type
|
Type of storage for links in group
H5G_STORAGE_TYPE_COMPACT:
Compact storage
H5G_STORAGE_TYPE_DENSE:
Indexed storage
H5G_STORAGE_TYPE_SYMBOL_TABLE:
Symbol tables, the original HDF5 structure | |
hsize_t nlinks
| Number of links in group | |
int64_t max_corder
| Current maximum creation order value for group | |
hbool_t mounted
| Whether the group has a file mounted on it |
hid_t group_id
|
IN: Group identifier |
H5G_info_t *group_info
|
OUT: Struct in which group information is returned |
SUBROUTINE h5gget_info_f(group_id, storage_type, nlinks, max_corder, hdferr, &
mounted)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: group_id
! Group identifier
INTEGER, INTENT(OUT) :: storage_type
! Type of storage for links in group:
! H5G_STORAGE_TYPE_COMPACT_F: Compact storage
! H5G_STORAGE_TYPE_DENSE_F: Indexed storage
! H5G_STORAGE_TYPE_SYMBOL_TABLE_F: Symbol tables
INTEGER, INTENT(OUT) :: nlinks
! Number of links in group
INTEGER, INTENT(OUT) :: max_corder
! Current maximum creation order value for group
INTEGER, INTENT(OUT) :: hdferr
! Error code:
! 0 on success and -1 on failure
LOGICAL, INTENT(OUT), OPTIONAL :: mounted
! Whether group has a file mounted on it
END SUBROUTINE h5gget_info_f
| Release | C |
| 1.8.2 | Added 'mounted' field. |
| 1.8.0 | Function introduced in this release. |
H5Gget_info_by_idx(
hid_t loc_id,
const char *group_name,
H5_index_t index_type,
H5_iter_order_t order,
hsize_t n,
H5G_info_t *group_info,
hid_t lapl_id
)
H5Gget_info_by_idx retrieves the same imformation
about a group as retrieved by the function
H5Gget_info,
immediately above, but the means of identifying the group
differs;
the group is identified by position in an index rather
than by name.
loc_id and group_name specify
the group containing the group for which information is sought.
The groups in group_name are indexed by
index_type; the group for which information
is retrieved is identified in that index by index order,
order, and index position, n.
If loc_id specifies the group
containing the group for which information is queried,
group_name can be a dot (.).
Valid values for index_type are as follows:
H5_INDEX_NAME
| An alpha-numeric index by group name | ||
H5_INDEX_CRT_ORDER
| An index by creation order |
The order in which the index is to be examined, as specified by
order, can be one of the following:
H5_ITER_INC
| The count is from beginning of the index, i.e., top-down. | ||
H5_ITER_DEC
| The count is from the end of the index, i.e., bottom-up. | ||
H5_ITER_NATIVE
| HDF5 counts through the index in the fastest-available order. No information is provided as to the order, but HDF5 ensures that no element in the index will be overlooked. |
hid_t loc_id
|
IN: File or group identifier |
const char *group_name
|
IN: Name of group containing group for which information is to be retrieved |
H5_index_t index_type
|
IN: Index type |
H5_iter_order_t order
|
IN: Order of the count in the index |
hsize_t n
|
IN: Position in the index of the group for which information is retrieved |
H5G_info_t *group_info
|
OUT: Struct in which group information is returned |
hid_t lapl_id
|
IN: Link access property list |
SUBROUTINE h5gget_info_by_idx_f(loc_id, group_name, index_type, order, n, &
storage_type, nlinks, max_corder, hdferr, lapl_id, mounted)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id
! File or group identifier
CHARACTER(LEN=*), INTENT(IN) :: group_name
! Name of group containing group for which
! information is to be retrieved
INTEGER, INTENT(IN) :: index_type
! Index type
INTEGER, INTENT(IN) :: order
! Order of the count in the index
INTEGER(HSIZE_T), INTENT(IN) :: n
! Position in the index of the group for which
! information is retrieved
INTEGER, INTENT(OUT) :: storage_type
! Type of storage for links in group:
! H5G_STORAGE_TYPE_COMPACT_F: Compact storage
! H5G_STORAGE_TYPE_DENSE_F: Indexed storage
! H5G_STORAGE_TYPE_SYMBOL_TABLE_F: Symbol tables
INTEGER, INTENT(OUT) :: nlinks
! Number of links in group
INTEGER, INTENT(OUT) :: max_corder
! Current maximum creation order value for group
INTEGER, INTENT(OUT) :: hdferr
! Error code:
! 0 on success and -1 on failure
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id
! Link access property list
LOGICAL, INTENT(OUT), OPTIONAL :: mounted
! Whether group has a file mounted on it
END SUBROUTINE h5gget_info_by_idx_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Gget_info_by_name(
hid_t loc_id,
const char *group_name,
H5G_info_t *group_info,
hid_t lapl_id
)
H5Gget_info_by_name retrieves information about the group
group_name located in the file or group specified
by loc_id.
The information is returned in the group_info struct.
If loc_id specifies the group for which information is
queried, group_name can be a dot (.).
group_info is an H5G_info_t struct
and is defined (in H5Gpublic.h) as follows:
H5G_storage_type_t storage_type
|
Type of storage for links in group
H5G_STORAGE_TYPE_COMPACT:
Compact storage
H5G_STORAGE_TYPE_DENSE:
Dense storage
H5G_STORAGE_TYPE_SYMBOL_TABLE:
Symbol tables, the original HDF5 structure | |
hsize_t nlinks
| Number of links in group | |
int64_t max_corder
| Current maximum creation order value for group | |
hbool_t mounted
| Whether the group has a file mounted on it |
hid_t loc_id
|
IN: File or group identifier |
const char *group_name
|
IN: Name of group for which information is to be retrieved |
H5G_info_t *group_info
|
OUT: Struct in which group information is returned |
hid_t lapl_id
|
IN: Link access property list |
SUBROUTINE h5gget_info_by_name_f(loc_id, group_name, &
storage_type, nlinks, max_corder, hdferr, lapl_id, mounted)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id
! File or group identifier
CHARACTER(LEN=*), INTENT(IN) :: group_name
! Name of group containing group for which
! information is to be retrieved
INTEGER, INTENT(OUT) :: storage_type
! Type of storage for links in group:
! H5G_STORAGE_TYPE_COMPACT_F: Compact storage
! H5G_STORAGE_TYPE_DENSE_F: Indexed storage
! H5G_STORAGE_TYPE_SYMBOL_TABLE_F: Symbol tables
INTEGER, INTENT(OUT) :: nlinks
! Number of links in group
INTEGER, INTENT(OUT) :: max_corder
! Current maximum creation order value for group
INTEGER, INTENT(OUT) :: hdferr
! Error code:
! 0 on success and -1 on failure
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id
! Link access property list
LOGICAL, INTENT(OUT), OPTIONAL :: mounted
! Whether group has a file mounted on it
END SUBROUTINE h5gget_info_by_name_f
| Release | C |
| 1.8.2 | Added 'mounted' field. |
| 1.8.0 | Function introduced in this release. |
H5Gget_linkval(
hid_t loc_id,
const char *name,
size_t size,
char *value
)
H5Lget_val.
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
H5Lget_info
(or the deprecated function 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
| Release | C |
| 1.8.0 | Function deprecated in this release. |
H5Gget_num_objs(hid_t loc_id,
hsize_t* num_obj)
H5Gget_info.
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. |
| 1.8.0 | Function deprecated in this release. |
H5Gget_objinfo(hid_t loc_id,
const char *name,
hbool_t follow_link,
H5G_stat_t *statbuf
)
H5Oget_info
and
H5Lget_info.
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. |
| 1.8.0 | Function deprecated in this release. |
H5Gget_objname_by_idx(hid_t loc_id,
hsize_t idx,
char *name,
size_t size )
H5Lget_name_by_idx.
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. |
| 1.8.0 | Function deprecated in this release. |
H5Gget_objtype_by_idx(
hid_t loc_id,
hsize_t idx
)
H5Oget_info.
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_GROUP
|
0
| Object is a group. | |
H5G_DATASET
|
1
| Object is a dataset. | |
H5G_TYPE
|
2
| Object is a named datatype. | |
H5G_LINK
|
3
| Object is a symbolic link. | |
H5G_UDLINK
|
4
| Object is a user-defined link. |
hid_t loc_id |
IN: Group or file identifier. |
hsize_t idx |
IN: Transient index identifying object. |
| Release | C |
| 1.6.0 | Function introduced in this release. |
| 1.6.0 | The function return type changed from int to the enumerated type H5G_obj_t. |
| 1.8.0 | Function deprecated in this release. |
H5Giterate(hid_t loc_id,
const char *name,
int *idx,
H5G_iterate_t operator,
void *operator_data
)
H5Literate.
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.
H5Giterate does not recursively follow links into
subgroups of the specified group.
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.
H5Giterate is not recursive.
In particular, if a member of name is found to be
a group, call it subgroup_a, H5Giterate
does not examine the members of subgroup_a.
When recursive iteration is required, the application must handle
the recursion, explicitly calling H5Giterate
on discovered subgroups.
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
| Release | C |
| 1.8.0 | Function deprecated in this release. |
H5Glink(hid_t loc_id,
H5G_link_t link_type,
const char *current_name,
const char *new_name
)
new_name
to current_name.
H5Lcreate_hard
and
H5Lcreate_soft.
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
! 0 on success and -1 on failure
END SUBROUTINE h5glink_f
| Release | C |
| 1.8.0 | Function deprecated in this release. |
H5Glink2(
hid_t curr_loc_id,
const char *current_name,
H5G_link_t link_type,
hid_t new_loc_id,
const char *new_name
)
H5Lcreate_hard
and
H5Lcreate_soft.
current_name
to new_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
! 0 on success and -1 on failure
END SUBROUTINE h5glink2_f
| Release | C |
| 1.8.0 | Function deprecated in this release. |
H5Gmove(hid_t loc_id,
const char *src_name,
const char *dst_name
)
H5Lmove.
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
| Release | C |
| 1.8.0 | Function deprecated in this release. |
H5Gmove2( hid_t src_loc_id,
const char *src_name, hid_t dst_loc_id,
const char *dst_name )
H5Lmove.
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
| Release | C |
| 1.8.0 | Function deprecated in this release. |
H5Gopen(
hid_t loc_id,
const char *name
)
H5Gopen(
hid_t loc_id,
const char * name,
hid_t gapl_id
)
H5Gopen is a macro that is mapped to either
H5Gopen1 or
H5Gopen2,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. For more information on macro use and mappings, see the “API Compatibility Macros in HDF5” document.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Gopen is mapped to the most recent version of
the function, currently
H5Gopen2.
If the library and/or application is compiled for Release 1.6
emulation, H5Gopen will be mapped to
H5Gopen1.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
| Compatibility setting | H5Gopen mapping |
|---|---|
Global settings |
|
| No compatibility flag | H5Gopen2 |
| Enable deprecated symbols | H5Gopen2 |
| Disable deprecated symbols | H5Gopen2 |
Emulate Release 1.6 interface |
H5Gopen1 |
Function-level macros |
|
H5Gopen_vers = 2 |
H5Gopen2 |
H5Gopen_vers = 1 |
H5Gopen1 |
A group created with this macro should be closed with
H5Gclose when the group is no longer needed so
that resource leaks will not develop.
SUBROUTINE h5gopen_f(loc_id, name, grp_id, hdferr, gapl_id)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group
INTEGER(HID_T), INTENT(OUT) :: grp_id ! File identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gapl_id
! Group access property list identifier
END SUBROUTINE h5gopen_f
| Release | Change |
| 1.8.0 |
The function H5Gopen renamed to
H5Gopen1 and deprecated in this release.
The macro H5Gopen
and the function H5Gopen2
introduced in this release. |
H5Gopen1(hid_t loc_id,
const char *name
)
H5GOpen2
or the macro
H5GOpen.
H5Gopen1 opens an existing group with the specified
name at the specified location, loc_id.
The location is identified by a file or group identifier
H5Gopen1 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. |
H5Gopen.
| Release | C |
| 1.8.0 |
The function H5Gopen renamed to
H5Gopen1 and deprecated
in this release. |
H5Gopen2(
hid_t loc_id,
const char * name,
hid_t gapl_id
)
H5Gopen2 opens an existing group,
name, at the location specified by loc_id.
With default settings, H5Gopen2 provides
similar functionality to that provided by H5Gopen1.
The only difference is that H5Gopen2
can provide a group access property list, gapl_id.
H5Gopen2 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 specifying the location of the group to be opened |
const char *name
|
IN: Name of the group to open |
hid_t gapl_id
|
IN: Group access property list identifier
(No group access properties have been implemented at this time; use H5P_DEFAULT.)
|
H5Gopen.
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Gset_comment(hid_t loc_id,
const char *name,
const char *comment
)
H5Oset_comment.
H5Gset_comment sets the comment for the
object specified by loc_id and name
to comment.
Any previously existing comment is overwritten.
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, 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, and named datatypes, 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 must be '.' (dot) if loc_id
fully specifies the object for which the comment is to be set.
|
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
| Release | C |
| 1.8.0 | Function deprecated in this release. |
H5Gunlink(hid_t loc_id,
const char *name
)
H5Ldelete.
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 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
| Release | C |
| 1.8.0 | Function deprecated in this release. |
|
The HDF Group Help Desk:
Describes HDF5 Release 1.8.20, November 2017. |
Copyright by
The HDF Group
and the Board of Trustees of the University of Illinois |