mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-12-09 07:32:32 +08:00
a901d24a8b
Purpose:
Renamed old "HDF5 User's Guide" as "HDF5 User's Guide, Release 1.4.5".
Added navigation bar link to new user's guide on HDF server.
Changed release tag line (in old UG only) back to
"Describes HDF5 Release 1.4.5, February 200 3"
Platforms tested:
IE 5
428 lines
15 KiB
HTML
428 lines
15 KiB
HTML
<html>
|
|
<head>
|
|
<title>Mounting Files</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>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>
|
|
|
|
|
|
<!-- #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: Spring 1999 -->
|
|
<!-- hhmts start -->
|
|
Last modified: 14 October 1999
|
|
<!-- hhmts end -->
|
|
|
|
</body>
|
|
</html>
|