diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 1998-07-15 04:51:50 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 1998-07-15 04:51:50 (GMT) |
| commit | c8e75d27b018deb862171a153dd640455dbe26fb (patch) | |
| tree | 0056588a00653bd4f6fff761482837baa9396a11 | |
| parent | 3e213ecf064638989c816ba3a10b3b6c6307fdad (diff) | |
| download | hdf5-c8e75d27b018deb862171a153dd640455dbe26fb.zip hdf5-c8e75d27b018deb862171a153dd640455dbe26fb.tar.gz hdf5-c8e75d27b018deb862171a153dd640455dbe26fb.tar.bz2 | |
[svn-r503] HDF5 Reference Manual
Updated for Alpha2.
| -rw-r--r-- | doc/html/Glossary.html | 99 | ||||
| -rw-r--r-- | doc/html/RM_H5.html | 220 | ||||
| -rw-r--r-- | doc/html/RM_H5A.html | 501 | ||||
| -rw-r--r-- | doc/html/RM_H5D.html | 405 | ||||
| -rw-r--r-- | doc/html/RM_H5E.html | 361 | ||||
| -rw-r--r-- | doc/html/RM_H5F.html | 300 | ||||
| -rw-r--r-- | doc/html/RM_H5Front.html | 72 | ||||
| -rw-r--r-- | doc/html/RM_H5G.html | 639 | ||||
| -rw-r--r-- | doc/html/RM_H5P.html | 1727 | ||||
| -rw-r--r-- | doc/html/RM_H5S.html | 529 | ||||
| -rw-r--r-- | doc/html/RM_H5T.html | 1755 | ||||
| -rw-r--r-- | doc/html/RM_H5Z.html | 93 |
12 files changed, 6701 insertions, 0 deletions
diff --git a/doc/html/Glossary.html b/doc/html/Glossary.html new file mode 100644 index 0000000..31b2db6 --- /dev/null +++ b/doc/html/Glossary.html @@ -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> diff --git a/doc/html/RM_H5.html b/doc/html/RM_H5.html new file mode 100644 index 0000000..8b2ab70 --- /dev/null +++ b/doc/html/RM_H5.html @@ -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> diff --git a/doc/html/RM_H5A.html b/doc/html/RM_H5A.html new file mode 100644 index 0000000..0c236da --- /dev/null +++ b/doc/html/RM_H5A.html @@ -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> diff --git a/doc/html/RM_H5D.html b/doc/html/RM_H5D.html new file mode 100644 index 0000000..7b5263d --- /dev/null +++ b/doc/html/RM_H5D.html @@ -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> diff --git a/doc/html/RM_H5E.html b/doc/html/RM_H5E.html new file mode 100644 index 0000000..e3c8177 --- /dev/null +++ b/doc/html/RM_H5E.html @@ -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> diff --git a/doc/html/RM_H5F.html b/doc/html/RM_H5F.html new file mode 100644 index 0000000..926d7ba --- /dev/null +++ b/doc/html/RM_H5F.html @@ -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> diff --git a/doc/html/RM_H5Front.html b/doc/html/RM_H5Front.html new file mode 100644 index 0000000..9c4e1ce --- /dev/null +++ b/doc/html/RM_H5Front.html @@ -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> diff --git a/doc/html/RM_H5G.html b/doc/html/RM_H5G.html new file mode 100644 index 0000000..55b7d5b --- /dev/null +++ b/doc/html/RM_H5G.html @@ -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> diff --git a/doc/html/RM_H5P.html b/doc/html/RM_H5P.html new file mode 100644 index 0000000..5329ec1 --- /dev/null +++ b/doc/html/RM_H5P.html @@ -0,0 +1,1727 @@ +<html> +<head><title> +HDF5/H5P 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> +H5P +<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>H5P: Property List Interface</h1> +</center> + +<h2>Property List API Functions</h2> + +These functions manipulate property list objects to allow objects which require +many different parameters to be easily manipulated. + +<dir> +<table border=0> +<tr><td valign=top> + + <i>General Property List Operations</i> + <ul> + <li><a href="#Property-Create">H5Pcreate</a> + <li><a href="#Property-GetClass">H5Pget_class</a> + <li><a href="#Property-Copy">H5Pcopy</a> + <li><a href="#Property-Close">H5Pclose</a> + </ul> + + <p><i>File Creation Properties</i> + <ul> + <li><a href="#Property-GetVersion">H5Pget_version</a> + <li><a href="#Property-SetUserblock">H5Pset_userblock</a> + <li><a href="#Property-GetUserblock">H5Pget_userblock</a> + <li><a href="#Property-SetSizes">H5Pset_sizes</a> + <li><a href="#Property-GetSizes">H5Pget_sizes</a> + <li><a href="#Property-SetSymK">H5Pset_sym_k</a> + <li><a href="#Property-GetSymK">H5Pget_sym_k</a> + <li><a href="#Property-SetIstoreK">H5Pset_istore_k</a> + <li><a href="#Property-GetIstoreK">H5Pget_istore_k</a> + </ul> + +</td><td> </td><td valign=top> + + <i>File Access Properties</i> + <ul> + <li><a href="#Property-GetDriver">H5Pget_driver</a> + <li><a href="#Property-SetStdio">H5Pset_stdio</a> + <li><a href="#Property-GetStdio">H5Pget_stdio</a> + <li><a href="#Property-SetSec2">H5Pset_sec2</a> + <li><a href="#Property-GetSec2">H5Pget_sec2</a> + <li><a href="#Property-SetAlignment">H5Pset_alignment</a> + <li><a href="#Property-GetAlignment">H5Pget_alignment</a> + <li><a href="#Property-SetCore">H5Pset_core</a> + <li><a href="#Property-GetCore">H5Pget_core</a> + <li><a href="#Property-SetMPI">H5Pset_mpi</a> || + <li><a href="#Property-GetMPI">H5Pget_mpi</a> || + <li><a href="#Property-SetFamily">H5Pset_family</a> + <li><a href="#Property-GetFamily">H5Pget_family</a> + <li><a href="#Property-SetCache">H5Pset_cache</a> + <li><a href="#Property-GetCache">H5Pget_cache</a> + <li><a href="#Property-SetSplit">H5Pset_split</a> + <li><a href="#Property-GetSplit">H5Pget_split</a> + </ul> + +</td><td> </td><td valign=top> + + <i>Dataset Creation Properties</i> + <ul> + <li><a href="#Property-SetLayout">H5Pset_layout</a> + <li><a href="#Property-GetLayout">H5Pget_layout</a> + <li><a href="#Property-SetChunk">H5Pset_chunk</a> + <li><a href="#Property-GetChunk">H5Pget_chunk</a> + <li><a href="#Property-SetDeflate">H5Pset_deflate</a> + <li><a href="#Property-GetDeflate">H5Pget_deflate</a> + <li><a href="#Property-SetCompression">H5Pset_compression</a> + <li><a href="#Property-GetCompression">H5Pget_compression</a> + <li><a href="#Property-SetExternal">H5Pset_external</a> + <li><a href="#Property-GetExternalCount">H5Pget_external_count</a> + <li><a href="#Property-GetExternal">H5Pget_external</a> + </ul> + + <p><i>Dataset Memory and Transfer Properties</i> + <ul> + <li><a href="#Property-SetBuffer">H5Pset_buffer</a> + <li><a href="#Property-GetBuffer">H5Pget_buffer</a> + <li><a href="#Property-SetPreserve">H5Pset_preserve</a> + <li><a href="#Property-GetPreserve">H5Pget_preserve</a> + <li><a href="#Property-SetXfer">H5Pset_xfer</a> || + <li><a href="#Property-GetXfer">H5Pget_xfer</a> || + </ul> + +</td></tr> + +<tr><td colspan=5 align=right> +<br> +|| <i>Available only in the parallel HDF5 library.</i> +</td></tr> + +</table> +</dir + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-Create">H5Pcreate</a> + <dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Pcreate</code>(<em>H5P_class_t</em> <code>type</code> + ) + <dt><strong>Purpose:</strong> + <dd>Creates a new property as an instance of a property list class. + <dt><strong>Description:</strong> + <dd><code>H5Pcreate</code> creates a new property as an instance of some + property list class. The new property list is initialized + with default values for the specified class. The classes are: + <dl> + <dt><code>H5P_FILE_CREATE</code> + <dd>Properties for file creation. + See <a href="Files.html">Files</a> + in the <cite>HDF User's Guide</cite> + for details about the file creation properties. + <dt><code>H5P_FILE_ACCESS</code> + <dd>Properties for file access. + See <a href="Files.html">Files</a> + in the <cite>HDF User's Guide</cite> + for details about the file creation properties. + <dt><code>H5P_DATASET_CREATE</code> + <dd>Properties for dataset creation. + See <a href="Datasets.html">Datasets</a> + in the <cite>HDF User's Guide</cite> + for details about dataset creation properties. + <dt><code>H5P_DATASET_XFER</code> + <dd>Properties for raw data transfer. + See <a href="Datasets.html">Datasets</a> + in the <cite>HDF User's Guide</cite> + for details about raw data transfer properties. + </dl> + <dt><strong>Parameters:</strong> + <dl> + <dt><em>H5P_class_t</em> <code>type</code> + <dd>IN: The type of property list to create. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a property list identifier (<code>plist</code>) if successful; + otherwise Fail (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-Close">H5Pclose</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pclose</code>(<em>hid_t</em> <code>plist</code> + ) + <dt><strong>Purpose:</strong> + <dd>Terminates access to a property list. + <dt><strong>Description:</strong> + <dd><code>H5Pclose</code> terminates access to a property list. + All property lists should be closed when the application is + finished accessing them. + This frees resources used by the property list. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the property list to terminate access to. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetClass">H5Pget_class</a> + <dt><strong>Signature:</strong> + <dd><em>H5P_class_t </em><code>H5Pget_class</code>(<em>hid_t</em> <code>plist</code> + ) + <dt><strong>Purpose:</strong> + <dd>Returns the property list class for a property list. + <dt><strong>Description:</strong> + <dd><code>H5Pget_class</code> returns the property list class for the + property list identied by the <code>plist</code> parameter. + Valid property list classes are defined in the description of + <code>H5Pcreate()</code>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of property list to query. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a property list class if successful. + Otherwise returns H5P_NO_CLASS (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-Copy">H5Pcopy</a> + <dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Pcopy</code>(<em>hid_t</em> <code>plist</code> + ) + <dt><strong>Purpose:</strong> + <dd>Copies an existing property list to create a new property list. + <dt><strong>Description:</strong> + <dd><code>H5Pcopy</code> copies an existing property list to create + a new property list. + The new property list has the same properties and values + as the original property list. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of property list to duplicate. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a property list identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetVersion">H5Pget_version</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_version</code>(<em>hid_t</em> <code>plist</code>, + <em>int *</em> <code>boot</code>, + <em>int *</em> <code>freelist</code>, + <em>int *</em> <code>stab</code>, + <em>int *</em> <code>shhdr</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the version information of various objects for + a file creation property list. + <dt><strong>Description:</strong> + <dd><code>H5Pget_version</code> retrieves the version information of various objects + for a file creation property list. Any pointer parameters which are + passed as NULL are not queried. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the file creation property list. + <dt><em>int *</em> <code>boot</code> + <dd>OUT: Pointer to location to return boot block version number. + <dt><em>int *</em> <code>freelist</code> + <dd>OUT: Pointer to location to return global freelist version number. + <dt><em>int *</em> <code>stab</code> + <dd>OUT: Pointer to location to return symbol table version number. + <dt><em>int *</em> <code>shhdr</code> + <dd>OUT: Pointer to location to return shared object header version number. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetUserblock">H5Pset_userblock</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_userblock</code>(<em>hid_t</em> <code>plist</code>, + <em>hsize_t</em> <code>size</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets user block size. + <dt><strong>Description:</strong> + <dd><code>H5Pset_userblock</code> sets the user block size of a + file creation property list. + The default user block size is 0; it may be set to any + power of 2 equal to 512 or greater (512, 1024, 2048, etc.). + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of property list to modify. + <dt><em>hsize_t</em> <code>size</code> + <dd>IN: Size of the user-block in bytes. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetUserblock">H5Pget_userblock</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_userblock</code>(<em>hid_t</em> <code>plist</code>, + <em>hsize_t *</em> <code>size</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the size of a user block. + <dt><strong>Description:</strong> + <dd><code>H5Pget_userblock</code> retrieves the size of a user block + in a file creation property list. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for property list to query. + <dt><em>hsize_t *</em> <code>size</code> + <dd>OUT: Pointer to location to return user-block size. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetSizes">H5Pset_sizes</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_sizes</code>(<em>hid_t</em> <code>plist</code>, + <em>size_t</em> <code>sizeof_addr</code>, + <em>size_t</em> <code>sizeof_size</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the byte size of the offsets and lengths used to address objects + in an HDF5 file. + <dt><strong>Description:</strong> + <dd><code>H5Pset_sizes</code> sets the byte size of the offsets and lengths used to + address objects in an HDF5 file. This function is only valid for + file creation property lists. Passing in a value of 0 for one of the + sizeof parameters retains the current value. The default value + for both values is 4 bytes. Valid values currenly are 2, 4, 8 and + 16. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of property list to modify. + <dt><em>size_t</em> <code>sizeof_addr</code> + <dd>IN: Size of an object offset in bytes. + <dt><em>size_t</em> <code>sizeof_size</code> + <dd>IN: Size of an object length in bytes. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetSizes">H5Pget_sizes</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_sizes</code>(<em>hid_t</em> <code>plist</code>, + <em>size_t *</em> <code>sizeof_addr</code>, + <em>size_t *</em> <code>sizeof_size</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the size of the offsets and lengths used in an HDF5 file. + <dt><strong>Description:</strong> + <dd><code>H5Pget_sizes</code> retrieves the size of the offsets + and lengths used in an HDF5 file. + This function is only valid for file creation property lists. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of property list to query. + <dt><em>size_t *</em> <code>size</code> + <dd>OUT: Pointer to location to return offset size in bytes. + <dt><em>size_t *</em> <code>size</code> + <dd>OUT: Pointer to location to return length size in bytes. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetMPI">H5Pset_mpi</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_mpi</code>(<em>hid_t</em> <code>plist</code>, + <em>MPI_Comm</em> <code>comm</code>, + <em>MPI_Info</em> <code>info</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the access mode for parallel I/O and the user supplied + communicator and info object. + <dt><strong>Description:</strong> + <dd><code>H5Pset_mpi</code> stores the access mode for MPIO call and the user supplied + communicator and info in the access property list, which can then + be used to open file. This function is available only in the + parallel HDF5 library and is not a collective function. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of property list to modify + <dt><em>MPI_Comm</em> <code>comm</code> + <dd>IN: MPI communicator to be used for file open as defined in + MPI_FILE_OPEN of MPI-2. This function does not make a + duplicated <code>comm</code>. Any modification to <code>comm</code> after + this function call returns may have undetermined effect + to the access property list. Users should call this function + again to setup the property list. + <dt><em>MPI_Info</em> <code>info</code> + <dd>IN: MPI info object to be used for file open as defined in + MPI_FILE_OPEN of MPI-2. This function does not make a + duplicated <code>info</code>. Any modification to <code>info</code> after + this function call returns may have undetermined effect + to the access property list. Users should call this function + again to setup the property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetMPI">H5Pget_mpi</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_mpi</code>(<em>hid_t</em> <code>plist</code>, + <em>MPI_Comm</em> <code>*comm</code>, + <em>MPI_Info</em> <code>*info</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the communicator and info object. + <dt><strong>Description:</strong> + <dd><code>H5Pget_mpi</code> retrieves the communicator and info object + that have been set by H5Pset_mpi. + This function is available only in the parallel HDF5 library + and is not a collective function. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list that has been set + successfully by H5Pset_mpi. + <dt><em>MPI_Comm *</em> <code>comm</code> + <dd>OUT: Pointer to location to return the communicator. + <dt><em>MPI_Info *</em> <code>info</code> + <dd>OUT: Pointer to location to return the info object. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if the file access property list is set to the MPI. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetXfer">H5Pset_xfer</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_xfer</code>(<em>hid_t</em> <code>plist</code>, + <em>H5D_transfer_t</em> <code>data_xfer_mode</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the transfer mode of the dataset transfer property list. + <dt><strong>Description:</strong> + <dd><code>H5Pset_xfer</code> sets the transfer mode of the dataset transfer property list. + The list can then be used to control the I/O transfer mode + during dataset accesses. This function is available only + in the parallel HDF5 library and is not a collective function. + <p> + Valid data transfer modes are: + <ul><dl> + <dt>H5D_XFER_INDEPENDENT + <dd>Use independent I/O access. + (Currently the default mode.) + <dt>H5D_XFER_COLLECTIVE + <dd>Use MPI collective I/O access. + <dt>H5D_XFER_DFLT + <dd>User default I/O access. + </dl></ul> + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a dataset transfer property list + <dt><em>H5D_transfer_t</em> <code>data_xfer_mode</code> + <dd>IN: Data transfer mode. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetXfer">H5Pget_xfer</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_xfer</code>(<em>hid_t</em> <code>plist</code>, + <em>H5D_transfer_t *</em> <code>data_xfer_mode</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the transfer mode from the dataset transfer property list. + <dt><strong>Description:</strong> + <dd><code>H5Pget_xfer</code> retrieves the transfer mode from the dataset + transfer property list. + This function is available only in the parallel HDF5 library + and is not a collective function. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a dataset transfer property list. + <dt><em>H5D_transfer_t *</em> <code>data_xfer_mode</code> + <dd>OUT: Pointer to location to return the data transfer mode. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetSymK">H5Pset_sym_k</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_sym_k</code>(<em>hid_t</em> <code>plist</code>, + <em>int</em> <code>ik</code>, + <em>int</em> <code>lk</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the size of parameters used to control the symbol table nodes. + <dt><strong>Description:</strong> + <dd><code>H5Pset_sym_k</code> sets the size of parameters used to control the + symbol table nodes. This function is only valid for + file creation property lists. Passing in a value of 0 for one of the + parameters retains the current value. + <p> + <code>ik</code> is one half the rank of a tree that stores a symbol + table for a group. Internal nodes of the symbol table are on + average 75% full. That is, the average rank of the tree is + 1.5 times the value of <code>ik</code>. + <p> + <code>lk</code> is one half of the number of symbols that can be stored in + a symbol table node. A symbol table node is the leaf of a + symbol table tree which is used to store a group. When + symbols are inserted randomly into a group, the group's + symbol table nodes are 75% full on average. That is, they + contain 1.5 times the number of symbols specified by <code>lk</code>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for property list to query. + <dt><em>int</em> <code>ik</code> + <dd>IN: Symbol table tree rank. + <dt><em>int</em> <code>lk</code> + <dd>IN: Symbol table node size. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetSymK">H5Pget_sym_k</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_sym_k</code>(<em>hid_t</em> <code>plist</code>, + <em>int *</em> <code>ik</code>, + <em>int *</em> <code>lk</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the size of the symbol table B-tree 1/2 rank + and the symbol table leaf node 1/2 size. + <dt><strong>Description:</strong> + <dd><code>H5Pget_sym_k</code> retrieves the size of the + symbol table B-tree 1/2 rank and the symbol table leaf node 1/2 size. + This function is only valid for file creationproperty lists. + If a parameter valued is set to NULL, that parameter is not retrieved. + See the description for <a href="#Property-SetSymK">H5Pset_sym_k</a> + for more information. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Property list to query. + <dt><em>int *</em> <code>ik</code> + <dd>OUT: Pointer to location to return the symbol table's B-tree 1/2 rank. + <dt><em>int *</em> <code>size</code> + <dd>OUT: Pointer to location to return the symbol table's leaf node 1/2 size. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetIstoreK">H5Pset_istore_k</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_istore_k</code>(<em>hid_t</em> <code>plist</code>, + <em>int</em> <code>ik</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the size of the parameter used to control the + B-trees for indexing chunked datasets. + <dt><strong>Description:</strong> + <dd><code>H5Pset_istore_k</code> sets the size of the parameter used to control the + B-trees for indexing chunked datasets. This function is only valid for + file creation property lists. Passing in a value of 0 for one of the + parameters retains the current value. + <p> + <code>ik</code> is one half the rank of a tree that stores chunked raw + data. On average, such a tree will be 75% full, or have an + average rank of 1.5 times the value of <code>ik</code>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of property list to query. + <dt><em>int</em> <code>ik</code> + <dd>IN: 1/2 rank of chunked storage B-tree. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetIstoreK">H5Pget_istore_k</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_istore_k</code>(<em>hid_t</em> <code>plist</code>, + <em>int *</em> <code>ik</code> + ) + <dt><strong>Purpose:</strong> + <dd>Queries the 1/2 rank of an indexed storage B-tree. + <dt><strong>Description:</strong> + <dd><code>H5Pget_istore_k</code> queries the 1/2 rank of + an indexed storage B-tree. + The argument <code>ik</code> may be the null pointer (NULL). + This function is only valid for file creation property lists. + <p> + See <a href="#Property-SetIstoreK">H5Pset_istore_k</a> for details. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of property list to query. + <dt><em>int *</em> <code>ik</code> + <dd>OUT: Pointer to location to return the chunked storage B-tree 1/2 rank. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetLayout">H5Pset_layout</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_layout</code>(<em>hid_t</em> <code>plist</code>, + <em>H5D_layout_t</em> <code>layout</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the type of storage used store the raw data for a dataset. + <dt><strong>Description:</strong> + <dd><code>H5Pset_layout</code> sets the type of storage used store the + raw data for a dataset. + This function is only valid for dataset creation property lists. + Valid parameters for <code>layout</code> are: + <ul><dl> + <dt>H5D_COMPACT + <dd>Store raw data and object header contiguously in file. + This should only be used for very small amounts of raw + data (suggested less than 1KB). + <dt>H5D_CONTIGUOUS + <dd>Store raw data seperately from object header in one + large chunk in the file. + <dt>H5D_CHUNKED + <dd>Store raw data seperately from object header in one + large chunk in the file and store chunks of the raw + data in seperate locations in the file. + </dl></ul> + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of property list to query. + <dt><em>H5D_layout_t</em> <code>layout</code> + <dd>IN: Type of storage layout for raw data. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetLayout">H5Pget_layout</a> + <dt><strong>Signature:</strong> + <dd><em>H5D_layout_t</em> <code>H5Pget_layout</code>(<em>hid_t</em> <code>plist</code>) + <dt><strong>Purpose:</strong> + <dd>Returns the layout of the raw data for a dataset. + <dt><strong>Description:</strong> + <dd><code>H5Pget_layout</code> returns the layout of the raw data for a dataset. + This function is only valid for dataset creation property lists. + Valid types for <code>layout</code> are: + <ul> <dl> + <dt>H5D_COMPACT + <dd>Raw data and object header stored contiguously in file. + <dt>H5D_CONTIGUOUS + <dd>Raw data stored seperately from object header in one + large chunk in the file. + <dt>H5D_CHUNKED + <dd>Raw data stored seperately from object header in + chunks in seperate locations in the file. + </dl> </ul> + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for property list to query. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns the layout type of a a dataset creation property list + if successful. + Otherwise returns H5D_LAYOUT_ERROR (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetChunk">H5Pset_chunk</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_chunk</code>(<em>hid_t</em> <code>plist</code>, + <em>int</em> <code>ndims</code>, + <em>const hsize_t *</em> <code>dim</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the size of the chunks used to store a chunked layout dataset. + <dt><strong>Description:</strong> + <dd><code>H5Pset_chunk</code> sets the size of the chunks used to store a chunked + layout dataset. This function is only valid for dataset creation + property lists. The <code>ndims</code> parameter currently must be the + same size as the rank of the dataset. The values of the + <code>dim</code> array define the size of the chunks to store the + dataset's raw data. As a side-effect, the layout of the dataset is + changed to H5D_CHUNKED, if it isn't already. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for property list to query. + <dt><em>int</em> <code>ndims</code> + <dd>IN: The number of dimensions of each chunk. + <dt><em>const hsize_t *</em> <code>dim</code> + <dd>IN: An array containing the size of each chunk. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetChunk">H5Pget_chunk</a> + <dt><strong>Signature:</strong> + <dd><em>int </em><code>H5Pget_chunk</code>(<em>hid_t</em> <code>plist</code>, + <em>int</em> <code>max_ndims</code>, + <em>hsize_t *</em> <code>dims</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the size of chunks for the raw data of a chunked layout dataset. + <dt><strong>Description:</strong> + <dd><code>H5Pget_chunk</code> retrieves the size of chunks for the + raw data of a chunked layout dataset. + This function is only valid for dataset creation property lists. + At most, <code>max_ndims</code> elements of <code>dims</code> + will be initialized. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of property list to query. + <dt><em>int</em> <code>max_ndims</code> + <dd>OUT: Size of the <code>dims</code> array. + <dt><em>hsize_t *</em> <code>dims</code> + <dd>OUT: Array to store the chunk dimensions. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns chunk dimensionality successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetAlignment">H5Pset_alignment</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_alignment</code>(<em>hid_t</em> <code>plist</code>, + <em>hsize_t</em> <code>threshold</code>, + <em>hsize_t</em> <code>alignment</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets alignment properties of a file access property list. + <dt><strong>Description:</strong> + <dd><code>H5Pset_alignment</code> sets the alignment properties + of a file access property list + so that any file object >= THRESHOLD bytes will be aligned on + an address which is a multiple of ALIGNMENT. The addresses + are relative to the end of the user block; the alignment is + calculated by subtracting the user block size from the + absolute file address and then adjusting the address to be a + multiple of ALIGNMENT. + <p> + Default values for THRESHOLD and ALIGNMENT are one, implying + no alignment. Generally the default values will result in + the best performance for single-process access to the file. + For MPI-IO and other parallel systems, choose an alignment + which is a multiple of the disk block size. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for a file access property list. + <dt><em>hsize_t</em> <code>threshold</code> + <dd>IN: Threshhold value. + <dt><em>hsize_t</em> <code>alignment</code> + <dd>IN: Alignment value. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetAlignment">H5Pget_alignment</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pget_alignment</code>(<em>hid_t</em> <code>plist</code>, + <em>hsize_t</em> <code>*threshold</code>, + <em>hsize_t</em> <code>*alignment</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the current settings for alignment properties from a + file access property list. + <dt><strong>Description:</strong> + <dd><code>H5Pget_alignment</code> retrieves the current settings for + alignment properties from a file access property list. + The <code>threshold</code> and/or <code>alignment</code> pointers + may be null pointers (NULL). + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list. + <dt><em>hsize_t</em> <code>*threshold</code> + <dd>OUT: Pointer to location of return threshhold value. + <dt><em>hsize_t</em> <code>*alignment</code> + <dd>OUT: Pointer to location of return alignment value. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetExternal">H5Pset_external</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_external</code>(<em>hid_t</em> <code>plist</code>, + <em>const char</em> <code>*name</code>, + <em>off_t</em> <code>offset</code>, + <em>hsize_t</em> <code>size</code> + ) + <dt><strong>Purpose:</strong> + <dd>Adds an external file to the list of external files. + <dt><strong>Description:</strong> + <dd><code>H5Pset_external</code> adds an external file to the + list of external files. + <p> + If a dataset is split across multiple files then the files + should be defined in order. The total size of the dataset is + the sum of the SIZE arguments for all the external files. If + the total size is larger than the size of a dataset then the + dataset can be extended (provided the data space also allows + the extending). + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a dataset creation property list. + <dt><em>const char</em> <code>*name</code> + <dd>IN: Name of an external file. + <dt><em>off_t</em> <code>offset</code> + <dd>IN: Offset, in bytes, from the beginning of the file + to the location in the file where the data starts. + <dt><em>hsize_t</em> <code>size</code> + <dd>IN: Number of bytes reserved in the file for the data. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetExternalCount">H5Pget_external_count</a> + <dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Pget_external_count</code>(<em>hid_t</em> <code>plist</code>, + ) + <dt><strong>Purpose:</strong> + <dd>Returns the number of external files for a dataset. + <dt><strong>Description:</strong> + <dd><code>H5Pget_external_count</code> returns the number of external files + for the specified dataset. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a dataset creation property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns the number of external files if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetExternal">H5Pget_external</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pget_external</code>(<em>hid_t</em> <code>plist</code>, + <em>int</em> <code>idx</code>, + <em>size_t</em> <code>name_size</code>, + <em>char</em> <code>*name</code>, + <em>off_t</em> <code>*offset</code>, + <em>hsize_t</em> <code>*size</code> + ) + <dt><strong>Purpose:</strong> + <dd>Returns information about an external file. + <dt><strong>Description:</strong> + <dd><code>H5Pget_external</code> returns information about an external file. + The external file is specified by its index, <code>idx</code>, + which is a number from zero to N-1, where N is the value + returned by <code>H5Pget_external_count()</code>. + At most <code>name_size</code> characters are copied into the + <code>name</code> array. If the external file name is + longer than <code>name_size</code> with the null terminator, the + return value is not null terminated (similar to <code>strncpy()</code>). + <p> + If <code>name_size</code> is zero or <code>name</code> is the + null pointer, the external file name is not returned. + If <code>offset</code> or <code>size</code> are null pointers + then the corresponding information is not returned. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a dataset creation property list. + <dt><em>int</em> <code>idx</code> + <dd>IN: External file index. + <dt><em>size_t</em> <code>name_size</code> + <dd>IN: Maximum length of <code>name</code> array. + <dt><em>char</em> <code>*name</code> + <dd>OUT: Name of the external file. + <dt><em>off_t</em> <code>*offset</code> + <dd>OUT: Pointer to a location to return an offset value. + <dt><em>hsize_t</em> <code>*size</code> + <dd>OUT: Pointer to a location to return the size of the + external file data. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetDriver">H5Pget_driver</a> + <dt><strong>Signature:</strong> + <dd><em>H5F_driver_t</em> <code>H5Pget_driver</code>(<em>hid_t</em> <code>plist</code>, + ) + <dt><strong>Purpose:</strong> + <dd>Returns a low-level file driver identifier. + <dt><strong>Description:</strong> + <dd><code>H5Pget_driver</code> returns the identifier of the + low-level file driver. Valid identifiers are: + <ul> + <li>H5F_LOW_STDIO (0) + <li>H5F_LOW_SEC2 (1) + <li>H5F_LOW_MPIO (2) + <li>H5F_LOW_CORE (3) + <li>H5F_LOW_SPLIT (4) + <li>H5F_LOW_FAMILY (5) + </ul> + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a low-level driver identifier if successful. + Otherwise returns H5F_LOW_ERROR (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetStdio">H5Pset_stdio</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_stdio</code>(<em>hid_t</em> <code>plist</code>) + <dt><strong>Purpose:</strong> + <dd>Sets the low level file driver to use the functions declared + in the stdio.h. + <dt><strong>Description:</strong> + <dd><code>H5Pset_stdio</code> sets the low level file driver to use + the functions declared + in the stdio.h file: fopen(), fseek() or fseek64(), fread(), + fwrite(), and fclose(). + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetStdio">H5Pget_stdio</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pget_stdio</code>(<em>hid_t</em> <code>plist</code>) + <dt><strong>Purpose:</strong> + <dd>Determines whether the file access property list is set to + the stdio driver. + <dt><strong>Description:</strong> + <dd><code>H5Pget_stdio</code> checks to determine whether the + file access property list is set to the stdio driver. + In the future, additional arguments may be added to this + function to match those added to H5Pset_stdio(). + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if the file access propety list is set + to the stdio driver. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetSec2">H5Pset_sec2</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_sec2</code>(<em>hid_t</em> <code>plist</code>, + ) + <dt><strong>Purpose:</strong> + <dd>Sets the low-level file driver to use the declared functions. + <dt><strong>Description:</strong> + <dd><code>H5Pset_sec2</code> sets the low-level file driver to use + the functions declared + in the unistd.h file: open(), lseek() or lseek64(), read(), + write(), and close(). + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetSec2">H5Pget_sec2</a> + <dt><strong>Signature:</strong> + <dd><em>returntype</em> <code>H5Pget_sec2</code>(<em>hid_t</em> <code>plist</code>) + <dt><strong>Purpose:</strong> + <dd>Checks whether the file access propety list is set + to the sec2 driver. + <dt><strong>Description:</strong> + <dd><code>H5Pget_sec2</code> checks to determine whether the + file access property list is set to the sec2 driver. + In the future, additional arguments may be + added to this function to match those added to H5Pset_sec2(). + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if the file access propety list is set + to the sec2 driver. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetCore">H5Pset_core</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_core</code>(<em>hid_t</em> <code>plist</code>, + <em>size_t</em> <code>increment</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the low-level file driver to use malloc() and free(). + <dt><strong>Description:</strong> + <dd><code>H5Pset_core</code> sets the low-level file driver to use malloc() and free(). + This driver is restricted to temporary files which are not + larger than the amount of virtual memory available. The + INCREMENT argument determines the file block size and memory + will be allocated in multiples of INCREMENT bytes. A liberal + INCREMENT results in fewer calls to realloc() and probably + less memory fragmentation. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list. + <dt><em>size_t</em> <code>increment</code> + <dd>IN: File block size in bytes. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetCore"></a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pget_core</code>(<em>hid_t</em> <code>plist</code>, + <em>size_t</em> <code>*increment</code> + ) + <dt><strong>Purpose:</strong> + <dd>Determines whether the file access property list is set + to the core driver. + <dt><strong>Description:</strong> + <dd><code>H5Pget_core</code> checks to determine whether the + file access property list is set to the core driver. + On success, the block size is returned + through the INCREMENT argument if it isn't the null pointer. + In the future, additional arguments may be added to this + function to match those added to H5Pset_core(). + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the file access property list. + <dt><em>size_t</em> <code>*increment</code> + <dd>OUT: Pointer to a location to return the file block size (in bytes). + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if the file access propety list is set + to the core driver. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetSplit">H5Pset_split</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_split</code>(<em>hid_t</em> <code>plist</code>, + <em>const char</em> <code>*meta_ext</code>, + <em>hid_t</em> <code>meta_plist</code>, + <em>const char</em> <code>*raw_ext</code>, + <em>hid_t</em> <code>raw_plist</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the low-level driver to split meta data from raw data. + <dt><strong>Description:</strong> + <dd><code>H5Pset_split</code> sets the low-level driver to + split meta data from raw data, storing meta data in one file and + raw data in another file. The meta file will have a name + which is formed by adding <em>meta_extension</em> (recommended + default value: <code>.meta</code>) to the end of the base name + and will be accessed according to the <em>meta_properties</em>. + The raw file will have a name which is formed by appending + <em>raw_extension</em> (recommended default value: + <code>.raw</code>) to the base name and will be accessed according + to the <em>raw_properties</em>. + Additional parameters may be added to this function in the future. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the file access property list. + <dt><em>const char</em> <code>*meta_ext</code> + <dd>IN: Name of the extension for the metafile filename. + Recommended default value: <code>.meta</code>. + <dt><em>hid_t</em> <code>meta_plist</code> + <dd>IN: Identifier of the meta file access property list. + <dt><em>const char</em> <code>*raw_ext</code> + <dd>IN: Name extension for the raw file filename. + Recommended default value: <code>.raw</code>. + <dt><em>hid_t</em> <code>raw_plist</code> + <dd>IN: Identifier of the raw file access property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetSplit">H5Pget_split</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pget_split</code>(<em>hid_t</em> <code>plist</code>, + <em>size_t</em> <code>meta_ext_size</code>, + <em>char</em> <code>*meta_ext</code>, + <em>hid_t</em> <code>*meta_properties</code>, + <em>size_t</em> <code>raw_ext_size</code>, + <em>char</em> <code>*raw_ext</code>, + <em>hid_t</em> <code>*raw_properties</code> + ) + <dt><strong>Purpose:</strong> + <dd>Determines whether the file access property list is set + to the split driver. + <dt><strong>Description:</strong> + <dd><code>H5Pget_split</code> checks to determine whether the file + access property list is set to the split driver. + On successful return, + <em>meta_properties</em> and <em>raw_properties</em> will + point to copies of the meta and raw access property lists + which should be closed by calling <code>H5Pclose()</code> when + the application is finished with them, but if the meta and/or + raw file has no property list then a negative value is + returned for that property list identifier. Also, if + <em>meta_extension</em> and/or <em>raw_extension</em> are + non-null pointers, at most <em>meta_ext_size</em> or + <em>raw_ext_size</em> characters of the meta or raw file name + extension will be copied to the specified buffer. If the + actual name is longer than what was requested then the result + will not be null terminated (similar to + <code>strncpy()</code>). In the future, additional arguments + may be added to this function to match those added to + <code>H5Pset_split()</code>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the file access property list. + <dt><em>size_t</em> <code>meta_ext_size</code> + <dd>IN: Number of characters of the meta file extension to be + copied to the <code>meta_ext</code> buffer. + <dt><em>OUT</em> <code>*meta_ext</code> + <dd>IN: Meta file extension. + <dt><em>hid_t</em> <code>*meta_properties</code> + <dd>OUT: Pointer to a copy of the meta file access property list. + <dt><em>size_t</em> <code>raw_ext_size</code> + <dd>IN: Number of characters of the raw file extension to be + copied to the <code>raw_ext</code> buffer. + <dt><em>char</em> <code>*raw_ext</code> + <dd>OUT: Raw file extension. + <dt><em>hid_t</em> <code>*raw_properties</code> + <dd>OUT: Pointer to a copy of the raw file access property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if the file access propety list is set + to the split driver. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetFamily">H5Pset_family</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_family</code>(<em>hid_t</em> <code>plist</code>, + <em>hsize_t</em> <code>memb_size</code>, + <em>hid_t</em> <code>memb_plist</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the file access properties list to the <em>family</em> + driver. + <dt><strong>Description:</strong> + <dd><code>H5Pset_family</code> sets the file access properties + to use the <em>family</em> + driver; any previously defined driver properties are erased + from the property list. Each member of the file family will + use <em>member_properties</em> as its file access property + list. The <em>memb_size</em> argument gives the logical size + in bytes of each family member but the actual size could be + smaller depending on whether the file contains holes. The + member size is only used when creating a new file or + truncating an existing file; otherwise the member size comes + from the size of the first member of the family being + opened. Note: if the size of the <code>off_t</code> type is + four bytes then the maximum family member size is usually + 2^31-1 because the byte at offset 2,147,483,647 is generally + inaccessable. Additional parameters may be added to this + function in the future. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the file access property list. + <dt><em>hsize_t</em> <code>memb_size</code> + <dd>IN: Logical size, in bytes, of each family member. + <dt><em>hid_t</em> <code>memb_plist</code> + <dd>IN: Identifier of the file access property list + for each member of the family. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetFamily">H5Pget_family</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pget_family</code>(<em>hid_t</em> <code>tid</code>, + <em>hsize_t</em> <code>*memb_size</code>, + <em>hid_t</em> <code>*memb_plist</code> + ) + <dt><strong>Purpose:</strong> + <dd>Determines whether the file access property list + is set to the family driver. + <dt><strong>Description:</strong> + <dd><code>H5Pget_family</code> checks to determine whether the + file access property list is set to the family driver. + On successful return, + <em>access_properties</em> will point to a copy of the member + access property list which should be closed by calling + <code>H5Pclose()</code> when the application is finished with + it. If <em>memb_size</em> is non-null then it will contain + the logical size in bytes of each family member. In the + future, additional arguments may be added to this function to + match those added to <code>H5Pset_family()</code>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the file access property list. + <dt><em>hsize_t</em> <code>*memb_size</code> + <dd>OUT: Logical size, in bytes, of each family member. + <dt><em>hid_t</em> <code>*memb_plist</code> + <dd>OUT: Identifier of the file access property list + for each member of the family. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if the file access propety list is set + to the family driver. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetCache">H5Pset_cache</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_cache</code>(<em>hid_t</em> <code>plist</code>, + <em>int</em> <code>mdc_nelmts</code>, + <em>size_t</em> <code>rdcc_nbytes</code>, + <em>double</em> <code>rdcc_w0</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the number of elements in the meta data cache and the + total number of bytes in the raw data chunk cache. + <dt><strong>Description:</strong> + <dd><code>H5Pset_cache</code> sets the number of elements (objects) in the meta data cache and the + total number of bytes in the raw data chunk cache. + <p> + Sets or queries the meta data cache and raw data chunk cache + parameters. The <em>plist</em> is a file access property + list. The number of elements (objects) in the meta data cache + is <em>mdc_nelmts</em>. The total size of the raw data chunk + cache and the preemption policy is <em>rdcc_nbytes</em> and + <em>w0</em>. For <code>H5Pget_cache()</code> any (or all) of + the pointer arguments may be null pointers. + <p> + The RDCC_W0 value should be between 0 and 1 inclusive and + indicates how much chunks that have been fully read are + favored for preemption. A value of zero means fully read + chunks are treated no differently than other chunks (the + preemption is strictly LRU) while a value of one means fully + read chunks are always preempted before other chunks. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the file access property list. + <dt><em>int</em> <code>mdc_nelmts</code> + <dd>IN: Number of elements (objects) in the meta data cache. + <dt><em>size_t</em> <code>rdcc_nbytes</code> + <dd>IN: Total size of the raw data chunk cache, in bytes. + <dt><em>double</em> <code>rdcc_w0</code> + <dd>IN: Preemption policy. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetCache">H5Pget_cache</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pget_cache</code>(<em>hid_t</em> <code>plist</code>, + <em>int</em> <code>*mdc_nelmts</code>, + <em>size_t</em> <code>*rdcc_nbytes</code>, + <em>double</em> <code>*rdcc_w0</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves maximun sizes of meta data cache and RDCC_WO. + <dt><strong>Description:</strong> + <dd>Retrieves the maximum possible number of elements in the meta + data cache and the maximum possible number of bytes and the + RDCC_W0 value in the raw data chunk cache. Any (or all) + arguments may be null pointers in which case the corresponding + datum is not returned. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the file access property list. + <dt><em>int</em> <code>*mdc_nelmts</code> + <dd>IN/OUT: Number of elements (objects) in the meta data cache. + <dt><em>size_t</em> <code>*rdcc_nbytes</code> + <dd>IN/OUT: Total size of the raw data chunk cache, in bytes. + <dt><em>double</em> <code>*rdcc_w0</code> + <dd>IN/OUT: Preemption policy. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetBuffer">H5Pset_buffer</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_buffer</code>(<em>hid_t</em> <code>plist</code>, + <em>size_t</em> <code>size</code>, + <em>void</em> <code>*tconv</code>, + <em>void</em> <code>*bkg</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets type conversion and background buffers. + <dt><strong>Description:</strong> + <dd> Given a dataset transfer property list, <code>H5Pset_buffer</code> + sets the maximum size + for the type conversion buffer and background buffer and + optionally supply pointers to application-allocated buffers. + If the buffer size is smaller than the entire amount of data + being transfered between application and file, and a type + conversion buffer or background buffer is required then + strip mining will be used. However, certain restrictions + apply for the size of buffer which can be used for strip + mining. For instance, when strip mining a 100x200x300 + hyperslab of a simple data space the buffer must be large + enough to hold a 1x200x300 slab. + <p> + If TCONV and/or BKG are null pointers then buffers will be + allocated and freed during the data transfer. + <p> + The default value for the maximum buffer is 1 Mb. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for the dataset transfer property list. + <dt><em>size_t</em> <code>size</code> + <dd>IN: Size for the type conversion and background buffers. + <dt><em>void</em> <code>tconv</code> + <dd>IN: Pointer to application-allocated type conversion buffer. + <dt><em>void</em> <code>bkg</code> + <dd>IN: Pointer to application-allocated background buffer. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetBuffer">H5Pget_buffer</a> + <dt><strong>Signature:</strong> + <dd><em>size_t</em> <code>H5Pget_buffer</code>(<em>hid_t</em> <code>plist</code>, + <em>void</em> <code>**tconv</code>, + <em>void</em> <code>**bkg</code> + ) + <dt><strong>Purpose:</strong> + <dd>Reads buffer settings. + <dt><strong>Description:</strong> + <dd><code>H5Pget_buffer</code> reads values previously set + with H5Pset_buffer(). + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for the dataset transfer property list. + <dt><em>void</em> <code>**tconv</code> + <dd>OUT: Address of the pointer to application-allocated + type conversion buffer. + <dt><em>void</em> <code>**bkg</code> + <dd>OUT: Address of the pointer to application-allocated + background buffer. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns buffer size if successful; + otherwise 0 on failure. +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetPreserve">H5Pset_preserve</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_preserve</code>(<em>hid_t</em> <code>plist</code>, + <em>hbool_t</em> <code>status</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the dataset transfer property list status to TRUE or FALSE. + <dt><strong>Description:</strong> + <dd><code>H5Pset_preserve</code> sets the + dataset transfer property list status to TRUE or FALSE. + <p> + When reading or writing compound data types and the + destination is partially initialized and the read/write is + intended to initialize the other members, one must set this + property to TRUE. Otherwise the I/O pipeline treats the + destination datapoints as completely uninitialized. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for the dataset transfer property list. + <dt><em>hbool_t</em> <code>status</code> + <dd>IN: Status of for the dataset transfer property list + (TRUE/FALSE). + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetPreserve">H5Pget_preserve</a> + <dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Pget_preserve</code>(<em>hid_t</em> <code>plist</code>) + <dt><strong>Purpose:</strong> + <dd>Checks status of the dataset transfer property list. + <dt><strong>Description:</strong> + <dd><code>H5Pget_preserve</code> checks the status of the + dataset transfer property list. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for the dataset transfer property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns TRUE or FALSE if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetCompression">H5Pset_compression</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_compression</code>(<em>hid_t</em> <code>plist</code>, + <em>H5Z_method_t</em> <code>method</code>, + <em>unsigned int</em> <code>flags</code>, + <em>size_t</em> <code>cd_size</code>, + <em>const void</em> <code>*client_data</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets compression method. + <dt><strong>Description:</strong> + <dd> <code>H5Pset_compression</code> sets the compression method in a dataset creation property + list. This is a catch-all function for defining compresion methods + and is intended to be called from a wrapper such as + <code>H5Pset_deflate()</code>. The dataset creation property + list <em>plist</em> is adjusted to use the specified + compression method. The <em>flags</em> is an 8-bit vector + which is stored in the file as part of the compression message + and passed to the compress and uncompress functions. The + <em>client_data</em> is a byte array of length + <em>cd_size</em> which is copied to the file and passed to the + compress and uncompress methods. + <p> + The FLAGS, CD_SIZE, and CLIENT_DATA are copied to the + property list and eventually to the file and passed to the + compression functions. + <p> + See <a href="Compression.html"><cite>Compression</cite></a> + in the <cite>HDF5 User's Guide</cite> for further information. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for the dataset creation property list. + <dt><em>H5Z_method_t</em> <code>method</code> + <dd>IN: Compression method, an integer from 16 to 225. + <dt><em>unsigned int</em> <code>flags</code> + <dd>IN: Compression flags. + <dt><em>size_t</em> <code>cd_size</code> + <dd>IN: Size of the byte array <code>client_data</code>. + <dt><em>const void</em> <code>*client_data</code> + <dd>IN: Client data byte array passed to the compression method. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetCompression">H5Pget_compression</a> + <dt><strong>Signature:</strong> + <dd><em>H5Z_method_t</em> <code>H5Pget_compression</code>(<em>hid_t</em> <code>plist</code>, + <em>unsigned int</em> <code>*flags</code>, + <em>size_t</em> <code>*cd_size</code>, + <em>void</em> <code>*client_data</code> + ) + <dt><strong>Purpose:</strong> + <dd>Gets compression method. + <dt><strong>Description:</strong> + <dd><code>H5Pget_compression</code> gets the compression method + information from a dataset creation property list. + The CLIENT_DATA buffer is initially CD_SIZE bytes. + On return, CLIENT_DATA will be initialized + with at most that many bytes, and CD_SIZE will contain the + actual size of the client data, which might be larger than + its original value.<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for the dataset creation property list. + <dt><em>unsigned int</em> <code>*flags</code> + <dd>OUT: Compression flags. + <dt><em>size_t</em> <code>*cd_size</code> + <dd>IN/OUT: Size of the <code>client_data</code> array. + <dt><em>void</em> <code>*client_data</code> + <dd>OUT: Byte array for the client data. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns compression method if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetDeflate">H5Pset_deflate</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_deflate</code>(<em>hid_t</em> <code>plist</code>, + <em>int</em> <code>level</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets compression method and compression level. + <dt><strong>Description:</strong> + <dd><code>H5Pset_deflate</code> sets the compression method for a + dataset creation property + list to H5D_COMPRESS_DEFLATE and the compression level to + LEVEL which should be a value between zero and nine, + inclusive. Lower compression levels are faster but result in + less compression. This is the same algorithm as used by the + GNU gzip program. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for the dataset creation property list. + <dt><em>int</em> <code>level</code> + <dd>IN: Compression level. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetDeflate">H5Pget_deflate</a> + <dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Pget_deflate</code>(<em>hid_t</em> <code>plist</code> + ) + <dt><strong>Purpose:</strong> + <dd>Returns the deflate compression level from a dataset creation + property list. + <dt><strong>Description:</strong> + <dd><code>H5Pget_deflate</code> returns the deflate compression level + from a dataset creation property list that uses that method. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for the dataset creation property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns compression level, a value between 0 and 9, 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> +<a href="RM_H5G.html">H5G</a> +H5P +<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> diff --git a/doc/html/RM_H5S.html b/doc/html/RM_H5S.html new file mode 100644 index 0000000..6230e56 --- /dev/null +++ b/doc/html/RM_H5S.html @@ -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> diff --git a/doc/html/RM_H5T.html b/doc/html/RM_H5T.html new file mode 100644 index 0000000..0fa5926 --- /dev/null +++ b/doc/html/RM_H5T.html @@ -0,0 +1,1755 @@ +<html> +<head><title> +HDF5/H5T 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> +<a href="RM_H5S.html">H5S</a> +H5T +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + +<center> +<h1>H5T: Datatype Interface</h1> +</center> + +<h2>Datatype Object API Functions</h2> + +These functions create and manipulate the datatype which describes elements +of a dataset. + +<table border=0> +<tr><td valign=top> +<i>General Datatype Operations</i> + <li><a href="#Datatype-Create">H5Tcreate</a> + <li><a href="#Datatype-Open">H5Topen</a> + <li><a href="#Datatype-Commit">H5Tcommit</a> + <li><a href="#Datatype-Committed">H5Tcommitted</a> + <li><a href="#Datatype-Copy">H5Tcopy</a> + <li><a href="#Datatype-Equal">H5Tequal</a> + <li><a href="#Datatype-Lock">H5Tlock</a> + <li><a href="#Datatype-Close">H5Tclose</a> +<p> +<i>Atomic Datatype Properties</i> + <li><a href="#Datatype-GetClass">H5Tget_class</a> + <li><a href="#Datatype-GetSize">H5Tget_size</a> + <li><a href="#Datatype-SetSize">H5Tset_size</a> + <li><a href="#Datatype-GetOrder">H5Tget_order</a> + <li><a href="#Datatype-SetOrder">H5Tset_order</a> + <li><a href="#Datatype-GetPrecision">H5Tget_precision</a> + <li><a href="#Datatype-SetPrecision">H5Tset_precision</a> + <li><a href="#Datatype-GetOffset">H5Tget_offset</a> + <li><a href="#Datatype-SetOffset">H5Tset_offset</a> +</td><td> </td><td valign=top> + <li><a href="#Datatype-GetPad">H5Tget_pad</a> + <li><a href="#Datatype-SetPad">H5Tset_pad</a> + <li><a href="#Datatype-GetSign">H5Tget_sign</a> + <li><a href="#Datatype-SetSign">H5Tset_sign</a> + <li><a href="#Datatype-GetFields">H5Tget_fields</a> + <li><a href="#Datatype-SetFields">H5Tset_fields</a> + <li><a href="#Datatype-GetEbias">H5Tget_ebias</a> + <li><a href="#Datatype-SetEbias">H5Tset_ebias</a> + <li><a href="#Datatype-GetNorm">H5Tget_norm</a> + <li><a href="#Datatype-SetNorm">H5Tset_norm</a> + <li><a href="#Datatype-GetInpad">H5Tget_inpad</a> + <li><a href="#Datatype-SetInpad">H5Tset_inpad</a> + <li><a href="#Datatype-GetCset">H5Tget_cset</a> + <li><a href="#Datatype-SetCset">H5Tset_cset</a> + <li><a href="#Datatype-GetStrpad">H5Tget_strpad</a> + <li><a href="#Datatype-SetStrpad">H5Tset_strpad</a> +<p> +<i>Properties of Compound Types</i> + <li><a href="#Datatype-GetClass">H5Tget_class</a> + <li><a href="#Datatype-GetSize">H5Tget_size</a> +</td><td> </td><td valign=top> + <li><a href="#Datatype-GetNmembers">H5Tget_nmembers</a> + <li><a href="#Datatype-GetMemberName">H5Tget_member_name</a> + <li><a href="#Datatype-GetMemberOffset">H5Tget_member_offset</a> + <li><a href="#Datatype-GetMemberDims">H5Tget_member_dims</a> + <li><a href="#Datatype-GetMemberType">H5Tget_member_type</a> + <li><a href="#Datatype-Insert">H5Tinsert</a> + <li><a href="#Datatype-Pack">H5Tpack</a> + <li><a href="#Datatype-InsertArray">H5Tinsert_array</a> +<p> +<i>Conversion Functions</i> + <li><a href="#Datatype-Convert">H5Tconvert</a> + <li><a href="#Datatype-Find">H5Tfind</a> + <li><a href="#Datatype-SetOverflow">H5Tset_overflow</a> + <li><a href="#Datatype-GetOverflow">H5Tget_overflow</a> + <li><a href="#Datatype-RegisterHard">H5Tregister_hard</a> + <li><a href="#Datatype-RegisterSoft">H5Tregister_soft</a> + <li><a href="#Datatype-Unregister">H5Tunregister</a> +</td></tr> +</table> + +<p> +The Datatype interface, H5T, provides a mechanism to describe the + storage format of individual data points of a data set and is + hopefully designed in such a way as to allow new features to be + easily added without disrupting applications that use the data + type interface. A dataset (the H5D interface) is composed of a + collection or raw data points of homogeneous type organized + according to the data space (the H5S interface). + +<p> +A datatype is a collection of datatype properties, all of + which can be stored on disk, and which when taken as a whole, + provide complete information for data conversion to or from that + datatype. The interface provides functions to set and query + properties of a datatype. + +<p> +A <em>data point</em> is an instance of a <em>datatype</em>, + which is an instance of a <em>type class</em>. We have defined + a set of type classes and properties which can be extended at a + later time. The atomic type classes are those which describe + types which cannot be decomposed at the datatype interface + level; all other classes are compound. + +<p> +See <a href="Datatypes.html"><cite>The Datatype Interface (H5T)</cite></a> +in the <cite>HDF5 User's Guide</cite> for further information. + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Open">H5Topen</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t</em><code>H5Topen</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em> <code>name</code> + ) +<dt><strong>Purpose:</strong> + <dd>Opens a named datatype. +<dt><strong>Description:</strong> + <dd><code>H5Topen</code> opens a named datatype at the location + specified by <code>loc_id</code> and returns an identifier + for the datatype. <code>loc_id</code> is either a file or + group identifier. The identifier should eventually be closed + by calling <code>H5Tclose()</code> to release resources. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>A file or group identifier. + <dt><em>const char *</em> <code>name</code> + <dd>A datatype name. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a named datatype identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Commit">H5Tcommit</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em><code>H5Tcommit</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em> <code>name</code>, + <em>hid_t</em> <code>type</code> + ) +<dt><strong>Purpose:</strong> + <dd>Commits a transient datatype to a file, creating a new named datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tcommit</code> commits a transient datatype + (not immutable) to a file, turned it into a named datatype. + The <code>loc_id</code> is either a file or group identifier + which, when combined with <code>name</code>, refers to a new + named datatype. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>A file or group identifier. + <dt><em>const char *</em> <code>name</code> + <dd>A datatype name. + <dt><em>hid_t</em> <code>type</code> + <dd>A datatype identifier. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Committed">H5Tcommitted</a> +<dt><strong>Signature:</strong> + <dd><em>hbool_t</em><code>H5Tcommitted</code>(<em>hid_t</em> <code>type</code>) +<dt><strong>Purpose:</strong> + <dd>Determines whether a datatype is a named type or a transient type. +<dt><strong>Description:</strong> + <dd><code>H5Tcommitted</code> queries a type to determine whether + the type specified by the <code>type</code> identifier + is a named type or a transient type. If this function returns + a positive value, then the type is named (that is, it has been + committed, perhaps by some other application). Datasets which + return committed datatypes with <code>H5Dget_type()</code> are + able to share the datatype with other datasets in the same file. +<dt><strong>Parameters:</strong> + <dl> + <dt>hid_t</em> <code>type</code> + <dd>Datatype identifier. + </dl> +<dt><strong>Returns:</strong> + <dd>The successful return values are TRUE if committed, else FALSE. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-InsertArray">H5Tinsert_array</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em><code>H5Tinsert_array</code>(<em>hid_t</em> <code>parent_id</code>, + <em>const char *</em><code>name</code>, + <em>size_t</em> <code>offset</code>, + <em>int</em> <code>ndims</code>, + <em>const size_t *</em><code>dim</code>, + <em>const int *</em><code>perm</code>, + <em>hid_t</em> <code>member_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Adds an array member to a compound datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tinsert_array</code> adds a new member to the + compound datatype <code>parent_id</code>. + The member is an array with <code>ndims</code> dimensionality + and the size of the array is </em><code>dim</code>. + The new member's name, <code>name</code>, must be unique + within the compound datatype. + The <code>offset</code> argument defines the start of the + member in an instance of the compound datatype and + <code>member_id</code> is the type identifier of the new member. + The total member size should be relatively small. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>parent_id</code> + <dd>Identifier of the parent compound datatype. + <dt><em>const char *</em><code>name</code> + <dd>Name of new member. + <dt><em>size_t</em> <code>offset</code> + <dd>Offset to start of new member within compound datatype. + <dt><em>int</em> <code>ndims</code> + <dd>Dimensionality of new member. + <dt><em>const size_t *</em><code>dim</code> + <dd>Size of new member array. + <dt><em>const int *</em><code>perm</code> + <dd>Pointer to buffer to store the permutation vector of + the field. + <dt><em>hid_t</em> <code>member_id</code> + <dd>Identifier of the datatype of the new member. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Find">H5Tfind</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_conv_t</em> <code>H5Tfind</code>(<em>hid_t</em> <code>src_id</code>, + <em>hid_t</em> <code>dst_id</code>, + <em>H5T_cdata_t **</em><code>pcdata</code> + ) +<dt><strong>Purpose:</strong> + <dd>Finds a conversion function. +<dt><strong>Description:</strong> + <dd><code>H5Tfind</code> finds a conversion function that can + handle a conversion from type <code>src_id</code> to type + <code>dst_id</code>. + The <code>pcdata</code> argument is a pointer to a pointer + to type conversion data which was created and initialized + by the soft type conversion function of this path when the + conversion function was installed on the path. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>src_id</code> + <dd>Identifier for the source datatype. + <dt><em>hid_t</em> <code>dst_id</code> + <dd>Identifier for the destination datatype. + <dt><em>H5T_cdata_t **</em><code>pcdata</code> + <dd>Pointer to type conversion data. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a pointer to a suitable conversion function if successful. + Otherwise returns NULL. +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Convert">H5Tconvert</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tconvert</code>(<em>hid_t</em> <code>src_id</code>, + <em>hid_t</em> <code>dst_id</code>, + <em>size_t</em> <code>nelmts</code>, + <em>void *</em><code>buf</code>, + <em>void *</em><code>background</code> + ) +<dt><strong>Purpose:</strong> + <dd>Converts data from between specified datatypes. +<dt><strong>Description:</strong> + <dd><code>H5Tconvert</code> converts <code>nelmts</code> elements + from the type specified by the <code>src_id</code> identifier + to type <code>dst_id</code>. + The source elements are packed in <code>buf</code> and on return + the destination will be packed in <code>buf</code>. + That is, the conversion is performed in place. + The optional background buffer is an array of <code>nelmts</code> + values of destination type which are merged with the converted + values to fill in cracks (for instance, <code>background</code> + might be an array of structs with the <code>a</code> and + <code>b</code> fields already initialized and the conversion + of <code>buf</code> supplies the <code>c</code> and <code>d</code> + field values). +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>src_id</code> + <dd>Identifier for the source datatype. + <dt><em>hid_t</em> <code>dst_id</code> + <dd>Identifier for the destination datatype. + <dt><em>size_t</em> <code>nelmts</code> + <dd>Size of array <code>buf</code>. + <dt><em>void *</em><code>buf</code> + <dd>Array containing pre- and post-conversion values. + <dt><em>void *</em><code>background</code> + <dd>Optional background buffer. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetOverflow">H5Tset_overflow</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tset_overflow</code>(<em>H5T_overflow_t</em> <code>func</code>) +<dt><strong>Purpose:</strong> + <dd>Sets the overflow handler to a specified function. +<dt><strong>Description:</strong> + <dd><code>H5Tset_overflow</code> sets the overflow handler + to be the function specified by <code>func</code>. + <code>func</code> will be called for all datatype conversions that + result in an overflow. + <p> + See the definition of <code>H5T_overflow_t</code> in + <code>H5Tpublic.h</code> for documentation + of arguments and return values. + The prototype for <code>H5T_overflow_t</code> is as follows:<br> + <code>herr_t (*H5T_overflow_t)(hid_t src_id, hid_t dst_id, + void *src_buf, void *dst_buf); + </code> + <p> + The NULL pointer may be passed to remove the overflow handler. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5T_overflow_t</em> <code>func</code> + <dd>Overflow function. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetOverflow">H5Tget_overflow</a> +<dt><strong>Signature:</strong> + + +H5Tget_overflow () + <dd><em>H5T_overflow_t</em> <code>H5Tget_overflow</code>(<code>void</code>) +<dt><strong>Purpose:</strong> + <dd>Returns a pointer to the current global overflow function. +<dt><strong>Description:</strong> + <dd><code>H5Tset_overflow</code> returns a pointer + to the current global overflow function. + This is an application-defined function that is called whenever a + datatype conversion causes an overflow. +<dt><strong>Parameters:</strong> + <dl> + <dt>None. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a pointer to an application-defined function if successful. + Otherwise returns NULL; this can happen if no overflow handling + function is registered. +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Create">H5Tcreate</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Tcreate</code>(<em>H5T_class_t </em><code>class</code>, + <em>size_t</em><code>size</code> + ) +<dt><strong>Purpose:</strong> + <dd>Creates a new dataype. +<dt><strong>Description:</strong> + <dd><code>H5Tcreate</code> creates a new dataype of the specified + class with the specified number of bytes. + Currently, only the <code>H5T_COMPOUND</code> datatype class is + supported with this function. Use <code>H5Tcopy</code> + to create integer or floating-point datatypes. + The datatype identifier returned from this function should be + released with <code>H5Tclose</code> or resource leaks will result. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5T_class_t</em> <code>class</code> + <dd>Class of datatype to create. + <dt><em>size_t</em> <code>size</code> + <dd>The number of bytes in the datatype to create. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns datatype identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Copy">H5Tcopy</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Tcopy</code>(<em>hid_t </em><code>type_id</code>) +<dt><strong>Purpose:</strong> + <dd>Copies an existing datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tcopy</code> copies an existing datatype. + The returned type is always transient and unlocked. + <p> + The <code>type_id</code> argument can be either a datatype + identifier, a predefined datatype (defined in + <code>H5Tpublic.h</code>), or a dataset identifier. + If <code>type_id</code> is a dataset identifier instead of a + datatype identifier, then this function returns a transient, + modifiable datatype which is a copy of the dataset's datatype. + <p> + The datatype identifier returned should be released with + <code>H5Tclose</code> or resource leaks will occur. +<!-- + <p> + Native datatypes supported by the library are: + <ul> <dl> + <dt>H5T_NATIVE_CHAR + <dd> Native character type, declare dataset array as 'char' + <dt>H5T_NATIVE_UCHAR + <dd> Native unsigned character type, declare dataset array as 'unsigned char' + <dt>H5T_NATIVE_SHORT + <dd> Native short type, declare dataset array as 'short' + <dt>H5T_NATIVE_USHORT + <dd> Native unsigned short type, declare dataset array as 'unsigned short' + <dt>H5T_NATIVE_INT + <dd> Native int type, declare dataset array as 'int' + <dt>H5T_NATIVE_UINT + <dd> Native unsigned int type, declare dataset array as 'unsigned int' + <dt>H5T_NATIVE_LONG + <dd> Native long type, declare dataset array as 'unsigned long' + <dt>H5T_NATIVE_ULONG + <dd> Native unsigned long type, declare dataset array as 'unsigned long' + <dt>H5T_NATIVE_LLONG + <dd> Native long long type, declare dataset array as 'unsigned long long' + <dt>H5T_NATIVE_ULLONG + <dd> Native unsigned long long type, declare dataset array as 'unsigned long long' + <dt>H5T_NATIVE_INT8 + <dd> Native signed 8-bit type, declare dataset array as 'int8' + <dt>H5T_NATIVE_UINT8 + <dd> Native unsigned 8-bit type, declare dataset array as 'uint8' + <dt>H5T_NATIVE_INT16 + <dd> Native signed 16-bit type, declare dataset array as 'int16' + <dt>H5T_NATIVE_UINT16 + <dd> Native unsigned 16-bit type, declare dataset array as 'uint16' + <dt>H5T_NATIVE_INT32 + <dd> Native signed 32-bit type, declare dataset array as 'int32' + <dt>H5T_NATIVE_UINT32 + <dd> Native unsigned 32-bit type, declare dataset array as 'uint32' + <dt>H5T_NATIVE_INT64 + <dd> Native signed 64-bit type, declare dataset array as 'uint64' + <dt>H5T_NATIVE_UINT64 + <dd> Native unsigned 64-bit type, declare dataset array as 'uint64' + <dt>H5T_NATIVE_FLOAT + <dd> Native single-precision float type, declare dataset array as 'float' + <dt>H5T_NATIVE_DOUBLE + <dd> Native double-precision float type, declare dataset array as 'double' + </dl> </ul> +--> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to copy. Can be a datatype + identifier, a predefined datatype (defined in + <code>H5Tpublic.h</code>), or a dataset identifier. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a datatype identifier if successful; + otherwise FAIL (-1) +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Equal">H5Tequal</a> +<dt><strong>Signature:</strong> + <dd><em>hbool_t </em><code>H5Tequal</code>(<em>hid_t </em><code>type_id1</code>, + <em>hid_t</em><code>type_id2</code> + ) +<dt><strong>Purpose:</strong> + <dd>Determines whether two datatype identifiers refer to the same datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tequal</code> determines whether two datatype identifiers + refer to the same datatype. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id1</code> + <dd>Identifier of datatype to compare. + <dt><em>hid_t</em> <code>type_id2</code> + <dd>Identifier of datatype to compare. + </dl> +<dt><strong>Returns:</strong> + <dd>When successful, returns TRUE if the datatype identifiers + refer to the same datatype, else FALSE. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Lock">H5Tlock</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tlock</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Locks a datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tlock</code> locks the datatype specified by the + <code>type_id</code> identifier, making it read-only and + non-destrucible. This is normally done by the library for + predefined datatypes so the application does not + inadvertently change or delete a predefined type. + Once a datatype is locked it can never be unlocked. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to lock. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetClass">H5Tget_class</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_class_t </em><code>H5Tget_class</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Returns the datatype class identifier. +<dt><strong>Description:</strong> + <dd><code>H5Tget_class</code> returns the datatype class identifier. + <p> + Valid class identifiers, as defined in <code>H5Tpublic.h</code>, are: + <ul><li><code>H5T_INTEGER</code> (<code>0</code>) + <li><code>H5T_FLOAT</code> (<code>1</code>) + <li><code>H5T_TIME</code> (<code>2</code>) + <li><code>H5T_STRING</code> (<code>3</code>) + <li><code>H5T_BITFIELD</code> (<code>4</code>) + <li><code>H5T_OPAQUE</code> (<code>5</code>) + <li><code>H5T_COMPOUND</code> (<code>6</code>) + </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns datatype class identifier if successful; + otherwise H5T_NO_CLASS (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetSize">H5Tget_size</a> +<dt><strong>Signature:</strong> + <dd><em>size_t </em><code>H5Tget_size</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Returns the size of a datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tget_size</code> returns the size of a datatype in bytes. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns the size of the datatype in bytes if successful; + otherwise 0. +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetSize">H5Tset_size</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_size</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em><code>size</code> + ) +<dt><strong>Purpose:</strong> + <dd>Sets the total size for an atomic datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tset_size</code> sets the total size in bytes, + <code>size</code>, for an atomic datatype (this operation + is not permitted on compound datatypes). If the size is + decreased so that the significant bits of the datatype extend beyond + the edge of the new size, then the `offset' property is decreased + toward zero. If the `offset' becomes zero and the significant + bits of the datatype still hang over the edge of the new size, then + the number of significant bits is decreased. + Adjusting the size of an H5T_STRING automatically sets the precision + to 8*size. All datatypes have a positive size. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to change size. + <dt><em>size_t</em> <code>size</code> + <dd>Size in bytes to modify datatype. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetOrder">H5Tget_order</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_order_t </em><code>H5Tget_order</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Returns the byte order of an atomic datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tget_order</code> returns the byte order of an + atomic datatype. + <p> + Possible return values are: + <ul><dl> + <dt><code>H5T_ORDER_LE</code> (<code>0</code>) + <dd>Little endian byte ordering (default). + <dt><code>H5T_ORDER_BE</code> (<code>1</code>) + <dd>Big endian byte ordering. + <dt><code>H5T_ORDER_VAX</code> (<code>2</code>) + <dd>VAX mixed byte ordering (not currently supported). + </dl></ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a byte order constant if successful; + otherwise <code>H5T_ORDER_ERROR</code> (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetOrder">H5Tset_order</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_order</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_order_t</em><code>order</code> + ) +<dt><strong>Purpose:</strong> + <dd>Sets the byte ordering of an atomic datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tset_order</code> sets the byte ordering of an atomic datatype. + Byte orderings currently supported are: + <ul> <dl> + <dt>H5T_ORDER_LE (<code>0</code>) + <dd> Little-endian byte ordering (default). + <dt>H5T_ORDER_BE (<code>1</code>) + <dd> Big-endian byte ordering. + <dt>H5T_ORDER_VAX (<code>2</code>) + <dd>VAX mixed byte ordering (not currently supported). + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to set. + <dt><em>H5T_order_t</em> <code>order</code> + <dd>Byte ordering constant. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetPrecision">H5Tget_precision</a> +<dt><strong>Signature:</strong> + <dd><em>size_t </em><code>H5Tget_precision</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Returns the precision of an atomic datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tget_precision</code> returns the precision of an atomic datatype. The + precision is the number of significant bits which, unless padding is + present, is 8 times larger than the value returned by H5Tget_size(). +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns the number of significant bits if successful; + otherwise 0. +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetPrecision">H5Tset_precision</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_precision</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em><code>precision</code> + ) +<dt><strong>Purpose:</strong> + <dd>Sets the precision of an atomic datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tset_precision</code> sets the precision of an atomic datatype. + The precision is the number of significant bits which, unless padding + is present, is 8 times larger than the value returned by H5Tget_size(). + <P>If the precision is increased then the offset is decreased and then + the size is increased to insure that significant bits do not "hang + over" the edge of the datatype. + <P>Changing the precision of an H5T_STRING automatically changes the + size as well. The precision must be a multiple of 8. + <P>When decreasing the precision of a floating point type, set the + locations and sizes of the sign, mantissa, and exponent fields + first. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to set. + <dt><em>size_t</em> <code>precision</code> + <dd>Number of bits of precision for datatype. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetOffset">H5Tget_offset</a> +<dt><strong>Signature:</strong> + <dd><em>size_t </em><code>H5Tget_offset</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves the bit offset of the first significant bit. +<dt><strong>Description:</strong> + <dd><code>H5Tget_offset</code> retrieves the bit offset of the first significant bit. + The signficant bits of an atomic datum can be offset from the beginning + of the memory for that datum by an amount of padding. The `offset' + property specifies the number of bits of padding that appear to the + "right of" the value. That is, if we have a 32-bit datum with 16-bits + of precision having the value 0x1122 then it will be layed out in + memory as (from small byte address toward larger byte addresses): + <br> + <br> + + <table border align=center cellpadding=4 width="80%"> + <tr align=center> + <th width="20%">Byte Position</th> + <th width="20%">Big-Endian Offset=0</th> + <th width="20%">Big-Endian Offset=16</th> + <th width="20%">Little-Endian Offset=0</th> + <th width="20%">Little-Endian Offset=16</th> + </tr> + <tr align=center> + <td>0:</td> + <td>[ pad]</td> + <td>[0x11]</td> + <td>[0x22]</td> + <td>[ pad]</td> + </tr> + <tr align=center> + <td>1:</td> + <td>[ pad]</td> + <td>[0x22]</td> + <td>[0x11]</td> + <td>[ pad]</td> + </tr> + <tr align=center> + <td>2:</td> + <td>[0x11]</td> + <td>[ pad]</td> + <td>[ pad]</td> + <td>[0x22]</td> + </tr> + <tr align=center> + <td>3:</td> + <td>[0x22]</td> + <td>[ pad]</td> + <td>[ pad]</td> + <td>[0x11]</td> + </tr> + </table> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a positive offset value if successful; + otherwise 0. +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetOffset">H5Tset_offset</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_offset</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em> <code>offset</code> + ) +<dt><strong>Purpose:</strong> + <dd>Sets the bit offset of the first significant bit. +<dt><strong>Description:</strong> + <dd><code>H5Tset_offset</code> sets the bit offset of the first significant bit. The + signficant bits of an atomic datum can be offset from the beginning of + the memory for that datum by an amount of padding. The `offset' + property specifies the number of bits of padding that appear to the + "right of" the value. That is, if we have a 32-bit datum with 16-bits + of precision having the value 0x1122 then it will be layed out in + memory as (from small byte address toward larger byte addresses): + <br> + <br> + + <table border align=center cellpadding=4 width="80%"> + <tr align=center> + <th width="20%">Byte Position</th> + <th width="20%">Big-Endian Offset=0</th> + <th width="20%">Big-Endian Offset=16</th> + <th width="20%">Little-Endian Offset=0</th> + <th width="20%">Little-Endian Offset=16</th> + </tr> + <tr align=center> + <td>0:</td> + <td>[ pad]</td> + <td>[0x11]</td> + <td>[0x22]</td> + <td>[ pad]</td> + </tr> + <tr align=center> + <td>1:</td> + <td>[ pad]</td> + <td>[0x22]</td> + <td>[0x11]</td> + <td>[ pad]</td> + </tr> + <tr align=center> + <td>2:</td> + <td>[0x11]</td> + <td>[ pad]</td> + <td>[ pad]</td> + <td>[0x22]</td> + </tr> + <tr align=center> + <td>3:</td> + <td>[0x22]</td> + <td>[ pad]</td> + <td>[ pad]</td> + <td>[0x11]</td> + </tr> + </table> + +<P>If the offset is incremented then the total size is +incremented also if necessary to prevent significant bits of +the value from hanging over the edge of the datatype. + +<P>The offset of an H5T_STRING cannot be set to anything but +zero. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to set. + <dt><em>size_t</em> <code>offset</code> + <dd>Offset of first significant bit. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetPad">H5Tget_pad</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tget_pad</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_pad_t *</em> <code>lsb</code>, + <em>H5T_pad_t *</em> <code>msb</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves the padding type of the least and most-significant bit padding. +<dt><strong>Description:</strong> + <dd><code>H5Tget_pad</code> retrieves the padding type of the least and most-significant + bit padding. Valid types are: + <ul> <dl> + <dt>H5T_PAD_ZERO (<code>0</code>) + <dd>Set background to zeros. + <dt>H5T_PAD_ONE (<code>1</code>) + <dd>Set background to ones. + <dt>H5T_PAD_BACKGROUND (<code>2</code>) + <dd>Leave background alone. + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>IN: Identifier of datatype to query. + <dt><em>H5T_pad_t *</em> <code>lsb</code> + <dd>OUT: Pointer to location to return least-significant + bit padding type. + <dt><em>H5T_pad_t *</em> <code>msb</code> + <dd>OUT: Pointer to location to return most-significant + bit padding type. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetPad">H5Tset_pad</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_pad</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_pad_t</em> <code>lsb</code>, + <em>H5T_pad_t</em> <code>msb</code> + ) +<dt><strong>Purpose:</strong> + <dd>Sets the least and most-significant bits padding types. +<dt><strong>Description:</strong> + <dd><code>H5Tset_pad</code> sets the least and most-significant bits padding types. + <ul> <dl> + <dt>H5T_PAD_ZERO (<code>0</code>) + <dd>Set background to zeros. + <dt>H5T_PAD_ONE (<code>1</code>) + <dd>Set background to ones. + <dt>H5T_PAD_BACKGROUND (<code>2</code>) + <dd>Leave background alone. + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to set. + <dt><em>H5T_pad_t</em> <code>lsb</code> + <dd>Padding type for least-significant bits. + <dt><em>H5T_pad_t</em> <code>msb</code> + <dd>Padding type for most-significant bits. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetSign">H5Tget_sign</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_sign_t </em><code>H5Tget_sign</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves the sign type for an integer type. +<dt><strong>Description:</strong> + <dd><code>H5Tget_sign</code> retrieves the sign type for an integer type. + Valid types are: + <ul> <dl> + <dt>H5T_SGN_NONE (<code>0</code>) + <dd>Unsigned integer type. + <dt>H5T_SGN_2 (<code>1</code>) + <dd>Two's complement signed integer type. + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a valid sign type if successful; + otherwise <code>H5T_SGN_ERROR</code> (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetSign">H5Tset_sign</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_sign</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_sign_t</em> <code>sign</code> + ) +<dt><strong>Purpose:</strong> + <dd>Sets the sign proprety for an integer type. +<dt><strong>Description:</strong> + <dd><code>H5Tset_sign</code> sets the sign proprety for an integer type. + <ul> <dl> + <dt>H5T_SGN_NONE (<code>0</code>) + <dd>Unsigned integer type. + <dt>H5T_SGN_2 (<code>1</code>) + <dd>Two's complement signed integer type. + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to set. + <dt><em>H5T_sign_t</em> <code>sign</code> + <dd>Sign type. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetFields">H5Tget_fields</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tget_fields</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t *</em> <code>epos</code>, + <em>size_t *</em> <code>esize</code>, + <em>size_t *</em> <code>mpos</code>, + <em>size_t *</em> <code>msize</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves floating point datatype bit field information. +<dt><strong>Description:</strong> + <dd><code>H5Tget_fields</code> retrieves information about the locations of the various + bit fields of a floating point datatype. The field positions are bit + positions in the significant region of the datatype. Bits are + numbered with the least significant bit number zero. + Any (or even all) of the arguments can be null pointers. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>IN: Identifier of datatype to query. + <dt><em>size_t *</em> <code>epos</code> + <dd>OUT: Pointer to location to return exponent bit-position. + <dt><em>size_t *</em> <code>esize</code> + <dd>OUT: Pointer to location to return size of exponent in bits. + <dt><em>size_t *</em> <code>mpos</code> + <dd>OUT: Pointer to location to return mantissa bit-position. + <dt><em>size_t *</em> <code>msize</code> + <dd>OUT: Pointer to location to return size of mantissa in bits. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetFields">H5Tset_fields</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_fields</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em> <code>epos</code>, + <em>size_t</em> <code>esize</code>, + <em>size_t</em> <code>mpos</code>, + <em>size_t</em> <code>msize</code> + ) +<dt><strong>Purpose:</strong> + <dd>Sets locations and sizes of floating point bit fields. +<dt><strong>Description:</strong> + <dd><code>H5Tset_fields</code> sets the locations and sizes of the various floating + point bit fields. The field positions are bit positions in the + significant region of the datatype. Bits are numbered with the least + significant bit number zero. + + <P>Fields are not allowed to extend beyond the number of bits of + precision, nor are they allowed to overlap with one another. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to set. + <dt><em>size_t</em> <code>epos</code> + <dd>Exponent bit position. + <dt><em>size_t</em> <code>esize</code> + <dd>Size of exponent in bits. + <dt><em>size_t</em> <code>mpos</code> + <dd>Mantissa bit position. + <dt><em>size_t</em> <code>msize</code> + <dd>Size of mantissa in bits. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetEbias">H5Tget_ebias</a> +<dt><strong>Signature:</strong> + <dd><em>size_t </em><code>H5Tget_ebias</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves the exponent bias of a floating-point type. +<dt><strong>Description:</strong> + <dd><code>H5Tget_ebias</code> retrieves the exponent bias of a floating-point type. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns the bias if successful; + otherwise 0. +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetEbias">H5Tset_ebias</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_ebias</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em> <code>ebias</code> + ) +<dt><strong>Purpose:</strong> + <dd>Sets the exponent bias of a floating-point type. +<dt><strong>Description:</strong> + <dd><code>H5Tset_ebias</code> sets the exponent bias of a floating-point type. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to set. + <dt><em>size_t</em> <code>ebias</code> + <dd>Exponent bias value. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetNorm">H5Tget_norm</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_norm_t </em><code>H5Tget_norm</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves mantissa normalization of a floating-point datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tget_norm</code> retrieves the mantissa normalization of + a floating-point datatype. Valid normalization types are: + <ul> <dl> + <dt>H5T_NORM_IMPLIED (<code>0</code>) + <dd>MSB of mantissa is not stored, always 1 + <dt>H5T_NORM_MSBSET (<code>1</code>) + <dd>MSB of mantissa is always 1 + <dt>H5T_NORM_NONE (<code>2</code>) + <dd>Mantissa is not normalized + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a valid normalization type if successful; + otherwise <code>H5T_NORM_ERROR</code> (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetNorm">H5Tset_norm</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_norm</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_norm_t</em> <code>norm</code> + ) +<dt><strong>Purpose:</strong> + <dd>Sets the mantissa normalization of a floating-point datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tset_norm</code> sets the mantissa normalization of + a floating-point datatype. Valid normalization types are: + <ul> <dl> + <dt>H5T_NORM_IMPLIED (<code>0</code>) + <dd>MSB of mantissa is not stored, always 1 + <dt>H5T_NORM_MSBSET (<code>1</code>) + <dd>MSB of mantissa is always 1 + <dt>H5T_NORM_NONE (<code>2</code>) + <dd>Mantissa is not normalized + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to set. + <dt><em>H5T_norm_t</em> <code>norm</code> + <dd>Mantissa normalization type. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetInpad">H5Tget_inpad</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_pad_t </em><code>H5Tget_inpad</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves the internal padding type for unused bits in floating-point datatypes. +<dt><strong>Description:</strong> + <dd><code>H5Tget_inpad</code> retrieves the internal padding type for + unused bits in floating-point datatypes. + Valid padding types are: + <ul> <dl> + <dt>H5T_PAD_ZERO (<code>0</code>) + <dd>Set background to zeros. + <dt>H5T_PAD_ONE (<code>1</code>) + <dd>Set background to ones. + <dt>H5T_PAD_BACKGROUND (<code>2</code>) + <dd>Leave background alone. + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a valid padding type if successful; + otherwise <code>H5T_PAD_ERROR</code> (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetInpad">H5Tset_inpad</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_inpad</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_pad_t</em> <code>inpad</code> + ) +<dt><strong>Purpose:</strong> + <dd>Fills unused internal floating point bits. +<dt><strong>Description:</strong> + <dd>If any internal bits of a floating point type are unused + (that is, those significant bits which are not part of the + sign, exponent, or mantissa), then <code>H5Tset_inpad</code> will be filled + according to the value of the padding value property <code>inpad</code>. + Valid padding types are: + <ul> <dl> + <dt>H5T_PAD_ZERO (<code>0</code>) + <dd>Set background to zeros. + <dt>H5T_PAD_ONE (<code>1</code>) + <dd>Set background to ones. + <dt>H5T_PAD_BACKGROUND (<code>2</code>) + <dd>Leave background alone. + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to modify. + <dt><em>H5T_pad_t</em> <code>pad</code> + <dd>Padding type. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetCset">H5Tget_cset</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_cset_t </em><code>H5Tget_cset</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves the character set type of a string datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tget_cset</code> retrieves the character set type + of a string datatype. Valid character set types are: + <ul> <dl> + <dt>H5T_CSET_ASCII (<code>0</code>) + <dd>Character set is US ASCII + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a valid character set type if successful; + otherwise <code>H5T_CSET_ERROR</code> (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetCset">H5Tset_cset</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_cset</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_cset_t</em> <code>cset</code> + ) +<dt><strong>Purpose:</strong> + <dd>Sets character set to be used. +<dt><strong>Description:</strong> + <dd><code>H5Tset_cset</code> the character set to be used. + <p> + HDF5 is able to distinguish between character sets of different + nationalities and to convert between them to the extent possible. + Valid character set types are: + <ul> <dl> + <dt>H5T_CSET_ASCII (<code>0</code>) + <dd>Character set is US ASCII. + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to modify. + <dt><em>H5T_cset_t</em> <code>cset</code> + <dd>Character set type. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetStrpad">H5Tget_strpad</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_str_t </em><code>H5Tget_strpad</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves the string padding method for a string datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tget_strpad</code> retrieves the string padding method + for a string datatype. Valid string padding types are: + <ul> <dl> + <dt>H5T_STR_NULL (<code>0</code>) + <dd>Pad with zeros (as C does) + <dt>H5T_STR_SPACE (<code>1</code>) + <dd>Pad with spaces (as FORTRAN does) + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a valid string padding type if successful; + otherwise <code>H5T_STR_ERROR</code> (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetStrpad">H5Tset_strpad</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_strpad</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_str_t</em> <code>strpad</code> + ) +<dt><strong>Purpose:</strong> + <dd>Defines the storage mechanism for character strings. +<dt><strong>Description:</strong> + <dd>The method used to store character strings differs with the + programming language: C usually null terminates strings while + Fortran left-justifies and space-pads strings. + <code>H5Tset_strpad</code> defines the storage mechanism for the string. + Valid string padding values are: + <ul> <dl> + <dt>H5T_STR_NULL (<code>0</code>) + <dd>Pad with zeros (as C does) + <dt>H5T_STR_SPACE (<code>1</code>) + <dd>Pad with spaces (as FORTRAN does) + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to modify. + <dt><em>H5T_str_t</em> <code>strpad</code> + <dd>String padding type. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetNmembers">H5Tget_nmembers</a> +<dt><strong>Signature:</strong> + <dd><em>intn </em><code>H5Tget_nmembers</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves the number of fields in a compound datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tget_nmembers</code> retrieves the number of fields a compound datatype has. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns number of members datatype has if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetMemberName">H5Tget_member_name</a> +<dt><strong>Signature:</strong> + <dd><em>char *</em> <code>H5Tget_member_name</code>(<em>hid_t </em><code>type_id</code>, + <em>int</em> <code>field_idx</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves the name of a field of a compound datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tget_member_name</code> retrieves the name of a field + of a compound datatype. Fields are stored in no particular + order, with indexes 0 through N-1, where N is the value returned + by <code>H5Tget_nmembers()</code>. The name of the field is + allocated with <code>malloc()</code> and the caller is responsible + for freeing the memory used by the name. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + <dt><em>int</em> <code>field_idx</code> + <dd>Field index (0-based) of the field name to retrieve. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a valid pointer if successful; + otherwise NULL. +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetMemberDims">H5Tget_member_dims</a> +<dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Tget_member_dims</code>(<em>hid_t </em><code>type_id</code>, + <em>int</em> <code>field_idx</code>, + <em>size_t *</em><code>dims</code>, + <em>int *</em><code>perm</code> + ) +<dt><strong>Purpose:</strong> + <dd>Returns the dimensionality of the field. +<dt><strong>Description:</strong> + <dd><code>H5Tget_member_dims</code> returns the dimensionality of + the field. The dimensions and permuation vector are returned + through arguments <code>dims</code> and <code>perm</code>, + both arrays of at least four elements. + Either (or even both) may be null pointers. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + <dt><em>int</em> <code>field_idx</code> + <dd>Field index (0-based) of the field <code>dims</code> + to retrieve. + <dt><em>size_t *</em> <code>dims</code> + <dd>Pointer to buffer to store the dimensions of the field. + <dt><em>int *</em> <code>perm</code> + <dd>Pointer to buffer to store the permutation vector of + the field. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns the number of dimensions, a number from 0 to 4, + if successful. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetMemberType">H5Tget_member_type</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t</em> <code>H5Tget_member_type</code>(<em>hid_t </em><code>type_id</code>, + <em>int</em> <code>field_idx</code> + ) +<dt><strong>Purpose:</strong> + <dd>Returns the datatype of the specified member. +<dt><strong>Description:</strong> + <dd><code>H5Tget_member_type</code> returns the datatype of the specified member. The caller + should invoke H5Tclose() to release resources associated with the type. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to query. + <dt><em>int</em> <code>field_idx</code> + <dd>Field index (0-based) of the field type to retrieve. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns the identifier of a copy of the datatype of the field + if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Insert">H5Tinsert</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tinsert</code>(<em>hid_t </em><code>type_id</code>, + <em>const char *</em> <code>name</code>, + <em>off_t</em> <code>offset</code>, + <em>hid_t</em> <code>field_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Adds a new member to a compound datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tinsert</code> adds another member to the compound datatype + <code>type_id</code>. The new member has a <code>name</code> which + must be unique within the compound datatype. + The <code>offset</code> argument defines the start of the member + in an instance of the compound datatype, and <code>field_id</code> + is the datatype identifier of the new member. + <P> + Note: All members of a compound datatype must be atomic; a + compound datatype cannot have a member which is a compound + datatype. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of compound datatype to modify. + <dt><em>const char *</em> <code>name</code> + <dd>Name of the field to insert. + <dt><em>off_t</em> <code>offset</code> + <dd>Offset in memory structure of the field to insert. + <dt><em>hid_t</em> <code>field_id</code> + <dd>Datatype identifier of the field to insert. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Pack">H5Tpack</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tpack</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Recursively removes padding from within a compound datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tpack</code> recursively removes padding from within a compound + datatype to make it more efficient (space-wise) to store that data. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to modify. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-RegisterHard">H5Tregister_hard</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tregister_hard</code>(<em>const char + *</em> <code>name</code>, <em>hid_t </em><code>src_id</code>, + <em>hid_t</em> <code>dst_id</code>, + <em>H5T_conv_t</em> <code>func</code> + ) +<dt><strong>Purpose:</strong> + <dd>Registers a hard conversion function. +<dt><strong>Description:</strong> + <dd><code>H5Tregister_hard</code> registers a hard conversion function for a datatype + conversion path. The path is specified by the source and destination + datatypes <code>src_id</code> and <code>dst_id</code>. A conversion + path can only have one hard function, so <code>func</code> replaces any + previous hard function. + <p> + If <code>func</code> is the null pointer then any hard function + registered for this path is removed from this path. The soft functions + are then used when determining which conversion function is appropriate + for this path. The <code>name</code> argument is used only + for debugging and should be a short identifier for the function. + <p> + The type of the conversion function pointer is declared as: + <br> + <code>typedef</code> <em>herr_t </em>(<code>*H5T_conv_t</code>) (<em>hid_t </em><code>src_id</code>, + <em>hid_t </em><code>dst_id</code>, + <em>H5T_cdata_t *</em><code>cdata</code>, + <em>size_t </em><code>nelmts</code>, + <em>void *</em><code>buf</code>, + <em>void *</em><code>bkg)</code>; +<dt><strong>Parameters:</strong> + <dl> + <dt><em>const char *</em> <code>name</code> + <dd>Name displayed in diagnostic output. + <dt><em>hid_t</em> <code>src_id</code> + <dd>Identifier of source datatype. + <dt><em>hid_t</em> <code>dst_id</code> + <dd>Identifier of destination datatype. + <dt><em>H5T_conv_t</em> <code>func</code> + <dd>Function to convert between source and destination datatypes. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-RegisterSoft">H5Tregister_soft</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tregister_soft</code>(<em>const char + *</em> <code>name</code>, <em>H5T_class_t </em><code>src_cls</code>, + <em>H5T_class_t</em> <code>dst_cls</code>, + <em>H5T_conv_t</em> <code>func</code> + ) +<dt><strong>Purpose:</strong> + <dd>Registers a soft conversion function. +<dt><strong>Description:</strong> + <dd><code>H5Tregister_soft</code> registers a soft conversion function by adding it to the + end of the master soft list and replacing the soft function in all + applicable existing conversion paths. The <code>name</code> + is used only for debugging and should be a short identifier + for the function. + <P> + The type of the conversion function pointer is declared as: + <br> + <code>typedef</code> <em>herr_t </em>(<code>*H5T_conv_t</code>) (<em>hid_t </em><code>src_id</code>, + <em>hid_t </em><code>dst_id</code>, + <em>H5T_cdata_t *</em><code>cdata</code>, + <em>size_t </em><code>nelmts</code>, + <em>void *</em><code>buf</code>, + <em>void *</em><code>bkg)</code>; +<dt><strong>Parameters:</strong> + <dl> + <dt><em>const char *</em> <code>name</code> + <dd>Name displayed in diagnostic output. + <dt><em>H5T_class_t</em> <code>src_cls</code> + <dd>Identifier of source datatype class. + <dt><em>H5T_class_t</em> <code>dst_cls</code> + <dd>Identifier of destination datatype class. + <dt><em>H5T_conv_t</em> <code>func</code> + <dd>Function to convert between source and destination datatypes. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Unregister">H5Tunregister</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tunregister</code>(<em>H5T_conv_t</em> <code>func</code> + ) +<dt><strong>Purpose:</strong> + <dd>Removes a conversion function from all conversion paths. +<dt><strong>Description:</strong> + <dd><code>H5Tunregister</code> removes a conversion function from all conversion paths. + <P> + The type of the conversion function pointer is declared as: + <br> + <code>typedef</code> <em>herr_t </em>(<code>*H5T_conv_t</code>) (<em>hid_t </em><code>src_id</code>, + <em>hid_t </em><code>dst_id</code>, + <em>H5T_cdata_t *</em><code>cdata</code>, + <em>size_t </em><code>nelmts</code>, + <em>void *</em><code>buf</code>, + <em>void *</em><code>bkg)</code>; +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5T_conv_t</em> <code>func</code> + <dd>Function to remove from conversion paths. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Close">H5Tclose</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tclose</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Releases a datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tclose</code> releases a datatype. Further access + through the datatype identifier is illegal. Failure to release + a datatype with this call will result in resource leaks. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype 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> +<a href="RM_H5S.html">H5S</a> +H5T +<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> diff --git a/doc/html/RM_H5Z.html b/doc/html/RM_H5Z.html new file mode 100644 index 0000000..a5ef92c --- /dev/null +++ b/doc/html/RM_H5Z.html @@ -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> |