Pread() and Pwrite() (BPX1RW, BPX4RW) — Read from or write to a file without changing the file pointer

Function

The Pread() and Pwrite() callable service reads from or writes to a given position in a file without changing the file pointer.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1RW):	31-bit
AMODE (BPX4RW):	64-bit
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1RW,(File_descriptor,
              Fuio_Address,
              Fuio_Alet,
              Fuio_Length,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4RW with the same parameters. The Fuio_Address parameter is a doubleword.

Parameters

File_descriptor

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the file descriptor of an open file.

Fuio_Address

Supplied parameter

Type:: Address
Length:: Fullword (doubleword)

The name of a fullword (doubleword) field that contains the address of the Fuio control block, which contains the user request. This area is mapped by the BPXYFUIO macro (see BPXYFUIO — Map file system user I/O block).

The setting of the FuioAddr64 bit, and not the AMODE of the caller, indicates whether the buffer address is a 31-bit or 64-bit address. If FuioAddr64 is on, the buffer address is in FuioBufferAddr, and is 31-bit. If FuioAddr64 is off, the buffer address is in FuioBuffV64Addr, and is 64-bit.

Fuio_Alet

Supplied parameter

Type:: Address
Length:: Fullword

The name of a fullword field that contains the address of Fuio_alet.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the Pread() and Pwrite() service returns the number of bytes that were actually 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 Pread() and Pwrite() service stores the return code. The Pread() and Pwrite() 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. In addition to the return codes listed for the read and write callable services, the Pread() and Pwrite() service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	The offset argument is not valid. The value is negative.
ENXIO	A request was outside the capabilities of the device.
EOVERFLOW	The file is a regular file and an attempt was made to read or write at or beyond the offset maximum associated with the file.
ESPIPE	File_descriptor is associated with a pipe or FIFO.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the Pread() and Pwrite() service stores the reason code. The Pread() and Pwrite() service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Related services

Characteristics and restrictions

Start of change BPX1RW/BPX4RW does not support conversion using Unicode Services. End of change

Examples

For an example using this callable service, see BPX1RW (Pwrite) example.