]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
ac56b6a8 | 2 | .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. |
c11b1abf | 3 | .\" and Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 4 | .\" |
93015253 | 5 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
6 | .\" Permission is granted to make and distribute verbatim copies of this |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
c13182ef | 14 | .\" |
fea681da MK |
15 | .\" Since the Linux kernel and libraries are constantly changing, this |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
c13182ef | 22 | .\" |
fea681da MK |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 25 | .\" %%%LICENSE_END |
fea681da MK |
26 | .\" |
27 | .\" Modified Sat Jul 24 13:35:59 1993 by Rik Faith <faith@cs.unc.edu> | |
28 | .\" Modified Sun Nov 28 17:19:01 1993 by Rik Faith <faith@cs.unc.edu> | |
29 | .\" Modified Sat Jan 13 12:58:08 1996 by Michael Haardt | |
30 | .\" <michael@cantor.informatik.rwth-aachen.de> | |
31 | .\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer <aeb@cwi.nl> | |
32 | .\" 2001-12-13 added remark by Zack Weinberg | |
a43e21f0 MK |
33 | .\" 2007-06-18 mtk: |
34 | .\" Added details about seekable files and file offset. | |
35 | .\" Noted that write() may write less than 'count' bytes, and | |
36 | .\" gave some examples of why this might occur. | |
37 | .\" Noted what happens if write() is interrupted by a signal. | |
fea681da | 38 | .\" |
867c9b34 | 39 | .TH WRITE 2 2019-10-10 "Linux" "Linux Programmer's Manual" |
fea681da MK |
40 | .SH NAME |
41 | write \- write to a file descriptor | |
42 | .SH SYNOPSIS | |
43 | .B #include <unistd.h> | |
68e4db0a | 44 | .PP |
fea681da MK |
45 | .BI "ssize_t write(int " fd ", const void *" buf ", size_t " count ); |
46 | .SH DESCRIPTION | |
e511ffb6 | 47 | .BR write () |
fea681da MK |
48 | writes up to |
49 | .I count | |
9c93cce7 | 50 | bytes from the buffer starting at |
0daa9e92 | 51 | .I buf |
a43e21f0 | 52 | to the file referred to by the file descriptor |
4df883b9 | 53 | .IR fd . |
efeece04 | 54 | .PP |
a43e21f0 MK |
55 | The number of bytes written may be less than |
56 | .I count | |
57 | if, for example, | |
58 | there is insufficient space on the underlying physical medium, or the | |
59 | .B RLIMIT_FSIZE | |
60 | resource limit is encountered (see | |
61 | .BR setrlimit (2)), | |
62 | or the call was interrupted by a signal | |
63 | handler after having written less than | |
64 | .I count | |
65 | bytes. | |
66 | (See also | |
67 | .BR pipe (7).) | |
efeece04 | 68 | .PP |
a43e21f0 MK |
69 | For a seekable file (i.e., one to which |
70 | .BR lseek (2) | |
71 | may be applied, for example, a regular file) | |
c72249c5 | 72 | writing takes place at the file offset, |
a43e21f0 MK |
73 | and the file offset is incremented by |
74 | the number of bytes actually written. | |
75 | If the file was | |
76 | .BR open (2)ed | |
77 | with | |
78 | .BR O_APPEND , | |
79 | the file offset is first set to the end of the file before writing. | |
80 | The adjustment of the file offset and the write operation | |
81 | are performed as an atomic step. | |
efeece04 | 82 | .PP |
60a90ecd MK |
83 | POSIX requires that a |
84 | .BR read (2) | |
e6f3afdb | 85 | that can be proved to occur after a |
60a90ecd | 86 | .BR write () |
e6f3afdb | 87 | has returned will return the new data. |
9ee4a2b6 | 88 | Note that not all filesystems are POSIX conforming. |
efeece04 | 89 | .PP |
dfbb4842 MK |
90 | According to POSIX.1, if |
91 | .I count | |
92 | is greater than | |
93 | .BR SSIZE_MAX , | |
94 | the result is implementation-defined; | |
95 | see NOTES for the upper limit on Linux. | |
47297adb | 96 | .SH RETURN VALUE |
3d335319 | 97 | On success, the number of bytes written is returned. |
c13182ef | 98 | On error, \-1 is returned, and \fIerrno\fP is set |
3d335319 MK |
99 | to indicate the cause of the error. |
100 | .PP | |
101 | Note that a successful | |
102 | .BR write () | |
103 | may transfer fewer than | |
104 | .I count | |
105 | bytes. | |
106 | Such partial writes can occur for various reasons; | |
107 | for example, because there was insufficient space on the disk device | |
108 | to write all of the requested bytes, or because a blocked | |
109 | .BR write () | |
110 | to a socket, pipe, or similar was interrupted by a signal handler | |
111 | after it had transferred some, but before it had transferred all | |
112 | of the requested bytes. | |
113 | In the event of a partial write, the caller can make another | |
114 | .BR write () | |
115 | call to transfer the remaining bytes. | |
116 | The subsequent call will either transfer further bytes or | |
117 | may result in an error (e.g., if the disk is now full). | |
efeece04 | 118 | .PP |
609af441 MK |
119 | If \fIcount\fP is zero and |
120 | .I fd | |
121 | refers to a regular file, then | |
a43e21f0 | 122 | .BR write () |
609af441 | 123 | may return a failure status if one of the errors below is detected. |
becb7f08 | 124 | If no errors are detected, or error detection is not performed, |
609af441 MK |
125 | 0 will be returned without causing any other effect. |
126 | If | |
127 | \fIcount\fP is zero and | |
128 | .I fd | |
c13182ef | 129 | refers to a file other than a regular file, |
609af441 | 130 | the results are not specified. |
fea681da MK |
131 | .SH ERRORS |
132 | .TP | |
133 | .B EAGAIN | |
a43e21f0 MK |
134 | The file descriptor |
135 | .I fd | |
ff40dbb3 | 136 | refers to a file other than a socket and has been marked nonblocking |
86426e0b | 137 | .RB ( O_NONBLOCK ), |
fea681da | 138 | and the write would block. |
9f629381 MK |
139 | See |
140 | .BR open (2) | |
141 | for further details on the | |
142 | .BR O_NONBLOCK | |
143 | flag. | |
fea681da | 144 | .TP |
86426e0b MK |
145 | .BR EAGAIN " or " EWOULDBLOCK |
146 | .\" Actually EAGAIN on Linux | |
147 | The file descriptor | |
148 | .I fd | |
ff40dbb3 | 149 | refers to a socket and has been marked nonblocking |
86426e0b MK |
150 | .RB ( O_NONBLOCK ), |
151 | and the write would block. | |
152 | POSIX.1-2001 allows either error to be returned for this case, | |
153 | and does not require these constants to have the same value, | |
154 | so a portable application should check for both possibilities. | |
155 | .TP | |
fea681da MK |
156 | .B EBADF |
157 | .I fd | |
158 | is not a valid file descriptor or is not open for writing. | |
159 | .TP | |
c4c8b1da MK |
160 | .B EDESTADDRREQ |
161 | .I fd | |
162 | refers to a datagram socket for which a peer address has not been set using | |
163 | .BR connect (2). | |
164 | .TP | |
a1f01685 | 165 | .B EDQUOT |
9ee4a2b6 | 166 | The user's quota of disk blocks on the filesystem containing the file |
a1f01685 MH |
167 | referred to by |
168 | .I fd | |
169 | has been exhausted. | |
170 | .TP | |
fea681da MK |
171 | .B EFAULT |
172 | .I buf | |
173 | is outside your accessible address space. | |
174 | .TP | |
175 | .B EFBIG | |
176 | An attempt was made to write a file that exceeds the implementation-defined | |
a43e21f0 MK |
177 | maximum file size or the process's file size limit, |
178 | or to write at a position past the maximum allowed offset. | |
fea681da MK |
179 | .TP |
180 | .B EINTR | |
01538d0d MK |
181 | The call was interrupted by a signal before any data was written; see |
182 | .BR signal (7). | |
fea681da MK |
183 | .TP |
184 | .B EINVAL | |
185 | .I fd | |
94604cf7 | 186 | is attached to an object which is unsuitable for writing; |
c13182ef | 187 | or the file was opened with the |
94604cf7 MK |
188 | .B O_DIRECT |
189 | flag, and either the address specified in | |
190 | .IR buf , | |
191 | the value specified in | |
192 | .IR count , | |
c72249c5 | 193 | or the file offset is not suitably aligned. |
fea681da MK |
194 | .TP |
195 | .B EIO | |
196 | A low-level I/O error occurred while modifying the inode. | |
c6822f69 | 197 | This error may relate to the write-back of data written by an earlier |
549597a8 | 198 | .BR write (), |
9c93cce7 | 199 | which may have been issued to a different file descriptor on |
c6822f69 MK |
200 | the same file. |
201 | Since Linux 4.13, errors from write-back come | |
9c93cce7 N |
202 | with a promise that they |
203 | .I may | |
204 | be reported by subsequent. | |
549597a8 | 205 | .BR write () |
9c93cce7 N |
206 | requests, and |
207 | .I will | |
208 | be reported by a subsequent | |
209 | .BR fsync (2) | |
210 | (whether or not they were also reported by | |
549597a8 | 211 | .BR write ()). |
9c93cce7 | 212 | .\" commit 088737f44bbf6378745f5b57b035e57ee3dc4750 |
11cf58cd N |
213 | An alternate cause of |
214 | .B EIO | |
215 | on networked filesystems is when an advisory lock had been taken out | |
216 | on the file descriptor and this lock has been lost. | |
217 | See the | |
218 | .I "Lost locks" | |
219 | section of | |
220 | .BR fcntl (2) | |
221 | for further details. | |
fea681da MK |
222 | .TP |
223 | .B ENOSPC | |
224 | The device containing the file referred to by | |
225 | .I fd | |
226 | has no room for the data. | |
227 | .TP | |
fbab10e5 MK |
228 | .B EPERM |
229 | The operation was prevented by a file seal; see | |
230 | .BR fcntl (2). | |
231 | .TP | |
fea681da MK |
232 | .B EPIPE |
233 | .I fd | |
c13182ef MK |
234 | is connected to a pipe or socket whose reading end is closed. |
235 | When this happens the writing process will also receive a | |
fea681da MK |
236 | .B SIGPIPE |
237 | signal. | |
238 | (Thus, the write return value is seen only if the program | |
239 | catches, blocks or ignores this signal.) | |
240 | .PP | |
241 | Other errors may occur, depending on the object connected to | |
242 | .IR fd . | |
47297adb | 243 | .SH CONFORMING TO |
c13182ef | 244 | SVr4, 4.3BSD, POSIX.1-2001. |
97c1eac8 MK |
245 | .\" SVr4 documents additional error |
246 | .\" conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE. | |
efeece04 | 247 | .PP |
a9b4ebbc MK |
248 | Under SVr4 a write may be interrupted and return |
249 | .B EINTR | |
250 | at any point, | |
c13182ef | 251 | not just before any data is written. |
fea681da | 252 | .SH NOTES |
51015f14 MK |
253 | The types |
254 | .I size_t | |
255 | and | |
256 | .I ssize_t | |
257 | are, respectively, | |
258 | unsigned and signed integer data types specified by POSIX.1. | |
efeece04 | 259 | .PP |
fea681da | 260 | A successful return from |
e511ffb6 | 261 | .BR write () |
fea681da | 262 | does not make any guarantee that data has been committed to disk. |
9c93cce7 | 263 | On some filesystems, including NFS, it does not even guarantee |
c6822f69 MK |
264 | that space has successfully been reserved for the data. |
265 | In this case, | |
266 | some errors might be delayed until a future | |
549597a8 | 267 | .BR write (), |
c6822f69 | 268 | .BR fsync (2), |
9c93cce7 N |
269 | or even |
270 | .BR close (2). | |
fea681da MK |
271 | The only way to be sure is to call |
272 | .BR fsync (2) | |
273 | after you are done writing all your data. | |
efeece04 | 274 | .PP |
a43e21f0 MK |
275 | If a |
276 | .BR write () | |
277 | is interrupted by a signal handler before any bytes are written, | |
278 | then the call fails with the error | |
279 | .BR EINTR ; | |
280 | if it is interrupted after at least one byte has been written, | |
281 | the call succeeds, and returns the number of bytes written. | |
efeece04 | 282 | .PP |
77548009 | 283 | On Linux, |
6b693d86 | 284 | .BR write () |
77548009 MK |
285 | (and similar system calls) will transfer at most |
286 | 0x7ffff000 (2,147,479,552) bytes, | |
287 | returning the number of bytes actually transferred. | |
288 | .\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 | |
289 | (This is true on both 32-bit and 64-bit systems.) | |
ebf12012 GR |
290 | .PP |
291 | An error return value while performing | |
6614e292 | 292 | .BR write () |
ebf12012 GR |
293 | using direct I/O does not mean the |
294 | entire write has failed. Partial data may be written | |
295 | and the data at the file offset on which the | |
6614e292 | 296 | .BR write () |
ebf12012 | 297 | was attempted should be considered inconsistent. |
2afe9365 MK |
298 | .SH BUGS |
299 | According to POSIX.1-2008/SUSv4 Section XSI 2.9.7 | |
300 | ("Thread Interactions with Regular File Operations"): | |
efeece04 | 301 | .PP |
2afe9365 MK |
302 | .RS 4 |
303 | All of the following functions shall be atomic with respect to | |
304 | each other in the effects specified in POSIX.1-2008 when they | |
305 | operate on regular files or symbolic links: ... | |
306 | .RE | |
efeece04 | 307 | .PP |
2afe9365 MK |
308 | Among the APIs subsequently listed are |
309 | .BR write () | |
310 | and | |
311 | .BR writev (2). | |
312 | And among the effects that should be atomic across threads (and processes) | |
313 | are updates of the file offset. | |
314 | However, on Linux before version 3.14, | |
315 | this was not the case: if two processes that share | |
316 | an open file description (see | |
317 | .BR open (2)) | |
318 | perform a | |
319 | .BR write () | |
320 | (or | |
321 | .BR writev (2)) | |
322 | at the same time, then the I/O operations were not atomic | |
323 | with respect updating the file offset, | |
324 | with the result that the blocks of data output by the two processes | |
325 | might (incorrectly) overlap. | |
326 | This problem was fixed in Linux 3.14. | |
327 | .\" http://thread.gmane.org/gmane.linux.kernel/1649458 | |
328 | .\" From: Michael Kerrisk (man-pages <mtk.manpages <at> gmail.com> | |
329 | .\" Subject: Update of file offset on write() etc. is non-atomic with I/O | |
330 | .\" Date: 2014-02-17 15:41:37 GMT | |
331 | .\" Newsgroups: gmane.linux.kernel, gmane.linux.file-systems | |
332 | .\" commit 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4 | |
333 | .\" Author: Linus Torvalds <torvalds@linux-foundation.org> | |
334 | .\" Date: Mon Mar 3 09:36:58 2014 -0800 | |
ffb30e75 | 335 | .\" |
2afe9365 | 336 | .\" vfs: atomic f_pos accesses as per POSIX |
47297adb | 337 | .SH SEE ALSO |
fea681da MK |
338 | .BR close (2), |
339 | .BR fcntl (2), | |
340 | .BR fsync (2), | |
341 | .BR ioctl (2), | |
342 | .BR lseek (2), | |
343 | .BR open (2), | |
64c7bb8a | 344 | .BR pwrite (2), |
fea681da MK |
345 | .BR read (2), |
346 | .BR select (2), | |
ed93deb2 | 347 | .BR writev (2), |
7677b814 | 348 | .BR fwrite (3) |