mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-21 01:04:10 +08:00
4612 lines
176 KiB
HTML
4612 lines
176 KiB
HTML
<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<name> - 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<name> - 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-GetCreateTemplate">H5Fget_create_template</a>
|
|
<li><a href="#File-Close">H5Fclose</a>
|
|
</ol>
|
|
|
|
<li><a href="#Template">Template</a> - H5P<name> - API for manipulating object templates
|
|
<ol type=A>
|
|
<li><a href="#Template-Create">H5Pcreate</a>
|
|
<li><a href="#Template-GetClass">H5Pget_class</a>
|
|
<li><a href="#Template-Copy">H5Pcopy</a>
|
|
<li><a href="#Template-Close">H5Pclose</a>
|
|
<li><a href="#Template-GetVersion">H5Pget_version</a>
|
|
<li><a href="#Template-SetUserblock">H5Pset_userblock</a>
|
|
<li><a href="#Template-GetUserblock">H5Pget_userblock</a>
|
|
<li><a href="#Template-SetSizes">H5Pset_sizes</a>
|
|
<li><a href="#Template-GetSizes">H5Pget_sizes</a>
|
|
<li><a href="#Template-SetMPI">H5Pset_mpi</a>
|
|
<li><a href="#Template-GetMPI">H5Pget_mpi</a>
|
|
<li><a href="#Template-SetXfer">H5Pset_xfer</a>
|
|
<li><a href="#Template-GetXfer">H5Pget_xfer</a>
|
|
<li><a href="#Template-SetSymK">H5Pset_sym_k</a>
|
|
<li><a href="#Template-GetSymK">H5Pget_sym_k</a>
|
|
<li><a href="#Template-SetIstoreK">H5Pset_istore_k</a>
|
|
<li><a href="#Template-GetIstoreK">H5Pget_istore_k</a>
|
|
<li><a href="#Template-SetLayout">H5Pset_layout</a>
|
|
<li><a href="#Template-GetLayout">H5Pget_layout</a>
|
|
<li><a href="#Template-SetChunk">H5Pset_chunk</a>
|
|
<li><a href="#Template-GetChunk">H5Pget_chunk</a>
|
|
</ol>
|
|
|
|
<!--
|
|
<li><a href="#Error">Error</a> - H5E<name> - API for error reporting
|
|
<ol type=A>
|
|
<li><a href="#Error-SetPush">H5Eset_push</a>
|
|
</ol>
|
|
-->
|
|
|
|
<!--
|
|
<li><a href="#Relationships">Relationships</a> - H5R<name> - 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<name> - 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<name> - 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<name> - 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<name> - 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_template</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_template</code> parameter is a template containing
|
|
additional information required for specific methods of access,
|
|
parallel I/O for example. The paramters for access templates 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_template</code>
|
|
<dd>Template indicating the file access properties.
|
|
If parallel file access is desired, this is a collective
|
|
call according to the communicator stored in the
|
|
access_template. Use 0 for default access template.
|
|
</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_template</code>,
|
|
<em>hid_t</em> <code>access_template</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_template</code> and <code>access_template</code>
|
|
parameters are templates 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 templates 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_template</code>
|
|
<dd>File creation template ID, used when modifying default file meta-data
|
|
<dt><em>hid_t</em><code>access_template</code>
|
|
<dd>Template indicating the file access properties.
|
|
If parallel file access is desired, this is a collective
|
|
call according to the communicator stored in the
|
|
access_template. Use 0 for default access template.
|
|
</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-GetCreateTemplate">H5Fget_create_template</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Fget_create_template</code>(<em>hid_t</em> <code>file_id</code>
|
|
)
|
|
<dt><strong>Description:</strong>
|
|
<dd>This function returns an template 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 to get creation template of
|
|
</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="Template">Template API Functions</a></h2>
|
|
<P>These functions manipulate template objects to allow objects which require
|
|
many different parameters to be easily manipulated.
|
|
<br>
|
|
<br>
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Template-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 template ID for a copy of the default
|
|
template of a given type.
|
|
<br>
|
|
<dl>
|
|
<dt>Template 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 template to create.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Valid ID on success, negative on failure
|
|
</dl>
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Template-Close">H5Pclose</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Pclose</code>(<em>hid_t</em> <code>template_id</code>
|
|
)
|
|
<dt><strong>Description:</strong>
|
|
<dd>This function terminates access to a template.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>template_id</code>
|
|
<dd>Template ID to terminate access to.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>zero/negative
|
|
</dl>
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Template-GetClass">H5Pget_class</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>H5P_class_t </em><code>H5Pget_class</code>(<em>hid_t</em> <code>template_id</code>
|
|
)
|
|
<dt><strong>Description:</strong>
|
|
<dd>This function queries the class of a template ID.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>template_id</code>
|
|
<dd>Template ID to query.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Template class code on success, negative on failure
|
|
</dl>
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Template-Copy">H5Pcopy</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Pcopy</code>(<em>hid_t</em> <code>template_id</code>
|
|
)
|
|
<dt><strong>Description:</strong>
|
|
<dd>This function makes a copy of a template ID.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>template_id</code>
|
|
<dd>Template ID to duplicate.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Template ID on success, negative on failure
|
|
</dl>
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Template-GetVersion">H5Pget_version</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Pget_version</code>(<em>hid_t</em> <code>template_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 template. Any pointer parameters which are
|
|
passed as NULL are not queried.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>template_id</code>
|
|
<dd>Template 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="Template-SetUserblock">H5Pset_userblock</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Pset_userblock</code>(<em>hid_t</em> <code>template_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 templates. 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>template_id</code>
|
|
<dd>Template 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="Template-GetUserblock">H5Pget_userblock</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Pget_userblock</code>(<em>hid_t</em> <code>template_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 templates.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>template_id</code>
|
|
<dd>Template 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="Template-SetSizes">H5Pset_sizes</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Pset_sizes</code>(<em>hid_t</em> <code>template_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 templates. 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>template_id</code>
|
|
<dd>Template 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="Template-GetSizes">H5Pget_sizes</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Pget_sizes</code>(<em>hid_t</em> <code>template_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
|
|
templates.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>template_id</code>
|
|
<dd>Template 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="Template-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 template 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 template 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 template. Users should call this function
|
|
again to setup the template.
|
|
<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 template. Users should call this function
|
|
again to setup the template.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>zero/negative
|
|
</dl>
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Template-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="Template-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="Template-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="Template-SetSymK">H5Pset_sym_k</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Pset_sym_k</code>(<em>hid_t</em> <code>template_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 templates. 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>template_id</code>
|
|
<dd>Template 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="Template-GetSymK">H5Pget_sym_k</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Pget_sym_k</code>(<em>hid_t</em> <code>template_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="#Template-SetSymK">H5Pset_sym_k</a> for
|
|
more information. This function is only valid for file creation
|
|
templates. If a parameter valued is set to NULL, that parameter is
|
|
not retrieved.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>template_id</code>
|
|
<dd>Template 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="Template-SetIstoreK">H5Pset_istore_k</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Pset_istore_k</code>(<em>hid_t</em> <code>template_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 templates. 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>template_id</code>
|
|
<dd>Template 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="Template-GetIstoreK">H5Pget_istore_k</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Pget_istore_k</code>(<em>hid_t</em> <code>template_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="#Template-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 templates.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>template_id</code>
|
|
<dd>Template 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="Template-SetLayout">H5Pset_layout</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Pset_layout</code>(<em>hid_t</em> <code>template_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 templates.
|
|
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>template_id</code>
|
|
<dd>Template 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="Template-GetLayout">H5Pget_layout</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Pget_layout</code>(<em>hid_t</em> <code>template_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 templates.
|
|
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>template_id</code>
|
|
<dd>Template 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="Template-SetChunk">H5Pset_chunk</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Pset_chunk</code>(<em>hid_t</em> <code>template_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
|
|
templates. 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>template_id</code>
|
|
<dd>Template 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="Template-GetChunk">H5Pget_chunk</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Pget_chunk</code>(<em>hid_t</em> <code>template_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
|
|
templates.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>template_id</code>
|
|
<dd>Template 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>template_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>template_id</code>
|
|
contains either the default template (H5P_DEFAULT) or a template_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>template_id</code>
|
|
<dd>ID of the dataset creation template.
|
|
</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 template for a
|
|
dataset. The template 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 template 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_template_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_template_id</code> is a dataset transfer template 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_template_id</code>
|
|
<dd>ID of a transfer template 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_template_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_template_id</code> is a dataset transfer template 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_template_id</code>
|
|
<dd>ID of a transfer template 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>
|
|
|