Function

The vfs_mount operation activates a file system and returns the root directory vnode_token.

Environment on entry and exit

See Environment for PFS operations.

Parameters

Token_structure

Supplied parameter

Type:

TOKSTR

Length:

Specified by TOKSTR.ts_hdr.cblen.

The Token_structure represents the file system (VFS) that is being operated on. It contains the PFS's initialization token and mount token. Refer to LFS/PFS control block structure for a discussion of this structure, and to the TOKSTR typedef in BPXYPFSI in Interface structures for C language servers and clients for its mapping.

OSI_structure

Supplied and returned parameter

Type:

OSI

Length:

Specified by OSI.osi_hdr.cblen.

The OSI_structure contains information that is used by the OSI operations that may be called by the PFS. See OSI services for more information.

It also contains MVS-specific information that needs to be passed to the PFS, including SMF accounting fields, a work area, a recovery area, and an optional pointer to an output ATTR structure. For more details on the OSI structure, see The OSI structure.

This area is mapped by the OSI typedef in BPXYPFSI in Interface structures for C language servers and clients.

Audit_structure

Supplied parameter

Type:

CRED

Length:

Specified by CRED.cred_hdr.cblen.

The Audit_structure contains information that is used by the security product for access checks and auditing. It is passed to most SAF routines that are invoked by the PFS.

See Security responsibilities and considerations for a discussion of security processing, and to the CRED typedef in BPXYPFSI in Interface structures for C language servers and clients for the mapping of this structure.

Mount_table

Supplied and returned parameter

Type:

Structure

Length:

Specified by the MTAB.mtab_hdr.cblen field

An area that is used to pass the file system name, mount options, and PFS-specific parameters to the vfs_mount operation. This area is mapped by the MTAB typedef in the BPXYPFSI header file (see Interface structures for C language servers and clients).

Vnode_token

Returned parameter

Type:

Token

Length:

8 bytes

An area in which the vfs_mount service returns the vnode_token for the root directory of the mounted file system.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

A fullword in which the vfs_mount service returns the results of the operation, as one of the following:

Return_value

Meaning

-1

The operation was not successful. The Return_code and Reason_Code values must be filled in by the PFS when Return_value is -1.

0

The operation was successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

A fullword in which the vfs_mount service stores the return code. The vfs_mount service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of supported return code values.

The vfs_mount operation should support at least the following error value:

Return_code	Explanation
EEXIST	A file system with the same name has already been mounted.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

A fullword in which the vfs_mount service stores the reason code. The vfs_mount service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. These reason codes are documented by the PFS.

Implementation notes

Overview of vfs_mount processing

Mounting file systems provides an overview of file system mount processing.

Specific processing notes

