diff options
| -rw-r--r-- | doc/html/H5.api.html | 4623 |
1 files changed, 0 insertions, 4623 deletions
diff --git a/doc/html/H5.api.html b/doc/html/H5.api.html deleted file mode 100644 index 5f3cf78..0000000 --- a/doc/html/H5.api.html +++ /dev/null @@ -1,4623 +0,0 @@ -<html><head><title> -HDF5 Draft API Specification -</title></head><body> - -<center> -<h1>HDF5: API Specification</h1> -</center> - -<ol type=I> -<li><a href="#Library">Library</a> - H5<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-GetCreatePlist">H5Fget_create_plist</a> - <li><a href="#File-Close">H5Fclose</a> -</ol> - -<li><a href="#Plist">Property list</a> - H5P<name> - API for manipulating object property lists -<ol type=A> - <li><a href="#Plist-Create">H5Pcreate</a> - <li><a href="#Plist-GetClass">H5Pget_class</a> - <li><a href="#Plist-Copy">H5Pcopy</a> - <li><a href="#Plist-Close">H5Pclose</a> - <li><a href="#Plist-GetVersion">H5Pget_version</a> - <li><a href="#Plist-SetUserblock">H5Pset_userblock</a> - <li><a href="#Plist-GetUserblock">H5Pget_userblock</a> - <li><a href="#Plist-SetSizes">H5Pset_sizes</a> - <li><a href="#Plist-GetSizes">H5Pget_sizes</a> - <li><a href="#Plist-SetMPI">H5Pset_mpi</a> - <li><a href="#Plist-GetMPI">H5Pget_mpi</a> - <li><a href="#Plist-SetXfer">H5Pset_xfer</a> - <li><a href="#Plist-GetXfer">H5Pget_xfer</a> - <li><a href="#Plist-SetSymK">H5Pset_sym_k</a> - <li><a href="#Plist-GetSymK">H5Pget_sym_k</a> - <li><a href="#Plist-SetIstoreK">H5Pset_istore_k</a> - <li><a href="#Plist-GetIstoreK">H5Pget_istore_k</a> - <li><a href="#Plist-SetLayout">H5Pset_layout</a> - <li><a href="#Plist-GetLayout">H5Pget_layout</a> - <li><a href="#Plist-SetChunk">H5Pset_chunk</a> - <li><a href="#Plist-GetChunk">H5Pget_chunk</a> -</ol> - -<!-- -<li><a href="#Error">Error</a> - H5E<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_plist</code> - ) -<dt><strong>Description:</strong> - <dd>This is the primary function for opening existing HDF5 files. - The <code>flags</code> parameter determines the file - access mode. There is no read flag, all open files are - implicitily opened for read access. All flags may be - combined with the '|' (boolean OR operator) to change the - behavior of the file open call. The - <code>access_plist</code> parameter is a property list - containing additional information required for specific - methods of access, parallel I/O for example. The - paramters for access property lists are described in the - H5P API documentation. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>const char *</em><code>name</code> - <dd>Name of the file to access. - <dt><em>uintn</em> <code>flags</code> - <dd>File access flags: - <ul><dl> - <dt>H5F_ACC_RDWR - <dd>Allow read and write access to file. - </dl></ul> - <dt><em>hid_t</em><code>access_plist</code> - <dd>Property list indicating the file access properties. - If parallel file access is desired, this is a collective - call according to the communicator stored in the - access_plist. Use 0 for default access properties. - </dl> -<dt><strong>Returns:</strong> - <dd>An ID (of type <em>hid_t</em>) for the file upon success, - otherwise negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="File-Create">H5Fcreate</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Fcreate</code>(<em>const char *</em><code>name</code>, - <em>uintn</em> <code>flags</code>, - <em>hid_t</em> <code>create_plist</code>, - <em>hid_t</em> <code>access_plist</code> - ) -<dt><strong>Description:</strong> - <dd>This is the primary function for opening and creating HDF5 files. - The <code>flags</code> parameter determines whether an - existing file will be overwritten or not. All newly - created files are opened for both reading and writing. - All flags may be combined with the '|' (boolean OR - operator) to change the behavior of the file open call. - The <code>create_plist</code> and - <code>access_plist</code> parameters are property lists - containing additional information required for specific - methods of access or particular aspects of the file to set - when creating a file. The parameters for creation and - access property lists are described in the H5P API - documentation. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>const char *</em><code>name</code> - <dd>Name of the file to access. - <dt><em>uintn</em> <code>flags</code> - <dd>File access flags: - <ul><dl> - <dt>H5F_ACC_TRUNC - <dd>Truncate file, if it already exists. The file will - be truncated, erasing all data previously stored in - the file. - </dl></ul> - <dt><em>hid_t</em><code>create_plist</code> - <dd>File creation property list ID, used when modifying - default file meta-data. - <dt><em>hid_t</em><code>access_plist</code> - <dd>Property list indicating the file access properties. - If parallel file access is desired, this is a collective - call according to the communicator stored in the - access_plist. Use 0 for default access properties. - </dl> -<dt><strong>Returns:</strong> - <dd>An ID (of type <em>hid_t</em>) for the file upon success, - otherwise negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="File-IsHDF5">H5Fis_hdf5</a> -<dt><strong>Signature:</strong> - <dd><em>hbool_t </em><code>H5Fis_hdf5</code>(<em>const char *</em><code>name</code> - ) -<dt><strong>Description:</strong> - <dd>This function determines whether a file is in the HDF5 format. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>const char *</em><code>name</code> - <dd>File name to check format. - </dl> -<dt><strong>Returns:</strong> - <dd>TRUE/FALSE/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="File-GetCreatePlist">H5Fget_create_plist</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Fget_create_plist</code>(<em>hid_t</em> <code>file_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function returns a property list ID with a copy of - the parameters used to create this file. Useful for - duplicating the parameters when creating another file. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>file_id</code> - <dd>File ID for which to get creation property list. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="File-Close">H5Fclose</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Fclose</code>(<em>hid_t</em> <code>file_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function terminates access to an HDF5 file. If this is the - last file ID open for a file and if access IDs are still in use, - this function will fail. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>file_id</code> - <dd>File ID to terminate access to. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<h2><a name="Plist">Property List API Functions</a></h2> -<P>These functions manipulate property lists to allow objects which require -many different parameters to be easily manipulated. -<br> -<br> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-Create">H5Pcreate</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Pcreate</code>(<em>H5P_class_t</em> <code>type</code> - ) -<dt><strong>Description:</strong> - <dd>This function returns a property list ID for a copy of the default - property list of a given type. - <br> - <dl> - <dt>Property List Types and Uses: - <ul><dl> - <dt>H5P_FILE_CREATE - <dd>Used to set the metadata information about a file during - file creation. - <dt>H5P_FILE_ACCESS - <dd>Used to set I/O access information about a file. - <dt>H5P_DATASET_CREATE - <dd>Used to set information about a dataset when it is - created. - <dt>H5P_DATASET_XFER - <dd>Used to set access information about a memory to dataset - transfer. - </dl></ul> - </dl> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>H5P_class_t</em> <code>type</code> - <dd>The type of property list to create. - </dl> -<dt><strong>Returns:</strong> - <dd>Valid ID on success, negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-Close">H5Pclose</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pclose</code>(<em>hid_t</em> <code>plist_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function terminates access to a property list. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list ID to terminate access to. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-GetClass">H5Pget_class</a> -<dt><strong>Signature:</strong> - <dd><em>H5P_class_t </em><code>H5Pget_class</code>(<em>hid_t</em> <code>plist_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function queries the class of a property list ID. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list ID to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Property list class code on success, negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-Copy">H5Pcopy</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Pcopy</code>(<em>hid_t</em> <code>plist_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function makes a copy of a property list ID. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list ID to duplicate. - </dl> -<dt><strong>Returns:</strong> - <dd>Property list ID on success, negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-GetVersion">H5Pget_version</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pget_version</code>(<em>hid_t</em> <code>plist_id</code>, - <em>int *</em> <code>boot</code>, - <em>int *</em> <code>freelist</code>, - <em>int *</em> <code>stab</code>, - <em>int *</em> <code>shhdr</code> - ) -<dt><strong>Description:</strong> - <dd>This function queries the version information of various objects - for a file creation property list. Any pointer parameters - which are passed as NULL are not queried. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list ID to query. - <dt><em>int *</em> <code>boot</code> - <dd>Pointer to location to return boot block version number. - <dt><em>int *</em> <code>freelist</code> - <dd>Pointer to location to return global freelist version number. - <dt><em>int *</em> <code>stab</code> - <dd>Pointer to location to return symbol table version number. - <dt><em>int *</em> <code>shhdr</code> - <dd>Pointer to location to return shared object header version number. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-SetUserblock">H5Pset_userblock</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pset_userblock</code>(<em>hid_t</em> <code>plist_id</code>, - <em>hsize_t</em> <code>size</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the size of the user-block located at the - beginning of an HDF5 file. This function is only valid for - file creation property lists. The default user-block size is 0. - Only values which are powers of 2 larger equal to 512 or larger - may be used as a valid user-block size. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list to modify. - <dt><em>hsize_t</em> <code>size</code> - <dd>Size of the user-block in bytes. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-GetUserblock">H5Pget_userblock</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pget_userblock</code>(<em>hid_t</em> <code>plist_id</code>, - <em>hsize_t *</em> <code>size</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the size of the user-block located at the - beginning of an HDF5 file. This function is only valid for - file creation property lists. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list ID to query. - <dt><em>hsize_t *</em> <code>size</code> - <dd>Pointer to location to return user-block size. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-SetSizes">H5Pset_sizes</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pset_sizes</code>(<em>hid_t</em> <code>plist_id</code>, - <em>size_t</em> <code>sizeof_addr</code>, - <em>size_t</em> <code>sizeof_size</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the byte size of the offsets and lengths used to - address objects in an HDF5 file. This function is only - valid for file creation property lists. Passing in a - value of 0 for one of the sizeof parameters retains the - current value. The default value for both values is 4 - bytes. Valid values currenly are 2, 4, 8 and 16. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list to modify. - <dt><em>size_t</em> <code>sizeof_addr</code> - <dd>Size of an object offset in bytes. - <dt><em>size_t</em> <code>sizeof_size</code> - <dd>Size of an object length in bytes. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-GetSizes">H5Pget_sizes</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pget_sizes</code>(<em>hid_t</em> <code>plist_id</code>, - <em>size_t *</em> <code>sizeof_addr</code>, - <em>size_t *</em> <code>sizeof_size</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the size of the offsets and lengths used - in an HDF5 file. This function is only valid for file creation - property lists. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list ID to query. - <dt><em>size_t *</em> <code>size</code> - <dd>Pointer to location to return offset size in bytes. - <dt><em>size_t *</em> <code>size</code> - <dd>Pointer to location to return length size in bytes. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-SetMPI">H5Pset_mpi</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pset_mpi</code>(<em>hid_t</em> <code>tid</code>, - <em>MPI_Comm</em> <code>comm</code>, - <em>MPI_Info</em> <code>info</code> - ) -<dt><strong>Description:</strong> - <dd>Store the access mode for parallel I/O call and the user supplied - communicator and info in the access property list which can then - be used to open file. This function is available only in the - parallel HDF5 library. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tid</code> - <dd>ID of property list to modify - <dt><em>MPI_Comm</em> <code>comm</code> - <dd> - MPI communicator to be used for file open as defined in - MPI_FILE_OPEN of MPI-2. This function does not make a - duplicated communicator. Any modification to comm after - this function call returns may have undetermined effect - to the access property list. Users should call this function - again to setup the property list. - <dt><em>MPI_Info</em> <code>info</code> - <dd> - MPI info object to be used for file open as defined in - MPI_FILE_OPEN of MPI-2. This function does not make a - duplicated info. Any modification to info after - this function call returns may have undetermined effect - to the access property list. Users should call this function - again to setup the property list. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-GetMPI">H5Pget_mpi</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pget_mpi</code>(<em>hid_t</em> <code>tid</code>, - <em>MPI_Comm</em> <code>*comm</code>, - <em>MPI_Info</em> <code>*info</code> - ) -<dt><strong>Description:</strong> - <dd>Retrieves the communicator and info object - that have been set by H5Pset_mpi. - This function is available only in the parallel HDF5 library. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tid</code> - <dd>ID of a file access property list that has been set - successfully by H5Pset_mpi. - <dt><em>MPI_Comm *</em> <code>comm</code> - <dd>Pointer to location to return the communicator. - <dt><em>MPI_Info *</em> <code>info</code> - <dd>Pointer to location to return the info object. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-SetXfer">H5Pset_xfer</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pset_xfer</code>(<em>hid_t</em> <code>tid</code>, - <em>H5D_transfer_t</em> <code>data_xfer_mode</code> - ) -<dt><strong>Description:</strong> - <dd>Set the transfer mode of the dataset transfer property list. - The list can then be used to control the I/O transfer mode - during dataset accesses. This function is available only - in the parallel HDF5 library and is not a collective function. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tid</code> - <dd>ID of a dataset transfer property list - <dt><em>H5D_transfer_t</em> <code>data_xfer_mode</code> - <dd>Data transfer modes: - <ul><dl> - <dt>H5D_XFER_INDEPENDENT - <dd>Use independent I/O access. - <dt>H5D_XFER_COLLECTIVE - <dd>Use MPI collective I/O access. - </dl></ul> - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-GetXfer">H5Pget_xfer</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pget_xfer</code>(<em>hid_t</em> <code>tid</code>, - <em>H5D_transfer_t *</em> <code>data_xfer_mode</code> - ) -<dt><strong>Description:</strong> - <dd>Retrieves the transfer mode from the dataset - transfer property list. - This function is available only in the parallel HDF5 library. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tid</code> - <dd>ID of a dataset transfer property list. - <dt><em>H5D_transfer_t *</em> <code>data_xfer_mode</code> - <dd>Pointer to location to return the data_xfer_mode. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-SetSymK">H5Pset_sym_k</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pset_sym_k</code>(<em>hid_t</em> <code>plist_id</code>, - <em>size_t</em> <code>ik</code>, - <em>size_t</em> <code>lk</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the size of parameters used to control the - symbol table nodes. This function is only valid for file - creation property lists. Passing in a value of 0 for one - of the parameters retains the current value. - <code>ik</code> is one half the rank of a tree that stores - a symbol table for a group. Internal nodes of the symbol - table are on average 75% full. That is, the average rank - of the tree is 1.5 times the value of - <code>ik</code>. <code>lk</code> is one half of the number - of symbols that can be stored in a symbol table node. A - symbol table node is the leaf of a symbol table tree which - is used to store a group. When symbols are inserted - randomly into a group, the group's symbol table nodes are - 75% full on average. That is, they contain 1.5 times the - number of symbols specified by <code>lk</code>. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list ID to query. - <dt><em>size_t</em> <code>ik</code> - <dd>Symbol table tree rank. - <dt><em>size_t</em> <code>lk</code> - <dd>Symbol table node size. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-GetSymK">H5Pget_sym_k</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pget_sym_k</code>(<em>hid_t</em> <code>plist_id</code>, - <em>size_t *</em> <code>ik</code>, - <em>size_t *</em> <code>lk</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the size of the symbol table's B-tree - 1/2 rank and the symbol table's leaf node 1/2 size. See - information for <a href="#Plist-SetSymK">H5Pset_sym_k</a> - for more information. This function is only valid for file - creation property lists. If a parameter valued is set to - NULL, that parameter is not retrieved. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list ID to query. - <dt><em>size_t *</em> <code>ik</code> - <dd>Pointer to location to return the symbol table's B-tree 1/2 rank. - <dt><em>size_t *</em> <code>size</code> - <dd>Pointer to location to return the symbol table's leaf node 1/2 size. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-SetIstoreK">H5Pset_istore_k</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pset_istore_k</code>(<em>hid_t</em> <code>plist_id</code>, - <em>size_t</em> <code>ik</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the size of the parameter used to control the - B-trees for indexing chunked datasets. This function is - only valid for file creation property lists. Passing in a - value of 0 for one of the parameters retains the current - value. <code>ik</code> is one half the rank of a tree - that stores chunked raw data. On average, such a tree - will be 75% full, or have an average rank of 1.5 times the - value of <code>ik</code>. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list ID to query. - <dt><em>size_t</em> <code>ik</code> - <dd>1/2 rank of chunked storage B-tree. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-GetIstoreK">H5Pget_istore_k</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pget_istore_k</code>(<em>hid_t</em> <code>plist_id</code>, - <em>size_t *</em> <code>ik</code> - ) -<dt><strong>Description:</strong> - <dd>Queries the 1/2 rank of an indexed storage B-tree. See - <a href="#Plist-SetIstoreK">H5Pset_istore_k</a> for details. - The argument <code>ik</code> may be the null pointer. This - function is only valid for file creation property lists. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list ID to query. - <dt><em>size_t *</em> <code>ik</code> - <dd>Pointer to location to return the chunked storage B-tree 1/2 rank. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-SetLayout">H5Pset_layout</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pset_layout</code>(<em>hid_t</em> <code>plist_id</code>, - <em>H5D_layout_t</em> <code>layout</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the type of storage used store the raw data for - a dataset. This function is only valid for dataset - creation property lists. Valid parameter for - <code>layout</code> are: - <ul> <dl> - <dt>H5D_COMPACT - <dd>Store raw data and object header contiguously in file. - This should only be used for very small amounts of raw - data (suggested less than 1KB). - <dt>H5D_CONTIGUOUS - <dd>Store raw data seperately from object header in one - large chunk in the file. - <dt>H5D_CHUNKED - <dd>Store raw data seperately from object header in one - large chunk in the file and store chunks of the raw - data in seperate locations in the file. - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list ID to query. - <dt><em>H5D_layout_t</em> <code>layout</code> - <dd>Type of storage layout for raw data. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-GetLayout">H5Pget_layout</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pget_layout</code>(<em>hid_t</em> <code>plist_id</code>, - <em>H5D_layout_t *</em> <code>layout</code> - ) -<dt><strong>Description:</strong> - <dd>Queries the layout of the raw data for a dataset. - This function is only valid for dataset creation property lists. - Valid types for <code>layout</code> are: - <ul> <dl> - <dt>H5D_COMPACT - <dd>Raw data and object header stored contiguously in file. - <dt>H5D_CONTIGUOUS - <dd>Raw data stored seperately from object header in one - large chunk in the file. - <dt>H5D_CHUNKED - <dd>Raw data stored seperately from object header in - chunks in seperate locations in the file. - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list ID to query. - <dt><em>H5D_layout_t *</em> <code>layout</code> - <dd>Pointer to location to return the storage layout. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-SetChunk">H5Pset_chunk</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pset_chunk</code>(<em>hid_t</em> <code>plist_id</code>, - <em>int</em> <code>ndims</code>, - <em>const hsize_t *</em> <code>dim</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the size of the chunks used to store a chunked - layout dataset. This function is only valid for dataset - creation property lists. The <code>ndims</code> parameter - currently must be the same size as the rank of the - dataset. The values of the <code>dim</code> array define - the size of the chunks to store the dataset's raw data. - As a side-effect, the layout of the dataset is changed to - H5D_CHUNKED, if it isn't already. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list ID to query. - <dt><em>int</em> <code>ndims</code> - <dd>The number of dimensions of each chunk. - <dt><em>const hsize_t *</em> <code>dim</code> - <dd>An array containing the size of each chunk. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Plist-GetChunk">H5Pget_chunk</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pget_chunk</code>(<em>hid_t</em> <code>plist_id</code>, - <em>int</em> <code>max_ndims</code> - <em>hsize_t *</em> <code>dims</code> - ) -<dt><strong>Description:</strong> - <dd>Queries the size of chunks for the raw data of a chunked layout - dataset. This function is only valid for dataset creation - property lists. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list ID to query. - <dt><em>int</em> <code>max_ndims</code> - <dd>Size of the <code>dims</code> array. - <dt><em>hsize_t *</em> <code>dims</code> - <dd>Array to store the chunk dimensions. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<!-- -<hr> -<h2><a name="Error">Error API Functions</a></h2> -<P>These functions allow flexible error reporting for the HDF5 library. -<br> -<br> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Error-SetPush">H5Eset_push</a> -<dt><strong>Signature:</strong> - <dd><em>H5E_push_func_t </em><code>H5Eset_push</code>(<em>H5E_push_func_t</em> <code>func</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets a function to call when an error is detected in - the library. The prototype of the H5E_push_func_t is: <br> -void H5E_push_func_t(int32 errid, hdf_maj_err_code_t maj, hdf_min_err_code_t min, const char *function_name, const char *file_name, intn line); -<dt><strong>Parameters:</strong> - <dl> - <dt><em>H5E_push_func_t</em><code>func</code> - <dd>Pointer to the error reporting function. - </dl> -<dt><strong>Returns:</strong> - <dd>The pointer to the previous error repoting function on succes, NULL on failure -</dl> ---> - -<!-- -<hr> -<h2><a name="Relationships">Relationships API Functions</a></h2> -<P>These functions provide methods of creating links between logically -related objects in a file. -<br> -<br> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Relationships-GetNumRelations">H5Rget_num_relations</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Rget_num_relations</code>(<em>hid_t </em><code>obj_id</code>, - <em>int32 *</em><code>num_attached</code>, - <em>int32 *</em><code>num_memberof</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the number of relationships attached to the - object and the number of other objects that the object is a member of - itself. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>obj_id</code> - <dd>ID of the object to query the number of attached relations - <dt><em>int32 *</em> <code>num_attached</code> - <dd>Number of objects attached to the object - <dt><em>int32 *</em> <code>num_memberof</code> - <dd>Number of objects that the object is a member of - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Relationships-GetMemberOfOIDs">H5Rget_memberof_oids</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Rget_memberof_oids</code>(<em>hid_t </em><code>obj_id</code>, - <em>hoid_t </em><code>memberof_list[]</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the OIDs of the objects that the object is a - member of. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>obj_id</code> - <dd>ID of the object to get the members of list - <dt><em>hoid_t *</em> <code>memberof_list</code> - <dd>A list of the OIDs for objects which the object is attached to. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Relationships-GetAttachedOIDs">H5Rget_attached_oids</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Rget_attached_oids</code>(<em>hid_t </em><code>obj_id</code>, - <em>hoid_t </em><code>attached_list[]</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the OIDs of the objects that are attached to - the object. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>obj_id</code> - <dd>ID of the object to get the attached OIDs from - <dt><em>hoid_t *</em> <code>attached_list</code> - <dd>A list of the OIDs for objects which are attached to the - object - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Relationships-Attach">H5Rattach_oid</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Rattach_oid</code>(<em>hid_t </em><code>obj_id</code>, - <em>hoid_t </em><code>attach</code> - ) -<dt><strong>Description:</strong> - <dd>This function attaches an OID to the object. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>obj_id</code> - <dd>ID of the object to attach an OID to - <dt><em>hoid_t </em> <code>attach</code> - <dd>The OID to attach to the object - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> ---> - -<hr> -<h2><a name="Dataset">Dataset Object API Functions</a></h2> -<P>These functions create and manipulate dataset objects. Each dataset must -be constructed from a datatype and a dataspace. -<br> -<br> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataset-Create">H5Dcreate</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Dcreate</code>(<em>hid_t </em><code>file_id</code>, - <em>const char *</em><code>name</code>, - <em>hid_t</em><code>type_id</code>, - <em>hid_t</em><code>space_id</code>, - <em>hid_t</em><code>plist_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function creates a new dataset in the file specified with the - <code>file_id</code>. The <code>type_id</code> and - <code>space_id</code> are the IDs of the datatype and - dataspace used to construct the framework of the dataset. The - datatype and dataspace parameters describe the dataset as it - will exist in the file, which is not necessarily the same as - it exists in memory. The <code>plist_id</code> contains - either the default property lists (H5P_DEFAULT) or a plist_id - with particular constant properties used to create the - dataset. The <code>name</code> is used to identify the - dataset in a group and must be unique within that group. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>file_id</code> - <dd>ID of the file to create the dataset within. - <dt><em>const char *</em> <code>name</code> - <dd>The name of the dataset to create. - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of the datatype to use when creating the dataset. - <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace to use when creating the dataset. - <dt><em>hid_t</em> <code>plist_id</code> - <dd>ID of the dataset creation property list. - </dl> -<dt><strong>Returns:</strong> - <dd>Dataset ID on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataset-Open">H5Dopen</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Dopen</code>(<em>hid_t </em><code>file_id</code>, - <em>const char *</em><code>name</code> - ) -<dt><strong>Description:</strong> - <dd>This function opens an existing dataset for access in the file - specified with the <code>file_id</code>. The <code>name</code> is - used to identify the dataset in the file. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>file_id</code> - <dd>ID of the file to access the dataset within. - <dt><em>const char *</em> <code>name</code> - <dd>The name of the dataset to access. - </dl> -<dt><strong>Returns:</strong> - <dd>Dataset ID on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataset-GetSpace">H5Dget_space</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Dget_space</code>(<em>hid_t </em><code>dataset_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function returns a copy of the dataspace for a dataset. The - dataspace should be released with the H5Sclose() function. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>dataset_id</code> - <dd>ID of the dataset to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Dataspace ID on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataset-GetType">H5Dget_type</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Dget_type</code>(<em>hid_t </em><code>dataset_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function returns a copy of the datatype for a dataset. The - dataspace should be released with the H5Tclose() function. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>dataset_id</code> - <dd>ID of the dataset to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Datatype ID on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataset-GetCreateParms">H5Dget_create_plist</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Dget_create_plist</code>(<em>hid_t </em><code>dataset_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function returns a copy of the dataset creation property - list for a dataset. The property list should be released with the - H5Pclose() function. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>dataset_id</code> - <dd>ID of the dataset to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Dataset creation property list ID on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataset-Read">H5Dread</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Dread</code>(<em>hid_t </em><code>dataset_id</code>, - <em>hid_t</em> <code>mem_type_id</code>, - <em>hid_t</em> <code>mem_space_id</code>, - <em>hid_t</em> <code>file_space_id</code>, - <em>hid_t</em> <code>transfer_plist_id</code>, - <em>void *</em> <code>buf</code> - ) -<dt><strong>Description:</strong> - <dd>This function reads raw data from the specified dataset into <code>buf</code>, - converting from the file datatype of the dataset into the - memory datatype specified in <code>mem_type_id</code>. The - portion of the dataset to read from disk is specified with the - <code>file_spaceid</code> which can contain a dataspace with a - hyperslab selected or the constant H5S_ALL, which indicates - the entire dataset is to be read. The portion of the dataset - read into the memory buffer is specified with the - <code>mem_space_id</code> which can also be a hyperslab of the - same size or the H5S_ALL parameter to store the entire - dataset. The <code>transfer_plist_id</code> is a dataset - transfer property list ID which is used to provide addition - parameters for the I/O operation or can be H5P_DEFAULT for the - default library behavior. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>dataset_id</code> - <dd>ID of the dataset read from. - <dt><em>hid_t</em> <code>mem_type_id</code> - <dd>ID of the memory datatype. - <dt><em>hid_t</em> <code>mem_space_id</code> - <dd>ID of the memory dataspace. - <dt><em>hid_t</em> <code>file_space_id</code> - <dd>ID of the dataset's dataspace in the file. - <dt><em>hid_t</em> <code>transfer_plist_id</code> - <dd>ID of a transfer property list for this I/O operation. - <dt><em>void *</em> <code>buf</code> - <dd>Buffer to store information read from the file. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataset-Write">H5Dwrite</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Dwrite</code>(<em>hid_t </em><code>dataset_id</code>, - <em>hid_t</em> <code>mem_type_id</code>, - <em>hid_t</em> <code>mem_space_id</code>, - <em>hid_t</em> <code>file_space_id</code>, - <em>hid_t</em> <code>transfer_plist_id</code>, - <em>const void *</em> <code>buf</code> - ) -<dt><strong>Description:</strong> - <dd>This function writes raw data from memory into the specified dataset - converting from the memory datatype of the dataset specified - in <code>mem_type_id</code> into the file datatype. The - portion of the dataset to written to disk is specified with - the <code>file_spaceid</code> which can contain a dataspace - with a hyperslab selected or the constant H5S_ALL, which - indicates the entire dataset is to be written. The portion of - the dataset written from the memory buffer is specified with - the <code>mem_space_id</code> which can also be a hyperslab of - the same size or the H5S_ALL parameter to store the entire - dataset. The <code>transfer_plist_id</code> is a dataset - transfer property list ID which is used to provide addition - parameters for the I/O operation or can be H5P_DEFAULT for the - default library behavior. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>dataset_id</code> - <dd>ID of the dataset read from. - <dt><em>hid_t</em> <code>mem_type_id</code> - <dd>ID of the memory datatype. - <dt><em>hid_t</em> <code>mem_space_id</code> - <dd>ID of the memory dataspace. - <dt><em>hid_t</em> <code>file_space_id</code> - <dd>ID of the dataset's dataspace in the file. - <dt><em>hid_t</em> <code>transfer_plist_id</code> - <dd>ID of a transfer property list for this I/O operation. - <dt><em>const void *</em> <code>buf</code> - <dd>Buffer to store information to be written to the file. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataset-Extend">H5Dextend</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Dextend</code>(<em>hid_t </em><code>dataset_id</code>, - <em>const hsize_t *</em> <code>size</code> - ) -<dt><strong>Description:</strong> - <dd>This function increases the size of the dataspace of a dataset with - unlimited dimensions. It cannot be used to extend the size of a - dataspace's fixed dimensions. The <code>size</code> array must have - the same number of entries as the rank of the dataset's dataspace. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>dataset_id</code> - <dd>ID of the dataset read from. - <dt><em>const hsize_t *</em> <code>size</code> - <dd>Array containing the new magnitude of each dimension. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataset-Close">H5Dclose</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Dclose</code>(<em>hid_t </em><code>dataset_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function ends access to a dataset and releases resources used by - it. Further use of the dataset ID is illegal in calls to the dataset - API. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>dataset_id</code> - <dd>ID of the dataset to finish access to. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<h2><a name="Datatype">Datatype Object API Functions</a></h2> -<P>These functions create and manipulate the datatype which describes elements -of a dataset. -<br> -<br> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-Create">H5Tcreate</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Tcreate</code>(<em>H5T_class_t </em><code>class</code>, - <em>size_t</em><code>size</code> - ) -<dt><strong>Description:</strong> - <dd>This function creates a new dataype of the specified class with the - specified number of bytes. Currently, only the <code>H5T_COMPOUND</code> - datatype class is supported with this function, use <code>H5Tcopy</code> - to create integer or floating-point datatypes. The datatype ID - returned from this function should be released with H5Tclose or resource - leaks will result. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>H5T_class_t</em> <code>class</code> - <dd>Class of datatype to create. - <dt><em>size_t</em> <code>size</code> - <dd>The number of bytes in the datatype to create. - </dl> -<dt><strong>Returns:</strong> - <dd>Datatype ID on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-Copy">H5Tcopy</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Tcopy</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function copies an existing datatype. The datatype ID returned - should be released with H5Tclose or resource leaks will occur. Native - datatypes supported by the library are: - <ul> <dl> - <dt>H5T_NATIVE_CHAR - <dd> Native character type, declare dataset array as 'char' - <dt>H5T_NATIVE_UCHAR - <dd> Native unsigned character type, declare dataset array as 'unsigned char' - <dt>H5T_NATIVE_SHORT - <dd> Native short type, declare dataset array as 'short' - <dt>H5T_NATIVE_USHORT - <dd> Native unsigned short type, declare dataset array as 'unsigned short' - <dt>H5T_NATIVE_INT - <dd> Native int type, declare dataset array as 'int' - <dt>H5T_NATIVE_UINT - <dd> Native unsigned int type, declare dataset array as 'unsigned int' - <dt>H5T_NATIVE_LONG - <dd> Native long type, declare dataset array as 'unsigned long' - <dt>H5T_NATIVE_ULONG - <dd> Native unsigned long type, declare dataset array as 'unsigned long' - <dt>H5T_NATIVE_LLONG - <dd> Native long long type, declare dataset array as 'unsigned long long' - <dt>H5T_NATIVE_ULLONG - <dd> Native unsigned long long type, declare dataset array as 'unsigned long long' - <dt>H5T_NATIVE_INT8 - <dd> Native signed 8-bit type, declare dataset array as 'int8' - <dt>H5T_NATIVE_UINT8 - <dd> Native unsigned 8-bit type, declare dataset array as 'uint8' - <dt>H5T_NATIVE_INT16 - <dd> Native signed 16-bit type, declare dataset array as 'int16' - <dt>H5T_NATIVE_UINT16 - <dd> Native unsigned 16-bit type, declare dataset array as 'uint16' - <dt>H5T_NATIVE_INT32 - <dd> Native signed 32-bit type, declare dataset array as 'int32' - <dt>H5T_NATIVE_UINT32 - <dd> Native unsigned 32-bit type, declare dataset array as 'uint32' - <dt>H5T_NATIVE_INT64 - <dd> Native signed 64-bit type, declare dataset array as 'uint64' - <dt>H5T_NATIVE_UINT64 - <dd> Native unsigned 64-bit type, declare dataset array as 'uint64' - <dt>H5T_NATIVE_FLOAT - <dd> Native single-precision float type, declare dataset array as 'float' - <dt>H5T_NATIVE_DOUBLE - <dd> Native double-precision float type, declare dataset array as 'double' - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to copy. - </dl> -<dt><strong>Returns:</strong> - <dd>Datatype ID on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-Equal">H5Tequal</a> -<dt><strong>Signature:</strong> - <dd><em>hbool_t </em><code>H5Tequal</code>(<em>hid_t </em><code>type_id1</code>, - <em>hid_t</em><code>type_id2</code> - ) -<dt><strong>Description:</strong> - <dd>This function determines if two datatype IDs refer to the same - datatype. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id1</code> - <dd>ID of datatype to compare. - <dt><em>hid_t</em> <code>type_id2</code> - <dd>ID of datatype to compare. - </dl> -<dt><strong>Returns:</strong> - <dd>TRUE/FALSE/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-Lock">H5Tlock</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tlock</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function locks a type, making it read-only and non-destrucible. - This is normally done by the library for predefined data types so the - application doesn't inadvertently change or delete a predefined type. - Once a data type is locked it can never be unlocked. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to lock. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetClass">H5Tget_class</a> -<dt><strong>Signature:</strong> - <dd><em>H5T_class_t </em><code>H5Tget_class</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function returns the base class of a datatype. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Non-negative type class on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetSize">H5Tget_size</a> -<dt><strong>Signature:</strong> - <dd><em>size_t </em><code>H5Tget_size</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function returns the size of a datatype in bytes. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Positve size in bytes on success, 0 on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-SetSize">H5Tset_size</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_size</code>(<em>hid_t </em><code>type_id</code>, - <em>size_t</em><code>size</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the total size in bytes for an atomic data type (this - operation is not permitted on compound data types). If the size is - decreased so that the significant bits of the data type extend beyond - the edge of the new size, then the `offset' property is decreased - toward zero. If the `offset' becomes zero and the significant - bits of the data type still hang over the edge of the new size, then - the number of significant bits is decreased. - Adjusting the size of an H5T_STRING automatically sets the precision - to 8*size. All data types have a positive size. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to change size. - <dt><em>size_t</em> <code>size</code> - <dd>Size in bytes to modify datatype. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetOrder">H5Tget_order</a> -<dt><strong>Signature:</strong> - <dd><em>H5T_order_t </em><code>H5Tget_order</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function returns the byte order of an atomic datatype. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Byte order constant on success, negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-SetOrder">H5Tset_order</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_order</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_order_t</em><code>order</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the byte ordering of an atomic datatype. - Byte orderings currently supported are: - <ul> <dl> - <dt>H5T_ORDER_LE - <dd> Little-endian byte ordering (default) - <dt>H5T_ORDER_BE - <dd> Big-endian byte ordering - <dt>H5T_ORDER_Vax - <dd> VAX-endianness byte ordering (not currently supported) - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. - <dt><em>H5T_order_t</em> <code>order</code> - <dd>Byte ordering constant. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetPrecision">H5Tget_precision</a> -<dt><strong>Signature:</strong> - <dd><em>size_t </em><code>H5Tget_precision</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function returns the precision of an atomic data type. The - precision is the number of significant bits which, unless padding is - present, is 8 times larger than the value returned by H5Tget_size(). -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Number of significant bits on success, 0 on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-SetPrecision">H5Tset_precision</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_precision</code>(<em>hid_t </em><code>type_id</code>, - <em>size_t</em><code>precision</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the precision of an atomic data type. The precision - is the number of significant bits which, unless padding is present, is 8 - times larger than the value returned by H5Tget_size(). - <P>If the precision is increased then the offset is decreased and then - the size is increased to insure that significant bits do not "hang - over" the edge of the data type. - <P>Changing the precision of an H5T_STRING automatically changes the - size as well. The precision must be a multiple of 8. - <P>When decreasing the precision of a floating point type, set the - locations and sizes of the sign, mantissa, and exponent fields - first. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. - <dt><em>size_t</em> <code>precision</code> - <dd>Number of bits of precision for datatype. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetOffset">H5Tget_offset</a> -<dt><strong>Signature:</strong> - <dd><em>size_t </em><code>H5Tget_offset</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the bit offset of the first significant bit. - The signficant bits of an atomic datum can be offset from the beginning - of the memory for that datum by an amount of padding. The `offset' - property specifies the number of bits of padding that appear to the - "right of" the value. That is, if we have a 32-bit datum with 16-bits - of precision having the value 0x1122 then it will be layed out in - memory as (from small byte address toward larger byte addresses): - <br> - <br> - - <table border align=center cellpadding=4 width="80%"> - <tr align=center> - <th width="20%">Byte Position</th> - <th width="20%">Big-Endian Offset=0</th> - <th width="20%">Big-Endian Offset=16</th> - <th width="20%">Little-Endian Offset=0</th> - <th width="20%">Little-Endian Offset=16</th> - </tr> - <tr align=center> - <td>0:</td> - <td>[ pad]</td> - <td>[0x11]</td> - <td>[0x22]</td> - <td>[ pad]</td> - </tr> - <tr align=center> - <td>1:</td> - <td>[ pad]</td> - <td>[0x22]</td> - <td>[0x11]</td> - <td>[ pad]</td> - </tr> - <tr align=center> - <td>2:</td> - <td>[0x11]</td> - <td>[ pad]</td> - <td>[ pad]</td> - <td>[0x22]</td> - </tr> - <tr align=center> - <td>3:</td> - <td>[0x22]</td> - <td>[ pad]</td> - <td>[ pad]</td> - <td>[0x11]</td> - </tr> - </table> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Positive offset value on success, 0 on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-SetOffset">H5Tset_offset</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_offset</code>(<em>hid_t </em><code>type_id</code>, - <em>size_t</em> <code>offset</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the bit offset of the first significant bit. The - signficant bits of an atomic datum can be offset from the beginning of - the memory for that datum by an amount of padding. The `offset' - property specifies the number of bits of padding that appear to the - "right of" the value. That is, if we have a 32-bit datum with 16-bits - of precision having the value 0x1122 then it will be layed out in - memory as (from small byte address toward larger byte addresses): - <br> - <br> - - <table border align=center cellpadding=4 width="80%"> - <tr align=center> - <th width="20%">Byte Position</th> - <th width="20%">Big-Endian Offset=0</th> - <th width="20%">Big-Endian Offset=16</th> - <th width="20%">Little-Endian Offset=0</th> - <th width="20%">Little-Endian Offset=16</th> - </tr> - <tr align=center> - <td>0:</td> - <td>[ pad]</td> - <td>[0x11]</td> - <td>[0x22]</td> - <td>[ pad]</td> - </tr> - <tr align=center> - <td>1:</td> - <td>[ pad]</td> - <td>[0x22]</td> - <td>[0x11]</td> - <td>[ pad]</td> - </tr> - <tr align=center> - <td>2:</td> - <td>[0x11]</td> - <td>[ pad]</td> - <td>[ pad]</td> - <td>[0x22]</td> - </tr> - <tr align=center> - <td>3:</td> - <td>[0x22]</td> - <td>[ pad]</td> - <td>[ pad]</td> - <td>[0x11]</td> - </tr> - </table> - -<P>If the offset is incremented then the total size is -incremented also if necessary to prevent significant bits of -the value from hanging over the edge of the data type. - -<P>The offset of an H5T_STRING cannot be set to anything but -zero. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. - <dt><em>size_t</em> <code>offset</code> - <dd>Offset of first significant bit. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetPad">H5Tget_pad</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tget_pad</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_pad_t *</em> <code>lsb</code>, - <em>H5T_pad_t *</em> <code>msb</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the padding type of the least and most-significant - bit padding. Valid types are: - <ul> <dl> - <dt>H5T_PAD_ZERO - <dd>Set background to zeros. - <dt>H5T_PAD_ONE - <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND - <dd>Leave background alone. - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - <dt><em>H5T_pad_t *</em> <code>lsb</code> - <dd>Pointer to location to return least-significant bit padding type. - <dt><em>H5T_pad_t *</em> <code>msb</code> - <dd>Pointer to location to return most-significant bit padding type. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-SetPad">H5Tset_pad</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_pad</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_pad_t</em> <code>lsb</code>, - <em>H5T_pad_t</em> <code>msb</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the least and most-significant bits padding types. - <ul> <dl> - <dt>H5T_PAD_ZERO - <dd>Set background to zeros. - <dt>H5T_PAD_ONE - <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND - <dd>Leave background alone. - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. - <dt><em>H5T_pad_t</em> <code>lsb</code> - <dd>Padding type for least-significant bits. - <dt><em>H5T_pad_t</em> <code>msb</code> - <dd>Padding type for most-significant bits. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetSign">H5Tget_sign</a> -<dt><strong>Signature:</strong> - <dd><em>H5T_sign_t </em><code>H5Tget_sign</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the sign type for an integer type. - Valid types are: - <ul> <dl> - <dt>H5T_SGN_NONE - <dd>Unsigned integer type. - <dt>H5T_SGN_2 - <dd>Two's complement signed integer type. - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Non-negative sign type on success, negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-SetSign">H5Tset_sign</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_sign</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_sign_t</em> <code>sign</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the sign proprety for an integer type. - <ul> <dl> - <dt>H5T_SGN_NONE - <dd>Unsigned integer type. - <dt>H5T_SGN_2 - <dd>Two's complement signed integer type. - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. - <dt><em>H5T_sign_t</em> <code>sign</code> - <dd>Sign type. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetFields">H5Tget_fields</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tget_fields</code>(<em>hid_t </em><code>type_id</code>, - <em>size_t *</em> <code>epos</code>, - <em>size_t *</em> <code>esize</code>, - <em>size_t *</em> <code>mpos</code>, - <em>size_t *</em> <code>msize</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves information about the locations of the various - bit fields of a floating point data type. The field positions are bit - positions in the significant region of the data type. Bits are - numbered with the least significant bit number zero. - Any (or even all) of the arguments can be null pointers. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - <dt><em>size_t *</em> <code>epos</code> - <dd>Pointer to location to return exponent bit-position. - <dt><em>size_t *</em> <code>esize</code> - <dd>Pointer to location to return size of exponent in bits. - <dt><em>size_t *</em> <code>mpos</code> - <dd>Pointer to location to return mantissa bit-position. - <dt><em>size_t *</em> <code>msize</code> - <dd>Pointer to location to return size of mantissa in bits. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-SetFields">H5Tset_fields</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_fields</code>(<em>hid_t </em><code>type_id</code>, - <em>size_t</em> <code>epos</code>, - <em>size_t</em> <code>esize</code>, - <em>size_t</em> <code>mpos</code>, - <em>size_t</em> <code>msize</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the locations and sizes of the various floating - point bit fields. The field positions are bit positions in the - significant region of the data type. Bits are numbered with the least - significant bit number zero. - - <P>Fields are not allowed to extend beyond the number of bits of - precision, nor are they allowed to overlap with one another. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. - <dt><em>size_t</em> <code>epos</code> - <dd>Exponent bit position. - <dt><em>size_t</em> <code>esize</code> - <dd>Size of exponent in bits. - <dt><em>size_t</em> <code>mpos</code> - <dd>Mantissa bit position. - <dt><em>size_t</em> <code>msize</code> - <dd>Size of mantissa in bits. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetEbias">H5Tget_ebias</a> -<dt><strong>Signature:</strong> - <dd><em>size_t </em><code>H5Tget_ebias</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the exponent bias of a floating-point type. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Positive value on success, 0 on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-SetEbias">H5Tset_ebias</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_ebias</code>(<em>hid_t </em><code>type_id</code>, - <em>size_t</em> <code>ebias</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the exponent bias of a floating-point type. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. - <dt><em>size_t</em> <code>ebias</code> - <dd>Exponent bias value. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetNorm">H5Tget_norm</a> -<dt><strong>Signature:</strong> - <dd><em>H5T_norm_t </em><code>H5Tget_norm</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the mantissa normalization of a floating-point - datatype. Valid normalization values are: - <ul> <dl> - <dt>H5T_NORM_IMPLIED - <dd>MSB of mantissa isn't stored, always 1 - <dt>H5T_NORM_MSBSET - <dd>MSB of mantissa is always 1 - <dt>H5T_NORM_NONE - <dd>Mantissa is not normalized - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Non-negative normalization type on success, negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-SetNorm">H5Tset_norm</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_norm</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_norm_t</em> <code>norm</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets the mantissa normalization of a floating-point - datatype. Valid normalization values are: - <ul> <dl> - <dt>H5T_NORM_IMPLIED - <dd>MSB of mantissa isn't stored, always 1 - <dt>H5T_NORM_MSBSET - <dd>MSB of mantissa is always 1 - <dt>H5T_NORM_NONE - <dd>Mantissa is not normalized - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. - <dt><em>H5T_norm_t</em> <code>norm</code> - <dd>Mantissa normalization type. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetInpad">H5Tget_inpad</a> -<dt><strong>Signature:</strong> - <dd><em>H5T_pad_t </em><code>H5Tget_inpad</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the internal padding type for unused bits in - floating-point datatypes. - Valid padding values are: - <ul> <dl> - <dt>H5T_PAD_ZERO - <dd>Set background to zeros. - <dt>H5T_PAD_ONE - <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND - <dd>Leave background alone. - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Non-negative padding type on success, negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-SetInpad">H5Tset_inpad</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_inpad</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_pad_t</em> <code>inpad</code> - ) -<dt><strong>Description:</strong> - <dd>If any internal bits of a floating point type are unused - (that is, those significant bits which are not part of the - sign, exponent, or mantissa) then they will be filled - according to the value of this property. - Valid padding values are: - <ul> <dl> - <dt>H5T_PAD_ZERO - <dd>Set background to zeros. - <dt>H5T_PAD_ONE - <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND - <dd>Leave background alone. - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to modify. - <dt><em>H5T_pad_t</em> <code>pad</code> - <dd>Padding type. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetCset">H5Tget_cset</a> -<dt><strong>Signature:</strong> - <dd><em>H5T_cset_t </em><code>H5Tget_cset</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the character set type of a string datatype. - Valid character set values are: - <ul> <dl> - <dt>H5T_CSET_ASCII - <dd>Character set is US ASCII - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Non-negative character set type on success, negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-SetCset">H5Tset_cset</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_cset</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_cset_t</em> <code>cset</code> - ) -<dt><strong>Description:</strong> - <dd>HDF5 is able to distinguish between character sets of different - nationalities and to convert between them to the extent possible. - Valid character set values are: - <ul> <dl> - <dt>H5T_CSET_ASCII - <dd>Character set is US ASCII - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to modify. - <dt><em>H5T_cset_t</em> <code>cset</code> - <dd>Character set type. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetStrpad">H5Tget_strpad</a> -<dt><strong>Signature:</strong> - <dd><em>H5T_str_t </em><code>H5Tget_strpad</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the string padding method for a string datatype. - Valid string padding values are: - <ul> <dl> - <dt>H5T_STR_NULL - <dd>Pad with zeros (as C does) - <dt>H5T_STR_SPACE - <dd>Pad with spaces (as FORTRAN does) - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Non-negative string padding type on success, negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-SetStrpad">H5Tset_strpad</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_strpad</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_str_t</em> <code>strpad</code> - ) -<dt><strong>Description:</strong> - <dd>The method used to store character strings differs with the programming - language: C usually null terminates strings while Fortran - left-justifies and space-pads strings. This property defines the - storage mechanism for the string. - Valid string padding values are: - <ul> <dl> - <dt>H5T_STR_NULL - <dd>Pad with zeros (as C does) - <dt>H5T_STR_SPACE - <dd>Pad with spaces (as FORTRAN does) - </dl> </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to modify. - <dt><em>H5T_str_t</em> <code>strpad</code> - <dd>String padding type. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetNmembers">H5Tget_nmembers</a> -<dt><strong>Signature:</strong> - <dd><em>intn </em><code>H5Tget_nmembers</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the number of fields a compound datatype has. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - </dl> -<dt><strong>Returns:</strong> - <dd>Number of members datatype has on success, negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetMemberName">H5Tget_member_name</a> -<dt><strong>Signature:</strong> - <dd><em>char *</em> <code>H5Tget_member_name</code>(<em>hid_t </em><code>type_id</code>, - <em>intn</em> <code>fieldno</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the name of a field of a compound data type. - Fields are stored in no particular order with numbers 0 through N-1 - where N is the value returned by H5Tget_nmembers(). The name of the - field is allocated with malloc() and the caller is responsible for - freeing the memory used by the name. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - <dt><em>intn</em> <code>fieldno</code> - <dd>Field number (indexed from 0) of the field name to retrieve. - </dl> -<dt><strong>Returns:</strong> - <dd>Valid pointer on success, NULL on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetMemberDims">H5Tget_member_dims</a> -<dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Tget_member_dims</code>(<em>hid_t </em><code>type_id</code>, - <em>intn</em> <code>fieldno</code>, - <em>size_t *</em> <code>dims</code>, - <em>int *</em> <code>perm</code> - ) -<dt><strong>Description:</strong> - <dd>This function returns the dimensionality of the field. The dimensions - and permuation vector are returned through arguments <code>dims</code> - and <code>perm</code>, both arrays of at least four elements. Either - (or even both) may be null pointers. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - <dt><em>intn</em> <code>fieldno</code> - <dd>Field number (indexed from 0) of the field dims to retrieve. - <dt><em>size_t *</em> <code>dims</code> - <dd>Pointer to buffer to store the dimensions of the field. - <dt><em>int *</em> <code>perm</code> - <dd>Pointer to buffer to store the permutation vector of the field. - </dl> -<dt><strong>Returns:</strong> - <dd>Number of dimensions on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetMemberType">H5Tget_member_type</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t</em> <code>H5Tget_member_type</code>(<em>hid_t </em><code>type_id</code>, - <em>intn</em> <code>fieldno</code> - ) -<dt><strong>Description:</strong> - <dd>This function returns the data type of the specified member. The caller - should invoke H5Tclose() to release resources associated with the type. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - <dt><em>intn</em> <code>fieldno</code> - <dd>Field number (indexed from 0) of the field type to retrieve. - </dl> -<dt><strong>Returns:</strong> - <dd>The ID of a copy of the datatype of the field, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-Insert">H5Tinsert</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Tinsert</code>(<em>hid_t </em><code>type_id</code>, - <em>const char *</em> <code>name</code>, - <em>off_t</em> <code>offset</code>, - <em>hid_t</em> <code>field_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function adds another member to the compound data type - <code>type_id</code>. The new member has a <code>name</code> which - must be unique within the compound data type. The <code>offset</code> - argument defines the start of the member in an instance of the compound - data type, and <code>field_id</code> is the type of the new member. - - <P>Note: All members of a compound data type must be atomic; a - compound data type cannot have a member which is a compound data - type. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of compound datatype to modify. - <dt><em>const char *</em> <code>name</code> - <dd>Name of the field to insert. - <dt><em>off_t</em> <code>offset</code> - <dd>Offset in memory structure of the field to insert. - <dt><em>hid_t</em> <code>field_id</code> - <dd>Datatype ID of the field to insert. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-Pack">H5Tpack</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Tpack</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function recursively removes padding from within a compound - datatype to make it more efficient (space-wise) to store that data. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to modify. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-RegisterHard">H5Tregister_hard</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Tregister_hard</code>(<em>const char - *</em> <code>name</code>, <em>hid_t </em><code>src_id</code>, - <em>hid_t</em> <code>dst_id</code>, - <em>H5T_conv_t</em> <code>func</code> - ) -<dt><strong>Description:</strong> - <dd>This function registers a hard conversion function for a data type - conversion path. The path is specified by the source and destination - datatypes <code>src_id</code> and <code>dst_id</code>. A conversion - path can only have one hard function, so <code>func</code> replaces any - previous hard function. - <P>If <code>func</code> is the null pointer then any hard function - registered for this path is removed from this path. The soft functions - are then used when determining which conversion function is appropriate - for this path. The <code>name</code> argument is used only - for debugging and should be a short identifier for the function. - <P>The type of the conversion function pointer is declared as: - typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, - size_t nelmts, void *buf, void *bkg); -<dt><strong>Parameters:</strong> - <dl> - <dt><em>const char *</em> <code>name</code> - <dd>Name displayed in diagnostic output. - <dt><em>hid_t</em> <code>src_id</code> - <dd>ID of source datatype. - <dt><em>hid_t</em> <code>dst_id</code> - <dd>ID of destination datatype. - <dt><em>H5T_conv_t</em> <code>func</code> - <dd>Function to convert between source and destination datatypes. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-RegisterSoft">H5Tregister_soft</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Tregister_soft</code>(<em>const char - *</em> <code>name</code>, <em>hid_t </em><code>src_id</code>, - <em>hid_t</em> <code>dst_id</code>, - <em>H5T_conv_t</em> <code>func</code> - ) -<dt><strong>Description:</strong> - <dd>This function registers a soft conversion function by adding it to the - end of the master soft list and replacing the soft function in all - applicable existing conversion paths. The <code>name</code> - is used only for debugging and should be a short identifier - for the function. - <P>The type of the conversion function pointer is declared as: - typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, - size_t nelmts, void *buf, void *bkg); -<dt><strong>Parameters:</strong> - <dl> - <dt><em>const char *</em> <code>name</code> - <dd>Name displayed in diagnostic output. - <dt><em>hid_t</em> <code>src_id</code> - <dd>ID of source datatype. - <dt><em>hid_t</em> <code>dst_id</code> - <dd>ID of destination datatype. - <dt><em>H5T_conv_t</em> <code>func</code> - <dd>Function to convert between source and destination datatypes. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-Unregister">H5Tunregister</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Tunregister</code>(<em>H5T_conv_t</em> <code>func</code> - ) -<dt><strong>Description:</strong> - <dd>This function removes a conversion function from all conversion paths. - <P>The type of the conversion function pointer is declared as: - typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, - size_t nelmts, void *buf, void *bkg); -<dt><strong>Parameters:</strong> - <dl> - <dt><em>H5T_conv_t</em> <code>func</code> - <dd>Function to remove from conversion paths. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-Close">H5Tclose</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tclose</code>(<em>hid_t </em><code>type_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function releases a datatype. Further access through the datatype - ID is illegal. Failure to release a datatype with this call will - result in resource leaks. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to release. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - - -<hr> -<h2><a name="Dataspace">Dataspace Object API Functions</a></h2> -<P>These functions create and manipulate the dataspace in which to store the -elements of a dataset. -<br> -<br> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataspace-CreateSimple">H5Screate_simple</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t</em> <code>H5Screate_simple</code>(<em>int</em> <code>rank</code>, - <em>const hsize_t *</em> <code>dims</code>, - <em>const hsize_t *</em> <code>maxdims</code> - ) -<dt><strong>Description:</strong> - <dd>This function creates a new simple data space object and opens it for - access. The <code>rank</code> is the number of dimensions used in the - dataspace. The <code>dims</code> argument is the size of the simple - dataset and the <code>maxdims</code> argument is the upper limit on the - size of the dataset. <code>maxdims</code> may be the null pointer in - which case the upper limit is the same as <code>dims</code>. If an - element of <code>maxdims</code> is zero then the corresponding dimension - is unlimited, otherwise no element of <code>maxdims</code> should be - smaller than the corresponding element of <code>dims</code>. The - dataspace ID returned from this function should be released with - H5Sclose or resource leaks will occur. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>int</em> <code>rank</code> - <dd>Number of dimensions of dataspace. - <dt><em>const hsize_t *</em> <code>dims</code> - <dd>An array of the size of each dimension. - <dt><em>const hsize_t *</em> <code>maxdims</code> - <dd>An array of the maximum size of each dimension. - </dl> -<dt><strong>Returns:</strong> - <dd>A dataspace ID on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataspace-Copy">H5Scopy</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Scopy</code>(<em>hid_t </em><code>space_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function copies a dataspace. The dataspace ID returned from this - function should be released with H5Sclose or resource leaks will occur. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of dataspace to copy. - </dl> -<dt><strong>Returns:</strong> - <dd>A dataspace ID on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataspace-GetNpoints">H5Sget_npoints</a> -<dt><strong>Signature:</strong> - <dd><em>hsize_t</em> <code>H5Sget_npoints</code>(<em>hid_t </em><code>space_id</code>) -<dt><strong>Description:</strong> - <dd>This function determines the number of elements in a dataspace. For - example, a simple 3-dimensional dataspace with dimensions 2, 3 and 4 - would have 24 elements. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace object to query - </dl> -<dt><strong>Returns:</strong> - <dd>Number of elements in the dataspace, 0 on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataspace-GetNdims">H5Sget_ndims</a> -<dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Sget_ndims</code>(<em>hid_t</em> <code>space_id</code>) -<dt><strong>Description:</strong> - <dd>This function determines the dimensionality (or rank) of a dataspace. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace object to query - </dl> -<dt><strong>Returns:</strong> - <dd>Number of dimensions in the dataspace, negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataspace-GetDims">H5Sget_dims</a> -<dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Sget_dims</code>(<em>hid_t</em> <code>space_id</code>, - <em>hsize_t *</em><code>dims</code>, - <em>hsize_t *</em><code>maxdims</code> - ) -<dt><strong>Description:</strong> - <dd>This function returns the size of each dimension in a dataspace through - the <code>dims</code> parameter. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace object to query - <dt><em>hsize_t *</em><code>dims</code> - <dd>Pointer to array to store the size of each dimension. - <dt><em>hsize_t *</em><code>maxdims</code> - <dd>Pointer to array to store the maximum size of each dimension. - </dl> -<dt><strong>Returns:</strong> - <dd>Number of dimensions in the dataspace, negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataspace-IsSimple">H5Sis_simple</a> -<dt><strong>Signature:</strong> - <dd><em>hbool_t </em><code>H5Sis_simple</code>(<em>hid_t </em><code>space_id</code>) -<dt><strong>Description:</strong> - <dd>This function determines whether a dataspace object is a simple - dataspace or not. [Currently, all dataspace objects are simple - dataspaces, complex dataspace support will be added in the future] -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace object to query - </dl> -<dt><strong>Returns:</strong> - <dd>TRUE or FALSE on success, negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataspace-SetSpace">H5Sset_space</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Sset_space</code>(<em>hid_t </em><code>space_id</code>, - <em>uint32 </em><code>rank</code>, - <em>uint32 *</em><code>dims</code> - ) -<dt><strong>Description:</strong> - <dd>This function determines the number of dimensions and the size of each - dimension for the space that a dataset is stored within. This function - only creates simple dataspace objects. Setting the rank to a - value of zero allows scalar objects to be created. Dimensions are - specified from slowest to fastest changing in the <code>dims</code> - array (i.e. 'C' order). Setting the size of a dimension to zero - indicates that the dimension is of unlimited size and should be allowed - to expand. Currently, only the first dimension in the array (the - slowest) may be unlimited in size. - [Currently, all dataspace objects are simple - dataspaces, complex dataspace support will be added in the future] -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace object. - <dt><em>uint32</em> <code>rank</code> - <dd>The number of dimensions the object is composed of. - <dt><em>uint32 *</em> <code>dims</code> - <dd>An array of the size of each dimension. (NULL for scalar objects) - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataspace-SetHyperslab">H5Sset_hyperslab</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Sset_hyperslab</code>(<em>hid_t</em> <code>space_id</code>, - <em>const hssize_t *</em><code>start</code>, - <em>const hsize_t *</em><code>count</code>, - <em>const hsize_t *</em><code>stride</code> - ) -<dt><strong>Description:</strong> - <dd>This function selects a hyperslab from a simple dataspace. The stride - array may be used to sub-sample the hyperslab chosen, a value of 1 in each - position of the stride array selects contiguous elements in the array, - a value of 2 selects every other element, etc. If the stride parameter is - set to NULL, a contiguous hyperslab is chosen. The values in the start and - count arrays may be negative, to allow for selecting hyperslabs in chunked - datasets which extend in arbitrary directions. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace object to set hyperslab in. - <dt><em>const hssize_t *</em><code>start</code> - <dd>Pointer to array of starting location for hyperslab. - <dt><em>const hsize_t *</em><code>count</code> - <dd>Pointer to array of magnitude of hyperslab. - <dt><em>const hsize_t *</em><code>stride</code> - <dd>Pointer to array of stride of hyperslab. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataspace-GetHyperslab">H5Sget_hyperslab</a> -<dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Sget_hyperslab</code>(<em>hid_t</em> <code>space_id</code>, - <em>hssize_t *</em><code>start</code>, - <em>hsize_t *</em><code>count</code>, - <em>hsize_t *</em><code>stride</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves information about the hyperslab from a simple - dataspace. If no hyperslab has been defined then the hyperslab is the - same as the entire array. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace object to set hyperslab in. - <dt><em>hssize_t *</em><code>start</code> - <dd>Pointer to array to store starting location of hyperslab. - <dt><em>hsize_t *</em><code>count</code> - <dd>Pointer to array to store magnitude of hyperslab. - <dt><em>hsize_t *</em><code>stride</code> - <dd>Pointer to array to store stride of hyperslab. - </dl> -<dt><strong>Returns:</strong> - <dd>Hyperslab dimensionality on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataspace-Close">H5Sclose</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Sclose</code>(<em>hid_t </em><code>space_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function releases a dataspace. Further access through the dataspace - ID is illegal. Failure to release a dataspace with this call will - result in resource leaks. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of dataspace to release. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<h2><a name="Group">Group Object API Functions</a></h2> - -<p>A group associates names with objects and provides a mechanism -which can map a name to an object. Since all objects -appear in at least one group (with the possible exception of the root -object) and since objects can have names in more than one group, the -set of all objects in an HDF5 file is a directed graph. The internal -nodes (nodes with out-degree greater than zero) must be groups while -the leaf nodes (nodes with out-degree zero) are either empty groups or -objects of some other type. Exactly one object in every non-empty -file is the root object. The root object always has a positive -in-degree because it is pointed to by the file boot block. - -<p>Every file handle returned by <code>H5Fcreate</code> or -<code>H5Fopen</code> maintains an independent current working group -stack, the top item of which is the current working group (the root -object is the current working group if the stack is empty). The stack -can be manipulated with <code>H5Gset</code>, <code>H5Gpush</code>, and -<code>H5Gpop</code>. - -<p>An object name consists of one or more components separated from -one another by slashes. If the name begins with a slash then the -object is located by looking for the first component in the root -object, then looking for the second component in that object, etc., -until the entire name is traversed. If the name doesn't begin with a -slash then the traversal begins with the current working group. - -<p>The library does not maintain the full absolute name of its current -working group because (1) cycles in the graph can make the name length -unbounded and (2) a group doesn't necessarily have a unique name. A -more Unix-like hierarchical naming scheme can be implemented on top of -the directed graph scheme by creating a ".." entry in each group that -points to its single predecessor and then a <code>getcwd</code> -function would be trivial. - -<br> -<br> - -<hr> - <dl> - <dt><strong>Name:</strong> <a name="Group-Create">H5Gcreate</a> - <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Gset</code> (<em>hid_t</em> - <code>file</code>, <em>const char *</em><code>name</code>, - <em>size_t</em> <code>size_hint</code>) - <dt><strong>Description:</strong> - <dd>This function creates a new empty group and gives it a name. - <dt><strong>Parameters:</strong> - <dd> - <dl> - <dt><em>hid_t</em> <code>file</code> - <dd>The file handle returned by <code>H5Fcreate</code> or - <code>H5Fopen</code>. - <dt><em>const char *</em><code>name</code> - <dd>The absolute or relative name of the new group. - <dt><em>size_t</em> <code>size_hint</code> - <dd>The size hint is an optional parameter that indicates - the number of bytes to reserve for the names that will - appear in the group. A conservative estimate could result - in multiple system-level I/O requests to read the group - name heap while a liberal estimate could result in a - single large I/O request even when the group has just a - few names. HDF5 stores each name with a null terminator. - </dl> - <dt><strong>Returns:</strong> - <dd>Returns a negative value on failure, non-negative otherwise. - </dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Group-Open">H5Sopen</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Gopen</code>(<em>hid_t</em> <code>file_id</code>, - <em>const char *</em><code>name</code> - ) -<dt><strong>Description:</strong> - <dd>This function opens an existing group for modification. When finished, - call H5Gclose() to close it and release resources. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>file_id</code> - <dd>ID of file to open group within. - <dt><em>const char *</em> <code>name</code> - <dd>Name of group to open. - </dl> -<dt><strong>Returns:</strong> - <dd>Valid group ID on success, negative on failure. -</dl> - -<hr> - <dl> - <dt><strong>Name:</strong> <a name="Group-Set">H5Gset</a> - <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Gset</code> (<em>hid_t</em> - <code>file</code>, <em>const char *</em><code>name</code>) - <dt><strong>Description:</strong> - <dd>This function sets the current working group by modifying the - top element of the current working group stack or, if the - stack is empty, by pushing a new element onto the stack. - <dt><strong>Parameters:</strong> - <dd> - <dl> - <dt><em>hid_t</em> <code>file</code> - <dd>The file handle returned by <code>H5Fcreate</code> or - <code>H5Fopen</code>. - <dt><em>const char *</em><code>name</code> - <dd>The name of the new current working group. If the name - doesn't begin with a slash then it is looked up relative the - the previous current working group. - </dl> - <dt><strong>Returns:</strong> - <dd>Returns a negative value on failure, non-negative otherwise. - </dl> - -<hr> - <dl> - <dt><strong>Name:</strong> <a name="Group-Push">H5Gpush</a> - <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Gpush</code> (<em>hid_t</em> - <code>file</code>, <em>const char *</em><code>name</code>) - <dt><strong>Description:</strong> - <dd>This function sets the current working group by pushing a - new element onto the current working group stack. - <dt><strong>Parameters:</strong> - <dd> - <dl> - <dt><em>hid_t</em> <code>file</code> - <dd>The file handle returned by <code>H5Fcreate</code> or - <code>H5Fopen</code>. - <dt><em>const char *</em><code>name</code> - <dd>The name of the new current working group. If the name - doesn't begin with a slash then it is looked up relative the - the previous current working group. - </dl> - <dt><strong>Returns:</strong> - <dd>Returns a negative value on failure, non-negative otherwise. - </dl> - -<hr> - <dl> - <dt><strong>Name:</strong> <a name="Group-Pop">H5Gpop</a> - <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Gpop</code> (<em>hid_t</em> - <code>file</code>) - <dt><strong>Description:</strong> - <dd>This function restores the previous current working group by - popping an element from the current working group stack. An - empty stack implies that the current working group is the root - object. Attempting to pop an empty stack results in failure. - <dt><strong>Parameters:</strong> - <dd> - <dl> - <dt><em>hid_t</em> <code>file</code> - <dd>The file handle returned by <code>H5Fcreate</code> or - <code>H5Fopen</code>. - </dl> - <dt><strong>Returns:</strong> - <dd>Returns a negative value on failure, non-negative otherwise. - </dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Group-Close">H5Gclose</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Gclose</code>(<em>hid_t </em><code>group_id</code> - ) -<dt><strong>Description:</strong> - <dd>This function releases a group. Further access through the group - ID is illegal. Failure to release a group with this call will - result in resource leaks. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>group_id</code> - <dd>ID of group to release. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<!-- -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Group-GetNumContents">H5Gget_num_contents</a> -<dt><strong>Signature:</strong> - <dd><em>uint32 </em><code>H5Gget_num_contents</code>(<em>hid_t </em><code>grp_id</code>) -<dt><strong>Description:</strong> - <dd>This function retrieves the number of objects in the contents of the - group. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>grp_id</code> - <dd>ID of the group object to query - </dl> -<dt><strong>Returns:</strong> - <dd>Number of objects in group's contents on success, Unegative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Group-GetContentInfo">H5Gget_content_info</a> -<dt><strong>Signature:</strong> - <dd><em>uint32 </em><code>H5Gget_content_info</code>(<em>hid_t </em><code>grp_id</code>, - <em>int32 </em><code>index</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the type (dataset, dimension, datatype or - group) of an item in a group. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>grp_id</code> - <dd>ID of the group object to query - <dt><em>uint32</em> <code>index</code> - <dd>Item index in the group to query the type of - </dl> -<dt><strong>Returns:</strong> - <dd>The type of the object for an item on success, or Unegative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Group-GetContentInfoMult">H5Gget_content_info_mult</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Gget_content_info</code>(<em>hid_t </em><code>grp_id</code>, - <em>int32 </em><code>start_index</code>, - <em>int32 </em><code>num_items</code>, - <em>int32 </em><code>itemtype_list[]</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the type (dataset, dimension, datatype or - group) of a list of items in a group. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>grp_id</code> - <dd>ID of the group object to query - <dt><em>uint32</em> <code>start_index</code> - <dd>The starting index to query the types of items - <dt><em>uint32</em> <code>num_items</code> - <dd>The number of items to query the types of - <dt><em>uint32</em> <code>itemtype_list[]</code> - <dd>A list to store the types of the items in - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Group-GetOIDByName">H5Gget_oid_by_name</a> -<dt><strong>Signature:</strong> - <dd><em>hoid_t </em><code>H5Gget_oid_by_name</code>(<em>hid_t </em><code>grp_id</code>, - <em>char *</em><code>name</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the OID of an item in the group which matches - the name supplied. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>grp_id</code> - <dd>ID of the group object to query - <dt><em>char *</em> <code>name</code> - <dd>The name of the item to find - </dl> -<dt><strong>Returns:</strong> - <dd>A valid OID on success, or negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Group-GetOIDByIndex">H5Gget_oid_by_index</a> -<dt><strong>Signature:</strong> - <dd><em>hoid_t </em><code>H5Gget_oid_by_index</code>(<em>hid_t </em><code>grp_id</code>, - <em>uint32</em><code>index</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the OID of the n'th item in a group. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>grp_id</code> - <dd>ID of the group object to query - <dt><em>uint32</em> <code>index</code> - <dd>The index of the item in the group - </dl> -<dt><strong>Returns:</strong> - <dd>A valid OID on success, or negative on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Group-GetNameByOID">H5Gget_name_by_oid</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Gget_name_by_oid</code>(<em>hid_t </em><code>grp_id</code>, - <em>hoid_t</em><code>oid</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the name of the item in a group whose OID - matches the one supplied. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>grp_id</code> - <dd>ID of the group object to query - <dt><em>hoid_t</em> <code>oid</code> - <dd>The OID of the item in the group - </dl> -<dt><strong>Returns:</strong> - <dd>An atom for the string on success, NULL on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Group-GetNameByIndex">H5Gget_name_by_index</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Gget_name_by_index</code>(<em>hid_t </em><code>grp_id</code>, - <em>uint32</em><code>index</code> - ) -<dt><strong>Description:</strong> - <dd>This function retrieves the name of the n'th item in a group -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>grp_id</code> - <dd>ID of the group object to query - <dt><em>uint32</em> <code>index</code> - <dd>The index of the item in the group - </dl> -<dt><strong>Returns:</strong> - <dd>An atom for the string on success, NULL on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Group-InsertItem">H5Ginsert_item</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Ginsert_item</code>(<em>hid_t </em><code>grp_id</code>, - <em>hoid_t</em><code>item</code> - ) -<dt><strong>Description:</strong> - <dd>This function inserts the item into a group -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>grp_id</code> - <dd>ID of the group object to change - <dt><em>hoid_t</em> <code>item</code> - <dd>The OID of the item to insert into the group - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Group-InsertItemMult">H5Ginsert_item_mult</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Ginsert_item_mult</code>(<em>hid_t </em><code>grp_id</code>, - <em>uint32</em><code>num_items</code> - <em>hoid_t</em><code>item_list[]</code> - ) -<dt><strong>Description:</strong> - <dd>This function inserts multiple items into a group -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>grp_id</code> - <dd>ID of the group object to change - <dt><em>hoid_t</em> <code>num_items</code> - <dd>The number of items to insert into the group - <dt><em>hoid_t</em> <code>item_list[]</code> - <dd>The OIDs of the items to insert - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Group-RemoveItem">H5Gremove_item</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Gremove_item</code>(<em>hid_t </em><code>grp_id</code>, - <em>hoid_t</em><code>item</code> - ) -<dt><strong>Description:</strong> - <dd>This function removes an item from a group -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>grp_id</code> - <dd>ID of the group object to change - <dt><em>hoid_t</em> <code>item_list[]</code> - <dd>The OID of the items to remove - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Group-RemoveItemMult">H5Gremove_item_mult</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Gremove_item_mult</code>(<em>hid_t </em><code>grp_id</code>, - <em>uint32</em><code>num_items</code> - <em>hoid_t</em><code>item_list[]</code> - ) -<dt><strong>Description:</strong> - <dd>This function removes multiple items from a group -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>grp_id</code> - <dd>ID of the group object to change - <dt><em>hoid_t</em> <code>num_items</code> - <dd>The number of items to remove from the group - <dt><em>hoid_t</em> <code>item_list[]</code> - <dd>The OIDs of the items to remove - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> ---> - -<!-- -<hr> -<h2><a name="LinkList">Linked-List Object API Functions</a></h2> -<P>These functions manage in-memory linked lists in various useful ways. -<br> -<br> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-AddToBeginning">H5Ladd_to_beginning</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Ladd_to_beginning</code>(<em>hid_t </em><code>lst_id</code>, - <em>VOIDP</em><code>item</code> - ) -<dt><strong>Description:</strong> - <dd>This function adds an object to the beginning of a linked list -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - <dt><em>VOIDP</em> <code>item</code> - <dd>A pointer to the object to add to the list. This must not - be NULL. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-AddToEnd">H5Ladd_to_end</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Ladd_to_end</code>(<em>hid_t </em><code>lst_id</code>, - <em>VOIDP</em><code>item</code> - ) -<dt><strong>Description:</strong> - <dd>This function adds an object to the end of a linked list -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - <dt><em>VOIDP</em> <code>item</code> - <dd>A pointer to the object to add to the list. This must not - be NULL. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-RemoveFromBeginning">H5Lremove_from_beginning</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Lremove_from_beginning</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function removes an object from the front of a linked list and - returns it. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-RemoveFromEnd">H5Lremove_from_end</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Lremove_from_end</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function removes an object from the back of a linked list and - returns it. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-RemoveCurrent">H5Lremove_current</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Lremove_current</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function removes the current object from the list and returns - a pointer to it. The list's current object is moved back to the - previous item in the list, or set to NULL if the object removed is at - the beginning of the list. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-DeleteAll">H5Ldelete_all</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Ldelete_all</code>(<em>hid_t </em><code>lst_id</code>, - <em>void</em><code>(*free_func)(VOIDP)</code> - ) -<dt><strong>Description:</strong> - <dd>This function removes all the objects from a list. If - <code>free_func</code> is not NULL, each object removed from the list - is passed to <code>free_func</code> before being removed from the list. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - <dt><em>void</em> <code>(*free_func)(VOIDP)</code> - <dd>Pointer to the function to call for each item removed from - the list. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-Index">H5Lindex</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Lindex</code>(<em>hid_t </em><code>lst_id</code>, - <em>uintn</em><code>indx</code> - ) -<dt><strong>Description:</strong> - <dd>This function finds the n'th object in a list and returns it. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - <dt><em>uintn</em> <code>indx</code> - <dd>Index of the object to return. - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-PeekAtBeginning">H5Lpeek_at_beginning</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Lpeek_at_beginning</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the first object in the list. If - the list is empty, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-PeekAtEnd">H5Lpeek_at_end</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Lpeek_at_end</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the last object in the list. If - the list is empty, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-FirstInList">H5Lfirst_in_list</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Lfirst_in_list</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the first object in the list, and - marks it as the current object. If the list is empty, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-LastInList">H5Llast_in_list</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Llast_in_list</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the last object in the list, and - marks it as the current object. If the list is empty, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-CurrentInList">H5Lcurrent_in_list</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Lcurrent_in_list</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the object that is considered the - "current object" in the list. - If the current object has been removed, or current points before or - after the list or the list is empty, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-NextInList">H5Lnext_in_list</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Lnext_in_list</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the next object in the list and marks - it as the current object. - If the end of the list has been reached or the list is empty, NULL is - returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-PreviousInList">H5Lprevious_in_list</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Lprevious_in_list</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the previous object in the list and - marks it as the current object. - If the beginning of the list has been reached or the list is empty, NULL - is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-ResetToBeginning">H5Lreset_to_beginning</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Lreset_to_beginning</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function resets the "current object" to the beginning of the list. - Therefore the next object in the list is the first object. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-ResetToEnd">H5Lreset_to_end</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Lreset_to_end</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function resets the "current object" to the end of the list. - Therefore the previous object in the list is the last object. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-NumOfObjects">H5Lnum_of_objects</a> -<dt><strong>Signature:</strong> - <dd><em>uintn </em><code>H5Lnum_of_objects</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns the number of objects in the list. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>The number of nodes in the list (possibly zero) on success or UFAIL on - failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-IsEmpty">H5Lis_empty</a> -<dt><strong>Signature:</strong> - <dd><em>hbool_t </em><code>H5Lis_empty</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function determines if the list is empty. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>TRUE if the list is empty, FALSE if the list has objects, negative on - failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-IsInList">H5Lis_in_list</a> -<dt><strong>Signature:</strong> - <dd><em>hbool_t </em><code>H5Lis_in_list</code>(<em>hid_t </em><code>lst_id</code>, - <em>VOIDP</em><code>search_ptr</code> - ) -<dt><strong>Description:</strong> - <dd>This function determines if an object is in the list. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - <dt><em>VOIDP</em> <code>search_ptr</code> - <dd>Pointer to look for in list - </dl> -<dt><strong>Returns:</strong> - <dd>TRUE if the list contains the pointer, FALSE if the list has does not, - negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-CopyList">H5Lcopy_list</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Lcopy_list</code>(<em>hid_t </em><code>lst_id</code>) -<dt><strong>Description:</strong> - <dd>This function makes a copy of the list. The objects themselves are not - copied, only new references to them are made. The new list has no - current object set. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - </dl> -<dt><strong>Returns:</strong> - <dd>A valid list atom on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-PerformOnList">H5Lperform_on_list</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Lperform_on_list</code>(<em>hid_t </em><code>lst_id</code>, - <em>void</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function performs the specified function on each object in the - list. Any options arguments required can be passed through the "args" - pointer. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - <dt><em>void</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-FirstThat">H5Lfirst_that</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Lfirst_that</code>(<em>hid_t </em><code>lst_id</code>, - <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function will find and return the first object in the list which - causes the specified function to return a TRUE (non-zero) value. Any - optional arguments required can be passed through the "args" variable. - The found object is then marked as the current object. If no objects - in the list meet the criteria of the specified function or an error - occurs, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure or no matching objects -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-NextThat">H5Lnext_that</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Lnext_that</code>(<em>hid_t </em><code>lst_id</code>, - <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function will find and return the next object in the list which - causes the specified function to return a TRUE (non-zero) value. Any - optional arguments required can be passed through the "args" variable. - The found object is then marked as the current object. If no objects - in the list meet the criteria of the specified function or an error - occurs, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure or no matching objects -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-PreviousThat">H5Lprevious_that</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Lprevious_that</code>(<em>hid_t </em><code>lst_id</code>, - <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function will find and return the previous object in the list which - causes the specified function to return a TRUE (non-zero) value. Any - optional arguments required can be passed through the "args" variable. - The found object is then marked as the current object. If no objects - in the list meet the criteria of the specified function or an error - occurs, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure or no matching objects -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-LastThat">H5Llast_that</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Llast_that</code>(<em>hid_t </em><code>lst_id</code>, - <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function will find and return the last object in the list which - causes the specified function to return a TRUE (non-zero) value. Any - optional arguments required can be passed through the "args" variable. - The found object is then marked as the current object. If no objects - in the list meet the criteria of the specified function or an error - occurs, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure or no matching objects -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-AllSuchThat">H5Lall_such_that</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Lall_such_that</code>(<em>hid_t </em><code>lst_id</code>, - <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function will return a new list containing all of the objects in - the list which cause the specified function to return a TRUE (non-zero) - value. Any optional arguments required can be passed through the "args" - variable. The objects themselves are not copied, onle new references - to them are made. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>A valid list atom on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="LinkList-RemoveAllSuchThat">H5Lremove_all_such_that</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Lremove_all_such_that</code>(<em>hid_t </em><code>lst_id</code>, - <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function will remove all of the objects in the list which cause - the specified function to return a TRUE (non-zero) value. Any optional - arguments required can be passed through the "args" variable. Note that - the memory for the objects will not be reclaimed, so if the objects have - no other references, it is best to avoid this function and remove the - objects one by one, freeing them when necessary. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>lst_id</code> - <dd>ID of the list object - <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<h2><a name="TBBT">Threaded, Balanced, Binary-Tree Object API Functions</a></h2> -<P>These functions manage in-memory TBBTs in various useful ways. -<br> -<br> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-Add">H5Badd</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Badd</code>(<em>hid_t </em><code>tree_id</code>, - <em>VOIDP</em><code>item</code>, - <em>VOIDP</em><code>key</code> - ) -<dt><strong>Description:</strong> - <dd>This function inserts a new node having a key value of <code>key</code> - and a data pointer of <code>item</code> into the tree. If a node - already exists in the tree with the same key value or an error occurs, - negative is returned, otherwise, zero is returned. The comparison - function which the tree was created with is used to determine the - location of the new node in the tree. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - <dt><em>VOIDP</em> <code>item</code> - <dd>Pointer to the data of the object to insert into the tree. - <dt><em>VOIDP</em> <code>key</code> - <dd>Pointer to the key of the object to insert into the tree. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-Remove">H5Bremove</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Bremove</code>(<em>hid_t </em><code>tree_id</code>, - <em>VOIDP</em><code>key</code> - ) -<dt><strong>Description:</strong> - <dd>This function removes a node with a key value of <code>key</code>. - The data pointer corresponding to the key is returned on success, or - a NULL value is returned on failure. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - <dt><em>VOIDP</em> <code>key</code> - <dd>Pointer to the key of the object to remove from the tree. - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to the data item on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-RemoveAll">H5Bremove_all</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Bremove_all</code>(<em>hid_t </em><code>tree_id</code>, - <em>void</em><code>(*free_func)(VOIDP)</code> - ) -<dt><strong>Description:</strong> - <dd>This function removes all nodes from the tree. If - <code>free_func</code> is not NULL, each object removed from the list - is passed to <code>free_func</code> before being removed from the list. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - <dt><em>void</em> <code>(*free_func)(VOIDP)</code> - <dd>Pointer to the function to call for each item removed from - the list. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-RemoveCurrent">H5Bremove_current</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Bremove_all</code>(<em>hid_t </em><code>tree_id</code>) -<dt><strong>Description:</strong> - <dd>This function removes the "current object" from the tree and returns - a pointer to it. The tree's current object is moved back to the - previous node in the tree, or set to NULL if the object removed is at - the beginning of the tree. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to the data item removed on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-PeekAtBeginning">H5Bpeek_at_beginning</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Bpeek_at_beginning</code>(<em>hid_t </em><code>tree_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the first object in the tree. If - the tree is empty, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to the first data item on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-PeekAtEnd">H5Bpeek_at_end</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Bpeek_at_end</code>(<em>hid_t </em><code>tree_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the last object in the tree. If - the tree is empty, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to the last data item on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-Find">H5Bfind</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Bfind</code>(<em>hid_t </em><code>tree_id</code>, - <em>VOIDP</em><code>key</code> - ) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the object in the tree who's key - matches the argument passed in. If the no match is found, NULL is - returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - <dt><em>VOIDP</em> <code>key</code> - <dd>Pointer to the key of the object to search for the tree. - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to the data item on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-Index">H5Bindex</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Bindex</code>(<em>hid_t </em><code>tree_id</code>, - <em>uintn</em><code>indx</code> - ) -<dt><strong>Description:</strong> - <dd>This function finds the n'th object in a tree and returns it. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - <dt><em>uintn</em> <code>indx</code> - <dd>Index of the object to return. - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to the data item on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-FirstInTree">H5Bfirst_in_tree</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Bfirst_in_tree</code>(<em>hid_t </em><code>tree_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the first object in the tree, and - marks it as the current object. If the tree is empty, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to the data item on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-LastInTree">H5Blast_in_tree</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Blast_in_tree</code>(<em>hid_t </em><code>tree_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the last object in the tree, and - marks it as the current object. If the tree is empty, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to the data item on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-CurrentInTree">H5Bcurrent_in_tree</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Bcurrent_in_tree</code>(<em>hid_t </em><code>tree_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the object that is considered the - "current object" in the tree. - If the current object has been removed, or current points before or - after the tree or the tree is empty, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to the data item on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-NextInTree">H5Bnext_in_tree</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Bnext_in_tree</code>(<em>hid_t </em><code>tree_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the next object in the tree and marks - it as the current object. - If the end of the tree has been reached or the tree is empty, NULL is - returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to the data item on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-PreviousInTree">H5Bprevious_in_tree</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Bprevious_in_tree</code>(<em>hid_t </em><code>tree_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns a pointer to the previous object in the tree and - marks it as the current object. - If the beginning of the tree has been reached or the tree is empty, NULL - is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to the data item on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-ResetToBeginning">H5Breset_to_beginning</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Breset_to_beginning</code>(<em>hid_t </em><code>tree_id</code>) -<dt><strong>Description:</strong> - <dd>This function resets the "current object" to the beginning of the tree. - Therefore the next object in the tree is the first object. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to the data item on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-ResetToEnd">H5Breset_to_end</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Breset_to_end</code>(<em>hid_t </em><code>tree_id</code>) -<dt><strong>Description:</strong> - <dd>This function resets the "current object" to the end of the tree. - Therefore the previous object in the tree is the last object. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to the data item on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-NumOfObjects">H5Bnum_of_objects</a> -<dt><strong>Signature:</strong> - <dd><em>uintn </em><code>H5Bnum_of_objects</code>(<em>hid_t </em><code>tree_id</code>) -<dt><strong>Description:</strong> - <dd>This function returns the number of objects in the tree. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - </dl> -<dt><strong>Returns:</strong> - <dd>The number of nodes in the tree (possibly zero) on success or UFAIL on - failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-IsEmpty">H5Bis_empty</a> -<dt><strong>Signature:</strong> - <dd><em>hbool_t </em><code>H5Bis_empty</code>(<em>hid_t </em><code>tree_id</code>) -<dt><strong>Description:</strong> - <dd>This function determines if the tree is empty. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - </dl> -<dt><strong>Returns:</strong> - <dd>TRUE if the tree is empty, FALSE if the tree has objects, negative on - failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-IsInTree">H5Bis_in_tree</a> -<dt><strong>Signature:</strong> - <dd><em>hbool_t </em><code>H5Bis_in_tree</code>(<em>hid_t </em><code>tree_id</code>, - <em>VOIDP</em><code>item</code>, - <em>VOIDP</em><code>key</code> - ) -<dt><strong>Description:</strong> - <dd>This function determines if an object is in the tree. If - <code>item</code> is NULL, only the key pointer will be used to search - for nodes in the tree. If <code>key</code> is NULL, only the item pointer - will be used to search for nodes in the tree. If both <code>item</code> - and <code>key</code> are not NULL, only a node which matches both pointers - will be considered a match for the search. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - <dt><em>VOIDP</em> <code>item</code> - <dd>Pointer to the data of the object to search for in the tree. - <dt><em>VOIDP</em> <code>key</code> - <dd>Pointer to the key of the object to search for in the tree. - </dl> -<dt><strong>Returns:</strong> - <dd>TRUE if a search node is found, FALSE if no nodes match, negative on - failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-CopyTree">H5Bcopy_tree</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Bcopy_tree</code>(<em>hid_t </em><code>tree_id</code>) -<dt><strong>Description:</strong> - <dd>This function makes a copy of the tree. The objects themselves are not - copied, only new references to them are made. The new tree has no - current object set. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - </dl> -<dt><strong>Returns:</strong> - <dd>A valid tree atom on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-PerformOnTree">H5Bperform_on_tree</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Bperform_on_tree</code>(<em>hid_t </em><code>tree_id</code>, - <em>void</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function performs the specified function on each object in the - tree. Any options arguments required can be passed through the "args" - pointer. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - <dt><em>void</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-FirstThat">H5Bfirst_that</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Bfirst_that</code>(<em>hid_t </em><code>tree_id</code>, - <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function will find and return the first object in the tree which - causes the specified function to return a TRUE (non-zero) value. Any - optional arguments required can be passed through the "args" variable. - The found object is then marked as the current object. If no objects - in the tree meet the criteria of the specified function or an error - occurs, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure or no matching objects -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-NextThat">H5Bnext_that</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Bnext_that</code>(<em>hid_t </em><code>tree_id</code>, - <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function will find and return the next object in the tree which - causes the specified function to return a TRUE (non-zero) value. Any - optional arguments required can be passed through the "args" variable. - The found object is then marked as the current object. If no objects - in the tree meet the criteria of the specified function or an error - occurs, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure or no matching objects -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-PreviousThat">H5Bprevious_that</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Bprevious_that</code>(<em>hid_t </em><code>tree_id</code>, - <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function will find and return the previous object in the tree which - causes the specified function to return a TRUE (non-zero) value. Any - optional arguments required can be passed through the "args" variable. - The found object is then marked as the current object. If no objects - in the tree meet the criteria of the specified function or an error - occurs, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure or no matching objects -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-LastThat">H5Blast_that</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Blast_that</code>(<em>hid_t </em><code>tree_id</code>, - <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function will find and return the last object in the tree which - causes the specified function to return a TRUE (non-zero) value. Any - optional arguments required can be passed through the "args" variable. - The found object is then marked as the current object. If no objects - in the tree meet the criteria of the specified function or an error - occurs, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure or no matching objects -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-AllSuchThat">H5Ball_such_that</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Ball_such_that</code>(<em>hid_t </em><code>tree_id</code>, - <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function will return a new tree containing all of the objects in - the tree which cause the specified function to return a TRUE (non-zero) - value. Any optional arguments required can be passed through the "args" - variable. The objects themselves are not copied, onle new references - to them are made. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>A valid tree atom on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="TBBT-RemoveAllSuchThat">H5Bremove_all_such_that</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Bremove_all_such_that</code>(<em>hid_t </em><code>tree_id</code>, - <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function will remove all of the objects in the tree which cause - the specified function to return a TRUE (non-zero) value. Any optional - arguments required can be passed through the "args" variable. Note that - the memory for the objects will not be reclaimed, so if the objects have - no other references, it is best to avoid this function and remove the - objects one by one, freeing them when necessary. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>tree_id</code> - <dd>ID of the TBBT object - <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<h2><a name="BitVector">Bit-Vector Object API Functions</a></h2> -<P>These functions manage in-memory bit-vectors used to provide "set" -operations and maintain groups of flags about file information. -<br> -<br> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="BitVector-Set">H5Vset</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Vset</code>(<em>hid_t </em><code>bv_id</code>, - <em>uint32</em><code>bit_num</code>, - <em>hbool_t</em><code>value</code> - ) -<dt><strong>Description:</strong> - <dd>This function sets a bit in a bit-vector to a given boolean value. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>bv_id</code> - <dd>ID of the bit-vector object. - <dt><em>uint32</em> <code>bit_num</code> - <dd>Which bit in the vector to set. - <dt><em>hbool_t</em> <code>value</code> - <dd>Value to set the bit to. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="BitVector-Get">H5Vget</a> -<dt><strong>Signature:</strong> - <dd><em>hbool_t </em><code>H5Vget</code>(<em>hid_t </em><code>bv_id</code>, - <em>uint32</em><code>bit_num</code> - ) -<dt><strong>Description:</strong> - <dd>This function gets the value of a bit in a bit-vector. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>bv_id</code> - <dd>ID of the bit-vector object. - <dt><em>uint32</em> <code>bit_num</code> - <dd>Which bit in the vector to get. - </dl> -<dt><strong>Returns:</strong> - <dd>Value of the bit or negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="BitVector-Clear">H5Vclear</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Vclear</code>(<em>hid_t </em><code>bv_id</code>, - <em>hbool_t</em><code>value</code> - ) -<dt><strong>Description:</strong> - <dd>This function clears an entire bit-vector to a given boolean value. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>bv_id</code> - <dd>ID of the bit-vector object. - <dt><em>hbool_t</em> <code>value</code> - <dd>The value to clear the bit-vector to. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="BitVector-Size">H5Vsize</a> -<dt><strong>Signature:</strong> - <dd><em>uint32 </em><code>H5Vclear</code>(<em>hid_t </em><code>bv_id</code>) -<dt><strong>Description:</strong> - <dd>This function reports the number of bits used in a bit-vector. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>bv_id</code> - <dd>ID of the bit-vector object. - </dl> -<dt><strong>Returns:</strong> - <dd>The number of bits in the bit-vector (possibly zero) on success or - UFAIL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="BitVector-Find">H5Vfind</a> -<dt><strong>Signature:</strong> - <dd><em>uint32 </em><code>H5Vfind</code>(<em>hid_t </em><code>bv_id</code>, - <em>hbool_t</em><code>value</code> - ) -<dt><strong>Description:</strong> - <dd>This function finds the first bit in a bit-vector with a given value. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>bv_id</code> - <dd>ID of the bit-vector object. - <dt><em>hbool_t</em> <code>value</code> - <dd>The value to search for. - </dl> -<dt><strong>Returns:</strong> - <dd>The position of the first bit with the given value on success or UFAIL - on failure. -</dl> - -<hr> -<h2><a name="Atom">Atom Object API Functions</a></h2> -<P>These functions manage in-memory atoms, which provide a portable and -protected way of refering to memory structures. -<br> -<br> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Atom-Register">H5Aregister</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Aregister</code>(<em>hgroup_t </em><code>grp_id</code>, - <em>VOIDP</em><code>ptr</code> - ) -<dt><strong>Description:</strong> - <dd>This function registers a pointer (to a data-structure, usually) in a - group and provides an atom for it. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hgroup_t</em> <code>grp_id</code> - <dd>ID of the atom group. - <dt><em>VOIDP</em> <code>ptr</code> - <dd>The pointer (to a data-structure) to register in the group. - </dl> -<dt><strong>Returns:</strong> - <dd>A value atom on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Atom-Unregister">H5Aunregister</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Aunregister</code>(<em>hid_t </em><code>atm</code>) -<dt><strong>Description:</strong> - <dd>This function removes an atom from a group and returns a pointer to - the structure which was registered. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>atm</code> - <dd>Atom to remove. - </dl> -<dt><strong>Returns:</strong> - <dd>A valid memory pointer on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Atom-LookupObject">H5Alookup_object</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Alookup_object</code>(<em>hid_t </em><code>atm</code>) -<dt><strong>Description:</strong> - <dd>This function retrieves the memory pointer which is associated with - the atom. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>atm</code> - <dd>Atom to look up. - </dl> -<dt><strong>Returns:</strong> - <dd>A valid memory pointer on success, NULL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Atom-LookupGroup">H5Alookup_group</a> -<dt><strong>Signature:</strong> - <dd><em>hgroup_t </em><code>H5Alookup_group</code>(<em>hid_t </em><code>atm</code>) -<dt><strong>Description:</strong> - <dd>This function retrieves the group that the atom is in. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>atm</code> - <dd>Atom to look up. - </dl> -<dt><strong>Returns:</strong> - <dd>A valid atom group on success, negative on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Atom-Search">H5Asearch</a> -<dt><strong>Signature:</strong> - <dd><em>VOIDP </em><code>H5Asearch</code>(<em>hgroup_t </em><code>grp</code>, - <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, - <em>VOIDP</em><code>args</code>, - ) -<dt><strong>Description:</strong> - <dd>This function will find and return the first object in the atomic - group which causes the specified function to return a TRUE (non-zero) - value. Any optional arguments required can be passed through the - "args" variable. Currently, there is no way to resume a search. - If no objects in the group meet the criteria of the specified function - or an error occurs, NULL is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hgroup_t</em> <code>grp</code> - <dd>ID of the atom group to search. - <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> - <dd>Pointer to the function to operate on the objects - <dt><em>VOIDP</em> <code>args</code> - <dd>Pointer any additional arguments needed by the function as - it is operating on the objects. - </dl> -<dt><strong>Returns:</strong> - <dd>A pointer to an object on success/NULL on failure or no matching objects -</dl> - -<hr> -<h2><a name="String">String Object API Functions</a></h2> -<P>These functions manage in-memory character strings in an object-oriented -way. -<br> -<br> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="String-Copy">H5Scopy</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Scopy</code>(<em>hid_t </em><code>strg_id1</code>, - <em>hid_t</em><code>strg_id2</code> - ) -<dt><strong>Description:</strong> - <dd>This function copies a string from one string object to another. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>strg_id1</code> - <dd>ID of the destination string. - <dt><em>hid_t</em> <code>strg_id2</code> - <dd>ID of the source string. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="String-Convert">H5Sconvert</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Sconvert</code>(<em>hid_t </em><code>strg_id/code>, - <em>char *</em><code>buf</code> - ) -<dt><strong>Description:</strong> - <dd>This function copies a string object into a zero-terminated character - buffer. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>strg_id</code> - <dd>ID of the destination string. - <dt><em>char *</em> <code>buf</code> - <dd>Character buffer to store string in. - </dl> -<dt><strong>Returns:</strong> - <dd>zero/negative -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="String-Len">H5Slen</a> -<dt><strong>Signature:</strong> - <dd><em>uintn </em><code>H5Slen</code>(<em>hid_t </em><code>strg_id</code>) -<dt><strong>Description:</strong> - <dd>This function return the length of a string in characters. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>strg_id</code> - <dd>ID of the string. - </dl> -<dt><strong>Returns:</strong> - <dd>The length of the string (possibly 0) on success, or UFAIL on failure. -</dl> - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="String-Compare">H5Scompare</a> -<dt><strong>Signature:</strong> - <dd><em>intn </em><code>H5Scompare</code>(<em>hid_t </em><code>strg_id1</code>, - <em>hid_t</em><code>strg_id2</code> - ) -<dt><strong>Description:</strong> - <dd>This function compares the two strings, returning an integer less than, - equal to, or greater than zero, indicating that the string referenced - by <code>strg_id1</code> is less than, equal to, or greater than the - string referenced by <code>strg_id2</code>. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>strg_id1</code> - <dd>ID of the first string. - <dt><em>hid_t</em> <code>strg_id1</code> - <dd>ID of the second string. - </dl> -<dt><strong>Returns:</strong> - <dd>An integer less than, equal to, or greater than zero based on the values - of the strings. -</dl> ---> - -<hr> -<h2><a name="Glossary">Glossary of data-types used</a></h2> -<P>Since many of the typedefs in the HDF5 API are not well-defined yet, -the types below may change radically en route to a final API... -<br> -<br> - -<a name="Glossary-Basic">Basic Types:</a> -<ul> - <li>char - 8-bit character (only for ASCII information) - <li>int8 - 8-bit signed integer - <li>uint8 - 8-bit unsigned integer - <li>int16 - 16-bit signed integer - <li>uint16 - 16-bit unsigned integer - <li>int32 - 32-bit signed integer - <li>uint32 - 32-bit unsigned integer - <li>intn - "native" signed integer - <li>uintn - "native" unsigned integer - <li>int64 - 64-bit signed integer (new) - <li>uint64 - 64-bit unsigned integer (new) - <li>float32 - 32-bit IEEE float - <li>float64 - 64-bit IEEE float -</ul> - -<a name="Glossary-Complex">Complex Types:</a> -<ul> - <li>hid_t - 32-bit unsigned integer used as ID for memory objects - <li>hoid_t - 32-bit unsigned integer (currently) used as ID for disk-based - objects - <li>hbool_t - boolean to indicate true/false/error codes from functions - <li>herr_t - 32-bit integer to indicate succeed/fail codes from functions -</ul> - -<a name="Glossary-DiskIO">Disk I/O Types:</a> -<ul> - <li>hoff_t - (64-bit?) offset on disk in bytes - <li>hlen_t - (64-bit?) length on disk in bytes -</ul> - |