mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-01-12 15:04:59 +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:
1512 lines
60 KiB
HTML
1512 lines
60 KiB
HTML
<html>
|
|
<head><title>
|
|
HDF5/H5G 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>H5G: Group Interface</h1>
|
|
</center>
|
|
|
|
<h2>Group Object API Functions</h2>
|
|
|
|
The Group interface functions create and manipulate groups
|
|
of objects in an HDF5 file.
|
|
<p>
|
|
<strong>The C Interfaces:</strong>
|
|
|
|
<table border=0>
|
|
<tr><td valign=top>
|
|
<ul>
|
|
<li><a href="#Group-Create">H5Gcreate</a>
|
|
<li><a href="#Group-Open">H5Gopen</a>
|
|
<li><a href="#Group-Close">H5Gclose</a>
|
|
<li><a href="#Group-SetComment">H5Gset_comment</a>
|
|
<li><a href="#Group-GetComment">H5Gget_comment</a>
|
|
</ul>
|
|
</td><td> </td>
|
|
<td valign=top>
|
|
<ul>
|
|
<li><a href="#Group-Link">H5Glink</a>
|
|
<li><a href="#Group-Link2">H5Glink2</a>
|
|
<li><a href="#Group-Unlink">H5Gunlink</a>
|
|
<li><a href="#Group-Move">H5Gmove</a>
|
|
<li><a href="#Group-Move2">H5Gmove2</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Group-Iterate">H5Giterate</a>
|
|
<li><a href="#Group-GetObjinfo">H5Gget_objinfo</a>
|
|
<li><a href="#Group-GetNumObjs">H5Gget_num_objs</a>
|
|
<li><a href="#Group-GetObjNameByIdx">H5Gget_objname_by_idx</a>
|
|
<li><a href="#Group-GetObjTypeByIdx">H5Gget_objtype_by_idx</a>
|
|
<li><a href="#Group-GetLinkval">H5Gget_linkval</a>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
|
|
<i>Alphabetical Listing</i>
|
|
|
|
<table border="0">
|
|
<tr>
|
|
<td valign="top">
|
|
<ul>
|
|
<li><a href="#Group-Close">H5Gclose</a>
|
|
<li><a href="#Group-Create">H5Gcreate</a>
|
|
<li><a href="#Group-GetComment">H5Gget_comment</a>
|
|
<li><a href="#Group-GetLinkval">H5Gget_linkval</a>
|
|
<li><a href="#Group-GetNumObjs">H5Gget_num_objs</a>
|
|
<li><a href="#Group-GetObjinfo">H5Gget_objinfo</a>
|
|
</ul>
|
|
</td>
|
|
|
|
<td> </td>
|
|
|
|
<td valign="top">
|
|
<ul>
|
|
<li><a href="#Group-GetObjNameByIdx">H5Gget_objname_by_idx</a>
|
|
<li><a href="#Group-GetObjTypeByIdx">H5Gget_objtype_by_idx</a>
|
|
<li><a href="#Group-Iterate">H5Giterate</a>
|
|
<li><a href="#Group-Link">H5Glink</a>
|
|
<li><a href="#Group-Link2">H5Glink2</a>
|
|
<li><a href="#Group-Move">H5Gmove</a>
|
|
</ul>
|
|
</td>
|
|
|
|
<td> </td>
|
|
|
|
<td valign="top">
|
|
<ul>
|
|
<li><a href="#Group-Move2">H5Gmove2</a>
|
|
<li><a href="#Group-Open">H5Gopen</a>
|
|
<li><a href="#Group-SetComment">H5Gset_comment</a>
|
|
<li><a href="#Group-Unlink">H5Gunlink</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="#Group-Create">h5gcreate_f</a>
|
|
<li><a href="#Group-Open">h5gopen_f</a>
|
|
<li><a href="#Group-Close">h5gclose_f</a>
|
|
<li><a href="#Group-SetComment">h5gset_comment_f</a>
|
|
<li><a href="#Group-GetComment">h5gget_comment_f</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Group-Link">h5glink_f</a>
|
|
<li><a href="#Group-Link2">h5glink2_f</a>
|
|
<li><a href="#Group-Unlink">h5gunlink_f</a>
|
|
<li><a href="#Group-Move">h5gmove_f</a>
|
|
<li><a href="#Group-Move2">h5gmove2_f</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Group-Iterate">h5gget_obj_info_idx_f</a>
|
|
<li><a href="#Group-Iterate">h5gn_members_f</a>
|
|
<!--<li><a href="#Group-GetObjinfo">h5gget_objinfo_f</a> -->
|
|
<!--<li><a href="#Group-GetNumObjs">h5gget_num_objs_f</a> -->
|
|
<!--<li><a href="#Group-GetObjNameByIdx">h5gget_objname_by_idx_f</a> -->
|
|
<!--<li><a href="#Group-GetObjTypeByIdx">h5gget_objtype_by_idx_f</a> -->
|
|
<li><a href="#Group-GetLinkval">h5gget_linkval_f</a>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
|
|
<p>
|
|
A group associates names with objects and provides a mechanism
|
|
for mapping a name to an object. Since all objects appear in at
|
|
least one group (with the possible exception of the root object)
|
|
and since objects can have names in more than one group, the set
|
|
of all objects in an HDF5 file is a directed graph. The internal
|
|
nodes (nodes with out-degree greater than zero) must be groups
|
|
while the leaf nodes (nodes with out-degree zero) are either empty
|
|
groups or objects of some other type. Exactly one object in every
|
|
non-empty file is the root object. The root object always has a
|
|
positive in-degree because it is pointed to by the file super block.
|
|
|
|
<p>
|
|
An object name consists of one or more components separated from
|
|
one another by slashes. An absolute name begins with a slash and the
|
|
object is located by looking for the first component in the root
|
|
object, then looking for the second component in the first object, etc.,
|
|
until the entire name is traversed. A relative name does not begin
|
|
with a slash and the traversal begins at the location specified by the
|
|
create or access function.
|
|
|
|
<p>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT " " -->
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Gclose" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Close">H5Gclose</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Gclose</code>(<em>hid_t </em><code>group_id</code>)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Closes the specified group.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gclose</code> releases resources used by a group which was
|
|
opened by <code>H5Gcreate</code> or <code>H5Gopen</code>.
|
|
After closing a group, the <code>group_id</code> cannot be used again.
|
|
<p>
|
|
Failure to release a group with this call will result in resource leaks.
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>group_id </code></td>
|
|
<td valign="top">IN: Group identifier to release.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Fortran90 Interface:</strong> h5gclose_f
|
|
<dd>
|
|
<pre>
|
|
SUBROUTINE h5gclose_f( gr_id, hdferr)
|
|
IMPLICIT NONE
|
|
INTEGER(HID_T), INTENT(IN) :: gr_id ! Group identifier
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
! 0 on success and -1 on failure
|
|
END SUBROUTINE h5gclose_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 "H5Gcreate" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Create">H5Gcreate</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Gcreate</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>,
|
|
<em>size_t</em> <code>size_hint</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Creates a new empty group and gives it a name.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gcreate</code> creates a new group with the specified
|
|
name at the specified location, <code>loc_id</code>.
|
|
The location is identified by a file or group identifier.
|
|
The name, <code>name</code>, must not already be taken by some
|
|
other object and all parent groups must already exist.
|
|
<p>
|
|
<code>size_hint</code> is a hint for the number of bytes to
|
|
reserve to store the names which will be eventually added to
|
|
the new group. Passing a value of zero for <code>size_hint</code>
|
|
is usually adequate since the library is able to dynamically
|
|
resize the name heap, but a correct hint may result in better
|
|
performance.
|
|
If a non-positive value is supplied for <code>size_hint</code>,
|
|
then a default size is chosen.
|
|
<p>
|
|
The return value is a group identifier for the open group.
|
|
This group identifier should be closed by calling
|
|
<code>H5Gclose</code> when it is no longer needed.
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>loc_id</code></td>
|
|
<td valign="top">IN: File or group identifier.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char *</em><code>name</code></td>
|
|
<td valign="top">IN: Absolute or relative name of the new group.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>size_t</em> <code>size_hint </code></td>
|
|
<td valign="top">IN: Optional parameter indicating the number of bytes
|
|
to reserve for the names that will appear in the group.
|
|
A conservative estimate could result in multiple
|
|
system-level I/O requests to read the group name heap;
|
|
a liberal estimate could result in a single large
|
|
I/O request even when the group has just a few names.
|
|
HDF5 stores each name with a null terminator.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a valid group identifier for the open group if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Fortran90 Interface:</strong> h5gcreate_f
|
|
<dd>
|
|
<pre>
|
|
SUBROUTINE h5gcreate_f(loc_id, name, gr_id, hdferr, size_hint)
|
|
|
|
IMPLICIT NONE
|
|
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
|
|
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group to be created
|
|
INTEGER(HID_T), INTENT(OUT) :: gr_id ! Group identifier
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
! 0 on success and -1 on failure
|
|
INTEGER(SIZE_T), OPTIONAL, INTENT(IN) :: size_hint
|
|
! Number of bytes to store the names
|
|
! of objects in the group.
|
|
! Default value is
|
|
! OBJECT_NAMELEN_DEFAULT_F
|
|
END SUBROUTINE h5gcreate_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 "H5Gget_comment" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-GetComment">H5Gget_comment</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Gget_comment</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>,
|
|
<em>size_t</em> <code>bufsize</code>,
|
|
<em>char *</em><code>comment</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Retrieves comment for specified object.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gget_comment</code> retrieves the comment for the the
|
|
object specified by <code>loc_id</code> and <code>name</code>.
|
|
The comment is returned in the buffer <code>comment</code>.
|
|
<p>
|
|
At most <code>bufsize</code> characters, including a null
|
|
terminator, are returned in <code>comment</code>.
|
|
The returned value is not null terminated
|
|
if the comment is longer than the supplied buffer.
|
|
<p>
|
|
If an object does not have a comment, the empty string
|
|
is returned.
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>loc_id</code></td>
|
|
<td valign="top">IN: Identifier of the file, group, dataset, or
|
|
named datatype.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char *</em><code>name </code></td>
|
|
<td valign="top">IN: Name of the object in <code>loc_id</code> whose
|
|
comment is to be retrieved.
|
|
<br>
|
|
<code>name</code> can be '.' (dot) if <code>loc_id</code>
|
|
fully specifies the object for which the associated comment
|
|
is to be retrieved.
|
|
<br>
|
|
<code>name</code> is ignored if <code>loc_id</code>
|
|
is a dataset or named datatype.
|
|
</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>size_t</em> <code>bufsize</code></td>
|
|
<td valign="top">IN: Anticipated required size of the
|
|
<code>comment</code> buffer.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>char *</em><code>comment</code></td>
|
|
<td valign="top">OUT: The comment.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns the number of characters in the comment,
|
|
counting the null terminator, if successful; the value
|
|
returned may be larger than <code>bufsize</code>.
|
|
Otherwise returns a negative value.
|
|
<dt><strong>Fortran90 Interface:</strong> h5gget_comment_f
|
|
<dd>
|
|
<pre>
|
|
SUBROUTINE h5gget_comment_f(loc_id, name, size, buffer, hdferr)
|
|
IMPLICIT NONE
|
|
INTEGER(HID_T), INTENT(IN) :: loc_id ! File, group, dataset, or
|
|
! named datatype identifier
|
|
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the object link
|
|
CHARACTER(LEN=size), INTENT(OUT) :: buffer ! Buffer to hold the comment
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
! 0 on success and -1 on failure
|
|
END SUBROUTINE h5gget_comment_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 "H5Gget_linkval" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-GetLinkval">H5Gget_linkval</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Gget_linkval</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>,
|
|
<em>size_t</em> <code>size</code>,
|
|
<em>char *</em><code>value</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns the name of the object that the symbolic link points to.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gget_linkval</code> returns <code>size</code>
|
|
characters of the name of the object that the symbolic link <code>name</code> points to.
|
|
<p>
|
|
The parameter <code>loc_id</code> is a file or group identifier.
|
|
<p>
|
|
The parameter <code>name</code> must be a symbolic link pointing to
|
|
the desired object and must be defined relative to <code>loc_id</code>.
|
|
<p>
|
|
If <code>size</code> is smaller than the size of the returned object name, then
|
|
the name stored in the buffer <code>value</code> will not be null terminated.
|
|
<p>
|
|
This function fails if <code>name</code> is not a symbolic link.
|
|
The presence of a symbolic link can be tested by passing zero for
|
|
<code>size</code> and NULL for <code>value</code>.
|
|
<p>
|
|
This function should be used only after <code>H5Gget_objinfo</code> has been called
|
|
to verify that <code>name</code> is a symbolic link.
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>loc_id</code></td>
|
|
<td valign="top">IN: Identifier of the file or group.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char *</em><code>name </code></td>
|
|
<td valign="top">IN: Symbolic link to the object whose name is to be returned.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>size_t</em> <code>size</code></td>
|
|
<td valign="top">IN: Maximum number of characters of <code>value</code>
|
|
to be returned.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>char *</em><code>value</code></td>
|
|
<td valign="top">OUT: A buffer to hold the name of the object being sought.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value, with the link value in <code>value</code>,
|
|
if successful.
|
|
Otherwise returns a negative value.
|
|
<dt><strong>Fortran90 Interface:</strong> h5gget_linkval_f
|
|
<dd>
|
|
<pre>
|
|
SUBROUTINE h5gget_linkval_f(loc_id, name, size, buffer, hdferr)
|
|
IMPLICIT NONE
|
|
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
|
|
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the symbolic link
|
|
CHARACTER(LEN=size), INTENT(OUT) :: buffer ! Buffer to hold a
|
|
! name of the object
|
|
! symbolic link points to
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
! 0 on success and -1 on failure
|
|
END SUBROUTINE h5gget_linkval_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 "H5Gget_num_objs" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-GetNumObjs">H5Gget_num_objs</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Gget_num_objs</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>hsize_t* </em> <code>num_obj</code>)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns number of objects in the group specified by its identifier
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gget_num_objs</code> returns number of objects in a group.
|
|
Group is specified by its identifier <code>loc_id</code>.
|
|
If a file identifier is passed in, then the number of objects in the
|
|
root group is returned.
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>loc_id</code></td>
|
|
<td valign="top">IN: Identifier of the group or the file</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>hsize_t *</em><code>num_obj </code></td>
|
|
<td valign="top">OUT: Number of objects in the group.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns positive value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Fortran90 Interface:</strong>
|
|
<dd>None.
|
|
|
|
<!--
|
|
<pre>
|
|
SUBROUTINE
|
|
</pre>
|
|
-->
|
|
|
|
<!--<dt><strong>Non-C API(s):</strong>
|
|
<dd>
|
|
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Gget_objinfo" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-GetObjinfo">H5Gget_objinfo</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Gget_objinfo</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>,
|
|
<em>hbool_t</em> <code>follow_link</code>,
|
|
<em>H5G_stat_t *</em><code>statbuf</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns information about an object.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gget_objinfo</code> returns information about the
|
|
specified object through the <code>statbuf</code> argument.
|
|
<code>loc_id</code> (a file or group identifier) and
|
|
<code>name</code> together determine the object.
|
|
If the object is a symbolic link and <code>follow_link</code> is
|
|
zero (<code>0</code>), then the information returned is that for the link itself;
|
|
otherwise the link is followed and information is returned about
|
|
the object to which the link points.
|
|
If <code>follow_link</code> is non-zero but the final symbolic link
|
|
is dangling (does not point to anything), then an error is returned.
|
|
The <code>statbuf</code> fields are undefined for an error.
|
|
The existence of an object can be tested by calling this function
|
|
with a null <code>statbuf</code>.
|
|
<p>
|
|
<code>H5Gget_objinfo</code> fills in the following data structure
|
|
(defined in H5Gpublic.h):
|
|
<pre>
|
|
typedef struct H5G_stat_t {
|
|
unsigned long fileno;
|
|
haddr_t objno;
|
|
unsigned nlink;
|
|
H5G_obj_t type;
|
|
time_t mtime;
|
|
size_t linklen;
|
|
H5O_stat_t ohdr;
|
|
} H5G_stat_t
|
|
</pre>
|
|
|
|
where H5O_stat_t (defined in H5Opublic.h) is:
|
|
|
|
<pre>
|
|
typedef struct H5O_stat_t {
|
|
hsize_t size;
|
|
hsize_t free;
|
|
unsigned nmesgs;
|
|
unsigned nchunks;
|
|
} H5O_stat_t
|
|
</pre>
|
|
The <code>fileno</code> and <code>objno</code> fields contain
|
|
four values which uniquely identify an object among those
|
|
HDF5 files which are open: if all four values are the same
|
|
between two objects, then the two objects are the same
|
|
(provided both files are still open).
|
|
<ul>
|
|
<li>Note that if a file is closed and re-opened, the
|
|
value in <code>fileno</code> will change.
|
|
<li>If a VFL driver either does not or cannot detect that
|
|
two <code>H5Fopen</code> calls referencing the same file
|
|
actually open the same file, each will get a different
|
|
<code>fileno</code>.
|
|
</ul>
|
|
<p>
|
|
The <code>nlink</code> field is the number of hard links to
|
|
the object or zero when information is being returned about a
|
|
symbolic link (symbolic links do not have hard links but
|
|
all other objects always have at least one).
|
|
<p>
|
|
The <code>type</code> field contains the type of the object,
|
|
one of
|
|
<code>H5G_GROUP</code>,
|
|
<code>H5G_DATASET</code>,
|
|
<code>H5G_LINK</code>, or
|
|
<code>H5G_TYPE</code>.
|
|
<p>
|
|
The <code>mtime</code> field contains the modification time.
|
|
<p>
|
|
If information is being returned about a symbolic link then
|
|
<code>linklen</code> will be the length of the link value
|
|
(the name of the pointed-to object with the null terminator);
|
|
otherwise <code>linklen</code> will be zero.
|
|
<p>
|
|
The fields in the <code>H5O_stat_t</code> struct contain information
|
|
about the object header for the object queried:
|
|
<ul><dl>
|
|
<dt><code>size</code>
|
|
<dd>The total size of all the object header information in
|
|
the file (for all chunks).
|
|
<dt><code>free</code>
|
|
<dd>The size of unused space in the object header.
|
|
<dt><code>nmesgs</code>
|
|
<dd>The number of object header messages.
|
|
<dt><code>nchunks</code>
|
|
<dd>The number of chunks the object header is broken up into.
|
|
</dl> </ul>
|
|
|
|
<p>
|
|
Other fields may be added to this structure in the future.
|
|
<dt><strong>Note:</strong>
|
|
<dd>Some systems will be able to record the time accurately but
|
|
unable to retrieve the correct time; such systems (e.g., Irix64)
|
|
will report an <code>mtime</code> value of 0 (zero).
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>loc_id</code></td>
|
|
<td valign="top">IN: File or group identifier.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char</em> <code>*name</code></td>
|
|
<td valign="top">IN: Name of the object for which status is being sought.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>hbool_t</em> <code>follow_link</code></td>
|
|
<td valign="top">IN: Link flag.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>H5G_stat_t</em> <code>*statbuf </code></td>
|
|
<td valign="top">OUT: Buffer in which to return information about the object.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd> Returns a non-negative value if successful, with the fields of
|
|
<code>statbuf</code> (if non-null) initialized.
|
|
Otherwise returns a negative value.
|
|
<dt><strong>Fortran90 Interface:</strong>
|
|
<dd>None.
|
|
|
|
<!--
|
|
<pre>
|
|
SUBROUTINE
|
|
</pre>
|
|
-->
|
|
|
|
<!--<dt><strong>Non-C API(s):</strong>
|
|
<dd>
|
|
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Gget_objname_by_idx" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-GetObjNameByIdx">H5Gget_objname_by_idx</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>ssize_t</em> <code>H5Gget_objname_by_idx</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>hsize_t</em> <code>idx</code>,
|
|
<em>char *</em><code>name</code>,
|
|
<em>size_t</em> <code>size</code> )
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns a name of an object specified by an index.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gget_objname_by_idx</code> returns a name of the object
|
|
specified by the index <code>idx</code> in the group <code>loc_id</code>.
|
|
<p>
|
|
The group is specified by a group identifier <code>loc_id</code>.
|
|
If preferred, a file identifier may be passed in <code>loc_id</code>;
|
|
that file's root group will be assumed.
|
|
<p>
|
|
<code>idx</code> is the transient index used to iterate through
|
|
the objects in the group.
|
|
The value of <code>idx</code> is any nonnegative number less than
|
|
the total number of objects in the group, which is returned by the
|
|
function <code>H5Gget_num_objs</code>.
|
|
Note that this is a transient index; an object may have a
|
|
different index each time a group is opened.
|
|
<p>
|
|
The object name is returned in the user-specified buffer <code>name</code>.
|
|
<p>
|
|
If the size of the provided buffer <code>name</code> is
|
|
less or equal the actual object name length,
|
|
the object name is truncated to <code>max_size - 1</code> characters.
|
|
<p>
|
|
Note that if the size of the object's name is unkown, a
|
|
preliminary call to <code>H5Gget_objname_by_idx</code> with <code>name</code>
|
|
set to NULL will return the length of the object's name.
|
|
A second call to <code>H5Gget_objname_by_idx</code>
|
|
can then be used to retrieve the actual name.
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>loc_id </code></td>
|
|
<td valign="top">IN: Group or file identifier.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>hsize_t</em> <code>idx</code></td>
|
|
<td valign="top">IN: Transient index identifying object.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>char *</em><code>name</code></td>
|
|
<td valign="top">IN/OUT: Pointer to user-provided buffer the object name.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>size_t</em> <code>size</code></td>
|
|
<td valign="top">IN: Name length.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns the size of the object name if successful,
|
|
or <code>0</code> if no name is associated with the group identifier.
|
|
Otherwise returns a negative value.
|
|
<dt><strong>Fortran90 Interface:</strong>
|
|
<dd>None.
|
|
|
|
<!--
|
|
<pre>
|
|
SUBROUTINE
|
|
</pre>
|
|
-->
|
|
|
|
<!--<dt><strong>Non-C API(s):</strong>
|
|
<dd>
|
|
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Gget_objtype_by_idx" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-GetObjTypeByIdx">H5Gget_objtype_by_idx</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>int</em> <code>H5Gget_objtype_by_idx</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>hsize_t</em> <code>idx</code> )
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns the type of an object specified by an index.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gget_objtype_by_idx</code> returns the type of the object
|
|
specified by the index <code>idx</code> in the group <code>loc_id</code>.
|
|
<p>
|
|
The group is specified by a group identifier <code>loc_id</code>.
|
|
If preferred, a file identifier may be passed in <code>loc_id</code>;
|
|
that file's root group will be assumed.
|
|
<p>
|
|
<code>idx</code> is the transient index used to iterate through
|
|
the objects in the group.
|
|
This parameter is described in more detail in the discussion of
|
|
<a href="#Group-GetObjNameByIdx"><code>H5Gget_objname_by_idx</code></a>.
|
|
<p>
|
|
The object type is returned as the function return value:
|
|
<table>
|
|
<tr valign=top align=left><td>
|
|
|
|
</td><td>
|
|
<code>H5G_LINK</code>
|
|
<!--</td><td>
|
|
<code>0x0001</code>-->
|
|
</td><td>
|
|
<code>0</code>
|
|
</td><td>
|
|
Object is a symbolic link.
|
|
</td></tr>
|
|
<tr valign=top align=left><td>
|
|
|
|
</td><td>
|
|
<code>H5G_GROUP</code>
|
|
<!--</td><td>
|
|
<code>0x0001</code>-->
|
|
</td><td>
|
|
<code>1</code>
|
|
</td><td>
|
|
Object is a group.
|
|
</td></tr>
|
|
<tr valign=top align=left><td>
|
|
|
|
</td><td>
|
|
<code>H5G_DATASET</code>
|
|
<!--</td><td>
|
|
<code>0x0001</code>-->
|
|
</td><td>
|
|
<code>2</code>
|
|
</td><td>
|
|
Object is a dataset.
|
|
</td></tr>
|
|
<tr valign=top align=left><td>
|
|
|
|
</td><td>
|
|
<code>H5G_TYPE</code>
|
|
<!--</td><td>
|
|
<code>0x0001</code>-->
|
|
</td><td>
|
|
<code>3</code>
|
|
</td><td>
|
|
Object is a named datatype.
|
|
</td></tr>
|
|
</table>
|
|
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>loc_id </code></td>
|
|
<td valign="top">IN: Group or file identifier.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>hsize_t</em> <code>idx</code></td>
|
|
<td valign="top">IN: Transient index identifying object.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns the type of the object if successful.
|
|
Otherwise returns a negative value.
|
|
<dt><strong>Fortran90 Interface:</strong>
|
|
<dd>None.
|
|
|
|
<!--
|
|
<pre>
|
|
SUBROUTINE
|
|
</pre>
|
|
-->
|
|
|
|
<!--<dt><strong>Non-C API(s):</strong>
|
|
<dd>
|
|
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Giterate" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Iterate">H5Giterate</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>int</em> <code>H5Giterate</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char</em> <code>*name</code>,
|
|
<em>int</em> <code>*idx</code>,
|
|
<em>H5G_iterate_t</em> <code>operator</code>,
|
|
<em>void</em> <code>*operator_data</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Iterates an operation over the entries of a group.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Giterate</code> iterates over the members of
|
|
<code>name</code> in the file or group specified with
|
|
<code>loc_id</code>.
|
|
For each object in the group, the <code>operator_data</code>
|
|
and some additional information, specified below, are
|
|
passed to the <code>operator</code> function.
|
|
The iteration begins with the <code>idx</code> object in the
|
|
group and the next element to be processed by the operator is
|
|
returned in <code>idx</code>. If <code>idx</code>
|
|
is NULL, then the iterator starts at the first group member;
|
|
since no stopping point is returned in this case, the iterator
|
|
cannot be restarted if one of the calls to its operator returns
|
|
non-zero.
|
|
<p>
|
|
The prototype for <code>H5G_iterate_t</code> is:
|
|
<table>
|
|
<tr>
|
|
<td valign="top"> </td>
|
|
<td valign="top"><code>typedef</code> <em>herr_t </em>(*<code>H5G_iterate_t</code>)
|
|
(<em>hid_t</em> <code>group_id</code>, <em>const char *</em>
|
|
<code>member_name</code>, <em>void *</em><code>operator_data</code>);</td></tr>
|
|
</table>
|
|
|
|
<p>The operation receives the group identifier for the group being
|
|
iterated over, <code>group_id</code>, the name of the current
|
|
object within the group, <code>member_name</code>, and the
|
|
pointer to the operator data passed in to <code>H5Giterate</code>,
|
|
<code>operator_data</code>.
|
|
<p>
|
|
The return values from an operator are:
|
|
<ul>
|
|
<li>Zero causes the iterator to continue, returning
|
|
zero when all group members have been processed.
|
|
<li>Positive causes the iterator to immediately return that positive
|
|
value, indicating short-circuit success. The iterator can be
|
|
restarted at the next group member.
|
|
<li>Negative causes the iterator to immediately return that value,
|
|
indicating failure. The iterator can be restarted at the next
|
|
group member.
|
|
</ul>
|
|
<p>
|
|
<code>H5Giterate</code> assumes that the membership of the group
|
|
identified by <code>name</code> remains unchanged through the
|
|
iteration. If the membership changes during the iteration,
|
|
the function's behavior is undefined.
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>loc_id</code></td>
|
|
<td valign="top">IN: File or group identifier.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char</em> <code>*name</code></td>
|
|
<td valign="top">IN: Group over which the iteration is performed.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>int</em> <code>*idx</code></td>
|
|
<td valign="top">IN/OUT: Location at which to begin the iteration.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>H5G_iterate_t</em> <code>operator </code></td>
|
|
<td valign="top">IN: Operation to be performed on an object at each step of
|
|
the iteration.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>void</em> <code>*operator_data</code></td>
|
|
<td valign="top">IN/OUT: Data associated with the operation.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns the return value of the last operator if it was non-zero,
|
|
or zero if all group members were processed.
|
|
Otherwise returns a negative value.
|
|
<!-- NEW PAGE -->
|
|
<dt><strong>Fortran90 Interface:</strong>
|
|
<dd>There is no direct FORTRAN couterpart for the C function
|
|
<code>H5Giterate</code>.
|
|
Instead, that functionality is provided by two FORTRAN functions:
|
|
|
|
<center>
|
|
<table width=80%>
|
|
<tr valign=top align=left>
|
|
<td>
|
|
<code>h5gn_members_f</code>
|
|
</td>
|
|
<td> </td>
|
|
<td>
|
|
<strong>Purpose:</strong>
|
|
Returns the number of group members.
|
|
</tr>
|
|
<tr valign=top align=left>
|
|
<td>
|
|
<code>h5gget_obj_info_idx_f</code>
|
|
</td><td> </td><td>
|
|
<strong>Purpose:</strong>
|
|
Returns name and type of the group member identified by its index.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<pre>
|
|
SUBROUTINE h5gn_members_f(loc_id, name, nmembers, hdferr)
|
|
IMPLICIT NONE
|
|
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
|
|
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group
|
|
INTEGER, INTENT(OUT) :: nmembers ! Number of members in the group
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
! 0 on success and -1 on failure
|
|
END SUBROUTINE h5gn_members_f
|
|
</pre>
|
|
|
|
<pre>
|
|
SUBROUTINE h5gget_obj_info_idx_f(loc_id, name, idx, &
|
|
obj_name, obj_type, hdferr)
|
|
IMPLICIT NONE
|
|
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
|
|
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group
|
|
INTEGER, INTENT(IN) :: idx ! Index of member object
|
|
CHARACTER(LEN=*), INTENT(OUT) :: obj_name ! Name of the object
|
|
INTEGER, INTENT(OUT) :: obj_type ! Object type :
|
|
! H5G_LINK_F
|
|
! H5G_GROUP_F
|
|
! H5G_DATASET_F
|
|
! H5G_TYPE_F
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
! 0 on success and -1 on failure
|
|
END SUBROUTINE h5gget_obj_info_idx_f
|
|
</pre>
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Glink" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Link">H5Glink</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Glink</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>H5G_link_t</em> <code>link_type</code>,
|
|
<em>const char *</em><code>current_name</code>,
|
|
<em>const char *</em><code>new_name</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Creates a link of the specified type from <code>new_name</code>
|
|
to <code>current_name</code>.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Glink</code> creates a new name for an object that has some current
|
|
name, possibly one of many names it currently has.
|
|
<p>
|
|
If <code>link_type</code> is <code>H5G_LINK_HARD</code>, then
|
|
<code>current_name</code> must specify the name of an
|
|
existing object and both
|
|
names are interpreted relative to <code>loc_id</code>, which is
|
|
either a file identifier or a group identifier.
|
|
<p>
|
|
If <code>link_type</code> is <code>H5G_LINK_SOFT</code>, then
|
|
<code>current_name</code> can be anything and is interpreted at
|
|
lookup time relative to the group which contains the final
|
|
component of <code>new_name</code>. For instance, if
|
|
<code>current_name</code> is <code>./foo</code>,
|
|
<code>new_name</code> is <code>./x/y/bar</code>, and a request
|
|
is made for <code>./x/y/bar</code>, then the actual object looked
|
|
up is <code>./x/y/./foo</code>.
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>loc_id</code></td>
|
|
<td valign="top">IN: File or group identifier.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>H5G_link_t</em> <code>link_type</code></td>
|
|
<td valign="top">IN: Link type.
|
|
Possible values are <code>H5G_LINK_HARD</code> and
|
|
<code>H5G_LINK_SOFT</code>.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char *</em> <code>current_name </code></td>
|
|
<td valign="top">IN: Name of the existing object if link is a hard link.
|
|
Can be anything for the soft link.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char *</em> <code>new_name</code></td>
|
|
<td valign="top">IN: New name for the object.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Fortran90 Interface:</strong> h5glink_f
|
|
<dd>
|
|
<pre>
|
|
SUBROUTINE h5glink_f(loc_id, link_type, current_name, new_name, hdferr)
|
|
IMPLICIT NONE
|
|
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group location identifier
|
|
INTEGER, INTENT(IN) :: link_type ! Link type, possible values are:
|
|
! H5G_LINK_HARD_F
|
|
! H5G_LINK_SOFT_F
|
|
CHARACTER(LEN=*), INTENT(IN) :: current_name
|
|
! Current object name relative
|
|
! to loc_id
|
|
CHARACTER(LEN=*), INTENT(IN) :: new_name ! New object name
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
|
|
END SUBROUTINE h5glink_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 "H5Glink2" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Link2">H5Glink2</a>
|
|
<dt><strong>Signature:</strong>
|
|
|
|
<dd><em>herr_t</em> <code>H5Glink2</code>(
|
|
<em>hid_t</em> <code>curr_loc_id</code>, <em>const char *</em><code>current_name</code>,
|
|
<em>H5G_link_t</em> <code>link_type</code>,
|
|
<em>hid_t</em> <code>new_loc_id</code>, <em>const char *</em><code>new_name</code> )
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Creates a link of the specified type from <code>new_name</code>
|
|
to <code>current_name</code>.
|
|
<dt><strong>Description:</strong>
|
|
|
|
<dd><code>H5Glink2</code> creates a new name for an object that has some current
|
|
name, possibly one of many names it currently has.
|
|
<p>
|
|
If <code>link_type</code> is <code>H5G_LINK_HARD</code>, then <code>current_name</code>
|
|
must specify the name of an existing object.
|
|
In this case, <code>current_name</code> and <code>new_name</code> are interpreted
|
|
relative to <code>curr_loc_id</code> and <code>new_loc_id</code>, respectively,
|
|
which are either file or group identifiers.
|
|
<p>
|
|
If <code>link_type</code> is <code>H5G_LINK_SOFT</code>, then
|
|
<code>current_name</code> can be anything and is interpreted at
|
|
lookup time relative to the group which contains the final
|
|
component of <code>new_name</code>. For instance, if
|
|
<code>current_name</code> is <code>./foo</code>,
|
|
<code>new_name</code> is <code>./x/y/bar</code>, and a request
|
|
is made for <code>./x/y/bar</code>, then the actual object looked
|
|
up is <code>./x/y/./foo</code>.
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>curr_loc_id</code></td>
|
|
<td valign="top">IN: The file or group identifier for the original object.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char *</em> <code>current_name </code></td>
|
|
<td valign="top">IN: Name of the existing object if link is a hard link.
|
|
Can be anything for the soft link.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>H5G_link_t</em> <code>link_type</code></td>
|
|
<td valign="top">IN: Link type.
|
|
Possible values are <code>H5G_LINK_HARD</code> and
|
|
<code>H5G_LINK_SOFT</code>.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>new_loc_id</code></td>
|
|
<td valign="top">IN: The file or group identifier for the new link.</td></tr>
|
|
<td valign="top"><em>const char *</em> <code>new_name</code></td>
|
|
<td valign="top">IN: New name for the object.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Fortran90 Interface:</strong> h5glink2_f
|
|
<dd>
|
|
<pre>
|
|
SUBROUTINE h5glink2_f(cur_loc_id, cur_name, link_type, new_loc_id, new_name, hdferr)
|
|
IMPLICIT NONE
|
|
INTEGER(HID_T), INTENT(IN) :: cur_loc_id ! File or group location identifier
|
|
CHARACTER(LEN=*), INTENT(IN) :: cur_name ! Name of the existing object
|
|
! is relative to cur_loc_id
|
|
! Can be anything for the soft link
|
|
INTEGER, INTENT(IN) :: link_type ! Link type, possible values are:
|
|
! H5G_LINK_HARD_F
|
|
! H5G_LINK_SOFT_F
|
|
INTEGER(HID_T), INTENT(IN) :: new_loc_id ! New location identifier
|
|
CHARACTER(LEN=*), INTENT(IN) :: new_name ! New object name
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
|
|
END SUBROUTINE h5glink2_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 "H5Gmove" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Move">H5Gmove</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Gmove</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char</em> <code>*src_name</code>,
|
|
<em>const char</em> <code>*dst_name</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Renames an object within an HDF5 file.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gmove</code> renames an object within an HDF5 file.
|
|
The original name, <code>src_name</code>, is unlinked from the
|
|
group graph and the new name, <code>dst_name</code>, is inserted
|
|
as an atomic operation. Both names are interpreted relative
|
|
to <code>loc_id</code>, which is either a file or a group
|
|
identifier.
|
|
<dt><strong>Warning:</strong>
|
|
<dd>Exercise care in moving groups as it is possible to render data in
|
|
a file inaccessible with <code>H5Gmove</code>.
|
|
See <a href="Groups.html#H5GUnlinkToCorrupt">The Group Interface</a>
|
|
in the <cite>HDF5 User's Guide</cite>.
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>loc_id</code></td>
|
|
<td valign="top">IN: File or group identifier.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char</em> <code>*src_name </code></td>
|
|
<td valign="top">IN: Object's original name.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char</em> <code>*dst_name</code></td>
|
|
<td valign="top">IN: Object's new name.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Fortran90 Interface:</strong> h5gmove_f
|
|
<dd>
|
|
<pre>
|
|
SUBROUTINE h5gmove_f(loc_id, name, new_name, hdferr)
|
|
IMPLICIT NONE
|
|
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
|
|
CHARACTER(LEN=*), INTENT(IN) :: name ! Original name of an object
|
|
CHARACTER(LEN=*), INTENT(IN) :: new_name ! New name of an object
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
! 0 on success and -1 on failure
|
|
END SUBROUTINE h5gmove_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 "H5Gmove2" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Move2">H5Gmove2</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Gmove2</code>( <em>hid_t</em> <code>src_loc_id</code>,
|
|
<em>const char</em> <code>*src_name</code>, <em>hid_t</em> <code>dst_loc_id</code>,
|
|
<em>const char</em> <code>*dst_name</code> )
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Renames an object within an HDF5 file.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gmove2</code> renames an object within an HDF5 file. The original
|
|
name, <code>src_name</code>, is unlinked from the group graph and the new
|
|
name, <code>dst_name</code>, is inserted as an atomic operation.
|
|
<p>
|
|
</p><code>src_name</code> and <code>dst_name</code> are interpreted relative to
|
|
<code>src_name</code> and <code>dst_name</code>, respectively,
|
|
which are either file or group identifiers.
|
|
<dt><strong>Warning:</strong>
|
|
<dd>Exercise care in moving groups as it is possible to render data in a file
|
|
inaccessible with <code>H5Gmove</code>. See <a href="Groups.html#H5GUnlinkToCorrupt">The
|
|
Group Interface</a> in the <cite>HDF5 User's Guide</cite>.
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>src_loc_id</code></td>
|
|
<td valign="top">IN: Original file or group identifier.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char</em> <code>*src_name </code></td>
|
|
<td valign="top">IN: Object's original name.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>dst_loc_id</code></td>
|
|
<td valign="top">IN: Destination file or group identifier.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char</em> <code>*dst_name</code></td>
|
|
<td valign="top">IN: Object's new name.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful; otherwise returns a negative
|
|
value.
|
|
<dt><strong>Fortran90 Interface:</strong> h5gmove2_f
|
|
<dd>
|
|
<pre>
|
|
SUBROUTINE h5gmove2_f(src_loc_id, src_name, dst_loc_id, dst_name, hdferr)
|
|
IMPLICIT NONE
|
|
INTEGER(HID_T), INTENT(IN) :: src_loc_id ! File or group identifier
|
|
CHARACTER(LEN=*), INTENT(IN) :: src_name ! Original name of an object
|
|
! relative to src_loc_id
|
|
INTEGER(HID_T), INTENT(IN) :: dst_loc_id ! File or group identifier
|
|
CHARACTER(LEN=*), INTENT(IN) :: dst_name ! New name of an object
|
|
! relative to dst_loc_id
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
! 0 on success and -1 on failure
|
|
END SUBROUTINE h5gmove2_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 "H5Gopen" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Open">H5Gopen</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Gopen</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Opens an existing group for modification and returns a group
|
|
identifier for that group.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gopen</code> opens an existing group with the specified
|
|
name at the specified location, <code>loc_id</code>.
|
|
<p>
|
|
The location is identified by a file or group identifier
|
|
<p>
|
|
<code>H5Gopen</code> returns a group identifier for the group
|
|
that was opened. This group identifier should be released by
|
|
calling <code>H5Gclose</code> when it is no longer needed.
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>loc_id</code></td>
|
|
<td valign="top">IN: File or group identifier within which group is to be open.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char *</em> <code>name </code></td>
|
|
<td valign="top">IN: Name of group to open.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a valid group identifier if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Fortran90 Interface:</strong> h5gopen_f
|
|
<dd>
|
|
<pre>
|
|
SUBROUTINE h5gopen_f(loc_id, name, gr_id, hdferr)
|
|
IMPLICIT NONE
|
|
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
|
|
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group to open
|
|
INTEGER(HID_T), INTENT(OUT) :: gr_id ! Group identifier
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
! 0 on success and -1 on failure
|
|
END SUBROUTINE h5gopen_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 "H5Gset_comment" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-SetComment">H5Gset_comment</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Gset_comment</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>,
|
|
<em>const char *</em><code>comment</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Sets comment for specified object.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gset_comment</code> sets the comment for the
|
|
object specified by <code>loc_id</code> and <code>name</code>
|
|
to <code>comment</code>.
|
|
Any previously existing comment is overwritten.
|
|
<p>
|
|
If <code>comment</code> is the empty string or a
|
|
null pointer, the comment message is removed from the object.
|
|
<p>
|
|
Comments should be relatively short, null-terminated,
|
|
ASCII strings.
|
|
<p>
|
|
Comments can be attached to any object that has an object header,
|
|
e.g., datasets, groups, named datatypes, and dataspaces, but
|
|
not symbolic links.
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>loc_id</code></td>
|
|
<td valign="top">IN: Identifier of the file, group, dataset,
|
|
or named datatype.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char *</em><code>name</code></td>
|
|
<td valign="top">IN: Name of the object whose comment is to be
|
|
set or reset.
|
|
<br>
|
|
<code>name</code> can be '.' (dot) if <code>loc_id</code>
|
|
fully specifies the object for which the comment is to be set.
|
|
<br>
|
|
<code>name</code> is ignored if <code>loc_id</code>
|
|
is a dataset or named datatype.
|
|
</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char *</em><code>comment </code></td>
|
|
<td valign="top">IN: The new comment.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Fortran90 Interface:</strong> h5gset_comment_f
|
|
<dd>
|
|
<pre>
|
|
SUBROUTINE h5gset_comment_f(loc_id, name, comment, hdferr)
|
|
IMPLICIT NONE
|
|
INTEGER(HID_T), INTENT(IN) :: loc_id ! File, group, dataset, or
|
|
! named datatype identifier
|
|
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of object
|
|
CHARACTER(LEN=*), INTENT(IN) :: comment ! Comment for the object
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
! 0 on success and -1 on failure
|
|
END SUBROUTINE h5gset_comment_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 "H5Gunlink" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Group-Unlink">H5Gunlink</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Gunlink</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Removes the link to an object from a group.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Gunlink</code> removes the object specified by
|
|
<code>name</code> from the group graph and decrements the
|
|
link count for the object to which <code>name</code> points.
|
|
This action eliminates any association between <code>name</code>
|
|
and the object to which <code>name</code> pointed.
|
|
<p>
|
|
Object headers keep track of how many hard links refer to an object;
|
|
when the link count reaches zero, the object can be removed
|
|
from the file. Objects which are open are not removed until all
|
|
identifiers to the object are closed.
|
|
<p>
|
|
If the link count reaches zero, all file space associated with
|
|
the object will be released, i.e., identified in memory as freespace.
|
|
If the any object identifier is open for the object, the space
|
|
will not be released until after the object identifier is closed.
|
|
<p>
|
|
Note that space identified as freespace is available for re-use
|
|
only as long as the file remains open; once a file has been
|
|
closed, the HDF5 library loses track of freespace. See
|
|
“<a href="Performance.html#Freespace">Freespace Management</a>”
|
|
in the <cite>HDF5 User's Guide</cite> for further details.
|
|
<dt><strong>Warning:</strong>
|
|
<dd>Exercise care in unlinking groups as it is possible to render data in
|
|
a file inaccessible with <code>H5Gunlink</code>.
|
|
See <a href="Groups.html#H5GUnlinkToCorrupt">The Group Interface</a>
|
|
in the <cite>HDF5 User's Guide</cite>.
|
|
<dt><strong>Parameters:</strong>
|
|
<ul><table>
|
|
<tr>
|
|
<td valign="top"><em>hid_t</em> <code>loc_id</code></td>
|
|
<td valign="top">IN: Identifier of the file or group containing the object.</td></tr>
|
|
<tr>
|
|
<td valign="top"><em>const char *</em> <code>name </code></td>
|
|
<td valign="top">IN: Name of the object to unlink.</td></tr>
|
|
</table></ul>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Fortran90 Interface:</strong> h5gunlink_f
|
|
<dd>
|
|
<pre>
|
|
SUBROUTINE h5gunlink_f(loc_id, name, hdferr)
|
|
IMPLICIT NONE
|
|
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
|
|
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the object to unlink
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
! 0 on success and -1 on failure
|
|
END SUBROUTINE h5gunlink_f
|
|
</pre>
|
|
|
|
<!--<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: 25 May 2004");
|
|
-->
|
|
</SCRIPT>
|
|
|
|
</body>
|
|
</html>
|