unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

WRITE(2V)                                                            WRITE(2V)



NAME
       write, writev - write output

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

       #include <&lt;sys/types.h>&gt;
       #include <&lt;sys/uio.h>&gt;

       int writev(fd, iov, iovcnt)
       int fd;
       struct iovec *iov;
       int iovcnt;

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.  writev()  per-
       forms the same action, but gathers the output data from the iovcnt buf-
       fers specified by the members of the  iov  array:  iov[0],iov[1],  ...,
       iov[iovcnt-1].   If  nbyte is zero, write() takes no action and returns
       0.  writev(), however, returns -1 and sets the  global  variable  errno
       (see ERRORS below).

       For writev(), the iovec structure is defined as

              struct iovec {
                   caddr_t   iov_base;
                   int  iov_len;
              };

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

       On  objects  capable of seeking, the write() starts at a position 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 associated 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() or writev() 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() or writev() is interrupted
       by a signal after successfully writing some data, it returns the number
       of bytes written.

       For  regular files, if the O_SYNC flag of the file status flags is set,
       write() does not return until both the file data and file  status  have
       been  physically  updated.   This  function is for special applications
       that require extra reliability at the cost of performance.   For  block
       special  files, if O_SYNC is set, the write() does not return until the
       data has been physically updated.

       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.

       For STREAMS (see intro(2)) files, the operation of write() and writev()
       are determined by the values of the minimum and  maximum  packet  sizes
       accepted  by  the  stream.   These  values are contained in the topmost
       stream module.  Unless the user pushes (see I_PUSH in streamio(4))  the
       topmost  module, these values can not be set or tested from user level.
       If the total number of bytes to be written falls within the packet size
       range, that many bytes are written.  If the total number of bytes to be
       written does not fall within the range  and  the  minimum  packet  size
       value  is  zero, write() and writev() break the data to be written into
       maximum packet size segments prior to sending the data downstream  (the
       last  segment  may  contain less than the maximum packet size).  If the
       total number of bytes to be written does not fall within the range  and
       the  minimum value is non-zero, write() and writev() fail and set errno
       to ERANGE.  Writing a zero-length buffer (the total number of bytes  to
       be written is zero) sends zero bytes with zero returned.

       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 <&lt;sys/fcntl.h>&gt;), 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 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 descriptor is marked for  non-blocking  I/O  by  using
                 fcntl()  to  set  the  FNBIO  or  O_NDELAY  flag  (defined in
                 <&lt;sys/fcntl.h>&gt;), 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.

              o  If  the  descriptor  is  marked  for  non-blocking  I/O using
                 fcntl() to set the FNONBLOCK or O_NONBLOCK flag  (defined  in
                 <&lt;sys/fcntl.h>&gt;),  write()  requests  for {PIPE_BUF} (see path-
                 conf(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()  and  writev()  return  the number of bytes actually written on
       success.  On failure, they return -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  allocated  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 multiplexor.

                           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 process (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.

       In addition to the above, writev() may set errno to:

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

                           One of the iov_len values in the iov array was neg-
                           ative.

                           The  sum  of  the  iov_len  values in the iov array
                           overflowed a 32-bit integer.

       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 stream, 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)



                                21 January 1990                      WRITE(2V)