write(2)                                                 write(2)



NAME
     write, writev - write on a file

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

     int write(fildes, buf, nbytes)
     int fildes;
     char *buf;
     unsigned nbytes;

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

DESCRIPTION
     write attempts to write nbytes bytes from the buffer pointed
     to by buf to the file associated with fildes.  writev
     performs the same action, but gathers the output data from
     the iovlen buffers specified by the members of the iovec
     array:  iov[0], iov[1], and so on.

     The file descriptor fildes is obtained from a creat, open,
     dup, fcntl, pipe, or socket system call.

     On devices capable of seeking, the actual writing of data
     proceeds from the position in the file indicated by the file
     pointer.  On return from write, the file pointer is
     incremented by the number of bytes actually written.

     On devices incapable of seeking, writing always starts at
     the current position.  The value of a file pointer
     associated with such a device is undefined.

     If the O_APPEND flag of the file status flags is set, the
     file pointer is set to the end of the file prior to each
     write.

     When writing to a pipe (or FIFO), write requests of PIPE_BUF
     bytes or less are not interleaved with data from other
     processes writing to the same pipe.  Writes of greater than
     PIPE_BUF bytes may have data interleaved, on arbitrary
     boundaries, with writes by other processes.

STATUS MESSAGES AND VALUES
     On successful completion, the number of bytes actually
     written is returned.  If the process compatibility flag
     COMPAT_SYSCALL is set (see setcompat(2)), as in the POSIX
     environment, and write-interrupted by a signal after
     successfully writing some data, it returns the number of



January 1992                                                    1

write(2)                                                 write(2)



     bytes written.  If nybytes is 0, write returns 0 and has no
     other result.  Otherwise, -1 is returned and errno is set to
     indicate the error.

     When attempting to write to a stream when buffer space is
     not currently available and if O_NDELAY or O_NONBLOCK is
     set, the write returns the number of bytes written before
     there were no buffers available.  If O_NDELAY and O_NONBLOCK
     are clear, the write blocks until buffers become available.

     write fails and the file pointer remains unchanged if one or
     more of the following is true:

     EIO  A physical I/O error has occurred or the process is in
          a background process group and is attempting to write
          to its controlling terminal (see termio(7P)).  TOSTOP
          is set, the process is not blocking or ignoring
          SIGTTOU.  The process group of the processes is
          orphaned or the write was to an open device after a
          modem disconnect or hangup occurred.

     ENXIO
          The device associated with the file descriptor is a
          block device file or character device file and the
          value of the file pointer is out of range.

     EBADF
          The file descriptor, fildes, is not valid and open for
          writing.

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

     EFBIG
          An attempt was made to write a file that exceeds the
          process's file size limit or the maximum file size.
          See ulimit(2).

     EFAULT
          Part of iov or data to be written to the file points
          outside the allocated address space of the process.

     EFAULT
          buf points outside the allocated address space of the
          process.

     EINTR
          A signal was caught during the write system call.

     ENOSPC
          Not enough space was left on the device containing the



2                                                    January 1992

write(2)                                                 write(2)



          file.

     If the number of bytes specified in a write request exceeds
     the available space limit, that is, the per-process file
     size (see ulimit(2)), or exceeds the size of the physical
     media, only as many bytes for which there is room will be
     written.  For example, suppose there is space in a file for
     an additional 20 bytes before reaching a limit.  A write of
     512 bytes returns 20.  The next write of a nonzero number of
     bytes gives a failure return with the following exceptions:

     If the file being written is a pipe (or FIFO) and

          if the O_NDELAY flag of the file-flag word is set, then
          writing to a full pipe (or FIFO) returns a count of 0.

          if O_NDELAY is clear, writes to a full pipe (or FIFO)
          blocks until space becomes available.

     If the file being written is a pipe (or FIFO) and

          if O_NONBLOCK is set, write requests for PIPE_BUF or
          fewer bytes either succeed completely or return -1 and
          set errno to EAGAIN.

          if O_NONBLOCK is clear, a write request may block until
          space is available.

     When writing to a file descriptor (other than a pipe or
     FIFO) that supports nonblocking writes and cannot accept
     data immediately and if O_NONBLOCK is set, write writes what
     data it can, returning -1 and setting errno to EAGAIN.  If
     O_NONBLOCK is clear, write blocks until the data is
     accepted.

SEE ALSO
     creat(2), dup(2), fcntl(2), lseek(2), open(2), pipe(2),
     select(2N), socket(2N), ulimit(2)

















January 1992                                                    3