mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-01-30 15:32:37 +08:00
fd05f98e9e
Purpose:
Marking files for "Release 1.4, February 2001."
Description:
Across doc files
Updating "Describes HDF5 Release..." entry to "Describes
HDF5 Release 1.4, February 2001."
Copyright.html: Added 2001 to years copyrighted.
index.html: Changed header to Release 1.4 (from 1.4 Beta)
Platforms tested:
IE 5
416 lines
14 KiB
HTML
416 lines
14 KiB
HTML
<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>
|