Debian Codegraph @

upstream/debian-unstable/man2/write.2

raw
1 .\" Copyright 1992, Drew Eckhardt <[email protected]>
2 .\" Copyright 1993, Ian Jackson <[email protected]>
3 .\" Copyright 2007, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH write 2 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 write \- write to a file descriptor
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <unistd.h>
17 .P
18 .BR "ssize_t write(" "size_t count;"
19 .BI " int " fd ", const void " buf [ count "], size_t " count );
20 .fi
21 .SH DESCRIPTION
22 .BR write ()
23 writes up to
24 .I count
25 bytes from the buffer starting at
26 .I buf
27 to the file referred to by the file descriptor
28 .IR fd .
29 .P
30 The number of bytes written may be less than
31 .I count
32 if, for example,
33 there is insufficient space on the underlying physical medium, or the
34 .B RLIMIT_FSIZE
35 resource limit is encountered (see
36 .BR setrlimit (2)),
37 or the call was interrupted by a signal
38 handler after having written less than
39 .I count
40 bytes.
41 (See also
42 .BR pipe (7).)
43 .P
44 For a seekable file (i.e., one to which
45 .BR lseek (2)
46 may be applied, for example, a regular file)
47 writing takes place at the file offset,
48 and the file offset is incremented by
49 the number of bytes actually written.
50 If the file was
51 .BR open (2)ed
52 with
53 .BR O_APPEND ,
54 the file offset is first set to the end of the file before writing.
55 The adjustment of the file offset and the write operation
56 are performed as an atomic step.
57 .P
58 POSIX requires that a
59 .BR read (2)
60 that can be proved to occur after a
61 .BR write ()
62 has returned will return the new data.
63 Note that not all filesystems are POSIX conforming.
64 .P
65 According to POSIX.1, if
66 .I count
67 is greater than
68 .BR SSIZE_MAX ,
69 the result is implementation-defined;
70 see NOTES for the upper limit on Linux.
71 .SH RETURN VALUE
72 On success, the number of bytes written is returned.
73 On error, \-1 is returned, and
74 .I errno
75 is set
76 to indicate the error.
77 .P
78 Note that a successful
79 .BR write ()
80 may transfer fewer than
81 .I count
82 bytes.
83 Such partial writes can occur for various reasons;
84 for example, because there was insufficient space on the disk device
85 to write all of the requested bytes, or because a blocked
86 .BR write ()
87 to a socket, pipe, or similar was interrupted by a signal handler
88 after it had transferred some, but before it had transferred all
89 of the requested bytes.
90 In the event of a partial write, the caller can make another
91 .BR write ()
92 call to transfer the remaining bytes.
93 The subsequent call will either transfer further bytes or
94 may result in an error (e.g., if the disk is now full).
95 .P
96 If
97 .I count
98 is zero and
99 .I fd
100 refers to a regular file, then
101 .BR write ()
102 may return a failure status if one of the errors below is detected.
103 If no errors are detected, or error detection is not performed,
104 0 is returned without causing any other effect.
105 If
106 .I count
107 is zero and
108 .I fd
109 refers to a file other than a regular file,
110 the results are not specified.
111 .SH ERRORS
112 .TP
113 .B EAGAIN
114 The file descriptor
115 .I fd
116 refers to a file other than a socket and has been marked nonblocking
117 .RB ( O_NONBLOCK ),
118 and the write would block.
119 See
120 .BR open (2)
121 for further details on the
122 .B O_NONBLOCK
123 flag.
124 .TP
125 .BR EAGAIN " or " EWOULDBLOCK
126 .\" Actually EAGAIN on Linux
127 The file descriptor
128 .I fd
129 refers to a socket and has been marked nonblocking
130 .RB ( O_NONBLOCK ),
131 and the write would block.
132 POSIX.1-2001 allows either error to be returned for this case,
133 and does not require these constants to have the same value,
134 so a portable application should check for both possibilities.
135 .TP
136 .B EBADF
137 .I fd
138 is not a valid file descriptor or is not open for writing.
139 .TP
140 .B EDESTADDRREQ
141 .I fd
142 refers to a datagram socket for which a peer address has not been set using
143 .BR connect (2).
144 .TP
145 .B EDQUOT
146 The user's quota of disk blocks on the filesystem containing the file
147 referred to by
148 .I fd
149 has been exhausted.
150 .TP
151 .B EFAULT
152 .I buf
153 is outside your accessible address space.
154 .TP
155 .B EFBIG
156 An attempt was made to write a file that exceeds the implementation-defined
157 maximum file size or the process's file size limit,
158 or to write at a position past the maximum allowed offset.
159 .TP
160 .B EINTR
161 The call was interrupted by a signal before any data was written;
162 see
163 .BR signal (7).
164 .TP
165 .B EINVAL
166 .I fd
167 is attached to an object which is unsuitable for writing;
168 or the file was opened with the
169 .B O_DIRECT
170 flag, and either the address specified in
171 .IR buf ,
172 the value specified in
173 .IR count ,
174 or the file offset is not suitably aligned.
175 .TP
176 .B EIO
177 A low-level I/O error occurred while modifying the inode.
178 This error may relate to the write-back of data written by an earlier
179 .BR write (),
180 which may have been issued to a different file descriptor on
181 the same file.
182 Since Linux 4.13, errors from write-back come
183 with a promise that they
184 .I may
185 be reported by subsequent.
186 .BR write ()
187 requests, and
188 .I will
189 be reported by a subsequent
190 .BR fsync (2)
191 (whether or not they were also reported by
192 .BR write ()).
193 .\" commit 088737f44bbf6378745f5b57b035e57ee3dc4750
194 An alternate cause of
195 .B EIO
196 on networked filesystems is when an advisory lock had been taken out
197 on the file descriptor and this lock has been lost.
198 See the
199 .I "Lost locks"
200 section of
201 .BR fcntl (2)
202 for further details.
203 .TP
204 .B ENOSPC
205 The device containing the file referred to by
206 .I fd
207 has no room for the data.
208 .TP
209 .B EPERM
210 The operation was prevented by a file seal;
211 see
212 .BR fcntl (2).
213 .TP
214 .B EPIPE
215 .I fd
216 is connected to a pipe or socket whose reading end is closed.
217 When this happens the writing process will also receive a
218 .B SIGPIPE
219 signal.
220 (Thus, the write return value is seen only if the program
221 catches, blocks or ignores this signal.)
222 .P
223 Other errors may occur, depending on the object connected to
224 .IR fd .
225 .SH STANDARDS
226 POSIX.1-2024.
227 .SH HISTORY
228 SVr4, 4.3BSD, POSIX.1-2001.
229 .\" SVr4 documents additional error
230 .\" conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE.
231 .P
232 Under SVr4 a write may be interrupted and return
233 .B EINTR
234 at any point,
235 not just before any data is written.
236 .SH NOTES
237 A successful return from
238 .BR write ()
239 does not make any guarantee that data has been committed to disk.
240 On some filesystems, including NFS, it does not even guarantee
241 that space has successfully been reserved for the data.
242 In this case,
243 some errors might be delayed until a future
244 .BR write (),
245 .BR fsync (2),
246 or even
247 .BR close (2).
248 The only way to be sure is to call
249 .BR fsync (2)
250 after you are done writing all your data.
251 .P
252 If a
253 .BR write ()
254 is interrupted by a signal handler before any bytes are written,
255 then the call fails with the error
256 .BR EINTR ;
257 if it is interrupted after at least one byte has been written,
258 the call succeeds, and returns the number of bytes written.
259 .P
260 On Linux,
261 .BR write ()
262 (and similar system calls) will transfer at most
263 0x7ffff000 (2,147,479,552) bytes,
264 returning the number of bytes actually transferred.
265 .\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69
266 (This is true on both 32-bit and 64-bit systems.)
267 .P
268 An error return value while performing
269 .BR write ()
270 using direct I/O does not mean the
271 entire write has failed.
272 Partial data may be written
273 and the data at the file offset on which the
274 .BR write ()
275 was attempted should be considered inconsistent.
276 .SH BUGS
277 According to POSIX.1-2008/SUSv4 Section XSI 2.9.7
278 ("Thread Interactions with Regular File Operations"):
279 .P
280 .RS 4
281 All of the following functions shall be atomic with respect to
282 each other in the effects specified in POSIX.1-2008 when they
283 operate on regular files or symbolic links: ...
284 .RE
285 .P
286 Among the APIs subsequently listed are
287 .BR write ()
288 and
289 .BR writev (2).
290 And among the effects that should be atomic across threads (and processes)
291 are updates of the file offset.
292 However, before Linux 3.14,
293 this was not the case: if two processes that share
294 an open file description (see
295 .BR open (2))
296 perform a
297 .BR write ()
298 (or
299 .BR writev (2))
300 at the same time, then the I/O operations were not atomic
301 with respect to updating the file offset,
302 with the result that the blocks of data output by the two processes
303 might (incorrectly) overlap.
304 This problem was fixed in Linux 3.14.
305 .\" http://thread.gmane.org/gmane.linux.kernel/1649458
306 .\" From: Michael Kerrisk (man-pages <mtk.manpages <at> gmail.com>
307 .\" Subject: Update of file offset on write() etc. is non-atomic with I/O
308 .\" Date: 2014-02-17 15:41:37 GMT
309 .\" Newsgroups: gmane.linux.kernel, gmane.linux.file-systems
310 .\" commit 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4
311 .\" Author: Linus Torvalds <[email protected]>
312 .\" Date: Mon Mar 3 09:36:58 2014 -0800
313 .\"
314 .\" vfs: atomic f_pos accesses as per POSIX
315 .SH SEE ALSO
316 .BR close (2),
317 .BR fcntl (2),
318 .BR fsync (2),
319 .BR ioctl (2),
320 .BR lseek (2),
321 .BR open (2),
322 .BR pwrite (2),
323 .BR read (2),
324 .BR select (2),
325 .BR writev (2),
326 .BR fwrite (3)