HP-UX Reference (11i v3 07/02) - 2 System Calls (vol 5)

r
read(2) read(2)
Upon successful completion, readv() marks for update the st_atime field of the file.
The
pread() function performs the same action as
read(), except that it reads from a given position in
the file without changing the file pointer. The first three arguments of
pread() are the same as read()
with the addition of a fourth argument offset
for the desired position inside the file. An attempt to per-
form a
pread() on a file that is incapable of seeking results in an error.
RETURN VALUE
Upon successful completion, read() returns the number of bytes actually read and placed in the buffer;
this number may be less than nbyte if:
• The file is associated with a communication line (see ioctl(2) and termio(7)), or
• The number of bytes left in the file is less than nbyte bytes.
•
read() was interrupted by a signal after it had successfully read some, but not all of the data
requested.
When an end-of-file is reached, a value of 0 is returned. Otherwise, a −1 is returned and
errno is set to
indicate the error.
Upon successful completion,
pread() and readv() return a non-negative integer indicating the number
of bytes actually read. Otherwise, the functions return −1 and set errno to indicate the error.
ERRORS
The
read(), pread() and readv() functions will fail if:
[EAGAIN] Enforcement-mode file and record locking is set,
O_NDELAY or O_NONBLOCK is
set, and there is a blocking write lock.
[EBADF] The fildes argument is not a valid file descriptor open for reading.
[EBADMSG] The file is a
STREAM file that is set to control-normal mode and the message wait-
ing to be read includes a control part.
[EDEADLK] A resource deadlock would occur as a result of this operation (see lockf(2) and
fcntl(2)).
[EFAULT] buf points outside the allocated address space. Reliable detection of this error is
implementation dependent.
[EINTR] A signal was caught before any data was transferred (see signal(5)).
[EINVAL] The starting file offset associated with fildes is greater than the maximum sup-
ported file size.
[EINVAL] The
STREAM or multiplexer referenced by fildes is linked (directly or indirectly)
downstream from a multiplexer.
[EIO] A physical I/O error has occurred.
[EIO] The process is a member of a background process attempting to read from its con-
trolling terminal, the process is ignoring or blocking the
SIGTTIN signal or the
process group is orphaned. This error may also be generated for
implementation-dependent reasons.
[EISDIR] The fildes argument refers to a directory and the implementation does not allow
the directory to be read using read(), pread() or readv(). The read-
dir()
function should be used instead.
[ENOLCK] The system record lock table is full, preventing the read from sleeping until the
blocking write lock is removed.
The readv() function will fail if:
[EINVAL] The sum of the iov_len values in the iov array overflowed an ssize_t.
[EFAULT] iov_base or iov points outside of the allocated address space. The reliable detection
of this error is implementation-dependent.
The read(), pread() and readv() functions may fail if:
[ENXIO] A request was made of a non-existent device, or the request was outside the capa-
bilities of the device.
330 Hewlett-Packard Company − 3 − HP-UX 11i Version 3: February 2007