vfs_recovery — Recover resources at end-of-memory

Function

The vfs_recovery operation permits a PFS to recover resources when a user address space enters end-of-memory processing while a request to that PFS is active.

Environment on entry and exit

See Environment for PFS operations.

Input parameter format

vfs_recovery  (Token_structure,
               OSI_structure,
               Audit_structure,
               Recovery_area,
               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.

Recovery_area

Supplied parameter

Type:: String
Length:: 8 bytes

A copy of the Recovery_area that was filled in by the PFS during the operation that was interrupted. This area is mapped by osirtoken in BPXYPFSI (see Interface structures for C language servers and clients).

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vfs_recovery operation 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_recovery operation stores the return code. The vfs_recovery operation 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.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vfs_recovery operation stores the reason code. The vfs_recovery operation 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_recovery processing

Recovery considerations provides an overview of recovery processing, and discusses the flow for vfs_recovery in particular.

Specific processing notes

When an active request to the PFS is interrupted in a situation where normal ESTAE processing is bypassed by MVS™, the PFS may have resources, such as storage and locks, that are left in a state that will cause problems for other users.

To allow the PFS a chance to clean up if this should happen, a Recovery_area is passed on every operation, through the osi_rtokptr pointer in the OSI_structure, where the PFS can record its resources or store a pointer to a recovery block. Any information that is stored in this area by the PFS during an operation is passed back to the PFS via the Recovery_area parameter of vfs_recovery if the operation is interrupted by end-of-memory for the user address space.

The OSI Work Area and the Pre-initialized C Environment Stack, if used, are still addressable and left as they were at the time of the abend. These areas can be used to hold a recovery block whose address is placed in the Recovery_area. The vfs_recovery operation is invoked with its own areas like any other operation.

Refer also to vn_recovery — Recover resources after an abend, which is the operation that is invoked during normal ESTAE processing.

There is no EOM recovery for the vfs_recovery operation itself. The operation is invoked with osi_rtokptr pointing to a new recovery area that can be used for standard PFS abend recovery; that is, with vn_recovery.

The PFS is not called if the file system has been unmounted between the original vnode operation and the running of the EOM resource manager. This can only happen if the user was in a signal-enabled wait at the time the address space was terminated. It is expected that the PFS has cleaned up all its file-system-related resources during vfs_umount.

See also the OSI and osirtoken structures in Interface structures for C language servers and clients.

The state of any file-level objects that may have been involved with the interrupted operation is unknown at the time vfs_recovery is invoked.

Serialization provided by the LFS

The vfs_recovery operation is invoked with a shared latch held on the file system represented by the token_structure.

Any file-level objects that may have been involved with the interrupted operation are not serialized.

Security calls to be made by the PFS

None.