Debian Codegraph @

upstream/debian-unstable/man2/read.2

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