man2/read.2

   1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   2 .\"  and Copyright (C) 1993 Michael Haardt, Ian Jackson.
   3 .\"  and Copyright (C) 2009-2015 Michael Kerrisk, <mtk.manpages.gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" Modified Sat Jul 24 00:06:00 1993 by Rik Faith <faith@cs.unc.edu>
   8 .\" Modified Wed Jan 17 16:02:32 1996 by Michael Haardt
   9 .\"   <michael@cantor.informatik.rwth-aachen.de>
  10 .\" Modified Thu Apr 11 19:26:35 1996 by Andries Brouwer <aeb@cwi.nl>
  11 .\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer <aeb@cwi.nl>
  12 .\" Modified Fri Jan 31 16:47:33 1997 by Eric S. Raymond <esr@thyrsus.com>
  13 .\" Modified Sat Jul 12 20:45:39 1997 by Michael Haardt
  14 .\"   <michael@cantor.informatik.rwth-aachen.de>
  15 .\"
  16 .TH read 2 (date) "Linux man-pages (unreleased)"
  17 .SH NAME
  18 read \- read from a file descriptor
  19 .SH LIBRARY
  20 Standard C library
  21 .RI ( libc ", " \-lc )
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <unistd.h>
  25 .P
  26 .BI "ssize_t read(int " fd ", void " buf [. count "], size_t " count );
  27 .fi
  28 .SH DESCRIPTION
  29 .BR read ()
  30 attempts to read up to
  31 .I count
  32 bytes from file descriptor
  33 .I fd
  34 into the buffer starting at
  35 .IR buf .
  36 .P
  37 On files that support seeking,
  38 the read operation commences at the file offset,
  39 and the file offset is incremented by the number of bytes read.
  40 If the file offset is at or past the end of file,
  41 no bytes are read, and
  42 .BR read ()
  43 returns zero.
  44 .P
  45 If
  46 .I count
  47 is zero,
  48 .BR read ()
  49 .I may
  50 detect the errors described below.
  51 In the absence of any errors,
  52 or if
  53 .BR read ()
  54 does not check for errors, a
  55 .BR read ()
  56 with a
  57 .I count
  58 of 0 returns zero and has no other effects.
  59 .P
  60 According to POSIX.1, if
  61 .I count
  62 is greater than
  63 .BR SSIZE_MAX ,
  64 the result is implementation-defined;
  65 see NOTES for the upper limit on Linux.
  66 .SH RETURN VALUE
  67 On success, the number of bytes read is returned (zero indicates end of
  68 file), and the file position is advanced by this number.
  69 It is not an error if this number is smaller than the number of bytes
  70 requested; this may happen for example because fewer bytes are actually
  71 available right now (maybe because we were close to end-of-file, or
  72 because we are reading from a pipe, or from a terminal), or because
  73 .BR read ()
  74 was interrupted by a signal.
  75 See also NOTES.
  76 .P
  77 On error, \-1 is returned, and
  78 .I errno
  79 is set to indicate the error.
  80 In this case, it is left unspecified whether
  81 the file position (if any) changes.
  82 .SH ERRORS
  83 .TP
  84 .B EAGAIN
  85 The file descriptor
  86 .I fd
  87 refers to a file other than a socket and has been marked nonblocking
  88 .RB ( O_NONBLOCK ),
  89 and the read would block.
  90 See
  91 .BR open (2)
  92 for further details on the
  93 .B O_NONBLOCK
  94 flag.
  95 .TP
  96 .BR EAGAIN " or " EWOULDBLOCK
  97 .\" Actually EAGAIN on Linux
  98 The file descriptor
  99 .I fd
 100 refers to a socket and has been marked nonblocking
 101 .RB ( O_NONBLOCK ),
 102 and the read would block.
 103 POSIX.1-2001 allows either error to be returned for this case,
 104 and does not require these constants to have the same value,
 105 so a portable application should check for both possibilities.
 106 .TP
 107 .B EBADF
 108 .I fd
 109 is not a valid file descriptor or is not open for reading.
 110 .TP
 111 .B EFAULT
 112 .I buf
 113 is outside your accessible address space.
 114 .TP
 115 .B EINTR
 116 The call was interrupted by a signal before any data was read; see
 117 .BR signal (7).
 118 .TP
 119 .B EINVAL
 120 .I fd
 121 is attached to an object which is unsuitable for reading;
 122 or the file was opened with the
 123 .B O_DIRECT
 124 flag, and either the address specified in
 125 .IR buf ,
 126 the value specified in
 127 .IR count ,
 128 or the file offset is not suitably aligned.
 129 .TP
 130 .B EINVAL
 131 .I fd
 132 was created via a call to
 133 .BR timerfd_create (2)
 134 and the wrong size buffer was given to
 135 .BR read ();
 136 see
 137 .BR timerfd_create (2)
 138 for further information.
 139 .TP
 140 .B EIO
 141 I/O error.
 142 This will happen for example when the process is in a
 143 background process group, tries to read from its controlling terminal,
 144 and either it is ignoring or blocking
 145 .B SIGTTIN
 146 or its process group
 147 is orphaned.
 148 It may also occur when there is a low-level I/O error
 149 while reading from a disk or tape.
 150 A further possible cause of
 151 .B EIO
 152 on networked filesystems is when an advisory lock had been taken
 153 out on the file descriptor and this lock has been lost.
 154 See the
 155 .I "Lost locks"
 156 section of
 157 .BR fcntl (2)
 158 for further details.
 159 .TP
 160 .B EISDIR
 161 .I fd
 162 refers to a directory.
 163 .P
 164 Other errors may occur, depending on the object connected to
 165 .IR fd .
 166 .SH STANDARDS
 167 POSIX.1-2008.
 168 .SH HISTORY
 169 SVr4, 4.3BSD, POSIX.1-2001.
 170 .SH NOTES
 171 On Linux,
 172 .BR read ()
 173 (and similar system calls) will transfer at most
 174 0x7ffff000 (2,147,479,552) bytes,
 175 returning the number of bytes actually transferred.
 176 .\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69
 177 (This is true on both 32-bit and 64-bit systems.)
 178 .P
 179 On NFS filesystems, reading small amounts of data will update the
 180 timestamp only the first time, subsequent calls may not do so.
 181 This is caused
 182 by client side attribute caching, because most if not all NFS clients
 183 leave
 184 .I st_atime
 185 (last file access time)
 186 updates to the server, and client side reads satisfied from the
 187 client's cache will not cause
 188 .I st_atime
 189 updates on the server as there are no
 190 server-side reads.
 191 UNIX semantics can be obtained by disabling client-side attribute caching,
 192 but in most situations this will substantially
 193 increase server load and decrease performance.
 194 .SH BUGS
 195 According to POSIX.1-2008/SUSv4 Section XSI 2.9.7
 196 ("Thread Interactions with Regular File Operations"):
 197 .P
 198 .RS 4
 199 All of the following functions shall be atomic with respect to
 200 each other in the effects specified in POSIX.1-2008 when they
 201 operate on regular files or symbolic links: ...
 202 .RE
 203 .P
 204 Among the APIs subsequently listed are
 205 .BR read ()
 206 and
 207 .BR readv (2).
 208 And among the effects that should be atomic across threads (and processes)
 209 are updates of the file offset.
 210 However, before Linux 3.14,
 211 this was not the case: if two processes that share
 212 an open file description (see
 213 .BR open (2))
 214 perform a
 215 .BR read ()
 216 (or
 217 .BR readv (2))
 218 at the same time, then the I/O operations were not atomic
 219 with respect updating the file offset,
 220 with the result that the reads in the two processes
 221 might (incorrectly) overlap in the blocks of data that they obtained.
 222 This problem was fixed in Linux 3.14.
 223 .\" http://thread.gmane.org/gmane.linux.kernel/1649458
 224 .\"    From: Michael Kerrisk (man-pages <mtk.manpages <at> gmail.com>
 225 .\"    Subject: Update of file offset on write() etc. is non-atomic with I/O
 226 .\"    Date: 2014-02-17 15:41:37 GMT
 227 .\"    Newsgroups: gmane.linux.kernel, gmane.linux.file-systems
 228 .\" commit 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4
 229 .\"    Author: Linus Torvalds <torvalds@linux-foundation.org>
 230 .\"    Date:   Mon Mar 3 09:36:58 2014 -0800
 231 .\"
 232 .\"        vfs: atomic f_pos accesses as per POSIX
 233 .SH SEE ALSO
 234 .BR close (2),
 235 .BR fcntl (2),
 236 .BR ioctl (2),
 237 .BR lseek (2),
 238 .BR open (2),
 239 .BR pread (2),
 240 .BR readdir (2),
 241 .BR readlink (2),
 242 .BR readv (2),
 243 .BR select (2),
 244 .BR write (2),
 245 .BR fread (3)