pread(S)
pread, pread64 --
atomic position and read
Synopsis
#include <unistd.h>
ssize_t pread(int fd, void *buf, size_t nbytes, off_t offset);
ssize_t pread64(int fd, void *buf, size_t nbytes, off64_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 sets errno to:
EOVERFLOW-
The file is a regular file, nbyte is greater than 0, the
starting position is before the end-of-file and the starting position is
greater than or equal to the offset maximum established in the open
file descriptor associated with fd.
There is no data transfer.
In the following conditions, pread and pread64
fail and set errno to:
EACCES-
fd 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.
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-
fd 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-
fd 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-
fd 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.
ENOLINK-
fd is on a remote machine and the link
to that machine is no longer active.
ESPIPE-
fd
is associated with a pipe or fifo.
ENOSYS-
The device for ``fstype'' does not support seek operations.
References
intro(S),
lseek(S),
pwrite(S),
read(S)
Notices
pread updates the time of last access (see
stat(S))
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.
Considerations for large file support
pread64 supports large files, but is otherwise identical
to pread.
For details on programming for large file capable applications, see
``Large File Support''
on intro(S).
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 - 01 June 2005