diff options
Diffstat (limited to 'doc/html/Attributes.html')
| -rw-r--r-- | doc/html/Attributes.html | 287 |
1 files changed, 0 insertions, 287 deletions
diff --git a/doc/html/Attributes.html b/doc/html/Attributes.html deleted file mode 100644 index 63f8e5e..0000000 --- a/doc/html/Attributes.html +++ /dev/null @@ -1,287 +0,0 @@ - -<html> - <head> - <title>Attribute Interface (H5A)</title> - -<!-- #BeginLibraryItem "/ed_libs/styles_UG.lbi" --> -<!-- - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * Copyright by the Board of Trustees of the University of Illinois. * - * All rights reserved. * - * * - * This file is part of HDF5. The full HDF5 copyright notice, including * - * terms governing use, modification, and redistribution, is contained in * - * the files COPYING and Copyright.html. COPYING can be found at the root * - * of the source code distribution tree; Copyright.html can be found at the * - * root level of an installed copy of the electronic HDF5 document set and * - * is linked from the top-level documents page. It can also be found at * - * http://hdf.ncsa.uiuc.edu/HDF5/doc/Copyright.html. If you do not have * - * access to either file, you may request a copy from hdfhelp@ncsa.uiuc.edu. * - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - --> - -<link href="ed_styles/UGelect.css" rel="stylesheet" type="text/css"> -<!-- #EndLibraryItem --></head> - - <body bgcolor="#FFFFFF"> - - -<!-- #BeginLibraryItem "/ed_libs/NavBar_UG.lbi" --><hr> -<center> -<table border=0 width=98%> -<tr><td valign=top align=left> - <a href="index.html">HDF5 documents and links</a> <br> - <a href="H5.intro.html">Introduction to HDF5</a> <br> - <a href="RM_H5Front.html">HDF5 Reference Manual</a> <br> - <a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User's Guide for Release 1.6</a> <br> - <!-- - <a href="Glossary.html">Glossary</a><br> - --> -</td> -<td valign=top align=right> - And in this document, the - <a href="H5.user.html"><strong>HDF5 User's Guide from Release 1.4.5:</strong></a> - <br> - <a href="Files.html">Files</a> - <a href="Datasets.html">Datasets</a> - <a href="Datatypes.html">Datatypes</a> - <a href="Dataspaces.html">Dataspaces</a> - <a href="Groups.html">Groups</a> - <br> - <a href="References.html">References</a> - <a href="Attributes.html">Attributes</a> - <a href="Properties.html">Property Lists</a> - <a href="Errors.html">Error Handling</a> - <br> - <a href="Filters.html">Filters</a> - <a href="Caching.html">Caching</a> - <a href="Chunking.html">Chunking</a> - <a href="MountingFiles.html">Mounting Files</a> - <br> - <a href="Performance.html">Performance</a> - <a href="Debugging.html">Debugging</a> - <a href="Environment.html">Environment</a> - <a href="ddl.html">DDL</a> -</td></tr> -</table> -</center> -<hr> -<!-- #EndLibraryItem --><h1>The Attribute Interface (H5A)</h1> - - <h2>1. Introduction</h2> - - <p>The attribute API (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 - requirements 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>Attributes are not separate objects in the file, they are always - contained in the object header of the object they are attached to. The - I/O functions defined below are required to read or write attribute - information, not the H5D I/O routines. - - <h2>2. Creating, Opening, Closing and Deleting Attributes</h2> - - <p>Attributes are created with the <code>H5Acreate()</code> function, - and existing attributes can be accessed with either the - <code>H5Aopen_name()</code> or <code>H5Aopen_idx()</code> functions. All - three functions return an object ID which should be eventually released - by calling <code>H5Aclose()</code>. - - <dl> - <dt><code>hid_t H5Acreate (hid_t <em>loc_id</em>, const char - *<em>name</em>, hid_t <em>type_id</em>, hid_t <em>space_id</em>, - hid_t <em>create_plist_id</em>)</code> - <dd>This function creates an attribute which is attached to the object - specified with <em>loc_id</em>. The name specified with <em>name</em> - for each attribute for an object must be unique for that object. The <em>type_id</em> - and <em>space_id</em> are created with the H5T and H5S interfaces - respectively. Currently only simple dataspaces are allowed for attribute - dataspaces. The <em>create_plist_id</em> property list is currently - unused, but will be used in the future for optional properties of - attributes. The attribute ID returned from this function must be released - with H5Aclose 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. - This function returns an attribute ID for success or negative for failure. - - <br><br> - <dt><code>hid_t H5Aopen_name (hid_t <em>loc_id</em>, const char - *<em>name</em>)</code> - <dd> This function opens an attribute which is attached to the object - specified with <em>loc_id</em>. The name specified with <em>name</em> - indicates the attribute to access. The attribute ID returned from this - function must be released with H5Aclose or resource leaks will develop. - This function returns an attribute ID for success or negative for failure. - - <br><br> - <dt><code>hid_t H5Aopen_idx (hid_t <em>loc_id</em>, unsigned - <em>idx</em>)</code> - <dd>This function opens an attribute which is attached to the object - specified with <em>loc_id</em>. The attribute specified with <em>idx</em> - indicates the <em>idx</em>th attribute to access, starting with '0'. The - attribute ID returned from this function must be released with H5Aclose or - resource leaks will develop. - This function returns an attribute ID for success or negative for failure. - - <br><br> - <dt><code>herr_t H5Aclose (hid_t <em>attr_id</em>)</code> - <dd>This function releases an attribute from use. Further use of the - attribute ID will result in undefined behavior. - This function returns non-negative on success, negative on failure. - - <br><br> - <dt><code>herr_t H5Adelete (hid_t <em>loc_id</em>, - const char *<em>name</em>)</code> - <dd>This function removes the named attribute from a dataset or group. - This function should not be used when attribute IDs are open on <em>loc_id</em> - as it may cause the internal indexes of the attributes to change and future - writes to the open attributes to produce incorrect results. - Returns non-negative on success, negative on failure. - </dl> - - <h2>3. Attribute I/O Functions</h2> - - <p>Attributes may only be written as an entire object, no partial I/O - is currently supported. - - <dl> - <dt><code>herr_t H5Awrite (hid_t <em>attr_id</em>, - hid_t <em>mem_type_id</em>, void *<em>buf</em>)</code> - <dd>This function writes an attribute, specified with <em>attr_id</em>, - with <em>mem_type_id</em> specifying the datatype in memory. The entire - attribute is written from <em>buf</em> to the file. - This function returns non-negative on success, negative on failure. - - <br><br> - <dt><code>herr_t H5Aread (hid_t <em>attr_id</em>, - hid_t <em>mem_type_id</em>, void *<em>buf</em>)</code> - <dd>This function read an attribute, specified with <em>attr_id</em>, with - <em>mem_type_id</em> specifying the datatype in memory. The entire - attribute is read into <em>buf</em> from the file. - This function returns non-negative on success, negative on failure. - - </dl> - - <h2>4. Attribute Inquiry Functions</h2> - - <dl> - <dt><code>herr_t H5Aiterate (hid_t <em>loc_id</em>, - unsigned *<em>attr_number</em>, - H5A_operator <em>operator</em>, - void *<em>operator_data</em>)</code> - <dd> This function iterates over the attributes of the dataset or group - specified with <em>loc_id</em>. For each attribute of the object, the - <em>operator_data</em> and some additional information (specified below) - are passed to the <em>operator</em> function. The iteration begins with - the <em>*attr_number</em> object in the group and the next attribute to be - processed by the operator is returned in <em>*attr_number</em>. - <P>The iterator returns a negative value if something is wrong, the return - value of the last operator if it was non-zero, or zero if all attributes - were processed. - <P>The prototype for H5A_operator_t 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 ID for the group or dataset being iterated over - (<em>loc_id</em>), the name of the current attribute about the object (<em>attr_name</em>) - and the pointer to the operator data passed in to H5Aiterate - (<em>operator_data</em>). 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> - <br><br> - <dt><code>hid_t H5Aget_space (hid_t <em>attr_id</em>)</code> - <dd>This function retrieves a copy of the dataspace for an attribute. - The dataspace ID returned from this function must be released with H5Sclose - or resource leaks will develop. - This function returns a dataspace ID for success or negative for failure. - <br><br> - <dt><code>hid_t H5Aget_type (hid_t <em>attr_id</em>)</code> - <dd>This function retrieves a copy of the datatype for an attribute. - The datatype ID returned from this function must be released with H5Tclose - or resource leaks will develop. - This function returns a datatype ID for success or negative for failure. - <br><br> - <dt><code>ssize_t H5Aget_name (hid_t <em>attr_id</em>, - size_t <em>buf_size</em>, char *<em>buf</em>)</code> - <dd>This function retrieves the name of an attribute for an attribute ID. - Up to <em>buf_size</em> characters are stored in <em>buf</em> followed by a - '\0' string terminator. If the name of the attribute is longer than - <em>buf_size</em>-1, the string terminator is stored in the last position - of the buffer to properly terminate the string. - This function returns the length of the attribute's name (which may be - longer than <em>buf_size</em>) on success or negative for failure. - <br><br> - <dt><code>int H5Aget_num_attrs (hid_t <em>loc_id</em>)</code> - <dd>This function returns the number of attributes attached to a dataset or - group, <em>loc_id</em>. - This function returns non-negative for success or negative for failure. - </dl> - - -<!-- #BeginLibraryItem "/ed_libs/NavBar_UG.lbi" --><hr> -<center> -<table border=0 width=98%> -<tr><td valign=top align=left> - <a href="index.html">HDF5 documents and links</a> <br> - <a href="H5.intro.html">Introduction to HDF5</a> <br> - <a href="RM_H5Front.html">HDF5 Reference Manual</a> <br> - <a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User's Guide for Release 1.6</a> <br> - <!-- - <a href="Glossary.html">Glossary</a><br> - --> -</td> -<td valign=top align=right> - And in this document, the - <a href="H5.user.html"><strong>HDF5 User's Guide from Release 1.4.5:</strong></a> - <br> - <a href="Files.html">Files</a> - <a href="Datasets.html">Datasets</a> - <a href="Datatypes.html">Datatypes</a> - <a href="Dataspaces.html">Dataspaces</a> - <a href="Groups.html">Groups</a> - <br> - <a href="References.html">References</a> - <a href="Attributes.html">Attributes</a> - <a href="Properties.html">Property Lists</a> - <a href="Errors.html">Error Handling</a> - <br> - <a href="Filters.html">Filters</a> - <a href="Caching.html">Caching</a> - <a href="Chunking.html">Chunking</a> - <a href="MountingFiles.html">Mounting Files</a> - <br> - <a href="Performance.html">Performance</a> - <a href="Debugging.html">Debugging</a> - <a href="Environment.html">Environment</a> - <a href="ddl.html">DDL</a> -</td></tr> -</table> -</center> -<hr> -<!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address> -<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> -<br> -Describes HDF5 Release 1.4.5, February 2003 -</address><!-- #EndLibraryItem --> - - -Last modified: 6 July 2000 - - -</body> -</html> |