NAME
read,
readv,
pread,
preadv —
read input
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <unistd.h>
ssize_t
read(
int d,
void *buf,
size_t nbytes);
ssize_t
pread(
int
d,
void *buf,
size_t nbytes,
off_t offset);
#include <sys/uio.h>
ssize_t
readv(
int
d,
const struct iovec
*iov,
int iovcnt);
ssize_t
preadv(
int
d,
const struct iovec
*iov,
int iovcnt,
off_t offset);
DESCRIPTION
read() attempts to read
nbytes of data
from the object referenced by the descriptor
d into the
buffer pointed to by
buf.
readv()
performs the same action, but scatters the input data into the
iovcnt buffers specified by the members of the
iov array: iov[0], iov[1], ..., iov[iovcnt-1].
pread() and
preadv() perform the same
functions, but read from the specified position in the file without modifying
the file pointer.
For
readv() and
preadv(), the
iovec structure is defined as:
struct iovec {
void *iov_base;
size_t iov_len;
};
Each
iovec entry specifies the base address and length of
an area in memory where data should be placed.
readv() will
always fill an area completely before proceeding to the next.
On objects capable of seeking, the
read() starts at a position
given by the file pointer associated with
d (see
lseek(2)). Upon return from
read(), the file pointer is incremented by the number of
bytes actually read.
Objects that are not capable of seeking always read from the current position.
The value of the file pointer associated with such an object is undefined.
Upon successful completion,
read(),
readv(),
pread(), and
preadv() return the number of
bytes actually read and placed in the buffer. The system guarantees to read
the number of bytes requested if the descriptor references a normal file that
has that many bytes left before the end-of-file, but in no other case.
RETURN VALUES
If successful, the number of bytes actually read is returned. Upon reading
end-of-file, zero is returned. Otherwise, a -1 is returned and the global
variable
errno is set to indicate the error.
ERRORS
read(),
readv(),
pread(),
and
preadv() will succeed unless:
-
-
- [
EAGAIN
]
- The file was marked for non-blocking I/O, and no data were
ready to be read.
-
-
- [
EBADF
]
- d is not a valid file or socket
descriptor open for reading.
-
-
- [
EFAULT
]
- buf points outside the allocated
address space.
-
-
- [
EINTR
]
- A read from a slow device (i.e. one that might block for an
arbitrary amount of time) was interrupted by the delivery of a signal
before any data arrived. See
sigaction(2) for more
information on the interaction between signals and system calls.
-
-
- [
EINVAL
]
- The file pointer associated with d
was negative; or the total length of the I/O is more than can be expressed
by the ssize_t return value.
-
-
- [
EIO
]
- An I/O error occurred while reading from the file
system.
-
-
- [
EISDIR
]
- d refers to a directory and the
implementation does not allow the directory to be read using
read() or pread(). The
readdir() function should be used instead.
In addition,
readv() and
preadv() may return
one of the following errors:
-
-
- [
EFAULT
]
- Part of the iov points outside the
process's allocated address space.
-
-
- [
EINVAL
]
- iovcnt was less than or equal to 0,
or greater than {
IOV_MAX
}; or one of the
iov_len values in the iov
array was negative; or the sum of the iov_len values
in the iov array overflowed a 32-bit integer.
The
pread() and
preadv() calls may also
return the following errors:
-
-
- [
EINVAL
]
- The specified file offset is invalid.
-
-
- [
ESPIPE
]
- The file descriptor is associated with a pipe, socket, or
FIFO.
SEE ALSO
dup(2),
fcntl(2),
open(2),
pipe(2),
poll(2),
select(2),
sigaction(2),
socket(2),
socketpair(2)
STANDARDS
The
read() function conforms to
IEEE Std
1003.1-1990 (“POSIX.1”). The
readv() and
pread() functions conform to
X/Open
Portability Guide Issue 4, Version 2 (“XPG4.2”).
HISTORY
The
preadv() function call appeared in
NetBSD
1.4. The
pread() function call appeared in
AT&T System V Release 4 UNIX. The
readv() function call appeared in
4.2BSD. The
read() function call
appeared in
Version 2 AT&T UNIX.
CAVEATS
Error checks should explicitly test for -1. Code such as
while ((nr = read(fd, buf, sizeof(buf))) > 0)
is not maximally portable, as some platforms allow for
nbytes to range between
SSIZE_MAX
and
SIZE_MAX
- 2, in
which case the return value of an error-free
read() may
appear as a negative number distinct from -1. Proper loops should use
while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0)