readv()

Read bytes from a file

Synopsis:

#include <sys/uio.h>

ssize_t readv( int fildes,
               const iov_t* iov,
               int nparts );

Arguments:

fildes: The descriptor of the file that you want to read from.
iov: An array of iov_t objects where the function can store the data that it reads. The combined size (i.e., the sum of the length values) of the objects must not exceed SSIZE_MAX (see <limits.h>), or the function fails and sets errno to EINVAL.
nparts: The number of entries in the iov array. The maximum number of entries is UIO_MAXIOV.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The readv() function attempts to read from the file associated with the open file descriptor, fildes, placing the data into nparts buffers specified by the members of the iov array: iov[0], iov[1], … iov[nparts - 1].

On a regular file or other file capable of seeking, readv() starts at a position in the file given by the file offset associated with fildes. Before successfully returning from readv(), the file offset is incremented by the number of bytes actually read.

The iov_t structure contains the following members:

iov_base: The base address of a memory area where data should be placed.
iov_len: The length of the memory area.

The readv() function always fills one buffer completely before proceeding to the next.

Note: The readv() call ignores advisory locks that may have been set by the fcntl() function.

On a file not capable of seeking, readv() starts at the current position.

When readv() returns successfully, its return value is the number of bytes actually read and placed in the buffer. This number will never be greater than the combined sizes of the iov buffers, although it may be less for one of the following reasons:

The number of bytes left in the file is less than the combined size of the iov buffers.
The readv() request was interrupted by a signal.
The file is a pipe (or FIFO) or a special file, and has fewer bytes immediately available for reading. For example, reading from a file associated with a terminal may return one typed line of data.

If readv() is interrupted by a signal before it reads any data, it returns -1 and sets errno to EINTR. However, if readv() is interrupted by a signal after it has successfully read some data, it returns the number of bytes read.

No data is transferred past the current end-of-file. If the starting position is at or after the end-of-file, readv() returns zero. If the file is a device special file, the result of subsequent calls to readv() will work, based on the then current state of the device (that is, the end of file is transitory).

When attempting to read from an empty pipe or FIFO:

If no process has the pipe open for writing, readv() returns 0 to indicate end-of-file.
If a process has the pipe open for writing, and O_NONBLOCK is set, readv() returns -1 and sets errno to EAGAIN.
If a process has the pipe open for writing, and O_NONBLOCK is clear, read() blocks until some data is written, or the pipe is closed by all processes that had opened it for writing.

When attempting to read from a file (other than a pipe or FIFO) that supports nonblocking reads and has no data currently available:

If O_NONBLOCK is set, readv() returns -1 and sets errno to EAGAIN.
If O_NONBLOCK is clear, readv() blocks until some data is available.
The O_NONBLOCK flag has no effect if some data is available.

If you call readv() on a portion of a file, prior to the end-of-file, that hasn't been written, it returns bytes with the value zero.

If readv() succeeds, the st_atime field of the file is marked for update.

Returns:

The number of bytes read, or -1 if an error occurred (errno is set).

Errors:

EAGAIN: The O_NONBLOCK flag is set for the file descriptor, and the process would be delayed in the read operation.
EBADF: The file descriptor, fildes, isn't a valid file descriptor open for reading.
EINTR: The read operation was interrupted by a signal, and either no data was transferred, or the resource manager responsible for that file doesn't report partial transfers.
EINVAL: The nparts argument is less than or equal to 0, or greater than UIO_MAXIOV. Or, an attempt was made to read a number bytes that exceeds the allowable limit.
EIO: A physical I/O error occurred (for example, a bad block on a disk). The precise meaning is device-dependent.
EISDIR: The file descriptor is for a directory.
ENOSYS: The readv() function isn't implemented for the filesystem specified by fildes.

Classification:

POSIX 1003.1 XSI

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	Yes
Thread	Yes