WRITE(2V)                 SYSTEM CALLS                  WRITE(2V)

NAME
     write - write output

SYNOPSIS
     int write(fd, buf, nbyte)
     int fd;
     char *buf;
     int nbyte;

SYSTEM V SYNOPSIS
     int write(fd, buf, nbyte)
     int fd;
     char *buf;
     unsigned nbyte;

DESCRIPTION
     write() attempts to write nbyte bytes of data to the  object
     referenced  by  the descriptor fd from the buffer pointed to
     by  buf.   If  nbyte is zero,  write() takes n o action  and 
     returns 0.  

     On objects capable of seeking, the write() starts at a posi-
     tion  given  by  the  seek  pointer associated with fd, (see
     lseek(2V)).  Upon return from write(), the seek  pointer  is
     incremented by the number of bytes actually written.

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

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

     If the process calling write() receives a signal
     before  any  data are written, the system call is restarted,
     unless the process explicitly set the  signal  to  interrupt
     the  call using sigvec() or sigaction() (see the discussions
     of   SV_INTERRUPT   on   sigvec(2)   and   SA_INTERRUPT   on
     sigaction(3V)).   If write() is interrupted by a
     signal after successfully writing some data, it returns  the
     number of bytes written.

     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 a descriptor or the object it refers to is  marked  for
     non-blocking  I/O,  and  the  descriptor refers to an object
     subject to flow control, such as a socket, a pipe (or FIFO),
     or a stream, 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 such
     an object's buffers are full, so that it cannot  accept  any
     data, then:

          o+  If the object to  which  the  descriptor  refers  is
             marked   for  non-blocking  I/O  using  the  FIONBIO
             request to ioctl(2), or by using  fcntl(2V)  to  set
             the   FNDELAY   or   O_NDELAY   flag   (defined   in
             <sys/fcntl.h>), write() returns -1 and sets errno to
             EWOULDBLOCK.

     Upon successful completion, write()  marks  for  update  the
     st_ctime and st_mtime fields of the file.

SYSTEM V DESCRIPTION
     write() and writev() behave as described above, except:

     When a descriptor or the object it refers to is  marked  for
     non-blocking  I/O,  and  the  descriptor refers to an object
     subject to flow control, such as a socket, a pipe (or FIFO),
     or a _s_t_r_e_a_m, 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 such
     an object's buffers are full, so that it cannot  accept  any
     data, then:

          +  If the descriptor is marked for non-blocking I/O  by
             using  fcntl()  to  set  the  FNBIO or O_NDELAY flag
             (defined in <sys/fcntl.h>), and does not refer to  a
             stream, the write() returns 0.  If the descriptor is
             marked for non-blocking I/O, and refers to a stream,
             write() returns -1 and sets errno to EAGAIN.

          +  If the descriptor is  marked  for  non-blocking  I/O
             using  fcntl()  to  set  the FNONBLOCK or O_NONBLOCK
             flag (defined in  <sys/fcntl.h>),  write()  requests
             for  {PIPE_BUF}  (see  pathconf(2V))  or fewer bytes
             either  succeed  completely  and  return  nbyte,  or
             return -1 and set errno to EAGAIN. A write() request
             for greater than {PIPE_BUF} bytes  either  transfers
             what it can and returns the number of bytes written,
             or transfers no data and returns -1 and  sets  errno
             to  EAGAIN.  If  a  write()  request is greater than
             {PIPE_BUF} bytes and all data previously written  to
             the  pipe  has been read, write() transfers at least
             {PIPE_BUF} bytes.

RETURN VALUES
     write() returns the  number  of  bytes  actually
     written  on  success.   On  failure,  it returns -1 and set
     errno to indicate the error.

ERRORS
     write() and writev()  fail  and  the  seek  pointer  remains
     unchanged if one or more of the following are true:

     EBADF               fd is not a valid  descriptor  open  for
                         writing.

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

     EFAULT              Part of iov or data to be written to the
                         file  points outside the process's allo-
                         cated address space.

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

     EINTR               The process performing a write  received
                         a  signal  before any data were written,
                         and the signal was set to interrupt  the
                         system call.

     EINVAL              The stream  is  linked  below  a  multi-
                         plexor.

                         The seek pointer associated with fd  was
                         negative.

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

                         The process is in a  background  process
                         group  and is attempting to write to its
                         controlling terminal, TOSTOP is set, the
                         process is neither ignoring nor blocking
                         SIGTTOU, and the process  group  of  the
                         process is orphaned.

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

     ENXIO               A hangup occurred on  the  stream  being
                         written to.

     EPIPE               An attempt is made to write  to  a  pipe
                         that is not open for reading by any pro-
                         cess (or to a socket of type SOCK_STREAM
                         that  is  connected  to  a peer socket.)
                         Note: an attempted write  of  this  kind
                         also  causes  you  to  receive a SIGPIPE
                         signal from the kernel.  If  you've  not
                         made  a  special  provision  to catch or
                         ignore this signal,  then  your  process
                         dies.

     ERANGE              fd refers to a stream, the total  number
                         of  bytes  to  be written is outside the
                         minimum and maximum write range, and the
                         minimum value is non-zero.

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


     A write to a STREAMS file can fail if an error  message  has
     been  received  at  the stream head.  In this case, errno is
     set to the value included in the error message.

SYSTEM V ERRORS
     write() fails and sets errno as described above, except:

     EAGAIN              The descriptor referred to a streeam, was
                         marked for non-blocking I/O, and no data
                         could be written immediately.

                         The O_NONBLOCK flag is set for the  file
                         descriptor and write() would block.

SEE ALSO
     dup(2V), fcntl(2V), intro(2), ioctl(2), lseek(2V), open(2V),
     pipe(2V), select(2), sigvec(2), signal(3V)


Sun Release 4.1   Last change: 21 January 1990                  5
