readv() — Read data on a file or socket and store in a set of buffers
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
XPG4.2 |
both |
Format
#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/uio.h>
ssize_t readv(int fs, const struct iovec *iov, int iovcnt);
#define _OE_SOCKETS
#include <sys/uio.h>
int readv(int fs, struct iovec *iov, int iovcnt);
General description
- Parameter
- Description
- fs
- The file or socket descriptor.
- iov
- A pointer to an iovec structure.
- iovcnt
- The number of buffers pointed to by the iov parameter.
- Element
- Description
- iov_base
- The pointer to the buffer.
- iov_len
- The length of the buffer.
This call returns a number of bytes of data equal to but not exceeding the sum of all the iov_len fields. If less than the number of bytes requested is available, the call returns the number currently available. If data is not available for the socket fs, and the socket is in blocking mode, readv() call blocks the caller until data arrives. If data is not available and fs is in nonblocking mode, readv() returns a -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.
For datagram sockets, this call returns the entire datagram that was sent, provided that the datagram fits into the specified buffer. Excess datagram data is discarded. Stream sockets act like streams of information with no boundaries separating data. For example, if applications A and B are connected with a stream socket and application A sends 1000 bytes, each call to this function can return 1 byte, or 10 bytes, or the entire 1000 bytes. Therefore, applications using stream sockets should place this call in a loop, calling this function until all data has been received.
For X/Open sockets, if the total number of bytes to read is 0, readv() returns 0. If readv() is for a file and no data is available, readv() returns 0. If a readv() is interrupted by a signal before it reads any data, it returns -1 with errno set to EINTR. If readv() is interrupted by a signal after it has read data, it returns the number of bytes read. If fs refers to a socket, readv() is the equivalent of recv() with no flags set.
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, readv() returns the number of bytes read into the buffer.
If the connection is broken on a stream socket and data is available, then the readv() function reads the data and gives no error. If the connection is broken on a stream socket and no data is available, then the readv() function returns 0 bytes as EOF.
- Error Code
- Description
- EAGAIN
- The O_NONBLOCK flag is set for the file descriptor and the process would be delayed by the readv().
- EBADF
- fs is not a valid file or socket descriptor.
- ECONNRESET
- A connection was forcibly closed by a peer.
- EFAULT
- Using iov and iovcnt would result in an attempt to access storage outside the caller's address space.
- EINTR
- readv() was interrupted by a signal that was caught before any data was available.
- EINVAL
- iovcnt was not valid, or one of the fields in the iov array was not valid.
- ENOBUFS
- Insufficient system resources are available to complete the call.
- ENOTCONN
- A receive is attempted on a connection-oriented socket that is not connected.
- ETIMEDOUT
- The connection timed out during connection establishment, or due to a transmission timeout on active connection.
- EWOULDBLOCK
- socket is in nonblocking mode and data is not available to read. or the SO_RCVTIMEO timeout value was been reached before data was 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
- 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
- writev() — Write data on a file or socket from an array