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
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
|
<html>
<head>
<title>Mounting Files</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> <br>
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
<a href="index.html">Other HDF5 documents and links</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:</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>
Mounting Files
<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>
<h1>Mounting Files</h1>
<h2>Purpose</h2>
<p>This document contrasts two methods for mounting an hdf5 file
on another hdf5 file: the case where the relationship between
files is a tree and the case where it's a graph. The tree case
simplifies current working group functions and allows symbolic
links to point into ancestor files whereas the graph case is
more consistent with the organization of groups within a
particular file.
<h2>Definitions</h2>
<p>If file <code>child</code> is mounted on file
<code>parent</code> at group <code>/mnt</code> in
<code>parent</code> then the contents of the root group of
<code>child</code> will appear in the group <code>/mnt</code> of
<code>parent</code>. The group <code>/mnt</code> is called the
<em>mount point</em> of the child in the parent.
<h2>Common Features</h2>
<p>These features are common to both mounting schemes.
<ul>
<li>The previous contents of <code>/mnt</code> in
<code>parent</code> is temporarily hidden. If objects in that
group had names from other groups then the objects will still
be visible by those other names.
<li>The mount point is actually an OID (not a name) so if there
are other names besides <code>/mnt</code> for that group then
the root group of the child will be visible in all those
names.
<li>At most one file can be mounted per mount point but a parent
can have any number of mounted children.
<li>Name lookups will entail a search through the mount table at
each stage of the lookup. The search will be O(log
<em>N</em>) where <em>N</em> is the number of children mounted
on that file.
<li>Files open for read-only can be mounted on other files that
are open for read-only. Mounting a file in no way changes the
contents of the file.
<li>Mounting a child may hide mount points that exist below the
child's mount point, but it does not otherwise affect mounted
files.
<li>Hard links cannot cross file boundaries. An object cannot
be moved or renamed with <code>H5Gmove()</code> in such a way
that the new location would be in a different file than the
original location.
<li>The child can be accessed in a manner different from the
parent. For instance, a read-write child in a read-only
parent, a parallel child in a serial parent, <em>etc</em>.
<li>If some object in the child is open and the child is
unmounted and/or closed, the object will remain open and
accessible until explicitly closed. As in the mountless case,
the underlying UNIX file will be held open until all member
objects are closed.
<li>Current working groups that point into a child will remain
open and usable even after the child has been unmounted and/or
closed.
<li>Datasets that share a committed datatype must reside in the
same file as the datatype.
</ul>
<h2>Contrasting Features</h2>
<center>
<table border width="90%">
<tr>
<th width="50%">Tree</th>
<th width="50%">Graph</th>
</tr>
<tr valign=top>
<td>The set of mount-related files makes a tree.</td>
<td>The set of mount-related files makes a directed
graph.</td>
</tr>
<tr valign=top>
<td>A file can be mounted at only one mount point.</td>
<td>A file can be mounted at any number of mount points.</td>
</tr>
<tr valign=top>
<td>Symbolic links in the child that have a link value which
is an absolute name can be interpreted with respect to the
root group of either the child or the root of the mount
tree, a property which is determined when the child is
mounted.</td>
<td>Symbolic links in the child that have a link value which
is an absolute name are interpreted with respect to the
root group of the child.</td>
</tr>
<tr valign=top>
<td>Closing a child causes it to be unmounted from the
parent.</td>
<td>Closing a child has no effect on its relationship with
the parent. One can continue to access the child contents
through the parent.</td>
</tr>
<tr valign=top>
<td>Closing the parent recursively unmounts and closes all
mounted children.</td>
<td>Closing the parent unmounts all children but
does not close them or unmount their children.</td>
</tr>
<tr valign=top>
<td>The current working group functions
<code>H5Gset()</code>, <code>H5Gpush()</code>, and
<code>H5Gpop()</code> operate on the root of the mount
tree.</td>
<td>The current working group functions operate on the file
specified by their first argument.</td>
</tr>
<tr valign=top>
<td>Absolute name lookups (like for <code>H5Dopen()</code>)
are always performed with respect to the root of the mount
tree.</td>
<td>Absolute name lookups are performed with respect to the
file specified by the first argument.</td>
</tr>
<tr valign=top>
<td>Relative name lookups (like for <code>H5Dopen()</code>)
are always performed with respect to the specified group
or the current working group of the root of the mount
tree.</td>
<td>Relative name lookups are always performed with respect
to the specified group or the current working group of the
file specified by the first argument.</td>
</tr>
<tr valign=top>
<td>Mounting a child temporarily hides the current working
group stack for that child</td>
<td>Mounting a child has no effect on its current working
group stack.</td>
</tr>
<tr valign=top>
<td>Calling <code>H5Fflush()</code> will flush all files of
the mount tree regardless of which file is specified as
the argument.</td>
<td>Calling <code>H5Fflush()</code> will flush only the
specified file.</td>
</tr>
</table>
</center>
<h2>Functions</h2>
<dl>
<dt><code>herr_t H5Fmount(hid_t <em>loc</em>, const char
*<em>name</em>, hid_t <em>child</em>, hid_t
<em>plist</em>)</code>
<dd>The file <em>child</em> is mounted at the specified location
in the parent. The <em>loc</em> and <em>name</em> specify the
mount point, a group in the parent. The <em>plist</em>
argument is an optional mount property list. The call will
fail if some file is already mounted on the specified group.
<table border>
<tr>
<th width="50%">Tree</th>
<th width="50%">Graph</th>
</tr>
<tr valign=top>
<td>The call will fail if the child is already mounted
elsewhere.</td>
<td>A child can be mounted at numerous mount points.</td>
</tr>
<tr valign=top>
<td>The call will fail if the child is an ancestor of the
parent.</td>
<td>The mount graph is allowed to have cycles.</td>
</tr>
<tr valign=top>
<td>Subsequently closing the child will cause it to be
unmounted from the parent.</td>
<td>Closing the child has no effect on its mount
relationship with the parent.</td>
</tr>
</table>
<br><br>
<dt><code>herr_t H5Funmount(hid_t <em>loc</em>, const char
*<em>name</em>)</code>
<dd>Any file mounted at the group specified by <em>loc</em> and
<em>name</em> is unmounted. The child is not closed. This
function fails if no child is mounted at the specified point.
<br><br>
<dt><code>hid_t H5Pcreate(H5P_MOUNT)</code>
<dd>Creates and returns a new mount property list initialized
with default values.
<br><br>
<dt><code>herr_t H5Pset_symlink_locality(hid_t <em>plist</em>,
H5G_symlink_t <em>locality</em>)</code>
<dt><code>herr_t H5Pget_symlink_locality(hid_t <em>plist</em>,
H5G_symlink_t *<em>locality</em>)</code>
<dd>These functions exist only for the tree scheme. They set or
query the property that determines whether symbolic links with
absolute name value in the child are looked up with respect to
the child or to the mount root. The possible values are
<code>H5G_SYMLINK_LOCAL</code> or
<code>H5G_SYMLINK_GLOBAL</code> (the default).
<br><br>
<dt><code>hid_t H5Freopen(hid_t <em>file</em>)</code>
<dd>A file handle is reopened, creating an additional file
handle. The new file handle refers to the same file but has an
empty current working group stack.
<table border>
<tr>
<th width="50%">Tree</th>
<th width="50%">Graph</th>
</tr>
<tr valign=top>
<td>The new handle is not mounted but the old handle
continues to be mounted.</td>
<td>The new handle is mounted at the same location(s) as
the original handle.</td>
</tr>
</table>
</dl>
<h2>Example</h2>
<p>A file <code>eos.h5</code> contains data which is constant for
all problems. The output of a particular physics application is
dumped into <code>data1.h5</code> and <code>data2.h5</code> and
the physics expects various constants from <code>eos.h5</code>
in the <code>eos</code> group of the two data files. Instead of
copying the contents of <code>eos.h5</code> into every physics
output file we simply mount <code>eos.h5</code> as a read-only
child of <code>data1.h5</code> and <code>data2.h5</code>.
<center>
<table border width="90%">
<tr><td><h3>Tree</h3><code><pre>
/* Create data1.h5 */
data1 = H5Fcreate("data1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
H5Gclose(H5Gcreate(data1, "/eos", 0));
H5Gset_comment(data1, "/eos", "EOS mount point");
/* Create data2.h5 */
data2 = H5Fcreate("data2.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
H5Gclose(H5Gcreate(data2, "/eos", 0));
H5Gset_comment(data2, "/eos", "EOS mount point");
/* Open eos.h5 and mount it in both files */
eos1 = H5Fopen("eos.h5", H5F_ACC_RDONLY, H5P_DEFAULT);
H5Fmount(data1, "/eos", eos1, H5P_DEFAULT);
eos2 = H5Freopen(eos1);
H5Fmount(data2, "/eos", eos2, H5P_DEFAULT);
... physics output ...
H5Fclose(data1);
H5Fclose(data2);
</pre></code></td></tr>
<tr><td><h3>Graph</h3><code><pre>
/* Create data1.h5 */
data1 = H5Fcreate("data1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
H5Gclose(H5Gcreate(data1, "/eos", 0));
H5Gset_comment(data1, "/eos", "EOS mount point");
/* Create data2.h5 */
data2 = H5Fcreate("data2.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
H5Gclose(H5Gcreate(data2, "/eos", 0));
H5Gset_comment(data2, "/eos", "EOS mount point");
/* Open eos.h5 and mount it in both files */
eos = H5Fopen("eos.h5", H5F_ACC_RDONLY, H5P_DEFAULT);
H5Fmount(data1, "/eos", eos, H5P_DEFAULT);
H5Fmount(data2, "/eos", eos, H5P_DEFAULT);
H5Fclose(eos);
... physics output ...
H5Fclose(data1);
H5Fclose(data2);
</pre></code></td></tr>
</table>
</center>
<hr>
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
<a href="H5.intro.html">Introduction to HDF5</a> <br>
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
<a href="index.html">Other HDF5 documents and links</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:</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>
Mounting Files
<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>
<address>
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
</address>
<!-- Created: Spring 1999 -->
<!-- hhmts start -->
Last modified: 14 October 1999
<!-- hhmts end -->
<br>
Describes HDF5 Release 1.4, February 2001
</body>
</html>
|
