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



NAME
     write, writev - write output

SYNOPSIS
     cc = write(d, buf, nbytes)
     int cc, d;
     char *buf;
     int nbytes;

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

     cc = writev(d, iov, iovcnt)
     int cc, d;
     struct iovec *iov;
     int iovcnt;

DESCRIPTION
     _w_r_i_t_e attempts to write _n_b_y_t_e_s of data to the object  refer-
     enced by the descriptor _d from the buffer pointed to by _b_u_f.
     _w_r_i_t_e_v performs the same action, but gathers the output data
     from  the _i_o_v_c_n_t buffers specified by the members of the _i_o_v
     array: iov[0], iov[1], ..., iov[iovcnt-1].

     For _w_r_i_t_e_v, the _i_o_v_e_c structure is defined as

          struct iovec {
               caddr_t   iov_base;
               int  iov_len;
          };

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

     On objects capable of seeking, the _w_r_i_t_e starts at  a  posi-
     tion  given  by the pointer associated with _d, see _l_s_e_e_k(2).
     Upon return from _w_r_i_t_e, the 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 pointer associated
     with such an object is undefined.

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

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



Sun Release 3.2     Last change: 16 July 1986                   1






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



     user-id file owned by the super-user.

     When using non-blocking I/O on objects that are  subject  to
     flow  control,  such as sockets, pipes (or FIFOs), or termi-
     nals, _w_r_i_t_e and _w_r_i_t_e_v 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 _w_r_i_t_e and _w_r_i_t_e_v will return -1 and set _e_r_r_n_o  to
     EWOULDBLOCK.  Otherwise, they will block until space becomes
     available.

SYSTEM V DESCRIPTION
     A _w_r_i_t_e (but not a _w_r_i_t_e_v) on an object that  cannot  accept
     any  data  will return a count of 0, rather than returning-1
     and setting _e_r_r_n_o to EWOULDBLOCK.

RETURN VALUE
     Upon successful completion the number of bytes actually wri-
     ten  is returned.  Otherwise a -1 is returned and the global
     variable _e_r_r_n_o is set to indicate the error.

ERRORS
     _w_r_i_t_e and _w_r_i_t_e_v will fail and the file pointer will  remain
     unchanged if one or more of the following are true:

     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 (or to a
                    socket of type SOCK_STREAM that is  connected
                    to  a peer socket.)  Note: an attempted write
                    of this kind will also cause you to recieve a
                    SIGPIPE  signal  from  the kernel.  If you've
                    not made a  special  provision  to  catch  or
                    ignore this signal, your process will die.

     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 _i_o_v or data to be written to the file
                    points   outside   the   process's  allocated
                    address space.

a signal whose.SM SV_INTERRUPT
     The call is forced to terminate prematurely due to the arrival of
                    bit  in  sv_flags  is  set   (see _s_i_g_v_e_c(2)).
                    _s_i_g_n_a_l(3V), in  the  System  V  compatibility
                    library,  sets  this  bit  for  any signal it
                    catches.




Sun Release 3.2     Last change: 16 July 1986                   2






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



     EINVAL         The pointer associated with _d was negative.

     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.

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

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

     EINVAL         _I_o_v_c_n_t was  less  than  or  equal  to  0,  or
                    greater than 16.

     EINVAL         One of the _i_o_v__l_e_n values in  the  _i_o_v  array
                    was negative.

     EINVAL         The sum of the  _i_o_v__l_e_n  values  in  the  _i_o_v
                    array overflowed a 32-bit integer.

SEE ALSO
     fcntl(2), lseek(2), open(2V), pipe(2), select(2)



























Sun Release 3.2     Last change: 16 July 1986                   3