*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> write (2)              



NAME    [Toc]    [Back]

     write, writev, pwrite, pwritev - write output

SYNOPSIS    [Toc]    [Back]

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

     write(int d, const void *buf, size_t nbytes);

     pwrite(int d, const void *buf, size_t nbytes, off_t offset);

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

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

     pwritev(int  d,  const  struct iovec *iov, int iovcnt, off_t

DESCRIPTION    [Toc]    [Back]

     write() attempts to write nbytes of data to the object  referenced by the
     descriptor  d  from  the buffer pointed to by buf.  writev()
performs the
     same action, but gathers the output  data  from  the  iovcnt
buffers specified
  by  the members of the iov array: iov[0], iov[1], ...,
     pwrite() and pwritev() perform the same functions, but write
to the specified
 position in the file without modifying the file pointer.

     For writev() and pwritev(), the iovec structure  is  defined

           struct iovec {
                   void *iov_base;
                   size_t iov_len;

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

     On objects capable of seeking, the write() starts at a position given by
     the pointer associated with d (see lseek(2)).   Upon  return
from write(),
     the pointer is incremented by the number of bytes which were

     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 real user is not the superuser, then  write()  clears
the set-userID
 bit on a file.  This prevents penetration of system security by a user
     who ``captures'' a writable set-user-ID file  owned  by  the

     If write() succeeds it will update the st_ctime and st_mtime
fields of
     the file's meta-data (see stat(2)).

     When using non-blocking I/O on objects such as sockets  that
are subject
     to  flow control, write() and writev() may write fewer bytes
than requested;
 the return value must be noted, and the remainder of the
     should be retried when possible.

     Note  that  writev() and pwritev() will fail if the value of
iovcnt exceeds
     the constant IOV_MAX.

RETURN VALUES    [Toc]    [Back]

     Upon successful completion the number of  bytes  which  were
written is returned.
  Otherwise, a -1 is returned and the global variable
errno is set
     to indicate the error.

ERRORS    [Toc]    [Back]

     write(), pwrite(), writev(), and pwritev() will fail and the
file pointer
     will remain unchanged if:

     [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.

     [EPIPE]        An  attempt  is  made to write to a socket of
                   that is not connected to a peer socket.

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

     [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.

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

     In addition, write() and pwrite() may return  the  following

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

     [EINVAL]      nbytes was larger than SSIZE_MAX.

     Also, writev() and pwritev() may return one of the following

                   The  destination  is  no longer available when
writing to a
                   UNIX domain  datagram  socket  on  which  connect(2) had been
                   used to set a destination address.

     [EINVAL]      iovcnt was less than or equal to 0, or greater

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

SEE ALSO    [Toc]    [Back]

     fcntl(2), lseek(2), open(2), pipe(2), poll(2), select(2)

STANDARDS    [Toc]    [Back]

     The  write()  function  conforms  to  IEEE  Std  1003.1-1990
(``POSIX'').  The
     writev() and pwrite() functions conform to X/Open Portability Guide Issue
     4.2 (``XPG4.2'').

HISTORY    [Toc]    [Back]

     The  pwritev()  function  call appeared in OpenBSD 2.7.  The
pwrite() function
 call appeared in AT&T System V.4  UNIX.   The  writev()
function call
     appeared  in  4.2BSD.  The write() function call appeared in
Version 2 AT&T

CAVEATS    [Toc]    [Back]

     Error checks should explicitly test for -1.  Code such as

           while ((nr = write(fd, buf, sizeof(buf))) > 0)

     is not maximally  portable,  as  some  platforms  allow  for
nbytes to range
     between SSIZE_MAX and SIZE_MAX - 2, in which case the return
value of an
     error-free write() may appear as a negative number  distinct
from -1.
     Proper loops should use

           while  ((nr = write(fd, buf, sizeof(buf))) != -1 && nr
!= 0)

OpenBSD     3.6                           July      28,      1998
[ Back ]
 Similar pages
Name OS Title
echo OpenBSD write arguments to the standard output
echo FreeBSD write arguments to the standard output
putwchar Linux write a wide character to standard output
printf Tru64 General: Write formatted text to some output device
uprintf Tru64 General: Write formatted text to some output device
strace HP-UX write STREAMS event trace messages to standard output
tee Linux read from standard input and write to standard output and files
fs_async HP-UX enables write calls to return before write operation is complete (Boolean)
tis_write_unlock Tru64 Unlocks the specified read-write lock that was acquired for write access
tis_write_lock Tru64 Acquires the specified read-write lock for write access
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service