mirror of https://github.com/mkerrisk/man-pages
258 lines
7.5 KiB
Groff
258 lines
7.5 KiB
Groff
.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
|
|
.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" Modified Sat Jul 24 00:06:00 1993 by Rik Faith <faith@cs.unc.edu>
|
|
.\" Modified Wed Jan 17 16:02:32 1996 by Michael Haardt
|
|
.\" <michael@cantor.informatik.rwth-aachen.de>
|
|
.\" Modified Thu Apr 11 19:26:35 1996 by Andries Brouwer <aeb@cwi.nl>
|
|
.\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer <aeb@cwi.nl>
|
|
.\" Modified Fri Jan 31 16:47:33 1997 by Eric S. Raymond <esr@thyrsus.com>
|
|
.\" Modified Sat Jul 12 20:45:39 1997 by Michael Haardt
|
|
.\" <michael@cantor.informatik.rwth-aachen.de>
|
|
.\"
|
|
.TH READ 2 2017-03-13 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
read \- read from a file descriptor
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <unistd.h>
|
|
.sp
|
|
.BI "ssize_t read(int " fd ", void *" buf ", size_t " count );
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.BR read ()
|
|
attempts to read up to
|
|
.I count
|
|
bytes from file descriptor
|
|
.I fd
|
|
into the buffer starting at
|
|
.IR 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
|
|
.BR read ()
|
|
returns zero.
|
|
|
|
If
|
|
.I count
|
|
is zero,
|
|
.BR read ()
|
|
.I may
|
|
detect the errors described below.
|
|
In the absence of any errors,
|
|
or if
|
|
.BR read ()
|
|
does not check for errors, a
|
|
.BR read ()
|
|
with a
|
|
.I count
|
|
of 0 returns zero and has no other effects.
|
|
|
|
According to POSIX.1, if
|
|
.I count
|
|
is greater than
|
|
.BR SSIZE_MAX ,
|
|
the result is implementation-defined;
|
|
see NOTES for the upper limit on Linux.
|
|
.SH RETURN VALUE
|
|
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
|
|
.BR read ()
|
|
was interrupted by a signal.
|
|
See also NOTES.
|
|
|
|
On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
In this case, it is left unspecified whether
|
|
the file position (if any) changes.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EAGAIN
|
|
The file descriptor
|
|
.I fd
|
|
refers to a file other than a socket and has been marked nonblocking
|
|
.RB ( O_NONBLOCK ),
|
|
and the read would block.
|
|
See
|
|
.BR open (2)
|
|
for further details on the
|
|
.BR O_NONBLOCK
|
|
flag.
|
|
.TP
|
|
.BR EAGAIN " or " EWOULDBLOCK
|
|
.\" Actually EAGAIN on Linux
|
|
The file descriptor
|
|
.I fd
|
|
refers to a socket and has been marked nonblocking
|
|
.RB ( 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.
|
|
.TP
|
|
.B EBADF
|
|
.I fd
|
|
is not a valid file descriptor or is not open for reading.
|
|
.TP
|
|
.B EFAULT
|
|
.I buf
|
|
is outside your accessible address space.
|
|
.TP
|
|
.B EINTR
|
|
The call was interrupted by a signal before any data was read; see
|
|
.BR signal (7).
|
|
.TP
|
|
.B EINVAL
|
|
.I fd
|
|
is attached to an object which is unsuitable for reading;
|
|
or the file was opened with the
|
|
.B O_DIRECT
|
|
flag, and either the address specified in
|
|
.IR buf ,
|
|
the value specified in
|
|
.IR count ,
|
|
or the file offset is not suitably aligned.
|
|
.TP
|
|
.B EINVAL
|
|
.I fd
|
|
was created via a call to
|
|
.BR timerfd_create (2)
|
|
and the wrong size buffer was given to
|
|
.BR read ();
|
|
see
|
|
.BR timerfd_create (2)
|
|
for further information.
|
|
.TP
|
|
.B EIO
|
|
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
|
|
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.
|
|
.TP
|
|
.B EISDIR
|
|
.I fd
|
|
refers to a directory.
|
|
.PP
|
|
Other errors may occur, depending on the object connected to
|
|
.IR fd .
|
|
.SH CONFORMING TO
|
|
SVr4, 4.3BSD, POSIX.1-2001.
|
|
.SH NOTES
|
|
The types
|
|
.I size_t
|
|
and
|
|
.I ssize_t
|
|
are, respectively,
|
|
unsigned and signed integer data types specified by POSIX.1.
|
|
|
|
On Linux,
|
|
.BR read ()
|
|
(and similar system calls) will transfer at most
|
|
0x7ffff000 (2,147,479,552) bytes,
|
|
returning the number of bytes actually transferred.
|
|
.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69
|
|
(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
|
|
.I st_atime
|
|
(last file access time)
|
|
updates to the server, and client side reads satisfied from the
|
|
client's cache will not cause
|
|
.I 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.
|
|
.SH BUGS
|
|
According to POSIX.1-2008/SUSv4 Section XSI 2.9.7
|
|
("Thread Interactions with Regular File Operations"):
|
|
|
|
.RS 4
|
|
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: ...
|
|
.RE
|
|
|
|
Among the APIs subsequently listed are
|
|
.BR read ()
|
|
and
|
|
.BR readv (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
|
|
.BR open (2))
|
|
perform a
|
|
.BR read ()
|
|
(or
|
|
.BR 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 Linux 3.14.
|
|
.\" http://thread.gmane.org/gmane.linux.kernel/1649458
|
|
.\" From: Michael Kerrisk (man-pages <mtk.manpages <at> gmail.com>
|
|
.\" Subject: Update of file offset on write() etc. is non-atomic with I/O
|
|
.\" Date: 2014-02-17 15:41:37 GMT
|
|
.\" Newsgroups: gmane.linux.kernel, gmane.linux.file-systems
|
|
.\" commit 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4
|
|
.\" Author: Linus Torvalds <torvalds@linux-foundation.org>
|
|
.\" Date: Mon Mar 3 09:36:58 2014 -0800
|
|
.\"
|
|
.\" vfs: atomic f_pos accesses as per POSIX
|
|
.SH SEE ALSO
|
|
.BR close (2),
|
|
.BR fcntl (2),
|
|
.BR ioctl (2),
|
|
.BR lseek (2),
|
|
.BR open (2),
|
|
.BR pread (2),
|
|
.BR readdir (2),
|
|
.BR readlink (2),
|
|
.BR readv (2),
|
|
.BR select (2),
|
|
.BR write (2),
|
|
.BR fread (3)
|