NFS file handles

As mentioned before, the VFS callable services API is designed to be used with NFS, and NFS uses file handles to represent files. Two advantages of NFS file handles over pathnames are that they are a smaller fixed length (usually 32 bytes long), and that they always refer to the same file object even if that object is renamed or if it is deleted and the pathname reused for another object. In the latter case, references to the file handle fail, but this is the desired result.

An NFS file handle contains two pieces of information that are needed to convert the handle back to a file. These are the file system in which the file resides and its identifier (FID) within that file system. The FID values, which are generated by PFSs that own the data, are unique within a file system, persistent, and never reused. File systems, however, do not have a persistent and dedicated identifier that can be used in an NFS file handle.

An NFS client expects file handles to be valid for as long as the corresponding VFS server object exists. To support their validity over system or VFS server restarts, the VFS server must maintain a disk file, or database, that retains some information about the NFS mounts that have been performed. With this database, the VFS server can create unique and persistent file system identifiers to be placed in the file handles along with the file's FID. This file system identifier is called a "mount key", and the following process makes it unique and persistent:

On each mount RPC, a unique "mount key" is generated. This can be, for example, an index into a mount table or a time stamp.
The mount key can be reused after the client issues an unmount RPC. Presumably the client will not be using old file handles from directories that it has unmounted.

The initial directory pathname from the RPC and the mount key are saved on disk. The file system name and directory FID are also saved.

A mount structure is built to hold the mount key and VFS token. With the mount key the VFS server is able to find the mount structure and extract the VFS token.
Each file handle that is constructed contains the file's FID and the mount key for the mount RPC under which the file resides.
Each time the VFS server is started, it reads the mount file and rebuilds the corresponding mount structures with their saved mount keys.
v_rpn() is called, with the saved path name, to get a new VFS token, which is saved in the new mount structure.

At this point the VFS server has re-created the mount state it had before the system was restarted, and it can field inbound RPCs and process their file handles.
With an old file handle the VFS server can find the new mount structure, since the mount key has not changed and the new VFS token is used on the subsequent call to v_get().

A mount RPC refers to a specific initial directory, which, when the RPC arrived, was known by the path name that is included with the RPC. That specific directory can be renamed or deleted and the path name reused for another directory. If this happens, the v_rpn() that is issued by a VFS server after it restarts yields the VFS token and FID of a different directory. In this case, the same file handle used by a client before and after the VFS server restart refers to two different objects!

To help detect this situation, v_rpn() returns additional information about the real mounted file system that the initial directory belongs to. This includes the FILESYSTEM name used on the real mount command. By saving this name and the FID of the initial directory, along with the path name and mount key, the VFS server can validate the output of v_rpn() after a restart.

After a restart v_rpn(), the old and new FIDs are compared to catch situations in which the path name has been reused within the same real file system. The old and new FILESYSTEM names are compared in order to catch instances in which the path name was reused across real file systems and happens to refer to an object with the same FID within the new file system. Getting the same FID is not so uncommon; because FIDs are usually generated sequentially, the local root of every real file system, for example, tends to have the same FID.

This scheme requires that the FILESYSTEM name not be reused for another file system, but this is somewhat easier to control. Generally, mount commands are issued only from the BPXPRMxx parmlib member that was used to start z/OS UNIX, or by a small set of people with special authorization. For HFS file systems, also, the FILESYSTEM name is the name of an MVS™ data set. Controls can be placed over who is able to rename or delete these data sets, and they cannot be renamed or deleted by anyone while they are mounted.