summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/html/H5.api.html4623
1 files changed, 0 insertions, 4623 deletions
diff --git a/doc/html/H5.api.html b/doc/html/H5.api.html
deleted file mode 100644
index 5f3cf78..0000000
--- a/doc/html/H5.api.html
+++ /dev/null
@@ -1,4623 +0,0 @@
-<html><head><title>
-HDF5 Draft API Specification
-</title></head><body>
-
-<center>
-<h1>HDF5: API Specification</h1>
-</center>
-
-<ol type=I>
-<li><a href="#Library">Library</a> - H5&lt;name&gt; - API for global library HDF information/modification
-<ol type=A>
- <li><a href="#Library-DontAtExit">H5dont_atexit</a>
- <li><a href="#Library-Close">H5close</a>
- <li><a href="#Library-Version">H5version</a>
-</ol>
-
-<li><a href="#File">File</a> - H5F&lt;name&gt; - API for accessing HDF files
-<ol type=A>
- <li><a href="#File-Open">H5Fopen</a>
- <li><a href="#File-Create">H5Fcreate</a>
- <li><a href="#File-IsHDF5">H5Fis_hdf5</a>
- <li><a href="#File-GetCreatePlist">H5Fget_create_plist</a>
- <li><a href="#File-Close">H5Fclose</a>
-</ol>
-
-<li><a href="#Plist">Property list</a> - H5P&lt;name&gt; - API for manipulating object property lists
-<ol type=A>
- <li><a href="#Plist-Create">H5Pcreate</a>
- <li><a href="#Plist-GetClass">H5Pget_class</a>
- <li><a href="#Plist-Copy">H5Pcopy</a>
- <li><a href="#Plist-Close">H5Pclose</a>
- <li><a href="#Plist-GetVersion">H5Pget_version</a>
- <li><a href="#Plist-SetUserblock">H5Pset_userblock</a>
- <li><a href="#Plist-GetUserblock">H5Pget_userblock</a>
- <li><a href="#Plist-SetSizes">H5Pset_sizes</a>
- <li><a href="#Plist-GetSizes">H5Pget_sizes</a>
- <li><a href="#Plist-SetMPI">H5Pset_mpi</a>
- <li><a href="#Plist-GetMPI">H5Pget_mpi</a>
- <li><a href="#Plist-SetXfer">H5Pset_xfer</a>
- <li><a href="#Plist-GetXfer">H5Pget_xfer</a>
- <li><a href="#Plist-SetSymK">H5Pset_sym_k</a>
- <li><a href="#Plist-GetSymK">H5Pget_sym_k</a>
- <li><a href="#Plist-SetIstoreK">H5Pset_istore_k</a>
- <li><a href="#Plist-GetIstoreK">H5Pget_istore_k</a>
- <li><a href="#Plist-SetLayout">H5Pset_layout</a>
- <li><a href="#Plist-GetLayout">H5Pget_layout</a>
- <li><a href="#Plist-SetChunk">H5Pset_chunk</a>
- <li><a href="#Plist-GetChunk">H5Pget_chunk</a>
-</ol>
-
-<!--
-<li><a href="#Error">Error</a> - H5E&lt;name&gt; - API for error reporting
-<ol type=A>
- <li><a href="#Error-SetPush">H5Eset_push</a>
-</ol>
--->
-
-<!--
-<li><a href="#Relationships">Relationships</a> - H5R&lt;name&gt; - API for logically linking objects together (ie. attributes)
-<ol type=A>
- <li><a href="#Relationships-GetNumRelations">H5Rget_num_relations</a>
- <li><a href="#Relationships-GetMemberOfOIDs">H5Rget_memberof_oids</a>
- <li><a href="#Relationships-GetAttachedOIDs">H5Rget_attached_oids</a>
- <li><a href="#Relationships-Attach">H5Rattach_oid</a>
-</ol>
--->
-
-<li><a href="#Dataset">Dataset</a> - H5D&lt;name&gt; - API for manipulating scientific datasets. See <a href="Datasets.html">datasets</a>.
-<ol type=A>
- <li><a href="#Dataset-Create">H5Dcreate</a>
- <li><a href="#Dataset-Open">H5Dopen</a>
- <li><a href="#Dataset-GetSpace">H5Dget_space</a>
- <li><a href="#Dataset-GetType">H5Dget_type</a>
- <li><a href="#Dataset-GetCreateParms">H5Dget_create_parms</a>
- <li><a href="#Dataset-Read">H5Dread</a>
- <li><a href="#Dataset-Write">H5Dwrite</a>
- <li><a href="#Dataset-Extend">H5Dextend</a>
- <li><a href="#Dataset-Close">H5Dclose</a>
-</ol>
-
-<li><a href="#Datatype">Datatype</a> - H5T&lt;name&gt; - API for defining dataset element information. See <a href="Datatypes.html">data types</a>.
-<ol type=A>
- <li><a href="#Datatype-Create">H5Tcreate</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-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>
- <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>
- <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-RegisterHard">H5Tregister_hard</a>
- <li><a href="#Datatype-RegisterSoft">H5Tregister_soft</a>
- <li><a href="#Datatype-Unregister">H5Tunregister</a>
- <li><a href="#Datatype-Close">H5Tclose</a>
-</ol>
-
-<li><a href="#Dataspace">Dataspace</a> - H5S&lt;name&gt; - API for defining dataset dataspace
-<ol type=A>
- <li><a href="#Dataspace-CreateSimple">H5Screate_simple</a>
- <li><a href="#Dataspace-Copy">H5Scopy</a>
- <li><a href="#Dataspace-GetNpoints">H5Sget_npoints</a>
- <li><a href="#Dataspace-GetNdims">H5Sget_ndims</a>
- <li><a href="#Dataspace-GetDims">H5Sget_dims</a>
- <li><a href="#Dataspace-IsSimple">H5Sis_simple</a>
- <li><a href="#Dataspace-SetSpace">H5Sset_space</a>
- <li><a href="#Dataspace-SetHyperslab">H5Sset_hyperslab</a>
- <li><a href="#Dataspace-GetHyperslab">H5Sget_hyperslab</a>
- <li><a href="#Dataspace-Close">H5Sclose</a>
-</ol>
-
-<li><a href="#Group">Group</a> - H5G&lt;name&gt; - API for creating physical groups of objects on disk.
-<ol type=A>
- <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-Push">H5Gpush</a>
- <li><a href="#Group-Pop">H5Gpop</a>
- <li><a href="#Group-Close">H5Gclose</a>
-<!--
- <li><a href="#Group-GetNumContents">get_num_contents</a>
- <li><a href="#Group-GetContentInfo">get_content_info</a>
- <li><a href="#Group-GetContentInfoMult">get_content_info_mult</a>
- <li><a href="#Group-GetOIDByName">get_oid_by_name</a>
- <li><a href="#Group-GetOIDByIndex">get_oid_by_index</a>
- <li><a href="#Group-GetNameByOID">get_name_by_oid</a>
- <li><a href="#Group-GetNameByIndex">get_name_by_index</a>
- <li><a href="#Group-InsertItem">insert_item</a>
- <li><a href="#Group-InsertItemMult">insert_item_mult</a>
- <li><a href="#Group-RemoveItem">remove_item</a>
- <li><a href="#Group-RemoveItemMult">remove_item_mult</a>
--->
-</ol>
-
-<li><a href="#Glossary">Glossary</a> - A glossary of data-types used in the APIs
-<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>
-
-</ol>
-
-<hr>
-<h2><a name="Library">Library API Functions</a></h2>
-<P>These functions are designed to provide access to HDF5 application/library
-behavior. They are used to get information about or change global library
-parameters.
-<br>
-<br>
-
-<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>Description:</strong>
- <dd>This routine indicates to the library that an 'atexit()' cleanup routine
- should not be installed. The major (only?) purpose for this is in
- situations where the library is dynamically linked into an application and
- is un-linked from the application before 'exit()' gets callled. In those
- situations, a routine installed with 'atexit()' would jump to a routine
- which was no longer in memory, causing errors.
- 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> <em>none</em>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This routines flushes all data to disk, closes all file handles and
- cleans up all memory used by the library. Generally it is installed
- to be called when the application calls <em>exit</em>, 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> none
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>uintn *</em><code>majversion</code>,
- <em>uintn *</em><code>minversion</code>,
- <em>uintn *</em><code>relversion</code>,
- <em>uintn *</em><code>patversion</code>
- )
-<dt><strong>Description:</strong>
- <dd>This routine retrieves the major, minor, release and patch versions
- of the library which is linked to the application.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>uintn *</em><code>majversion</code>
- <dd>The major version of the library.
- <dt><em>uintn *</em><code>minversion</code>
- <dd>The minor version of the library.
- <dt><em>uintn *</em><code>relversion</code>
- <dd>The release number of the library.
- <dt><em>uintn *</em><code>patversion</code>
- <dd>The patch number of the library.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<h2><a name="File">File API Functions</a></h2>
-<P>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.
-<br>
-<br>
-
-<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>uintn</em> <code>flags</code>,
- <em>hid_t</em> <code>access_plist</code>
- )
-<dt><strong>Description:</strong>
- <dd>This is the primary function for opening existing HDF5 files.
- The <code>flags</code> parameter determines the file
- access mode. There is no read flag, all open files are
- implicitily opened for read access. All flags may be
- combined with the '|' (boolean OR operator) to change the
- behavior of the file open call. The
- <code>access_plist</code> parameter is a property list
- containing additional information required for specific
- methods of access, parallel I/O for example. The
- paramters for access property lists are described in the
- H5P API documentation.
-<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:
- <ul><dl>
- <dt>H5F_ACC_RDWR
- <dd>Allow read and write access to file.
- </dl></ul>
- <dt><em>hid_t</em><code>access_plist</code>
- <dd>Property list indicating the file access properties.
- If parallel file access is desired, this is a collective
- call according to the communicator stored in the
- access_plist. Use 0 for default access properties.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>An ID (of type <em>hid_t</em>) for the file upon success,
- otherwise negative
-</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>uintn</em> <code>flags</code>,
- <em>hid_t</em> <code>create_plist</code>,
- <em>hid_t</em> <code>access_plist</code>
- )
-<dt><strong>Description:</strong>
- <dd>This is the primary function for opening and creating HDF5 files.
- The <code>flags</code> parameter determines whether an
- existing file will be overwritten or not. All newly
- created files are opened for both reading and writing.
- All flags may be combined with the '|' (boolean OR
- operator) to change the behavior of the file open call.
- The <code>create_plist</code> and
- <code>access_plist</code> parameters are property lists
- containing additional information required for specific
- methods of access or particular aspects of the file to set
- when creating a file. The parameters for creation and
- access property lists are described in the H5P API
- documentation.
-<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:
- <ul><dl>
- <dt>H5F_ACC_TRUNC
- <dd>Truncate file, if it already exists. The file will
- be truncated, erasing all data previously stored in
- the file.
- </dl></ul>
- <dt><em>hid_t</em><code>create_plist</code>
- <dd>File creation property list ID, used when modifying
- default file meta-data.
- <dt><em>hid_t</em><code>access_plist</code>
- <dd>Property list indicating the file access properties.
- If parallel file access is desired, this is a collective
- call according to the communicator stored in the
- access_plist. Use 0 for default access properties.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>An ID (of type <em>hid_t</em>) for the file upon success,
- otherwise negative
-</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>Description:</strong>
- <dd>This function 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>TRUE/FALSE/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="File-GetCreatePlist">H5Fget_create_plist</a>
-<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Fget_create_plist</code>(<em>hid_t</em> <code>file_id</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function returns a property list ID with a copy of
- the parameters used to create this file. Useful for
- duplicating the parameters when creating another file.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>file_id</code>
- <dd>File ID for which to get creation property list.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function terminates access to an HDF5 file. If this is the
- last file ID open for a file and if access IDs are still in use,
- this function will fail.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>file_id</code>
- <dd>File ID to terminate access to.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<h2><a name="Plist">Property List API Functions</a></h2>
-<P>These functions manipulate property lists to allow objects which require
-many different parameters to be easily manipulated.
-<br>
-<br>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-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>Description:</strong>
- <dd>This function returns a property list ID for a copy of the default
- property list of a given type.
- <br>
- <dl>
- <dt>Property List Types and Uses:
- <ul><dl>
- <dt>H5P_FILE_CREATE
- <dd>Used to set the metadata information about a file during
- file creation.
- <dt>H5P_FILE_ACCESS
- <dd>Used to set I/O access information about a file.
- <dt>H5P_DATASET_CREATE
- <dd>Used to set information about a dataset when it is
- created.
- <dt>H5P_DATASET_XFER
- <dd>Used to set access information about a memory to dataset
- transfer.
- </dl></ul>
- </dl>
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>H5P_class_t</em> <code>type</code>
- <dd>The type of property list to create.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Valid ID on success, negative on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-Close">H5Pclose</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pclose</code>(<em>hid_t</em> <code>plist_id</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function terminates access to a property list.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>Property list ID to terminate access to.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-GetClass">H5Pget_class</a>
-<dt><strong>Signature:</strong>
- <dd><em>H5P_class_t </em><code>H5Pget_class</code>(<em>hid_t</em> <code>plist_id</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function queries the class of a property list ID.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>Property list ID to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Property list class code on success, negative on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-Copy">H5Pcopy</a>
-<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Pcopy</code>(<em>hid_t</em> <code>plist_id</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function makes a copy of a property list ID.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>Property list ID to duplicate.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Property list ID on success, negative on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-GetVersion">H5Pget_version</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pget_version</code>(<em>hid_t</em> <code>plist_id</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>Description:</strong>
- <dd>This function queries 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_id</code>
- <dd>Property list ID to query.
- <dt><em>int *</em> <code>boot</code>
- <dd>Pointer to location to return boot block version number.
- <dt><em>int *</em> <code>freelist</code>
- <dd>Pointer to location to return global freelist version number.
- <dt><em>int *</em> <code>stab</code>
- <dd>Pointer to location to return symbol table version number.
- <dt><em>int *</em> <code>shhdr</code>
- <dd>Pointer to location to return shared object header version number.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-SetUserblock">H5Pset_userblock</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pset_userblock</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>hsize_t</em> <code>size</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function sets the size of the user-block located at the
- beginning of an HDF5 file. This function is only valid for
- file creation property lists. The default user-block size is 0.
- Only values which are powers of 2 larger equal to 512 or larger
- may be used as a valid user-block size.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>Property list to modify.
- <dt><em>hsize_t</em> <code>size</code>
- <dd>Size of the user-block in bytes.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-GetUserblock">H5Pget_userblock</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pget_userblock</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>hsize_t *</em> <code>size</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function retrieves the size of the user-block located at the
- beginning of 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_id</code>
- <dd>Property list ID to query.
- <dt><em>hsize_t *</em> <code>size</code>
- <dd>Pointer to location to return user-block size.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-SetSizes">H5Pset_sizes</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pset_sizes</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>size_t</em> <code>sizeof_addr</code>,
- <em>size_t</em> <code>sizeof_size</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function 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_id</code>
- <dd>Property list to modify.
- <dt><em>size_t</em> <code>sizeof_addr</code>
- <dd>Size of an object offset in bytes.
- <dt><em>size_t</em> <code>sizeof_size</code>
- <dd>Size of an object length in bytes.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-GetSizes">H5Pget_sizes</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pget_sizes</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>size_t *</em> <code>sizeof_addr</code>,
- <em>size_t *</em> <code>sizeof_size</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function 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_id</code>
- <dd>Property list ID to query.
- <dt><em>size_t *</em> <code>size</code>
- <dd>Pointer to location to return offset size in bytes.
- <dt><em>size_t *</em> <code>size</code>
- <dd>Pointer to location to return length size in bytes.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-SetMPI">H5Pset_mpi</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pset_mpi</code>(<em>hid_t</em> <code>tid</code>,
- <em>MPI_Comm</em> <code>comm</code>,
- <em>MPI_Info</em> <code>info</code>
- )
-<dt><strong>Description:</strong>
- <dd>Store the access mode for parallel I/O 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.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tid</code>
- <dd>ID of property list to modify
- <dt><em>MPI_Comm</em> <code>comm</code>
- <dd>
- MPI communicator to be used for file open as defined in
- MPI_FILE_OPEN of MPI-2. This function does not make a
- duplicated communicator. Any modification to comm 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>
- 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 info. Any modification to info 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>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-GetMPI">H5Pget_mpi</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pget_mpi</code>(<em>hid_t</em> <code>tid</code>,
- <em>MPI_Comm</em> <code>*comm</code>,
- <em>MPI_Info</em> <code>*info</code>
- )
-<dt><strong>Description:</strong>
- <dd>Retrieves the communicator and info object
- that have been set by H5Pset_mpi.
- This function is available only in the parallel HDF5 library.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tid</code>
- <dd>ID of a file access property list that has been set
- successfully by H5Pset_mpi.
- <dt><em>MPI_Comm *</em> <code>comm</code>
- <dd>Pointer to location to return the communicator.
- <dt><em>MPI_Info *</em> <code>info</code>
- <dd>Pointer to location to return the info object.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-SetXfer">H5Pset_xfer</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pset_xfer</code>(<em>hid_t</em> <code>tid</code>,
- <em>H5D_transfer_t</em> <code>data_xfer_mode</code>
- )
-<dt><strong>Description:</strong>
- <dd>Set 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.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tid</code>
- <dd>ID of a dataset transfer property list
- <dt><em>H5D_transfer_t</em> <code>data_xfer_mode</code>
- <dd>Data transfer modes:
- <ul><dl>
- <dt>H5D_XFER_INDEPENDENT
- <dd>Use independent I/O access.
- <dt>H5D_XFER_COLLECTIVE
- <dd>Use MPI collective I/O access.
- </dl></ul>
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-GetXfer">H5Pget_xfer</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pget_xfer</code>(<em>hid_t</em> <code>tid</code>,
- <em>H5D_transfer_t *</em> <code>data_xfer_mode</code>
- )
-<dt><strong>Description:</strong>
- <dd>Retrieves the transfer mode from the dataset
- transfer property list.
- This function is available only in the parallel HDF5 library.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tid</code>
- <dd>ID of a dataset transfer property list.
- <dt><em>H5D_transfer_t *</em> <code>data_xfer_mode</code>
- <dd>Pointer to location to return the data_xfer_mode.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-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_id</code>,
- <em>size_t</em> <code>ik</code>,
- <em>size_t</em> <code>lk</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function 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.
- <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>. <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_id</code>
- <dd>Property list ID to query.
- <dt><em>size_t</em> <code>ik</code>
- <dd>Symbol table tree rank.
- <dt><em>size_t</em> <code>lk</code>
- <dd>Symbol table node size.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-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_id</code>,
- <em>size_t *</em> <code>ik</code>,
- <em>size_t *</em> <code>lk</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function retrieves the size of the symbol table's B-tree
- 1/2 rank and the symbol table's leaf node 1/2 size. See
- information for <a href="#Plist-SetSymK">H5Pset_sym_k</a>
- for more information. This function is only valid for file
- creation property lists. If a parameter valued is set to
- NULL, that parameter is not retrieved.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>Property list ID to query.
- <dt><em>size_t *</em> <code>ik</code>
- <dd>Pointer to location to return the symbol table's B-tree 1/2 rank.
- <dt><em>size_t *</em> <code>size</code>
- <dd>Pointer to location to return the symbol table's leaf node 1/2 size.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-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_id</code>,
- <em>size_t</em> <code>ik</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function 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. <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_id</code>
- <dd>Property list ID to query.
- <dt><em>size_t</em> <code>ik</code>
- <dd>1/2 rank of chunked storage B-tree.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-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_id</code>,
- <em>size_t *</em> <code>ik</code>
- )
-<dt><strong>Description:</strong>
- <dd>Queries the 1/2 rank of an indexed storage B-tree. See
- <a href="#Plist-SetIstoreK">H5Pset_istore_k</a> for details.
- The argument <code>ik</code> may be the null pointer. This
- function is only valid for file creation property lists.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>Property list ID to query.
- <dt><em>size_t *</em> <code>ik</code>
- <dd>Pointer to location to return the chunked storage B-tree 1/2 rank.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-SetLayout">H5Pset_layout</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pset_layout</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>H5D_layout_t</em> <code>layout</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function sets the type of storage used store the raw data for
- a dataset. This function is only valid for dataset
- creation property lists. Valid parameter 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_id</code>
- <dd>Property list ID to query.
- <dt><em>H5D_layout_t</em> <code>layout</code>
- <dd>Type of storage layout for raw data.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-GetLayout">H5Pget_layout</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pget_layout</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>H5D_layout_t *</em> <code>layout</code>
- )
-<dt><strong>Description:</strong>
- <dd>Queries 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_id</code>
- <dd>Property list ID to query.
- <dt><em>H5D_layout_t *</em> <code>layout</code>
- <dd>Pointer to location to return the storage layout.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-SetChunk">H5Pset_chunk</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pset_chunk</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>int</em> <code>ndims</code>,
- <em>const hsize_t *</em> <code>dim</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function 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_id</code>
- <dd>Property list ID to query.
- <dt><em>int</em> <code>ndims</code>
- <dd>The number of dimensions of each chunk.
- <dt><em>const hsize_t *</em> <code>dim</code>
- <dd>An array containing the size of each chunk.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Plist-GetChunk">H5Pget_chunk</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pget_chunk</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>int</em> <code>max_ndims</code>
- <em>hsize_t *</em> <code>dims</code>
- )
-<dt><strong>Description:</strong>
- <dd>Queries the size of chunks for the raw data of a chunked layout
- dataset. This function is only valid for dataset creation
- property lists.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>Property list ID to query.
- <dt><em>int</em> <code>max_ndims</code>
- <dd>Size of the <code>dims</code> array.
- <dt><em>hsize_t *</em> <code>dims</code>
- <dd>Array to store the chunk dimensions.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<!--
-<hr>
-<h2><a name="Error">Error API Functions</a></h2>
-<P>These functions allow flexible error reporting for the HDF5 library.
-<br>
-<br>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Error-SetPush">H5Eset_push</a>
-<dt><strong>Signature:</strong>
- <dd><em>H5E_push_func_t </em><code>H5Eset_push</code>(<em>H5E_push_func_t</em> <code>func</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function sets a function to call when an error is detected in
- the library. The prototype of the H5E_push_func_t is: <br>
-void H5E_push_func_t(int32 errid, hdf_maj_err_code_t maj, hdf_min_err_code_t min, const char *function_name, const char *file_name, intn line);
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>H5E_push_func_t</em><code>func</code>
- <dd>Pointer to the error reporting function.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>The pointer to the previous error repoting function on succes, NULL on failure
-</dl>
--->
-
-<!--
-<hr>
-<h2><a name="Relationships">Relationships API Functions</a></h2>
-<P>These functions provide methods of creating links between logically
-related objects in a file.
-<br>
-<br>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Relationships-GetNumRelations">H5Rget_num_relations</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Rget_num_relations</code>(<em>hid_t </em><code>obj_id</code>,
- <em>int32 *</em><code>num_attached</code>,
- <em>int32 *</em><code>num_memberof</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function retrieves the number of relationships attached to the
- object and the number of other objects that the object is a member of
- itself.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>obj_id</code>
- <dd>ID of the object to query the number of attached relations
- <dt><em>int32 *</em> <code>num_attached</code>
- <dd>Number of objects attached to the object
- <dt><em>int32 *</em> <code>num_memberof</code>
- <dd>Number of objects that the object is a member of
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Relationships-GetMemberOfOIDs">H5Rget_memberof_oids</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Rget_memberof_oids</code>(<em>hid_t </em><code>obj_id</code>,
- <em>hoid_t </em><code>memberof_list[]</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function retrieves the OIDs of the objects that the object is a
- member of.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>obj_id</code>
- <dd>ID of the object to get the members of list
- <dt><em>hoid_t *</em> <code>memberof_list</code>
- <dd>A list of the OIDs for objects which the object is attached to.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Relationships-GetAttachedOIDs">H5Rget_attached_oids</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Rget_attached_oids</code>(<em>hid_t </em><code>obj_id</code>,
- <em>hoid_t </em><code>attached_list[]</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function retrieves the OIDs of the objects that are attached to
- the object.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>obj_id</code>
- <dd>ID of the object to get the attached OIDs from
- <dt><em>hoid_t *</em> <code>attached_list</code>
- <dd>A list of the OIDs for objects which are attached to the
- object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Relationships-Attach">H5Rattach_oid</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Rattach_oid</code>(<em>hid_t </em><code>obj_id</code>,
- <em>hoid_t </em><code>attach</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function attaches an OID to the object.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>obj_id</code>
- <dd>ID of the object to attach an OID to
- <dt><em>hoid_t </em> <code>attach</code>
- <dd>The OID to attach to the object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
--->
-
-<hr>
-<h2><a name="Dataset">Dataset Object API Functions</a></h2>
-<P>These functions create and manipulate dataset objects. Each dataset must
-be constructed from a datatype and a dataspace.
-<br>
-<br>
-
-<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>file_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>plist_id</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function creates a new dataset in the file specified with the
- <code>file_id</code>. The <code>type_id</code> and
- <code>space_id</code> are the IDs of the datatype and
- dataspace used to construct the framework of the dataset. The
- datatype and dataspace parameters describe the dataset as it
- will exist in the file, which is not necessarily the same as
- it exists in memory. The <code>plist_id</code> contains
- either the default property lists (H5P_DEFAULT) or a plist_id
- with particular constant properties used to create the
- dataset. The <code>name</code> is used to identify the
- dataset in a group and must be unique within that group.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>file_id</code>
- <dd>ID of the file 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>ID of the datatype to use when creating the dataset.
- <dt><em>hid_t</em> <code>space_id</code>
- <dd>ID of the dataspace to use when creating the dataset.
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>ID of the dataset creation property list.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Dataset ID on success, negative on failure.
-</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>file_id</code>,
- <em>const char *</em><code>name</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function opens an existing dataset for access in the file
- specified with the <code>file_id</code>. The <code>name</code> is
- used to identify the dataset in the file.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>file_id</code>
- <dd>ID 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>Dataset ID on success, negative on failure.
-</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>Description:</strong>
- <dd>This function returns a copy of the dataspace for a dataset. The
- dataspace should be released with the H5Sclose() function.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>dataset_id</code>
- <dd>ID of the dataset to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Dataspace ID on success, negative on failure.
-</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>Description:</strong>
- <dd>This function returns a copy of the datatype for a dataset. The
- dataspace should be released with the H5Tclose() function.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>dataset_id</code>
- <dd>ID of the dataset to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Datatype ID on success, negative on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Dataset-GetCreateParms">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>Description:</strong>
- <dd>This function returns a copy of the dataset creation property
- list for a dataset. The property list should be released with the
- H5Pclose() function.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>dataset_id</code>
- <dd>ID of the dataset to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Dataset creation property list ID on success, negative on failure.
-</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>transfer_plist_id</code>,
- <em>void *</em> <code>buf</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function reads raw data from the specified dataset into <code>buf</code>,
- converting from the file datatype of the dataset into the
- memory datatype specified in <code>mem_type_id</code>. The
- portion of the dataset to read from disk is specified with the
- <code>file_spaceid</code> which can contain a dataspace with a
- hyperslab selected or the constant H5S_ALL, which indicates
- the entire dataset is to be read. The portion of the dataset
- read into the memory buffer is specified with the
- <code>mem_space_id</code> which can also be a hyperslab of the
- same size or the H5S_ALL parameter to store the entire
- dataset. The <code>transfer_plist_id</code> is a dataset
- transfer property list ID which is used to provide addition
- parameters for the I/O operation or can be H5P_DEFAULT for the
- default library behavior.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>dataset_id</code>
- <dd>ID of the dataset read from.
- <dt><em>hid_t</em> <code>mem_type_id</code>
- <dd>ID of the memory datatype.
- <dt><em>hid_t</em> <code>mem_space_id</code>
- <dd>ID of the memory dataspace.
- <dt><em>hid_t</em> <code>file_space_id</code>
- <dd>ID of the dataset's dataspace in the file.
- <dt><em>hid_t</em> <code>transfer_plist_id</code>
- <dd>ID of a transfer property list for this I/O operation.
- <dt><em>void *</em> <code>buf</code>
- <dd>Buffer to store information read from the file.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>transfer_plist_id</code>,
- <em>const void *</em> <code>buf</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function writes raw data from memory into the specified dataset
- converting from the memory datatype of the dataset specified
- in <code>mem_type_id</code> into the file datatype. The
- portion of the dataset to written to disk is specified with
- the <code>file_spaceid</code> which can contain a dataspace
- with a hyperslab selected or the constant H5S_ALL, which
- indicates the entire dataset is to be written. The portion of
- the dataset written from the memory buffer is specified with
- the <code>mem_space_id</code> which can also be a hyperslab of
- the same size or the H5S_ALL parameter to store the entire
- dataset. The <code>transfer_plist_id</code> is a dataset
- transfer property list ID which is used to provide addition
- parameters for the I/O operation or can be H5P_DEFAULT for the
- default library behavior.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>dataset_id</code>
- <dd>ID of the dataset read from.
- <dt><em>hid_t</em> <code>mem_type_id</code>
- <dd>ID of the memory datatype.
- <dt><em>hid_t</em> <code>mem_space_id</code>
- <dd>ID of the memory dataspace.
- <dt><em>hid_t</em> <code>file_space_id</code>
- <dd>ID of the dataset's dataspace in the file.
- <dt><em>hid_t</em> <code>transfer_plist_id</code>
- <dd>ID of a transfer property list for this I/O operation.
- <dt><em>const void *</em> <code>buf</code>
- <dd>Buffer to store information to be written to the file.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function increases the size of the dataspace of a dataset with
- unlimited dimensions. It cannot be used to extend the size of a
- dataspace's fixed dimensions. The <code>size</code> array must have
- the same number of entries as the rank of the dataset's dataspace.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>dataset_id</code>
- <dd>ID of the dataset read from.
- <dt><em>const hsize_t *</em> <code>size</code>
- <dd>Array containing the new magnitude of each dimension.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function ends access to a dataset and releases resources used by
- it. Further use of the dataset ID is illegal in calls to the dataset
- API.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>dataset_id</code>
- <dd>ID of the dataset to finish access to.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<h2><a name="Datatype">Datatype Object API Functions</a></h2>
-<P>These functions create and manipulate the datatype which describes elements
-of a dataset.
-<br>
-<br>
-
-<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>Description:</strong>
- <dd>This function 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 ID
- returned from this function should be released with H5Tclose 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>Datatype ID on success, negative on failure.
-</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>Description:</strong>
- <dd>This function copies an existing datatype. The datatype ID returned
- should be released with H5Tclose or resource leaks will occur. 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>ID of datatype to copy.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Datatype ID on success, negative on failure.
-</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>Description:</strong>
- <dd>This function determines if two datatype IDs refer to the same
- datatype.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id1</code>
- <dd>ID of datatype to compare.
- <dt><em>hid_t</em> <code>type_id2</code>
- <dd>ID of datatype to compare.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>TRUE/FALSE/negative
-</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>Description:</strong>
- <dd>This function locks a type, making it read-only and non-destrucible.
- This is normally done by the library for predefined data types so the
- application doesn't inadvertently change or delete a predefined type.
- Once a data type is locked it can never be unlocked.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to lock.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function returns the base class of a datatype.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Non-negative type class on success, negative on failure.
-</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>Description:</strong>
- <dd>This function returns the size of a datatype in bytes.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Positve size in bytes on success, 0 on failure.
-</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>Description:</strong>
- <dd>This function sets the total size in bytes for an atomic data type (this
- operation is not permitted on compound data types). If the size is
- decreased so that the significant bits of the data type 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 data type 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 data types have a positive size.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID 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>zero/negative
-</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>Description:</strong>
- <dd>This function returns the byte order of an atomic datatype.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Byte order constant on success, negative on failure
-</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>Description:</strong>
- <dd>This function sets the byte ordering of an atomic datatype.
- Byte orderings currently supported are:
- <ul> <dl>
- <dt>H5T_ORDER_LE
- <dd> Little-endian byte ordering (default)
- <dt>H5T_ORDER_BE
- <dd> Big-endian byte ordering
- <dt>H5T_ORDER_Vax
- <dd> VAX-endianness byte ordering (not currently supported)
- </dl> </ul>
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to set.
- <dt><em>H5T_order_t</em> <code>order</code>
- <dd>Byte ordering constant.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function returns the precision of an atomic data type. 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>ID of datatype to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Number of significant bits on success, 0 on failure
-</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>Description:</strong>
- <dd>This function sets the precision of an atomic data type. 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 data type.
- <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>ID 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>zero/negative
-</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>Description:</strong>
- <dd>This function 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>ID of datatype to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Positive offset value on success, 0 on failure.
-</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>Description:</strong>
- <dd>This function 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 data type.
-
-<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>ID of datatype to set.
- <dt><em>size_t</em> <code>offset</code>
- <dd>Offset of first significant bit.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function retrieves the padding type of the least and most-significant
- bit padding. Valid types are:
- <ul> <dl>
- <dt>H5T_PAD_ZERO
- <dd>Set background to zeros.
- <dt>H5T_PAD_ONE
- <dd>Set background to ones.
- <dt>H5T_PAD_BACKGROUND
- <dd>Leave background alone.
- </dl> </ul>
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to query.
- <dt><em>H5T_pad_t *</em> <code>lsb</code>
- <dd>Pointer to location to return least-significant bit padding type.
- <dt><em>H5T_pad_t *</em> <code>msb</code>
- <dd>Pointer to location to return most-significant bit padding type.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function sets the least and most-significant bits padding types.
- <ul> <dl>
- <dt>H5T_PAD_ZERO
- <dd>Set background to zeros.
- <dt>H5T_PAD_ONE
- <dd>Set background to ones.
- <dt>H5T_PAD_BACKGROUND
- <dd>Leave background alone.
- </dl> </ul>
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID 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>zero/negative
-</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>Description:</strong>
- <dd>This function retrieves the sign type for an integer type.
- Valid types are:
- <ul> <dl>
- <dt>H5T_SGN_NONE
- <dd>Unsigned integer type.
- <dt>H5T_SGN_2
- <dd>Two's complement signed integer type.
- </dl> </ul>
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Non-negative sign type on success, negative on failure
-</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>Description:</strong>
- <dd>This function sets the sign proprety for an integer type.
- <ul> <dl>
- <dt>H5T_SGN_NONE
- <dd>Unsigned integer type.
- <dt>H5T_SGN_2
- <dd>Two's complement signed integer type.
- </dl> </ul>
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to set.
- <dt><em>H5T_sign_t</em> <code>sign</code>
- <dd>Sign type.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function retrieves information about the locations of the various
- bit fields of a floating point data type. The field positions are bit
- positions in the significant region of the data type. 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>ID of datatype to query.
- <dt><em>size_t *</em> <code>epos</code>
- <dd>Pointer to location to return exponent bit-position.
- <dt><em>size_t *</em> <code>esize</code>
- <dd>Pointer to location to return size of exponent in bits.
- <dt><em>size_t *</em> <code>mpos</code>
- <dd>Pointer to location to return mantissa bit-position.
- <dt><em>size_t *</em> <code>msize</code>
- <dd>Pointer to location to return size of mantissa in bits.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function sets the locations and sizes of the various floating
- point bit fields. The field positions are bit positions in the
- significant region of the data type. 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>ID 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>zero/negative
-</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>Description:</strong>
- <dd>This function retrieves the exponent bias of a floating-point type.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Positive value on success, 0 on failure.
-</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>Description:</strong>
- <dd>This function sets the exponent bias of a floating-point type.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to set.
- <dt><em>size_t</em> <code>ebias</code>
- <dd>Exponent bias value.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function retrieves the mantissa normalization of a floating-point
- datatype. Valid normalization values are:
- <ul> <dl>
- <dt>H5T_NORM_IMPLIED
- <dd>MSB of mantissa isn't stored, always 1
- <dt>H5T_NORM_MSBSET
- <dd>MSB of mantissa is always 1
- <dt>H5T_NORM_NONE
- <dd>Mantissa is not normalized
- </dl> </ul>
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Non-negative normalization type on success, negative on failure
-</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>Description:</strong>
- <dd>This function sets the mantissa normalization of a floating-point
- datatype. Valid normalization values are:
- <ul> <dl>
- <dt>H5T_NORM_IMPLIED
- <dd>MSB of mantissa isn't stored, always 1
- <dt>H5T_NORM_MSBSET
- <dd>MSB of mantissa is always 1
- <dt>H5T_NORM_NONE
- <dd>Mantissa is not normalized
- </dl> </ul>
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to set.
- <dt><em>H5T_norm_t</em> <code>norm</code>
- <dd>Mantissa normalization type.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function retrieves the internal padding type for unused bits in
- floating-point datatypes.
- Valid padding values are:
- <ul> <dl>
- <dt>H5T_PAD_ZERO
- <dd>Set background to zeros.
- <dt>H5T_PAD_ONE
- <dd>Set background to ones.
- <dt>H5T_PAD_BACKGROUND
- <dd>Leave background alone.
- </dl> </ul>
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Non-negative padding type on success, negative on failure
-</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>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 they will be filled
- according to the value of this property.
- Valid padding values are:
- <ul> <dl>
- <dt>H5T_PAD_ZERO
- <dd>Set background to zeros.
- <dt>H5T_PAD_ONE
- <dd>Set background to ones.
- <dt>H5T_PAD_BACKGROUND
- <dd>Leave background alone.
- </dl> </ul>
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to modify.
- <dt><em>H5T_pad_t</em> <code>pad</code>
- <dd>Padding type.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function retrieves the character set type of a string datatype.
- Valid character set values are:
- <ul> <dl>
- <dt>H5T_CSET_ASCII
- <dd>Character set is US ASCII
- </dl> </ul>
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Non-negative character set type on success, negative on failure
-</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>Description:</strong>
- <dd>HDF5 is able to distinguish between character sets of different
- nationalities and to convert between them to the extent possible.
- Valid character set values are:
- <ul> <dl>
- <dt>H5T_CSET_ASCII
- <dd>Character set is US ASCII
- </dl> </ul>
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to modify.
- <dt><em>H5T_cset_t</em> <code>cset</code>
- <dd>Character set type.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function retrieves the string padding method for a string datatype.
- Valid string padding values are:
- <ul> <dl>
- <dt>H5T_STR_NULL
- <dd>Pad with zeros (as C does)
- <dt>H5T_STR_SPACE
- <dd>Pad with spaces (as FORTRAN does)
- </dl> </ul>
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Non-negative string padding type on success, negative on failure
-</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>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. This property defines the
- storage mechanism for the string.
- Valid string padding values are:
- <ul> <dl>
- <dt>H5T_STR_NULL
- <dd>Pad with zeros (as C does)
- <dt>H5T_STR_SPACE
- <dd>Pad with spaces (as FORTRAN does)
- </dl> </ul>
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to modify.
- <dt><em>H5T_str_t</em> <code>strpad</code>
- <dd>String padding type.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function retrieves the number of fields a compound datatype has.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID of datatype to query.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Number of members datatype has on success, negative on failure
-</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>intn</em> <code>fieldno</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function retrieves the name of a field of a compound data type.
- Fields are stored in no particular order with numbers 0 through N-1
- where N is the value returned by H5Tget_nmembers(). The name of the
- field is allocated with malloc() 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>ID of datatype to query.
- <dt><em>intn</em> <code>fieldno</code>
- <dd>Field number (indexed from 0) of the field name to retrieve.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Valid pointer on success, NULL on failure
-</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>intn</em> <code>fieldno</code>,
- <em>size_t *</em> <code>dims</code>,
- <em>int *</em> <code>perm</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function 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>ID of datatype to query.
- <dt><em>intn</em> <code>fieldno</code>
- <dd>Field number (indexed from 0) of the field dims 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>Number of dimensions on success, negative on failure.
-</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>intn</em> <code>fieldno</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function returns the data type 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>ID of datatype to query.
- <dt><em>intn</em> <code>fieldno</code>
- <dd>Field number (indexed from 0) of the field type to retrieve.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>The ID of a copy of the datatype of the field, negative on failure.
-</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>Description:</strong>
- <dd>This function adds another member to the compound data type
- <code>type_id</code>. The new member has a <code>name</code> which
- must be unique within the compound data type. The <code>offset</code>
- argument defines the start of the member in an instance of the compound
- data type, and <code>field_id</code> is the type of the new member.
-
- <P>Note: All members of a compound data type must be atomic; a
- compound data type cannot have a member which is a compound data
- type.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>ID 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 ID of the field to insert.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function 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>ID of datatype to modify.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</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>Description:</strong>
- <dd>This function registers a hard conversion function for a data type
- 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:
- typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata,
- size_t nelmts, void *buf, void *bkg);
-<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>ID of source datatype.
- <dt><em>hid_t</em> <code>dst_id</code>
- <dd>ID 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>zero/negative
-</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>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>Description:</strong>
- <dd>This function 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:
- typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata,
- size_t nelmts, void *buf, void *bkg);
-<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>ID of source datatype.
- <dt><em>hid_t</em> <code>dst_id</code>
- <dd>ID 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>zero/negative
-</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>Description:</strong>
- <dd>This function removes a conversion function from all conversion paths.
- <P>The type of the conversion function pointer is declared as:
- typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata,
- size_t nelmts, void *buf, void *bkg);
-<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>zero/negative
-</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>Description:</strong>
- <dd>This function releases a datatype. Further access through the datatype
- ID 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>ID of datatype to release.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-
-<hr>
-<h2><a name="Dataspace">Dataspace Object API Functions</a></h2>
-<P>These functions create and manipulate the dataspace in which to store the
-elements of a dataset.
-<br>
-<br>
-
-<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>Description:</strong>
- <dd>This function creates a new simple data space object 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 ID returned from this function should be released with
- H5Sclose 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>A dataspace ID on success, negative on failure.
-</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>Description:</strong>
- <dd>This function copies a dataspace. The dataspace ID returned from this
- function should be released with H5Sclose or resource leaks will occur.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>space_id</code>
- <dd>ID of dataspace to copy.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A dataspace ID on success, negative on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Dataspace-GetNpoints">H5Sget_npoints</a>
-<dt><strong>Signature:</strong>
- <dd><em>hsize_t</em> <code>H5Sget_npoints</code>(<em>hid_t </em><code>space_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function 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>Number of elements in the dataspace, 0 on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Dataspace-GetNdims">H5Sget_ndims</a>
-<dt><strong>Signature:</strong>
- <dd><em>int</em> <code>H5Sget_ndims</code>(<em>hid_t</em> <code>space_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function determines the dimensionality (or rank) of a dataspace.
-<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>Number of dimensions in the dataspace, negative on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Dataspace-GetDims">H5Sget_dims</a>
-<dt><strong>Signature:</strong>
- <dd><em>int</em> <code>H5Sget_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>Description:</strong>
- <dd>This function returns the size of each dimension in a dataspace through
- the <code>dims</code> parameter.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>space_id</code>
- <dd>ID of the dataspace object to query
- <dt><em>hsize_t *</em><code>dims</code>
- <dd>Pointer to array to store the size of each dimension.
- <dt><em>hsize_t *</em><code>maxdims</code>
- <dd>Pointer to array to store the maximum size of each dimension.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Number of dimensions in the dataspace, negative on failure
-</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>Description:</strong>
- <dd>This function determines whether a dataspace object is a simple
- dataspace or not. [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>ID of the dataspace object to query
- </dl>
-<dt><strong>Returns:</strong>
- <dd>TRUE or FALSE on success, negative on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Dataspace-SetSpace">H5Sset_space</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Sset_space</code>(<em>hid_t </em><code>space_id</code>,
- <em>uint32 </em><code>rank</code>,
- <em>uint32 *</em><code>dims</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function determines the number of dimensions and the size of each
- dimension for the space that a dataset is stored within. This function
- only creates simple dataspace objects. Setting the rank to a
- value of zero allows scalar objects to be created. Dimensions are
- specified from slowest to fastest changing in the <code>dims</code>
- array (i.e. 'C' order). Setting the size of a dimension to zero
- indicates that the dimension is of unlimited size and should be allowed
- to expand. Currently, only the first dimension in the array (the
- slowest) may be unlimited in size.
- [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>ID of the dataspace object.
- <dt><em>uint32</em> <code>rank</code>
- <dd>The number of dimensions the object is composed of.
- <dt><em>uint32 *</em> <code>dims</code>
- <dd>An array of the size of each dimension. (NULL for scalar objects)
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Dataspace-SetHyperslab">H5Sset_hyperslab</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Sset_hyperslab</code>(<em>hid_t</em> <code>space_id</code>,
- <em>const hssize_t *</em><code>start</code>,
- <em>const hsize_t *</em><code>count</code>,
- <em>const hsize_t *</em><code>stride</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function selects a hyperslab from a simple dataspace. The stride
- array may be used to sub-sample the hyperslab chosen, a value of 1 in each
- position of the stride array selects contiguous elements in the array,
- a value of 2 selects every other element, etc. If the stride parameter is
- set to NULL, a contiguous hyperslab is chosen. The values in the start and
- count arrays may be negative, to allow for selecting hyperslabs in chunked
- datasets which extend in arbitrary directions.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>space_id</code>
- <dd>ID of the dataspace object to set hyperslab in.
- <dt><em>const hssize_t *</em><code>start</code>
- <dd>Pointer to array of starting location for hyperslab.
- <dt><em>const hsize_t *</em><code>count</code>
- <dd>Pointer to array of magnitude of hyperslab.
- <dt><em>const hsize_t *</em><code>stride</code>
- <dd>Pointer to array of stride of hyperslab.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Dataspace-GetHyperslab">H5Sget_hyperslab</a>
-<dt><strong>Signature:</strong>
- <dd><em>int</em> <code>H5Sget_hyperslab</code>(<em>hid_t</em> <code>space_id</code>,
- <em>hssize_t *</em><code>start</code>,
- <em>hsize_t *</em><code>count</code>,
- <em>hsize_t *</em><code>stride</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function retrieves information about the hyperslab from a simple
- dataspace. If no hyperslab has been defined then the hyperslab is the
- same as the entire array.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>space_id</code>
- <dd>ID of the dataspace object to set hyperslab in.
- <dt><em>hssize_t *</em><code>start</code>
- <dd>Pointer to array to store starting location of hyperslab.
- <dt><em>hsize_t *</em><code>count</code>
- <dd>Pointer to array to store magnitude of hyperslab.
- <dt><em>hsize_t *</em><code>stride</code>
- <dd>Pointer to array to store stride of hyperslab.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Hyperslab dimensionality on success, negative on failure.
-</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>Description:</strong>
- <dd>This function releases a dataspace. Further access through the dataspace
- ID 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>ID of dataspace to release.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<h2><a name="Group">Group Object API Functions</a></h2>
-
-<p>A group associates names with objects and provides a mechanism
-which can map 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 handle 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 root
-object is the current working group if the stack is empty). The stack
-can be manipulated with <code>H5Gset</code>, <code>H5Gpush</code>, and
-<code>H5Gpop</code>.
-
-<p>An object name consists of one or more components separated from
-one another by slashes. If the name begins with a slash then the
-object is located by looking for the first component in the root
-object, then looking for the second component in that object, etc.,
-until the entire name is traversed. If the name doesn't begin with a
-slash then 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 doesn't 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 and then a <code>getcwd</code>
-function would be trivial.
-
-<br>
-<br>
-
-<hr>
- <dl>
- <dt><strong>Name:</strong> <a name="Group-Create">H5Gcreate</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Gset</code> (<em>hid_t</em>
- <code>file</code>, <em>const char *</em><code>name</code>,
- <em>size_t</em> <code>size_hint</code>)
- <dt><strong>Description:</strong>
- <dd>This function creates a new empty group and gives it a name.
- <dt><strong>Parameters:</strong>
- <dd>
- <dl>
- <dt><em>hid_t</em> <code>file</code>
- <dd>The file handle returned by <code>H5Fcreate</code> or
- <code>H5Fopen</code>.
- <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>The size hint is an optional parameter that indicates
- 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 while 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 negative value on failure, non-negative otherwise.
- </dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Group-Open">H5Sopen</a>
-<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Gopen</code>(<em>hid_t</em> <code>file_id</code>,
- <em>const char *</em><code>name</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function opens an existing group for modification. When finished,
- call H5Gclose() to close it and release resources.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>file_id</code>
- <dd>ID of file to open group within.
- <dt><em>const char *</em> <code>name</code>
- <dd>Name of group to open.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Valid group ID on success, negative on failure.
-</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>file</code>, <em>const char *</em><code>name</code>)
- <dt><strong>Description:</strong>
- <dd>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.
- <dt><strong>Parameters:</strong>
- <dd>
- <dl>
- <dt><em>hid_t</em> <code>file</code>
- <dd>The file handle returned by <code>H5Fcreate</code> or
- <code>H5Fopen</code>.
- <dt><em>const char *</em><code>name</code>
- <dd>The name of the new current working group. If the name
- doesn't begin with a slash then it is looked up relative the
- the previous current working group.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a negative value on failure, non-negative otherwise.
- </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>file</code>, <em>const char *</em><code>name</code>)
- <dt><strong>Description:</strong>
- <dd>This function sets the current working group by pushing a
- new element onto the current working group stack.
- <dt><strong>Parameters:</strong>
- <dd>
- <dl>
- <dt><em>hid_t</em> <code>file</code>
- <dd>The file handle returned by <code>H5Fcreate</code> or
- <code>H5Fopen</code>.
- <dt><em>const char *</em><code>name</code>
- <dd>The name of the new current working group. If the name
- doesn't begin with a slash then it is looked up relative the
- the previous current working group.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a negative value on failure, non-negative otherwise.
- </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>file</code>)
- <dt><strong>Description:</strong>
- <dd>This function 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.
- <dt><strong>Parameters:</strong>
- <dd>
- <dl>
- <dt><em>hid_t</em> <code>file</code>
- <dd>The file handle returned by <code>H5Fcreate</code> or
- <code>H5Fopen</code>.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a negative value on failure, non-negative otherwise.
- </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>Description:</strong>
- <dd>This function releases a group. Further access through the group
- ID is illegal. 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>ID of group to release.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<!--
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Group-GetNumContents">H5Gget_num_contents</a>
-<dt><strong>Signature:</strong>
- <dd><em>uint32 </em><code>H5Gget_num_contents</code>(<em>hid_t </em><code>grp_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function retrieves the number of objects in the contents of the
- group.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>grp_id</code>
- <dd>ID of the group object to query
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Number of objects in group's contents on success, Unegative on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Group-GetContentInfo">H5Gget_content_info</a>
-<dt><strong>Signature:</strong>
- <dd><em>uint32 </em><code>H5Gget_content_info</code>(<em>hid_t </em><code>grp_id</code>,
- <em>int32 </em><code>index</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function retrieves the type (dataset, dimension, datatype or
- group) of an item in a group.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>grp_id</code>
- <dd>ID of the group object to query
- <dt><em>uint32</em> <code>index</code>
- <dd>Item index in the group to query the type of
- </dl>
-<dt><strong>Returns:</strong>
- <dd>The type of the object for an item on success, or Unegative on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Group-GetContentInfoMult">H5Gget_content_info_mult</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Gget_content_info</code>(<em>hid_t </em><code>grp_id</code>,
- <em>int32 </em><code>start_index</code>,
- <em>int32 </em><code>num_items</code>,
- <em>int32 </em><code>itemtype_list[]</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function retrieves the type (dataset, dimension, datatype or
- group) of a list of items in a group.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>grp_id</code>
- <dd>ID of the group object to query
- <dt><em>uint32</em> <code>start_index</code>
- <dd>The starting index to query the types of items
- <dt><em>uint32</em> <code>num_items</code>
- <dd>The number of items to query the types of
- <dt><em>uint32</em> <code>itemtype_list[]</code>
- <dd>A list to store the types of the items in
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Group-GetOIDByName">H5Gget_oid_by_name</a>
-<dt><strong>Signature:</strong>
- <dd><em>hoid_t </em><code>H5Gget_oid_by_name</code>(<em>hid_t </em><code>grp_id</code>,
- <em>char *</em><code>name</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function retrieves the OID of an item in the group which matches
- the name supplied.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>grp_id</code>
- <dd>ID of the group object to query
- <dt><em>char *</em> <code>name</code>
- <dd>The name of the item to find
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A valid OID on success, or negative on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Group-GetOIDByIndex">H5Gget_oid_by_index</a>
-<dt><strong>Signature:</strong>
- <dd><em>hoid_t </em><code>H5Gget_oid_by_index</code>(<em>hid_t </em><code>grp_id</code>,
- <em>uint32</em><code>index</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function retrieves the OID of the n'th item in a group.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>grp_id</code>
- <dd>ID of the group object to query
- <dt><em>uint32</em> <code>index</code>
- <dd>The index of the item in the group
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A valid OID on success, or negative on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Group-GetNameByOID">H5Gget_name_by_oid</a>
-<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Gget_name_by_oid</code>(<em>hid_t </em><code>grp_id</code>,
- <em>hoid_t</em><code>oid</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function retrieves the name of the item in a group whose OID
- matches the one supplied.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>grp_id</code>
- <dd>ID of the group object to query
- <dt><em>hoid_t</em> <code>oid</code>
- <dd>The OID of the item in the group
- </dl>
-<dt><strong>Returns:</strong>
- <dd>An atom for the string on success, NULL on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Group-GetNameByIndex">H5Gget_name_by_index</a>
-<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Gget_name_by_index</code>(<em>hid_t </em><code>grp_id</code>,
- <em>uint32</em><code>index</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function retrieves the name of the n'th item in a group
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>grp_id</code>
- <dd>ID of the group object to query
- <dt><em>uint32</em> <code>index</code>
- <dd>The index of the item in the group
- </dl>
-<dt><strong>Returns:</strong>
- <dd>An atom for the string on success, NULL on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Group-InsertItem">H5Ginsert_item</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Ginsert_item</code>(<em>hid_t </em><code>grp_id</code>,
- <em>hoid_t</em><code>item</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function inserts the item into a group
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>grp_id</code>
- <dd>ID of the group object to change
- <dt><em>hoid_t</em> <code>item</code>
- <dd>The OID of the item to insert into the group
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Group-InsertItemMult">H5Ginsert_item_mult</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Ginsert_item_mult</code>(<em>hid_t </em><code>grp_id</code>,
- <em>uint32</em><code>num_items</code>
- <em>hoid_t</em><code>item_list[]</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function inserts multiple items into a group
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>grp_id</code>
- <dd>ID of the group object to change
- <dt><em>hoid_t</em> <code>num_items</code>
- <dd>The number of items to insert into the group
- <dt><em>hoid_t</em> <code>item_list[]</code>
- <dd>The OIDs of the items to insert
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Group-RemoveItem">H5Gremove_item</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Gremove_item</code>(<em>hid_t </em><code>grp_id</code>,
- <em>hoid_t</em><code>item</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function removes an item from a group
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>grp_id</code>
- <dd>ID of the group object to change
- <dt><em>hoid_t</em> <code>item_list[]</code>
- <dd>The OID of the items to remove
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Group-RemoveItemMult">H5Gremove_item_mult</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Gremove_item_mult</code>(<em>hid_t </em><code>grp_id</code>,
- <em>uint32</em><code>num_items</code>
- <em>hoid_t</em><code>item_list[]</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function removes multiple items from a group
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>grp_id</code>
- <dd>ID of the group object to change
- <dt><em>hoid_t</em> <code>num_items</code>
- <dd>The number of items to remove from the group
- <dt><em>hoid_t</em> <code>item_list[]</code>
- <dd>The OIDs of the items to remove
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
--->
-
-<!--
-<hr>
-<h2><a name="LinkList">Linked-List Object API Functions</a></h2>
-<P>These functions manage in-memory linked lists in various useful ways.
-<br>
-<br>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-AddToBeginning">H5Ladd_to_beginning</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Ladd_to_beginning</code>(<em>hid_t </em><code>lst_id</code>,
- <em>VOIDP</em><code>item</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function adds an object to the beginning of a linked list
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- <dt><em>VOIDP</em> <code>item</code>
- <dd>A pointer to the object to add to the list. This must not
- be NULL.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-AddToEnd">H5Ladd_to_end</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Ladd_to_end</code>(<em>hid_t </em><code>lst_id</code>,
- <em>VOIDP</em><code>item</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function adds an object to the end of a linked list
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- <dt><em>VOIDP</em> <code>item</code>
- <dd>A pointer to the object to add to the list. This must not
- be NULL.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-RemoveFromBeginning">H5Lremove_from_beginning</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Lremove_from_beginning</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function removes an object from the front of a linked list and
- returns it.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-RemoveFromEnd">H5Lremove_from_end</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Lremove_from_end</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function removes an object from the back of a linked list and
- returns it.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-RemoveCurrent">H5Lremove_current</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Lremove_current</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function removes the current object from the list and returns
- a pointer to it. The list's current object is moved back to the
- previous item in the list, or set to NULL if the object removed is at
- the beginning of the list.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-DeleteAll">H5Ldelete_all</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Ldelete_all</code>(<em>hid_t </em><code>lst_id</code>,
- <em>void</em><code>(*free_func)(VOIDP)</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function removes all the objects from a list. If
- <code>free_func</code> is not NULL, each object removed from the list
- is passed to <code>free_func</code> before being removed from the list.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- <dt><em>void</em> <code>(*free_func)(VOIDP)</code>
- <dd>Pointer to the function to call for each item removed from
- the list.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-Index">H5Lindex</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Lindex</code>(<em>hid_t </em><code>lst_id</code>,
- <em>uintn</em><code>indx</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function finds the n'th object in a list and returns it.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- <dt><em>uintn</em> <code>indx</code>
- <dd>Index of the object to return.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-PeekAtBeginning">H5Lpeek_at_beginning</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Lpeek_at_beginning</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the first object in the list. If
- the list is empty, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-PeekAtEnd">H5Lpeek_at_end</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Lpeek_at_end</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the last object in the list. If
- the list is empty, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-FirstInList">H5Lfirst_in_list</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Lfirst_in_list</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the first object in the list, and
- marks it as the current object. If the list is empty, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-LastInList">H5Llast_in_list</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Llast_in_list</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the last object in the list, and
- marks it as the current object. If the list is empty, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-CurrentInList">H5Lcurrent_in_list</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Lcurrent_in_list</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the object that is considered the
- "current object" in the list.
- If the current object has been removed, or current points before or
- after the list or the list is empty, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-NextInList">H5Lnext_in_list</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Lnext_in_list</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the next object in the list and marks
- it as the current object.
- If the end of the list has been reached or the list is empty, NULL is
- returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-PreviousInList">H5Lprevious_in_list</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Lprevious_in_list</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the previous object in the list and
- marks it as the current object.
- If the beginning of the list has been reached or the list is empty, NULL
- is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-ResetToBeginning">H5Lreset_to_beginning</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Lreset_to_beginning</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function resets the "current object" to the beginning of the list.
- Therefore the next object in the list is the first object.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-ResetToEnd">H5Lreset_to_end</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Lreset_to_end</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function resets the "current object" to the end of the list.
- Therefore the previous object in the list is the last object.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-NumOfObjects">H5Lnum_of_objects</a>
-<dt><strong>Signature:</strong>
- <dd><em>uintn </em><code>H5Lnum_of_objects</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns the number of objects in the list.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>The number of nodes in the list (possibly zero) on success or UFAIL on
- failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-IsEmpty">H5Lis_empty</a>
-<dt><strong>Signature:</strong>
- <dd><em>hbool_t </em><code>H5Lis_empty</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function determines if the list is empty.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>TRUE if the list is empty, FALSE if the list has objects, negative on
- failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-IsInList">H5Lis_in_list</a>
-<dt><strong>Signature:</strong>
- <dd><em>hbool_t </em><code>H5Lis_in_list</code>(<em>hid_t </em><code>lst_id</code>,
- <em>VOIDP</em><code>search_ptr</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function determines if an object is in the list.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- <dt><em>VOIDP</em> <code>search_ptr</code>
- <dd>Pointer to look for in list
- </dl>
-<dt><strong>Returns:</strong>
- <dd>TRUE if the list contains the pointer, FALSE if the list has does not,
- negative on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-CopyList">H5Lcopy_list</a>
-<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Lcopy_list</code>(<em>hid_t </em><code>lst_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function makes a copy of the list. The objects themselves are not
- copied, only new references to them are made. The new list has no
- current object set.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A valid list atom on success, negative on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-PerformOnList">H5Lperform_on_list</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Lperform_on_list</code>(<em>hid_t </em><code>lst_id</code>,
- <em>void</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function performs the specified function on each object in the
- list. Any options arguments required can be passed through the "args"
- pointer.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- <dt><em>void</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-FirstThat">H5Lfirst_that</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Lfirst_that</code>(<em>hid_t </em><code>lst_id</code>,
- <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function will find and return the first object in the list which
- causes the specified function to return a TRUE (non-zero) value. Any
- optional arguments required can be passed through the "args" variable.
- The found object is then marked as the current object. If no objects
- in the list meet the criteria of the specified function or an error
- occurs, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure or no matching objects
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-NextThat">H5Lnext_that</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Lnext_that</code>(<em>hid_t </em><code>lst_id</code>,
- <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function will find and return the next object in the list which
- causes the specified function to return a TRUE (non-zero) value. Any
- optional arguments required can be passed through the "args" variable.
- The found object is then marked as the current object. If no objects
- in the list meet the criteria of the specified function or an error
- occurs, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure or no matching objects
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-PreviousThat">H5Lprevious_that</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Lprevious_that</code>(<em>hid_t </em><code>lst_id</code>,
- <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function will find and return the previous object in the list which
- causes the specified function to return a TRUE (non-zero) value. Any
- optional arguments required can be passed through the "args" variable.
- The found object is then marked as the current object. If no objects
- in the list meet the criteria of the specified function or an error
- occurs, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure or no matching objects
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-LastThat">H5Llast_that</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Llast_that</code>(<em>hid_t </em><code>lst_id</code>,
- <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function will find and return the last object in the list which
- causes the specified function to return a TRUE (non-zero) value. Any
- optional arguments required can be passed through the "args" variable.
- The found object is then marked as the current object. If no objects
- in the list meet the criteria of the specified function or an error
- occurs, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure or no matching objects
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-AllSuchThat">H5Lall_such_that</a>
-<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Lall_such_that</code>(<em>hid_t </em><code>lst_id</code>,
- <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function will return a new list containing all of the objects in
- the list which cause the specified function to return a TRUE (non-zero)
- value. Any optional arguments required can be passed through the "args"
- variable. The objects themselves are not copied, onle new references
- to them are made.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A valid list atom on success, negative on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="LinkList-RemoveAllSuchThat">H5Lremove_all_such_that</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Lremove_all_such_that</code>(<em>hid_t </em><code>lst_id</code>,
- <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function will remove all of the objects in the list which cause
- the specified function to return a TRUE (non-zero) value. Any optional
- arguments required can be passed through the "args" variable. Note that
- the memory for the objects will not be reclaimed, so if the objects have
- no other references, it is best to avoid this function and remove the
- objects one by one, freeing them when necessary.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>lst_id</code>
- <dd>ID of the list object
- <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<h2><a name="TBBT">Threaded, Balanced, Binary-Tree Object API Functions</a></h2>
-<P>These functions manage in-memory TBBTs in various useful ways.
-<br>
-<br>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-Add">H5Badd</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Badd</code>(<em>hid_t </em><code>tree_id</code>,
- <em>VOIDP</em><code>item</code>,
- <em>VOIDP</em><code>key</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function inserts a new node having a key value of <code>key</code>
- and a data pointer of <code>item</code> into the tree. If a node
- already exists in the tree with the same key value or an error occurs,
- negative is returned, otherwise, zero is returned. The comparison
- function which the tree was created with is used to determine the
- location of the new node in the tree.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- <dt><em>VOIDP</em> <code>item</code>
- <dd>Pointer to the data of the object to insert into the tree.
- <dt><em>VOIDP</em> <code>key</code>
- <dd>Pointer to the key of the object to insert into the tree.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-Remove">H5Bremove</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Bremove</code>(<em>hid_t </em><code>tree_id</code>,
- <em>VOIDP</em><code>key</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function removes a node with a key value of <code>key</code>.
- The data pointer corresponding to the key is returned on success, or
- a NULL value is returned on failure.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- <dt><em>VOIDP</em> <code>key</code>
- <dd>Pointer to the key of the object to remove from the tree.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to the data item on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-RemoveAll">H5Bremove_all</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Bremove_all</code>(<em>hid_t </em><code>tree_id</code>,
- <em>void</em><code>(*free_func)(VOIDP)</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function removes all nodes from the tree. If
- <code>free_func</code> is not NULL, each object removed from the list
- is passed to <code>free_func</code> before being removed from the list.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- <dt><em>void</em> <code>(*free_func)(VOIDP)</code>
- <dd>Pointer to the function to call for each item removed from
- the list.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-RemoveCurrent">H5Bremove_current</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Bremove_all</code>(<em>hid_t </em><code>tree_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function removes the "current object" from the tree and returns
- a pointer to it. The tree's current object is moved back to the
- previous node in the tree, or set to NULL if the object removed is at
- the beginning of the tree.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to the data item removed on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-PeekAtBeginning">H5Bpeek_at_beginning</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Bpeek_at_beginning</code>(<em>hid_t </em><code>tree_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the first object in the tree. If
- the tree is empty, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to the first data item on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-PeekAtEnd">H5Bpeek_at_end</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Bpeek_at_end</code>(<em>hid_t </em><code>tree_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the last object in the tree. If
- the tree is empty, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to the last data item on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-Find">H5Bfind</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Bfind</code>(<em>hid_t </em><code>tree_id</code>,
- <em>VOIDP</em><code>key</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the object in the tree who's key
- matches the argument passed in. If the no match is found, NULL is
- returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- <dt><em>VOIDP</em> <code>key</code>
- <dd>Pointer to the key of the object to search for the tree.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to the data item on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-Index">H5Bindex</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Bindex</code>(<em>hid_t </em><code>tree_id</code>,
- <em>uintn</em><code>indx</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function finds the n'th object in a tree and returns it.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- <dt><em>uintn</em> <code>indx</code>
- <dd>Index of the object to return.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to the data item on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-FirstInTree">H5Bfirst_in_tree</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Bfirst_in_tree</code>(<em>hid_t </em><code>tree_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the first object in the tree, and
- marks it as the current object. If the tree is empty, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to the data item on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-LastInTree">H5Blast_in_tree</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Blast_in_tree</code>(<em>hid_t </em><code>tree_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the last object in the tree, and
- marks it as the current object. If the tree is empty, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to the data item on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-CurrentInTree">H5Bcurrent_in_tree</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Bcurrent_in_tree</code>(<em>hid_t </em><code>tree_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the object that is considered the
- "current object" in the tree.
- If the current object has been removed, or current points before or
- after the tree or the tree is empty, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to the data item on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-NextInTree">H5Bnext_in_tree</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Bnext_in_tree</code>(<em>hid_t </em><code>tree_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the next object in the tree and marks
- it as the current object.
- If the end of the tree has been reached or the tree is empty, NULL is
- returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to the data item on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-PreviousInTree">H5Bprevious_in_tree</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Bprevious_in_tree</code>(<em>hid_t </em><code>tree_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns a pointer to the previous object in the tree and
- marks it as the current object.
- If the beginning of the tree has been reached or the tree is empty, NULL
- is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to the data item on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-ResetToBeginning">H5Breset_to_beginning</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Breset_to_beginning</code>(<em>hid_t </em><code>tree_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function resets the "current object" to the beginning of the tree.
- Therefore the next object in the tree is the first object.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to the data item on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-ResetToEnd">H5Breset_to_end</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Breset_to_end</code>(<em>hid_t </em><code>tree_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function resets the "current object" to the end of the tree.
- Therefore the previous object in the tree is the last object.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to the data item on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-NumOfObjects">H5Bnum_of_objects</a>
-<dt><strong>Signature:</strong>
- <dd><em>uintn </em><code>H5Bnum_of_objects</code>(<em>hid_t </em><code>tree_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function returns the number of objects in the tree.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>The number of nodes in the tree (possibly zero) on success or UFAIL on
- failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-IsEmpty">H5Bis_empty</a>
-<dt><strong>Signature:</strong>
- <dd><em>hbool_t </em><code>H5Bis_empty</code>(<em>hid_t </em><code>tree_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function determines if the tree is empty.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>TRUE if the tree is empty, FALSE if the tree has objects, negative on
- failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-IsInTree">H5Bis_in_tree</a>
-<dt><strong>Signature:</strong>
- <dd><em>hbool_t </em><code>H5Bis_in_tree</code>(<em>hid_t </em><code>tree_id</code>,
- <em>VOIDP</em><code>item</code>,
- <em>VOIDP</em><code>key</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function determines if an object is in the tree. If
- <code>item</code> is NULL, only the key pointer will be used to search
- for nodes in the tree. If <code>key</code> is NULL, only the item pointer
- will be used to search for nodes in the tree. If both <code>item</code>
- and <code>key</code> are not NULL, only a node which matches both pointers
- will be considered a match for the search.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- <dt><em>VOIDP</em> <code>item</code>
- <dd>Pointer to the data of the object to search for in the tree.
- <dt><em>VOIDP</em> <code>key</code>
- <dd>Pointer to the key of the object to search for in the tree.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>TRUE if a search node is found, FALSE if no nodes match, negative on
- failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-CopyTree">H5Bcopy_tree</a>
-<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Bcopy_tree</code>(<em>hid_t </em><code>tree_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function makes a copy of the tree. The objects themselves are not
- copied, only new references to them are made. The new tree has no
- current object set.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A valid tree atom on success, negative on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-PerformOnTree">H5Bperform_on_tree</a>
-<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Bperform_on_tree</code>(<em>hid_t </em><code>tree_id</code>,
- <em>void</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function performs the specified function on each object in the
- tree. Any options arguments required can be passed through the "args"
- pointer.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- <dt><em>void</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-FirstThat">H5Bfirst_that</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Bfirst_that</code>(<em>hid_t </em><code>tree_id</code>,
- <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function will find and return the first object in the tree which
- causes the specified function to return a TRUE (non-zero) value. Any
- optional arguments required can be passed through the "args" variable.
- The found object is then marked as the current object. If no objects
- in the tree meet the criteria of the specified function or an error
- occurs, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure or no matching objects
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-NextThat">H5Bnext_that</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Bnext_that</code>(<em>hid_t </em><code>tree_id</code>,
- <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function will find and return the next object in the tree which
- causes the specified function to return a TRUE (non-zero) value. Any
- optional arguments required can be passed through the "args" variable.
- The found object is then marked as the current object. If no objects
- in the tree meet the criteria of the specified function or an error
- occurs, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure or no matching objects
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-PreviousThat">H5Bprevious_that</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Bprevious_that</code>(<em>hid_t </em><code>tree_id</code>,
- <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function will find and return the previous object in the tree which
- causes the specified function to return a TRUE (non-zero) value. Any
- optional arguments required can be passed through the "args" variable.
- The found object is then marked as the current object. If no objects
- in the tree meet the criteria of the specified function or an error
- occurs, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure or no matching objects
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-LastThat">H5Blast_that</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Blast_that</code>(<em>hid_t </em><code>tree_id</code>,
- <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function will find and return the last object in the tree which
- causes the specified function to return a TRUE (non-zero) value. Any
- optional arguments required can be passed through the "args" variable.
- The found object is then marked as the current object. If no objects
- in the tree meet the criteria of the specified function or an error
- occurs, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure or no matching objects
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-AllSuchThat">H5Ball_such_that</a>
-<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Ball_such_that</code>(<em>hid_t </em><code>tree_id</code>,
- <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function will return a new tree containing all of the objects in
- the tree which cause the specified function to return a TRUE (non-zero)
- value. Any optional arguments required can be passed through the "args"
- variable. The objects themselves are not copied, onle new references
- to them are made.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A valid tree atom on success, negative on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="TBBT-RemoveAllSuchThat">H5Bremove_all_such_that</a>
-<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Bremove_all_such_that</code>(<em>hid_t </em><code>tree_id</code>,
- <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function will remove all of the objects in the tree which cause
- the specified function to return a TRUE (non-zero) value. Any optional
- arguments required can be passed through the "args" variable. Note that
- the memory for the objects will not be reclaimed, so if the objects have
- no other references, it is best to avoid this function and remove the
- objects one by one, freeing them when necessary.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>tree_id</code>
- <dd>ID of the TBBT object
- <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<h2><a name="BitVector">Bit-Vector Object API Functions</a></h2>
-<P>These functions manage in-memory bit-vectors used to provide "set"
-operations and maintain groups of flags about file information.
-<br>
-<br>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="BitVector-Set">H5Vset</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Vset</code>(<em>hid_t </em><code>bv_id</code>,
- <em>uint32</em><code>bit_num</code>,
- <em>hbool_t</em><code>value</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function sets a bit in a bit-vector to a given boolean value.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>bv_id</code>
- <dd>ID of the bit-vector object.
- <dt><em>uint32</em> <code>bit_num</code>
- <dd>Which bit in the vector to set.
- <dt><em>hbool_t</em> <code>value</code>
- <dd>Value to set the bit to.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="BitVector-Get">H5Vget</a>
-<dt><strong>Signature:</strong>
- <dd><em>hbool_t </em><code>H5Vget</code>(<em>hid_t </em><code>bv_id</code>,
- <em>uint32</em><code>bit_num</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function gets the value of a bit in a bit-vector.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>bv_id</code>
- <dd>ID of the bit-vector object.
- <dt><em>uint32</em> <code>bit_num</code>
- <dd>Which bit in the vector to get.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Value of the bit or negative on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="BitVector-Clear">H5Vclear</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Vclear</code>(<em>hid_t </em><code>bv_id</code>,
- <em>hbool_t</em><code>value</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function clears an entire bit-vector to a given boolean value.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>bv_id</code>
- <dd>ID of the bit-vector object.
- <dt><em>hbool_t</em> <code>value</code>
- <dd>The value to clear the bit-vector to.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="BitVector-Size">H5Vsize</a>
-<dt><strong>Signature:</strong>
- <dd><em>uint32 </em><code>H5Vclear</code>(<em>hid_t </em><code>bv_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function reports the number of bits used in a bit-vector.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>bv_id</code>
- <dd>ID of the bit-vector object.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>The number of bits in the bit-vector (possibly zero) on success or
- UFAIL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="BitVector-Find">H5Vfind</a>
-<dt><strong>Signature:</strong>
- <dd><em>uint32 </em><code>H5Vfind</code>(<em>hid_t </em><code>bv_id</code>,
- <em>hbool_t</em><code>value</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function finds the first bit in a bit-vector with a given value.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>bv_id</code>
- <dd>ID of the bit-vector object.
- <dt><em>hbool_t</em> <code>value</code>
- <dd>The value to search for.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>The position of the first bit with the given value on success or UFAIL
- on failure.
-</dl>
-
-<hr>
-<h2><a name="Atom">Atom Object API Functions</a></h2>
-<P>These functions manage in-memory atoms, which provide a portable and
-protected way of refering to memory structures.
-<br>
-<br>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Atom-Register">H5Aregister</a>
-<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Aregister</code>(<em>hgroup_t </em><code>grp_id</code>,
- <em>VOIDP</em><code>ptr</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function registers a pointer (to a data-structure, usually) in a
- group and provides an atom for it.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hgroup_t</em> <code>grp_id</code>
- <dd>ID of the atom group.
- <dt><em>VOIDP</em> <code>ptr</code>
- <dd>The pointer (to a data-structure) to register in the group.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A value atom on success, negative on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Atom-Unregister">H5Aunregister</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Aunregister</code>(<em>hid_t </em><code>atm</code>)
-<dt><strong>Description:</strong>
- <dd>This function removes an atom from a group and returns a pointer to
- the structure which was registered.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>atm</code>
- <dd>Atom to remove.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A valid memory pointer on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Atom-LookupObject">H5Alookup_object</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Alookup_object</code>(<em>hid_t </em><code>atm</code>)
-<dt><strong>Description:</strong>
- <dd>This function retrieves the memory pointer which is associated with
- the atom.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>atm</code>
- <dd>Atom to look up.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A valid memory pointer on success, NULL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Atom-LookupGroup">H5Alookup_group</a>
-<dt><strong>Signature:</strong>
- <dd><em>hgroup_t </em><code>H5Alookup_group</code>(<em>hid_t </em><code>atm</code>)
-<dt><strong>Description:</strong>
- <dd>This function retrieves the group that the atom is in.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>atm</code>
- <dd>Atom to look up.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A valid atom group on success, negative on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Atom-Search">H5Asearch</a>
-<dt><strong>Signature:</strong>
- <dd><em>VOIDP </em><code>H5Asearch</code>(<em>hgroup_t </em><code>grp</code>,
- <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>,
- <em>VOIDP</em><code>args</code>,
- )
-<dt><strong>Description:</strong>
- <dd>This function will find and return the first object in the atomic
- group which causes the specified function to return a TRUE (non-zero)
- value. Any optional arguments required can be passed through the
- "args" variable. Currently, there is no way to resume a search.
- If no objects in the group meet the criteria of the specified function
- or an error occurs, NULL is returned.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hgroup_t</em> <code>grp</code>
- <dd>ID of the atom group to search.
- <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>
- <dd>Pointer to the function to operate on the objects
- <dt><em>VOIDP</em> <code>args</code>
- <dd>Pointer any additional arguments needed by the function as
- it is operating on the objects.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>A pointer to an object on success/NULL on failure or no matching objects
-</dl>
-
-<hr>
-<h2><a name="String">String Object API Functions</a></h2>
-<P>These functions manage in-memory character strings in an object-oriented
-way.
-<br>
-<br>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="String-Copy">H5Scopy</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Scopy</code>(<em>hid_t </em><code>strg_id1</code>,
- <em>hid_t</em><code>strg_id2</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function copies a string from one string object to another.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>strg_id1</code>
- <dd>ID of the destination string.
- <dt><em>hid_t</em> <code>strg_id2</code>
- <dd>ID of the source string.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="String-Convert">H5Sconvert</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Sconvert</code>(<em>hid_t </em><code>strg_id/code>,
- <em>char *</em><code>buf</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function copies a string object into a zero-terminated character
- buffer.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>strg_id</code>
- <dd>ID of the destination string.
- <dt><em>char *</em> <code>buf</code>
- <dd>Character buffer to store string in.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>zero/negative
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="String-Len">H5Slen</a>
-<dt><strong>Signature:</strong>
- <dd><em>uintn </em><code>H5Slen</code>(<em>hid_t </em><code>strg_id</code>)
-<dt><strong>Description:</strong>
- <dd>This function return the length of a string in characters.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>strg_id</code>
- <dd>ID of the string.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>The length of the string (possibly 0) on success, or UFAIL on failure.
-</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="String-Compare">H5Scompare</a>
-<dt><strong>Signature:</strong>
- <dd><em>intn </em><code>H5Scompare</code>(<em>hid_t </em><code>strg_id1</code>,
- <em>hid_t</em><code>strg_id2</code>
- )
-<dt><strong>Description:</strong>
- <dd>This function compares the two strings, returning an integer less than,
- equal to, or greater than zero, indicating that the string referenced
- by <code>strg_id1</code> is less than, equal to, or greater than the
- string referenced by <code>strg_id2</code>.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>strg_id1</code>
- <dd>ID of the first string.
- <dt><em>hid_t</em> <code>strg_id1</code>
- <dd>ID of the second string.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>An integer less than, equal to, or greater than zero based on the values
- of the strings.
-</dl>
--->
-
-<hr>
-<h2><a name="Glossary">Glossary of data-types used</a></h2>
-<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...
-<br>
-<br>
-
-<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>
-