summaryrefslogtreecommitdiffstats
path: root/doc/html/RM_H5A.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/html/RM_H5A.html')
-rw-r--r--doc/html/RM_H5A.html501
1 files changed, 501 insertions, 0 deletions
diff --git a/doc/html/RM_H5A.html b/doc/html/RM_H5A.html
new file mode 100644
index 0000000..0c236da
--- /dev/null
+++ b/doc/html/RM_H5A.html
@@ -0,0 +1,501 @@
+<html>
+<head><title>
+HDF5/H5A 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;
+H5A&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;
+<a href="RM_H5G.html">H5G</a>&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>H5A: Attribute Interface</h1>
+</center>
+
+<h2>Attribute API Functions</h2>
+
+These functions create and manipulate attributes
+and information about attributes.
+
+<table border=0>
+<tr><td valign=top>
+<ul>
+ <li><a href="#Annot-Create">H5Acreate</a>
+ <li><a href="#Annot-Write">H5Awrite</a>
+ <li><a href="#Annot-Read">H5Aread</a>
+ <li><a href="#Annot-Close">H5Aclose</a>
+</ul>
+</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
+<ul>
+ <li><a href="#Annot-GetName">H5Aget_name</a>
+ <li><a href="#Annot-OpenName">H5Aopen_name</a>
+ <li><a href="#Annot-OpenIdx">H5Aopen_idx</a>
+ <li><a href="#Annot-GetSpace">H5Aget_space</a>
+</ul>
+</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
+<ul>
+ <li><a href="#Annot-GetType">H5Aget_type</a>
+ <li><a href="#Annot-NumAttrs">H5Anum_attrs</a>
+ <li><a href="#Annot-Iterate">H5Aiterate</a>
+ <li><a href="#Annot-Delete">H5Adelete</a>
+</ul>
+</td></tr>
+</table>
+
+<p>
+The Attribute interface, H5A, is primarily designed to easily allow
+small datasets to be attached to primary datasets as metadata information.
+Additional goals for the H5A interface include keeping storage requirement
+for each attribute to a minimum and easily sharing attributes among
+datasets.
+<p>
+Because attributes are intended to be small objects, large datasets
+intended as additional information for a primary dataset should be
+stored as supplemental datasets in a group with the primary dataset.
+Attributes can then be attached to the group containing everything
+to indicate a particular type of dataset with supplemental datasets
+is located in the group. How small is "small" is not defined by the
+library and is up to the user's interpretation.
+<p>
+See <a href="Attributes.html"><cite>Attributes</cite></a> in the
+<a href="H5.user.html"><cite>HDF5 User's Guide</cite></a> for further information.
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Annot-Create">H5Acreate</a>
+<dt><strong>Signature:</strong>
+ <dd><em>hid_t</em> <code>H5Acreate</code>(<em>hid_t</em> <code>loc_id</code>,
+ <em>const char *</em><code>name</code>,
+ <em>hid_t</em> <code>type_id</code>,
+ <em>hid_t</em> <code>space_id</code>,
+ <em>hid_t</em> <code>create_plist</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Creates a dataset as an attribute of another group, dataset,
+ or named datatype.
+<dt><strong>Description:</strong>
+ <dd><code>H5Acreate</code> creates an attribute which is attached
+ to the object specified with <code>loc_id</code>.
+ <code>loc_id</code> is an identifier of a group, dataset,
+ or named datatype. The name specified with <code>name</code>
+ for each attribute for an object must be unique for that object.
+ The datatype and dataspace identifiers of the attribute,
+ <code>type_id</code> and <code>space_id</code>, respectively,
+ are created with the H5T and H5S interfaces, respectively.
+ Currently only simple dataspaces are allowed for attribute
+ dataspaces. The <code>create_plist_id</code> property list
+ is currently unused, but will be used int the future for optional
+ properties of attributes. The attribute identifier returned from
+ this function must be released with <code>H5Aclose</code> or
+ resource leaks will develop. Attempting to create an attribute
+ with the same name as an already existing attribute will fail,
+ leaving the pre-existing attribute in place.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>loc_id</code>
+ <dd>IN: Object (dataset or group) to be attached to.
+ <dt><em>const char *</em><code>name</code>
+ <dd>IN: Name of attribute to create.
+ <dt><em>hid_t</em> <code>type_id</code>
+ <dd>IN: Identifier of datatype for attribute.
+ <dt><em>hid_t</em> <code>space_id</code>
+ <dd>IN: Identifier of dataspace for attribute.
+ <dt><em>hid_t</em> <code>create_plist</code>
+ <dd>IN: Identifier of creation property list (currently not used).
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns an attribute identifier if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Annot-OpenName">H5Aopen_name</a>
+<dt><strong>Signature:</strong>
+ <dd><em>hid_t</em> <code>H5Aopen_name</code>(<em>hid_t</em> <code>loc_id</code>,
+ <em>const char *</em><code>name</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd> Opens an attribute specified by name.
+<dt><strong>Description:</strong>
+ <dd><code>H5Aopen_name</code> opens an attribute specified by
+ its name, <code>name</code>, which is attached to the
+ object specified with <code>loc_id</code>.
+ The location object may be either a group, dataset, or
+ named datatype, which may have any sort of attribute.
+ The attribute identifier returned from this function must
+ be released with <code>H5Aclose</code> or resource leaks
+ will develop.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>loc_id</code>
+ <dd>IN: Identifier of a group, dataset, or named datatype
+ atttribute to be attached to.
+ <dt><em>const char *</em><code>name</code>
+ <dd>IN: Attribute name.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns attribute identifier if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Annot-OpenIdx">H5Aopen_idx</a>
+<dt><strong>Signature:</strong>
+ <dd><em>hid_t</em> <code>H5Aopen_idx</code>(<em>hid_t</em> <code>loc_id</code>,
+ <em>unsigned int</em> <code>idx</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Opens the attribute specified by its index.
+<dt><strong>Description:</strong>
+ <dd><code>H5Aopen_idx</code> opens an attribute which is attached
+ to the object specified with <code>loc_id</code>.
+ The location object may be either a group, dataset, or
+ named datatype, all of which may have any sort of attribute.
+ The attribute specified by the index, <code>idx</code>,
+ indicates the attribute to access.
+ The value of <code>idx</code> is a 0-based, non-negative integer.
+ The attribute identifier returned from this function must be
+ released with <code>H5Aclose</code> or resource leaks will develop.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>loc_id</code>
+ <dd>IN: Identifier of the group, dataset, or named datatype
+ attribute to be attached to.
+ <dt><em>unsigned int</em> <code>idx</code>
+ <dd>IN: Index of the attribute to open.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns attribute identifier if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Annot-Write">H5Awrite</a>
+<dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Awrite</code>(<em>hid_t</em> <code>attr_id</code>,
+ <em>hid_t</em> <code>mem_type_id</code>,
+ <em>void *</em><code>buf</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Writes data to an attribute.
+<dt><strong>Description:</strong>
+ <dd><code>H5Awrite</code> writes an attribute, specified with
+ <code>attr_id</code>. The attribute's memory datatype
+ is specified with <code>mem_type_id</code>. The entire
+ attribute is written from <code>buf</code> to the file.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>attr_id</code>
+ <dd>IN: Identifier of an attribute to write.
+ <dt><em>hid_t</em> <code>mem_type_id</code>
+ <dd>IN: Identifier of the attribute datatype (in memory).
+ <dt><em>void *</em><code>buf</code>
+ <dd>IN: Data to be written.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns SUCCEED (0) if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Annot-Read">H5Aread</a>
+<dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Aread</code>(<em>hid_t</em> <code>attr_id</code>,
+ <em>hid_t</em> <code>mem_type_id</code>,
+ <em>void *</em><code>buf</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Reads an attribute.
+<dt><strong>Description:</strong>
+ <dd><code>H5Aread</code> reads an attribute, specified with
+ <code>attr_id</code>. The attribute's memory datatype
+ is specified with <code>mem_type_id</code>. The entire
+ attribute is read into <code>buf</code> from the file.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>attr_id</code>
+ <dd>IN: Identifier of an attribute to read.
+ <dt><em>hid_t</em> <code>mem_type_id</code>
+ <dd>IN: Identifier of the attribute datatype (in memory).
+ <dt><em>void *</em><code>buf</code>
+ <dd>IN: Buffer for data to be read.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns SUCCEED (0) if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Annot-GetSpace">H5Aget_space</a>
+<dt><strong>Signature:</strong>
+ <dd><em>hid_t</em> <code>H5Aget_space</code>(<em>hid_t</em> <code>attr_id</code>)
+<dt><strong>Purpose:</strong>
+ <dd>Gets a copy of the dataspace for an attribute.
+<dt><strong>Description:</strong>
+ <dd><code>H5Aget_space</code> retrieves a copy of the dataspace
+ for an attribute. The dataspace identifier returned from
+ this function must be released with <code>H5Sclose</code>
+ or resource leaks will develop.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>attr_id</code>
+ <dd>IN: Identifier of an attribute.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns attribute dataspace identifier if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Annot-GetType">H5Aget_type</a>
+<dt><strong>Signature:</strong>
+ <dd><em>hid_t</em> <code>H5Aget_type</code>(<em>hid_t</em> <code>attr_id</code>)
+<dt><strong>Purpose:</strong>
+ <dd>Gets an attribute datatype.
+<dt><strong>Description:</strong>
+ <dd><code>H5Aget_type</code> retrieves a copy of the datatype
+ for an attribute.
+ <p>
+ The datatype is reopened if it is a named type before returning
+ it to the application. The datatypes returned by this function
+ are always read-only. If an error occurs when atomizing the
+ return datatype, then the datatype is closed.
+ <p>
+ The datatype identifier returned from this function must be
+ released with <code>H5Tclose</code> or resource leaks will develop.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>attr_id</code>
+ <dd>IN: Identifier of an attribute.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns a datatype identifier if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Annot-GetName">H5Aget_name</a>
+<dt><strong>Signature:</strong>
+ <dd><em>size_t</em> <code>H5Aget_name</code>(<em>hid_t</em> <code>attr_id</code>,
+ <em>char *</em><code>buf</code>,
+ <em>size_t</em> <code>buf_size</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Gets an attribute name.
+<dt><strong>Description:</strong>
+ <dd><code>H5Aget_name</code> retrieves the name of an attribute
+ specified by the identifier, <code>attr_id</code>.
+ Up to <code>buf_size</code> characters are stored in
+ <code>buf</code> followed by a <code>\0</code> string
+ terminator. If the name of the attribute is longer than
+ <code>buf_size</code> -1, the string terminator is stored in the
+ last position of the buffer to properly terminate the string.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>attr_id</code>
+ <dd>IN: Identifier of the attribute.
+ <dt><em>char *</em><code>buf</code>
+ <dd>IN: Buffer to store name in.
+ <dt><em>size_t</em> <code>buf_size</code>
+ <dd>IN: The size of the buffer to store the name in.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns the length of the attribute's name, which may be
+ longer than <code>buf_size</code>, if successful.
+ Otherwise returns FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Annot-NumAttrs">H5Anum_attrs</a>
+<dt><strong>Signature:</strong>
+ <dd><em>int</em> <code>H5Anum_attrs</code>(<em>hid_t</em> <code>loc_id</code>)
+<dt><strong>Purpose:</strong>
+ <dd>Determines the number of attributes attached to an object.
+<dt><strong>Description:</strong>
+ <dd><code>H5Anum_attrs</code> returns the number of attributes
+ attached to the object specified by its identifier,
+ <code>loc_id</code>.
+ The object can be a group, dataset, or named datatype.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>loc_id</code>
+ <dd>IN: Identifier of a group, dataset, or named datatype.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns the number of attributes if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Annot-Iterate">H5Aiterate</a>
+<dt><strong>Signature:</strong>
+ <dd><em>int</em> <code>H5Aiterate</code>(<em>hid_t</em> <code>loc_id</code>,
+ <em>unsigned *</em> <code>idx</code>,
+ <em>H5A_operator_t</em> <code>op</code>,
+ <em>void *</em><code>op_data</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Calls a user's function for each attribute on an object.
+<dt><strong>Description:</strong>
+ <dd><code>H5Aiterate</code> iterates over the attributes of
+ the object specified by its identifier, <code>loc_id</code>.
+ The object can be a group, dataset, or named datatype.
+ For each attribute of the object, the <code>op_data</code>
+ and some additional information specified below are passed
+ to the operator function <code>op</code>.
+ The iteration begins with the attribute specified by its
+ index, <code>idx</code>; the index for the next attribute
+ to be processed by the operator, <code>op</code>, is
+ returned in <code>idx</code>.
+ If <code>idx</code> is the null pointer, then all attributes
+ are processed.
+ <p>
+ The prototype for <code>H5A_operator_t</code> is: <br>
+ <code>typedef herr_t (*H5A_operator_t)(hid_t <em>loc_id</em>,
+ const char *<em>attr_name</em>,
+ void *<em>operator_data</em>);
+ </code>
+ <p>
+ The operation receives the identifier for the group, dataset
+ or named datatype being iterated over, <code>loc_id</code>, the
+ name of the current attribute about the object, <code>attr_name</code>,
+ and the pointer to the operator data passed in to <code>H5Aiterate</code>,
+ <code>op_data</code>. The return values from an operator are:
+ <ul>
+ <li>Zero causes the iterator to continue, returning zero when all
+ attributes 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 attribute.
+ <li>Negative causes the iterator to immediately return that value,
+ indicating failure. The iterator can be restarted at the next
+ attribute.
+ </ul>
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>loc_id</code>
+ <dd>IN: Identifier of a group, dataset or named datatype.
+ <dt><em>unsigned *</em> <code>idx</code>
+ <dd>IN/OUT: Starting (IN) and ending (OUT) attribute index.
+ <dt><em>H5A_operator_t</em> <code>op</code>
+ <dd>IN: User's function to pass each attribute to
+ <dt><em>void *</em><code>op_data</code>
+ <dd>IN/OUT: User's data to pass through to iterator operator function
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>If successful, returns the return value of the last operator
+ if it was non-zero, or zero if all attributes were processed.
+ Otherwise returns FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Annot-Delete">H5Adelete</a>
+<dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Adelete</code>(<em>hid_t</em> <code>loc_id</code>,
+ <em>const char *</em><code>name</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Deletes an attribute from a location.
+<dt><strong>Description:</strong>
+ <dd><code>H5Adelete</code> removes the attribute specified by its
+ name, <code>name</code>, from a dataset, group, or named datatype.
+ This function should not be used when attribute identifiers are
+ open on <code>loc_id</code> as it may cause the internal indexes
+ of the attributes to change and future writes to the open
+ attributes to produce incorrect results.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>loc_id</code>
+ <dd>IN: Identifier of the dataset, group, or named datatype
+ to have the attribute deleted from.
+ <dt><em>const char *</em><code>name</code>
+ <dd>IN: Name of the attribute to delete.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns SUCCEED (0) if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Annot-Close">H5Aclose</a>
+<dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Aclose</code>(<em>hid_t</em> <code>attr_id</code>)
+<dt><strong>Purpose:</strong>
+ <dd>Closes the specified attribute.
+<dt><strong>Description:</strong>
+ <dd><code>H5Aclose</code> terminates access to the attribute
+ specified by its identifier, <code>attr_id</code>.
+ Further use of the attribute identifier will result in
+ undefined behavior.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>attr_id</code>
+ <dd>IN: Attribute to release access to.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns SUCCEED (0) if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<center>
+<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;
+<a href="RM_H5.html">H5</a>&nbsp;&nbsp;
+H5A&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;
+<a href="RM_H5G.html">H5G</a>&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>