|
FunctionThe vn_close operation closes a
file or socket.
Input parameter formatvn_close (Token_structure,
OSI_structure,
Audit_structure,
Open_flags,
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 (vnode)
that is being operated on. It contains the PFS's initialization token,
mount token, and the file 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.
- Open_flags
- Supplied parameter
- Type:
- Bit
- Length:
- Fullword
A fullword containing the open flags that are associated
with this file. These flags are defined by fcntl.h.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
A fullword in which the vn_close 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 vn_close operation stores
the return code. The vn_close operation 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.
- Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
A fullword in which the vn_close operation stores
the reason code. The vn_close 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 vn_close processing
See Opening and closing files and first references to files for a discussion of close
processing.
See Creating, referring to, and closing socket vnodes for a discussion
of relevant socket processing.
For more information about the
semantics of this operation for a POSIX-conforming PFS, refer to the close() function
in the POSIX .1 standard (IEEE Std 1003.1-1990).
- Specific processing notes
- The Return_value parameter is preset to -1 before the PFS is called.
If the PFS program checks or ends abnormally during the vn_close operation
and the abend is percolated back to the LFS, the LFS uses the Return_value
to determine what to do next. If the Return_value is still -1, the
PFS is recalled with vn_close; otherwise it is not. Therefore, just
before the PFS reaches a point at which it would rather not be recalled
if it should end abnormally, it should zero out the Return_value.
- If the PFS supports vn_recovery, and vn_recovery returns control
information to direct the outcome of the original call, the rule is
overridden. That is, vn_close is not recalled if it appears that
vn_recovery has handled the problem, regardless of the value of Return_value.
- Although the Return_value, Return_code, and Reason_code values
are returned to the caller, the operation always succeeds in that
the user's file descriptor is freed and the vnode's open counter is
decremented, regardless of the Return_value.
- If vn_inactive is not supported by the PFS, the LFS will free
its vnode after the vn_close returns. If vn_inactive is supported,
the LFS keeps the vnode for a few minutes and then invokes vn_inactive,
at which time the vnode is freed.
For sockets PFSs, the total number
of vnodes in use is used to enforce the MAXSOCKETS limit. Thus, for
sockets PFSs that use vn_inactive, it is possible for a heavily loaded
system to reach its MAXSOCKETS limit—even though not that many sockets
are open—because of closed vnodes that have not yet been inactivated.
Refer
to Creating, referring to, and closing socket vnodes for more information about socket
close and inactivation.
- Serialization provided by the LFS
The
vn_close operation is invoked with an exclusive latch held on the
vnode of the file. Shared read support for the file that is being
closed can be modified in the OSI by the PFS upon returning from the
vn_close operation.
- Security calls to be made by the PFS
- None.
|