readv (BPX1RDV, BPX4RDV) — Read data and store it in a set of buffers

Function

The readv callable service reads data and stores it in a set of buffers.

Requirements

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 (BPX1RDV):	31-bit task or SRB mode
AMODE (BPX4RDV):	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.

Parameters

File_descriptor

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the file descriptor for which the readv request is to be done.

Iov_count

Supplied and returned parameter

Type:

Integer

Length:

Fullword

The name of a field that contains the number of buffers that are pointed to by Iov_struct. The total number of buffers may not exceed IOV_MAX (defined in BPXYIOV — Map the I/O vector structure).

Iov_struct

Supplied parameter

Type:

Structure

Length:

Iov_count times length(iov)

The name of a field that contains 31(64)-bit pointers to buffers in which data is to be stored, and their lengths. In 64-bit mode, Iov_struct contains doubleword pointer and length subfields. See BPXYIOV — Map the I/O vector structure for more information.

Iov_alet

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a field that contains the ALET for Iov_struct.

Iov_buffer_alet

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a field that contains the ALET for buffers that are pointed to by Iov_struct.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the readv service returns one of the following:

• The number of bytes that were read into the buffers, if the request is successful.
• -1, if the request is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the readv service stores the return code. The readv 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 readv service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EAGAIN	The file was opened with the nonblock option, and data is not available to be read.
EBADF	An incorrect file descriptor was specified. The following reason codes can accompany the return code: JRFileDesNotInUse, JRFileNotOpen.
EINTR	A signal interrupted the readv function before any data was available. The following reason code can accompany the return code: JRSockRdwrSignal.
EINVAL	The socket is marked shutdown for read; or an incorrect length was specified in the iov. 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. However, TOSTOP is set, the process is neither ignoring nor blocking SIGTTOU signals, and the process group of the process is orphaned. This can happen, for example, if a background job tries to write to the terminal after the user has logged off.
ENOBUFS	A buffer could not be obtained. The following reason code can accompany the return code: JROutofSocketCells.
EWOULDBLOCK	The socket is marked nonblocking and no data is waiting to be read, or the SO_RCVTIMEO timeout value was reached before data was available. The socket is marked blocking, and the call has blocked for that time period which was specified in the SO_RCVTIMEO option without receiving any data. The following reason code can accompany the return code: JRTimeout.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the readv service stores the reason code. The readv 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.

Usage notes

• See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.
• Socket files: When this callable service is used for datagram sockets, the readv service returns the entire datagram that was sent, providing that the datagram fits into the specified buffers. The excess is discarded. For stream sockets, data is not discarded. Multiple invocations of readv may be needed to return all the data.
• Bytes read: The number of bytes that were requested for reading is not checked against any system limit. A limit can be imposed by a high-level-language POSIX implementation.
• Access time: A successful read updates the access time of the file read.
• Origin of bytes read: If the file that was specified by File_descriptor is a regular file, or any other type of file where a seek operation is possible, bytes are read from the file offset that is associated with the file descriptor. A successful read increments the file offset by the number of bytes that are read.

  For files where no seek operation is possible, there is no file offset associated with the file descriptor. Reading begins at the current position in the file.

• Number of bytes read: When a read request completes, the Return_value field shows the number of bytes that were actually read — a number less than or equal to the number of bytes that were requested. Following are some reasons why the number of bytes that are read might be less than the number of bytes that were requested:
  • Fewer than the requested number of bytes remained in the file; the end of file was reached before all requested bytes were read.
  • The service was interrupted by a signal after some, but not all, of the requested bytes were read. (If no bytes were read, the return value is set to -1 and an error is reported.)
  • The file is a pipe, FIFO, or special file, and fewer bytes than requested were available for reading.
  There are several reasons why a read request might complete successfully with no bytes read — that is, with Return_value set to 0. For example, zero bytes are read in these cases:

  • The service specified that zero bytes were to be read.
  • The starting position for the read was at or beyond the end of the file.
  • The file that is being read is a FIFO file or a pipe, and no process has the pipe open for writing.
  • The file that is being read is a slave pseudoterminal, and a zero-length canonical line was written to the master.
• Nonblocking: If a process has a pipe open for reading with nonblocking specified, a request to read from the file ends with a return value of —1 and a "Resource temporarily unavailable" return code. But if nonblocking is not specified, the read request is blocked (does not return) until some data is written, or until the pipe is closed by all other processes that have the pipe open for writing.

  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.

• SIGTTIN processing: The readv service causes signal SIGTTIN to be sent under the following conditions:
  • The process is attempting to read from its controlling terminal, and
  • The process is running in a background process group, and
  • The SIGTTIN signal is not blocked or ignored, and
  • The process group of the process is not orphaned.
  If these conditions are met, SIGTTIN is sent. If SIGTTIN has a handler, the handler gets control and the read ends with a return code of EINTR. If SIGTTIN is set to default, the process stops in the read and continues when the process is moved to the foreground.

Related services

• writev (BPX1WRV, BPX4WRV) — Write data from a set of buffers

Characteristics and restrictions

There are no restrictions on the use of the readv service.