writev

Purpose

     Writes output gathered from multiple buffers.

Library

     Berkeley Library (libbsd.a)

Syntax

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

     int writev (fildes, iov, iovcnt)
     int fildes;
     struct iovec *iov;
     int iovcnt;

Description

     The writev subroutine  attempts to write the  data in the
     buffers  specified  by  the array  of  iovec  structures,
     pointed to by  the iov parameter, to  the file associated
     with the  fildes parameter.  The iovcnt  parameter is the
     number of iovec  structures pointed to by  the iov param-
     eter.

     The iovec  structure is  defined in the  sys/uio.h header
     file, and it contains the following members:

          caddr_t  iov_base;
          int      iov_len;

     Each iovec entry specifies the base address and length of
     an area in memory from which data should be written.  The
     writev subroutine  always writes  a complete  area before
     moving to the next.

     On devices capable  of seeking, writev starts  at a posi-
     tion in  the file  given by  the file  pointer associated
     with the  fildes parameter.  Upon return  from the writev
     subroutine, the file pointer is incremented by the number
     of bytes actually read.

     Devices that  are incapable  of seeking always  read from
     the current position.  The value  of a file pointer asso-
     ciated with such a file is undefined.

     When  using nonblocking  I/O on  objects such  as sockets
     that are subject to flow  control, writev may write fewer
     bytes than requested.  In  this case, the calling process

     must  note the  return value  and retry  the rest  of the
     operation when possible.

Return Value

     Upon successful completion, writev  returns the number of
     bytes that  were actually written.  Otherwise,  the value
     -1 is returned and errno is set to indicate the error.

Diagnostics

     The writev subroutine fails when  one or more of the fol-
     lowing is true:

     EBADF         The fildes  does not specify a  valid file,
                   or the  socket descriptor  is not  open for
                   writing.

     EFAULT        The buf parameter &pointsout..

     EFBIG         An attempt  was made  to write a  file that
                   exceeds the maximum file size.

     ENOSPC        No free  space is  left on the  file system
                   containing the file.

     EINVAL        The   fildes  parameter   has  a   negative
                   pointer.

     EINVAL        The iovcnt value was  not between 1 and 16,
                   inclusive.

     EINVAL        One of the iov_len  values in the iov array
                   was negative.

     EINVAL        The sum  of the  iov_len values in  the iov
                   array overflowed a 32-bit integer.

     EPIPE         An attempt was made to write to a file that
                   is not open for writing by any process.

     EPIPE         An  attempt was  made  to write  to a  file
                   without a  reader, or  to a socket  or type
                   SOCK_STREAM that is not connected to a peer
                   socket.

     EWOULDBLOCK   The  file was  marked for  non-blocking I/O
                   and no data could be written immediately.

Related Information

     In  this  book:   "fcntl,"   "lseek,"   "open,"  "pipe,"
     "select," and  "write, writex."