diff options
| author | Quincey Koziol <koziol@hdfgroup.org> | 1998-07-08 14:54:54 (GMT) |
|---|---|---|
| committer | Quincey Koziol <koziol@hdfgroup.org> | 1998-07-08 14:54:54 (GMT) |
| commit | bd1e676c521d881b3143829f493a28b5ced1294b (patch) | |
| tree | 69c50f9fe21ce87f293d8617a6bd51b4cc1e0244 /doc/html/H5.api.html | |
| parent | 73345095897d9698bb1f2f7df830bf80a56dc65a (diff) | |
| download | hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.zip hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.gz hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.bz2 | |
[svn-r467] Restructuring documentation.
Diffstat (limited to 'doc/html/H5.api.html')
| -rw-r--r-- | doc/html/H5.api.html | 4611 |
1 files changed, 4611 insertions, 0 deletions
diff --git a/doc/html/H5.api.html b/doc/html/H5.api.html new file mode 100644 index 0000000..b2402a5 --- /dev/null +++ b/doc/html/H5.api.html @@ -0,0 +1,4611 @@ +<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> + |