summaryrefslogtreecommitdiffstats
path: root/doc/html/Groups.html
blob: c55cd2582295833f53a4f921c9f8166b9e63c3dc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
  <head>
    <title>Group Interface (H5G)</title>
  </head>

  <body bgcolor="#FFFFFF">


<hr>
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
   <a href="H5.intro.html">Introduction to HDF5</a>&nbsp;<br>
   <a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;<br>
   <a href="index.html">Other HDF5 documents and links</a>&nbsp;<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:</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;
      Groups&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;
</td></tr>
</table>
</center>
<hr>


    <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.


<hr>
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
   <a href="H5.intro.html">Introduction to HDF5</a>&nbsp;<br>
   <a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;<br>
   <a href="index.html">Other HDF5 documents and links</a>&nbsp;<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:</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;
      Groups&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;
</td></tr>
</table>
</center>



<hr>
<address>
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
</address>

<!-- Created: Tue Jan 27 09:11:27 EST 1998 -->
<!-- hhmts start -->
Last modified:  1 November 2000
<!-- hhmts end -->

<br>
Describes HDF5 Release 1.4, February 2001


  </body>
</html>