mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-01-30 15:32:37 +08:00
1179 lines
44 KiB
HTML
1179 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-GetType">h5iget_type_f</a>
|
||
<li><a href="#Identify-GetName">h5iget_name_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>
|