|
FunctionThe vn_readwritev operation reads
or writes on a file or socket, using a set of buffers to hold the
data that is read or written.
Input parameter formatvn_readwritev (Token_structure,
OSI_structure,
Audit_structure,
Open_flags,
User_IO_structure,
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:
- Structure
- Length:
- Fullword
A fullword that contains the bits that are associated
with the socket. The defined values for this field are mapped by fcntl.h.
- User_IO_structure
- Supplied and returned parameter
- Type:
- UIO
- Length:
- Specified by UIO.u_hdr.cblen.
An area that contains the parameters for the I/O
that is to be performed. This area is mapped by the UIO typedef in
the BPXYVFSI header file (see Interface structures for C language servers and clients). See "Specific
processing notes" for details on how the fields in this structure
are processed.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
A fullword in which the vn_readwritev 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 or greater
- The operation was successful; the value represents the number
of bytes that were transferred.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
A fullword in which the vn_readwritev operation
stores the return code. The vn_readwritev 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.
The vn_readwritev operation should
support at least the following error values: Return_code |
Explanation |
---|
EINVAL |
Either a negative number of bytes was requested, or this socket
has been shut down. |
EFAULT |
A buffer address that was specified is not in addressable storage. |
EFBIG |
Writing to the specified file would exceed the file size limit
for the process or the maximum file size that is supported by the
physical file system. |
EWOULDBLOCK |
The operation would have required a blocking wait, and this
socket was marked as nonblocking. |
- Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
A fullword in which the vn_readwritev operation
stores the reason code. The vn_readwritev 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_readwritev processing
For more information about the semantics of this operation
for a POSIX-conforming PFS, refer to the publications that are mentioned
in Finding more information about sockets for the readv and writev functions.
- Specific processing notes
- The following UIO fields are provided by the LFS:
- UIO.u_hdr.cbid
- Contains UIO_ID (from the BPXYVFSI header file)
- UIO.u_hdr.cblen
- Specifies the length of the user_IO_structure
- UIO.u_buffaddr
- Specifies the address of the caller's iov structure. The iov structure
is mapped in uio.h.
- UIO.u_buffalet
- Specifies the ALET of the caller's iov structure
- UIO.u_offseth
- Specifies the upper word of a doubleword value that contains the
offset into the file. The updated value for this field is returned
by the PFS as a result of the vn_readwritev operation.
- UIO.u_offset
- Specifies the lower word of a doubleword value that contains the
offset into the file. The updated value for this field is returned
by the PFS as a result of the vn_readwritev operation.
- UIO.u_count
- Specifies the number of elements in the IOV array
- UIO.u_asid
- Specifies the ASID of the caller
- UIO.u_rw
- Specifies whether the request is a read (0) or a write (1)
- UIO.u_key
- Specifies the storage key of the caller's buffer
- UIO.u_iovbufalet
- Specifies the ALET of the iov's buffers. All of the iov buffers
must use the same ALET.
- UIO.u_fssizelimithw
- Specifies the high word of the file size limit for the process.
- UIO.u_fssizelimitlw
- Specifies the low word of the file size limit for the process.
Also
refer to Reading from and writing to files for details on how reads and
writes are done by the file system.
The UIO contains fields that may point to a 64-bit addressable
user buffer. When FuioAddr64 is on (and FuioRealPage is off), FuioBuff64Vaddr
points to a buffer, an IOV64, or an MSGH64.
- PFS Limit Processing
The UIO contains the process file size limit for the file.
This is a doubleword value that is contained in UIO.u_fssizelimithw
and UIO.u_fssizelimitlw. When a write request is unable to write
any data before exceeding the file size limit, the PFS must set the
UIO.u_limitex bit on, in addition to setting a Return_code of EFBIG.
This includes detecting the special case in which the UIO.u_fssizelimithw
is equal to UIO_NONEWFILES, which prohibits the expansion of existing
files.
(Note that for vn_setattr, the LFS handles file size
limit checking.)
The PFS must also be aware of one other special
value for the file size limit. If both UIO.u_fssizelimithw and UIO.u_fssizelimitlw
are equal to 0, there is no file size limit set for the process.
- Serialization provided by the LFS
The
vn_readwritev operation is invoked with an exclusive latch held on
the vnode of the file or socket, unless the VnodSharedRead flag indicates
that shared read is supported, in which case a shared latch is held
on the vnode.
Shared read support for the file that is being
read from or written to can be modified in the OSI by the PFS upon
returning from the vn_readwritev operation.
- Security calls to be made by the PFS
If the check access bit is set and this PFS does access checking,
the PFS is expected to invoke SAF's Check Access callable service
to verify that the user has permission to read from or write to the
file.
The PFS is expected to invoke SAF's Clear Setid callable
service whenever a write is done to a file with the S_GID or S_UID
options. System overhead can be significantly reduced by setting an
internal flag in the Inode to indicate that Clear Setid has been called,
so that subsequent calls can be avoided. This flag would be cleared
whenever the file's mode was changed via vn_setattr. In other words,
Clear Setid should only be called once on the first write after the
file's mode is changed or its Inode is created in storage.
|