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)

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.

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

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

Error Messages

Usage Notes

1. 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
   
   
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. 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.
   
   
5. 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.
   
   
6. 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.



7. 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.

8. 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.

9. 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

[ Back to top | UNIX-Type APIs | APIs by category ]