LFS/PFS control block structure

In the LFS/PFS model that is used in z/OS UNIX, each active file system object is represented in the LFS and PFS by its own control blocks or structures. These are called the vnode and inode, respectively. There is a one-to-one relationship between the LFS's vnode and the PFS's inode. They effectively point to each other across the interface, although neither ever directly refers to the other's fields.

Porting note

Such terms as "build the inode", as used in this topic, mean "construct the in-storage representation of a file". This does not imply anything about the file representation as it is stored on disk.

There is only one vnode-inode pair for each data object in the system, no matter how many links there are to the object (for file objects), or how many users may be accessing the object. Users who access a vnode through the LFS must be accessing the same data object through the PFS.

Token_structure: A difference between the z/OS UNIX PFS interface and other implementations is that the vnode is not directly addressable by the PFS during a vnode operation. A Token_structure is presented on all calls as a vnode surrogate.

The Token_structure contains the following 8-byte PFS tokens:

Initialization token, returned from the PFS_Init routine during PFS activation. This token usually contains the address of the PFS anchor block.
Mount token, returned from the vfs_mount or vfs_network operation for the file system that is related to the current call. This token usually contains the address of the PFS mount block.
File token, originally passed by the PFS to osi_getvnode when the file's vnode-inode pair was created. This token usually contains the address of the PFS file block—that is, the inode.

For a vnode operation, Token_structure contains all three tokens; for a VFS operation, it contains only the initialization and mount tokens.

See the TOKSTR typedef in Interface structures for C language servers and clients for the mapping of Token_structure.

Porting note

The file token within Token_structure is a copy of the "private data" area in the vnode. If a PFS expects a vnode structure as an input parameter, but does not refer to any vnode fields other than the PFS's private data pointer, the subfields within the program's vnode structure can be rearranged so that the pointer's offset matches that used in Token_structure. In this way, the PFS code that refers to this field will pick up the correct value when it is recompiled, and does not have to be changed.

Token_structure is transient; it lives only for the duration of a single call.

Figure 1. The LFS/PFS control block structure The GFS-PFS anchor pair is created at PFS initialization time, while the VFS-MNT pair is created during a file system mount or socket network activation.

The GFS-PFS anchor pair is created at PFS initialization time, while the VFS-MNT pair is created during a file system mount or socket network activation.

The control block relationships described so far are illustrated in Figure 1. Reading from left to right, in the order they are created:

The GFS-PFS_anchor pair is created at PFS initialization time and exists as long as the PFS does. Pfsa@ represents the PFS token saved by the LFS.
The VFS-MNT pair is created during a file system mount or socket network activation, and exists until the file system is unmounted, or forever, respectively. Mnt@ represents the PFS token saved by the LFS from that operation.
The vnode-inode pair is created during lookup and creation operations, which are explained in Creating, referring to, and inactivating file vnodes and Creating, referring to, and closing socket vnodes.
Each of these control blocks contains the other's token for the file object. The vnode's Inod@ token is placed in Token_structure as input for a call to the PFS, and an inode's Vnod@ token is returned by the PFS from any call that has a vnode as output.
Token_structure contains all three PFS tokens, and spans the LFS-PFS interface as the first parameter of each call.