readv()--Read from Descriptor Using Multiple Buffers
Syntax
#include <sys/types.h> #include <sys/uio.h> int readv(int descriptor, struct iovec *io_vector[], int vector_length)Service Program Name: QP0LLIB1
Default Public Authority: *USE
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).
See read()--Read from Descriptor for more information related to reading from a descriptor.
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; size_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
- n
- readv() is successful, where n is the number of bytes read.
- -1
- readv() was not successful. The errno global variable is set to indicate the error.
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.
Error condition | Additional information |
---|---|
[EACCES] |
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] | |
[EBADF] | |
[EBADFID] | |
[EBUSY] | |
[EDAMAGE] | |
[EFAULT] | |
[EINTR] | |
[EINVAL] |
For example, 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. See Usage Notes for additional possibilities. |
[EIO] | |
[ENOMEM] | |
[ENOTAVAIL] | |
[ENOTSAFE] | |
[EOVERFLOW] |
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. |
[ERESTART] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[EUNKNOWN] |
When the descriptor refers to a socket, errno could indicate one of the following errors:
Error condition | Additional information |
---|---|
[ECONNABORTED] |
This error code indicates that the transport provider ended the connection abnormally because of one of the following:
|
[ECONNREFUSED] | |
[ECONNRESET] | |
[EINTR] | |
[ENOTCONN] | |
[ETIMEDOUT] |
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] | |
[EWOULDBLOCK] |
If interaction with a file server is required to access the object, errno could indicate one of the following errors:
Error condition | Additional information |
---|---|
[EADDRNOTAVAIL] | |
[ECONNABORTED] | |
[ECONNREFUSED] | |
[ECONNRESET] | |
[EHOSTDOWN] | |
[EHOSTUNREACH] | |
[ENETDOWN] | |
[ENETRESET] | |
[ENETUNREACH] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[ETIMEDOUT] | |
[EUNATCH] |
Error Messages
Message ID | Error Message Text |
---|---|
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. Error number &1. |
Usage Notes
- This function will fail with error code [ENOTSAFE] when all the following
conditions are true:
- Where multiple threads exist 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
- Independent ASP QSYS.LIB
- QOPT
- Network File System
- QFileSvr.400
- Where multiple threads exist in the job.
- 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.
- 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.
- The partner program has issued a close() for the socket.
- 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.
- The partner program has sent a NULL message (a datagram with no user
data).
- If a connect() has been issued previously, then data can be
received only from the address specified in the previous
connect().
- 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.
- Error [EINVAL] will be returned when the specified vector_length
value is less than 1
or greater than IOV_MAX, where IOV_MAX is defined in <sys/uio.h>
along with the iovec structure.
- QFileSvr.400 File System Differences
When connecting to a system at release V5R4M5 and earlier, QFileSvr.400 does not support large files. Otherwise, the starting offset is limited by the file system being accessed on the server.
- QOPT File System Differences
When reading from files on volumes formatted in Universal Disk Format (UDF), byte locks on the range being read are ignored.
- Using this function successfully on the /dev/null or /dev/zero character special file results in a return value of 0. In addition, the access time for the file is updated.
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
- fclear()--Write (Binary Zeros) to Descriptor
- fclear64()--Write (Binary Zeros) to Descriptor (Large File Enabled)
- fcntl()--Perform File Control Command
- ioctl()--Perform 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
API introduced: V3R1