HDF5 documents and links 
Introduction to HDF5 
HDF5 Reference Manual 
HDF5 User's Guide for Release 1.8 
And in this document, the HDF5 User's Guide from Release 1.4.5:    
Files   Datasets   Datatypes   Dataspaces   Groups  
References   Attributes   Property Lists   Error Handling  
Filters   Caching   Chunking   Mounting Files  
Performance   Debugging   Environment   DDL  

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.

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.8 
And in this document, the HDF5 User's Guide from Release 1.4.5:    
Files   Datasets   Datatypes   Dataspaces   Groups  
References   Attributes   Property Lists   Error Handling  
Filters   Caching   Chunking   Mounting Files  
Performance   Debugging   Environment   DDL  

THG Help Desk:
Describes HDF5 Release 1.4.5, February 2003
Last modified: 14 October 1999