375 lines
8.3 KiB
HTML
375 lines
8.3 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of READ</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>READ</H1>
|
|
Section: Linux Programmer's Manual (2)<BR>Updated: 2018-02-02<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
read - read from a file descriptor
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>#include <<A HREF="file:///usr/include/unistd.h">unistd.h</A>></B>
|
|
|
|
<B>ssize_t read(int </B><I>fd</I><B>, void *</B><I>buf</I><B>, size_t </B><I>count</I><B>);</B>
|
|
</PRE>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>read</B>()
|
|
|
|
attempts to read up to
|
|
<I>count</I>
|
|
|
|
bytes from file descriptor
|
|
<I>fd</I>
|
|
|
|
into the buffer starting at
|
|
<I>buf</I>.
|
|
|
|
<P>
|
|
|
|
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
|
|
<B>read</B>()
|
|
|
|
returns zero.
|
|
<P>
|
|
|
|
If
|
|
<I>count</I>
|
|
|
|
is zero,
|
|
<B>read</B>()
|
|
|
|
<I>may</I>
|
|
|
|
detect the errors described below.
|
|
In the absence of any errors,
|
|
or if
|
|
<B>read</B>()
|
|
|
|
does not check for errors, a
|
|
<B>read</B>()
|
|
|
|
with a
|
|
<I>count</I>
|
|
|
|
of 0 returns zero and has no other effects.
|
|
<P>
|
|
|
|
According to POSIX.1, if
|
|
<I>count</I>
|
|
|
|
is greater than
|
|
<B>SSIZE_MAX</B>,
|
|
|
|
the result is implementation-defined;
|
|
see NOTES for the upper limit on Linux.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
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
|
|
<B>read</B>()
|
|
|
|
was interrupted by a signal.
|
|
See also NOTES.
|
|
<P>
|
|
|
|
On error, -1 is returned, and
|
|
<I>errno</I>
|
|
|
|
is set appropriately.
|
|
In this case, it is left unspecified whether
|
|
the file position (if any) changes.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>EAGAIN</B>
|
|
|
|
<DD>
|
|
The file descriptor
|
|
<I>fd</I>
|
|
|
|
refers to a file other than a socket and has been marked nonblocking
|
|
(<B>O_NONBLOCK</B>),
|
|
|
|
and the read would block.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2)
|
|
|
|
for further details on the
|
|
<B>O_NONBLOCK</B>
|
|
|
|
flag.
|
|
<DT id="2"><B>EAGAIN</B> or <B>EWOULDBLOCK</B>
|
|
|
|
<DD>
|
|
|
|
The file descriptor
|
|
<I>fd</I>
|
|
|
|
refers to a socket and has been marked nonblocking
|
|
(<B>O_NONBLOCK</B>),
|
|
|
|
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.
|
|
<DT id="3"><B>EBADF</B>
|
|
|
|
<DD>
|
|
<I>fd</I>
|
|
|
|
is not a valid file descriptor or is not open for reading.
|
|
<DT id="4"><B>EFAULT</B>
|
|
|
|
<DD>
|
|
<I>buf</I>
|
|
|
|
is outside your accessible address space.
|
|
<DT id="5"><B>EINTR</B>
|
|
|
|
<DD>
|
|
The call was interrupted by a signal before any data was read; see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+signal">signal</A></B>(7).
|
|
|
|
<DT id="6"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
<I>fd</I>
|
|
|
|
is attached to an object which is unsuitable for reading;
|
|
or the file was opened with the
|
|
<B>O_DIRECT</B>
|
|
|
|
flag, and either the address specified in
|
|
<I>buf</I>,
|
|
|
|
the value specified in
|
|
<I>count</I>,
|
|
|
|
or the file offset is not suitably aligned.
|
|
<DT id="7"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
<I>fd</I>
|
|
|
|
was created via a call to
|
|
<B><A HREF="/cgi-bin/man/man2html?2+timerfd_create">timerfd_create</A></B>(2)
|
|
|
|
and the wrong size buffer was given to
|
|
<B>read</B>();
|
|
|
|
see
|
|
<B><A HREF="/cgi-bin/man/man2html?2+timerfd_create">timerfd_create</A></B>(2)
|
|
|
|
for further information.
|
|
<DT id="8"><B>EIO</B>
|
|
|
|
<DD>
|
|
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
|
|
<B>SIGTTIN</B>
|
|
|
|
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
|
|
<B>EIO</B>
|
|
|
|
on networked filesystems is when an advisory lock had been taken
|
|
out on the file descriptor and this lock has been lost.
|
|
See the
|
|
<I>Lost locks</I>
|
|
|
|
section of
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fcntl">fcntl</A></B>(2)
|
|
|
|
for further details.
|
|
<DT id="9"><B>EISDIR</B>
|
|
|
|
<DD>
|
|
<I>fd</I>
|
|
|
|
refers to a directory.
|
|
</DL>
|
|
<P>
|
|
|
|
Other errors may occur, depending on the object connected to
|
|
<I>fd</I>.
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
SVr4, 4.3BSD, POSIX.1-2001.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
The types
|
|
<I>size_t</I>
|
|
|
|
and
|
|
<I>ssize_t</I>
|
|
|
|
are, respectively,
|
|
unsigned and signed integer data types specified by POSIX.1.
|
|
<P>
|
|
|
|
On Linux,
|
|
<B>read</B>()
|
|
|
|
(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.)
|
|
<P>
|
|
|
|
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
|
|
<I>st_atime</I>
|
|
|
|
(last file access time)
|
|
updates to the server, and client side reads satisfied from the
|
|
client's cache will not cause
|
|
<I>st_atime</I>
|
|
|
|
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.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
According to POSIX.1-2008/SUSv4 Section XSI 2.9.7
|
|
("Thread Interactions with Regular File Operations"):
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="10"><DD>
|
|
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: ...
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
Among the APIs subsequently listed are
|
|
<B>read</B>()
|
|
|
|
and
|
|
<B><A HREF="/cgi-bin/man/man2html?2+readv">readv</A></B>(2).
|
|
|
|
And 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
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2))
|
|
|
|
perform a
|
|
<B>read</B>()
|
|
|
|
(or
|
|
<B><A HREF="/cgi-bin/man/man2html?2+readv">readv</A></B>(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 Linux 3.14.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+close">close</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fcntl">fcntl</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+ioctl">ioctl</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+lseek">lseek</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+pread">pread</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+readdir">readdir</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+readlink">readlink</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+readv">readv</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+select">select</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+fread">fread</A></B>(3)
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="11"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="12"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="13"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="14"><A HREF="#lbAE">RETURN VALUE</A><DD>
|
|
<DT id="15"><A HREF="#lbAF">ERRORS</A><DD>
|
|
<DT id="16"><A HREF="#lbAG">CONFORMING TO</A><DD>
|
|
<DT id="17"><A HREF="#lbAH">NOTES</A><DD>
|
|
<DT id="18"><A HREF="#lbAI">BUGS</A><DD>
|
|
<DT id="19"><A HREF="#lbAJ">SEE ALSO</A><DD>
|
|
<DT id="20"><A HREF="#lbAK">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:34 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|