summaryrefslogtreecommitdiffstats
path: root/doc/html/RM_H5G.html
diff options
context:
space:
mode:
authorFrank Baker <fbaker@hdfgroup.org>1998-07-15 04:51:50 (GMT)
committerFrank Baker <fbaker@hdfgroup.org>1998-07-15 04:51:50 (GMT)
commitc8e75d27b018deb862171a153dd640455dbe26fb (patch)
tree0056588a00653bd4f6fff761482837baa9396a11 /doc/html/RM_H5G.html
parent3e213ecf064638989c816ba3a10b3b6c6307fdad (diff)
downloadhdf5-c8e75d27b018deb862171a153dd640455dbe26fb.zip
hdf5-c8e75d27b018deb862171a153dd640455dbe26fb.tar.gz
hdf5-c8e75d27b018deb862171a153dd640455dbe26fb.tar.bz2
[svn-r503] HDF5 Reference Manual
Updated for Alpha2.
Diffstat (limited to 'doc/html/RM_H5G.html')
-rw-r--r--doc/html/RM_H5G.html639
1 files changed, 639 insertions, 0 deletions
diff --git a/doc/html/RM_H5G.html b/doc/html/RM_H5G.html
new file mode 100644
index 0000000..55b7d5b
--- /dev/null
+++ b/doc/html/RM_H5G.html
@@ -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>&nbsp;
+<a href="RM_H5.html">H5</a>&nbsp;&nbsp;
+<a href="RM_H5A.html">H5A</a>&nbsp;&nbsp;
+<a href="RM_H5D.html">H5D</a>&nbsp;&nbsp;
+<a href="RM_H5E.html">H5E</a>&nbsp;&nbsp;
+<a href="RM_H5F.html">H5F</a>&nbsp;&nbsp;
+H5G&nbsp;&nbsp;
+<a href="RM_H5P.html">H5P</a>&nbsp;&nbsp;
+<a href="RM_H5S.html">H5S</a>&nbsp;&nbsp;
+<a href="RM_H5T.html">H5T</a>&nbsp;&nbsp;
+<a href="RM_H5Z.html">H5Z</a>&nbsp;&nbsp;
+<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>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</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>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</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>
+ &nbsp;&nbsp;&nbsp;&nbsp;
+ <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>
+ &nbsp;&nbsp;&nbsp;&nbsp;
+ <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>&nbsp;
+<a href="RM_H5.html">H5</a>&nbsp;&nbsp;
+<a href="RM_H5A.html">H5A</a>&nbsp;&nbsp;
+<a href="RM_H5D.html">H5D</a>&nbsp;&nbsp;
+<a href="RM_H5E.html">H5E</a>&nbsp;&nbsp;
+<a href="RM_H5F.html">H5F</a>&nbsp;&nbsp;
+H5G&nbsp;&nbsp;
+<a href="RM_H5P.html">H5P</a>&nbsp;&nbsp;
+<a href="RM_H5S.html">H5S</a>&nbsp;&nbsp;
+<a href="RM_H5T.html">H5T</a>&nbsp;&nbsp;
+<a href="RM_H5Z.html">H5Z</a>&nbsp;&nbsp;
+<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>