diff options
Diffstat (limited to 'doc/html/MountingFiles.html')
| -rw-r--r-- | doc/html/MountingFiles.html | 419 |
1 files changed, 419 insertions, 0 deletions
diff --git a/doc/html/MountingFiles.html b/doc/html/MountingFiles.html new file mode 100644 index 0000000..5e35e74 --- /dev/null +++ b/doc/html/MountingFiles.html @@ -0,0 +1,419 @@ +<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> + <br> + <a href="Ragged.html">Ragged Arrays</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> + <br> + <a href="Ragged.html">Ragged Arrays</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 Beta, December 2000 + + + </body> +</html> |