Return values - BrainDump

On success, readv()andwritev()return the number of bytes read or written, respectively. This number should be the sum of allcount iov_lenvalues. On error, the system calls return-1, and seterrnoas appropriate. These system calls can experience any of the errors of theread()andwrite()system calls, and will, upon receiving such errors, set the sameerrnocodes. In addition, the standards define two other error situations.

First, because the return type is anssize_t, if the sum of allcount iov_lenvalues is greater thanSSIZE_MAX, no data will be transferred,-1will be returned, anderrnowill be set toEINVAL.

Second, POSIX dictates thatcountmust be larger than zero, and less than or equal toIOV_MAX, which is defined in<limits.h>. In Linux,IOV_MAXis currently1024. Ifcountis0, the system calls return0.* Ifcountis greater thanIOV_MAX, no data is transferred, the calls return-1, anderrnois set toEINVAL.

Optimizing the Count

During a vectored I/O operation, the Linux kernel must allocate internal data structures to represent each segment. Normally, this allocation would occur dynamically, based on the size of count. As an optimization, however, the Linux kernel creates a small array of segments on the stack that it uses ifcountis sufficiently small, negating the need to dynamically allocate the segments, and thereby providing a small boost in performance. This threshold is currently eight, so ifcountis less than or equal to8, the vectored I/O operation occurs in a very memory-efficient manner off of the process’ kernel stack.

Most likely, you won’t have a choice about how many segments you need to transfer at once in a given vectored I/O operation. If you are flexible, however, and are debating over a small value, choosing a value of eight or less definitely improves efficiency.

Let’s consider a simple example that writes out a vector of three segments, each containing a string of a different size. This self-contained program is complete enough to demonstrate writev(), yet simple enough to serve as a useful code snippet:

  #include <stdio.h>
  #include <sys/types.h>
  #include <sys/stat.h>
  #include <fcntl.h>
  #include <string.h>
  #include <sys/uio.h>

  int main ()
  {
          struct iovec iov[3];
          ssize_t nr;
          int fd, i;

          char *buf[] = {
                  "The term buccaneer comes from the word boucan.\n",
                  "A boucan is a wooden frame used for cooking meat.\n",
                  "Buccaneer is the West Indies name for a pirate.\n" };

          fd = open ("buccaneer.txt", O_WRONLY | O_CREAT | O_TRUNC);
          if (fd == -1) {
                  perror ("open");
                  return 1; 
          }

          /* fill out three iovec structures */
          for (i = 0; i < 3; i++) {
                  iov[i].iov_base = buf[i];
                  iov[i].iov_len = strlen (buf[i]);
          }

          /* with a single call, write them all out */
          nr = writev (fd, iov, 3);
          if (nr == -1) {
                  perror ("writev");
                  return 1;
          }
          printf ("wrote %d bytes\n", nr);

          if (close (fd)) {
                  perror ("close");
                  return 1;
          }

          return 0;
  }

Running the program produces the desired result:

  $ ./writev
  wrote 148 bytes

As does reading the file:

  $ cat buccaneer.txt
  The term buccaneer comes from the word boucan.
  A boucan is a wooden frame used for cooking meat.
  Buccaneer is the West Indies name for a pirate.