READ(2) | System Calls Manual | READ(2) |
read
, readv
,
pread
, preadv
—
#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);
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.
read
(), readv
(),
pread
(), and preadv
() will
succeed unless:
EAGAIN
]EBADF
]EFAULT
]EINTR
]EINVAL
]EIO
]EISDIR
]read
() or
pread
(). The readdir
()
function should be used instead.In addition, readv
() and
preadv
() may return one of the following errors:
EFAULT
]EINVAL
]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:
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”).
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 1 AT&T UNIX.
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 2, 2019 | NetBSD 9.0 |