1998-12-22 06:52:56 +08:00
|
|
|
|
1998-07-08 22:54:54 +08:00
|
|
|
<html>
|
|
|
|
|
<head>
|
1999-12-14 04:39:48 +08:00
|
|
|
<title>Attribute Interface (H5A)</title>
|
2003-03-15 03:12:34 +08:00
|
|
|
|
2003-07-03 05:28:11 +08:00
|
|
|
<!-- #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">
|
2003-03-15 03:12:34 +08:00
|
|
|
<!-- #EndLibraryItem --></head>
|
1998-07-08 22:54:54 +08:00
|
|
|
|
1998-12-22 06:52:56 +08:00
|
|
|
<body bgcolor="#FFFFFF">
|
2003-03-15 03:12:34 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/NavBar_UG.lbi" --><hr>
|
1998-12-22 06:52:56 +08:00
|
|
|
<center>
|
|
|
|
|
<table border=0 width=98%>
|
|
|
|
|
<tr><td valign=top align=left>
|
2003-03-15 03:12:34 +08:00
|
|
|
<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>
|
2003-07-04 03:35:53 +08:00
|
|
|
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User's Guide for Release 1.6</a> <br>
|
2003-03-15 03:12:34 +08:00
|
|
|
<!--
|
|
|
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
|
|
|
-->
|
1998-12-22 06:52:56 +08:00
|
|
|
</td>
|
|
|
|
|
<td valign=top align=right>
|
2003-03-15 03:12:34 +08:00
|
|
|
And in this document, the
|
2003-07-04 03:35:53 +08:00
|
|
|
<a href="H5.user.html"><strong>HDF5 User's Guide from Release 1.4.5:</strong></a>
|
2003-03-15 03:12:34 +08:00
|
|
|
<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>
|
1998-12-22 06:52:56 +08:00
|
|
|
</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
</center>
|
|
|
|
|
<hr>
|
2003-03-15 03:12:34 +08:00
|
|
|
<!-- #EndLibraryItem --><h1>The Attribute Interface (H5A)</h1>
|
1998-07-08 22:54:54 +08:00
|
|
|
|
|
|
|
|
<h2>1. Introduction</h2>
|
|
|
|
|
|
1999-04-16 23:31:54 +08:00
|
|
|
<p>The attribute API (H5A) is primarily designed to easily allow small
|
1998-07-08 22:54:54 +08:00
|
|
|
datasets to be attached to primary datasets as metadata information.
|
|
|
|
|
Additional goals for the H5A interface include keeping storage
|
1999-04-16 23:31:54 +08:00
|
|
|
requirements for each attribute to a minimum and easily sharing
|
1998-07-08 22:54:54 +08:00
|
|
|
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.
|
1999-04-16 23:31:54 +08:00
|
|
|
<p>Attributes are not separate objects in the file, they are always
|
1998-07-08 22:54:54 +08:00
|
|
|
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
|
1999-04-16 23:31:54 +08:00
|
|
|
unused, but will be used in the future for optional properties of
|
1998-07-08 22:54:54 +08:00
|
|
|
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.
|
1999-04-16 23:31:54 +08:00
|
|
|
This function returns an attribute ID for success or negative for failure.
|
1998-07-08 22:54:54 +08:00
|
|
|
|
|
|
|
|
<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.
|
1999-04-16 23:31:54 +08:00
|
|
|
This function returns an attribute ID for success or negative for failure.
|
1998-07-08 22:54:54 +08:00
|
|
|
|
|
|
|
|
<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.
|
1999-04-16 23:31:54 +08:00
|
|
|
This function returns an attribute ID for success or negative for failure.
|
1998-07-08 22:54:54 +08:00
|
|
|
|
|
|
|
|
<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>
|
2000-07-07 00:33:00 +08:00
|
|
|
<dt><code>herr_t H5Aiterate (hid_t <em>loc_id</em>,
|
1998-07-08 22:54:54 +08:00
|
|
|
unsigned *<em>attr_number</em>,
|
|
|
|
|
H5A_operator <em>operator</em>,
|
|
|
|
|
void *<em>operator_data</em>)</code>
|
1999-04-16 23:31:54 +08:00
|
|
|
<dd> This function iterates over the attributes of the dataset or group
|
1998-07-08 22:54:54 +08:00
|
|
|
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>
|
1999-12-14 04:39:48 +08:00
|
|
|
<dt><code>ssize_t H5Aget_name (hid_t <em>attr_id</em>,
|
1999-05-29 04:09:10 +08:00
|
|
|
size_t <em>buf_size</em>, char *<em>buf</em>)</code>
|
1998-07-08 22:54:54 +08:00
|
|
|
<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>
|
1998-09-10 06:48:37 +08:00
|
|
|
<dt><code>int H5Aget_num_attrs (hid_t <em>loc_id</em>)</code>
|
1998-07-08 22:54:54 +08:00
|
|
|
<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>
|
|
|
|
|
|
1998-12-22 06:52:56 +08:00
|
|
|
|
2003-03-15 03:12:34 +08:00
|
|
|
<!-- #BeginLibraryItem "/ed_libs/NavBar_UG.lbi" --><hr>
|
1998-12-22 06:52:56 +08:00
|
|
|
<center>
|
|
|
|
|
<table border=0 width=98%>
|
|
|
|
|
<tr><td valign=top align=left>
|
2003-03-15 03:12:34 +08:00
|
|
|
<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>
|
2003-07-04 03:35:53 +08:00
|
|
|
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User's Guide for Release 1.6</a> <br>
|
2003-03-15 03:12:34 +08:00
|
|
|
<!--
|
|
|
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
|
|
|
-->
|
1998-12-22 06:52:56 +08:00
|
|
|
</td>
|
|
|
|
|
<td valign=top align=right>
|
2003-03-15 03:12:34 +08:00
|
|
|
And in this document, the
|
2003-07-04 03:35:53 +08:00
|
|
|
<a href="H5.user.html"><strong>HDF5 User's Guide from Release 1.4.5:</strong></a>
|
2003-03-15 03:12:34 +08:00
|
|
|
<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>
|
1998-12-22 06:52:56 +08:00
|
|
|
</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
</center>
|
1998-09-10 06:48:37 +08:00
|
|
|
<hr>
|
2003-03-15 03:12:34 +08:00
|
|
|
<!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address>
|
|
|
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
2000-12-09 06:12:36 +08:00
|
|
|
<br>
|
2003-07-04 03:35:53 +08:00
|
|
|
Describes HDF5 Release 1.4.5, February 2003
|
2003-03-15 03:12:34 +08:00
|
|
|
</address><!-- #EndLibraryItem -->
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Last modified: 6 July 2000
|
2000-12-09 06:12:36 +08:00
|
|
|
|
1998-09-10 06:48:37 +08:00
|
|
|
|
2003-03-15 03:12:34 +08:00
|
|
|
</body>
|
1998-07-08 22:54:54 +08:00
|
|
|
</html>
|
