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
                     process'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 ap‐
       peared in Version 6 AT&T UNIX.



GNO                             23 January 1997                       WRITE(2)