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
|
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
BPX1RW/BPX4RW does not support conversion using Unicode Services.
Examples
For an example using this callable service, see BPX1RW (Pwrite) example.