The read callable service reads the number of bytes that you specify from a file or socket into a buffer that you provide.
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task SRB - AF_INET/AF_INET6 socket support only |
Cross memory mode: | PASN = HASN |
AMODE (BPX1RED): | 31-bit task or srb mode |
AMODE (BPX4RED): | 64-bit task mode only |
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. |
|
AMODE 64 callers use BPX4RED with the same parameters. The Buffer_address parameter is a doubleword.
The name of a fullword that contains the file descriptor of an open file or socket.
The name of a fullword (doubleword) that contains the address of the buffer into which data is to be read.
The name of a fullword that contains the ALET for the Buffer_address that identifies the address space or data space where the buffer resides.
You should specify a Buffer_ALET of 0 for the normal case of a buffer in the user's address space (current primary address space). If a value other than 0 is specified for the Buffer_ALET, the value must represent a valid entry in the dispatchable unit access list (DUAL).
The name of a fullword that contains the number of bytes that you want to read from the file. This number must be less than or equal to the length of the buffer that you provide for data to be read into.
The name of a fullword in which the read service returns the number of bytes that were actually read (this may be 0) if the request is successful, or -1 if it is not successful.
For more information about the return value, refer to usage note 5.
Return_code | Explanation |
---|---|
EAGAIN | The file was opened with the nonblock option, and data is not available to be read. |
EBADF | The File_descriptor parameter does not contain the descriptor of an open file; or the file is not opened for read. The following reason codes can accompany the return code: JRFileDesNotInUse, JRFileNotOpen. |
EINTR | The service was interrupted by a signal before it could read any data. |
EINVAL | The Read_Count parameter contains a value that is less than zero; or the socket is marked shutdown for read. The following reason codes can accompany the return code: JRSocketClosed, JRSocketCallParmError. |
EIO | The process is in a background process group, and is attempting to read from its controlling terminal. Either the process is ignoring or blocking the SIGTTIN signal, or the process group is orphaned. |
ENOBUFS | A buffer could not be obtained. The following reason code can accompany the return code: JROutofSocketCells. |
ENOTSOCK | The Socket_descriptor does not refer to a valid socket descriptor. The following reason code can accompany the return code: JRMustBeSocket. |
EWOULDBLOCK |
|
The name of a fullword in which the read service stores the reason code. The read 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.
Master and slave pseudoterminals also operate this way, except that how they act depends on how they were opened. If the master or the slave is opened blocking, the reads are blocked if there is no data. If they are opened nonblocking, EAGAIN is returned if there is no data.
If the file was opened by an authorized program, all subsequent reads and writes against the file must be issued from an authorized state.
The first restriction is not applicable if each thread coordinates its reads and writes so that simultaneous I/O does not occur. Both restrictions are not applicable if each thread opens the file independently.
Reads or writes that cause a conversion of greater than 2 G result in an EINVAL error with reason JrUniOpTooBig.
Refer to the BPX1FCT (fcntl) operations for instances of how a lseek operation in a conversion environment can affect read and write operations
For an example using this callable service, see BPX1RED (read) example.