diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 2005-07-19 17:28:56 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 2005-07-19 17:28:56 (GMT) |
| commit | 794ba0a251af47b8e3c60afa2fe92d267e2a6b55 (patch) | |
| tree | f24cea3b81ff02fa3f31c0a1c4e80fa10f4393c0 /doc/html/RM_H5I.html | |
| parent | d2e92fd23610c3ccdddbbc55484e54a5a21a9252 (diff) | |
| download | hdf5-794ba0a251af47b8e3c60afa2fe92d267e2a6b55.zip hdf5-794ba0a251af47b8e3c60afa2fe92d267e2a6b55.tar.gz hdf5-794ba0a251af47b8e3c60afa2fe92d267e2a6b55.tar.bz2 | |
[svn-r11084]
Description:
All HDF5 user documentation has been moved to a separate hdf5doc/
repository, managed under Subversion.
With this 'cvs commit', all files are stripped from hdf5/doc/.
THIS CHANGE IS APPLIED ONLY TO THE HDF5 DEVELOPMENT BRANCH,
post Release 1.6.x; it is not applied to the release branches.
Diffstat (limited to 'doc/html/RM_H5I.html')
| -rw-r--r-- | doc/html/RM_H5I.html | 1187 |
1 files changed, 0 insertions, 1187 deletions
diff --git a/doc/html/RM_H5I.html b/doc/html/RM_H5I.html deleted file mode 100644 index 4f5e731..0000000 --- a/doc/html/RM_H5I.html +++ /dev/null @@ -1,1187 +0,0 @@ -<html> -<head><title> -HDF5/H5I API Specification -</title> - -<!-- #BeginLibraryItem "/ed_libs/styles_RM.lbi" --> - -<!-- - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * Copyright by the Board of Trustees of the University of Illinois. * - * All rights reserved. * - * * - * This file is part of HDF5. The full HDF5 copyright notice, including * - * terms governing use, modification, and redistribution, is contained in * - * the files COPYING and Copyright.html. COPYING can be found at the root * - * of the source code distribution tree; Copyright.html can be found at the * - * root level of an installed copy of the electronic HDF5 document set and * - * is linked from the top-level documents page. It can also be found at * - * http://hdf.ncsa.uiuc.edu/HDF5/doc/Copyright.html. If you do not have * - * access to either file, you may request a copy from hdfhelp@ncsa.uiuc.edu. * - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - --> - -<link href="ed_styles/RMelect.css" rel="stylesheet" type="text/css"> -<!-- #EndLibraryItem --></head> - -<body bgcolor="#FFFFFF"> -<!-- HEADER RIGHT " " --> - - -<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr> -<center> -<table border=0 width=98%> -<tr><td valign=top align=left> -<a href="index.html">HDF5 documents and links</a> <br> -<a href="H5.intro.html">Introduction to HDF5</a> <br> -<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</a> <br> -<!-- -<a href="Glossary.html">Glossary</a><br> ---> -</td> -<td valign=top align=right> -And in this document, the -<a href="RM_H5Front.html">HDF5 Reference Manual</a> -<br> -<a href="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5im.html">H5IM</a> -<a href="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5lt.html">H5LT</a> -<a href="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5pt.html">H5PT</a> -<a href="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5tb.html">H5TB</a> -<br> -<a href="RM_H5.html">H5</a> -<a href="RM_H5A.html">H5A</a> -<a href="RM_H5D.html">H5D</a> -<a href="RM_H5E.html">H5E</a> -<a href="RM_H5F.html">H5F</a> -<a href="RM_H5G.html">H5G</a> -<a href="RM_H5I.html">H5I</a> -<a href="RM_H5P.html">H5P</a> -<br> -<a href="RM_H5R.html">H5R</a> -<a href="RM_H5S.html">H5S</a> -<a href="RM_H5T.html">H5T</a> -<a href="RM_H5Z.html">H5Z</a> -<a href="Tools.html">Tools</a> -<a href="PredefDTypes.html">Datatypes</a> -</td></tr> -</table> -</center> -<hr><!-- #EndLibraryItem --><center> -<h1>H5I: Identifier Interface</h1> -</center> - -<h2>Identifier API Functions</h2> - -These functions provides tools for working with object identifiers and -object names. - - -<p> -<strong>The C Interface:</strong> - -<table border=0> -<tr><td valign=top> -<ul> - <li><a href="#Identify-GetFileId">H5Iget_file_id</a> - <li><a href="#Identify-GetName">H5Iget_name</a> - <li><a href="#Identify-GetType">H5Iget_type</a> - <li><a href="#Identify-ObjectVerify">H5Iobject_verify</a> - <li><a href="#Identify-RemoveVerify">H5Iremove_verify</a> - <li><a href="#Identify-Search">H5Isearch</a> -</ul> -</td><td> </td><td valign=top> -<ul> - <li><a href="#Identify-GetRef">H5Iget_ref</a> - <li><a href="#Identify-IncRef">H5Iinc_ref</a> - <li><a href="#Identify-DecRef">H5Idec_ref</a> - <li><a href="#Identify-Register">H5Iregister</a> - <li><a href="#Identify-RegisterType">H5Iregister_type</a> - <li><a href="#Identify-DestroyType">H5Idestroy_type</a> -</ul> -</td><td> </td><td valign=top> -<ul> - <li><a href="#Identify-GetTypeRef">H5Iget_type_ref</a> - <li><a href="#Identify-DecTypeRef">H5Idec_type_ref</a> - <li><a href="#Identify-IncTypeRef">H5Iinc_type_ref</a> - <li><a href="#Identify-ClearType">H5Iclear_type</a> - <li><a href="#Identify-NMembers">H5Inmembers</a> -</ul> -</td></tr> -</table> -<br> - - -<i>Alphabetical Listing</i> - -<table border="0"> - <tr> - <td valign="top"> - <ul> - <li><a href="#Identify-ClearType">H5Iclear_type</a> - <li><a href="#Identify-DecRef">H5Idec_ref</a> - <li><a href="#Identify-DecTypeRef">H5Idec_type_ref</a> - <li><a href="#Identify-DestroyType">H5Idestroy_type</a> - <li><a href="#Identify-GetFileId">H5Iget_file_id</a> - <li><a href="#Identify-GetName">H5Iget_name</a> - </ul> - </td> - - <td> </td> - - <td valign="top"> - <ul> - <li><a href="#Identify-GetRef">H5Iget_ref</a> - <li><a href="#Identify-GetType">H5Iget_type</a> - <li><a href="#Identify-GetTypeRef">H5Iget_type_ref</a> - <li><a href="#Identify-IncRef">H5Iinc_ref</a> - <li><a href="#Identify-IncTypeRef">H5Iinc_type_ref</a> - <li><a href="#Identify-NMembers">H5Inmembers</a> - </ul> - </td> - - <td> </td> - - <td valign="top"> - <ul> - <li><a href="#Identify-ObjectVerify">H5Iobject_verify</a> - <li><a href="#Identify-Register">H5Iregister</a> - <li><a href="#Identify-RegisterType">H5Iregister_type</a> - <li><a href="#Identify-RemoveVerify">H5Iremove_verify</a> - <li><a href="#Identify-Search">H5Isearch</a> - </ul> - </td> - </tr> -</table> - -<br> -<strong>The FORTRAN90 Interfaces:</strong> -<br> -In general, each FORTRAN90 subroutine performs exactly the same task -as the corresponding C function. -<br> - -<table border=0> -<tr><td valign=top> -<ul> - <li><a href="#Identify-GetName">h5iget_name_f</a> - <li><a href="#Identify-GetType">h5iget_type_f</a> -</ul> -</td><td> </td><td valign=top> -<ul> - <li><a href="#Identify-GetRef">h5iget_ref_f</a> - <li><a href="#Identify-IncRef">h5iinc_ref_f</a> -</ul> -</td><td> </td><td valign=top> -<ul> - <li><a href="#Identify-DecRef">h5idec_ref_f</a> -</ul> -</td></tr> -</table> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT " " --> -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Iclear_type" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-ClearType">H5Iclear_type</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Iclear_type</code>(<em>H5I_type_t</em> <code>type</code>, - <em>hbool_t</em> <code>force</code>) -<dt><strong>Purpose:</strong> - <dd>Deletes all IDs of the given type -<dt><strong>Description:</strong> - <dd><code>H5Iclear_type</code> deletes all IDs of the type identified by the argument type. - <p> - The type’s free function is first called on all of these IDs to free their memory, - then they are removed from the type. - - <p> - If the <code>force</code> flag is set to false, only those IDs whose reference - counts are equal to 1 will be deleted, and all other IDs will be entirely unchanged. - If the <code>force</code> flag is true, all IDs of this type will be deleted. -<dt><strong>Parameters:</strong> - <ul> - <table> - <tr> - <td valign="top"><em>H5I_type_t</em> <code>type </code></td> - <td valign="top">IN: Identifier of ID type which is to be cleared of IDs</td> - </tr> - <tr> - <td valign="top"><em>hbool_t</em> <code>force</code></td> - <td valign="top">IN: Whether or not to force deletion of all IDs</td> - </tr> - </table> - </ul> -<dt><strong>Returns:</strong> - <dd>Returns non-negative on success, negative on failure. -<dt><strong>Fortran90 Interface:</strong> - <dd>This function is not supported in FORTRAN 90. - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Idec_ref" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-DecRef">H5Idec_ref</a> -<dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Idec_ref</code>(<em>hid_t</em> <code>obj_id</code>) -<dt><strong>Purpose:</strong> - <dd>Decrements the reference count for an object. -<dt><strong>Description:</strong> - <dd><code>H5Idec_ref</code> decrements the reference count of the object - identified by <code>obj_id</code>. - - <p> - The reference count for an object ID is attached to the information - about an object in memory and has no relation to the number of links to - an object on disk. - - <p> - The reference count for a newly created object will be 1. - Reference counts for objects may be explicitly modified with this - function or with <code>H5Iinc_ref</code>. - When an object ID's reference count reaches zero, the object will be - closed. - Calling an object ID's 'close' function decrements the reference count - for the ID which normally closes the object, but - if the reference count for the ID has been incremented with - <code>H5Iinc_ref</code>, the object will only be closed when the - reference count - reaches zero with further calls to this function or the - object ID's 'close' function. - - <p> - If the object ID was created by a collective parallel call (such as - <code>H5Dcreate</code>, <code>H5Gopen</code>, etc.), the reference - count should be modified by all the processes which have copies of - the ID. Generally this means that group, dataset, attribute, file - and named datatype IDs should be modified by all the processes and - that all other types of IDs are safe to modify by individual processes. - - <p> - This function is of particular value when an application is maintaining - multiple copies of an object ID. The object ID can be incremented when - a copy is made. Each copy of the ID can then be safely closed or - decremented and the HDF5 object will be closed when the reference count - for that that object drops to zero. -<dt><strong>Parameters:</strong> - <ul><table> - <tr> - <td valign="top"><em>hid_t</em> <code>obj_id </code></td> - <td valign="top">IN: Object identifier whose reference count will be modified.</td></tr> - </table></ul> -<dt><strong>Returns:</strong> - <dd>Returns a non-negative reference count of the object ID after - decrementing it if successful; otherwise a negative value is returned. -<dt><strong>Fortran90 Interface:</strong> h5idec_ref_f - <dd> - <pre> -SUBROUTINE h5idec_ref_f(obj_id, ref_count, hdferr) - IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id !Object identifier - INTEGER, INTENT(OUT) :: ref_count !Reference count of object ID - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success, and -1 on failure -END SUBROUTINE h5idec_ref_f - </pre> - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Idec_type_ref" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-DecTypeRef">H5Idec_type_ref</a> -<dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Idec_type_ref</code>(<em>H5I_type_t</em> <code>type</code>) -<dt><strong>Purpose:</strong> - <dd>Decrements the reference count on an ID type. -<dt><strong>Description:</strong> - <dd><code>H5Idec_type_ref</code> decrements the reference count on an ID type. - The reference count is used by the library to indicate when an ID type can - be destroyed. If the reference count reaches zero, this function will destroy it. - - <p>The <code>type</code> parameter is the identifier for the ID type whose - reference count is to be decremented. This identifier must have been - created by a call to <code>H5Iregister_type</code>. -<dt><strong>Parameters:</strong> - <ul> - <table> - <tr> - <td valign="top"><em>H5I_type_t</em> <code>type </code></td> - <td valign="top">IN: The identifier of the type whose reference count is to be decremented</td> - </tr> - </table> - </ul> -<dt><strong>Returns:</strong> - <dd>Returns the current reference count on success, negative on failure. -<dt><strong>Fortran90 Interface:</strong> - <dd>This function is not supported in FORTRAN 90. - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Idestroy_type" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-DestroyType">H5Idestroy_type</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Idestroy_type</code>(<em>H5I_type_t</em> <code>type</code>) -<dt><strong>Purpose:</strong> - <dd>Removes the type <code>type</code> and all IDs within that type. -<dt><strong>Description:</strong> - <dd><code>H5Idestroy_type</code> deletes an entire ID type. All IDs of this - type are destroyed and no new IDs of this type can be registered. - - <p> - The type’s free function is called on all of the IDs which are deleted by - this function, freeing their memory. In addition, all memory used by this - type’s hash table is freed. - - <p> - Since the <em>H5I_type_t</em> values of destroyed ID types are reused - when new types are registered, it is a good idea to set the variable - holding the value of the destroyed type to <code>H5I_UNINIT</code>. -<dt><strong>Parameters:</strong> - <ul> - <table> - <tr> - <td valign="top"><em>H5I_type_t</em> <code>type </code></td> - <td valign="top">IN: Identifier of ID type which is to be destroyed</td> - </tr> - </table> - </ul> -<dt><strong>Returns:</strong> - <dd>Returns non-negative on success, negative on failure. -<dt><strong>Fortran90 Interface:</strong> - <dd>This function is not supported in FORTRAN 90. - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Iget_file_id" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-GetFileId">H5Iget_file_id</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t</em> <code>H5Iget_file_id</code>(<em>hid_t</em> <code>obj_id</code>) -<dt><strong>Purpose:</strong> - <dd>Retrieves an identifier for the file containing the specified object. -<dt><strong>Description:</strong> - <dd><code>H5Iget_file_id</code> returns the identifier of the file - associated with the object referenced by <code>obj_id</code>. - <p> - <code>obj_id</code> can be a file, group, dataset, named datatype, - or attribute identifier. - <p> - Note that the HDF5 Library permits an application to close a file - while objects within the file remain open. - If the file containing the object <code>obj_id</code> - is still open, <code>H5Iget_file_id</code> will retrieve the - existing file identifier. - If there is no existing file identifier for the file, - i.e., the file has been closed, - <code>H5Iget_file_id</code> will reopen the file and - return a new file identifier. - In either case, the file identifier must eventually be released - using <code>H5Fclose</code>. -<dt><strong>Parameters:</strong> - <ul> - <table> - <tr> - <td valign="top"><em>hid_t</em> <code>obj_id </code></td> - <td valign="top">IN: Identifier of the object whose associated - file identifier will be returned.</td> - </tr> - </table> - </ul> -<dt><strong>Returns:</strong> - <dd>Returns a file identifier on success, negative on failure. -<dt><strong>Fortran90 Interface:</strong> - <dd> - <pre> -SUBROUTINE h5iget_file_id_f(obj_id, file_id, hdferr) - - IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier - INTEGER(HID_T), INTENT(OUT) :: file_id ! File identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code - -END SUBROUTINE h5iget_file_id_f - </pre> - -<!--<dt><strong>Non-C API(s):</strong> - <dd> - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Iget_name" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-GetName">H5Iget_name</a> -<dt><strong>Signature:</strong> - <dd><em>ssize_t</em> <code>H5Iget_name</code>(<em>hid_t</em> <code>obj_id</code>, - <em>char *</em><code>name</code>, - <em>size_t</em> <code>size</code> - ) -<dt><strong>Purpose:</strong> </dt> - <dd>Retrieves a name of an object based on the object identifier. -<dt><strong>Description:</strong> - <dd><code>H5Iget_name</code> retrieves a name for the object identified - by <code>obj_id</code>. - <p> - Up to <code>size</code> characters of the name are returned in - <code>name</code>; additional characters, if any, are not returned - to the user application. - <p> - If the length of the name, which determines the required - value of <code>size</code>, is unknown, a preliminary - <code>H5Iget_name</code> call can be made. - The return value of this call will be the size of the - object name. - That value can then be assigned to <code>size</code> - for a second <code>H5Iget_name</code> call, - which will retrieve the actual name. - <p> - If there is no name associated with the object identifier - or if the name is <code>NULL</code>, <code>H5Iget_name</code> - returns <code>0</code> (zero). - <p> - Note that an object in an HDF5 file may have multiple names, - varying according to the path through the HDF5 group - hierarchy used to reach that object. -<dt><strong>Parameters:</strong> - <ul><table> - <tr> - <td valign="top"><em>hid_t</em> <code>obj_id </code></td> - <td valign="top">IN: Identifier of the object. - This identifier can refer to a group, dataset, or named datatype.</td></tr> - <tr> - <td valign="top"><em>char *</em><code>name</code></td> - <td valign="top">OUT: A name associated with the identifier.</td></tr> - <tr> - <td valign="top"><em>size_t size</em></td> - <td valign="top">IN: The size of the <code>name</code> buffer.</td></tr> - </table></ul> -<dt><strong>Returns:</strong> - <dd>Returns the length of the name if successful, - returning <code>0</code> (zero) if no name is associated with the identifier. - Otherwise returns a negative value. -<dt><strong>Fortran90 Interface:</strong> h5iget_name_f - <dd> - <pre> -SUBROUTINE h5iget_name_f(obj_id, buf, buf_size, hdferr) - IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier - CHARACTER(LEN=*), INTENT(OUT) :: buf ! Buffer to hold object name - INTEGER(SIZE_T), INTENT(IN) :: buf_size ! Buffer size - INTEGER(SIZE_T), INTENT(OUT) :: name_size ! Name size - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success, and -1 on failure -END SUBROUTINE h5iget_name_f - </pre> - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Iget_ref" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-GetRef">H5Iget_ref</a> -<dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Iget_ref</code>(<em>hid_t</em> <code>obj_id</code>) -<dt><strong>Purpose:</strong> - <dd>Retrieves the reference count for an object. -<dt><strong>Description:</strong> - <dd><code>H5Iget_ref</code> retrieves the reference count of the object - identified by <code>obj_id</code>. - - <p> - The reference count for an object ID is attached to the information - about an object in memory and has no relation to the number of links to - an object on disk. - - <p> - This function can also be used to check if an object ID is still valid. - A non-negative return value from this function indicates that the ID - is still valid. -<dt><strong>Parameters:</strong> - <ul><table> - <tr> - <td valign="top"><em>hid_t</em> <code>obj_id </code></td> - <td valign="top">IN: Object identifier whose reference count will be retrieved.</td></tr> - </table></ul> -<dt><strong>Returns:</strong> - <dd>Returns a non-negative current reference count of the object ID - if successful; otherwise a negative value is returned. -<dt><strong>Fortran90 Interface:</strong> h5iget_ref_f - <dd> - <pre> -SUBROUTINE h5iget_ref_f(obj_id, ref_count, hdferr) - IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id !Object identifier - INTEGER, INTENT(OUT) :: ref_count !Reference count of object ID - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success, and -1 on failure -END SUBROUTINE h5iget_ref_f - </pre> - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Iget_type" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-GetType">H5Iget_type</a> -<dt><strong>Signature:</strong> - <dd><em>H5I_type_t</em> <code>H5Iget_type</code>(<em>hid_t</em> <code>obj_id</code>) -<dt><strong>Purpose:</strong> - <dd>Retrieves the type of an object. -<dt><strong>Description:</strong> - <dd><code>H5Iget_type</code> retrieves the type of the object - identified by <code>obj_id</code>. - <p> - Valid types returned by the function are - <table> - <tr><td width=200><code> H5I_FILE</code> - </td><td>File</td></tr> - <tr><td><code> H5I_GROUP</code> - </td><td>Group</td></tr> - <tr><td><code> H5I_DATATYPE</code> - </td><td>Datatype</td></tr> - <tr><td><code> H5I_DATASPACE</code> - </td><td>Dataspace</td></tr> - <tr><td><code> H5I_DATASET</code> - </td><td>Dataset</td></tr> - <tr><td><code> H5I_ATTR</code> - </td><td>Attribute</td></tr> - </table> - If no valid type can be determined or the identifier - submitted is invalid, the function returns - <table> - <tr><td width=200><code> H5I_BADID</code> - </td><td>Invalid identifier</td></tr> - </table> - <p> - This function is of particular value in determining the - type of object closing function (<code>H5Dclose</code>, - <code>H5Gclose</code>, etc.) to call after a call to - <code>H5Rdereference</code>. -<dt><strong>Parameters:</strong> - <ul><table> - <tr> - <td valign="top"><em>hid_t</em> <code>obj_id </code></td> - <td valign="top">IN: Object identifier whose type is to be determined.</td></tr> - </table></ul> -<dt><strong>Returns:</strong> - <dd>Returns the object type if successful; - otherwise <code>H5I_BADID</code>. -<dt><strong>Fortran90 Interface:</strong> h5iget_type_f - <dd> - <pre> -SUBROUTINE h5iget_type_f(obj_id, type, hdferr) - IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id !Object identifier - INTEGER, INTENT(OUT) :: type !type of an object. - !possible values are: - !H5I_FILE_F - !H5I_GROUP_F - !H5I_DATATYPE_F - !H5I_DATASPACE_F - !H5I_DATASET_F - !H5I_ATTR_F - !H5I_BADID_F - INTEGER, INTENT(OUT) :: hdferr ! E rror code - ! 0 on success, and -1 on failure -END SUBROUTINE h5iget_type_f - </pre> - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Iget_type_ref" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-GetTypeRef">H5Iget_type_ref</a> -<dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Iget_type_ref</code>(<em>H5I_type_t</em> <code>type</code>) -<dt><strong>Purpose:</strong> - <dd>Retrieves the reference count on an ID type. -<dt><strong>Description:</strong> - <dd><code>H5Iget_type_ref</code> retrieves the reference count on an ID type. - The reference count is used by the library to indicate when an - ID type can be destroyed. - - <p> - The <code>type</code> parameter is the identifier for the ID type whose - reference count is to be retrieved. This identifier must have been created - by a call to <code>H5Iregister_type</code>. -<dt><strong>Parameters:</strong> - <ul> - <table> - <tr> - <td valign="top"><em>H5I_type_t</em> <code>type </code></td> - <td valign="top">IN: The identifier of the type whose reference count is to be retrieved</td> - </tr> - </table> - </ul> -<dt><strong>Returns:</strong> - <dd>Returns the current reference count on success, negative on failure. -<dt><strong>Fortran90 Interface:</strong> - <dd>This function is not supported in FORTRAN 90. - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Iinc_ref" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-IncRef">H5Iinc_ref</a> -<dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Iinc_ref</code>(<em>hid_t</em> <code>obj_id</code>) -<dt><strong>Purpose:</strong> - <dd>Increments the reference count for an object. -<dt><strong>Description:</strong> - <dd><code>H5Iinc_ref</code> increments the reference count of the object - identified by <code>obj_id</code>. - - <p> - The reference count for an object ID is attached to the information - about an object in memory and has no relation to the number of links to - an object on disk. - - <p> - The reference count for a newly created object will be 1. - Reference counts for objects may be explicitly modified with this - function or with <code>H5Idec_ref</code>. - When an object ID's reference count reaches zero, the object will be - closed. - Calling an object ID's 'close' function decrements the reference count - for the ID which normally closes the object, but - if the reference count for the ID has been incremented with this - function, the object will only be closed when the reference count - reaches zero with further calls to <code>H5Idec_ref</code> or the - object ID's 'close' function. - - <p> - If the object ID was created by a collective parallel call (such as - <code>H5Dcreate</code>, <code>H5Gopen</code>, etc.), the reference - count should be modified by all the processes which have copies of - the ID. Generally this means that group, dataset, attribute, file - and named datatype IDs should be modified by all the processes and - that all other types of IDs are safe to modify by individual processes. - - <p> - This function is of particular value when an application is maintaining - multiple copies of an object ID. The object ID can be incremented when - a copy is made. Each copy of the ID can then be safely closed or - decremented and the HDF5 object will be closed when the reference count - for that that object drops to zero. -<dt><strong>Parameters:</strong> - <ul><table> - <tr> - <td valign="top"><em>hid_t</em> <code>obj_id </code></td> - <td valign="top">IN: Object identifier whose reference count will be modified.</td></tr> - </table></ul> -<dt><strong>Returns:</strong> - <dd>Returns a non-negative reference count of the object ID after - incrementing it if successful; otherwise a negative value is returned. -<dt><strong>Fortran90 Interface:</strong> h5iinc_ref_f - <dd> - <pre> -SUBROUTINE h5iinc_ref_f(obj_id, ref_count, hdferr) - IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id !Object identifier - INTEGER, INTENT(OUT) :: ref_count !Reference count of object ID - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success, and -1 on failure -END SUBROUTINE h5iinc_ref_f - </pre> - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Iinc_type_ref" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-IncTypeRef">H5Iinc_type_ref</a> -<dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Iinc_type_ref</code>(<em>H5I_type_t</em> <code>type</code>) -<dt><strong>Purpose:</strong> - <dd>Increments the reference count on an ID type. -<dt><strong>Description:</strong> - <dd><code>H5Iinc_type_ref</code> increments the reference count on an ID type. - The reference count is used by the library to indicate when an ID type can be destroyed. - - <p> - The <code>type</code> parameter is the identifier for the ID type whose - reference count is to be incremented. This identifier must have been created - by a call to <code>H5Iregister_type</code>. -<dt><strong>Parameters:</strong> - <ul> - <table> - <tr> - <td valign="top"><em>H5I_type_t</em> <code>type </code></td> - <td valign="top">IN: The identifier of the type whose reference count is to be incremented</td> - </tr> - </table> - </ul> -<dt><strong>Returns:</strong> - <dd>Returns the current reference count on success, negative on failure. -<dt><strong>Fortran90 Interface:</strong> - <dd>This function is not supported in FORTRAN 90. - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Inmembers" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-NMembers">H5Inmembers</a> -<dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Inmembers</code>(<em>H5I_type_t</em> <code>type</code>) -<dt><strong>Purpose:</strong> - <dd>Returns the number of IDs in a given type. -<dt><strong>Description:</strong> - <dd><code>H5Inmembers</code> returns the number of IDs of a given ID type. - If no IDs of this type have been registered, H5Inmembers returns 0. - If the type does not exist or has been destroyed, <code>H5Inmembers</code> - also returns 0. -<dt><strong>Parameters:</strong> - <ul> - <table> - <tr> - <td valign="top"><em>H5I_type_t</em> <code>type </code></td> - <td valign="top">IN: Identifier of ID type whose member count will be retrieved</td> - </tr> - </table> - </ul> -<dt><strong>Returns:</strong> - <dd>Returns number of members on success, zero if type is not a valid ID type. -<dt><strong>Fortran90 Interface:</strong> - <dd>This function is not supported in FORTRAN 90. - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Iobject_verify" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-ObjectVerify">H5Iobject_verify</a> -<dt><strong>Signature:</strong> - <dd><em>void *</em> <code>H5Iobject_verify</code>(<em>hid_t</em> <code>id</code>, - <em>H5I_type_t</em> <code>id_type</code>) -<dt><strong>Purpose:</strong> - <dd>Returns the object referenced by id. -<dt><strong>Description:</strong> - <dd><code>H5Iobject_verify</code> returns a pointer to the memory referenced by - <code>id</code> after verifying that <code>id</code> is of type <code>id_type</code>. - This function is analogous to dereferencing a pointer in C with type checking. - - <p> - <code>H5Iregister</code>(<em>H5I_type_t</em> <code>type</code>, - <em>void *</em><code>object</code>) takes an <em>H5I_type_t</em> and a - void pointer to an object, returning an <em>hid_t</em> of that type. - This <em>hid_t</em> can then be passed to <code>H5Iobject_verify</code> - along with its type to retrieve the object. - - <p> - <code>H5Iobject_verify</code> does not change the ID it is called on in any - way (as opposed to <code>H5Iremove_verify</code>, which removes the ID from its - type’s hash table). -<dt><strong>Parameters:</strong> - <ul> - <table> - <tr> - <td valign="top"><em>hid_t</em> <code>id</code></td> - <td valign="top">IN: ID to be dereferenced</td> - </tr> - <tr> - <td valign="top"><em>H5I_type_t</em> <code>type </code></td> - <td valign="top">IN: ID type to which id should belong</td> - </tr> - </table> - </ul> -<dt><strong>Returns:</strong> - <dd>Pointer to the object referenced by id on success, <code>NULL</code> on failure. -<dt><strong>Fortran90 Interface:</strong> - <dd>This function is not supported in FORTRAN 90. - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Iregister" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-Register">H5Iregister</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t</em> <code>H5Iregister</code>(<em>H5I_type_t</em> <code>type</code>, - <em>void *</em><code>object</code>) -<dt><strong>Purpose:</strong> - <dd>Creates and returns a new ID. -<dt><strong>Description:</strong> - <dd><code>H5Iregister</code> allocates space for a new ID and returns an identifier for it. - - <p> - The <code>type</code> parameter is the identifier for the ID type to which - this new ID will belong. This identifier must have been created by a call - to <code>H5Iregister_type</code>. - - <p> - The <code>object</code> parameter is a pointer to the memory which the new - ID will be a reference to. This pointer will be stored by the library and - returned to you via a call to <code>H5Iobject_verify</code>. -<dt><strong>Parameters:</strong> - <ul> - <table> - <tr> - <td valign="top"><em>H5I_type_t</em> <code>type </code></td> - <td valign="top">IN: The identifier of the type to which the new ID will belong</td> - </tr> - <tr> - <td valign="top"><em>void *</em><code>object</code></td> - <td valign="top">IN: Pointer to memory for the library to store</td> - </tr> - </table> - </ul> -<dt><strong>Returns:</strong> - <dd>Returns the new ID on success, negative on failure. -<dt><strong>Fortran90 Interface:</strong> - <dd>This function is not supported in FORTRAN 90. - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Iregister_type" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-RegisterType">H5Iregister_type</a> -<dt><strong>Signature:</strong> - <dd><em>H5I_type_t</em> <code>H5Iregister_type</code>(<em>size_t</em> - <code>hash_size</code>, <em>unsigned</em> <code>reserved</code>, - <em>H5I_free_t</em> <code>free_func</code>) -<dt><strong>Purpose:</strong> - <dd>Creates and returns a new ID type. -<dt><strong>Description:</strong> - <dd><code>H5Iregister_type</code> allocates space for a new ID type and - returns an identifier for it. - - <p> - The <code>hash_size</code> parameter indicates the minimum size of the hash - table used to store IDs in the new type. - - <p> - The <code>reserved</code> parameter indicates the number of IDs in this new - type to be reserved. Reserved IDs are valid IDs which are not associated with - any storage within the library. - - <p> - The <code>free_func</code> parameter is a function pointer to a function - which returns an <em>herr_t</em> and accepts a <em>void *</em>. The purpose - of this function is to deallocate memory for a single ID. It will be called - by <code>H5Iclear_type</code> and <code>H5Idestroy_type</code> on each ID. - This function is NOT called by <code>H5Iremove_verify</code>. - The <em>void *</em> will be the same pointer which was passed in to - the <code>H5Iregister</code> function. The <code>free_func</code> - function should return 0 on success and -1 on failure. -<dt><strong>Parameters:</strong> - <ul> - <table> - <tr> - <td valign="top"><em>size_t</em> <code>hash_size</code></td> - <td valign="top">IN: Size of the hash table (in entries) used to store IDs for the new type</td> - </tr> - <tr> - <td valign="top"><em>unsigned</em> <code>reserved</code></td> - <td valign="top">IN: Number of reserved IDs for the new type</td> - </tr> - <tr> - <td valign="top"><em>H5I_free_t</em> <code>free_func </code></td> - <td valign="top">IN: Function used to deallocate space for a single ID</td> - </tr> - </table> - </ul> -<dt><strong>Returns:</strong> - <dd>Returns the type identifier on success, negative on failure. -<dt><strong>Fortran90 Interface:</strong> - <dd>This function is not supported in FORTRAN 90. - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Iremove_verify" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-RemoveVerify">H5Iremove_verify</a> -<dt><strong>Signature:</strong> - <dd><em>void *</em><code>H5Iremove_verify</code>(<em>hid_t</em> <code>id</code>, - <em>H5I_type_t</em> <code>id_type</code>) -<dt><strong>Purpose:</strong> - <dd>Removes an ID from internal storage. -<dt><strong>Description:</strong> - <dd><code>H5Iremove_verify</code> first ensures that <code>id</code> belongs to - <code>id_type</code>. If so, it removes <code>id</code> from internal storage - and returns the pointer to the memory it referred to. This pointer is the - same pointer that was placed in storage by <code>H5Iregister</code>. - If <code>id</code> does not belong to <code>id_type</code>, - then <code>NULL</code> is returned. - - <p> - The <code>id</code> parameter is the ID which is to be removed from - internal storage. Note: this function does NOT deallocate the memory that - <code>id</code> refers to. The pointer returned by <code>H5Iregister</code> - must be deallocated by the user to avoid memory leaks. - - <p> - The <code>type</code> parameter is the identifier for the ID type - which <code>id</code> is supposed to belong to. This identifier must - have been created by a call to <code>H5Iregister_type</code>. -<dt><strong>Parameters:</strong> - <ul> - <table> - <tr> - <td valign="top"><em>hid_t</em> <code>id</code></td> - <td valign="top">IN: The ID to be removed from internal storage</td> - </tr> - <tr> - <td valign="top"><em>H5I_type_t</em> <code>type </code></td> - <td valign="top">IN: The identifier of the type whose reference count is to be retrieved</td> - </tr> - </table> - </ul> -<dt><strong>Returns:</strong> - <dd>Returns a pointer to the memory referred to by <code>id</code> - on success, <code>NULL</code> on failure. -<dt><strong>Fortran90 Interface:</strong> - <dd>This function is not supported in FORTRAN 90. - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Isearch" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-Search">H5Isearch</a> -<dt><strong>Signature:</strong> - <dd><em>void *</em><code>H5Isearch</code>(<em>H5I_type_t</em> <code>type</code>, - <em>H5I_search_func_t</em> <code>func</code>, <em>void *</em><code>key</code>) -<dt><strong>Purpose:</strong> - <dd>Finds the memory referred to by an ID within the given ID type such that - some criterion is satisfied. -<dt><strong>Description:</strong> - <dd><code>H5Isearch</code> searches through a give ID type to find an object - that satisfies the criteria defined by <code>func</code>. If such an object - is found, the pointer to the memory containing this object is returned. - Otherwise, <code>NULL</code> is returned. To do this, <code>func</code> is - called on every member of <code>type</code>. The first member to satisfy - <code>func</code> is returned. - - <p> - The <code>type</code> parameter is the identifier for the ID type which is - to be searched. This identifier must have been created by a call to - <code>H5Iregister_type</code>. - - <p> - The parameter <code>func</code> is a function pointer to a function - which takes three parameters. The first parameter is a <em>void *</em>. - It will be a pointer the object to be tested. This is the same object - that was placed in storage using <code>H5Iregister</code>. The second - parameter is a <em>hid_t</em>. It is the ID of the object to be tested. - The last parameter is a <em>void *</em>. This is the <code>key</code> parameter - and can be used however the user finds helpful. Or it can simply be ignored - if it is not needed. <code>func</code> returns 0 if the object it is testing - does not pass its criteria. A non-zero value should be returned if the object - does pass its criteria. - - <p> - The <code>key</code> parameter will be passed to the search function as a - parameter. It can be used to further define the search at run-time. -<dt><strong>Parameters:</strong> - <ul> - <table> - <tr> - <td valign="top"><em>H5I_type_t</em> <code>type</code></td> - <td valign="top">IN: The identifier of the type to be searched</td> - </tr> - <tr> - <td valign="top"><em>H5I_search_func_t</em> <code>func </code></td> - <td valign="top">IN: The function defining the search criteria</td> - </tr> - <tr> - <td valign="top"><em>void *</em><code>key</code></td> - <td valign="top">IN: A key for the search function</td> - </tr> - </table> - </ul> -<dt><strong>Returns:</strong> - <dd>Returns a pointer to the object which satisfies the search function - on success, <code>NULL</code> on failure. -<dt><strong>Fortran90 Interface:</strong> - <dd>This function is not supported in FORTRAN 90. - - <!--<dt><strong>Non-C API(s):</strong> - <dd> - - - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - -<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr> -<center> -<table border=0 width=98%> -<tr><td valign=top align=left> -<a href="index.html">HDF5 documents and links</a> <br> -<a href="H5.intro.html">Introduction to HDF5</a> <br> -<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</a> <br> -<!-- -<a href="Glossary.html">Glossary</a><br> ---> -</td> -<td valign=top align=right> -And in this document, the -<a href="RM_H5Front.html">HDF5 Reference Manual</a> -<br> -<a href="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5im.html">H5IM</a> -<a href="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5lt.html">H5LT</a> -<a href="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5pt.html">H5PT</a> -<a href="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5tb.html">H5TB</a> -<br> -<a href="RM_H5.html">H5</a> -<a href="RM_H5A.html">H5A</a> -<a href="RM_H5D.html">H5D</a> -<a href="RM_H5E.html">H5E</a> -<a href="RM_H5F.html">H5F</a> -<a href="RM_H5G.html">H5G</a> -<a href="RM_H5I.html">H5I</a> -<a href="RM_H5P.html">H5P</a> -<br> -<a href="RM_H5R.html">H5R</a> -<a href="RM_H5S.html">H5S</a> -<a href="RM_H5T.html">H5T</a> -<a href="RM_H5Z.html">H5Z</a> -<a href="Tools.html">Tools</a> -<a href="PredefDTypes.html">Datatypes</a> -</td></tr> -</table> -</center> -<hr><!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address> -<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> -<br> -Describes HDF5 Release 1.7, the unreleased development branch; working toward HDF5 Release 1.8.0 -</address><!-- #EndLibraryItem --><SCRIPT LANGUAGE="JAVASCRIPT"> -<!-- -document.writeln("Last modified: 8 September 2004"); ---> -</SCRIPT> - -<!-- HEADER RIGHT " " --> - -</body> -</html> |