readv() read file into vector of buffers	Function
	SYNOPSIS DESCRIPTION PARAMETERS RETURN VALUES CONFORMANCE MULTITHREAD SAFETY LEVEL PORTING ISSUES AVAILABILITY SEE ALSO

---

SYNOPSIS

#include <unistd.h>

#include <sys/uio.h>

ssize_t readv(int fildes, const struct iovec *iov, int iovcnt);

---

DESCRIPTION

The read() function attempts to read data from the specified file descriptor into the specified vector of buffers. The iovec structure contains two fields: iov_base, which specifies the base address for the buffer, and iov_len, which specifies the size of the buffer. Each buffer is filled completely before proceeding to the next.

On file that support seeking, such as regular files, readv() starts at a position in the file given by the offset associated with the file descriptor. The file offset is incremented by the number of bytes actually read.

On files that do not support seeking, such as terminals, reads always occur from the current position. The value of a file offset associated with such a file is undefined.

No data transfer occurs past the current end-of-file. If the starting position is at or after the end-of-file, 0 is returned. If the file refers to a device or special file, the result of subsequent readv() requests is unspecified.

Reads larger than SSIZE_MAX are unsupported.

When attempting to read from an empty pipe or FIFO:

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

When attempting to read a file (other than a pipe or FIFO) that supports non-blocking 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 the calling thread until some data becomes available.
• The use of the O_NONBLOCK flag has no effect if there is some data available.

The readv() function reads data previously written to a file. If any portion of a regular file prior to the end-of-file has not been written, readv() returns bytes with value 0. For example, lseek() allows the file offset to be set beyond the end of existing data in the file. If data is later written at this point, subsequent reads in the gap between the previous end of data and the newly written data returns bytes with value 0 until data is written into the gap.

Upon successful completion, readv() marks for update the st_atime field of the file, and return the number of bytes read.

---

PARAMETERS

fildes 

Is the file descriptor that references an open file.

iov 

Points to an array of iovec structures defining buffers to be filled in.

iovcnt 

Is the number of entries in the iov array. This must be greater than 0 and less than or equal to IOV_MAX.

---

RETURN VALUES

If successful, readv() returns a non-negative integer that indicates the number of bytes read. The number of bytes read may be less than the number of bytes requested in any of the following conditions:

• The number of bytes left in the file is less than the requested length.
• The read() was interrupted by a signal.
• The file is a pipe or FIFO or special device and has fewer bytes than requested immediately available for reading.

On error, readv() returns -1, and sets errno to one of the following values:

EAGAIN 

The O_NONBLOCK flag is set for the file descriptor and the process would be delayed.

EBADF 

The fildes parameter is not a valid file descriptor open for reading.

EFAULT 

The buf parameter is not a valid pointer, or the buffer was overrun during the readv() request.

EINTR 

The readv() request was interrupted by a signal.

EINVAL 

The iovcnt parameter is less than 1 or greater than IOV_MAX.

The sum of the iov_len values in the iov array overflowed an ssize_t.

EIO 

A physical I/O error occurred.

EISDIR 

The fildes parameter refers to a directory. Use readdir() to read from directories.

ENXIO 

A request was made of a non-existent device, or the request was outside the capabilities of the device.

EOVERFLOW 

The file is a regular file, the number of bytes requested is greater than 0, the starting position is before the end-of-file, and the starting position is greater than or equal to the offset maximum established in the open file description associated with fildes.

---

CONFORMANCE

UNIX 98, with exceptions.

---

MULTITHREAD SAFETY LEVEL

MT-Safe.

---

PORTING ISSUES

Refer to File Management in the Windows Concepts chapter of the PTC MKS Toolkit UNIX to Windows Porting Guide for a detailed discussion of file handling, including a discussion of text mode and binary mode for files.

The test which causes the EOVERFLOW error condition to be returned can be disabled by using the _NutConf() function to turn off the _NC_SET_FULL_LFS_SEMANTICS flag.

---

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

---

SEE ALSO

Functions:

creat(), dup(), dup2(), fcntl(), ioctl(), lseek(), open(), pipe(), read(), readdir(), socket(), write(), writev()

---

PTC MKS Toolkit 10.5 Documentation Build 40.