1998-07-08 22:54:54 +08:00
|
|
|
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<title>Groups</title>
|
|
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
<h1>Groups</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
|
|
|
|
|
current working group (described below) or a 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 of the specified file.</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 current working group of the specified file. The
|
|
|
|
|
initial current working group is the root group of the
|
|
|
|
|
file as described below.</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 current working group of the specified 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. Current Working Group</h2>
|
|
|
|
|
|
|
|
|
|
<p>Each file handle (<code>hid_t <em>file_id</em></code>) has a
|
|
|
|
|
current working group, initially the root group of the file.
|
|
|
|
|
Names which do not begin with a slash are relative to the
|
|
|
|
|
specified group or to the current working group as described
|
|
|
|
|
above. For instance, the name "/Foo/Bar/Baz" is resolved by
|
|
|
|
|
first looking up "Foo" in the root group. But the name
|
|
|
|
|
"Foo/Bar/Baz" is resolved by first looking up "Foo" in the
|
|
|
|
|
current working group.
|
|
|
|
|
|
|
|
|
|
<dl>
|
|
|
|
|
<dt><code>herr_t H5Gset (hid_t <em>location_id</em>, const char
|
|
|
|
|
*<em>name</em>)</code>
|
|
|
|
|
<dd>The group with the specified name is made the current
|
|
|
|
|
working group for the file which contains it. The
|
|
|
|
|
<em>location_id</em> can be a file handle or a group handle
|
|
|
|
|
and the name is resolved as described above. Each file handle
|
|
|
|
|
has it's own current working group and if the
|
|
|
|
|
<em>location_id</em> is a group handle then the file handle is
|
|
|
|
|
derived from the group handle. This function returns zero for
|
|
|
|
|
success or negative for failure.
|
|
|
|
|
|
|
|
|
|
<br><br>
|
|
|
|
|
<dt><code>herr_t H5Gpush (hid_t <em>location_id</em>, const char
|
|
|
|
|
*<em>name</em>)</code>
|
|
|
|
|
<dd>Each file handle has a stack of groups and the top group on
|
|
|
|
|
that stack is the current working group. The stack initially
|
|
|
|
|
contains only the root group. This function pushes a new
|
|
|
|
|
group onto the stack and returns zero for success or negative
|
|
|
|
|
for failure.
|
|
|
|
|
|
|
|
|
|
<br><br>
|
|
|
|
|
<dt><code>herr_t H5Gpop (hid_t <em>location_id</em>)</code>
|
|
|
|
|
<dd>This function pops one group off the group stack for the
|
|
|
|
|
specified file (if the <em>location_id</em> is a group then
|
|
|
|
|
the file is derived from that group), changing the current
|
|
|
|
|
working group to the new top-of-stack group. The function
|
|
|
|
|
returns zero for success or negative for failure (failure
|
|
|
|
|
includes attempting to pop from an empty stack). If the last
|
|
|
|
|
item is popped from the stack then the current working group
|
|
|
|
|
is set to the root group.
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
<h2>5. 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. <b>This function is not
|
|
|
|
|
part of the prototype API.</b>
|
|
|
|
|
|
|
|
|
|
<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). <b>This function is not part of the prototype
|
|
|
|
|
API.</b>
|
|
|
|
|
</dl>
|
|
|
|
|
|
1998-07-21 05:01:32 +08:00
|
|
|
<h2>6. 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
|
[svn-r537] Changes since 19980722
----------------------
./src/H5A.c
./src/H5Apublic.h
./test/tattr.c
Switched the order of the second and third argument of
H5Aget_name() to make it consistent with other functions that
take buffers and buffer sizes.
./src/H5G.c
./src/H5Gpublic.h
./src/H5Gprivate.h
The H5Gget_comment() function returns the size of the comment
including the null terminator. If the object has no comment
then zero is returned. If an error occurs then a negative
value is returned.
./MANIFEST
./tools/Makefile.in
./tools/h5tools.h [NEW]
./tools/h5dump.c [NEW]
Created a library for printing values of datasets in a way
that looks nice. It's not done yet, but I needed it for
debugging the contents of files from Jim Reus.
./tools/h5ls.c
Added the `-d' and `--dump' options which cause the contents
of a dataset to be printed. Added `-w N' and `--width=N'
options to control how wide the raw data output should be. If
you want single-column output then say `-w1'.
Printing dataset values can now handle datasets of any integer
or floating point atomic type. As a special case, integers
which are one byte wide are treated a character strings for
now.
Sample output:
$ h5ls --dump --width=60 banana.hdf
ARCHIVE 0:0:0:744 Dataset {52/Inf}
Data:
(0) "U struct complex { double R; double I; };\012V"
(43) " double;\012"
U 0:0:0:2500 Dataset {256/512}
Data: printing of compound data types is not implemented yet
V 0:0:0:3928 Dataset {256/512}
Data:
(0) 0, 0.015625, 0.03125, 0.046875, 0.0625,
(5) 0.078125, 0.09375, 0.109375, 0.125, 0.140625,
(10) 0.15625, 0.171875, 0.1875, 0.203125, 0.21875,
(15) 0.234375, 0.25, 0.265625, 0.28125, 0.296875,
...
1998-07-24 05:19:17 +08:00
|
|
|
including a null terminator are copied, and the result is
|
1998-07-21 05:01:32 +08:00
|
|
|
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>
|
|
|
|
|
|
1998-09-10 06:48:37 +08:00
|
|
|
<!--
|
1998-07-08 22:54:54 +08:00
|
|
|
<hr>
|
|
|
|
|
<address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address>
|
1998-09-10 06:48:37 +08:00
|
|
|
-->
|
1998-07-08 22:54:54 +08:00
|
|
|
<!-- Created: Tue Jan 27 09:11:27 EST 1998 -->
|
|
|
|
|
<!-- hhmts start -->
|
1998-09-10 06:48:37 +08:00
|
|
|
<!--
|
[svn-r537] Changes since 19980722
----------------------
./src/H5A.c
./src/H5Apublic.h
./test/tattr.c
Switched the order of the second and third argument of
H5Aget_name() to make it consistent with other functions that
take buffers and buffer sizes.
./src/H5G.c
./src/H5Gpublic.h
./src/H5Gprivate.h
The H5Gget_comment() function returns the size of the comment
including the null terminator. If the object has no comment
then zero is returned. If an error occurs then a negative
value is returned.
./MANIFEST
./tools/Makefile.in
./tools/h5tools.h [NEW]
./tools/h5dump.c [NEW]
Created a library for printing values of datasets in a way
that looks nice. It's not done yet, but I needed it for
debugging the contents of files from Jim Reus.
./tools/h5ls.c
Added the `-d' and `--dump' options which cause the contents
of a dataset to be printed. Added `-w N' and `--width=N'
options to control how wide the raw data output should be. If
you want single-column output then say `-w1'.
Printing dataset values can now handle datasets of any integer
or floating point atomic type. As a special case, integers
which are one byte wide are treated a character strings for
now.
Sample output:
$ h5ls --dump --width=60 banana.hdf
ARCHIVE 0:0:0:744 Dataset {52/Inf}
Data:
(0) "U struct complex { double R; double I; };\012V"
(43) " double;\012"
U 0:0:0:2500 Dataset {256/512}
Data: printing of compound data types is not implemented yet
V 0:0:0:3928 Dataset {256/512}
Data:
(0) 0, 0.015625, 0.03125, 0.046875, 0.0625,
(5) 0.078125, 0.09375, 0.109375, 0.125, 0.140625,
(10) 0.15625, 0.171875, 0.1875, 0.203125, 0.21875,
(15) 0.234375, 0.25, 0.265625, 0.28125, 0.296875,
...
1998-07-24 05:19:17 +08:00
|
|
|
Last modified: Wed Jul 22 14:24:34 EDT 1998
|
1998-09-10 06:48:37 +08:00
|
|
|
-->
|
1998-07-08 22:54:54 +08:00
|
|
|
<!-- hhmts end -->
|
1998-09-10 06:48:37 +08:00
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
<address>
|
|
|
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
|
|
|
</address>
|
|
|
|
|
|
|
|
|
|
Last modified: 9 September 1998
|
|
|
|
|
|
1998-07-08 22:54:54 +08:00
|
|
|
</body>
|
|
|
|
|
</html>
|
