summaryrefslogtreecommitdiffstats
path: root/doc/html/MountingFiles.html
blob: 465782747780094f52a96aa5ef152a06c729dbcb (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
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>&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;
      <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;
      Mounting Files&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>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>&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;
      <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;
      Mounting Files&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: Spring 1999 -->
<!-- hhmts start -->
Last modified:  14 October 1999
<!-- hhmts end -->

<br>
Describes HDF5 Release 1.4, February 2001


  </body>
</html>