pread(2) pread(2)
NAME
pread - atomic position and read
SYNOPSIS
ssizet read(int fildes, void *buf, sizet nbyte, offt offset);
DESCRIPTION
The pread() system call does an atomic position-and-read, eliminating
the necessity of using a locking mechanism when both operations are
desired and file descriptors are shared. pread() is analogous to
read() but takes a fourth argument, offset. The read is done as if an
lseek() to offset (from the beginning of the file) were done first.
Note that (though the semantics are analogous) an lseek() is not actu-
ally performed; the file pointer is not affected by pread(). The read
of nbytes then starts at the specified offset.
The atomicity of pread() enables processes or threads that share file
descriptors to read from a shared file at a particular offset without
using a locking mechanism that would be necessary to achieve the same
result in separate lseek() and read() system calls. Atomicity is
required as the file pointer is shared and one thread might move the
pointer using lseek() after another process completes an lseek() but
prior to the read().
RETURN VALUES
Upon successful completion, pread() returns the number of bytes actu-
ally read and placed in buf. A value of 0 is returned when an end-of-
file has been reached. Otherwise a -1 and an error is returned.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
In the following conditions, pread() fail and set errno to:
EAGAIN Mandatory file/record locking was set, ONONBLOCK was set,
and there was a blocking record lock.
EAGAIN Total amount of system memory available when reading via raw
I/O is temporarily insufficient.
EAGAIN No data is waiting to be read on a file associated with a tty
device and ONONBLOCK was set.
EAGAIN No message is waiting to be read on a stream and ONONBLOCK
was set.
EBADF fildes is not a valid file descriptor open for reading.
EBADMSG Message waiting to be read on a stream is not a data message.
Page 1 Reliant UNIX 5.44 Printed 11/98
pread(2) pread(2)
EDEADLK The pread() was going to go to sleep and cause a deadlock to
occur.
EFAULT buf points outside the allocated address space.
EINTR A signal was received during the pread() system call.
EINVAL Attempted to read from a stream linked to a multiplexer.
EIO A physical I/O error has occurred, or the process is in a
background process group and is attempting to read from its
controlling terminal, and either the process is ignoring or
blocking the SIGTTIN signal or the process group of the pro-
cess is orphaned.
ENOLCK The system record lock table was full, so the pread() could
not go to sleep until the blocking record lock was removed.
ENOLINK fildes is on a remote machine and the link to that machine is
no longer active.
ENXIO The device associated with fildes is a block special or char-
acter special file and the value of the file pointer is out
of range.
A pread() from a STREAMS file also fails if an error message is
received at the stream head. In this case, errno is set to the value
returned in the error message. If a hangup occurs on the stream being
read, pread() continues to operate normally until the stream head read
queue is empty. Thereafter, it returns 0.
NOTES
pread() updates the time of last access [see stat(2)] of the file.
SEE ALSO
lseek(2), pwrite(2), read(2), unistd(4).
Page 2 Reliant UNIX 5.44 Printed 11/98