HP-UX Reference (11i v2 03/08) - 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 perform 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 waiting
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 sigvector (2)).
[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 readdir() func-
tion 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 capabil-
ities of the device.
Section 2−−274 Hewlett-Packard Company − 3 − HP-UX 11i Version 2: August 2003