pread(2)


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(2), 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.

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(2).
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004