mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-21 01:04:10 +08:00
82fb21b613
been checked into "HDF5 Development" branch. General ======= Various "copy edit" types of repairs. Revisions to document cross-linking. Added structural links tying all docs together (banners at top and bottom of documents, similar to Reference Manual banners of the Beta release). Set background color to white in all documents. NCSAfooterlogo.gif hdf2.jpg New image files to make the documents more self-contained (i.e., to prevent loading images from NCSA and HDF home servers). index.html Redesigned to isolate links external to the installation in a single location. Intro to HDF5 ============= H5.intro.html Fixed banner linking Intro to other docs. Set all URLs to be relative within the distribution; nothing points back to the HDF server. Updates to "Limits of the Current Release" and "Changes in the Current Release." HDF5 User's Guide ================= Changed several User Guide section titles such that all sections that are primarily about a particular interface are now titled in the format "The xxxxx Interface (H5x)". H5.user.html Commented out links to developer docs since they are marked in MANIFEST as not being for distribution in the release. Removed 2nd and 3rd indices from page. Changed "freeform" lists of sections (TOCs) to aligned tables. Datatypes.html Removed the sentence "I'm deferring definition until later since they're probably not as important as the other data types." from Section 3.3, "Properties of Date and Time Atomic Types." Added info regarding 'char' versus 'string' datatypes. Added as Section 3.7, "Character and String Datatype Issues." References.html Commented out substantial material (at end of document) from References planning document that is not appropriate for the User Guide but that is worth keeping around. Groups.html Final edits from elimination of "current working group." HDF5 Reference Manual ===================== Removed "Draft" from the <title>__</title> lines. RM_H5Front.html Removed 2nd and 3rd indices from page. Changed "freeform" lists of sections (TOCs) to aligned tables. RM_H5F.html RM_H5P.html Add file mounting information.
401 lines
14 KiB
HTML
401 lines
14 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Groups</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Files.html">Files</a>
|
|
<br>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Data Types</a>
|
|
<a href="Dataspaces.html">Dataspaces</a>
|
|
Groups
|
|
<a href="References.html">References</a>
|
|
<br>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
<a href="Errors.html">Error Handling</a>
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<br>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
<a href="Ragged.html">Ragged Arrays</a>
|
|
<!--
|
|
<hr>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Attributes.html">H5A</a>
|
|
<a href="Datasets.html">H5D</a>
|
|
<a href="Errors.html">H5E</a>
|
|
<a href="Files.html">H5F</a>
|
|
<a href="Groups.html">H5G</a>
|
|
<a href="Properties.html">H5P</a>
|
|
<a href="References.html">H5R & H5I</a>
|
|
<a href="Ragged.html">H5RA</a>
|
|
<a href="Dataspaces.html">H5S</a>
|
|
<a href="Datatypes.html">H5T</a>
|
|
<a href="Filters.html">H5Z</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
-->
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
|
|
|
|
<h1>The Group Interface (H5G)</h1>
|
|
|
|
<h2>1. Introduction</h2>
|
|
|
|
<p>An object in HDF5 consists of an object header at a fixed file
|
|
address that contains messages describing various properties of
|
|
the object such as its storage location, layout, compression,
|
|
etc. and some of these messages point to other data such as the
|
|
raw data of a dataset. The address of the object header is also
|
|
known as an <em>OID</em> and HDF5 has facilities for translating
|
|
names to OIDs.
|
|
|
|
<p>Every HDF5 object has at least one name and a set of names can
|
|
be stored together in a group. Each group implements a name
|
|
space where the names are any length and unique with respect to
|
|
other names in the group.
|
|
|
|
<p>Since a group is a type of HDF5 object it has an object header
|
|
and a name which exists as a member of some other group. In this
|
|
way, groups can be linked together to form a directed graph.
|
|
One particular group is called the <em>Root Group</em> and is
|
|
the group to which the HDF5 file boot block points. Its name is
|
|
"/" by convention. The <em>full name</em> of an object is
|
|
created by joining component names with slashes much like Unix.
|
|
|
|
<p>
|
|
<center>
|
|
<img alt="Group Graph Example" src="group_p1.gif">
|
|
</center>
|
|
|
|
<p>However, unlike Unix which arranges directories hierarchically,
|
|
HDF5 arranges groups in a directed graph. Therefore, there is
|
|
no ".." entry in a group since a group can have more than one
|
|
parent. There is no "." entry either but the library understands
|
|
it internally.
|
|
|
|
<h2>2. Names</h2>
|
|
|
|
<p>HDF5 places few restrictions on names: component names may be
|
|
any length except zero and may contain any character except
|
|
slash ("/") and the null terminator. A full name may be
|
|
composed of any number of component names separated by slashes,
|
|
with any of the component names being the special name ".". A
|
|
name which begins with a slash is an <em>absolute</em> name
|
|
which is looked up beginning at the root group of the file while
|
|
all other <em>relative</em> names are looked up beginning at the
|
|
specified group.
|
|
Multiple consecutive slashes in a full name are treated as
|
|
single slashes and trailing slashes are not significant. A
|
|
special case is the name "/" (or equivalent) which refers to the
|
|
root group.
|
|
|
|
<p>Functions which operate on names generally take a location
|
|
identifier which is either a file ID or a group ID and perform
|
|
the lookup with respect to that location. Some possibilities
|
|
are:
|
|
|
|
<p>
|
|
<center>
|
|
<table border cellpadding=4>
|
|
<tr>
|
|
<th>Location Type</th>
|
|
<th>Object Name</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>File ID</td>
|
|
<td><code>/foo/bar</code></td>
|
|
<td>The object <code>bar</code> in group <code>foo</code>
|
|
in the root group.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Group ID</td>
|
|
<td><code>/foo/bar</code></td>
|
|
<td>The object <code>bar</code> in group <code>foo</code>
|
|
in the root group of the file containing the specified
|
|
group. In other words, the group ID's only purpose is
|
|
to supply a file.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>File ID</td>
|
|
<td><code>/</code></td>
|
|
<td>The root group of the specified file.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Group ID</td>
|
|
<td><code>/</code></td>
|
|
<td>The root group of the file containing the specified
|
|
group.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>File ID</td>
|
|
<td><code>foo/bar</code></td>
|
|
<td>The object <code>bar</code> in group <code>foo</code>
|
|
in the specified group.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Group ID</td>
|
|
<td><code>foo/bar</code></td>
|
|
<td>The object <code>bar</code> in group <code>foo</code>
|
|
in the specified group.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>File ID</td>
|
|
<td><code>.</code></td>
|
|
<td>The root group of the file.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Group ID</td>
|
|
<td><code>.</code></td>
|
|
<td>The specified group.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Other ID</td>
|
|
<td><code>.</code></td>
|
|
<td>The specified object.</td>
|
|
</tr>
|
|
|
|
</table>
|
|
</center>
|
|
|
|
|
|
<h2>3. Creating, Opening, and Closing Groups</h2>
|
|
|
|
<p>Groups are created with the <code>H5Gcreate()</code> function,
|
|
and existing groups can be access with
|
|
<code>H5Gopen()</code>. Both functions return an object ID which
|
|
should be eventually released by calling
|
|
<code>H5Gclose()</code>.
|
|
|
|
<dl>
|
|
<dt><code>hid_t H5Gcreate (hid_t <em>location_id</em>, const char
|
|
*<em>name</em>, size_t <em>size_hint</em>)</code>
|
|
<dd>This function creates a new group with the specified
|
|
name at the specified location which is either a file ID or a
|
|
group ID. The name must not already be taken by some other
|
|
object and all parent groups must already exist. The
|
|
<em>size_hint</em> 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 <em>size_hint</em>
|
|
is usually adequate since the library is able to dynamically
|
|
resize the name heap, but a correct hint may result in better
|
|
performance. The return value is a handle for the open group
|
|
and it should be closed by calling <code>H5Gclose()</code>
|
|
when it's no longer needed. A negative value is returned for
|
|
failure.
|
|
|
|
<br><br>
|
|
<dt><code>hid_t H5Gopen (hid_t <em>location_id</em>, const char
|
|
*<em>name</em>)</code>
|
|
<dd>This function opens an existing group with the specified
|
|
name at the specified location which is either a file ID or a
|
|
group ID and returns an object ID. The object ID should be
|
|
released by calling <code>H5Gclose()</code> when it is no
|
|
longer needed. A negative value is returned for failure.
|
|
|
|
<br><br>
|
|
<dt><code>herr_t H5Gclose (hid_t <em>group_id</em>)</code>
|
|
<dd>This function releases resources used by an group which was
|
|
opened by <code>H5Gcreate()</code> or
|
|
<code>H5Gopen()</code>. After closing a group the
|
|
<em>group_id</em> should not be used again. This function
|
|
returns zero for success or a negative value for failure.
|
|
</dl>
|
|
|
|
<h2>4. Objects with Multiple Names</h2>
|
|
|
|
<p>An object (including a group) can have more than one
|
|
name. Creating the object gives it the first name, and then
|
|
functions described here can be used to give it additional
|
|
names. The association between a name and the object is called
|
|
a <em>link</em> and HDF5 supports two types of links: a <em>hard
|
|
link</em> is a direct association between the name and the
|
|
object where both exist in a single HDF5 address space, and a
|
|
<em>soft link</em> is an indirect association.
|
|
|
|
<p>
|
|
<center>
|
|
<img alt="Hard Link Example" src="group_p2.gif">
|
|
</center>
|
|
|
|
<p>
|
|
<center>
|
|
<img alt="Soft Link Example" src="group_p3.gif">
|
|
</center>
|
|
|
|
<dl>
|
|
<dt>Object Creation</dt>
|
|
<dd>The creation of an object creates a hard link which is
|
|
indistinguishable from other hard links that might be added
|
|
later.
|
|
|
|
<br><br>
|
|
<dt><code>herr_t H5Glink (hid_t <em>file_id</em>, H5G_link_t
|
|
<em>link_type</em>, const char *<em>current_name</em>,
|
|
const char *<em>new_name</em>)</code>
|
|
<dd>Creates a new name for an object that has some current name
|
|
(possibly one of many names it currently has). If the
|
|
<em>link_type</em> is <code>H5G_LINK_HARD</code> then a new
|
|
hard link is created. Otherwise if <em>link_type</em> is
|
|
<code>H5T_LINK_SOFT</code> a soft link is created which is an
|
|
alias for the <em>current_name</em>. When creating a soft
|
|
link the object need not exist. This function returns zero
|
|
for success or negative for failure.
|
|
|
|
<br><br>
|
|
<dt><code>herr_t H5Gunlink (hid_t <em>file_id</em>, const char
|
|
*<em>name</em>)</code>
|
|
<dd>This function removes an association between a name and an
|
|
object. Object headers keep track of how many hard links refer
|
|
to the object and when the hard link count reaches zero the
|
|
object can be removed from the file (but objects which are
|
|
open are not removed until all handles to the object are
|
|
closed).
|
|
</dl>
|
|
|
|
<h2>5. Comments</h2>
|
|
|
|
<p>Objects can have a comment associated with them. The comment
|
|
is set and queried with these two functions:
|
|
|
|
<dl>
|
|
<dt><code>herr_t H5Gset_comment (hid_t <em>loc_id</em>, const
|
|
char *<em>name</em>, const char *<em>comment</em>)</code>
|
|
<dd>The previous comment (if any) for the specified object is
|
|
replace with a new comment. If the <em>comment</em> argument
|
|
is the empty string or a null pointer then the comment message
|
|
is removed from the object. Comments should be relatively
|
|
short, null-terminated, ASCII strings.
|
|
|
|
<br><br>
|
|
<dt><code>herr_t H5Gget_comment (hid_t <em>loc_id</em>, const
|
|
char *<em>name</em>, size_t <em>bufsize</em>, char
|
|
*<em>comment</em>)</code>
|
|
<dd>The comment string for an object is returned through the
|
|
<em>comment</em> buffer. At most <em>bufsize</em> characters
|
|
including a null terminator are copied, and the result is
|
|
not null terminated if the comment is longer than the supplied
|
|
buffer. If an object doesn't have a comment then the empty
|
|
string is returned.
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Files.html">Files</a>
|
|
<br>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Data Types</a>
|
|
<a href="Dataspaces.html">Dataspaces</a>
|
|
Groups
|
|
<a href="References.html">References</a>
|
|
<br>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
<a href="Errors.html">Error Handling</a>
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<br>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
<a href="Ragged.html">Ragged Arrays</a>
|
|
<!--
|
|
<hr>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Attributes.html">H5A</a>
|
|
<a href="Datasets.html">H5D</a>
|
|
<a href="Errors.html">H5E</a>
|
|
<a href="Files.html">H5F</a>
|
|
<a href="Groups.html">H5G</a>
|
|
<a href="Properties.html">H5P</a>
|
|
<a href="References.html">H5R & H5I</a>
|
|
<a href="Ragged.html">H5RA</a>
|
|
<a href="Dataspaces.html">H5S</a>
|
|
<a href="Datatypes.html">H5T</a>
|
|
<a href="Filters.html">H5Z</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
-->
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
|
|
|
|
<!--
|
|
<hr>
|
|
<address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address>
|
|
-->
|
|
<!-- Created: Tue Jan 27 09:11:27 EST 1998 -->
|
|
<!-- hhmts start -->
|
|
<!--
|
|
Last modified: Wed Jul 22 14:24:34 EDT 1998
|
|
-->
|
|
<!-- hhmts end -->
|
|
|
|
<hr>
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
</address>
|
|
|
|
Last modified: 30 October 1998
|
|
|
|
</body>
|
|
</html>
|