H5G: Group Interface

Group Object API Functions

The C Interfaces:

H5Gcreate H5Gopen H5Gclose

H5Glink H5Gunlink H5Giterate H5Gmove

H5Gget_objinfo H5Gget_linkval H5Gset_comment H5Gget_comment

The FORTRAN90 Interfaces:
In general, each FORTRAN90 subroutine performs exactly the same task as the corresponding C function. The links below go to the C function descriptions, which serve as general descriptions for both. A button, under Non-C API(s) at the end of the C function description, opens an external browser window displaying the FORTRAN90-specific information. You will probably want to adjust the size and location of this external window so that both browser windows are visible and to facilitate moving easily between them.

h5gcreate_f h5gopen_f h5gclose_f

h5gunlink_f h5gget_obj_info_idx_f h5gn_members_f h5gmove_f

h5gget_linkval_f h5gset_comment_f h5gget_comment_f

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.

Name: H5Gcreate

Signature:

hid_t H5Gcreate(hid_t loc_id, const char *name, size_t size_hint )

Purpose:

Creates a new empty group and gives it a name.

Description:

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 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.

Parameters:

hid_t loc_id

The file or group identifier.

const char *name

The absolute or relative name of the new group.

size_t size_hint

An 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.

Returns:

Returns a valid group identifier for the open group if successful; otherwise returns a negative value.

Non-C API(s):

Name: H5Gopen

Signature:

hid_t H5Gopen(hid_t loc_id, const char *name )

Purpose:

Opens an existing group for modification and returns a group identifier for that group.

Description:

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.

Parameters:

hid_t loc_id

File or group identifier within which group is to be open.

const char * name

Name of group to open.

Returns:

Returns a valid group identifier if successful; otherwise returns a negative value.

Non-C API(s):

Name: H5Gclose

Signature:

herr_t H5Gclose(hid_t group_id)

Purpose:

Closes the specified group.

Description:

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.

Parameters:

hid_t group_id

Group identifier to release.

Returns:

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

Non-C API(s):

Name: H5Glink

Signature:

herr_t H5Glink(hid_t loc_id, H5G_link_t link_type, const char *current_name, const char *new_name )

Purpose:

Creates a link of the specified type from new_name to current_name.

Description:

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.

Parameters:

hid_t loc_id

File or group identifier.

H5G_link_t link_type

Link type. Possible values are H5G_LINK_HARD and H5G_LINK_SOFT.

const char * current_name

Name of the existing object if link is a hard link. Can be anything for the soft link.

const char * new_name

New name for the object.

Returns:

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

Non-C API(s):

Name: H5Gunlink

Signature:

herr_t H5Gunlink(hid_t loc_id, const char *name )

Purpose:

Removes the link to an object from a group.

Description:

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.

Warning:

Exercise care in unlinking groups as it is possible to render data in a file inaccessible with H5Gunlink. See The Group Interface in the HDF5 User's Guide.

Parameters:

hid_t loc_id

Identifier of the file containing the object.

const char * name

Name of the object to unlink.

Returns:

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

Non-C API(s):

Name: H5Giterate

Signature:

int H5Giterate(hid_t loc_id, const char *name, int *idx, H5G_iterate_t operator, void *operator_data )

Purpose:

Iterates an operation over the entries of a group.

Description:

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:

• Zero causes the iterator to continue, returning zero when all group members have been processed.
• Positive causes the iterator to immediately return that positive value, indicating short-circuit success. The iterator can be restarted at the next group member.
• Negative causes the iterator to immediately return that value, indicating failure. The iterator can be restarted at the next group member.

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.

Parameters:

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.

Returns:

Returns the return value of the last operator if it was non-zero, or zero if all group members were processed. Otherwise returns a negative value.

Non-C API(s):

There is no direct FORTRAN couterpart for the C function 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.

Name: H5Gmove

Signature:

herr_t H5Gmove(hid_t loc_id, const char *src, const char *dst )

Purpose:

Renames an object within an HDF5 file.

Description:

H5Gmove renames an object within an HDF5 file. The original name, src, is unlinked from the group graph and the new name, dst, is inserted as an atomic operation. Both names are interpreted relative to loc_id, which is either a file or a group identifier.

Warning:

Exercise care in moving groups as it is possible to render data in a file inaccessible with H5Gmove. See The Group Interface in the HDF5 User's Guide.

Parameters:

hid_t loc_id

File or group identifier.

const char *src

Object's original name.

const char *dst

Object's new name.

Returns:

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

Non-C API(s):

Name: H5Gget_objinfo

Signature:

herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link, H5G_stat_t *statbuf )

Purpose:

Returns information about an object.

Description:

H5Gget_objinfo returns information about the specified object through the statbuf argument. loc_id (a file or group identifier) and name together determine the object. If the object is a symbolic link and follow_link is zero (0), then the information returned is that for the link itself; otherwise the link is followed and information is returned about 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:

                  typedef struct H5G_stat_t {
                      unsigned long fileno[2];
                      unsigned long objno[2];
                      unsigned nlink;
                      int type;
                      time_t mtime; 
                      size_t linklen;
                  } H5G_stat_t
        

The fileno and objno fields contain four values which uniquely itentify 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). 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. Other fields may be added to this structure in the future.

Note:

Some systems will be able to record the time accurately but unable to retrieve the correct time; such systems (e.g., Irix64) will report an mtime value of 0 (zero).

Parameters:

hid_t loc_id

IN: File or group identifier.

const char *name

IN: Name of the object for which status is being sought.

hbool_t follow_link

IN: Link flag.

H5G_stat_t *statbuf

OUT: Buffer in which to return information about the object.

Returns:

Returns a non-negative value if successful, with the fields of statbuf (if non-null) initialized. Otherwise returns a negative value.

Name: H5Gget_linkval

Signature:

herr_t H5Gget_linkval(hid_t loc_id, const char *name, size_t size, char *value )

Purpose:

Returns the name of the object that the symbolic link points to.

Description:

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.

Parameters:

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.

Returns:

Returns a non-negative value, with the link value in value, if successful. Otherwise returns a negative value.

Non-C API(s):

Name: H5Gset_comment

Signature:

herr_t H5Gset_comment(hid_t loc_id, const char *name, const char *comment )

Purpose:

Sets comment for specified object.

Description:

H5Gset_comment sets the comment for the the object 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., data sets, groups, named data types, and data spaces, but not symbolic links.

Parameters:

hid_t loc_id

IN: Identifier of the file or group.

const char *name

IN: Name of the object whose comment is to be set or reset.

const char *comment

IN: The new comment.

Returns:

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

Non-C API(s):

Name: H5Gget_comment

Signature:

herr_t H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *comment )

Purpose:

Retrieves comment for specified object.

Description:

H5Gget_comment retrieves the comment for the the object name. The comment is returned in the buffer comment.

At most bufsize characters, including a null terminator, are copied. The result 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.

Parameters:

hid_t loc_id

IN: Identifier of the file or group.

const char *name

IN: Name of the object whose comment is to be set or reset.

size_t bufsize

IN: Anticipated size of the buffer required to hold comment.

char *comment

OUT: The comment.

Returns:

Returns the number of characters in the comment, counting the null terminator, if successful; the value returned may be larger than bufsize. Otherwise returns a negative value.

Non-C API(s):