Mounting Files

Purpose

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.

Definitions

If file child is mounted on file parent at group /mnt in parent then the contents of the root group of child will appear in the group /mnt of parent. The group /mnt is called the mount point of the child in the parent.

Common Features

These features are common to both mounting schemes.

The previous contents of /mnt in parent is temporarily hidden. If objects in that group had names from other groups then the objects will still be visible by those other names.
The mount point is actually an OID (not a name) so if there are other names besides /mnt for that group then the root group of the child will be visible in all those names.
At most one file can be mounted per mount point but a parent can have any number of mounted children.
Name lookups will entail a search through the mount table at each stage of the lookup. The search will be O(log N) where N is the number of children mounted on that file.
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.
Mounting a child may hide mount points that exist below the child's mount point, but it does not otherwise affect mounted files.
Hard links cannot cross file boundaries. An object cannot be moved or renamed with H5Gmove() in such a way that the new location would be in a different file than the original location.
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, etc.
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.
Current working groups that point into a child will remain open and usable even after the child has been unmounted and/or closed.
Datasets that share a committed datatype must reside in the same file as the datatype.

Contrasting Features

Tree	Graph
The set of mount-related files makes a tree.	The set of mount-related files makes a directed graph.
A file can be mounted at only one mount point.	A file can be mounted at any number of mount points.
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.	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.
Closing a child causes it to be unmounted from the parent.	Closing a child has no effect on its relationship with the parent. One can continue to access the child contents through the parent.
Closing the parent recursively unmounts and closes all mounted children.	Closing the parent unmounts all children but does not close them or unmount their children.
The current working group functions `H5Gset()`, `H5Gpush()`, and `H5Gpop()` operate on the root of the mount tree.	The current working group functions operate on the file specified by their first argument.
Absolute name lookups (like for `H5Dopen()`) are always performed with respect to the root of the mount tree.	Absolute name lookups are performed with respect to the file specified by the first argument.
Relative name lookups (like for `H5Dopen()`) are always performed with respect to the specified group or the current working group of the root of the mount tree.	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.
Mounting a child temporarily hides the current working group stack for that child	Mounting a child has no effect on its current working group stack.
Calling `H5Fflush()` will flush all files of the mount tree regardless of which file is specified as the argument.	Calling `H5Fflush()` will flush only the specified file.

Functions

herr_t H5Fmount(hid_t loc, const char *name, hid_t child, hid_t plist)

The file child is mounted at the specified location in the parent. The loc and name specify the mount point, a group in the parent. The plist argument is an optional mount property list. The call will fail if some file is already mounted on the specified group.

Tree	Graph
The call will fail if the child is already mounted elsewhere.	A child can be mounted at numerous mount points.
The call will fail if the child is an ancestor of the parent.	The mount graph is allowed to have cycles.
Subsequently closing the child will cause it to be unmounted from the parent.	Closing the child has no effect on its mount relationship with the parent.

herr_t H5Funmount(hid_t loc, const char *name)

Any file mounted at the group specified by loc and name is unmounted. The child is not closed. This function fails if no child is mounted at the specified point.

hid_t H5Pcreate(H5P_MOUNT)

Creates and returns a new mount property list initialized with default values.

herr_t H5Pset_symlink_locality(hid_t plist, H5G_symlink_t locality)

herr_t H5Pget_symlink_locality(hid_t plist, H5G_symlink_t *locality)

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 H5G_SYMLINK_LOCAL or H5G_SYMLINK_GLOBAL (the default).

hid_t H5Freopen(hid_t file)

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.

Tree	Graph
The new handle is not mounted but the old handle continues to be mounted.	The new handle is mounted at the same location(s) as the original handle.

Example

A file eos.h5 contains data which is constant for all problems. The output of a particular physics application is dumped into data1.h5 and data2.h5 and the physics expects various constants from eos.h5 in the eos group of the two data files. Instead of copying the contents of eos.h5 into every physics output file we simply mount eos.h5 as a read-only child of data1.h5 and data2.h5.

Tree

/* 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);

Graph

/* 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);

HDF5 documents and links
Introduction to HDF5
HDF5 Reference Manual
HDF5 User's Guide for Release 1.6

THG Help Desk:

Describes HDF5 Release 1.4.5, February 2003

Last modified: 14 October 1999