write(2)                                                           write(2)




 NAME
      write, writev - write on a file

 SYNOPSIS
      #include <unistd.h>

      ssize_t write(int fildes, const void *buf, size_t nbyte);

      #include <sys/uio.h>

      ssize_t writev(int fildes, const struct iovec *iov, int iovcnt);

 DESCRIPTION
      The write() function attempts to write nbyte bytes from the buffer
      pointed to by buf to the file associated with the open file
      descriptor, fildes.

      If nbyte is 0, write() will return 0 and have no other results if the
      file is a regular file; otherwise, the results are unspecified.

      On a regular file or other file capable of seeking, the actual writing
      of data proceeds from the position in the file indicated by the file
      offset associated with fildes.  Before successful return from write(),
      the file offset is incremented by  the number of bytes actually
      written. On a regular file, if this incremented file offset is greater
      than the length of the file, the length of the file will be set to
      this file offset.  If the O_SYNC flag of the file status flags is set
      and fildes refers to a regular file, a successful write() does not
      return until the data is delivered to the underlying hardware. On a
      file not capable of seeking, writing always takes place starting at
      the current position. The value of a file offset associated with such
      a device is undefined.

      If the O_APPEND flag of the file status flags is set, the file offset
      will be set to the end of the file prior to each write and no
      intervening file modification operation will occur between changing
      the file offset and the write operation.

      If a write() requests that more bytes be written than there is room
      for (for example, the ulimit or the physical end of a medium), only as
      many bytes as there is room for will be written. For example, suppose
      there is space for 20 bytes more in a file before reaching a limit. A
      write of 512 bytes will return 20. The next write of a non-zero number
      of bytes will give a failure return (except as noted below) and the
      implementation will generate a SIGXFSZ signal for the process.

      If write() is interrupted by a signal before it writes any data, it
      will return -1 with errno set to EINTR.

      If write() is interrupted by a signal after it successfully writes
      some data, it will return the number of bytes written.



 Hewlett-Packard Company            - 1 -    HP-UX Release 10.20:  July 1996






 write(2)                                                           write(2)




      If the value of nbyte is greater than {SSIZE_MAX}, the result is
      implementation-dependent.

      After a write() to a regular file has successfully returned:

           o  Any successful read() from each byte position in the file that
              was modified by that write will return the data specified by
              the write() for that position until such byte positions are
              again modified.

           o  Any subsequent successful write() to the same byte position in
              the file will overwrite that file data.

      Write requests to a pipe or FIFO will be handled the same as a regular
      file with the following exceptions:

           o  There is no file offset associated with a pipe, hence each
              write request will append to the end of the pipe.

           o  Write requests of {PIPE_BUF} bytes or less will not be
              interleaved with data from other processes doing writes on the
              same pipe.  Writes of greater than {PIPE_BUF} bytes may have
              data interleaved, on arbitrary boundaries, with writes by
              other processes, whether or not the O_NONBLOCK flag of the
              file status flags is set.

           o  If the O_NONBLOCK flag is clear, a write request may cause the
              process to block, but on normal completion it will return
              nbyte.

           o  If the O_NONBLOCK flag is set, write() requests will  be
              handled differently, in the following ways:

              -  The write() function will not block the process.

              -  A write request for {PIPE_BUF} or fewer bytes  will have
                 the following effect:  If there is sufficient space
                 available in the pipe, write() will transfer all the data
                 and return the number of bytes  requested.  Otherwise,
                 write() will transfer no data and return -1 with errno set
                 to EAGAIN.

              -  A write request for more than {PIPE_BUF} bytes will case
                 one of the following:

                 a. When at least one byte can be written, transfer what it
                    can and return the number of bytes  written. When all
                    data previously written to the pipe is read, it will
                    transfer at least {PIPE_BUF} bytes.





 Hewlett-Packard Company            - 2 -    HP-UX Release 10.20:  July 1996






 write(2)                                                           write(2)




                 b. When no data can be written, transfer no data and return
                    -1 with errno set to EAGAIN.

           When attempting to write to a file descriptor (other than a pipe
           or FIFO) that supports non-blocking writes and cannot accept the
           data immediately:

                o  If the O_NONBLOCK flag is clear, write() will block until
                   the data can be accepted.

                o  If the O_NONBLOCK flag is set, write() will not block the
                   process. If some data can be written without blocking the
                   process, write() will write what it can and return the
                   number of bytes written. Otherwise, it will return -1 and
                   errno will be set to EAGAIN.

           Upon successful completion, where nbyte is greater than 0,
           write() will mark for update the st_ctime and st_mtime fields of
           the file, and if the file is a regular file, the S_ISUID and
           S_ISGID bits of the file mode may be cleared.

           If fildes refers to a STREAM, the operation of write() is
           determined by the values of the minimum and maximum nbyte range
           ("packet size") accepted by the STREAM. These values are
           determined by the topmost STREAM module. If nbyte falls within
           the packet size range, nbyte bytes will be written. If nbyte does
           not fall within the range and the minimum packet size value is 0,
           write() will break the buffer into maximum packet size segments
           prior to sending the data downstream (the last segment may
           contain less than the maximum packet size). If nbyte does not
           fall within the range and the minimum value is non-zero, write()
           will fail with errno set to ERANGE.  Writing a zero-length buffer
           ( nbyte is 0) to a STREAMS device sends 0 bytes with 0 returned.
           However, writing a zero-length buffer to a STREAMS-based pipe or
           FIFO sends no message and 0 is returned. The process may issue
           I_SWROPT ioctl() to enable zero-length messages to be sent across
           the pipe or FIFO.

           When writing to a STREAM, data messages are  created with a
           priority band of 0.  When writing to a STREAM that is not a pipe
           or FIFO:

                o  If O_NONBLOCK is clear, and the STREAM cannot accept data
                   (the STREAM write queue is full due to internal flow
                   control  conditions), write() will block until data can
                   be accepted.

                o  If O_NONBLOCK is set and the STREAM cannot accept data,
                   write() will return -1 and set errno to [EAGAIN].





 Hewlett-Packard Company            - 3 -    HP-UX Release 10.20:  July 1996






 write(2)                                                           write(2)




                o  If O_NONBLOCK is set and part of the buffer has been
                   written while a condition in which the STREAM cannot
                   accept additional data occurs, write() will terminate and
                   return the number of bytes written.

           In addition, write() and writev() will fail if the STREAM head
           had processed an asynchronous error before the call. In this
           case, the value of errno does not reflect the result of write()
           or writev() but reflects the prior error.

           The writev() function is equivalent to write(), but gathers the
           output data from the iovcnt buffers specified by the members of
           the iov array: iov[0], iov[1], iov[iovcnt-1].  iovcnt is valid if
           greater than 0 and less than or equal to {IOV_MAX}, defined in
           <limits.h>.

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

           If fildes refers to a regular file and all of the iov_len members
           in the array pointed to by iov are 0, writev() will return 0 and
           have no other effect.  For other file types, the behaviour is
           unspecified.

           If the sum of the iov_len values is greater than SSIZE_MAX, the
           operation fails and no data is transferred.

 RETURN VALUE
      Upon successful completion, write() will return the number of bytes
      actually written to the file associated with fildes.  This number will
      never be greater than nbyte.  Otherwise, -1 is returned and errno is
      set to indicate the error.

      Upon successful  completion, writev() returns the number of bytes
      actually written. Otherwise, it returns a value of -1, the file-
      pointer remains unchanged, and errno is set to indicate an error.

 ERRORS
      The write() and writev() functions will fail if:

           [EAGAIN]       The O_NONBLOCK flag is set for the file descriptor
                          and the process would be delayed in the write()
                          operation.

           [EBADF]        The fildes argument is not a valid file descriptor
                          open for writing.

           [EFBIG]        An attempt was made to write a file that exceeds
                          the implementation-dependent maximum file size or



 Hewlett-Packard Company            - 4 -    HP-UX Release 10.20:  July 1996






 write(2)                                                           write(2)




                          the process' file size limit.

           [EINTR]        The write operation was terminated due to the
                          receipt of a signal, and no data was transferred.

           [EIO]          A physical I/O error has occurred.

           [EIO]          The process is a member of a background process
                          group 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. This error may
                          also be returned under implementation-dependent
                          conditions.

           [ENOSPC]       There was no free space remaining on the device
                          containing the file.

           [EPIPE]        An attempt is made to write to a pipe or FIFO that
                          is not open for reading by any process, or that
                          only has one end open. A SIGPIPE signal will also
                          be sent to the process.

           [ERANGE]       The transfer request size was outside the range
                          supported by the STREAMS file associated with
                          fildes.

      The writev() function will fail if:

           [EINVAL]       The sum of the iov_len values in the iov array
                          would overflow an ssize_t.

      The write() and writev() functions may fail if:

           [EINVAL]       The STREAM or multiplexer referenced by fildes is
                          linked (directly or indirectly) downstream from a
                          multiplexer.

           [ENXIO]        A request was made of a non-existent device, or
                          the request was outside the capabilities of the
                          device.

           [ENXIO]        A  hangup  occurred  on  the STREAM being written
                          to.

      A write to a STREAMS file may 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.

      The writev() function may fail and set errno to:




 Hewlett-Packard Company            - 5 -    HP-UX Release 10.20:  July 1996






 write(2)                                                           write(2)




           [EINVAL]       The iovcnt argument was less than or equal to 0,
                          or greater than {IOV_MAX}.

 SEE ALSO
      chmod(), creat(), dup(), fcntl(), getrlimit(), lseek(), open(),
      pipe(), ulimit(), <limits.h>, <stropts.h>, <sys/uio.h>, <unistd.h>.

 CHANGE HISTORY
      First released in Issue 1.

      Derived from Issue 1 of the SVID.

 Issue 4
      The following changes are incorporated for alignment with the ISO
      POSIX-1 standard:

           o  The type of the argument buf is changed from char * (Reg.).I
              const void* byte is changed from unsigned size_t.

           o  The DESCRIPTION section is changed:

              -  to indicate that writing at end-of-file is atomic

              -  to identify that {SSIZE_MAX} is now used to determine the
                 maximum value of nbyte

              -  to indicate the consequences of activities after a call to
                 the write() function

              -  To improve clarity, the text describing operations on pipes
                 or FIFOs when O_NONBLOCK is set is restructured.

      Other changes are incorporated as follows:

           o  The header <unistd.h> is added to the SYNOPSIS section.

           o  Reference to ulimit in the DESCRIPTION section is marked as an
              extension.

           o  Reference to the process' file size limit and the ulimit()
              function are marked as extensions in the description of the
              EFBIG error.

           o  The ENXIO error is marked as an extension.

           o  The APPLICATION USAGE section is removed.

           o  The description of EINTR is amended.

 Issue 4, Version 2




 Hewlett-Packard Company            - 6 -    HP-UX Release 10.20:  July 1996






 write(2)                                                           write(2)




      The following changes are incorporated for X/OPEN UNIX conformance:

           o  The writev() function is added to the SYNOPSIS.

           o  The DESCRIPTION is updated to describe the reading of data
              from STREAMS files, an operational description of the writev()
              function is included, and a statement is added indicating that
              SIGXFSZ will be generated if an attempted write operation
              would cause the maximum file size to be exceeded.

           o  The RETURN VALUE section is updated to describe values
              returned by the writev() function.

           o  The ERRORS section has been restructured to describe errors
              that apply to both write() and writev() apart from those that
              apply to writev() specifically. The EIO, ERANGE, and EINVAL
              errors are also added.





































                                    - 7 -         Formatted:  April 25, 2001






 write(2)                                                           write(2)




                                 HP-UX EXTENSIONS



 DESCRIPTION
      The iovec structure of the iov elements is defined as follows:

           struct iovec {
                caddr_t  iov_base;
                int      iov_len;
           };

      For ordinary files, if the O_DSYNC file status flag is set, the write
      does not return until both the file data and the file attributes
      required to retrieve the data are physically updated.  If the O_SYNC
      flag is set, the behavior is identical to that for O_DSYNC, with the
      addition that all file attributes changed by the write operation
      (including access time, modification time and status change time) are
      also physically updated prior to returning to the calling process.

      For block special files, if the O_DSYNC or the O_SYNC flag is set, the
      write does not return until the data is physically updated.  How the
      data reaches the physical media is implementation- and hardware-
      dependent.

      A write to an ordinary file is prevented if enforcement-mode file and
      record locking is set, and another process owns a lock on the segment
      of the file being written:

           If O_NDELAY or O_NONBLOCK is set, the write returns -1 and sets
           errno to EAGAIN.

           If O_NDELAY and O_NONBLOCK are clear, the write does not complete
           until the blocking record lock is removed.

      If the file being written is a pipe (or FIFO), the system-dependent
      maximum number of bytes that it can store is given by PIPSIZ (defined
      in <sys/inode.h>).  The minimum value of PIPSIZ on any HP-UX system is
      8192.  When writing a pipe, the following conditions apply:

           If the O_NDELAY or O_NONBLOCK file status flag is set:

                If nbyte is less than or equal to PIPSIZ and sufficient room
                exists in the pipe or FIFO, the write() succeeds and returns
                the number of bytes written;

                If nbyte is less than or equal to PIPSIZ but insufficient
                room exists in the pipe or FIFO, the write() returns having
                written nothing.  If O_NONBLOCK is set, -1 is returned and
                errno is set to [EAGAIN].  If O_NDELAY is set, 0 is
                returned.



 Hewlett-Packard Company            - 1 -    HP-UX Release 10.20:  July 1996






 write(2)                                                           write(2)




                If nbyte is greater than PIPSIZ and the pipe or FIFO is
                full, the write returns having written nothing.  If
                O_NONBLOCK is set, -1 is returned and errno is set to
                [EAGAIN].  If O_NDELAY is set, 0 is returned.

                If nbyte is greater than PIPSIZ, and some room exists in the
                pipe or FIFO, as much data as fits in the pipe or FIFO is
                written, and write() returns the number of bytes actually
                written, an amount less than the number of bytes requested.

           If the O_NDELAY and O_NONBLOCK file status flags are clear:

                The write() always executes correctly (blocking as
                necessary), and returns the number of bytes written.

      For character special devices, if the stopio() call was used on the
      same device after it was opened (see stopio(2)), write() returns -1,
      sets errno to [EBADF], and issues the SIGHUP signal to the process.

      write() clears the potential and granted privilege vectors on the
      file.

      If the write is performed by any user other than the owner or a user
      who has appropriate privileges, write() clears the set-user-ID, set-
      group-ID, and sticky bits on all nondirectory files.  If the write is
      performed by the owner or a user who has appropriate privileges, the
      behavior is file-system dependent.  In some file systems, the write
      clears the set-user-ID, set-group-ID, and sticky bits on a
      nondirectory file.  In other file systems, the write does not clear
      these bits on a nondirectory file.

      For directories, write() does not clear the set-user-ID, set-group-ID,
      and sticky bits.

 ERRORS
      If write() or writev() fails, the file offset remains unchanged and
      errno is set to one of the following values.

           [EAGAIN]       Enforcement-mode file and record locking was set,
                          O_NDELAY was set, and there was a blocking record
                          lock.

           [EDEADLK]      A resource deadlock would occur as a result of
                          this operation (see lockf(2) and fcntl(2)).

           [EDQUOT]       User's disk quota block limit has been reached for
                          this file system.

           [EFBIG]        The file is a regular file and nbyte is greater
                          than zero and the starting position is greater
                          than or equal to the offset maximum established in



 Hewlett-Packard Company            - 2 -    HP-UX Release 10.20:  July 1996






 write(2)                                                           write(2)




                          the open file description associated with fildes.

           [ENOLCK]       The system record lock table is full, preventing
                          the write from sleeping until the blocking record
                          lock is removed.

           [ENOSPC]       Not enough space on the file system.  The process
                          does not possess the limit effective privilege to
                          override this restriction.

      If writev() fails, the file offset remains unchanged and errno is set
      to one of the following values:

           [EFAULT]       iov_base or iov points outside of the allocated
                          address space.  The reliable detection of this
                          error is implementation dependent.

           [EINVAL]       One of the iov_len values in the iov array is
                          negative.

      If write() or writev() fails, the file offset is updated to reflect
      the amount of data transferred and errno is set to one of the
      following values.

           [EFAULT]       buf points outside the process's allocated address
                          space.  The reliable detection of this error is
                          implementation dependent.

 EXAMPLES
      Assuming a process opened a file for writing, the following call to
      write() attempts to write mybufsize bytes to the file from the buffer
      to which mybuf points.

           #include <string.h>

           int fildes;
           size_t mybufsize;
           ssize_t nbytes;
           char *mybuf = "aeiou and sometimes y";
           mybufsize = (size_t)strlen (mybuf);
           nbytes = write (fildes, (void *)mybuf, mybufsize);

 WARNINGS
      Check signal(5) for the appropriateness of signal references on
      systems that support sigvector() (see sigvector(2)).  sigvector() can
      affect the behavior described on this page.

      Character special devices, and raw disks in particular, apply
      constraints on how write() can be used.  See specific Section 7 manual
      entries for details on particular devices.




 Hewlett-Packard Company            - 3 -    HP-UX Release 10.20:  July 1996






 write(2)                                                           write(2)




 AUTHOR
      write() was developed by HP, AT&T, the University of California,
      Berkeley, and SecureWare Inc.

 SEE ALSO
      mkfs(1M) creat(2), dup(2), fcntl(2), lockf(2), lseek(2), open(2),
      pipe(2), sigvector(2), stopio(2) ulimit(2), ustat(2), signal(5).

 STANDARDS CONFORMANCE
      write(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1,
      POSIX.4











































 Hewlett-Packard Company            - 4 -    HP-UX Release 10.20:  July 1996