readv()--Read from Descriptor Using Multiple Buffers

#include <sys/types.h>
#include <sys/uio.h>

int readv(int descriptor,
          struct iovec *io_vector[],
          int vector_length)

Threadsafe: Conditional; see Usage Notes.

The readv() function is used to receive data from a file or socket descriptor. readv() provides a way for data to be stored in several different buffers (scatter/gather I/O).

Parameters

descriptor

(Input) The descriptor to be read. The descriptor refers to a file or a socket.

io_vector[]

(I/O) The pointer to an array of type struct iovec. struct iovec contains a sequence of pointers to buffers in which the data to be read is stored. The structure pointed to by the io_vector parameter is defined in <sys/uio.h>.

      struct iovec {
         void      *iov_base;
         ssize_t   iov_len;
      }

iov_base and iov_len are the only fields in iovec used by sockets. iov_base contains the pointer to a buffer and iov_len contains the buffer length. The rest of the fields are reserved.

vector_length

(Input) The number of entries in io_vector.

Authorities

No authorization is required.

Return Value

readv() returns an integer. Possible values are:

• -1 (unsuccessful)

• n (successful), where n is the number of bytes read.

Error Conditions

If readv() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

The thread does not have access to the specified file, directory, component, or path.

If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems.

This may occur if file_descriptor refers to a socket and the socket is using a connection-oriented transport service, and a connect() was previously completed. The thread, however, does not have the appropriate privileges to the objects that were needed to establish a connection. For example, the connect() required the use of an APPC device that the thread was not authorized to.

[EAGAIN]

Operation would have caused the process to be suspended.

[EBADF]

Descriptor not valid.

A file descriptor argument was out of range, referred to a file that was not open, or a read or write request was made to a file that is not open for that operation.

A given file descriptor or directory pointer is not valid for this operation. The specified descriptor is incorrect, or does not refer to an open file. Or, this readv request was made to a file that was only open for writing.

[EBADFID]

A file ID could not be assigned when linking an object to a directory.

The file ID table is missing or damaged.

To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible.

[EBUSY]

Resource busy.

An attempt was made to use a system resource that is not available at this time.

[EDAMAGE]

A damaged object was encountered.

A referenced object is damaged. The object cannot be used.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

This may occur if file_descriptor refers to a socket that is using a connectionless transport service, is not a socket of type SOCK_RAW, and is not bound to an address.

The file resides in a file system that does not support large files, and the starting offset of the file exceeds 2 GB minus 2 bytes.

[EIO]

Input/output error.

A physical I/O error occurred.

A referenced object may be damaged.

[ENOMEM]

Storage allocation request failed.

A function needed to allocate storage, but no storage is available.

There is not enough memory to perform the requested function.

[ENOTSAFE]

Function is not allowed in a job that is running with multiple threads.

[EOVERFLOW]

Object is too large to process.

The object's data size exceeds the limit allowed by this function.

The file is a regular file, nbyte is greater than 0, the starting offset is before the end-of-file and is greater than or equal to 2GB minus 2 bytes.

[ESTALE]

File or object handle rejected by server.

If you are accessing a remote file through the Network File System, the file may have been deleted at the server.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

When the descriptor refers to a socket, errno could indicate one of the following errors:

[ECONNABORTED]

Connection ended abnormally.

This error code indicates that the transport provider ended the connection abnormally because of one of the following:

• The retransmission limit has been reached for data that was being sent on the socket.

• A protocol error was detected.

[ECONNREFUSED]

The destination socket refused an attempted connect operation.

[ECONNRESET]

A connection with a remote socket was reset by that socket.

[EINTR]

Interrupted function call.

[ENOTCONN]

Requested operation requires a connection.

This error code is returned only on sockets that use a connection-oriented transport service.

[ETIMEDOUT]

A remote host did not respond within the timeout period.

A non-blocking connect() was previously completed that resulted in the connection timing out. No connection is established. This error code is returned only on sockets that use a connection-oriented transport service.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

[EWOULDBLOCK]

Operation would have caused the process to be suspended.

If interaction with a file server is required to access the object, errno could indicate one of the following errors:

