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.