diff options
Diffstat (limited to 'doc/src/RM_H5A.html')
| -rw-r--r-- | doc/src/RM_H5A.html | 523 |
1 files changed, 0 insertions, 523 deletions
diff --git a/doc/src/RM_H5A.html b/doc/src/RM_H5A.html deleted file mode 100644 index bda4333..0000000 --- a/doc/src/RM_H5A.html +++ /dev/null @@ -1,523 +0,0 @@ -<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="Tools.html">Tools</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">H5Aget_num_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, group, or named datatype) 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. - <p> - Datatype conversion takes place at the time of a read or write - and is automatic. See the - <a href="Datatypes.html#Datatypes-DataConversion">Data Conversion</a> - section of <cite>The Data Type Interface (H5T)</cite> in the - <cite>HDF5 User's Guide</cite> for a discussion of - data conversion, including the range of conversions currently - supported by the HDF5 libraries. -<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. - <p> - Datatype conversion takes place at the time of a read or write - and is automatic. See the - <a href="Datatypes.html#Datatypes-DataConversion">Data Conversion</a> - section of <cite>The Data Type Interface (H5T)</cite> in the - <cite>HDF5 User's Guide</cite> for a discussion of - data conversion, including the range of conversions currently - supported by the HDF5 libraries. -<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">H5Aget_num_attrs</a> -<dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Aget_num_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>H5Aget_num_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="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: 1 September 1998 - -</body> -</html> |