Function

The vn_rdwr operation reads data from or writes data to a file or a socket.

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 (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

An area that contains the options that are to be used when reading from or writing to the file or socket. This area is mapped by fcntl.h. See z/OS XL C/C++ Runtime Library Reference for a description of this header.

User_IO_structure

Supplied and returned parameter

Type:

Structure

Length:

Specified by the UIO.u_hdr.cblen field

An area to be used by the vn_rdwr service to determine the buffer address, length, storage key, and other attributes of the read or write request. This area is mapped by the UIO typedef in the BPXYVFSI header file (see Interface structures for C language servers and clients). See the description of the vn_readwritev service in Implementation 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_rdwr 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 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_rdwr service stores the return code. The vn_rdwr 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 vn_rdwr service should support the following error values:

Return_code	Explanation
EFAULT	A buffer address that was not valid was passed.
EINTR	The request was interrupted by a signal.
EACCES	The caller does not have the requested (read or write) access to the file.
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.
EIO	An I/O error occurred while the file was being accessed.
EWOULDBLOCK	The request was made of a non-blocking descriptor, and a block was needed to satisfy the request.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

A fullword in which the vn_rdwr service stores the reason code. The vn_rdwr 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 vn_rdwr processing

Reading from and writing to files provides an overview of file read and write processing.

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 input/output buffer

  UIO.u_buffalet

  Specifies the ALET of the caller's input/output buffer

  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_rdwr 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_rdwr operation.

  UIO.u_count

  Specifies the number of bytes that are to be read or written

  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 input/output buffer

  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

  UIO.u_sync

  Specifies that the file is to be written to disk before the PFS returns. The PFS sets UIO.u_syncd to indicate that this has been done.

  UIO.u_chkacc

  Specifies that access checking is to be performed

  UIO.u_realpage

  Specifies that a real storage address is being passed. This flag is used only if the PFS reported during initialization that it supports DATOFF moves.

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_rdwr operation is invoked with an exclusive latch held on the vnode, 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 may be modified in the OSI by the PFS upon returning from the vn_rdwr operation.

Security calls to be made by the PFS

If u_chkacc is on in the user_IO_structure, the PFS is expected to invoke SAF's Check Access callable service to check that the user has permission to read from or write to the file. This check should be based on the access intent that is specified by u_rw.

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 is 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.