diff options
Diffstat (limited to 'doc/src/RM_H5G.html')
| -rw-r--r-- | doc/src/RM_H5G.html | 744 |
1 files changed, 0 insertions, 744 deletions
diff --git a/doc/src/RM_H5G.html b/doc/src/RM_H5G.html deleted file mode 100644 index a4ca46a..0000000 --- a/doc/src/RM_H5G.html +++ /dev/null @@ -1,744 +0,0 @@ -<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; - haddr_t objno; - unsigned nlink; - H5G_obj_t type; - time_t mtime; - size_t linklen; - } H5G_stat_t - </pre> - The <code>fileno</code> and <code>objno</code> fields contain - values which uniquely itentify an object among those - HDF5 files which are open: if both 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> |