• The PFS is responsible for the following fields:

  token_structure.ts_mount

  The PFS should fill in this field with a token that it can use to locate the PFS structures that are associated with the mounted file system. On subsequent calls for files within this file system, the token_structure value contains the token set here by the PFS.

  MTAB.mt_filesys or MTAB.mt_ddname

  On entry to the PFS, the field MTAB.mt_filesys contains either the blank padded file system name or nulls. On a successful return, if this field is not nulls and it represents an MVS™ data set name, the field MTAB.mt_ddname should be filled in by the PFS with the dynamically allocated ddname.

  If the field MTAB.mt_filesys is nulls on entry to the PFS, the field MTAB.mt_ddname contains the ddname of an allocated MVS data set for the file system. On a successful return, the field MTAB.mt_filesys should be filled in by the PFS with the MVS data set name that is specified on the DD statement.

  MTAB.mt_rwmntclient

  The read/write sysplex-awareness of file systems is typically determined by the PfsiRWMntClient (or PfsiRWMntSysplex) that the PFS sets during its initialization. A PfsiRWMntClient (or PfsiRWMntSysplex) of 0 typically indicates that the PFS is sysplex-aware for all read/write mounts, and a PfsiRWMntClient (or PfsiRWMntSysplex) of 1 typically indicates that PFS is sysplex-unaware for all read/write mounts. However, if a PFS wants to mount certain file systems as read/write sysplex-aware and other file systems as read/write sysplex-unaware, it can do this by setting the output MTAB.mt_rwmntclient on the primary owner mount, to indicate the read-write sysplex-awareness of a particular file system. An output MTAB.mt_rwmntclient of 0 indicates read/write sysplex-aware, and an output MTAB.mt_rwmntclient of 1 indicates read/write sysplex-unaware.

  The output MTAB.mt_rwmntclient is ignored for network PFSes.

  MTAB.mt_disablella

  The LLA (lookup lookaside) enablement of file systems is typically determined by the PfsiDisableLLA that the PFS sets during its initialization. The PfsiDisableLLA typically indicates whether LLA is enabled or disabled for all file systems. However, if a PFS wants to disable LLA for certain file systems (those that are read/write sysplex-aware) and enable LLA for other file systems (those that are read/write sysplex-unaware), it can do this by setting MTAB.mt_disablella as output on the primary owner mount. An output MTAB.mt_disablella of 0 indicates that the LFS should enable LLA, and an output MTAB.mt_disablella of 1 indicates that the LFS should disable LLA.

  The output MTAB.mt_disablella is ignored for network PFSes.

  MTAB.mt_samemode

  If MTAB.mt_samemode is set by the LFS on input for an owner mount, then the read/write-awareness and LLA for this file system must not be changed by the PFS. The LFS passes the MTAB.mt_rwmntclient and MTAB.mt_disablella as input to indicate the read/write-awareness and LLA-enablement for the file system. MTAB.mt_samemode is set for certain operations where the read/write sysplex-awareness should not be changed by the PFS, like for the vfs_mount on the owner for a samemode remount. Only PFSes that would set the output MTAB.mt_rwmntclient and/or MTAB.mt_disablella need to check the input MTAB.mt_samemode bit.

  If every file in this file system has the same values, the PFS is responsible for filling in the MTAB with the following pathconf values (see the IEEE POSIX 1003.1 specification for further details):

  MTAB.mt_linkmax

  LINK_MAX

  MTAB.mt_namemax

  NAME_MAX

  MTAB.mt_notrunc

  POSIX_NO_TRUNC

  MTAB.mt_chownrstd

  POSIX_CHOWN_RESTRICTED

  Alternatively, the PFS may meet this responsibility by supporting vn_pathconf.

• The PFS must not issue a signal-enabled wait under the thread invoking vfs_mount.
• Waiting and posting provides an overview of wait and post processing.
• If the mount is to be completed asynchronously:
  • The PFS must set MTAB.mt_asynchmount on before returning to the LFS. The LFS in turn sets MTAB.mt_asynchmount on before calling the PFS for the second call to vfs_mount.
  • When the mount operation has completed, the PFS indicates this to the LFS by calling osi_mountstatus.
  • The vnode_token must be returned on at least one of the calls to vfs_mount. However, if the PFS chooses to return a nonzero vnode_token on each call, it must be the same token.
  • If asynchronous mount processing in the PFS fails, the PFS should call osi_mountstatus to drive the second call to vfs_mount. When called by the LFS to complete the mount, the PFS should then return the error to the LFS, which deletes all references to the incompletely mounted file system. No call to vfs_umount results.
  • If MTAB.mt_synchonly is set on in the Mount_table, vfs_mount must either complete the mount synchronously or reject the request, returning EINVAL. MTAB.mt_synchonly is always set on for the system root and for mounts that result from MOUNT statements in BPXPRMxx that specify DDNAME.
  • Vfs operations, such as vfs_umount and vfs_statfs, may need to be handled during an asynchronous mount.
• It is not necessary for the PFS to perform security checking during mount processing, because the LFS has already performed all necessary checking.
• The PFS returns an aggregate name, if it has one, from the vfs_mount operation. If mt_aggnameptr is not zero, it points to mt_aggname, which is a 45-byte area where the PFS can put the aggregate name. If the PFS may run on an earlier release, it should test for mt_hdr.cblen > 0x80 before it tests mt_aggnameptr. If read-only mounts of file systems with the same aggregate name should be function shipped to the owning system rather than locally mounted, mt_aggattachrw should be turned on. If subsequent recovery of this mount should not attempt to attach the aggregate before issuing the vfs_mount, mt_agghfscomp should be turned on.

Serialization provided by the LFS

The vfs_mount operation is invoked with an exclusive latch held on the file system, to ensure that no other operations are attempted upon the file system being mounted. In addition, the LFS ensures that all vfs_mount and vfs_umount calls are serialized.

Note: However, if the mount is asynchronous, there is a time between the start and the end of the mount in which the latch is not held.

Security calls to be made by the PFS

None.

Related services

• vfs_unmount — Unmount a file system
• vn_pathconf — Determine configurable pathname values
• osi_getvnode — Get or return a vnode
• osi_ctl — Pass control information to the kernel
• osi_wait — Wait for an event to occur