summaryrefslogtreecommitdiffstats
path: root/doc/html/MountingFiles.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/html/MountingFiles.html')
-rw-r--r--doc/html/MountingFiles.html427
1 files changed, 0 insertions, 427 deletions
diff --git a/doc/html/MountingFiles.html b/doc/html/MountingFiles.html
deleted file mode 100644
index 16f9115..0000000
--- a/doc/html/MountingFiles.html
+++ /dev/null
@@ -1,427 +0,0 @@
-<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>&nbsp;<br>
- <a href="H5.intro.html">Introduction to HDF5</a>&nbsp;<br>
- <a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;<br>
- <a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User's Guide for Release 1.6</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 from Release 1.4.5:</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;
- <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>
-<!-- #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>&nbsp;<br>
- <a href="H5.intro.html">Introduction to HDF5</a>&nbsp;<br>
- <a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;<br>
- <a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User's Guide for Release 1.6</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 from Release 1.4.5:</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;
- <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>
-<!-- #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>