read - read from a file descriptor
ssize_t read(int fd, void *buf, size_t count);
() attempts to read up to count
bytes from file descriptor
into the buffer starting at buf
On files that support seeking, the read operation commences at the file offset,
and the file offset is incremented by the number of bytes read. If the file
offset is at or past the end of file, no bytes are read, and read
is zero, read
detect the errors described
below. In the absence of any errors, or if read
() does not check for
errors, a read
() with a count
of 0 returns zero and has no other
According to POSIX.1, if count
is greater than SSIZE_MAX
result is implementation-defined; see NOTES for the upper limit on Linux.
On success, the number of bytes read is returned (zero indicates end of file),
and the file position is advanced by this number. It is not an error if this
number is smaller than the number of bytes requested; this may happen for
example because fewer bytes are actually available right now (maybe because we
were close to end-of-file, or because we are reading from a pipe, or from a
terminal), or because read
() was interrupted by a signal. See also
On error, -1 is returned, and errno
is set appropriately. In this case,
it is left unspecified whether the file position (if any) changes.
- The file descriptor fd refers to a file other than a
socket and has been marked nonblocking (O_NONBLOCK), and the read
would block. See open(2) for further details on the
- EAGAIN or EWOULDBLOCK
- The file descriptor fd refers to a socket and has
been marked nonblocking (O_NONBLOCK), and the read would block.
POSIX.1-2001 allows either error to be returned for this case, and does
not require these constants to have the same value, so a portable
application should check for both possibilities.
- fd is not a valid file descriptor or is not open for
- buf is outside your accessible address space.
- The call was interrupted by a signal before any data was
read; see signal(7).
- fd is attached to an object which is unsuitable for
reading; or the file was opened with the O_DIRECT flag, and either
the address specified in buf, the value specified in count,
or the file offset is not suitably aligned.
- fd was created via a call to
timerfd_create(2) and the wrong size buffer was given to
read(); see timerfd_create(2) for further information.
- I/O error. This will happen for example when the process is
in a background process group, tries to read from its controlling
terminal, and either it is ignoring or blocking SIGTTIN or its
process group is orphaned. It may also occur when there is a low-level I/O
error while reading from a disk or tape. A further possible cause of
EIO on networked filesystems is when an advisory lock had been
taken out on the file descriptor and this lock has been lost. See the
Lost locks section of fcntl(2) for further details.
- fd refers to a directory.
Other errors may occur, depending on the object connected to fd
SVr4, 4.3BSD, POSIX.1-2001.
The types size_t
are, respectively, unsigned and
signed integer data types specified by POSIX.1.
On Linux, read
() (and similar system calls) will transfer at most
0x7ffff000 (2,147,479,552) bytes, returning the number of bytes actually
transferred. (This is true on both 32-bit and 64-bit systems.)
On NFS filesystems, reading small amounts of data will update the timestamp only
the first time, subsequent calls may not do so. This is caused by client side
attribute caching, because most if not all NFS clients leave st_atime
(last file access time) updates to the server, and client side reads satisfied
from the client's cache will not cause st_atime
updates on the server
as there are no server-side reads. UNIX semantics can be obtained by disabling
client-side attribute caching, but in most situations this will substantially
increase server load and decrease performance.
According to POSIX.1-2008/SUSv4 Section XSI 2.9.7 ("Thread Interactions
with Regular File Operations"):
All of the following functions shall be atomic
with respect to each other in the effects specified in POSIX.1-2008 when they
operate on regular files or symbolic links: ...
Among the APIs subsequently listed are read
() and readv(2)
among the effects that should be atomic across threads (and processes) are
updates of the file offset. However, on Linux before version 3.14, this was
not the case: if two processes that share an open file description (see
) perform a read
() (or readv(2)
) at the same time,
then the I/O operations were not atomic with respect updating the file offset,
with the result that the reads in the two processes might (incorrectly)
overlap in the blocks of data that they obtained. This problem was fixed in
This page is part of release 4.16 of the Linux man-pages
description of the project, information about reporting bugs, and the latest
version of this page, can be found at