vfs_unmount — Unmount a file system

Function

The vfs_unmount operation unmounts a file system and inactivates the root vnode.

Environment on entry and exit

Input parameter format

vfs_umount  (Token_structure,
             OSI_structure,
             Audit_structure,
             Unmount_options,
             Return_value,
             Return_code,
             Reason_code)

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.

Refer to 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.

Unmount_options

Supplied parameter

Type:: Integer
Length:: Fullword

An area that is used to pass the options that are to be used to unmount the file system that is specified in Token_structure. The values for this parameter are defined in the stat.h header. For a description of this header, see z/OS XL C/C++ Runtime Library Reference.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vfs_unmount 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_unmount service stores the return code. The vfs_unmount service returns Return_code only if Return_value is -1. For a complete list of supported return code values, see z/OS UNIX System Services Messages and Codes.

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

Return_code	Explanation
EIO	An I/O error occurred while the file system was being unmounted.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vfs_unmount service stores the reason code. The vfs_unmount 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_unmount processing
Unmounting file systems provides an overview of file system unmount processing.
Specific processing notes
The PFS cannot issue a signal-enabled wait during unmount processing. Waiting and posting provides an overview of wait and post processing.

It is not necessary for the PFS to perform security checking during unmount processing, because the LFS has already performed all necessary checking.

A file system that is being mounted asynchronously may be unmounted before the mount process completes. Consequently, if the PFS returns only the vnode_token on the second call to vfs_mount, vfs_unmount must be capable of successfully unmounting a file system without reference to its inode token.

If vfs_umount is being invoked for a remount (MT_REMOUNT or OSI_REMOUNT), the PFS receives a vfs_mount for the same file system as soon as the vfs_umount completes. This is followed by vfs_vgets to recreate the vnode-inode pairs that were active at the time of the unmount operation. If a file was open at the time of the remount, the vnode's open counter is reestablished through calls to vn_open.

The PFS does not have to do anything special for remount; however, for performance reasons, it may want to maintain some resources at vfs_umount in anticipation of reusing them for the next vfs_mount. Socket or RPC sessions are examples of resources that might be worth maintaining.

If the PFS cannot support remount, it should reject the vfs_umount request. One reason for not supporting remount is that the PFS would not complete the following vfs_mount synchronously.
Serialization provided by the LFS
The vfs_unmount operation is invoked with an exclusive latch held on the file system, to ensure that no other operations are attempted upon the file system that is being unmounted. In addition, the LFS ensures that all mount and unmount operations are serialized.
Security calls to be made by the PFS: None.

Function

Environment on entry and exit

Input parameter format

Parameters

Implementation notes

Related services