WRITEV(2,L) AIX Technical Reference WRITEV(2,L)
-------------------------------------------------------------------------------
writev
PURPOSE
Writes output gathered from multiple buffers.
SYNTAX
#include <sys/uio.h>
int writev (d, iov, iovcnt)
int d;
struct iovec *iov;
int iovcnt;
DESCRIPTION
The writev system call attempts to write the data in the buffers specified by
the array of iovec structures, pointed to by the iov parameter, to the object
associated with the d parameter.
The d parameter is a file descriptor obtained from a creat, open, dup, fcntl,
or pipe system call, or a socket descriptor from a socket or socketpair system
call.
The iovec structure is defined in the sys/uio.h header file, and it contains
the following members:
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. The writev system call always writes a
complete area before moving to the next.
On devices capable of seeking, writev starts at a position in the file given by
the file pointer associated with the d parameter. Upon return from the writev
system call, the file pointer is incremented by the number of bytes actually
written.
Devices that are incapable of seeking always write at the current position.
The value of a file pointer associated with such a file is undefined.
When the O_APPEND flag of the file status is set, the file pointer is set to
the end of the file prior to each write.
If a file is opened with the O_DEFERC flag, changes made to it with writev can
later be undone with the fabort system call. Changes are not made permanent
until the file is committed explicitly by calling fsync or implicitly some time
Processed November 7, 1990 WRITEV(2,L) 1
WRITEV(2,L) AIX Technical Reference WRITEV(2,L)
after calling close or exiting, at which time all files are closed. (See
"fabort," "fsync, fcommit," and "close, closex.")
If the file is opened with the O_SYNC or O_REPLSYNC flags, changes are made
permanent and possibly replicated. (See "fcntl, flock, lockf," "open, openx,
creat," and "write, writex.")
If the writev system call requests that more bytes be written than there is
room for, only as many bytes as there is room for are written and the writev
system call returns an integer equal to the number of bytes written. The next
attempt to write nonzero number of bytes will fail (except as noted following).
The limit reached can be either the ulimit (see "ulimit") or the end of the
physical medium. A partial write is not permitted for the following:
o If the file being written is a pipe (or FIFO) and unless O_NDELAY or
O_NONBLOCK is set in the file flag word, then a writev to a full pipe (or
FIFO) blocks until space becomes available.
o If the file being written is a pipe (or FIFO) and O_NDELAY is set in the
file flag word, then a writev to a full pipe (or FIFO) returns a count of
0.
o If the file being written is a pipe (or FIFO) and O_NONBLOCK is set in the
file flag word, then a writev to a full pipe (or FIFO) returns -1 and errno
is set to EAGAIN.
When attempting to write to a socket and the socket is not ready to accept
data:
o Unless O_NDELAY or O_NONBLOCK is set, the writev blocks until the socket is
ready to accept data.
o If O_NDELAY is set, the writev returns 0.
o If O_NONBLOCK is set, the writev returns -1 and errno is set to EAGAIN.
If the file to be written supports enforcement mode record locks and all or
part of the region to be written is currently locked by another process:
o If O_NDELAY or O_NONBLOCK is set, then writev returns -1 and sets errno to
EAGAIN.
o If O_NDELAY and O_NONBLOCK are not set, then the calling process blocks
until the lock is released.
For more information about record locks, see "fcntl, flock, lockf."
If the Transparent Computing Facility is installed on your system, when writing
to a file which is stored on a site other than where the process is running, it
is possible for the out-of-space condition to go unnoticed until after the
write system call has returned. If this situation arises, the ENOSPC error
will be reported on subsequent write, fcommit, and fabort calls. The system
Processed November 7, 1990 WRITEV(2,L) 2
WRITEV(2,L) AIX Technical Reference WRITEV(2,L)
attempts to minimize the likelihood of out-of-space problems getting reported
in this way by using a less efficient, synchronous procedure for writing to a
remote file system when that file system is low on space. Thus, writing to a
remote file system is most efficient when the file system is less than 90%
full.
RETURN VALUE
Upon successful completion, writev returns the number of bytes that were
actually written. Otherwise, the value -1 is returned and errno is set to
indicate the error.
ERROR CONDITIONS
The writev system call fails when one or more of the following is true:
EBADF The d parameter is not a valid file descriptor open for writing or a
valid socket descriptor.
EAGAIN An enforcement mode record lock is outstanding in the portion of the
file that is to be written.
EAGAIN The object is a socket or pipe and is marked for nonblocking I/O, and
the socket or pipe was not ready to accept data.
EPIPE An attempt is made to write to a pipe that is not open for reading by
any process or to write to a socket of type SOCK_STREAM that is not
connected to a peer socket. A SIGPIPE signal is also sent to the
calling process.
EFBIG An attempt is made to write to a file that exceeds the process's file
size limit or the maximum file size (see "ulimit").
EINVAL The value of iovcnt was not between 1 and 16, inclusive.
EINVAL One of the iov_len values in the iov array was negative.
EINVAL The sum of the iov_len values in the iov array overflowed a 32-bit
integer.
EFAULT Part of the iov points to a location outside of the process's
allocated address space.
EDEADLK A deadlock would occur if the calling process were to sleep until the
region to be written was unlocked.
EINTR A signal was caught during the writev system call.
ENODEV The file specified is an invalid device for writing.
EIO A physical I/O error occurred.
Processed November 7, 1990 WRITEV(2,L) 3
WRITEV(2,L) AIX Technical Reference WRITEV(2,L)
If the Transparent Computing Facility is installed on your system, writev can
also fail if one or more of the following are true:
ESITEDN1 The file cannot be written because the file storage site went down.
If the file is replicated, this indicates the loss of the site where
the primary copy of the file is stored.
ESITEDN2 The operation was terminated because a site failed.
RELATED INFORMATION
In this book: "fcntl, flock, lockf," "lseek," "open, openx, creat," "pipe,"
"select," and "write, writex."
Processed November 7, 1990 WRITEV(2,L) 4