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