READ(2) | System Calls Manual | READ(2) |
read
, readv
,
pread
, preadv
—
read input
#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);
#include
<sys/types.h>
#include <sys/uio.h>
ssize_t
preadv
(int
d, const struct iovec
*iov, int iovcnt,
off_t offset);
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 offset 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
() and
preadv
()
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 pointer associated with
d (see
lseek(2)). Upon return from
read
(), the 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 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.
Note that
readv
() and
preadv
()
will fail if the value of iovcnt exceeds the constant
IOV_MAX
.
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.
read
(), readv
(),
pread
(), and preadv
() will
succeed unless:
EBADF
]EFAULT
]EINTR
]EIO
]EISDIR
]In addition, read
() and
readv
() may return the following errors:
EAGAIN
]ENOTCONN
]EIO
]SIGTTIN
signal or the process group is
orphaned.read
() and pread
()
may return the following error:
EINVAL
]SSIZE_MAX
.pread
() and
preadv
() may return the following errors:
readv
() and
preadv
() may return one of the following errors:
dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socket(2), socketpair(2)
The read
(),
readv
(), and pread
()
functions conform to IEEE Std 1003.1-2008
(“POSIX.1”).
A read
() system call first appeared in
Version 1 AT&T UNIX;
readv
() in 4.1cBSD;
pread
() in AT&T System V
Release 4 UNIX; and preadv
() in
OpenBSD 2.7.
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)
September 30, 2016 | OpenBSD-6.4 |