writev() — Write data on a file or socket from an array

Standards

Standards / Extensions	C or C++	Dependencies
XPG4.2 Single UNIX Specification, Version 3	both

Format

X/Open:

#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/uio.h>

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

Berkeley sockets:

#define _OE_SOCKETS
#include <sys/uio.h>

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

General description

The writev() function writes data to a file or socket with descriptor fs from a set of buffers. The data is gathered from the buffers specified by iov[0]…iov[iovcnt-1]. When the descriptor refers to a socket, it must be a connected socket.

Parameter: Description
fs: The file or socket descriptor.
iov: A pointer to an array of iovec buffers.
iovcnt: The number of buffers pointed to by the iov parameter.

The iovec structure is defined in uio.h and contains the following fields:

Element: Description
iov_base: Pointer to the buffer.
iov_len: Length of the buffer.

This call writes the sum of the iov_len bytes of data.

If there is not enough available buffer space to hold the socket data to be transmitted, and the socket is in blocking mode, writev() blocks the caller until additional buffer space becomes available. If the socket is in a nonblocking mode, writev() returns -1 and sets the error code to EWOULDBLOCK. See fcntl() — Control open file descriptors or ioctl() — Control device for a description of how to set nonblocking mode.

When the socket is not ready to accept data and the process is trying to write data to the socket:

Unless FNDELAY or O_NONBLOCK is set, writev() blocks until the socket is ready to accept data.
If FNDELAY is set, writev() returns a 0.
If O_NONBLOCK is set, writev() does not block the process. If some data can be written without blocking the process, writev() writes what it can and returns the number of bytes written. Otherwise, it sets the error code to EAGAIN and returns -1.

For datagram sockets, this call sends the entire datagram, provided that the datagram fits into the TCP/IP buffers. Stream sockets act like streams of information with no boundaries separating data. For example, if an application program wishes to send 1000 bytes, each call to this function can send 1 byte, or 10 bytes, or the entire 1000 bytes. Therefore, application programs using stream sockets should place this call in a loop, calling this function until all data has been sent.

Special behavior for C++: To use this function with C++, you must use the _XOPEN_SOURCE_EXTENDED 1 feature test macro.

Returned value

If successful, writev() returns the number of bytes written from the buffer.

A value of 0 or greater indicates the number of bytes sent, however, this does not assure that data delivery was complete. A connection can be dropped by a peer socket and a SIGPIPE signal generated at a later time if data delivery is not complete.

If unsuccessful, writev() returns -1 and sets errno to one of the following values:

Error Code: Description
EAGAIN: Resources temporarily unavailable. Subsequent requests may complete normally.
EBADF: fs is not a valid file or socket descriptor.
ECONNRESET: A connection was forcibly closed by a peer.
EDESTADDRREQ: The socket is not connection-oriented and no peer address is set.
EFAULT: Using the iov and iovcnt parameters would result in an attempt to access storage outside the caller's address space.
EINTR: A signal interrupted writev() before any data was transmitted.
EINVAL: An incorrect value for iocvnt was detected.
EMSGSIZE: The message was too big to be sent as a single datagram.
ENOBUFS: Buffer space is not available to send the message.
ENOTCONN: The socket is not connected.
EPIPE: For a connected stream socket the connection to the peer socket has been lost. A SIGPIPE signal is sent to the calling process.
EPROTOTYPE: The protocol is the wrong type for this socket. A SIGPIPE signal is sent to the calling process.
EWOULDBLOCK: socket is in nonblocking mode and no data buffers are available or the SO_SNDTIMEO timeout value was reached before buffers became available.