writev() — Write data on a file or socket from an array
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
XPG4.2 |
both |
Format
#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/uio.h>
ssize_t writev(int fs, const struct iovec *iov, int iovcnt);
#define _OE_SOCKETS
#include <sys/uio.h>
int writev(int fs, struct iovec *iov, int iovcnt);
General description
- 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.
- 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.
- 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.
- 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.
Related information
- sys/uio.h
- connect() — Connect a socket
- fcntl() — Control open file descriptors
- getsockopt() — Get the options associated with a socket
- ioctl() — Control device
- read() — Read from a file or socket
- readv() — Read data on a file or socket and store in a set of buffers
- recv() — Receive data on a socket
- recvfrom() — Receive messages on a socket
- recvmsg() — Receive messages on a socket and store in an array of message headers
- select(), pselect() — Monitor activity on files or sockets and message queues
- selectex() — Monitor activity on files or sockets and message queues
- send() — Send data on a socket
- sendmsg() — Send messages on a socket
- sendto() — Send data on a socket
- setsockopt() — Set options associated with a socket
- socket() — Create a socket
- write() — Write data on a file or socket