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).