[svn-r467] Restructuring documentation.

author: Quincey Koziol <koziol@hdfgroup.org> 1998-07-08 14:54:54 (GMT)
committer: Quincey Koziol <koziol@hdfgroup.org> 1998-07-08 14:54:54 (GMT)
commit: bd1e676c521d881b3143829f493a28b5ced1294b (patch)
tree: 69c50f9fe21ce87f293d8617a6bd51b4cc1e0244 /doc/html/Groups.html
parent: 73345095897d9698bb1f2f7df830bf80a56dc65a (diff)
download: hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.zip
hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.gz
hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.bz2
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>
author	Quincey Koziol <koziol@hdfgroup.org>	1998-07-08 14:54:54 (GMT)
committer	Quincey Koziol <koziol@hdfgroup.org>	1998-07-08 14:54:54 (GMT)
commit	bd1e676c521d881b3143829f493a28b5ced1294b (patch)
tree	69c50f9fe21ce87f293d8617a6bd51b4cc1e0244 /doc/html/Groups.html
parent	73345095897d9698bb1f2f7df830bf80a56dc65a (diff)
download	hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.zip hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.gz hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.bz2