diff options
Diffstat (limited to 'doc/html/RM_H5G.html')
| -rw-r--r-- | doc/html/RM_H5G.html | 639 |
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> +<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> |