mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-03-19 16:50:46 +08:00
[svn-r503] HDF5 Reference Manual
Updated for Alpha2.
This commit is contained in:
Frank Baker
parent
3e213ecf06
commit
c8e75d27b0
99
doc/html/Glossary.html
Normal file
99
doc/html/Glossary.html
Normal file
@ -0,0 +1,99 @@
|
||||
<html><head><title>
|
||||
HDF5 Draft Glossary
|
||||
</title></head>
|
||||
|
||||
<body>
|
||||
|
||||
<hr>
|
||||
<center>
|
||||
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
||||
<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_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>
|
||||
Glossary
|
||||
</center>
|
||||
<hr>
|
||||
|
||||
<center>
|
||||
<h1>HDF5 Glossary</h1>
|
||||
</center>
|
||||
|
||||
<i>(<b>Under construction!</b>
|
||||
This is the bare beginning of a Glossary to accompany the HDF5 documentation;
|
||||
it is by no means complete.)</i>
|
||||
|
||||
<ol type=A>
|
||||
<li><a href="#Glossary-Basic">Basic Types</a>
|
||||
<li><a href="#Glossary-Complex">Complex Types</a>
|
||||
<li><a href="#Glossary-DiskIO">Disk I/O Types</a>
|
||||
</ol>
|
||||
|
||||
<P>Since many of the typedefs in the HDF5 API are not well-defined yet,
|
||||
the types below may change radically en route to a final API...
|
||||
|
||||
<hr>
|
||||
|
||||
<a name="Glossary-Basic">Basic Types:</a>
|
||||
<ul>
|
||||
<li>char - 8-bit character (only for ASCII information)
|
||||
<li>int8 - 8-bit signed integer
|
||||
<li>uint8 - 8-bit unsigned integer
|
||||
<li>int16 - 16-bit signed integer
|
||||
<li>uint16 - 16-bit unsigned integer
|
||||
<li>int32 - 32-bit signed integer
|
||||
<li>uint32 - 32-bit unsigned integer
|
||||
<li>intn - "native" signed integer
|
||||
<li>uintn - "native" unsigned integer
|
||||
<li>int64 - 64-bit signed integer (new)
|
||||
<li>uint64 - 64-bit unsigned integer (new)
|
||||
<li>float32 - 32-bit IEEE float
|
||||
<li>float64 - 64-bit IEEE float
|
||||
</ul>
|
||||
|
||||
<a name="Glossary-Complex">Complex Types:</a>
|
||||
<ul>
|
||||
<li>hid_t - 32-bit unsigned integer used as ID for memory objects
|
||||
<li>hoid_t - 32-bit unsigned integer (currently) used as ID for disk-based
|
||||
objects
|
||||
<li>hbool_t - boolean to indicate true/false/error codes from functions
|
||||
<li>herr_t - 32-bit integer to indicate succeed/fail codes from functions
|
||||
</ul>
|
||||
|
||||
<a name="Glossary-DiskIO">Disk I/O Types:</a>
|
||||
<ul>
|
||||
<li>hoff_t - (64-bit?) offset on disk in bytes
|
||||
<li>hlen_t - (64-bit?) length on disk in bytes
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
<center>
|
||||
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
||||
<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_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>
|
||||
Glossary
|
||||
</center>
|
||||
<hr>
|
||||
|
||||
<address>
|
||||
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
||||
|
||||
<br>
|
||||
Last modified: 14 July 1998
|
||||
|
||||
</body>
|
||||
</html>
|
||||
220
doc/html/RM_H5.html
Normal file
220
doc/html/RM_H5.html
Normal file
@ -0,0 +1,220 @@
|
||||
<html>
|
||||
<head><title>
|
||||
HDF5/H5 Draft API Specification
|
||||
</title></head>
|
||||
|
||||
<body>
|
||||
|
||||
<hr>
|
||||
<center>
|
||||
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
||||
H5
|
||||
<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_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>H5: General Library Functions</h1>
|
||||
</center>
|
||||
|
||||
These functions serve general-purpose needs of the HDF5 library
|
||||
and it users.
|
||||
|
||||
<table border=0>
|
||||
<tr><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Library-Open">H5open</a>
|
||||
<li><a href="#Library-Close">H5close</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Library-Version">H5version</a>
|
||||
<li><a href="#Library-VersCheck">H5vers_check</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Library-DontAtExit">H5dont_atexit</a>
|
||||
</ul>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Library-Open">H5open</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5open</code>(<em>void</em>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Flushes all data to disk, closes file identifiers, and cleans up memory.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5open</code> initialize the library. This function is
|
||||
normally called automatically, but if you find that an
|
||||
HDF5 library function is failing inexplicably, try calling
|
||||
this function first.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt>None.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Library-Close">H5close</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5close</code>(<em>void</em>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Flushes all data to disk, closes file identifiers, and cleans up memory.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5close</code> flushes all data to disk,
|
||||
closes all file identifiers, and cleans up all memory used by
|
||||
the library. This function is generall called when the
|
||||
application calls <code>exit</code>, but may be called earlier
|
||||
in event of an emergency shutdown or out of desire to free all
|
||||
resources used by the HDF5 library.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt>None.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Library-DontAtExit">H5dont_atexit</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5dont_atexit</code>(<em>void</em>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Instructs library not to install <code>atexit</code> cleanup routine.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5dont_atexit</code> indicates to the library that an
|
||||
<code>atexit()</code> cleanup routine should not be installed.
|
||||
The major purpose for this is in situations where the
|
||||
library is dynamically linked into an application and is
|
||||
un-linked from the application before <code>exit()</code> gets
|
||||
called. In those situations, a routine installed with
|
||||
<code>atexit()</code> would jump to a routine which was
|
||||
no longer in memory, causing errors.
|
||||
<p>
|
||||
In order to be effective, this routine <em>must</em> be called
|
||||
before any other HDF function calls, and must be called each
|
||||
time the library is loaded/linked into the application
|
||||
(the first time and after it's been un-loaded).
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt>None.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Library-Version">H5version</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5version</code>(<em>unsigned *</em><code>majnum</code>,
|
||||
<em>unsigned *</em><code>minnum</code>,
|
||||
<em>unsigned *</em><code>relnum</code>,
|
||||
<em>unsigned *</em><code>patnum</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5version</code> retrieves the major, minor, release, and
|
||||
patch versions of the library which is linked to the application.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>unsigned *</em><code>majnum</code>
|
||||
<dd>The major version of the library.
|
||||
<dt><em>unsigned *</em><code>minnum</code>
|
||||
<dd>The minor version of the library.
|
||||
<dt><em>unsigned *</em><code>relnum</code>
|
||||
<dd>The release number of the library.
|
||||
<dt><em>unsigned *</em><code>patnum</code>
|
||||
<dd>The patch number of the library.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Library-VersCheck">H5vers_check</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5vers_check</code>(<em>unsigned *</em><code>majnum</code>,
|
||||
<em>unsigned *</em><code>minnum</code>,
|
||||
<em>unsigned *</em><code>relnum</code>,
|
||||
<em>unsigned *</em><code>patnum</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5vers_check</code> verifies that the arguments match the
|
||||
version numbers compiled into the library. This function is intended
|
||||
to be called from user to verify that the versions of header files
|
||||
compiled into the application match the version of the HDF5 library.
|
||||
<p>
|
||||
Due to the risks of data corruption or segmentation faults,
|
||||
<code>H5vers_check</code> causes the application to abort if the
|
||||
version numbers do not match.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>unsigned *</em><code>majnum</code>
|
||||
<dd>The major version of the library.
|
||||
<dt><em>unsigned *</em><code>minnum</code>
|
||||
<dd>The minor version of the library.
|
||||
<dt><em>unsigned *</em><code>relnum</code>
|
||||
<dd>The release number of the library.
|
||||
<dt><em>unsigned *</em><code>patnum</code>
|
||||
<dd>The patch number of the library.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful.
|
||||
Upon failure, this function causes the application to abort.
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<center>
|
||||
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
||||
H5
|
||||
<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_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>
|
||||
501
doc/html/RM_H5A.html
Normal file
501
doc/html/RM_H5A.html
Normal file
@ -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>
|
||||
405
doc/html/RM_H5D.html
Normal file
405
doc/html/RM_H5D.html
Normal file
@ -0,0 +1,405 @@
|
||||
<html>
|
||||
<head><title>
|
||||
HDF5/H5D Draft API Specification
|
||||
</title></head>
|
||||
|
||||
<body>
|
||||
|
||||
<hr>
|
||||
<center>
|
||||
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
||||
<a href="RM_H5.html">H5</a>
|
||||
<a href="RM_H5A.html">H5A</a>
|
||||
H5D
|
||||
<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>H5D: Datasets Interface</h1>
|
||||
</center>
|
||||
|
||||
<h2>Dataset Object API Functions</h2>
|
||||
|
||||
These functions create and manipulate dataset objects,
|
||||
and set and retrieve their constant or persistent properties.
|
||||
|
||||
<table border=0>
|
||||
<tr><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Dataset-Create">H5Dcreate</a>
|
||||
<li><a href="#Dataset-Open">H5Dopen</a>
|
||||
<li><a href="#Dataset-GetSpace">H5Dget_space</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Dataset-GetType">H5Dget_type</a>
|
||||
<li><a href="#Dataset-GetCreatePlist">H5Dget_create_plist</a>
|
||||
<li><a href="#Dataset-Read">H5Dread</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Dataset-Write">H5Dwrite</a>
|
||||
<li><a href="#Dataset-Extend">H5Dextend</a>
|
||||
<li><a href="#Dataset-Close">H5Dclose</a>
|
||||
</ul>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataset-Create">H5Dcreate</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Dcreate</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_id</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Creates a dataset at the specified location.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Dcreate</code> creates a data set with a name,
|
||||
<code>name</code>, in the file or in the group specified by
|
||||
the identifier <code>loc_id</code>.
|
||||
The dataset has the datatype and dataspace identified by
|
||||
<code>type_id</code> and <code>space_id</code>, respectively.
|
||||
The specified datatype and dataspace are the datatype and
|
||||
dataspace of the dataset as it will exist in the file,
|
||||
which may be different than in application memory.
|
||||
Dataset creation properties are specified by the argument
|
||||
<code>create_plist_id</code>.
|
||||
<p>
|
||||
<code>create_plist_id</code> is a <code>H5P_DATASET_CREATE</code>
|
||||
property list created with <code>H5Pcreate()</code> and
|
||||
initialized with the various functions described above.
|
||||
<code>H5Dcreate()</code> returns a dataset identifier for success
|
||||
or negative for failure. The identifier should eventually be
|
||||
closed by calling <code>H5Dclose()</code> to release resources
|
||||
it uses.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>loc_id</code>
|
||||
<dd>Identifier of the file or group to create the dataset within.
|
||||
<dt><em>const char *</em> <code>name</code>
|
||||
<dd>The name of the dataset to create.
|
||||
<dt><em>hid_t</em> <code>type_id</code>
|
||||
<dd>Identifier of the datatype to use when creating the dataset.
|
||||
<dt><em>hid_t</em> <code>space_id</code>
|
||||
<dd>Identifier of the dataspace to use when creating the dataset.
|
||||
<dt><em>hid_t</em> <code>create_plist_id</code>
|
||||
<dd>Identifier of the set creation property list.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a dataset identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataset-Open">H5Dopen</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Dopen</code>(<em>hid_t </em><code>loc_id</code>,
|
||||
<em>const char *</em><code>name</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Opens an existing dataset.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Dopen</code> opens an existing dataset for access in the file
|
||||
or group specified in <code>loc_id</code>. <code>name</code> is
|
||||
a dataset name and is used to identify the dataset in the file.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>loc_id</code>
|
||||
<dd>Identifier of the file to access the dataset within.
|
||||
<dt><em>const char *</em> <code>name</code>
|
||||
<dd>The name of the dataset to access.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a dataset identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataset-GetSpace">H5Dget_space</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Dget_space</code>(<em>hid_t </em><code>dataset_id</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Returns an identifier for a copy of the dataspace for a dataset.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Dget_space</code> returns an identifier for a copy of the
|
||||
dataspace for a dataset.
|
||||
The dataspace identifier should be released with the
|
||||
<code>H5Sclose()</code> function.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>dataset_id</code>
|
||||
<dd>Identifier of the dataset to query.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a dataspace identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataset-GetType">H5Dget_type</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Dget_type</code>(<em>hid_t </em><code>dataset_id</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Returns an identifier for a copy of the datatype for a dataset.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Dget_type</code> returns an identifier for a copy of the
|
||||
datatype for a dataset.
|
||||
The datatype should be released with the <code>H5Tclose()</code> function.
|
||||
<p>
|
||||
If a dataset has a named datatype, then an identifier to the
|
||||
opened datatype is returned.
|
||||
Otherwise, the returned datatype is read-only.
|
||||
If atomization of the datatype fails, then the datatype is closed.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>dataset_id</code>
|
||||
<dd>Identifier of the dataset to query.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a datatype identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataset-GetCreatePlist">H5Dget_create_plist</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Dget_create_plist</code>(<em>hid_t </em><code>dataset_id</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Returns an identifier for a copy of the
|
||||
dataset creation property list for a dataset.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Dget_create_plist</code> returns an identifier for a
|
||||
copy of the dataset creation property list for a dataset.
|
||||
The creation property list identifier should be released with
|
||||
the <code>H5Pclose()</code> function.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>dataset_id</code>
|
||||
<dd>Identifier of the dataset to query.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a dataset creation property list identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataset-Read">H5Dread</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t </em><code>H5Dread</code>(<em>hid_t </em><code>dataset_id</code>,
|
||||
<em>hid_t</em> <code>mem_type_id</code>,
|
||||
<em>hid_t</em> <code>mem_space_id</code>,
|
||||
<em>hid_t</em> <code>file_space_id</code>,
|
||||
<em>hid_t</em> <code>xfer_plist_id</code>,
|
||||
<em>void *</em> <code>buf</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Reads raw data from the specified dataset into <code>buf</code>,
|
||||
converting from file datatype and dataspace to
|
||||
memory datatype and dataspace.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Dread</code> reads a (partial) dataset, specified by its
|
||||
identifier <code>dataset_id</code>, from the file into the
|
||||
application memory buffer <code>buf</code>.
|
||||
Data transfer properties are defined by the argument
|
||||
<code>xfer_plist_id</code>.
|
||||
The memory datatype of the (partial) dataset is identified by
|
||||
the identifier <code>mem_type_id</code>.
|
||||
The part of the dataset to read is defined by
|
||||
<code>mem_space_id</code> and <code>file_space_id</code>.
|
||||
<p>
|
||||
<code>file_space_id</code> can be the constant <code>H5S_ALL</code>,
|
||||
which indicates that the entire file data space is to be referenced.
|
||||
<p>
|
||||
<code>mem_space_id</code> can be the constant <code>H5S_ALL</code>,
|
||||
in which case the memory data space is the same as the file data space
|
||||
defined when the dataset was created.
|
||||
<p>
|
||||
The number of elements in the memory data space must match
|
||||
the number of elements in the file data space.
|
||||
<p>
|
||||
<code>xfer_plist_id</code> can be the constant <code>H5P_DEFAULT</code>,
|
||||
in which case the default data transfer properties are used.
|
||||
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>dataset_id</code>
|
||||
<dd>Identifier of the dataset read from.
|
||||
<dt><em>hid_t</em> <code>mem_type_id</code>
|
||||
<dd>Identifier of the memory datatype.
|
||||
<dt><em>hid_t</em> <code>mem_space_id</code>
|
||||
<dd>Identifier of the memory dataspace.
|
||||
<dt><em>hid_t</em> <code>file_space_id</code>
|
||||
<dd>Identifier of the dataset's dataspace in the file.
|
||||
<dt><em>hid_t</em> <code>xfer_plist_id</code>
|
||||
<dd>Identifier of a transfer property list for this I/O operation.
|
||||
<dt><em>void *</em> <code>buf</code>
|
||||
<dd>Buffer to store data read from the file.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataset-Write">H5Dwrite</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t </em><code>H5Dwrite</code>(<em>hid_t </em><code>dataset_id</code>,
|
||||
<em>hid_t</em> <code>mem_type_id</code>,
|
||||
<em>hid_t</em> <code>mem_space_id</code>,
|
||||
<em>hid_t</em> <code>file_space_id</code>,
|
||||
<em>hid_t</em> <code>xfer_plist_id</code>,
|
||||
<em>const void *</em> <code>buf</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Writes raw data from an application buffer <code>buf</code> to
|
||||
the specified dataset, converting from
|
||||
memory datatype and dataspace to file datatype and dataspace.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Dwrite</code> writes a (partial) dataset, specified by its
|
||||
identifier <code>dataset_id</code>, from the
|
||||
application memory buffer <code>buf</code> into the file.
|
||||
Data transfer properties are defined by the argument
|
||||
<code>xfer_plist_id</code>.
|
||||
The memory datatype of the (partial) dataset is identified by
|
||||
the identifier <code>mem_type_id</code>.
|
||||
The part of the dataset to write is defined by
|
||||
<code>mem_space_id</code> and <code>file_space_id</code>.
|
||||
<p>
|
||||
<code>file_space_id</code> can be the constant <code>H5S_ALL</code>.
|
||||
which indicates that the entire file data space is to be referenced.
|
||||
<p>
|
||||
<code>mem_space_id</code> can be the constant <code>H5S_ALL</code>,
|
||||
in which case the memory data space is the same as the file data space
|
||||
defined when the dataset was created.
|
||||
<p>
|
||||
The number of elements in the memory data space must match
|
||||
the number of elements in the file data space.
|
||||
<p>
|
||||
<code>xfer_plist_id</code> can be the constant <code>H5P_DEFAULT</code>.
|
||||
in which case the default data transfer properties are used.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>dataset_id</code>
|
||||
<dd>Identifier of the dataset read from.
|
||||
<dt><em>hid_t</em> <code>mem_type_id</code>
|
||||
<dd>Identifier of the memory datatype.
|
||||
<dt><em>hid_t</em> <code>mem_space_id</code>
|
||||
<dd>Identifier of the memory dataspace.
|
||||
<dt><em>hid_t</em> <code>file_space_id</code>
|
||||
<dd>Identifier of the dataset's dataspace in the file.
|
||||
<dt><em>hid_t</em> <code>xfer_plist_id</code>
|
||||
<dd>Identifier of a transfer property list for this I/O operation.
|
||||
<dt><em>const void *</em> <code>buf</code>
|
||||
<dd>Buffer with data to be written to the file.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataset-Extend">H5Dextend</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t </em><code>H5Dextend</code>(<em>hid_t </em><code>dataset_id</code>,
|
||||
<em>const hsize_t *</em> <code>size</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Extends a dataset with unlimited dimension.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Dextend</code> verifies that the dataset is at least of size
|
||||
<code>size</code>.
|
||||
The dimensionality of <code>size</code> is the same as that of
|
||||
the dataspace of the dataset being changed.
|
||||
This function cannot be applied to a dataset with fixed dimensions.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>dataset_id</code>
|
||||
<dd>Identifier of the dataset.
|
||||
<dt><em>const hsize_t *</em> <code>size</code>
|
||||
<dd>Array containing the new magnitude of each dimension.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataset-Close">H5Dclose</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Dclose</code>(<em>hid_t </em><code>dataset_id</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Dclose</code> ends access to a dataset specified by
|
||||
<code>dataset_id</code> and releases resources used by it.
|
||||
Further use of the dataset identifier is illegal in calls to
|
||||
the dataset API.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>dataset_id</code>
|
||||
<dd>Identifier of the dataset to finish 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>
|
||||
<a href="RM_H5A.html">H5A</a>
|
||||
H5D
|
||||
<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>
|
||||
361
doc/html/RM_H5E.html
Normal file
361
doc/html/RM_H5E.html
Normal file
@ -0,0 +1,361 @@
|
||||
<html>
|
||||
<head><title>
|
||||
HDF5/H5E Draft API Specification
|
||||
</title></head>
|
||||
|
||||
<body>
|
||||
|
||||
<hr>
|
||||
<center>
|
||||
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
||||
<a href="RM_H5.html">H5</a>
|
||||
<a href="RM_H5A.html">H5A</a>
|
||||
<a href="RM_H5D.html">H5D</a>
|
||||
H5E
|
||||
<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>H5E: Error Interface</h1>
|
||||
</center>
|
||||
|
||||
<h2>Error API Functions</h2>
|
||||
|
||||
These functions provide error handling capabilities in the HDF5 environment.
|
||||
|
||||
<table border=0>
|
||||
<tr><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Error-SetAuto">H5Eset_auto</a>
|
||||
<li><a href="#Error-GetAuto">H5Eget_auto</a>
|
||||
<li><a href="#Error-Clear">H5Eclear</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Error-Print">H5Eprint</a>
|
||||
<li><a href="#Error-Walk">H5Ewalk</a>
|
||||
<li><a href="#Error-WalkCB">H5Ewalk_cb</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Error-GetMajor">H5Eget_major</a>
|
||||
<li><a href="#Error-GetMinor">H5Eget_minor</a>
|
||||
</ul>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
<p>
|
||||
The Error interface provides error handling in the form of a stack.
|
||||
The <code>FUNC_ENTER()</code> macro clears the error stack whenever
|
||||
an interface function is entered.
|
||||
When an error is detected, an entry is pushed onto the stack.
|
||||
As the functions unwind, additional entries are pushed onto the stack.
|
||||
The API function will return some indication that an error occurred and
|
||||
the application can print the error stack.
|
||||
<p>
|
||||
Certain API functions in the H5E package, such as <code>H5Eprint()</code>,
|
||||
do not clear the error stack. Otherwise, any function which
|
||||
does not have an underscore immediately after the package name
|
||||
will clear the error stack. For instance, <code>H5Fopen()</code>
|
||||
clears the error stack while <code>H5F_open()</code> does not.
|
||||
<p>
|
||||
An error stack has a fixed maximum size.
|
||||
If this size is exceeded then the stack will be truncated and only the
|
||||
inner-most functions will have entries on the stack.
|
||||
This is expected to be a rare condition.
|
||||
<p>
|
||||
Each thread has its own error stack, but since
|
||||
multi-threading has not been added to the library yet, this
|
||||
package maintains a single error stack. The error stack is
|
||||
statically allocated to reduce the complexity of handling
|
||||
errors within the H5E package.
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Error-SetAuto">H5Eset_auto</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5Eset_auto</code>(<em>H5E_auto_t</em> <code>func</code>,
|
||||
<em>void *</em><code>client_data</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Turns automatic error printing on or off.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Eset_auto</code> turns on or off automatic printing of
|
||||
errors. When turned on (non-null <code>func</code> pointer),
|
||||
any API function which returns an error indication will
|
||||
first call <code>func</code>, passing it <code>client_data</code>
|
||||
as an argument.
|
||||
<p>
|
||||
When the library is first initialized the auto printing function
|
||||
is set to <code>H5Eprint()</code> (cast appropriately) and
|
||||
<code>client_data</code> is the standard error stream pointer,
|
||||
<code>stderr</code>.
|
||||
<p>
|
||||
Automatic stack traversal is always in the
|
||||
<code>H5E_WALK_DOWNWARD</code> direction.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>H5E_auto_t</em> <code>func</code>
|
||||
<dd>Function to be called upon an error condition.
|
||||
<dt><em>void *</em><code>client_data</code>
|
||||
<dd>Data passed to the error function.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Error-GetAuto">H5Eget_auto</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5Eget_auto</code>(<em>H5E_auto_t *</em> <code>func</code>,
|
||||
<em>void **</em><code>client_data</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Returns the current settings for the automatic error stack
|
||||
traversal function and its data.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Eget_auto</code> returns the current settings for the
|
||||
automatic error stack traversal function, <code>func</code>,
|
||||
and its data, <code>client_data</code>. Either (or both)
|
||||
arguments may be null in which case the value is not returned.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>H5E_auto_t *</em> <code>func</code>
|
||||
<dd>Current setting for the function to be called upon an
|
||||
error condition.
|
||||
<dt><em>void **</em><code>client_data</code>
|
||||
<dd>Current setting for the data passed to the error function.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Error-Clear">H5Eclear</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5Eclear</code>(<code>void</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Clears the error stack for the current thread.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Eclear</code> clears the error stack for the current thread.
|
||||
<p>
|
||||
The stack is also cleared whenever an API function is called,
|
||||
with certain exceptions (for instance, <code>H5Eprint()</code>).
|
||||
<p>
|
||||
<code>H5Eclear</code> can fail if there are problems initializing
|
||||
the library.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt>None
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Error-Print">H5Eprint</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5Eprint</code>(<em>FILE *</em> <code>stream</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Prints the error stack in a default manner.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Eprint</code> prints the error stack on the specified
|
||||
stream, <code>stream</code>.
|
||||
Even if the error stack is empty, a one-line message will be printed:
|
||||
<br>
|
||||
<code>HDF5-DIAG: Error detected in thread 0.</code>
|
||||
<p>
|
||||
<code>H5Eprint</code> is a convenience function for
|
||||
<code>H5Ewalk()</code> with a function that prints error messages.
|
||||
Users are encouraged to write there own more specific error handlers.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>FILE *</em> <code>stream</code>
|
||||
<dd>File pointer, or stderr if NULL.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Error-Walk">H5Ewalk</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5Ewalk</code>(<em>H5E_direction_t</em> <code>direction</code>,
|
||||
<em>H5E_walk_t</em> <code>func</code>,
|
||||
<em>void *</em> <code>client_data</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Walks the error stack for the current thread, calling a specified
|
||||
function.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Ewalk</code> walks the error stack for the current thread
|
||||
and calls the specified function for each error along the way.
|
||||
<p>
|
||||
<code>direction</code> determines whether the stack is walked
|
||||
from the inside out or the outside in.
|
||||
A value of <code>H5E_WALK_UPWARD</code> means begin with the
|
||||
most specific error and end at the API;
|
||||
a value of <code>H5E_WALK_DOWNWARD</code> means to start at the
|
||||
API and end at the inner-most function where the error was first
|
||||
detected.
|
||||
<p>
|
||||
<code>func</code> will be called for each error in the error stack.
|
||||
Its arguments will include an index number (beginning at zero
|
||||
regardless of stack traversal direction), an error stack entry,
|
||||
and the <code>client_data</code> pointer passed to
|
||||
<code>H5E_print</code>.
|
||||
<p>
|
||||
<code>H5Ewalk</code> can fail if there are problems initializing
|
||||
the library.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>H5E_direction_t</em> <code>direction</code>
|
||||
<dd>Direction in which the error stack is to be walked.
|
||||
<dt><em>H5E_walk_t</em> <code>func</code>
|
||||
<dd>Function to be called for each error encountered.
|
||||
<dt><em>void *</em> <code>client_data</code>
|
||||
<dd>Data to be passed with <code>func</code>.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Error-WalkCB">H5Ewalk_cb</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5Ewalk_cb</code>(<em>int</em> <code>n</code>,
|
||||
<em>H5E_error_t *</em><code>err_desc</code>,
|
||||
<em>void</em> <code>*client_data</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Default error stack traversal callback function
|
||||
that prints error messages to the specified output stream.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Ewalk_cb</code> is a default error stack traversal callback
|
||||
function that prints error messages to the specified output stream.
|
||||
It is not meant to be called directly but rather as an
|
||||
argument to the <code>H5Ewalk()</code> function.
|
||||
This function is called also by <code>H5Eprint()</code>.
|
||||
Application writers are encouraged to use this function as a
|
||||
model for their own error stack walking functions.
|
||||
<p>
|
||||
<code>n</code> is a counter for how many times this function
|
||||
has been called for this particular traversal of the stack.
|
||||
It always begins at zero for the first error on the stack
|
||||
(either the top or bottom error, or even both, depending on
|
||||
the traversal direction and the size of the stack).
|
||||
<p>
|
||||
<code>err_desc</code> is an error description. It contains all the
|
||||
information about a particular error.
|
||||
<p>
|
||||
<code>client_data</code> is the same pointer that was passed as the
|
||||
<code>client_data</code> argument of <code>H5Ewalk()</code>.
|
||||
It is expected to be a file pointer (or stderr if null).
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>int</em> <code>n</code>
|
||||
<dd>Number of times this function has been called
|
||||
for this traversal of the stack.
|
||||
<dt><em>H5E_error_t *</em><code>err_desc</code>
|
||||
<dd>Error description.
|
||||
<dt><em>void</em> <code>*client_data</code>
|
||||
<dd>A file pointer, or stderr if null.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Error-GetMajor">H5Eget_major</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>const char *</em> <code>H5Eget_major</code>(<em>H5E_major_t</em> <code>n</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Returns a character string describing an error specified by a
|
||||
major error number.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd>Given a major error number, <code>H5Eget_major</code> returns a
|
||||
constant character string that describes the error.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>H5E_major_t</em> <code>n</code>
|
||||
<dd>Major error number.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd> Returns a character string describing the error if successful.
|
||||
Otherwise returns "Invalid major error number."
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Error-GetMinor">H5Eget_minor</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>const char *</em> <code>H5Eget_minor</code>(<em>H5E_minor_t</em> <code>n</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Returns a character string describing an error specified by a
|
||||
minor error number.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd>Given a minor error number, <code>H5Eget_minor</code> returns a
|
||||
constant character string that describes the error.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>H5E_minor_t</em> <code>n</code>
|
||||
<dd>Minor error number.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd> Returns a character string describing the error if successful.
|
||||
Otherwise returns "Invalid minor error number."
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<center>
|
||||
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
||||
<a href="RM_H5.html">H5</a>
|
||||
<a href="RM_H5A.html">H5A</a>
|
||||
<a href="RM_H5D.html">H5D</a>
|
||||
H5E
|
||||
<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>
|
||||
300
doc/html/RM_H5F.html
Normal file
300
doc/html/RM_H5F.html
Normal file
@ -0,0 +1,300 @@
|
||||
<html>
|
||||
<head><title>
|
||||
HDF5/H5F Draft API Specification
|
||||
</title></head>
|
||||
|
||||
<body>
|
||||
|
||||
<hr>
|
||||
<center>
|
||||
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
||||
<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>
|
||||
H5F
|
||||
<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>H5F: File Interface</h1>
|
||||
</center>
|
||||
|
||||
<h2>File API Functions</h2>
|
||||
|
||||
These functions are designed to provide file-level access to HDF5 files.
|
||||
Further manipulation of objects inside a file is performed through one of APIs
|
||||
documented below.
|
||||
|
||||
<table border=0>
|
||||
<tr><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#File-Open">H5Fopen</a>
|
||||
<li><a href="#File-Create">H5Fcreate</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#File-IsHDF5">H5Fis_hdf5</a>
|
||||
<li><a href="#File-Close">H5Fclose</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#File-GetCreateTemplate">H5Fget_create_template</a>
|
||||
<li><a href="#File-GetAccessTemplate">H5Fget_access_template</a>
|
||||
</ul>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="File-Open">H5Fopen</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Fopen</code>(<em>const char *</em><code>name</code>,
|
||||
<em>unsigned</em> <code>flags</code>,
|
||||
<em>hid_t</em> <code>access_id</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Opens an existing file.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Fopen</code> opens an existing file and is the primary
|
||||
function for accessing existing HDF5 files.
|
||||
<p>
|
||||
The parameter <code>access_id</code> is a file access property
|
||||
list identifier or <code>H5P_DEFAULT</code> for the default I/O access
|
||||
parameters.
|
||||
<p>
|
||||
The <code>flags</code> argument determines whether writing
|
||||
to an existing file will be allowed or not.
|
||||
The file is opened with read and write permission if
|
||||
<code>flags</code> is set to <code>H5F_ACC_RDWR</code>.
|
||||
All flags may be combined with the bit-wise OR operator (`|')
|
||||
to change the behavior of the file open call.
|
||||
The more complex behaviors of a file's access are controlled
|
||||
through the file-access property list.
|
||||
<p>
|
||||
Files which are opened more than once return a unique identifier
|
||||
for each <code>H5Fopen()</code> call and can be accessed
|
||||
through all file identifiers.
|
||||
<p>
|
||||
The return value is a file identifier for the open file and it
|
||||
should be closed by calling <code>H5Fclose()</code> when it is
|
||||
no longer needed.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>const char *</em><code>name</code>
|
||||
<dd>Name of the file to access.
|
||||
<dt><em>unsigned</em> <code>flags</code>
|
||||
<dd>File access flags. See the <code>H5Fcreate</code>
|
||||
parameters list for a list of possible values.
|
||||
<dt><em>hid_t</em> <code>access_id</code>
|
||||
<dd>Identifier for the file access properties list.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a file identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="File-Create">H5Fcreate</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Fcreate</code>(<em>const char *</em><code>name</code>,
|
||||
<em>unsigned</em> <code>flags</code>,
|
||||
<em>hid_t</em> <code>create_id</code>,
|
||||
<em>hid_t</em> <code>access_id</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Creates HDF5 files.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Fcreate</code> is the primary function for creating
|
||||
HDF5 files .
|
||||
<p>
|
||||
The <code>flags</code> parameter determines whether an
|
||||
existing file will be overwritten. All newly created files
|
||||
are opened for both reading and writing. All flags may be
|
||||
combined with the bit-wise OR operator (`|') to change
|
||||
the behavior of the <code>H5Fcreate</code> call.
|
||||
<p>
|
||||
The more complex behaviors of file creation and access
|
||||
are controlled through the file-creation and file-access
|
||||
property lists. The value of <code>H5P_DEFAULT</code> for
|
||||
a template value indicates that the library should use
|
||||
the default values for the appropriate template. Also see
|
||||
<code>H5Fpublic.h</code> for the list of supported flags.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>const char *</em><code>name</code>
|
||||
<dd>Name of the file to access.
|
||||
<dt><em>uintn</em> <code>flags</code>
|
||||
<dd>File access flags. Possible values include:
|
||||
<ul><dl>
|
||||
<dt>H5F_ACC_RDWR
|
||||
<dd>Allow read and write access to file.
|
||||
<dt>H5F_ACC_RDONLY
|
||||
<dd>Allow read-only access to file.
|
||||
<dt>H5F_ACC_TRUNC
|
||||
<dd>Truncate file, if it already exists,
|
||||
erasing all data previously stored in the file.
|
||||
<dt>H5F_ACC_EXCL
|
||||
<dd>Fail if file already exists.
|
||||
<dt>H5F_ACC_DEBUG
|
||||
<dd>Print debug information.
|
||||
<dt>H5P_DEFAULT
|
||||
<dd>Apply default file access and creation properties.
|
||||
</dl></ul>
|
||||
<dt><em>hid_t</em> <code>create_id</code>
|
||||
<dd>File creation template identifier, used when modifying
|
||||
default file meta-data.
|
||||
<dt><em>hid_t</em> <code>access_id</code>
|
||||
<dd>File access property list identifier.
|
||||
If parallel file access is desired, this is a collective
|
||||
call according to the communicator stored in the
|
||||
<code>access_template</code>.
|
||||
Use <code>0</code> for default access template.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a file identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="File-IsHDF5">H5Fis_hdf5</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hbool_t </em><code>H5Fis_hdf5</code>(<em>const char *</em><code>name</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Determines whether a file is in the HDF5 format.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Fis_hdf5</code> determines whether a file is in
|
||||
the HDF5 format.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>const char *</em><code>name</code>
|
||||
<dd>File name to check format.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns <code>TRUE</code> or <code>FALSE</code> if successful.
|
||||
Otherwise returns FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="File-GetCreateTemplate">H5Fget_create_template</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Fget_create_template</code>(<em>hid_t</em> <code>file_id</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Returns a file creation property list identifier.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Fget_create_template</code> returns a file creation
|
||||
property list identifier identifying the creation properties
|
||||
used to create this file. This function is useful for
|
||||
duplicating properties when creating another file.
|
||||
<p>
|
||||
See "File Creation Properties" in
|
||||
<a href="RM_H5P.html">H5P: Property List Interface</a>
|
||||
in this reference manual and
|
||||
"File Creation Properties"
|
||||
in <a href="Files.html"><cite>Files</cite></a> in the
|
||||
<cite>HDF5 User's Guide</cite> for
|
||||
additional information and related functions.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>file_id</code>
|
||||
<dd>Identifier of the file to get creation property list of
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a file creation property list identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="File-GetAccessTemplate">H5Fget_access_template</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Fget_access_template</code>(<em>hid_t</em> <code>file_id</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Returns a file access property list identifier.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Fget_access_template</code> returns the
|
||||
file access property list identifier of the specified file.
|
||||
<p>
|
||||
See "File Access Properties" in
|
||||
<a href="RM_H5P.html">H5P: Property List Interface</a>
|
||||
in this reference manual and
|
||||
"File Access Property Lists"
|
||||
in <a href="Files.html"><cite>Files</cite></a> in the
|
||||
<cite>HDF5 User's Guide</cite> for
|
||||
additional information and related functions.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>file_id</code>
|
||||
<dd>Identifier of file to get access property list of
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a file access property list identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="File-Close">H5Fclose</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t </em><code>H5Fclose</code>(<em>hid_t</em> <code>file_id</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Terminates access to an HDF5 file.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Fclose</code> terminates access to an HDF5 file.
|
||||
If this is the last file identifier open for a file
|
||||
and if access identifiers are still in use,
|
||||
this function will fail.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>file_id</code>
|
||||
<dd>Identifier of a file to terminate 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>
|
||||
<a href="RM_H5A.html">H5A</a>
|
||||
<a href="RM_H5D.html">H5D</a>
|
||||
<a href="RM_H5E.html">H5E</a>
|
||||
H5F
|
||||
<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>
|
||||
72
doc/html/RM_H5Front.html
Normal file
72
doc/html/RM_H5Front.html
Normal file
@ -0,0 +1,72 @@
|
||||
<html>
|
||||
<head><title>
|
||||
HDF5 Draft API Specification
|
||||
</title></head>
|
||||
<body>
|
||||
|
||||
<hr>
|
||||
<center>
|
||||
HDF5 Reference Manual
|
||||
<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_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>HDF5: API Specification<br>Reference Manual</h1>
|
||||
</center>
|
||||
|
||||
The HDF5 libraries provide several interfaces, each of which provides the
|
||||
tools required to meet specific aspects of the HDF5 data-handling requirements.
|
||||
|
||||
<ul>
|
||||
|
||||
<li><a href="RM_H5.html">Library Functions</a> -- The general-purpose <strong>H5</strong> functions.
|
||||
<li><a href="RM_H5F.html">File Interface</a> -- The <strong>H5F</strong> API for accessing HDF files.
|
||||
<li><a href="RM_H5P.html">Property List Interface</a> -- The <strong>H5P</strong> API for manipulating object templates.
|
||||
<li><a href="RM_H5D.html">Dataset Interface</a> -- The <strong>H5D</strong> API for manipulating scientific datasets.
|
||||
<li><a href="RM_H5T.html">Datatype Interface</a> -- The <strong>H5T</strong> API for defining dataset element information.
|
||||
<li><a href="RM_H5S.html">Dataspace Interface</a> -- The <strong>H5S</strong> API for defining dataset dataspace.
|
||||
<li><a href="RM_H5G.html">Group Interface</a> -- The <strong>H5G</strong> API for creating physical groups of objects on disk.
|
||||
<li><a href="RM_H5E.html">Error Interface</a> -- The <strong>H5E</strong> API for error handling.
|
||||
<li><a href="RM_H5Z.html">Compression Interface</a> -- The <strong>H5Z</strong> API for compression.
|
||||
<li><a href="RM_H5A.html">Annotation Interface</a> -- The <strong>H5A</strong> API for annotations.
|
||||
<li><a href="Glossary.html">Glossary</a> -- A glossary of data-types used in the APIs.
|
||||
|
||||
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
<center>
|
||||
HDF5 Reference Manual
|
||||
<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_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>
|
||||
639
doc/html/RM_H5G.html
Normal file
639
doc/html/RM_H5G.html
Normal file
@ -0,0 +1,639 @@
|
||||
<html>
|
||||
<head><title>
|
||||
HDF5/H5G Draft API Specification
|
||||
</title></head>
|
||||
|
||||
<body>
|
||||
|
||||
<hr>
|
||||
<center>
|
||||
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
||||
<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>
|
||||
H5G
|
||||
<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>H5G: Group Interface</h1>
|
||||
</center>
|
||||
|
||||
<h2>Group Object API Functions</h2>
|
||||
|
||||
The Group interface functions create and manipulate physical groups
|
||||
of objects on disk.
|
||||
|
||||
<table border=0>
|
||||
<tr><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Group-Create">H5Gcreate</a>
|
||||
<li><a href="#Group-Open">H5Gopen</a>
|
||||
<li><a href="#Group-Set">H5Gset</a>
|
||||
<li><a href="#Group-Close">H5Gclose</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Group-Push">H5Gpush</a>
|
||||
<li><a href="#Group-Pop">H5Gpop</a>
|
||||
<li><a href="#Group-Link">H5Glink</a>
|
||||
<li><a href="#Group-Unlink">H5Gunlink</a> (NYI)
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Group-Iterate">H5Giterate</a>
|
||||
<li><a href="#Group-Move">H5Gmove</a> (NYI)
|
||||
<li><a href="#Group-Stat">H5Gstat</a>
|
||||
<li><a href="#Group-GetLinkval">H5Gget_linkval</a>
|
||||
</ul>
|
||||
</td></tr><tr><td colspan=5 align=right>
|
||||
<font size=-2>(NYI = Not yet implemented)</font>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
<p>
|
||||
A group associates names with objects and provides a mechanism
|
||||
for mapping a name to an object. Since all objects appear in at
|
||||
least one group (with the possible exception of the root object)
|
||||
and since objects can have names in more than one group, the set
|
||||
of all objects in an HDF5 file is a directed graph. The internal
|
||||
nodes (nodes with out-degree greater than zero) must be groups
|
||||
while the leaf nodes (nodes with out-degree zero) are either empty
|
||||
groups or objects of some other type. Exactly one object in every
|
||||
non-empty file is the root object. The root object always has a
|
||||
positive in-degree because it is pointed to by the file boot block.
|
||||
|
||||
<p>
|
||||
Every file identifier returned by <code>H5Fcreate</code> or
|
||||
<code>H5Fopen</code> maintains an independent current working group
|
||||
stack, the top item of which is the current working group. The
|
||||
stack can be manipulated with <code>H5Gset</code>, <code>H5Gpush</code>,
|
||||
and <code>H5Gpop</code>. The root object is the current working group
|
||||
if the stack is empty.
|
||||
|
||||
<p>
|
||||
An object name consists of one or more components separated from
|
||||
one another by slashes. An absolute name begins with a slash and the
|
||||
object is located by looking for the first component in the root
|
||||
object, then looking for the second component in the first object, etc.,
|
||||
until the entire name is traversed. A relative name does not begin
|
||||
with a slash and the traversal begins with the current working group.
|
||||
|
||||
<p>
|
||||
The library does not maintain the full absolute name of its current
|
||||
working group because (1) cycles in the graph can make the name length
|
||||
unbounded and (2) a group does not necessarily have a unique name. A
|
||||
more Unix-like hierarchical naming scheme can be implemented on top of
|
||||
the directed graph scheme by creating a ".." entry in each group that
|
||||
points to its single predecessor; a <code>getcwd</code> function would
|
||||
then be trivial.
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Group-Create">H5Gcreate</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Gcreate</code>(<em>hid_t</em> <code>loc_id</code>,
|
||||
<em>const char *</em><code>name</code>,
|
||||
<em>size_t</em> <code>size_hint</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Creates a new empty group and gives it a name.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Gcreate</code> creates a new group with the specified
|
||||
name at the specified location, <code>loc_id</code>.
|
||||
The location is identified by a file or group identifier.
|
||||
The name, <code>name</code>, must not already be taken by some
|
||||
other object and all parent groups must already exist.
|
||||
<p>
|
||||
<code>size_hint</code> is a hint for the number of bytes to
|
||||
reserve to store the names which will be eventually added to
|
||||
the new group. Passing a value of zero for <code>size_hint</code>
|
||||
is usually adequate since the library is able to dynamically
|
||||
resize the name heap, but a correct hint may result in better
|
||||
performance.
|
||||
If a non-positive value is supplied for size_hint,
|
||||
then a default size is chosen.
|
||||
<p>
|
||||
The return value is a group identifier for the open group.
|
||||
This group identifier should be closed by calling
|
||||
<code>H5Gclose()</code> when it is no longer needed.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>loc_id</code>
|
||||
<dd>The file or group identifier.
|
||||
<dt><em>const char *</em><code>name</code>
|
||||
<dd>The absolute or relative name of the new group.
|
||||
<dt><em>size_t</em> <code>size_hint</code>
|
||||
<dd>An optional parameter indicating the number of bytes
|
||||
to reserve for the names that will appear in the group.
|
||||
A conservative estimate could result in multiple
|
||||
system-level I/O requests to read the group name heap;
|
||||
a liberal estimate could result in a single large
|
||||
I/O request even when the group has just a few names.
|
||||
HDF5 stores each name with a null terminator.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a valid group identifier for the open group if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Group-Open">H5Gopen</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Gopen</code>(<em>hid_t</em> <code>loc_id</code>,
|
||||
<em>const char *</em><code>name</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Opens an existing group for modification and returns a group
|
||||
identifier for that group.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Gopen</code> opens an existing group with the specified name at
|
||||
the specified location, <code>loc_id</code>.
|
||||
The location is identified by a file or
|
||||
group identifier, and returns a group identifier for the group.
|
||||
The obtained group identifier should be released by calling
|
||||
<code>H5Gclose()</code> when it is no longer needed.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>loc_id</code>
|
||||
<dd>File or group identifier within which group is to be open.
|
||||
<dt><em>const char *</em> <code>name</code>
|
||||
<dd>Name of group to open.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a valid group identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Group-Set">H5Gset</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t </em><code>H5Gset</code> (<em>hid_t</em> <code>loc_id</code>,
|
||||
<em>const char *</em><code>name</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Sets the current working group within a file.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Gset</code> sets the group with the specified name
|
||||
to be the current working group for the file which contains it.
|
||||
This function sets the current working group by modifying the
|
||||
top element of the current working group stack or, if the
|
||||
stack is empty, by pushing a new element onto the stack.
|
||||
The initial current working group is the root group.
|
||||
<p>
|
||||
<code>loc_id</code> can be a file identifier or a group identifier.
|
||||
<p>
|
||||
<code>name</code> is an absolute or relative name and is resolved as follows. Each file identifier
|
||||
has a current working group, initially the root group of the
|
||||
file. Relative names do not begin with a slash and are relative
|
||||
to the specified group or to the current working group.
|
||||
Absolute names begin with a slash and are relative to the file's
|
||||
root group. For instance, the name <code>/Foo/Bar/Baz</code> is
|
||||
resolved by first looking up <code>Foo</code> in the root group;
|
||||
the name <code>Foo/Bar/Baz</code> is resolved by first looking
|
||||
up the name <code>Foo</code> in the current working group.
|
||||
<p>
|
||||
Each file identifier maintains its own notion of the current
|
||||
working group. If <code>loc_id</code> is a group identifier, the
|
||||
file identifier is derived from the group identifier.
|
||||
<p>
|
||||
If a single file is opened with multiple calls to <code>H5Fopen()</code>,
|
||||
which would return multiple file identifiers, then each
|
||||
identifier's current working group can be set independently
|
||||
of the other file identifiers for that file.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>loc_id</code>
|
||||
<dd>The file or group identifier.
|
||||
<dt><em>const char *</em><code>name</code>
|
||||
<dd>The name of the new current working group.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Group-Push">H5Gpush</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t </em><code>H5Gpush</code> (<em>hid_t</em> <code>loc_id</code>,
|
||||
<em>const char *</em><code>name</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Sets the current working group by pushing a
|
||||
new element onto the current working group stack.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd>Each file identifier maintains a stack of groups, the top group
|
||||
of which is the current working group. The stack initially
|
||||
contains only the root group. <code>H5Gpush</code> pushes a new group
|
||||
onto the stack, thus setting a new current working group.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>loc_id</code>
|
||||
<dd>File or group identifier.
|
||||
<dt><em>const char *</em><code>name</code>
|
||||
<dd>The name of the new current working group. The name may be
|
||||
an absolute or relative name.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Group-Pop">H5Gpop</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t </em><code>H5Gpop</code> (<em>hid_t</em> <code>loc_id</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Removes the top, or latest, entry from the working group stack,
|
||||
setting the current working group to the previous value.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Gpop</code> restores the previous current working group by
|
||||
popping an element from the current working group stack.
|
||||
An empty stack implies that the current working group is the root
|
||||
object. Attempting to pop an empty stack results in failure.
|
||||
<p>
|
||||
Each file identfier maintains its own notion of the current
|
||||
working group. That is, if a single file is opened with
|
||||
multiple calls to <code>H5Fopen()</code>, which returns multiple file
|
||||
handles, then each identfier's current working group can be
|
||||
set independently of the other file identfiers for that file.
|
||||
<p>
|
||||
If <code>loc_id</code> is a group identifier, it is used only to determine the
|
||||
file identifier for the stack from which to pop the top entry.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>loc_id</code>
|
||||
<dd>The file or group identifier.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Group-Close">H5Gclose</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t </em><code>H5Gclose</code>(<em>hid_t </em><code>group_id</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Closes the specified group.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Gclose</code> releases resources used by a group which was
|
||||
opened by <code>H5Gcreate()</code> or <code>H5Gopen()</code>.
|
||||
After closing a group, the <code>group_id</code> cannot be used again.
|
||||
<p>
|
||||
Failure to release a group with this call will result in resource leaks.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>group_id</code>
|
||||
<dd>Group identifier to release.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Group-Link">H5Glink</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5Glink</code>(<em>hid_t</em> <code>loc_id</code>,
|
||||
<em>H5G_link_t</em> <code>link_type</code>,
|
||||
<em>const char *</em><code>current_name</code>,
|
||||
<em>const char *</em><code>new_name</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Creates a link of the specified type from <code>new_name</code>
|
||||
to <code>current_name</code>.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Glink</code> creates a new name for an object that has some current
|
||||
name, possibly one of many names it currently has.
|
||||
<p>
|
||||
If <code>link_type</code> is <code>H5G_LINK_HARD</code>, then
|
||||
<code>current_name</code> must name an existing object and both
|
||||
names are interpreted relative to <code>loc_id</code>, which is
|
||||
either a file identifier or a group identifier.
|
||||
<p>
|
||||
If <code>link_type</code> is <code>H5G_LINK_SOFT</code>, then
|
||||
<code>current_name</code> can be anything and is interpreted at
|
||||
lookup time relative to the group which contains the final
|
||||
component of <code>new_name</code>. For instance, if
|
||||
<code>current_name</code> is <code>./foo</code>,
|
||||
<code>new_name</code> is <code>./x/y/bar</code>, and a request
|
||||
is made for <code>./x/y/bar</code>, then the actual object looked
|
||||
up is <code>./x/y/./foo</code>.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>loc_id</code>
|
||||
<dd>File or group identifier.
|
||||
<dt><em>H5G_link_t</em> <code>link_type</code>
|
||||
<dd>Link type.
|
||||
Possible values are <code>H5G_LINK_HARD</code> and <code>H5G_LINK_SOFT</code>.
|
||||
<dt><em>const char *</em> <code>current_name</code>
|
||||
<dd>Name of the existing object if link is a hard link.
|
||||
Can be anything for the soft link.
|
||||
<dt><em>const char *</em> <code>new_name</code>
|
||||
<dd>New name for the object.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Group-Unlink">H5Gunlink</a>
|
||||
|
||||
<strong>(Not implemented in this release.)</strong>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t </em><code>H5Gunlink</code>(<em>hid_t</em> <code>loc_id</code>,
|
||||
<em>const char *</em><code>name</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Removes the specified <code>name</code> from the group graph and
|
||||
decrements the link count for the object to which <code>name</code> points
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Gunlink</code> removes an association between a name and an object.
|
||||
Object headers keep track of how many hard links refer to the object;
|
||||
when the hard link count reaches zero, the object can be removed
|
||||
from the file. Objects which are open are not removed until all
|
||||
identifiers to the object are closed.
|
||||
<p>
|
||||
If the link count reaches zero, all file-space associated with
|
||||
the object will be reclaimed. If the object is open, the
|
||||
reclamation of the file space is delayed until all handles to the
|
||||
object are closed.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>loc_id</code>
|
||||
<dd>Identifier of the file containing the object.
|
||||
<dt><em>const char *</em> <code>name</code>
|
||||
<dd>Name of the object to unlink.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Group-Iterate">H5Giterate</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>int</em> <code>H5Giterate</code>(<em>hid_t</em> <code>loc_id</code>,
|
||||
<em>const char</em> <code>*name</code>,
|
||||
<em>int</em> <code>*idx</code>,
|
||||
<em>H5G_operator_t</em> <code>operator</code>,
|
||||
<em>void</em> <code>*operator_data</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Iterates an operation over the entries of a group.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Giterate</code> iterates over the members of
|
||||
<code>name</code> in the file or group specified with
|
||||
<code>loc_id</code>.
|
||||
For each object in the group, the <code>operator_data</code>
|
||||
and some additional information, specified below, are
|
||||
passed to the <code>operator</code> function.
|
||||
The iteration begins with the <code>idx</code> object in the
|
||||
group and the next element to be processed by the operator is
|
||||
returned in <code>idx</code>. If <code>idx</code>
|
||||
is NULL, then the iterator starts at the first group member;
|
||||
since no stopping point is returned in this case, the iterator
|
||||
cannot be restarted if one of the calls to its operator returns
|
||||
non-zero.
|
||||
<p>
|
||||
The prototype for <code>H5G_operator_t</code> is:
|
||||
<ul><dl>
|
||||
<dd><code>typedef</code> <em>herr_t *</em>(<code>H5G_operator_t</code>)(<em>hid_t</em> <code>group_id</code>,
|
||||
<em>const char *</em><code>member_name</code>, <em>void *</em><code>operator_data/*in,out*/</code>);
|
||||
</dl></ul>
|
||||
<dd>The operation receives the group identifier for the group being
|
||||
iterated over, <code>group_id</code>, the name of the current
|
||||
object within the group, <code>member_name</code>, and the
|
||||
pointer to the operator data passed in to <code>H5Giterate</code>,
|
||||
<code>operator_data</code>.
|
||||
<p>
|
||||
The return values from an operator are:
|
||||
<ul>
|
||||
<li>Zero causes the iterator to continue, returning
|
||||
zero when all group members 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 group member.
|
||||
<li>Negative causes the iterator to immediately return that value,
|
||||
indicating failure. The iterator can be restarted at the next
|
||||
group member.
|
||||
</ul>
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>loc_id</code>
|
||||
<dd>IN: File or group identifier.
|
||||
<dt><em>const char</em> <code>*name</code>
|
||||
<dd>IN: Group over which the iteration is performed.
|
||||
<dt><em>int</em> <code>*idx</code>
|
||||
<dd>IN/OUT: Location at which to begin the iteration.
|
||||
<dt><em>H5G_iterate_t</em> <code>operator</code>
|
||||
<dd>IN: Operation to be performed on an object at each step of
|
||||
the iteration.
|
||||
<dt><em>void</em> <code>*operator_data</code>
|
||||
<dd>IN/OUT: Data associated with the operation.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns the return value of the last operator if it was non-zero,
|
||||
or zero if all group members were processed.
|
||||
Otherwise, returns FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Group-Move">H5Gmove</a>
|
||||
|
||||
<strong>(Not implemented in this release.)</strong>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5Gmove</code>(<em>hid_t</em> <code>loc_id</code>,
|
||||
<em>const char</em> <code>*src</code>,
|
||||
<em>const char</em> <code>*dst</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Renames an object within an HDF5 file.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Gmove</code> renames an object within an HDF5 file.
|
||||
The original name, <code>src</code>, is unlinked from the
|
||||
group graph and the new name, <code>dst</code>, is inserted
|
||||
as an atomic operation. Both names are interpreted relative
|
||||
to <code>loc_id</code>, which is either a file or a group
|
||||
identifier.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>loc_id</code>
|
||||
<dd>File or group identifier.
|
||||
<dt><em>const char</em> <code>*src</code>
|
||||
<dd>Object's original name.
|
||||
<dt><em>const char</em> <code>*dst</code>
|
||||
<dd>Object's new name.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Group-Stat">H5Gstat</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5Gstat</code>(<em>hid_t</em> <code>loc_id</code>,
|
||||
<em>const char *</em><code>name</code>,
|
||||
<em>hbool_t</em> <code>follow_link</code>,
|
||||
<em>H5G_stat_t *</em><code>statbuf</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Returns information about an object.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Gstat</code> returns information about the
|
||||
specified object through the <code>statbuf</code> argument.
|
||||
<code>loc_id</code> (a file, group, or dataset identifier) and
|
||||
<code>name</code> together determine the object.
|
||||
If the object is a symbolic link and <code>follow_link</code> is
|
||||
zero (<code>0</code>), then the information returned is that for the link itself;
|
||||
otherwise the link is followed and information is returned about
|
||||
the object to which the link points.
|
||||
If <code>follow_link</code> is non-zero but the final symbolic link
|
||||
is dangling (does not point to anything), then an error is returned.
|
||||
The <code>statbuf</code> fields are undefined for an error.
|
||||
The existence of an object can be tested by calling this function
|
||||
with a null <code>statbuf</code>.
|
||||
<p>
|
||||
<code>H5Gstat()</code> fills in the following data structure:
|
||||
<pre>
|
||||
typedef struct H5G_stat_t {
|
||||
unsigned long fileno[2];
|
||||
unsigned long objno[2];
|
||||
unsigned nlink;
|
||||
H5G_type_t type;
|
||||
size_t linklen;
|
||||
} H5G_stat_t
|
||||
</pre>
|
||||
The <code>fileno</code> and <code>objno</code> fields contain
|
||||
four values which uniquely itentify an object among those
|
||||
HDF5 files which are open: if all four values are the same
|
||||
between two objects, then the two objects are the same
|
||||
(provided both files are still open).
|
||||
The <code>nlink</code> field is the number of hard links to
|
||||
the object or zero when information is being returned about a
|
||||
symbolic link (symbolic links do not have hard links but
|
||||
all other objects always have at least one).
|
||||
The <code>type</code> field contains the type of the object,
|
||||
one of <code>H5G_GROUP</code>, <code>H5G_DATASET</code>,
|
||||
or <code>H5G_LINK</code>.
|
||||
If information is being returned about a symbolic link then
|
||||
<code>linklen</code> will be the length of the link value
|
||||
(the name of the pointed-to object with the null terminator);
|
||||
otherwise <code>linklen</code> will be zero.
|
||||
Other fields may be added to this structure in the future.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>loc_id</code>
|
||||
<dd>IN: File, group, or dataset identifier.
|
||||
<dt><em>const char</em> <code>*name</code>
|
||||
<dd>IN: Name of the object for which status is being sought.
|
||||
<dt><em>hbool_t</em> <code>follow_link</code>
|
||||
<dd>IN: Link flag.
|
||||
<dt><em>H5G_stat_t</em> <code>*statbuf</code>
|
||||
<dd>OUT: Buffer in which to return information about the object.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd> Returns SUCCEED (0) with the fields of STATBUF (if non-null) initialized.
|
||||
Otherwise returns FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Group-GetLinkval">H5Gget_linkval</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5Gget_linkval</code>(<em>hid_t</em> <code>loc_id</code>,
|
||||
<em>const char *</em><code>name</code>,
|
||||
<em>size_t</em> <code>size</code>,
|
||||
<em>char *</em><code>value</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Returns link value.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Gget_linkval</code> returns <code>size</code>
|
||||
characters of the link value through the <code>value</code>
|
||||
argument if <code>loc_id</code> (a file or group identifier)
|
||||
and <code>name</code> specify a symbolic link.
|
||||
If <code>size</code> is smaller than the link value, then
|
||||
<code>value</code> will not be null terminated.
|
||||
<p>
|
||||
This function fails if the specified object is not a symbolic link.
|
||||
The presence of a symbolic link can be tested by passing zero for
|
||||
<code>size</code> and NULL for <code>value</code>.
|
||||
<p>
|
||||
Use <code>H5Gstat()</code> to get the size of a link value.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>loc_id</code>
|
||||
<dd>IN: Identifier of the file or group .
|
||||
<dt><em>const char *</em><code>name</code>
|
||||
<dd>IN: Name of the object whose link value is to be checked.
|
||||
<dt><em>size_t</em> <code>size</code>
|
||||
<dd>IN: Maximum number of characters of <code>value</code>
|
||||
to be returned.
|
||||
<dt><em>char *</em><code>value</code>
|
||||
<dd>OUT: Link value.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0), with the link value in <code>value</code>,
|
||||
if successful.
|
||||
Otherwise returns FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<center>
|
||||
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
||||
<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>
|
||||
H5G
|
||||
<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>
|
||||
1727
doc/html/RM_H5P.html
Normal file
1727
doc/html/RM_H5P.html
Normal file
File diff suppressed because it is too large
Load Diff
529
doc/html/RM_H5S.html
Normal file
529
doc/html/RM_H5S.html
Normal file
@ -0,0 +1,529 @@
|
||||
<html>
|
||||
<head><title>
|
||||
HDF5/H5S Draft API Specification
|
||||
</title></head>
|
||||
|
||||
<body>
|
||||
|
||||
<hr>
|
||||
<center>
|
||||
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
||||
<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_H5P.html">H5P</a>
|
||||
H5S
|
||||
<a href="RM_H5T.html">H5T</a>
|
||||
<a href="RM_H5Z.html">H5Z</a>
|
||||
<a href="Glossary.html">Glossary</a>
|
||||
</center>
|
||||
<hr>
|
||||
|
||||
<center>
|
||||
<h1>H5S: Dataspace Interface</h1>
|
||||
</center>
|
||||
|
||||
<h2>Dataspace Object API Functions</h2>
|
||||
|
||||
These functions create and manipulate the dataspace in which to store the
|
||||
elements of a dataset.
|
||||
|
||||
<table border=0>
|
||||
<tr><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Dataspace-Create">H5Screate</a>
|
||||
<li><a href="#Dataspace-CreateSimple">H5Screate_simple</a>
|
||||
<li><a href="#Dataspace-Copy">H5Scopy</a>
|
||||
<li><a href="#Dataspace-SelectNpoints">H5Sselect_npoints</a>
|
||||
<li><a href="#Dataspace-SelectElements">H5Sselect_elements</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Dataspace-ExtentNpoints">H5Sextent_npoints</a>
|
||||
<li><a href="#Dataspace-ExtentNdims">H5Sextent_ndims</a>
|
||||
<li><a href="#Dataspace-ExtentDims">H5Sextent_dims</a>
|
||||
<li><a href="#Dataspace-GetClass">H5Sget_class</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Dataspace-SetExtentSimple">H5Sset_extent_simple</a>
|
||||
<li><a href="#Dataspace-IsSimple">H5Sis_simple</a>
|
||||
<li><a href="#Dataspace-SelectHyperslab">H5Sselect_hyperslab</a>
|
||||
<li><a href="#Dataspace-Close">H5Sclose</a>
|
||||
</ul>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataspace-Create">H5Screate</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t</em> <code>H5Screate</code>(<em>H5S_class_t</em> <code>type</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Creates a new dataspace of a specified type.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Screate</code> creates a new dataspace of a particular
|
||||
<code>type</code>.
|
||||
The types currently supported are <code>H5S_SCALAR</code>,
|
||||
<code>H5S_SIMPLE</code>, and <code>H5S_NONE</code>;
|
||||
others are planned to be added later. The <code>H5S_NONE</code>
|
||||
dataspace can only hold a selection, not an extent.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>H5S_class_t</em> <code>type</code>
|
||||
<dd>The type of dataspace to be created.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a dataspace identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataspace-CreateSimple">H5Screate_simple</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t</em> <code>H5Screate_simple</code>(<em>int</em> <code>rank</code>,
|
||||
<em>const hsize_t *</em> <code>dims</code>,
|
||||
<em>const hsize_t *</em> <code>maxdims</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Creates a new simple data space and opens it for access.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Screate_simple</code> creates a new simple data space
|
||||
and opens it for access. The <code>rank</code> is the number of
|
||||
dimensions used in the dataspace.
|
||||
The <code>dims</code> argument is the size
|
||||
of the simple dataset and the <code>maxdims</code> argument is
|
||||
the upper limit on the size of the dataset. <code>maxdims</code>
|
||||
may be the null pointer in which case the upper limit is the
|
||||
same as <code>dims</code>. If an element of <code>maxdims</code>
|
||||
is zero then the corresponding dimension is unlimited, otherwise
|
||||
no element of <code>maxdims</code> should be smaller than the
|
||||
corresponding element of <code>dims</code>. The dataspace
|
||||
identifier returned from this function should be released with
|
||||
<code>H5Sclose</code> or resource leaks will occur.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>int</em> <code>rank</code>
|
||||
<dd>Number of dimensions of dataspace.
|
||||
<dt><em>const hsize_t *</em> <code>dims</code>
|
||||
<dd>An array of the size of each dimension.
|
||||
<dt><em>const hsize_t *</em> <code>maxdims</code>
|
||||
<dd>An array of the maximum size of each dimension.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a dataspace identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataspace-Copy">H5Scopy</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Scopy</code>(<em>hid_t </em><code>space_id</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Creates an exact copy of a dataspace.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Scopy</code> creates a new dataspace which is an exact
|
||||
copy of the dataspace identified by <code>space_id</code>.
|
||||
The dataspace identifier returned from this function should be
|
||||
released with <code>H5Sclose</code> or resource leaks will occur.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>space_id</code>
|
||||
<dd>Identifier of dataspace to copy.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a dataspace identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataspace-SelectElements">H5Sselect_elements</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5Sselect_elements</code>(<em>hid_t </em><code>space_id</code>,
|
||||
<em>dh5s_selopt_t</em> <code>op</code>,
|
||||
<em>const size_t</em> <code>num_elements</code>,
|
||||
<em>const hssize_t *</em><code>coord</code>[ ]
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Selects array elements to be included in the selection for a dataspace.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Sselect_elements</code> selects array elements to be
|
||||
included in the selection for the <code>space_id</code>
|
||||
dataspace. The number of elements selected must be set with
|
||||
the <code>num_elements</code>. The <code>coord</code> array
|
||||
is a two-dimensional array of size <em>dataspace rank</em>
|
||||
by <code>num_elements</code> (ie. a list of coordinates in
|
||||
the array). The order of the element coordinates in the
|
||||
<code>coord</code> array also specifies the order in which
|
||||
the array elements are iterated through when I/O is performed.
|
||||
Duplicate coordinate locations are not checked for.
|
||||
<P>
|
||||
The selection operator <code>op</code> determines how the
|
||||
new selection is to be combined with the previously existing
|
||||
selection for the dataspace. Currently, only the
|
||||
<code>H5S_SELECT_SET</code> operator is supported, which
|
||||
replaces the existing selection with the parameters from
|
||||
this call. When operators other than <code>H5S_SELECT_SET</code>
|
||||
are used to combine a new selection with an existing selection,
|
||||
the selection ordering is reset to 'C' array ordering.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>space_id</code>
|
||||
<dd>Identifier of the dataspace.
|
||||
<dt><em>dh5s_selopt_t</em> <code>op</code>
|
||||
<dd>operator specifying how the new selection is to be
|
||||
combined with the existing selection for the dataspace.
|
||||
<dt><em>const size_t</em> <code>num_elements</code>
|
||||
<dd>Number of elements to be selected.
|
||||
<dt><em>const hssize_t *</em><code>coord</code>[ ]
|
||||
<dd>A 2-dimensional array specifying the coordinates of the
|
||||
elements being selected.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataspace-ExtentNpoints">H5Sextent_npoints</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hsize_t</em> <code>H5Sextent_npoints</code>(<em>hid_t </em><code>space_id</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Determines the number of elements in a dataspace.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Sextent_npoints</code> determines the number of elements
|
||||
in a dataspace. For example, a simple 3-dimensional dataspace
|
||||
with dimensions 2, 3, and 4 would have 24 elements.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>space_id</code>
|
||||
<dd>ID of the dataspace object to query
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns the number of elements in the dataspace if successful;
|
||||
otherwise returns 0.
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataspace-SelectNpoints">H5Sselect_npoints</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hsize_t</em> <code>H5Sselect_npoints</code>(<em>hid_t</em> <code>space_id</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Determines the number of elements in a dataspace.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Sselect_npoints</code> determines the number of elements
|
||||
in the current selection of a dataspace.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>space_id</code>
|
||||
<dd>Dataspace identifier.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a dataspace identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataspace-ExtentNdims">H5Sextent_ndims</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>int</em> <code>H5Sextent_ndims</code>(<em>hid_t</em> <code>space_id</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Determines the dimensionality of a dataspace.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Sextent_ndims</code> determines the dimensionality (or rank)
|
||||
of a dataspace.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>space_id</code>
|
||||
<dd>Identifier of the dataspace
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns the number of dimensions in the dataspace if successful;
|
||||
otherwise FAIL (-1)
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataspace-ExtentDims">H5Sextent_dims</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>int</em> <code>H5Sextent_dims</code>(<em>hid_t</em> <code>space_id</code>,
|
||||
<em>hsize_t *</em><code>dims</code>,
|
||||
<em>hsize_t *</em><code>maxdims</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Retrieves dataspace dimension size and maximum size.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Sextent_dims</code> returns the size and maximum sizes
|
||||
of each dimension of a dataspace through the <code>dims</code>
|
||||
and <code>maxdims</code> parameters.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>space_id</code>
|
||||
<dd>IN: Identifier of the dataspace object to query
|
||||
<dt><em>hsize_t *</em><code>dims</code>
|
||||
<dd>OUT: Pointer to array to store the size of each dimension.
|
||||
<dt><em>hsize_t *</em><code>maxdims</code>
|
||||
<dd>OUT: Pointer to array to store the maximum size of each dimension.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns the number of dimensions in the dataspace if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataspace-SetExtentSimple">H5Sset_extent_simple</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5S_set_extent_simple</code>(<em>hid_t</em> <code>space_id</code>,
|
||||
<em>int</em> <code>rank</code>,
|
||||
<em>const hsize_t *</em><code>current_size</code>,
|
||||
<em>const hsize_t *</em><code>maximum_size</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Sets or resets the size of an existing dataspace.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5S_set_extent_simple</code> sets or resets the size of
|
||||
an existing dataspace.
|
||||
<p>
|
||||
<code>rank</code> is the dimensionality, or number of
|
||||
dimensions, of the dataspace.
|
||||
<p>
|
||||
<code>current_size</code> is an array of size <code>rank</code>
|
||||
which contains the new size of each dimension in the dataspace.
|
||||
<code>maximum_size</code> is an array of size <code>rank</code>
|
||||
which contains the maximum size of each dimension in the
|
||||
dataspace.
|
||||
<p>
|
||||
Any previous extent is removed from the dataspace, the dataspace
|
||||
type is set to <code>H5S_SIMPLE</code>, and the extent is set as
|
||||
specified.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>space_id</code>
|
||||
<dd>Dataspace identifier.
|
||||
<dt><em>int</em> <code>rank</code>
|
||||
<dd>Rank, or dimensionality, of the dataspace.
|
||||
<dt><em>const hsize_t *</em><code>current_size</code>
|
||||
<dd>Array containing current size of dataspace.
|
||||
<dt><em>const hsize_t *</em><code>maximum_size</code>
|
||||
<dd>Array containing maximum size of dataspace.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a dataspace identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataspace-IsSimple">H5Sis_simple</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hbool_t </em><code>H5Sis_simple</code>(<em>hid_t </em><code>space_id</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Determines whether a dataspace is a simple dataspace.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Sis_simple</code> determines whether a dataspace is
|
||||
a simple dataspace. [Currently, all dataspace objects are simple
|
||||
dataspaces, complex dataspace support will be added in the future]
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>space_id</code>
|
||||
<dd>Identifier of the dataspace to query
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns TRUE or FALSE if Successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataspace-GetClass">H5Sget_class</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>H5S_class_t</em> <code>H5Sget_class</code>(<em>hid_t</em> <code>space_id</code>)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Determine the current class of a dataspace.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Sget_class</code> queries a dataspace to determine the
|
||||
current class of a dataspace.
|
||||
<p>
|
||||
The function returns a class name, one of the following:
|
||||
<code>H5S_SCALAR</code>,
|
||||
<code>H5S_SIMPLE</code>, or
|
||||
<code>H5S_NONE</code>.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>space_id</code>
|
||||
<dd>Dataspace identifier.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a dataspace class name if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataspace-SelectHyperslab">H5Sselect_hyperslab</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5Sselect_hyperslab</code>(<em>hid_t</em> <code>space_id</code>,
|
||||
<em>h5s_selopt_t</em><code>op</code>,
|
||||
<em>const hssize_t *</em><code>start</code>,
|
||||
<em>const hsize_t *</em><code>stride</code>
|
||||
<em>const hsize_t *</em><code>count</code>,
|
||||
<em>const hsize_t *</em><code>block</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Selects a hyperslab region to add to the current selected region.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Sselect_hyperslab</code> selects a hyperslab region
|
||||
to add to the current selected region for the dataspace
|
||||
specified by <code>space_id</code>.
|
||||
<p>
|
||||
The <code>start</code>, <code>stride</code>, <code>count</code>,
|
||||
and <code>block</code> arrays must be the same size as the rank
|
||||
of the dataspace.
|
||||
<p>
|
||||
The selection operator <code>op</code> determines how the new
|
||||
selection is to be combined with the already existing selection
|
||||
for the dataspace.
|
||||
<p>
|
||||
Currently, only the <code>H5S_SELECT_SET</code> operator is
|
||||
supported; it replaces the existing selection with the
|
||||
parameters from this call. Overlapping blocks are not
|
||||
supported with the <code>H5S_SELECT_SET</code> operator.
|
||||
<P>
|
||||
The <code>start</code> array determines the starting coordinates
|
||||
of the hyperslab
|
||||
to select.
|
||||
<p>
|
||||
The <code>stride</code> array chooses array locations
|
||||
from the dataspace
|
||||
with each value in the <code>stride</code> array determining how
|
||||
many elements to move
|
||||
in each dimension. Setting a value in the <code>stride</code>
|
||||
array to 1 moves to
|
||||
each element in that dimension of the dataspace; setting a value of 2 in a
|
||||
location in the <code>stride</code> array moves to every other
|
||||
element in that
|
||||
dimension of the dataspace. In other words, the <code>stride</code>
|
||||
determines the
|
||||
number of elements to move from the <code>start</code> location
|
||||
in each dimension.
|
||||
Stride values of 0 are not allowed. If the <code>stride</code>
|
||||
parameter is <code>NULL</code>,
|
||||
a contiguous hyperslab is selected (as if each value in the
|
||||
<code>stride</code> array
|
||||
was set to all 1's).
|
||||
<p>
|
||||
The <code>count</code> array determines how many blocks to
|
||||
select from the dataspace, in each dimension.
|
||||
<p>
|
||||
The <code>block</code> array determines
|
||||
the size of the element block selected from the dataspace.
|
||||
If the <code>block</code>
|
||||
parameter is set to <code>NULL</code>, the block size defaults
|
||||
to a single element
|
||||
in each dimension (as if the <code>block</code> array was set to all 1's).
|
||||
<P>
|
||||
For example, in a 2-dimensional dataspace, setting
|
||||
<code>start</code> to [1,1],
|
||||
<code>stride</code> to [4,4], <code>count</code> to [3,7], and
|
||||
<code>block</code> to [2,2] selects
|
||||
21 2x2 blocks of array elements starting with location (1,1) and selecting
|
||||
blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc.
|
||||
<P>
|
||||
Regions selected with this function call default to C order iteration when
|
||||
I/O is performed.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>space_id</code>
|
||||
<dd>IN: Identifier of dataspace selection to modify
|
||||
<dt><em>H5S_seloper_t</em> <code>op</code>
|
||||
<dd>IN: Operation to perform on current selection.
|
||||
<dt><em>const hssize_t *</em><code>start</code>
|
||||
<dd>IN: Offset of start of hyperslab
|
||||
<dt><em>const hsize_t *</em><code>count</code>
|
||||
<dd>IN: Number of blocks included in hyperslab.
|
||||
<dt><em>const hsize_t *</em><code>stride</code>
|
||||
<dd>IN: Hyperslab stride.
|
||||
<dt><em>const hsize_t *</em><code>block</code>
|
||||
<dd>IN: Size of block in hyperslab.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataspace-Close">H5Sclose</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t </em><code>H5Sclose</code>(<em>hid_t </em><code>space_id</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd>Releases and terminates access to a dataspace.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Sclose</code> releases a dataspace.
|
||||
Further access through the dataspace identifier is illegal.
|
||||
Failure to release a dataspace with this call will
|
||||
result in resource leaks.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>space_id</code>
|
||||
<dd>Identifier of dataspace to release.
|
||||
</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>
|
||||
<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_H5P.html">H5P</a>
|
||||
H5S
|
||||
<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>
|
||||
1755
doc/html/RM_H5T.html
Normal file
1755
doc/html/RM_H5T.html
Normal file
File diff suppressed because it is too large
Load Diff
93
doc/html/RM_H5Z.html
Normal file
93
doc/html/RM_H5Z.html
Normal file
@ -0,0 +1,93 @@
|
||||
<html>
|
||||
<head><title>
|
||||
HDF5/H5Z Draft API Specification
|
||||
</title></head>
|
||||
|
||||
<body>
|
||||
|
||||
<center>
|
||||
<h1>H5Z: Compression Interface</h1>
|
||||
</center>
|
||||
|
||||
<h2>Compression API Functions</h2>
|
||||
|
||||
This function enable the user to configure a new compression
|
||||
method for the local environment.
|
||||
|
||||
<table border=0>
|
||||
<tr><td valign=top>
|
||||
<ul>
|
||||
<li><a href="#Compression-Register">H5Zregister</a>
|
||||
</ul>
|
||||
</td><td> </td><td valign=top>
|
||||
<ul>
|
||||
|
||||
</ul>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
<p>
|
||||
HDF5 supports compression of raw data by compression methods
|
||||
built into the library or defined by an application.
|
||||
A compression method is associated with a dataset when the dataset is
|
||||
created and is applied independently to each storage chunk of the dataset.
|
||||
The dataset must use the <code>H5D_CHUNKED</code> storage layout.
|
||||
<p>
|
||||
The HDF5 library does not support compression for contiguous datasets
|
||||
because of the difficulty of implementing random access for partial I/O.
|
||||
Compact dataset compression is not supported because it would not produce
|
||||
significant results.
|
||||
<p>
|
||||
See <a href="../UG/Compression.html"><cite>Compression</cite></a> in the
|
||||
<cite>HDF5 User's Guide</cite> for further information.
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Compression-Register">H5Zregister</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>herr_t</em> <code>H5Zregister</code>(<em>H5Z_method_t</em> <code>method</code>,
|
||||
<em>const char *</em><code>name</code>,
|
||||
<em>H5Z_func_t</em><code>cfunc</code>,
|
||||
<em>H5Z_func_t</em> <code>ufunc</code>
|
||||
)
|
||||
<dt><strong>Purpose:</strong>
|
||||
<dd> Registers new compression and uncompression functions for a
|
||||
method specified by a method number.
|
||||
<dt><strong>Description:</strong>
|
||||
<dd><code>H5Zregister</code> registers new compression and uncompression
|
||||
functions for a method specified by a method number, <code>method</code>.
|
||||
<code>name</code> is used for debugging and may be the null pointer.
|
||||
Either or both of <code>cfunc</code> (the compression function) and
|
||||
<code>ufunc</code> (the uncompression method) may be null pointers.
|
||||
<p>
|
||||
The statistics associated with a method number are not reset
|
||||
by this function; they accumulate over the life of the library.
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>H5Z_method_t</em> <code>method</code>
|
||||
<dd>Number specifying compression method.
|
||||
<dt><em>const char *</em><code>name</code>
|
||||
<dd>Name associated with the method number.
|
||||
<dt><em>H5Z_func_t</em> <code>cfunc</code>
|
||||
<dd>Compression method.
|
||||
<dt><em>H5Z_func_t</em> <code>ufunc</code>
|
||||
<dd>Uncompression method.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
|
||||
<address>
|
||||
<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a>
|
||||
<br>
|
||||
<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a>
|
||||
|
||||
<br>
|
||||
Last modified: 8 July 1998
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Loading…
x
Reference in New Issue
Block a user