diff options
Diffstat (limited to 'doc/html/Groups.html')
| -rw-r--r-- | doc/html/Groups.html | 404 |
1 files changed, 0 insertions, 404 deletions
diff --git a/doc/html/Groups.html b/doc/html/Groups.html deleted file mode 100644 index 2941008..0000000 --- a/doc/html/Groups.html +++ /dev/null @@ -1,404 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<html> - <head> - <title>Group Interface (H5G)</title> - -<!-- #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> - - <body bgcolor="#FFFFFF"> - - -<!-- #BeginLibraryItem "/ed_libs/NavBar_UG.lbi" --><hr> -<center> -<table border=0 width=98%> -<tr><td valign=top align=left> - <a href="index.html">HDF5 documents and links</a> <br> - <a href="H5.intro.html">Introduction to HDF5</a> <br> - <a href="RM_H5Front.html">HDF5 Reference Manual</a> <br> - <a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User's Guide for Release 1.6</a> <br> - <!-- - <a href="Glossary.html">Glossary</a><br> - --> -</td> -<td valign=top align=right> - And in this document, the - <a href="H5.user.html"><strong>HDF5 User's Guide from Release 1.4.5:</strong></a> - <br> - <a href="Files.html">Files</a> - <a href="Datasets.html">Datasets</a> - <a href="Datatypes.html">Datatypes</a> - <a href="Dataspaces.html">Dataspaces</a> - <a href="Groups.html">Groups</a> - <br> - <a href="References.html">References</a> - <a href="Attributes.html">Attributes</a> - <a href="Properties.html">Property Lists</a> - <a href="Errors.html">Error Handling</a> - <br> - <a href="Filters.html">Filters</a> - <a href="Caching.html">Caching</a> - <a href="Chunking.html">Chunking</a> - <a href="MountingFiles.html">Mounting Files</a> - <br> - <a href="Performance.html">Performance</a> - <a href="Debugging.html">Debugging</a> - <a href="Environment.html">Environment</a> - <a href="ddl.html">DDL</a> -</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 - specified group. - Multiple consecutive slashes in a full name are treated as - single slashes and trailing slashes are not significant. A - special case is the name "/" (or equivalent) which refers to the - root group. - - <p>Functions which operate on names generally take a location - identifier which is either a file ID or a group ID and perform - the lookup with respect to that location. Some possibilities - are: - - <p> - <center> - <table border cellpadding=4> - <tr> - <th>Location Type</th> - <th>Object Name</th> - <th>Description</th> - </tr> - - <tr> - <td>File ID</td> - <td><code>/foo/bar</code></td> - <td>The object <code>bar</code> in group <code>foo</code> - in the root group.</td> - </tr> - - <tr> - <td>Group ID</td> - <td><code>/foo/bar</code></td> - <td>The object <code>bar</code> in group <code>foo</code> - in the root group of the file containing the specified - group. In other words, the group ID's only purpose is - to supply a file.</td> - </tr> - - <tr> - <td>File ID</td> - <td><code>/</code></td> - <td>The root group of the specified file.</td> - </tr> - - <tr> - <td>Group ID</td> - <td><code>/</code></td> - <td>The root group of the file containing the specified - group.</td> - </tr> - - <tr> - <td>File ID</td> - <td><code>foo/bar</code></td> - <td>The object <code>bar</code> in group <code>foo</code> - in the specified group.</td> - </tr> - - <tr> - <td>Group ID</td> - <td><code>foo/bar</code></td> - <td>The object <code>bar</code> in group <code>foo</code> - in the specified group.</td> - </tr> - - <tr> - <td>File ID</td> - <td><code>.</code></td> - <td>The root group of the file.</td> - </tr> - - <tr> - <td>Group ID</td> - <td><code>.</code></td> - <td>The specified group.</td> - </tr> - - <tr> - <td>Other ID</td> - <td><code>.</code></td> - <td>The specified object.</td> - </tr> - - </table> - </center> - - <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> - - <h2>4. Objects with Multiple Names</h2> - - <p>An object (including a group) can have more than one - name. Creating the object gives it the first name, and then - functions described here can be used to give it additional - names. The association between a name and the object is called - a <em>link</em> and HDF5 supports two types of links: a <em>hard - link</em> is a direct association between the name and the - object where both exist in a single HDF5 address space, and a - <em>soft link</em> is an indirect association. - - <p> - <center> - <img alt="Hard Link Example" src="group_p2.gif"> - </center> - - <p> - <center> - <img alt="Soft Link Example" src="group_p3.gif"> - </center> - - <dl> - <dt>Object Creation</dt> - <dd>The creation of an object creates a hard link which is - indistinguishable from other hard links that might be added - later. - - <br><br> - <dt><code>herr_t H5Glink (hid_t <em>file_id</em>, H5G_link_t - <em>link_type</em>, const char *<em>current_name</em>, - const char *<em>new_name</em>)</code> - <dd>Creates a new name for an object that has some current name - (possibly one of many names it currently has). If the - <em>link_type</em> is <code>H5G_LINK_HARD</code> then a new - hard link is created. Otherwise if <em>link_type</em> is - <code>H5T_LINK_SOFT</code> a soft link is created which is an - alias for the <em>current_name</em>. When creating a soft - link the object need not exist. This function returns zero - for success or negative for failure. - - <br><br> - <dt><code>herr_t H5Gunlink (hid_t <em>file_id</em>, const char - *<em>name</em>)</code> - <dd>This function removes an association between a name and an - object. Object headers keep track of how many hard links refer - to the object and when the hard link count reaches zero the - object can be removed from the file (but objects which are - open are not removed until all handles to the object are - closed). - </dl> - - <h2>5. Comments</h2> - - <p>Objects can have a comment associated with them. The comment - is set and queried with these two functions: - - <dl> - <dt><code>herr_t H5Gset_comment (hid_t <em>loc_id</em>, const - char *<em>name</em>, const char *<em>comment</em>)</code> - <dd>The previous comment (if any) for the specified object is - replace with a new comment. If the <em>comment</em> argument - is the empty string or a null pointer then the comment message - is removed from the object. Comments should be relatively - short, null-terminated, ASCII strings. - - <br><br> - <dt><code>herr_t H5Gget_comment (hid_t <em>loc_id</em>, const - char *<em>name</em>, size_t <em>bufsize</em>, char - *<em>comment</em>)</code> - <dd>The comment string for an object is returned through the - <em>comment</em> buffer. At most <em>bufsize</em> characters - including a null terminator are copied, and the result is - not null terminated if the comment is longer than the supplied - buffer. If an object doesn't have a comment then the empty - string is returned. - </dl> - - <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> - - -<!-- #BeginLibraryItem "/ed_libs/NavBar_UG.lbi" --><hr> -<center> -<table border=0 width=98%> -<tr><td valign=top align=left> - <a href="index.html">HDF5 documents and links</a> <br> - <a href="H5.intro.html">Introduction to HDF5</a> <br> - <a href="RM_H5Front.html">HDF5 Reference Manual</a> <br> - <a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User's Guide for Release 1.6</a> <br> - <!-- - <a href="Glossary.html">Glossary</a><br> - --> -</td> -<td valign=top align=right> - And in this document, the - <a href="H5.user.html"><strong>HDF5 User's Guide from Release 1.4.5:</strong></a> - <br> - <a href="Files.html">Files</a> - <a href="Datasets.html">Datasets</a> - <a href="Datatypes.html">Datatypes</a> - <a href="Dataspaces.html">Dataspaces</a> - <a href="Groups.html">Groups</a> - <br> - <a href="References.html">References</a> - <a href="Attributes.html">Attributes</a> - <a href="Properties.html">Property Lists</a> - <a href="Errors.html">Error Handling</a> - <br> - <a href="Filters.html">Filters</a> - <a href="Caching.html">Caching</a> - <a href="Chunking.html">Chunking</a> - <a href="MountingFiles.html">Mounting Files</a> - <br> - <a href="Performance.html">Performance</a> - <a href="Debugging.html">Debugging</a> - <a href="Environment.html">Environment</a> - <a href="ddl.html">DDL</a> -</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.4.5, February 2003 -</address><!-- #EndLibraryItem --><!-- Created: Tue Jan 27 09:11:27 EST 1998 --> -<!-- hhmts start --> -Last modified: 1 November 2000 -<!-- hhmts end --> - - -</body> -</html> |