What is `writev'?

Marc Evans Ultrix Q/A evans at testmax.zk3.dec.com
Sat Apr 14 02:00:41 AEST 1990




                                                         write(2)



Name
     write, writev - write on a file

Syntax
     write (fd, buf, nbytes)
     int fd;
     char *buf;
     int nbytes;

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

     writev (fd, iov, ioveclen)
     int fd;
     struct iovec *iov;
     int ioveclen;

Arguments
     fd          Descriptor returned by a creat, open, dup,
                 fcntl, pipe, or socket system call.

     buf         Points to the buffer containing the data to be
                 written.

     nbytes      Positive integer defining the number of bytes to
                 be written from the buffer.

     iov         Points to a data structure of type iovec, which
                 defines the starting location of the set of vec-
                 tors forming the array and the length of each
                 individual vector in the array to be written.

                 This structure is defined in <sys/uio.h> as fol-
                 lows:

                      struct iovec {

                             caddr_t   iov_base ;
                             int       iov_len ;
                      } ;

                 The caddr_t data type is defined in
                 <sys/types.h> and is the recommended way to
                 define an address for a character value.  In any
                 case, the address iov_base is the starting
                 address of the set of vectors.  The integer
                 value iov_len is the length of each individual
                 vector, in bytes.

     ioveclen    Defines the number of vectors in the array of
                 data to be written.  Note that the numbering of
                 the vectors begins with 0 and proceeds through



                                                                1






write(2)



                 ioveclen -1.

Description
     The write system call attempts to write a buffer of data to
     a file.  The writev system call attempts to write an array
     of buffers of data to a file.

     When a file is opened to a device capable of seeking (such
     as a disk or tape), the write starts at the position given
     by the file pointer associated with the file descriptor, fd.
     This file pointer is the offset, in bytes, from the begin-
     ning of the file where the write is to begin.  When the file
     is first opened, the file pointer is set at 0.  It can be
     modified by the read(2) lseek(2) and write system calls.
     When the write call returns, the file pointer is incremented
     by the number of bytes actually written.

     When the file is opened to a device not capable of seeking
     (such as sockets, pipes, or terminals), the write starts at
     the current position. The value of the pointer associated
     with such an object is undefined.

     By default, write does asynchronous writes.  That is, after
     the data is written to a buffer cache, control returns to
     the program.  The actual write to a device takes place after
     control returns.  However, if you use an open or fcntl call
     to open a file for synchronous writes, control does not
     return to the program until after the buffer cache has been
     written to the device.

     If a program is using write to a remote file over NFS, and
     an asynchronous write error occurs, then all subsequent
     write requests will return -1 and errno will be set to the
     asynchronous error code. Also, a subsequent fsync(2) or
     close(2) will likewise fail. The return code from close(2)
     should be inspected by any program that can write over NFS.

     Write requests to a pipe (or FIFO) are handled the same as a
     regular file, with the following exceptions:

     o    A file offset is not associated with a pipe. Therefore,
          each write request appends to the end of the pipe.

     o    Write requests less than or equivalent to {PIPE_BUF}
          bytes are not interleaved with data from other
          processes doing writes on the same pipe.  Write
          requests greater than {PIPE_BUF} bytes can interleave
          on arbitrary boundaries with writes by other processes.

     o    If the O_NDELAY and O_NONBLOCK flags are clear, a write
          can cause the process to block, but, under normal com-
          pletion, it returns nbytes.



2






                                                         write(2)



     o    If the O_NDELAY or O_NONBLOCK flag is set, the write
          function does not block the process.  Write requests
          less than or equal to {PIPE_BUF} bytes either succeed
          and return nbytes or -1, and errno is set to [EWOULD-
          BLOCK].  Write requests that exceed {PIPE_BUF} bytes
          can return complete success, partial write, or no suc-
          cess, and errno is to [EWOULDBLOCK].

Environment
     SYSTEM V
     When your program is compiled using the System V environ-
     ment, and the file was opened with the O_NDELAY flag set, a
     write to a full pipe (or FIFO) returns a zero (0), rather
     than an error, as for the ULTRIX non-System V environment.

     Differs from the System V definition in that the value
     nbytes is int, rather than unsigned.


     When your program is compiled using POSIX environment,
     EAGAIN is returned in errno, in place of EWOULDBLOCK.

Return Value
     Upon successful completion, the number of bytes actually
     written is returned.  Otherwise, a -1 is returned, and errno
     is set to indicate the error.

Diagnostics
     The write system call fails and the file pointer will remain
     unchanged, if any of the following is true:

     [EACCESS]      The file does not permit writing. NFS only.

     [EBADF]        The fd argument is not a valid descriptor
                    open for writing.

     [EPIPE]        An attempt was made to write to a pipe that
                    is not open for reading by any process.

     [EPIPE]        An attempt was made to write to a socket of
                    type SOCK_STREAM that is not connected to a
                    peer socket.

     [EFBIG]        An attempt was made to write a file that
                    exceeds the process's file size limit, set by
                    ulimit(2) or the maximum file size (approxi-
                    mately 2 Gigabytes).

     [EFAULT]       Part of the array pointed to by iov or data
                    to be written to the file points outside the
                    process's allocated address space.




                                                                3






write(2)



     [EWOULDBLOCK]  The O_NDELAY or O_NONBLOCK flag is set for
                    the file descriptor and the process would be
                    delayed in the write operation.

     [ENOSPC]       There is no free space remaining on the file
                    system containing the file.

     [EDQUOT]       The user's quota of disk blocks on the file
                    system containing the file has been
                    exhausted.

     [EIO]          An I/O error occurred while reading from or
                    writing to the file system.

     [EINTR]        The write operation was interrupted, no data
                    was transferred.

     [EINVAL]       The nbytes argument is negative.

     [EROFS]        The file is on a read-only file system. NFS
                    only.

     [ESTALE]       The fd argument is invalid because the file
                    referred to by that file handle no longer
                    exists or has been revoked. NFS only.

     [ETIMEDOUT]    A write operation failed because the server
                    did not properly respond after a period of
                    time that is dependent on the mount(8nfs)
                    options. NFS only.

See Also
     close(2), creat(2), dup(2), fcntl(2), fsync(2), lseek(2),
     open(2), pipe(2), socket(2)





















4




===========================================================================
Marc Evans - WB1GRH - evans at decvax.DEC.COM  | Synergytics     (603)635-8876
     Unix/X-window Software Contractor      | 21 Hinds Ln, Pelham, NH 03076
===========================================================================



More information about the Comp.lang.c mailing list