mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-27 02:10:55 +08:00
4146d79af1
Purpose:
Changed "HDF5 User's Guide" links (in navigation bars, primarily)
to point to new user's guide, which will reside for a while yet on
the HDF server.
The old user's guide will still go out with the distribution under
the label "HDF5 User's Guide, Release 1.4.5."
Platforms tested:
IE 5
747 lines
29 KiB
HTML
747 lines
29 KiB
HTML
<html>
|
|
<head><title>
|
|
HDF5/H5A API Specification
|
|
</title>
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/styles_RM.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/RMelect.css" rel="stylesheet" type="text/css">
|
|
<!-- #EndLibraryItem --></head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.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="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<br>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<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_H5I.html">H5I</a>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<br>
|
|
<a href="RM_H5R.html">H5R</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="PredefDTypes.html">Datatypes</a>
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
<!-- #EndLibraryItem --><center>
|
|
<h1>H5A: Attribute Interface</h1>
|
|
</center>
|
|
|
|
<h2>Attribute API Functions</h2>
|
|
|
|
These functions create and manipulate attributes
|
|
and information about attributes.
|
|
|
|
<p>
|
|
<strong>The C Interfaces:</strong>
|
|
|
|
<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>
|
|
<br>
|
|
|
|
<i>Alphabetical Listing</i>
|
|
|
|
<table border="0">
|
|
<tr>
|
|
<td valign="top">
|
|
<li><a href="#Annot-Close">H5Aclose</a>
|
|
<li><a href="#Annot-Create">H5Acreate</a>
|
|
<li><a href="#Annot-Delete">H5Adelete</a>
|
|
<li><a href="#Annot-GetName">H5Aget_name</a>
|
|
</td>
|
|
|
|
<td> </td>
|
|
|
|
<td valign="top">
|
|
<li><a href="#Annot-NumAttrs">H5Aget_num_attrs</a>
|
|
<li><a href="#Annot-GetSpace">H5Aget_space</a>
|
|
<li><a href="#Annot-GetType">H5Aget_type</a>
|
|
<li><a href="#Annot-Iterate">H5Aiterate</a>
|
|
</td>
|
|
|
|
<td> </td>
|
|
|
|
<td valign="top">
|
|
<li><a href="#Annot-OpenIdx">H5Aopen_idx</a>
|
|
<li><a href="#Annot-OpenName">H5Aopen_name</a>
|
|
<li><a href="#Annot-Read">H5Aread</a>
|
|
<li><a href="#Annot-Write">H5Awrite</a>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
<strong>The FORTRAN90 Interfaces:</strong>
|
|
|
|
<br>
|
|
<font size=-1>
|
|
<i>In general, each FORTRAN90 subroutine performs exactly the same task
|
|
as the corresponding C function. The links below go to the C function
|
|
descriptions, which serve as general descriptions for both. A button,
|
|
under <strong>Non-C API(s)</strong> at the end of the C function description,
|
|
opens an external browser window displaying the FORTRAN90-specific
|
|
information. You will probably want to adjust the size and location of
|
|
this external window so that both browser windows are visible and to
|
|
facilitate moving easily between them.</i>
|
|
</font>
|
|
|
|
<table border=0>
|
|
<tr><td valign=top>
|
|
<ul>
|
|
<li><a href="#Annot-Create">h5acreate_f</a>
|
|
<li><a href="#Annot-Write">h5awrite_f</a>
|
|
<li><a href="#Annot-Read">h5aread_f</a>
|
|
<li><a href="#Annot-Close">h5aclose_f</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Annot-GetName">h5aget_name_f</a>
|
|
<li><a href="#Annot-OpenName">h5aopen_name_f</a>
|
|
<li><a href="#Annot-OpenIdx">h5aopen_idx_f</a>
|
|
<li><a href="#Annot-GetSpace">h5aget_space_f</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Annot-GetType">h5aget_type_f</a>
|
|
<li><a href="#Annot-NumAttrs">h5aget_num_attrs_f</a>
|
|
<!--<li><a href="#Annot-Iterate">h5aiterate_f</a>-->
|
|
<li><a href="#Annot-Delete">h5adelete_f</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 named <code>name</code>
|
|
and attached to the object specified with <code>loc_id</code>.
|
|
<code>loc_id</code> is a group, dataset, or named datatype identifier.
|
|
<p>
|
|
The attribute name specified in <code>name</code> must be unique.
|
|
Attempting to create an attribute with the same name as an already
|
|
existing attribute will fail, leaving the pre-existing attribute
|
|
in place. To overwrite an existing attribute with a new attribute
|
|
of the same name, first call <code>H5Adelete</code> then recreate
|
|
the attribute with <code>H5Acreate</code>.
|
|
<p>
|
|
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.
|
|
<p>
|
|
Currently only simple dataspaces are allowed for attribute dataspaces.
|
|
<p>
|
|
The attribute creation property list, <code>create_plist</code>,
|
|
is currently unused;
|
|
it may be used in the future for optional attribute properties.
|
|
At this time, <code>H5P_DEFAULT</code> is the only accepted value.
|
|
<p>
|
|
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: 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 unused;
|
|
the only accepted value is <code>H5P_DEFAULT</code>.)
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns an attribute identifier if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5a_FORTRAN.html#h5acreate_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</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 returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5a_FORTRAN.html#h5aopen_name_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</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 returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5a_FORTRAN.html#h5aopen_idx_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</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>const 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>const void *</em><code>buf</code>
|
|
<dd>IN: Data to be written.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5a_FORTRAN.html#h5awrite_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</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>OUT: Buffer for data to be read.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5a_FORTRAN.html#h5aread_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</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 returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5a_FORTRAN.html#h5aget_space_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</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 returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5a_FORTRAN.html#h5aget_type_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Annot-GetName">H5Aget_name</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>ssize_t</em> <code>H5Aget_name</code>(<em>hid_t</em> <code>attr_id</code>,
|
|
<em>size_t</em> <code>buf_size</code>,
|
|
<em>char *</em><code>buf</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 -1)</code>, 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>size_t</em> <code>buf_size</code>
|
|
<dd>IN: The size of the buffer to store the name in.
|
|
<dt><em>char *</em><code>buf</code>
|
|
<dd>IN: Buffer to store 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 a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5a_FORTRAN.html#h5aget_name_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</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 returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5a_FORTRAN.html#h5aget_num_attrs_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Annot-Iterate">H5Aiterate</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</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 a negative value.
|
|
<!--
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5a_FORTRAN.html#h5aiterate_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
--> <!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</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 a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5a_FORTRAN.html#h5adelete_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</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 <code>attr_id</code> by releasing the identifier.
|
|
<p>
|
|
Further use of a released attribute identifier is illegal;
|
|
a function using such an identifier will fail.
|
|
<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 a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5a_FORTRAN.html#h5aclose_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.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="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<br>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<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_H5I.html">H5I</a>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<br>
|
|
<a href="RM_H5R.html">H5R</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="PredefDTypes.html">Datatypes</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.6.0, July 2003
|
|
</address><!-- #EndLibraryItem -->
|
|
|
|
Last modified: 6 June 2001
|
|
|
|
</body>
|
|
</html>
|