diff options
Diffstat (limited to 'doc/html/RM_H5A.html')
| -rw-r--r-- | doc/html/RM_H5A.html | 501 |
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> +<a href="RM_H5.html">H5</a> +H5A +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<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>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> </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> </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> +<a href="RM_H5.html">H5</a> +H5A +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<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> |