[EADDRNOTAVAIL]

Address not available.

[ECONNABORTED]

Connection ended abnormally.

[ECONNREFUSED]

The destination socket refused an attempted connect operation.

[ECONNRESET]

A connection with a remote socket was reset by that socket.

[EHOSTDOWN]

A remote host is not available.

[EHOSTUNREACH]

A route to the remote host is not available.

[ENETDOWN]

The network is not currently available.

[ENETRESET]

A socket is connected to a host that is no longer available.

[ENETUNREACH]

Cannot reach the destination network.

[ESTALE]

File or object handle rejected by server.

If you are accessing a remote file through the Network File System, the file may have been deleted at the server.

[ETIMEDOUT]

A remote host did not respond within the timeout period.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

Error Messages

CPE3418 E

Possible APAR condition or hardware failure.

CPF3CF2 E

Error(s) occurred during running of &1 API.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.

CPFA081 E

Unable to set return value or error code.

CPFA0D4 E

File system error occurred.

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:

   • There are secondary threads active in the job.

   • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:

     • Root

     • QOpenSys

     • User-defined

     • QNTC

     • QSYS.LIB

     • QOPT

     • QLANSrv

2. The io_vector[] parameter is an array of struct iovec structures. When a readv() is issued, the system processes the array elements one at a time, starting with io_vector[0]. For each element, iov_len bytes of received data are placed in storage pointed to by iov_base. Data is placed in storage until all buffers are full, or until there is no more data to receive. Only the storage pointed to by iov_base is updated. No change is made to the iov_len fields. To determine the end of the data, the application program must use the following:

   • The function return value (the total number of bytes received).

   • The lengths of the buffers pointed to by iov_base.

3. For sockets that use a connection-oriented transport service (for example, sockets with a type of SOCK_STREAM), a returned value of zero indicates one of the following:

   • The partner program has issued a close() for the socket.

   • The partner program has issued a shutdown() to disable writing to the socket.

   • The connection is broken and the error was returned on a previously issued socket function.

   • A shutdown() to disable reading was previously done on the socket.

4. For sockets that have a type of SOCK_SEQPACKET, each output operation by the partner program constitutes one record. If the record length is larger than the value specified by the buffer_length parameter, the remaining data from the record is discarded.

5. The following applies to sockets that use a connectionless transport service (for example, a socket with a type of SOCK_DGRAM):

   • If a connect() has been issued previously, then data can be received only from the address specified in the previous connect().

   • The address from which data is received is discarded, because the readv() has no address parameter.

   • The entire message must be read in a single read operation. If the size of the message is too large to fit in the user-supplied buffers, the remaining bytes of the message are discarded.

   • A returned value of zero indicates one of the following:

     • The partner program has sent a NULL message (a datagram with no user data).

     • A shutdown() to disable reading was previously done on the socket.

     • The buffer length specified by the application was zero.

6. For the file systems that do not support large files, readv() will return [EINVAL] if the starting offset exceeds 2GB minus 2 bytes, regardless of how the file was opened. For the file systems that do support large files, readv() will return [EOVERFLOW] if the starting offset exceeds 2GB minus 2 bytes and file was not opened for large file access.

7. QFileSvr.400 File System Differences

   The largest buffer size allowed is 16 megabytes. If a larger buffer is passed, the error EINVAL will be received.

Related Information

• The <limits.h> file (see Header Files for UNIX-Type Functions)

• The <unistd.h> file (see Header Files for UNIX-Type Functions)

• creat()--Create or Rewrite File

• dup()--Duplicate Open File Descriptor

• dup2()--Duplicate Open File Descriptor to Another Descriptor

• fcntl()--Perform File Control Command

• fcntl()--Retrieve or Change Descriptor Attributes

• ioctl()--Change Descriptor Attributes

• ioctl()--Perform File I/O Control Request

• lseek()--Set File Read/Write Offset

• open()--Open File

• read()--Read from Descriptor

• recv()--Receive Data

• recvfrom()--Receive Data

• recvmsg()--Receive Data or Descriptors or Both

• write()--Write to Descriptor

• writev()--Write to Descriptor Using Multiple Buffers