Function

The v_rdwr service accepts a vnode token that represents a file and reads data from or writes data to the file. The number of bytes that are read or written and the file attributes are returned upon completion of the operation.

Requirements

Parameters

Vnode_token

Supplied parameter

Type:

Token

Length:

8 bytes

The name of an 8-byte area that contains a vnode token that represents the file that is to be read from or written into.

OSS

Supplied and returned parameter

Type:

Structure

Length:

OSS#LENGTH (from the BPXYOSS macro)

The name of an area that contains operating-system-specific parameters. This area is mapped by the BPXYOSS macro (see BPXYOSS — Map operating system specific information).

UIO

Supplied and returned parameter

Type:

Structure

Length:

Fuio#Len (from the BPXYFUIO macro)

The name of an area that contains the user input and output block. This area is mapped by the BPXYFUIO macro (see Mapping macros in z/OS UNIX System Services Programming: Assembler Callable Services Referencefor the mapping of this field).

Attr_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of the area that is passed in the Attr parameter. To determine the value of Attr_length, use the ATTR structure (see BPXYATTR — Map file attributes for v_ system calls).

Attr

Returned parameter

Type:

Structure

Length:

Specified by the Attr_length parameter

The name of an area, of length Attr_length, in which the v_rdwr service returns the file attribute structure for the file that is specified by the vnode token. This area is mapped by the ATTR structure (see BPXYATTR — Map file attributes for v_ system calls).

The file attributes information is returned only if the read or write operation is successful.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the v_rdwr service returns the number of bytes read or written if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the v_rdwr service stores the return code. The v_rdwr service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The v_rdwr service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	Parameter error; for example, a supplied area was too small. The following reason codes can accompany the return code: JRSmallAttr, JRVTokenFreed, JRWrongPID, JRStaleVnodeTok, JRInvalidVnodeTok, JRInvalidOSS, JRRwNotRegFile, JRInvalidFuio, JRBytes2RWZero.
EFBIG	Writing to the specified file would exceed either the file size limit for the process or the maximum file size that is supported by the physical file system.
EACCES	The caller does not have the requested (read or write) access to the file.
EIO	An I/O error occurred while reading or writing the file.
EPERM	The operation is not permitted. The caller of the service is not registered as a server.
EMVSPFSPERM	An internal error occurred in the PFS. Consult Reason_code to determine the exact reason the error occurred.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the v_rdwr service stores the reason code. The v_rdwr service returns a Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

1. The following UIO fields are provided to specify the details of the read or write request:

   FuioSync

   Requests that all data that is associated with the file is to be transferred to the storage device before completion of this write request.

   FuioChkAcc

   Requests the PFS to perform required access checking before performing the requested read or write operation.

   FuioBufferAddr

   Contains the address of a buffer that contains the data that is to be read or written.

   FuioBuff64Vaddr

   Contains the 64-bit virtual address of a buffer that contains the data that is to be read or written.

   FuioIBytesRW

   Specifies the number of bytes to be read or written.

   FuioRWInd

   Specifies the operation requested; read or write.

   FuioCursor

   Specifies the byte offset in the file where the read or write operation is to begin.

   FuioRealPage

   Specifies that the buffer is a real-storage page and the DATOFF services of MVS™ must be used to move the data.

   FuioInternal

   Used internally by the LFS during a call; this field must be zeroed out before each call.

2. The FuioAddr64 setting determines whether the pointer to the user buffer is a 64-bit pointer in FuioBuff64Vaddr or a 31-bit pointer in FuioBufferAddr.
3. An open token from a prior v_open can passed in the OSS to indicate that this read or write operation is being done within the open context of that token. Consequently, the operation does not have to be verified against the share reservations that might currently be in effect for this file. If an open token is unavailable to pass on a call, there are three levels of share reservation checking that can be requested:

   Oss#NoTokAdvChk

   Advisory checking. The operation is validated only against non-NLM share reservations. This corresponds to a read or write from a version 2 or 3 NFS client. These clients do not issue an open request and the NLM share reservations that they make are only advisory with respect to the reads and writes of other version 2 or 3 clients.

   Oss#NoTokMandChk

   Mandatory checking. The operation ise validated against all share reservations. This corresponds to a version 4 NFS client read or write with a stateid of 0 or a write with a stateid of –1.

   Oss#NoTokOverride

   No checking. The operation is permitted without any share reservation checking. This is only allowed for read operations and corresponds to a version 4 NFS client read with a stateid of –1.

   In general, version 4 share reservations are enforced against all clients; read and write operations from version 4 clients cannot violate any share reservations. Read and write operations from version 2 and 3 clients are allowed to violate version 2 and 3 share reservations.

Related services

• v_reg (BPX1VRG, BPX4VRG) — Register a process as a server

Characteristics and restrictions

A process must be registered as a server before the v_rdwr service is permitted; see v_reg (BPX1VRG, BPX4VRG) — Register a process as a server.