pread() — Read from a file or socket without file pointer change

Standards

Format

#define _XOPEN_SOURCE 500
#include <unistd.h>

ssize_t pread(int fildes, void *buf, size_t nbyte, off_t offset);

General description

The pread() function performs the same action as read(), except that it reads from a given position in the file without changing the file pointer.

The first three arguments to pread() are the same as read(), with the addition of a fourth argument offset for the desired position inside the file.

An error result is returned for any attempt to perform a pread() on a file that is incapable of a seek action.

For regular files, no data transfer will occur past the offset maximum established in the open file description associated with fildes.

Returned value

If successful, pread() returns a non-negative integer indicating the number of bytes actually read.

If unsuccessful, pread() returns -1 and sets errno to one of the following values:

Error Code

Description

EAGAIN

O_NONBLOCK is set to 1, but data was not available for reading.

EBADF

fildes is not a valid file or socket descriptor.

ECONNRESET

A connection was forcibly closed by a peer.

EFAULT

Using the buf and nbyte parameters would result in an attempt to access memory outside the caller's address space.

EINTR

pread() was interrupted by a signal that was caught before any data was available.

EINVAL

nbyte contains a value that is less than 0, or the request is invalid or not supported, or the STREAM or multiplexer referenced by fildes is linked (directly or indirectly) downstream from a multiplexer.

The offset argument is invalid. The value is negative.

EIO

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. For sockets, an I/O error occurred.

ENOBUFS

Insufficient system resources are available to complete the call.

ENOTCONN

A receive was attempted on a connection-oriented socket that is not connected.

ENXIO

A request was outside the capabilities of the device.

EOVERFLOW

The file is a regular file and an attempt was made to read or write at or beyond the offset maximum associated with the file.

ESPIPE

fildes is associated with a pipe or FIFO.

ETIMEDOUT

The connection timed out during connection establishment, or due to a transmission timeout on active connection.

EWOULDBLOCK

socket is in nonblocking mode and data is not available to read. or the SO_RCVTIMEO timeout value was been reached before data was available.

Related information

• unistd.h
• pwrite() — Write data on a file or socket without file pointer change
• read() — Read from a file or socket