mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-02-23 16:20:57 +08:00
427ff7da28
Bug Fix/Code Cleanup/Doc Cleanup/Optimization/Branch Sync :-)
Description:
Generally speaking, this is the "signed->unsigned" change to selections.
However, in the process of merging code back, things got stickier and stickier
until I ended up doing a big "sync the two branches up" operation. So... I
brought back all the "infrastructure" fixes from the development branch to the
release branch (which I think were actually making some improvement in
performance) as well as fixed several bugs which had been fixed in one branch,
but not the other.
I've also tagged the repository before making this checkin with the label
"before_signed_unsigned_changes".
Platforms tested:
FreeBSD 4.10 (sleipnir) w/parallel & fphdf5
FreeBSD 4.10 (sleipnir) w/threadsafe
FreeBSD 4.10 (sleipnir) w/backward compatibility
Solaris 2.7 (arabica) w/"purify options"
Solaris 2.8 (sol) w/FORTRAN & C++
AIX 5.x (copper) w/parallel & FORTRAN
IRIX64 6.5 (modi4) w/FORTRAN
Linux 2.4 (heping) w/FORTRAN & C++
Misc. update:
1178 lines
44 KiB
HTML
1178 lines
44 KiB
HTML
<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="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<70>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<70>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<70>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<70>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="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>
|