mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-02-11 16:01:00 +08:00
745 lines
30 KiB
HTML
745 lines
30 KiB
HTML
<html>
|
|
<head><title>
|
|
HDF5/H5G Draft API Specification
|
|
</title></head>
|
|
|
|
<body>
|
|
|
|
<hr>
|
|
<center>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
<a href="RM_H5E.html">H5E</a>
|
|
<a href="RM_H5F.html">H5F</a>
|
|
H5G
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<a href="RM_H5S.html">H5S</a>
|
|
<a href="RM_H5T.html">H5T</a>
|
|
<a href="RM_H5Z.html">H5Z</a>
|
|
<a href="Tools.html">Tools</a>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a>
|
|
-->
|
|
</center>
|
|
<hr>
|
|
|
|
<center>
|
|
<h1>H5G: Group Interface</h1>
|
|
</center>
|
|
|
|
<h2>Group Object API Functions</h2>
|
|
|
|
The Group interface functions create and manipulate physical groups
|
|
of objects on disk.
|
|
|
|
<table border=0>
|
|
<tr><td valign=top>
|
|
<ul>
|
|
<li><a href="#Group-Create">H5Gcreate</a>
|
|
<li><a href="#Group-Open">H5Gopen</a>
|
|
<li><a href="#Group-Set">H5Gset</a>
|
|
<li><a href="#Group-Close">H5Gclose</a>
|
|
<li><a href="#Group-Push">H5Gpush</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Group-Pop">H5Gpop</a>
|
|
<li><a href="#Group-Link">H5Glink</a>
|
|
<li><a href="#Group-Unlink">H5Gunlink</a> (NYI)
|
|
<li><a href="#Group-Iterate">H5Giterate</a>
|
|
<li><a href="#Group-Move">H5Gmove</a> (NYI)
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Group-GetObjinfo">H5Gget_objinfo</a>
|
|
<li><a href="#Group-GetLinkval">H5Gget_linkval</a>
|
|
<li><a href="#Group-SetComment">H5Gset_comment</a>
|
|
<li><a href="#Group-GetComment">H5Gget_comment</a>
|
|
</ul>
|
|
</td></tr><tr><td colspan=5 align=right>
|
|
<font size=-2>(NYI = Not yet implemented)</font>
|
|
</td></tr>
|
|
</table>
|
|
|
|
<p>
|
|
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 boot block.
|
|
|
|
<p>
|
|
Every file identifier returned by <code>H5Fcreate</code> or
|
|
<code>H5Fopen</code> maintains an independent current working group
|
|
stack, the top item of which is the current working group. The
|
|
stack can be manipulated with <code>H5Gset</code>, <code>H5Gpush</code>,
|
|
and <code>H5Gpop</code>. The root object is the current working group
|
|
if the stack is empty.
|
|
|
|
<p>
|
|
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 with the current working group.
|
|
|
|
<p>
|
|
The library does not maintain the full absolute name of its current
|
|
working group because (1) cycles in the graph can make the name length
|
|
unbounded and (2) a group does not necessarily have a unique name. A
|
|
more Unix-like hierarchical naming scheme can be implemented on top of
|
|
the directed graph scheme by creating a ".." entry in each group that
|
|
points to its single predecessor; a <code>getcwd</code> function would
|
|
then be trivial.
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Create">H5Gcreate</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Gcreate</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>,
|
|
<em>size_t</em> <code>size_hint</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Creates a new empty group and gives it a name.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gcreate</code> creates a new group with the specified
|
|
name at the specified location, <code>loc_id</code>.
|
|
The location is identified by a file or group identifier.
|
|
The name, <code>name</code>, must not already be taken by some
|
|
other object and all parent groups must already exist.
|
|
<p>
|
|
<code>size_hint</code> 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 <code>size_hint</code>
|
|
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.
|
|
<p>
|
|
The return value is a group identifier for the open group.
|
|
This group identifier should be closed by calling
|
|
<code>H5Gclose()</code> when it is no longer needed.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>The file or group identifier.
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>The absolute or relative name of the new group.
|
|
<dt><em>size_t</em> <code>size_hint</code>
|
|
<dd>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.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a valid group identifier for the open group if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Open">H5Gopen</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Gopen</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Opens an existing group for modification and returns a group
|
|
identifier for that group.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gopen</code> opens an existing group with the specified name at
|
|
the specified location, <code>loc_id</code>.
|
|
The location is identified by a file or
|
|
group identifier, and returns a group identifier for the group.
|
|
The obtained group identifier should be released by calling
|
|
<code>H5Gclose()</code> when it is no longer needed.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>File or group identifier within which group is to be open.
|
|
<dt><em>const char *</em> <code>name</code>
|
|
<dd>Name of group to open.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a valid group identifier if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Set">H5Gset</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Gset</code> (<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Sets the current working group within a file.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gset</code> sets the group with the specified name
|
|
to be the current working group for the file which contains it.
|
|
This function sets the current working group by modifying the
|
|
top element of the current working group stack or, if the
|
|
stack is empty, by pushing a new element onto the stack.
|
|
The initial current working group is the root group.
|
|
<p>
|
|
<code>loc_id</code> can be a file identifier or a group identifier.
|
|
<p>
|
|
<code>name</code> is an absolute or relative name and is resolved as follows. Each file identifier
|
|
has a current working group, initially the root group of the
|
|
file. Relative names do not begin with a slash and are relative
|
|
to the specified group or to the current working group.
|
|
Absolute names begin with a slash and are relative to the file's
|
|
root group. For instance, the name <code>/Foo/Bar/Baz</code> is
|
|
resolved by first looking up <code>Foo</code> in the root group;
|
|
the name <code>Foo/Bar/Baz</code> is resolved by first looking
|
|
up the name <code>Foo</code> in the current working group.
|
|
<p>
|
|
Each file identifier maintains its own notion of the current
|
|
working group. If <code>loc_id</code> is a group identifier, the
|
|
file identifier is derived from the group identifier.
|
|
<p>
|
|
If a single file is opened with multiple calls to <code>H5Fopen()</code>,
|
|
which would return multiple file identifiers, then each
|
|
identifier's current working group can be set independently
|
|
of the other file identifiers for that file.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>The file or group identifier.
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>The name of the new current working group.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Push">H5Gpush</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Gpush</code> (<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Sets the current working group by pushing a
|
|
new element onto the current working group stack.
|
|
<dt><strong>Description:</strong>
|
|
<dd>Each file identifier maintains a stack of groups, the top group
|
|
of which is the current working group. The stack initially
|
|
contains only the root group. <code>H5Gpush</code> pushes a new group
|
|
onto the stack, thus setting a new current working group.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>File or group identifier.
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>The name of the new current working group. The name may be
|
|
an absolute or relative name.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Pop">H5Gpop</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Gpop</code> (<em>hid_t</em> <code>loc_id</code>)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Removes the top, or latest, entry from the working group stack,
|
|
setting the current working group to the previous value.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gpop</code> restores the previous current working group by
|
|
popping an element from the current working group stack.
|
|
An empty stack implies that the current working group is the root
|
|
object. Attempting to pop an empty stack results in failure.
|
|
<p>
|
|
Each file identfier maintains its own notion of the current
|
|
working group. That is, if a single file is opened with
|
|
multiple calls to <code>H5Fopen()</code>, which returns multiple file
|
|
handles, then each identfier's current working group can be
|
|
set independently of the other file identfiers for that file.
|
|
<p>
|
|
If <code>loc_id</code> is a group identifier, it is used only to determine the
|
|
file identifier for the stack from which to pop the top entry.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>The file, group, dataset, or datatype identifier.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Close">H5Gclose</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Gclose</code>(<em>hid_t </em><code>group_id</code>)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Closes the specified group.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gclose</code> releases resources used by a group which was
|
|
opened by <code>H5Gcreate()</code> or <code>H5Gopen()</code>.
|
|
After closing a group, the <code>group_id</code> cannot be used again.
|
|
<p>
|
|
Failure to release a group with this call will result in resource leaks.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>group_id</code>
|
|
<dd>Group identifier to release.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Link">H5Glink</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Glink</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>H5G_link_t</em> <code>link_type</code>,
|
|
<em>const char *</em><code>current_name</code>,
|
|
<em>const char *</em><code>new_name</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Creates a link of the specified type from <code>new_name</code>
|
|
to <code>current_name</code>.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Glink</code> creates a new name for an object that has some current
|
|
name, possibly one of many names it currently has.
|
|
<p>
|
|
If <code>link_type</code> is <code>H5G_LINK_HARD</code>, then
|
|
<code>current_name</code> must name an existing object and both
|
|
names are interpreted relative to <code>loc_id</code>, which is
|
|
either a file identifier or a group identifier.
|
|
<p>
|
|
If <code>link_type</code> is <code>H5G_LINK_SOFT</code>, then
|
|
<code>current_name</code> can be anything and is interpreted at
|
|
lookup time relative to the group which contains the final
|
|
component of <code>new_name</code>. For instance, if
|
|
<code>current_name</code> is <code>./foo</code>,
|
|
<code>new_name</code> is <code>./x/y/bar</code>, and a request
|
|
is made for <code>./x/y/bar</code>, then the actual object looked
|
|
up is <code>./x/y/./foo</code>.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>File, group, dataset, or datatype identifier.
|
|
<dt><em>H5G_link_t</em> <code>link_type</code>
|
|
<dd>Link type.
|
|
Possible values are <code>H5G_LINK_HARD</code> and <code>H5G_LINK_SOFT</code>.
|
|
<dt><em>const char *</em> <code>current_name</code>
|
|
<dd>Name of the existing object if link is a hard link.
|
|
Can be anything for the soft link.
|
|
<dt><em>const char *</em> <code>new_name</code>
|
|
<dd>New name for the object.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Unlink">H5Gunlink</a>
|
|
|
|
<strong>(Not implemented in this release.)</strong>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Gunlink</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Removes the specified <code>name</code> from the group graph and
|
|
decrements the link count for the object to which <code>name</code> points
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gunlink</code> removes an association between a name and an object.
|
|
Object headers keep track of how many hard links refer to the object;
|
|
when the hard 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.
|
|
<p>
|
|
If the link count reaches zero, all file-space associated with
|
|
the object will be reclaimed. If the object is open, the
|
|
reclamation of the file space is delayed until all handles to the
|
|
object are closed.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>Identifier of the file containing the object.
|
|
<dt><em>const char *</em> <code>name</code>
|
|
<dd>Name of the object to unlink.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Iterate">H5Giterate</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>int</em> <code>H5Giterate</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char</em> <code>*name</code>,
|
|
<em>int</em> <code>*idx</code>,
|
|
<em>H5G_operator_t</em> <code>operator</code>,
|
|
<em>void</em> <code>*operator_data</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Iterates an operation over the entries of a group.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Giterate</code> iterates over the members of
|
|
<code>name</code> in the file or group specified with
|
|
<code>loc_id</code>.
|
|
For each object in the group, the <code>operator_data</code>
|
|
and some additional information, specified below, are
|
|
passed to the <code>operator</code> function.
|
|
The iteration begins with the <code>idx</code> object in the
|
|
group and the next element to be processed by the operator is
|
|
returned in <code>idx</code>. If <code>idx</code>
|
|
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.
|
|
<p>
|
|
The prototype for <code>H5G_operator_t</code> is:
|
|
<ul><dl>
|
|
<dd><code>typedef</code> <em>herr_t *</em>(<code>H5G_operator_t</code>)(<em>hid_t</em> <code>group_id</code>,
|
|
<em>const char *</em><code>member_name</code>, <em>void *</em><code>operator_data/*in,out*/</code>);
|
|
</dl></ul>
|
|
<dd>The operation receives the group identifier for the group being
|
|
iterated over, <code>group_id</code>, the name of the current
|
|
object within the group, <code>member_name</code>, and the
|
|
pointer to the operator data passed in to <code>H5Giterate</code>,
|
|
<code>operator_data</code>.
|
|
<p>
|
|
The return values from an operator are:
|
|
<ul>
|
|
<li>Zero causes the iterator to continue, returning
|
|
zero when all group members have been processed.
|
|
<li>Positive causes the iterator to immediately return that positive
|
|
value, indicating short-circuit success. The iterator can be
|
|
restarted at the next group member.
|
|
<li>Negative causes the iterator to immediately return that value,
|
|
indicating failure. The iterator can be restarted at the next
|
|
group member.
|
|
</ul>
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>IN: File or group identifier.
|
|
<dt><em>const char</em> <code>*name</code>
|
|
<dd>IN: Group over which the iteration is performed.
|
|
<dt><em>int</em> <code>*idx</code>
|
|
<dd>IN/OUT: Location at which to begin the iteration.
|
|
<dt><em>H5G_iterate_t</em> <code>operator</code>
|
|
<dd>IN: Operation to be performed on an object at each step of
|
|
the iteration.
|
|
<dt><em>void</em> <code>*operator_data</code>
|
|
<dd>IN/OUT: Data associated with the operation.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns the return value of the last operator if it was non-zero,
|
|
or zero if all group members were processed.
|
|
Otherwise, returns FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Move">H5Gmove</a>
|
|
|
|
<strong>(Not implemented in this release.)</strong>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Gmove</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char</em> <code>*src</code>,
|
|
<em>const char</em> <code>*dst</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Renames an object within an HDF5 file.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gmove</code> renames an object within an HDF5 file.
|
|
The original name, <code>src</code>, is unlinked from the
|
|
group graph and the new name, <code>dst</code>, is inserted
|
|
as an atomic operation. Both names are interpreted relative
|
|
to <code>loc_id</code>, which is either a file or a group
|
|
identifier.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>File or group identifier.
|
|
<dt><em>const char</em> <code>*src</code>
|
|
<dd>Object's original name.
|
|
<dt><em>const char</em> <code>*dst</code>
|
|
<dd>Object's new name.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-GetObjinfo">H5Gget_objinfo</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Gget_objinfo</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>,
|
|
<em>hbool_t</em> <code>follow_link</code>,
|
|
<em>H5G_stat_t *</em><code>statbuf</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns information about an object.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gget_objinfo</code> returns information about the
|
|
specified object through the <code>statbuf</code> argument.
|
|
<code>loc_id</code> (a file, group, or dataset identifier) and
|
|
<code>name</code> together determine the object.
|
|
If the object is a symbolic link and <code>follow_link</code> is
|
|
zero (<code>0</code>), 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 <code>follow_link</code> is non-zero but the final symbolic link
|
|
is dangling (does not point to anything), then an error is returned.
|
|
The <code>statbuf</code> fields are undefined for an error.
|
|
The existence of an object can be tested by calling this function
|
|
with a null <code>statbuf</code>.
|
|
<p>
|
|
<code>H5Gget_objinfo()</code> fills in the following data structure:
|
|
<pre>
|
|
typedef struct H5G_stat_t {
|
|
unsigned long fileno[2];
|
|
unsigned long objno[2];
|
|
unsigned nlink;
|
|
H5G_type_t type;
|
|
time_t mtime;
|
|
size_t linklen;
|
|
} H5G_stat_t
|
|
</pre>
|
|
The <code>fileno</code> and <code>objno</code> 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 <code>nlink</code> 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 <code>type</code> field contains the type of the object,
|
|
one of <code>H5G_GROUP</code>, <code>H5G_DATASET</code>,
|
|
or <code>H5G_LINK</code>.
|
|
The <code>mtime</code> field contains the modification time.
|
|
If information is being returned about a symbolic link then
|
|
<code>linklen</code> will be the length of the link value
|
|
(the name of the pointed-to object with the null terminator);
|
|
otherwise <code>linklen</code> will be zero.
|
|
Other fields may be added to this structure in the future.
|
|
<dt><strong>Note:</strong>
|
|
<dd>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 <code>mtime</code> value of 0 (zero).
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>IN: File, group, dataset, or datatype identifier.
|
|
<dt><em>const char</em> <code>*name</code>
|
|
<dd>IN: Name of the object for which status is being sought.
|
|
<dt><em>hbool_t</em> <code>follow_link</code>
|
|
<dd>IN: Link flag.
|
|
<dt><em>H5G_stat_t</em> <code>*statbuf</code>
|
|
<dd>OUT: Buffer in which to return information about the object.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd> Returns SUCCEED (0) with the fields of <code>statbuf</code>
|
|
(if non-null) initialized.
|
|
Otherwise returns FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-GetLinkval">H5Gget_linkval</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Gget_linkval</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>,
|
|
<em>size_t</em> <code>size</code>,
|
|
<em>char *</em><code>value</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns link value.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gget_linkval</code> returns <code>size</code>
|
|
characters of the link value through the <code>value</code>
|
|
argument if <code>loc_id</code> (a file or group identifier)
|
|
and <code>name</code> specify a symbolic link.
|
|
If <code>size</code> is smaller than the link value, then
|
|
<code>value</code> will not be null terminated.
|
|
<p>
|
|
This function fails if the specified object is not a symbolic link.
|
|
The presence of a symbolic link can be tested by passing zero for
|
|
<code>size</code> and NULL for <code>value</code>.
|
|
<p>
|
|
Use <code>H5Gget_objinfo()</code> to get the size of a link value.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>IN: Identifier of the file, group, dataset, or datatype.
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>IN: Name of the object whose link value is to be checked.
|
|
<dt><em>size_t</em> <code>size</code>
|
|
<dd>IN: Maximum number of characters of <code>value</code>
|
|
to be returned.
|
|
<dt><em>char *</em><code>value</code>
|
|
<dd>OUT: Link value.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0), with the link value in <code>value</code>,
|
|
if successful.
|
|
Otherwise returns FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-SetComment">H5Gset_comment</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Gset_comment</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>,
|
|
<em>const char *</em><code>comment</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Sets comment for specified object.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gset_comment</code> sets the comment for the the
|
|
object <code>name</code> to <code>comment</code>.
|
|
Any previously existing comment is overwritten.
|
|
<p>
|
|
If <code>comment</code> is the empty string or a
|
|
null pointer, the comment message is removed from the object.
|
|
<p>
|
|
Comments should be relatively short, null-terminated,
|
|
ASCII strings.
|
|
<p>
|
|
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.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>IN: Identifier of the file, group, dataset, or datatype.
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>IN: Name of the object whose comment is to be set or reset.
|
|
<dt><em>const char *</em><code>comment</code>
|
|
<dd>IN: The new comment.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise returns FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-GetComment">H5Gget_comment</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Gget_comment</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>,
|
|
<em>size_t</em> <code>bufsize</code>,
|
|
<em>char *</em><code>comment</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Retrieves comment for specified object.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gget_comment</code> retrieves the comment for the the
|
|
object <code>name</code>. The comment is returned in the buffer
|
|
<code>comment</code>.
|
|
<p>
|
|
At most <code>bufsize</code> characters, including a null
|
|
terminator, are copied. The result is not null terminated
|
|
if the comment is longer than the supplied buffer.
|
|
<p>
|
|
If an object does not have a comment, the empty string
|
|
is returned.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>IN: Identifier of the file, group, dataset, or datatype.
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>IN: Name of the object whose comment is to be set or reset.
|
|
<dt><em>size_t</em> <code>bufsize</code>
|
|
<dd>IN: Anticipated size of the buffer required to hold
|
|
<code>comment</code>.
|
|
<dt><em>char *</em><code>comment</code>
|
|
<dd>OUT: The comment.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns the number of characters in the comment,
|
|
counting the null terminator, if successful; the value
|
|
returned may be larger than <code>bufsize</code>.
|
|
Otherwise returns FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
<a href="RM_H5E.html">H5E</a>
|
|
<a href="RM_H5F.html">H5F</a>
|
|
H5G
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<a href="RM_H5S.html">H5S</a>
|
|
<a href="RM_H5T.html">H5T</a>
|
|
<a href="RM_H5Z.html">H5Z</a>
|
|
<a href="Tools.html">Tools</a>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a>
|
|
-->
|
|
</center>
|
|
<hr>
|
|
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
|
|
<br>
|
|
Last modified: 2 September 1998
|
|
|
|
</body>
|
|
</html>
|