Updated: October 28, 2024 |
Read bytes from a file
#include <sys/uio.h> ssize_t readv( int filedes, const iov_t* iov, int nparts );
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
The readv() function attempts to read from the file associated with the open file descriptor, filedes, 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 filedes. 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:
The readv() function always fills one buffer completely before proceeding to the next.
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. POSIX requires that this number never be greater than the combined sizes of the iov buffers, but that depends on the underlying resource manager. The number may be less than the combined sizes if, for example:
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:
When attempting to read from a file (other than a pipe or FIFO) that supports nonblocking reads and has no data currently 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.
The number of bytes read, or -1 if an error occurred (errno is set).
Safety: | |
---|---|
Cancellation point | Yes |
Interrupt handler | No |
Signal handler | Yes |
Thread | Yes |