pread(2) pread(2)
NAME
pread - atomic position and read
SYNOPSIS
#include <unistd.h>
ssize_t pread(int fd, void *buf, size_t nbytes, off_t 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 actually 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
actually 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
In the following conditions, pread fails and set errno to:
EACCES fildes is open to a dynamic device and read
permission is denied.
EAGAIN Mandatory file/record locking was set, O_NDELAY
or O_NONBLOCK 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.
Copyright 1994 Novell, Inc. Page 1
pread(2) pread(2)
EAGAIN No data is waiting to be read on a file
associated with a tty device and O_NONBLOCK was
set.
EAGAIN No message is waiting to be read on a stream
and O_NDELAY or O_NONBLOCK 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.
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 caught during the pread system
call.
EINVAL Attempted to read from a stream linked to a
multiplexor.
EINVAL The resulting file pointer would be negative.
EINVAL fildes is a remote file descriptor accessed
using NFS, the Network File System, and the
resulting file pointer would be negative.
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 process is orphaned.
EIO fildes is open to a device that is in the
process of closing.
ENOLCK The system record lock table was full, so the
pread could not go to sleep until the blocking
record lock was removed.
Copyright 1994 Novell, Inc. Page 2
pread(2) pread(2)
ENOLINK fildes is on a remote machine and the link to
that machine is no longer active.
ESPIPE fildes is associated with a pipe or fifo.
ENOSYS The device for fstype does not support seek
operations.
REFERENCES
lseek(2), pwrite(2), read(2)
NOTICES
pread updates the time of last access [see stat(2)] of the
file.
Considerations for Threads Programming
Open file descriptors are a process resource and available to
any sibling thread; if used concurrently, actions by one
thread can interfere with those of a sibling.
While one thread is blocked, siblings might still be
executing.
Copyright 1994 Novell, Inc. Page 3