mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-21 01:04:10 +08:00
2e588eef3f
Purpose:
Bugfixes in H5Gset_comment, h5gget_comment_f, and h5gset_comment_f.
(Follow-on to the H5Gget_comment bugfix of last week.)
Description:
Changed C parameter descriptions to indicate the following:
'loc_id' can be file, group, dataset, or named datatype.
'name' can be '.' if 'loc_id' fully describes the object.
'name' is ignored if 'loc_id' is a dataset or named datatype.
Modified h5gget_comment_f and h5gset_comment_f notes accordingly.
Copy edits in H5Gget/set_comment and h5gget/set_comment_f.
Platforms tested:
Safari
1484 lines
59 KiB
HTML
1484 lines
59 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 -->
|
|
<!-- 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:
|
|
<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>
|
|
The <code>fileno</code> and <code>objno</code> fields contain
|
|
values which uniquely identify an object among those
|
|
HDF5 files which are open: if both 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).
|
|
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>.
|
|
The <code>mtime</code> field contains the modification time.
|
|
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.
|
|
|
|
<!-- INSERT H50_stat_t DESCRIPTION AS IN 1.6 -->
|
|
|
|
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).
|
|
<!-- NEW PAGE -->
|
|
<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>
|