[svn-r503] HDF5 Reference Manual
Updated for Alpha2.
This commit is contained in:
Frank Baker
639
doc/html/RM_H5G.html
Normal file
639
doc/html/RM_H5G.html
Normal file
@@ -0,0 +1,639 @@
|
||||
<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="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>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Group-Push">H5Gpush</a>
|
||||
<li><a href="#Group-Pop">H5Gpop</a>
|
||||
<li><a href="#Group-Link">H5Glink</a>
|
||||
<li><a href="#Group-Unlink">H5Gunlink</a> (NYI)
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Group-Iterate">H5Giterate</a>
|
||||
<li><a href="#Group-Move">H5Gmove</a> (NYI)
|
||||
<li><a href="#Group-Stat">H5Gstat</a>
|
||||
<li><a href="#Group-GetLinkval">H5Gget_linkval</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 or group 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 or group 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-Stat">H5Gstat</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5Gstat</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>H5Gstat</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>H5Gstat()</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;
|
||||
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>.
|
||||
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>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>loc_id</code>
|
||||
<dd>IN: File, group, or dataset 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 STATBUF (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>H5Gstat()</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 or group .
|
||||
<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>
|
||||
<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="Glossary.html">Glossary</a>
|
||||
</center>
|
||||
<hr>
|
||||
|
||||
<address>
|
||||
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
||||
|
||||
<br>
|
||||
Last modified: 14 July 1998
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user