hdf5/doc/html/Groups.html

403 lines
15 KiB
HTML
Raw Normal View History

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>Group Interface (H5G)</title>
[svn-r985] Checking in changes from "HDF5 Release 1.0" CVS branch that have not yet 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.
1998-12-22 06:52:56 +08:00
<!-- #BeginLibraryItem "/ed_libs/styles_UG.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/UGelect.css" rel="stylesheet" type="text/css">
<!-- #EndLibraryItem --></head>
[svn-r985] Checking in changes from "HDF5 Release 1.0" CVS branch that have not yet 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.
1998-12-22 06:52:56 +08:00
<body bgcolor="#FFFFFF">
<!-- #BeginLibraryItem "/ed_libs/NavBar_UG.lbi" --><hr>
[svn-r985] Checking in changes from "HDF5 Release 1.0" CVS branch that have not yet 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.
1998-12-22 06:52:56 +08:00
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
<a href="index.html">HDF5 documents and links</a>&nbsp;<br>
<a href="H5.intro.html">Introduction to HDF5</a>&nbsp;<br>
<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;<br>
<!--
<a href="Glossary.html">Glossary</a><br>
-->
[svn-r985] Checking in changes from "HDF5 Release 1.0" CVS branch that have not yet 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.
1998-12-22 06:52:56 +08:00
</td>
<td valign=top align=right>
And in this document, the
<a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a>&nbsp;&nbsp;&nbsp;&nbsp;
<br>
<a href="Files.html">Files</a>&nbsp;&nbsp;
<a href="Datasets.html">Datasets</a>&nbsp;&nbsp;
<a href="Datatypes.html">Datatypes</a>&nbsp;&nbsp;
<a href="Dataspaces.html">Dataspaces</a>&nbsp;&nbsp;
<a href="Groups.html">Groups</a>&nbsp;&nbsp;
<br>
<a href="References.html">References</a>&nbsp;&nbsp;
<a href="Attributes.html">Attributes</a>&nbsp;&nbsp;
<a href="Properties.html">Property Lists</a>&nbsp;&nbsp;
<a href="Errors.html">Error Handling</a>&nbsp;&nbsp;
<br>
<a href="Filters.html">Filters</a>&nbsp;&nbsp;
<a href="Caching.html">Caching</a>&nbsp;&nbsp;
<a href="Chunking.html">Chunking</a>&nbsp;&nbsp;
<a href="MountingFiles.html">Mounting Files</a>&nbsp;&nbsp;
<br>
<a href="Performance.html">Performance</a>&nbsp;&nbsp;
<a href="Debugging.html">Debugging</a>&nbsp;&nbsp;
<a href="Environment.html">Environment</a>&nbsp;&nbsp;
<a href="ddl.html">DDL</a>&nbsp;&nbsp;
[svn-r985] Checking in changes from "HDF5 Release 1.0" CVS branch that have not yet 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.
1998-12-22 06:52:56 +08:00
</td></tr>
</table>
</center>
<hr>
<!-- #EndLibraryItem --><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 super 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
[svn-r830] ====== Intro ====== H5.intro.html Major rewrite to Groups section. New Example 7 (groups). Added TOC and requisite links. Numbered sections. Labelled figures and centered those that were not. Fixed table formatting. =========== User Guide =========== H5.user.html Linked in Chunking.html. Linked in References.html. Linked in DDL.html. Chunking.html Minor edits. DDL.html References.html New documents. Datatypes.html Added "R Reference" to base name description and "H5T_STD_ROBJ -- Reference to an entire object in a file" to list of datatype names. Files.html H5Fflush Added scope parameter. Groups.html Removed references to "current working group." Removed H5Gpush, H5Gpop, and H5Gset functions. Removed note that H5Glink and H5Gunlink were not implemented. ================= Reference Manual ================= RM_*.html and Tools.html Updated Reference Manual internal cross-linking (the link banner at the top and bottom of each page). Changed Returns SUCCEED (0) if successful; otherwise FAIL (-1). to read Returns a non-negative value if successful; otherwise returns a negative value. and several derived changes where circumstances differred only slightly. Minor copy edits throughout. RM_H5.html Corrected H5open "Purpose" statement. RM_H5A.html Changed H5Aget_name return type to hssize_t. RM_H5F.html H5Fflush Added scope parameter. Added H5Freopen. RM_H5Front.html Reordered listing of interfaces to alphabetical order (H5, H5A, H5D, ...) Added H5I, H5R, and H5RA. RM_H5G.html H5Gopen Edited "Description." H5Gget_objinfo Added named datatype to list of valid values for loc_id. RM_H5I.html Identifier Interface New section. RM_H5P.html Added H5Pset_fill_value and H5Pget_fill_value. Several minor copy edits. RM_H5R.html Reference Interface New section. H5RA.html Essentially a new section. It was in the tree previously, but it did not actually have content. RM_H5S.html Changed H5Sget_select_npoints return type to hssize_t. Tools.html Updated h5dump documentation.
1998-10-30 06:13:17 +08:00
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>
[svn-r985] Checking in changes from "HDF5 Release 1.0" CVS branch that have not yet 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.
1998-12-22 06:52:56 +08:00
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>
[svn-r830] ====== Intro ====== H5.intro.html Major rewrite to Groups section. New Example 7 (groups). Added TOC and requisite links. Numbered sections. Labelled figures and centered those that were not. Fixed table formatting. =========== User Guide =========== H5.user.html Linked in Chunking.html. Linked in References.html. Linked in DDL.html. Chunking.html Minor edits. DDL.html References.html New documents. Datatypes.html Added "R Reference" to base name description and "H5T_STD_ROBJ -- Reference to an entire object in a file" to list of datatype names. Files.html H5Fflush Added scope parameter. Groups.html Removed references to "current working group." Removed H5Gpush, H5Gpop, and H5Gset functions. Removed note that H5Glink and H5Gunlink were not implemented. ================= Reference Manual ================= RM_*.html and Tools.html Updated Reference Manual internal cross-linking (the link banner at the top and bottom of each page). Changed Returns SUCCEED (0) if successful; otherwise FAIL (-1). to read Returns a non-negative value if successful; otherwise returns a negative value. and several derived changes where circumstances differred only slightly. Minor copy edits throughout. RM_H5.html Corrected H5open "Purpose" statement. RM_H5A.html Changed H5Aget_name return type to hssize_t. RM_H5F.html H5Fflush Added scope parameter. Added H5Freopen. RM_H5Front.html Reordered listing of interfaces to alphabetical order (H5, H5A, H5D, ...) Added H5I, H5R, and H5RA. RM_H5G.html H5Gopen Edited "Description." H5Gget_objinfo Added named datatype to list of valid values for loc_id. RM_H5I.html Identifier Interface New section. RM_H5P.html Added H5Pset_fill_value and H5Pget_fill_value. Several minor copy edits. RM_H5R.html Reference Interface New section. H5RA.html Essentially a new section. It was in the tree previously, but it did not actually have content. RM_H5S.html Changed H5Sget_select_npoints return type to hssize_t. Tools.html Updated h5dump documentation.
1998-10-30 06:13:17 +08:00
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>
[svn-r985] Checking in changes from "HDF5 Release 1.0" CVS branch that have not yet 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.
1998-12-22 06:52:56 +08:00
<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>
<p>Note, however, that object names within a group must be unique.
For example, <code>H5Dcreate</code> returns an error if a
dataset with the dataset name specified in the parameter list
already exists at the location specified in the parameter list.
<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>
[svn-r830] ====== Intro ====== H5.intro.html Major rewrite to Groups section. New Example 7 (groups). Added TOC and requisite links. Numbered sections. Labelled figures and centered those that were not. Fixed table formatting. =========== User Guide =========== H5.user.html Linked in Chunking.html. Linked in References.html. Linked in DDL.html. Chunking.html Minor edits. DDL.html References.html New documents. Datatypes.html Added "R Reference" to base name description and "H5T_STD_ROBJ -- Reference to an entire object in a file" to list of datatype names. Files.html H5Fflush Added scope parameter. Groups.html Removed references to "current working group." Removed H5Gpush, H5Gpop, and H5Gset functions. Removed note that H5Glink and H5Gunlink were not implemented. ================= Reference Manual ================= RM_*.html and Tools.html Updated Reference Manual internal cross-linking (the link banner at the top and bottom of each page). Changed Returns SUCCEED (0) if successful; otherwise FAIL (-1). to read Returns a non-negative value if successful; otherwise returns a negative value. and several derived changes where circumstances differred only slightly. Minor copy edits throughout. RM_H5.html Corrected H5open "Purpose" statement. RM_H5A.html Changed H5Aget_name return type to hssize_t. RM_H5F.html H5Fflush Added scope parameter. Added H5Freopen. RM_H5Front.html Reordered listing of interfaces to alphabetical order (H5, H5A, H5D, ...) Added H5I, H5R, and H5RA. RM_H5G.html H5Gopen Edited "Description." H5Gget_objinfo Added named datatype to list of valid values for loc_id. RM_H5I.html Identifier Interface New section. RM_H5P.html Added H5Pset_fill_value and H5Pget_fill_value. Several minor copy edits. RM_H5R.html Reference Interface New section. H5RA.html Essentially a new section. It was in the tree previously, but it did not actually have content. RM_H5S.html Changed H5Sget_select_npoints return type to hssize_t. Tools.html Updated h5dump documentation.
1998-10-30 06:13:17 +08:00
<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
[svn-r830] ====== Intro ====== H5.intro.html Major rewrite to Groups section. New Example 7 (groups). Added TOC and requisite links. Numbered sections. Labelled figures and centered those that were not. Fixed table formatting. =========== User Guide =========== H5.user.html Linked in Chunking.html. Linked in References.html. Linked in DDL.html. Chunking.html Minor edits. DDL.html References.html New documents. Datatypes.html Added "R Reference" to base name description and "H5T_STD_ROBJ -- Reference to an entire object in a file" to list of datatype names. Files.html H5Fflush Added scope parameter. Groups.html Removed references to "current working group." Removed H5Gpush, H5Gpop, and H5Gset functions. Removed note that H5Glink and H5Gunlink were not implemented. ================= Reference Manual ================= RM_*.html and Tools.html Updated Reference Manual internal cross-linking (the link banner at the top and bottom of each page). Changed Returns SUCCEED (0) if successful; otherwise FAIL (-1). to read Returns a non-negative value if successful; otherwise returns a negative value. and several derived changes where circumstances differred only slightly. Minor copy edits throughout. RM_H5.html Corrected H5open "Purpose" statement. RM_H5A.html Changed H5Aget_name return type to hssize_t. RM_H5F.html H5Fflush Added scope parameter. Added H5Freopen. RM_H5Front.html Reordered listing of interfaces to alphabetical order (H5, H5A, H5D, ...) Added H5I, H5R, and H5RA. RM_H5G.html H5Gopen Edited "Description." H5Gget_objinfo Added named datatype to list of valid values for loc_id. RM_H5I.html Identifier Interface New section. RM_H5P.html Added H5Pset_fill_value and H5Pget_fill_value. Several minor copy edits. RM_H5R.html Reference Interface New section. H5RA.html Essentially a new section. It was in the tree previously, but it did not actually have content. RM_H5S.html Changed H5Sget_select_npoints return type to hssize_t. Tools.html Updated h5dump documentation.
1998-10-30 06:13:17 +08:00
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
[svn-r830] ====== Intro ====== H5.intro.html Major rewrite to Groups section. New Example 7 (groups). Added TOC and requisite links. Numbered sections. Labelled figures and centered those that were not. Fixed table formatting. =========== User Guide =========== H5.user.html Linked in Chunking.html. Linked in References.html. Linked in DDL.html. Chunking.html Minor edits. DDL.html References.html New documents. Datatypes.html Added "R Reference" to base name description and "H5T_STD_ROBJ -- Reference to an entire object in a file" to list of datatype names. Files.html H5Fflush Added scope parameter. Groups.html Removed references to "current working group." Removed H5Gpush, H5Gpop, and H5Gset functions. Removed note that H5Glink and H5Gunlink were not implemented. ================= Reference Manual ================= RM_*.html and Tools.html Updated Reference Manual internal cross-linking (the link banner at the top and bottom of each page). Changed Returns SUCCEED (0) if successful; otherwise FAIL (-1). to read Returns a non-negative value if successful; otherwise returns a negative value. and several derived changes where circumstances differred only slightly. Minor copy edits throughout. RM_H5.html Corrected H5open "Purpose" statement. RM_H5A.html Changed H5Aget_name return type to hssize_t. RM_H5F.html H5Fflush Added scope parameter. Added H5Freopen. RM_H5Front.html Reordered listing of interfaces to alphabetical order (H5, H5A, H5D, ...) Added H5I, H5R, and H5RA. RM_H5G.html H5Gopen Edited "Description." H5Gget_objinfo Added named datatype to list of valid values for loc_id. RM_H5I.html Identifier Interface New section. RM_H5P.html Added H5Pset_fill_value and H5Pget_fill_value. Several minor copy edits. RM_H5R.html Reference Interface New section. H5RA.html Essentially a new section. It was in the tree previously, but it did not actually have content. RM_H5S.html Changed H5Sget_select_npoints return type to hssize_t. Tools.html Updated h5dump documentation.
1998-10-30 06:13:17 +08:00
closed).
</dl>
[svn-r830] ====== Intro ====== H5.intro.html Major rewrite to Groups section. New Example 7 (groups). Added TOC and requisite links. Numbered sections. Labelled figures and centered those that were not. Fixed table formatting. =========== User Guide =========== H5.user.html Linked in Chunking.html. Linked in References.html. Linked in DDL.html. Chunking.html Minor edits. DDL.html References.html New documents. Datatypes.html Added "R Reference" to base name description and "H5T_STD_ROBJ -- Reference to an entire object in a file" to list of datatype names. Files.html H5Fflush Added scope parameter. Groups.html Removed references to "current working group." Removed H5Gpush, H5Gpop, and H5Gset functions. Removed note that H5Glink and H5Gunlink were not implemented. ================= Reference Manual ================= RM_*.html and Tools.html Updated Reference Manual internal cross-linking (the link banner at the top and bottom of each page). Changed Returns SUCCEED (0) if successful; otherwise FAIL (-1). to read Returns a non-negative value if successful; otherwise returns a negative value. and several derived changes where circumstances differred only slightly. Minor copy edits throughout. RM_H5.html Corrected H5open "Purpose" statement. RM_H5A.html Changed H5Aget_name return type to hssize_t. RM_H5F.html H5Fflush Added scope parameter. Added H5Freopen. RM_H5Front.html Reordered listing of interfaces to alphabetical order (H5, H5A, H5D, ...) Added H5I, H5R, and H5RA. RM_H5G.html H5Gopen Edited "Description." H5Gget_objinfo Added named datatype to list of valid values for loc_id. RM_H5I.html Identifier Interface New section. RM_H5P.html Added H5Pset_fill_value and H5Pget_fill_value. Several minor copy edits. RM_H5R.html Reference Interface New section. H5RA.html Essentially a new section. It was in the tree previously, but it did not actually have content. RM_H5S.html Changed H5Sget_select_npoints return type to hssize_t. Tools.html Updated h5dump documentation.
1998-10-30 06:13:17 +08:00
<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
[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
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>
<a name="H5GUnlinkToCorrupt">
<h2>6. Unlinking Datasets with H5Gmove and H5Gunlink</h2>
</a>
<p>Exercise caution in the use of <code>H5Gmove</code> and
<code>H5Gunlink</code>.
<p>Note that <code>H5Gmove</code> and <code>H5Gunlink</code>
each include a step that unlinks pointers to a set or group.
If the link that is removed is on the only path leading
to a dataset or group, that dataset or group will become
inaccessible in the file.
<p>Consider the following example. Assume that the group
<code>group2</code> can only be accessed via the following path,
where <code>top_group</code> is a member of the file's root group:
<pre>
<code>/top_group/group1/group2/</code> </pre>
Using <code>H5Gmove</code>, <code>top_group</code> is renamed
to be a member of <code>group2</code>. At this point, since
<code>top_group</code> was the only route from the root group
to <code>group1</code>, there is no longer a path by which
one can access <code>group1</code>, <code>group2</code>, or
any member datasets.
<code>top_group</code> and any member datasets have also
become inaccessible.</p>
[svn-r985] Checking in changes from "HDF5 Release 1.0" CVS branch that have not yet 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.
1998-12-22 06:52:56 +08:00
<!-- #BeginLibraryItem "/ed_libs/NavBar_UG.lbi" --><hr>
[svn-r985] Checking in changes from "HDF5 Release 1.0" CVS branch that have not yet 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.
1998-12-22 06:52:56 +08:00
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
<a href="index.html">HDF5 documents and links</a>&nbsp;<br>
<a href="H5.intro.html">Introduction to HDF5</a>&nbsp;<br>
<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;<br>
<!--
<a href="Glossary.html">Glossary</a><br>
-->
[svn-r985] Checking in changes from "HDF5 Release 1.0" CVS branch that have not yet 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.
1998-12-22 06:52:56 +08:00
</td>
<td valign=top align=right>
And in this document, the
<a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a>&nbsp;&nbsp;&nbsp;&nbsp;
<br>
<a href="Files.html">Files</a>&nbsp;&nbsp;
<a href="Datasets.html">Datasets</a>&nbsp;&nbsp;
<a href="Datatypes.html">Datatypes</a>&nbsp;&nbsp;
<a href="Dataspaces.html">Dataspaces</a>&nbsp;&nbsp;
<a href="Groups.html">Groups</a>&nbsp;&nbsp;
<br>
<a href="References.html">References</a>&nbsp;&nbsp;
<a href="Attributes.html">Attributes</a>&nbsp;&nbsp;
<a href="Properties.html">Property Lists</a>&nbsp;&nbsp;
<a href="Errors.html">Error Handling</a>&nbsp;&nbsp;
<br>
<a href="Filters.html">Filters</a>&nbsp;&nbsp;
<a href="Caching.html">Caching</a>&nbsp;&nbsp;
<a href="Chunking.html">Chunking</a>&nbsp;&nbsp;
<a href="MountingFiles.html">Mounting Files</a>&nbsp;&nbsp;
<br>
<a href="Performance.html">Performance</a>&nbsp;&nbsp;
<a href="Debugging.html">Debugging</a>&nbsp;&nbsp;
<a href="Environment.html">Environment</a>&nbsp;&nbsp;
<a href="ddl.html">DDL</a>&nbsp;&nbsp;
[svn-r985] Checking in changes from "HDF5 Release 1.0" CVS branch that have not yet 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.
1998-12-22 06:52:56 +08:00
</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.6.0, July 2003
</address><!-- #EndLibraryItem --><!-- Created: Tue Jan 27 09:11:27 EST 1998 -->
<!-- hhmts start -->
Last modified: 1 November 2000
<!-- hhmts end -->
</body>
</html>