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 2021-03-22 "Linux" "Linux Programmer's Manual"
  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 .PP
  26 .BI "ssize_t read(int " fd ", void *" buf ", 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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .BR 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 .PP
 164 Other errors may occur, depending on the object connected to
 165 .IR fd .
 166 .SH CONFORMING TO
 167 SVr4, 4.3BSD, POSIX.1-2001.
 168 .SH NOTES
 169 The types
 170 .I size_t
 171 and
 172 .I ssize_t
 173 are, respectively,
 174 unsigned and signed integer data types specified by POSIX.1.
 175 .PP
 176 On Linux,
 177 .BR read ()
 178 (and similar system calls) will transfer at most
 179 0x7ffff000 (2,147,479,552) bytes,
 180 returning the number of bytes actually transferred.
 181 .\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69
 182 (This is true on both 32-bit and 64-bit systems.)
 183 .PP
 184 On NFS filesystems, reading small amounts of data will update the
 185 timestamp only the first time, subsequent calls may not do so.
 186 This is caused
 187 by client side attribute caching, because most if not all NFS clients
 188 leave
 189 .I st_atime
 190 (last file access time)
 191 updates to the server, and client side reads satisfied from the
 192 client's cache will not cause
 193 .I st_atime
 194 updates on the server as there are no
 195 server-side reads.
 196 UNIX semantics can be obtained by disabling client-side attribute caching,
 197 but in most situations this will substantially
 198 increase server load and decrease performance.
 199 .SH BUGS
 200 According to POSIX.1-2008/SUSv4 Section XSI 2.9.7
 201 ("Thread Interactions with Regular File Operations"):
 202 .PP
 203 .RS 4
 204 All of the following functions shall be atomic with respect to
 205 each other in the effects specified in POSIX.1-2008 when they
 206 operate on regular files or symbolic links: ...
 207 .RE
 208 .PP
 209 Among the APIs subsequently listed are
 210 .BR read ()
 211 and
 212 .BR readv (2).
 213 And among the effects that should be atomic across threads (and processes)
 214 are updates of the file offset.
 215 However, on Linux before version 3.14,
 216 this was not the case: if two processes that share
 217 an open file description (see
 218 .BR open (2))
 219 perform a
 220 .BR read ()
 221 (or
 222 .BR readv (2))
 223 at the same time, then the I/O operations were not atomic
 224 with respect updating the file offset,
 225 with the result that the reads in the two processes
 226 might (incorrectly) overlap in the blocks of data that they obtained.
 227 This problem was fixed in Linux 3.14.
 228 .\" http://thread.gmane.org/gmane.linux.kernel/1649458
 229 .\"    From: Michael Kerrisk (man-pages <mtk.manpages <at> gmail.com>
 230 .\"    Subject: Update of file offset on write() etc. is non-atomic with I/O
 231 .\"    Date: 2014-02-17 15:41:37 GMT
 232 .\"    Newsgroups: gmane.linux.kernel, gmane.linux.file-systems
 233 .\" commit 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4
 234 .\"    Author: Linus Torvalds <torvalds@linux-foundation.org>
 235 .\"    Date:   Mon Mar 3 09:36:58 2014 -0800
 236 .\"
 237 .\"        vfs: atomic f_pos accesses as per POSIX
 238 .SH SEE ALSO
 239 .BR close (2),
 240 .BR fcntl (2),
 241 .BR ioctl (2),
 242 .BR lseek (2),
 243 .BR open (2),
 244 .BR pread (2),
 245 .BR readdir (2),
 246 .BR readlink (2),
 247 .BR readv (2),
 248 .BR select (2),
 249 .BR write (2),
 250 .BR fread (3)