WRITE(2)                         System Calls                         WRITE(2)




NAME

       write, writev - write output


SYNOPSIS

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

       ssize_t write (int d, const void *buf, size_t nbytes);

       ssize_t writev (int d, const struct iovec *iov, int iovcnt);


DESCRIPTION

       write  attempts to write nbytes of data to the object referenced by the
       descriptor d from the buffer pointed to by buf.   writev  performs  the
       same action, but gathers the output data from the iovcnt buffers speci-
       fied  by  the  members  of  the  iov  array:   iov[0],   iov[1],   ...,
       iov[iovcnt-1].

       For writev, the iovec structure is defined as:

       struct iovec {
            void *iov_base;
            size_t iov_len;
       };

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

       On  objects capable of seeking, the write starts at a position given by
       the pointer associated with d (see lseek(2)).  Upon return from  write,
       the pointer is incremented by the number of bytes which were written.

       Objects  that  are not capable of seeking always write from the current
       position.  The value of the pointer associated with such an  object  is
       undefined.

       If the real user is not the super-user, then write clears the set-user-
       id bit on a file.  This prevents penetration of system  security  by  a
       user  who captures a writable set-user-id file owned by the super-user.

       When using non-blocking I/O on objects such as sockets that are subject
       to flow control, write and writev may write fewer bytes than requested;
       the return value must be noted, and  the  remainder  of  the  operation
       should be retried when possible.

       If the file was opened with the GNO-specific flag O_TRANS, then newline
       translation will occur; any line feed (0x0a) character present  in  buf
       will be converted to a carridge return (0x0d) before the write is done.
       See also the section on BUGS, below.


RETURN VALUES

       Upon successful completion the number of bytes which  were  written  is
       returned.   Otherwise a -1 is returned and the global variable errno is
       set to indicate the error.


ERRORS

       Write and writev will fail and the file pointer will  remain  unchanged
       if:

              EBADF  D is not a valid descriptor open for writing.

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

              EPIPE  An  attempt  is  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 pro-
                     cess's file size limit or the maximum file size.

              EFAULT Part of iov or data to be written to the file points out-
                     side the process's allocated address space.

              EINVAL The pointer associated with d was negative.

              ENOSPC There  is no free space remaining on the file system con-
                     taining the file.

              EDQUOT The user's quota of disk blocks on the file  system  con-
                     taining the file has been exhausted.

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

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

       In addition, writev may return one of the following errors:

              EINVAL Iovcnt  was  less  than  or  equal  to 0, or greater than
                     UIO_MAXIOV.

              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.


BUGS

       If the GNO-specific flag O_TRANS was specified when  the  descriptor  d
       was opened, then buf may be modified by this call; the newline transla-
       tion is done in-place.


SEE ALSO

       fcntl(2), lseek(2), open(2), pipe(2), select(2)


STANDARDS

       Write is expected to conform to IEEE Std 1003.1-1988 (POSIX).


HISTORY

       The writev function call appeared in 4.2BSD.   A  write  function  call
       appeared in Version 6 AT&T UNIX.



GNO                             23 January 1997                       WRITE(2)

Man(1) output converted with man2html