summaryrefslogtreecommitdiffstats
path: root/doc/html/Groups.html
diff options
context:
space:
mode:
authorQuincey Koziol <koziol@hdfgroup.org>1998-07-08 14:54:54 (GMT)
committerQuincey Koziol <koziol@hdfgroup.org>1998-07-08 14:54:54 (GMT)
commitbd1e676c521d881b3143829f493a28b5ced1294b (patch)
tree69c50f9fe21ce87f293d8617a6bd51b4cc1e0244 /doc/html/Groups.html
parent73345095897d9698bb1f2f7df830bf80a56dc65a (diff)
downloadhdf5-bd1e676c521d881b3143829f493a28b5ced1294b.zip
hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.gz
hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.bz2
[svn-r467] Restructuring documentation.
Diffstat (limited to 'doc/html/Groups.html')
-rw-r--r--doc/html/Groups.html288
1 files changed, 288 insertions, 0 deletions
diff --git a/doc/html/Groups.html b/doc/html/Groups.html
new file mode 100644
index 0000000..b1be2f1
--- /dev/null
+++ b/doc/html/Groups.html
@@ -0,0 +1,288 @@
+<!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>
+
+ <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: Tue Mar 24 15:52:14 EST 1998
+<!-- hhmts end -->
+ </body>
+</html>