1WRITE(3P) POSIX Programmer's Manual WRITE(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 pwrite, write - write on a file
13
15 #include <unistd.h>
16 ssize_t pwrite(int fildes, const void *buf, size_t nbyte,
20 off_t offset);
21 ssize_t write(int fildes, const void *buf, size_t nbyte);
22
25 The write() function shall attempt to write nbyte bytes from the buffer
26 pointed to by buf to the file associated with the open file descriptor,
27 fildes.
28 Before any action described below is taken, and if nbyte is zero and
30 the file is a regular file, the write() function may detect and return
31 errors as described below. In the absence of errors, or if error detec‐
32 tion is not performed, the write() function shall return zero and have
33 no other results. If nbyte is zero and the file is not a regular file,
34 the results are unspecified.
35 On a regular file or other file capable of seeking, the actual writing
37 of data shall proceed from the position in the file indicated by the
38 file offset associated with fildes. Before successful return from
39 write(), the file offset shall be incremented by the number of bytes
40 actually written. On a regular file, if this incremented file offset is
41 greater than the length of the file, the length of the file shall be
42 set to this file offset.
43 On a file not capable of seeking, writing shall always take place
45 starting at the current position. The value of a file offset associated
46 with such a device is undefined.
47 If the O_APPEND flag of the file status flags is set, the file offset
49 shall be set to the end of the file prior to each write and no inter‐
50 vening file modification operation shall occur between changing the
51 file offset and the write operation.
52 If a write() requests that more bytes be written than there is room for
54 (for example, the process' file size limit or the physical end of a
55 medium), only as many bytes as there is room for shall be written. For
56 example, suppose there is space for 20 bytes more in a file before
57 reaching a limit. A write of 512 bytes will return 20. The next write
58 of a non-zero number of bytes would give a failure return (except as
59 noted below).
60 If the request would cause the file size to exceed the soft file size
62 limit for the process and there is no room for any bytes to be written,
63 the request shall fail and the implementation shall generate the
64 SIGXFSZ signal for the thread.
65 If write() is interrupted by a signal before it writes any data, it
67 shall return -1 with errno set to [EINTR].
68 If write() is interrupted by a signal after it successfully writes some
70 data, it shall return the number of bytes written.
71 If the value of nbyte is greater than {SSIZE_MAX}, the result is imple‐
73 mentation-defined.
74 After a write() to a regular file has successfully returned:
76 * Any successful read() from each byte position in the file that was
78 modified by that write shall return the data specified by the
79 write() for that position until such byte positions are again modi‐
80 fied.
81 * Any subsequent successful write() to the same byte position in the
83 file shall overwrite that file data.
84 Write requests to a pipe or FIFO shall be handled in the same way as a
86 regular file with the following exceptions:
87 * There is no file offset associated with a pipe, hence each write
89 request shall append to the end of the pipe.
90 * Write requests of {PIPE_BUF} bytes or less shall not be interleaved
92 with data from other processes doing writes on the same pipe. Writes
93 of greater than {PIPE_BUF} bytes may have data interleaved, on arbi‐
94 trary boundaries, with writes by other processes, whether or not the
95 O_NONBLOCK flag of the file status flags is set.
96 * If the O_NONBLOCK flag is clear, a write request may cause the
98 thread to block, but on normal completion it shall return nbyte.
99 * If the O_NONBLOCK flag is set, write() requests shall be handled
101 differently, in the following ways:
102 * The write() function shall not block the thread.
104 * A write request for {PIPE_BUF} or fewer bytes shall have the fol‐
106 lowing effect: if there is sufficient space available in the
107 pipe, write() shall transfer all the data and return the number
108 of bytes requested. Otherwise, write() shall transfer no data and
109 return -1 with errno set to [EAGAIN].
110 * A write request for more than {PIPE_BUF} bytes shall cause one of
112 the following:
113 * When at least one byte can be written, transfer what it can
115 and return the number of bytes written. When all data previ‐
116 ously written to the pipe is read, it shall transfer at least
117 {PIPE_BUF} bytes.
118 * When no data can be written, transfer no data, and return -1
120 with errno set to [EAGAIN].
121 When attempting to write to a file descriptor (other than a pipe or
123 FIFO) that supports non-blocking writes and cannot accept the data
124 immediately:
125 * If the O_NONBLOCK flag is clear, write() shall block the calling
127 thread until the data can be accepted.
128 * If the O_NONBLOCK flag is set, write() shall not block the thread.
130 If some data can be written without blocking the thread, write()
131 shall write what it can and return the number of bytes written. Oth‐
132 erwise, it shall return -1 and set errno to [EAGAIN].
133 Upon successful completion, where nbyte is greater than 0, write()
135 shall mark for update the st_ctime and st_mtime fields of the file, and
136 if the file is a regular file, the S_ISUID and S_ISGID bits of the file
137 mode may be cleared.
138 For regular files, no data transfer shall occur past the offset maximum
140 established in the open file description associated with fildes.
141 If fildes refers to a socket, write() shall be equivalent to send()
143 with no flags set.
144 If the O_DSYNC bit has been set, write I/O operations on the file
146 descriptor shall complete as defined by synchronized I/O data integrity
147 completion.
148 If the O_SYNC bit has been set, write I/O operations on the file
150 descriptor shall complete as defined by synchronized I/O file integrity
151 completion.
152 If fildes refers to a shared memory object, the result of the write()
154 function is unspecified.
155 If fildes refers to a typed memory object, the result of the write()
157 function is unspecified.
158 If fildes refers to a STREAM, the operation of write() shall be deter‐
160 mined by the values of the minimum and maximum nbyte range (packet
161 size) accepted by the STREAM. These values are determined by the top‐
162 most STREAM module. If nbyte falls within the packet size range, nbyte
163 bytes shall be written. If nbyte does not fall within the range and
164 the minimum packet size value is 0, write() shall break the buffer into
165 maximum packet size segments prior to sending the data downstream (the
166 last segment may contain less than the maximum packet size). If nbyte
167 does not fall within the range and the minimum value is non-zero,
168 write() shall fail with errno set to [ERANGE]. Writing a zero-length
169 buffer ( nbyte is 0) to a STREAMS device sends 0 bytes with 0 returned.
170 However, writing a zero-length buffer to a STREAMS-based pipe or FIFO
171 sends no message and 0 is returned. The process may issue I_SWROPT
172 ioctl() to enable zero-length messages to be sent across the pipe or
173 FIFO.
174 When writing to a STREAM, data messages are created with a priority
176 band of 0. When writing to a STREAM that is not a pipe or FIFO:
177 * If O_NONBLOCK is clear, and the STREAM cannot accept data (the
179 STREAM write queue is full due to internal flow control conditions),
180 write() shall block until data can be accepted.
181 * If O_NONBLOCK is set and the STREAM cannot accept data, write()
183 shall return -1 and set errno to [EAGAIN].
184 * If O_NONBLOCK is set and part of the buffer has been written while a
186 condition in which the STREAM cannot accept additional data occurs,
187 write() shall terminate and return the number of bytes written.
188 In addition, write() shall fail if the STREAM head has processed an
190 asynchronous error before the call. In this case, the value of errno
191 does not reflect the result of write(), but reflects the prior error.
192 The pwrite() function shall be equivalent to write(), except that it
194 writes into a given position without changing the file pointer. The
195 first three arguments to pwrite() are the same as write() with the
196 addition of a fourth argument offset for the desired position inside
197 the file.
198
200 Upon successful completion, write() and pwrite() shall return the num‐
201 ber of bytes actually written to the file associated with fildes. This
202 number shall never be greater than nbyte. Otherwise, -1 shall be
203 returned and errno set to indicate the error.
204
206 The write() and pwrite() functions shall fail if:
207 EAGAIN The O_NONBLOCK flag is set for the file descriptor and the
209 thread would be delayed in the write() operation.
210 EBADF The fildes argument is not a valid file descriptor open for
212 writing.
213 EFBIG An attempt was made to write a file that exceeds the implementa‐
215 tion-defined maximum file size or the process' file size limit,
216 and there was no room for any bytes to be written.
217 EFBIG The file is a regular file, nbyte is greater than 0, and the
219 starting position is greater than or equal to the offset maximum
220 established in the open file description associated with fildes.
221 EINTR The write operation was terminated due to the receipt of a sig‐
223 nal, and no data was transferred.
224 EIO The process is a member of a background process group attempting
226 to write to its controlling terminal, TOSTOP is set, the process
227 is neither ignoring nor blocking SIGTTOU, and the process group
228 of the process is orphaned. This error may also be returned
229 under implementation-defined conditions.
230 ENOSPC There was no free space remaining on the device containing the
232 file.
233 EPIPE An attempt is made to write to a pipe or FIFO that is not open
235 for reading by any process, or that only has one end open. A
236 SIGPIPE signal shall also be sent to the thread.
237 ERANGE The transfer request size was outside the range supported by the
239 STREAMS file associated with fildes.
240 The write() function shall fail if:
243 EAGAIN or EWOULDBLOCK
245 The file descriptor is for a socket, is marked O_NONBLOCK, and
247 write would block.
248 ECONNRESET
250 A write was attempted on a socket that is not connected.
251 EPIPE A write was attempted on a socket that is shut down for writing,
253 or is no longer connected. In the latter case, if the socket is
254 of type SOCK_STREAM, the SIGPIPE signal is generated to the
255 calling process.
256 The write() and pwrite() functions may fail if:
259 EINVAL The STREAM or multiplexer referenced by fildes is linked
261 (directly or indirectly) downstream from a multiplexer.
262 EIO A physical I/O error has occurred.
264 ENOBUFS
266 Insufficient resources were available in the system to perform
267 the operation.
268 ENXIO A request was made of a nonexistent device, or the request was
270 outside the capabilities of the device.
271 ENXIO A hangup occurred on the STREAM being written to.
273 A write to a STREAMS file may fail if an error message has been
276 received at the STREAM head. In this case, errno is set to the value
277 included in the error message.
278 The write() function may fail if:
280 EACCES A write was attempted on a socket and the calling process does
282 not have appropriate privileges.
283 ENETDOWN
285 A write was attempted on a socket and the local network inter‐
286 face used to reach the destination is down.
287 ENETUNREACH
289 A write was attempted on a socket and no route to the network is
291 present.
292 The pwrite() function shall fail and the file pointer remain unchanged
295 if:
296 EINVAL The offset argument is invalid. The value is negative.
298 ESPIPE fildes is associated with a pipe or FIFO.
300 The following sections are informative.
303
305 Writing from a Buffer
306 The following example writes data from the buffer pointed to by buf to
307 the file associated with the file descriptor fd.
308 #include <sys/types.h>
311 #include <string.h>
312 ...
313 char buf[20];
314 size_t nbytes;
315 ssize_t bytes_written;
316 int fd;
317 ...
318 strcpy(buf, "This is a test\n");
319 nbytes = strlen(buf);
320 bytes_written = write(fd, buf, nbytes);
323 ...
324
326 None.
327
329 See also the RATIONALE section in read().
330 An attempt to write to a pipe or FIFO has several major characteris‐
332 tics:
333 * Atomic/non-atomic: A write is atomic if the whole amount written in
335 one operation is not interleaved with data from any other process.
336 This is useful when there are multiple writers sending data to a
337 single reader. Applications need to know how large a write request
338 can be expected to be performed atomically. This maximum is called
339 {PIPE_BUF}. This volume of IEEE Std 1003.1-2001 does not say whether
340 write requests for more than {PIPE_BUF} bytes are atomic, but
341 requires that writes of {PIPE_BUF} or fewer bytes shall be atomic.
342 * Blocking/immediate: Blocking is only possible with O_NONBLOCK clear.
344 If there is enough space for all the data requested to be written
345 immediately, the implementation should do so. Otherwise, the process
346 may block; that is, pause until enough space is available for writ‐
347 ing. The effective size of a pipe or FIFO (the maximum amount that
348 can be written in one operation without blocking) may vary dynami‐
349 cally, depending on the implementation, so it is not possible to
350 specify a fixed value for it.
351 * Complete/partial/deferred: A write request:
353 int fildes;
356 size_t nbyte;
357 ssize_t ret;
358 char *buf;
359 ret = write(fildes, buf, nbyte);
362 may return:
364 Complete
366 ret=nbyte
367 Partial
369 ret<nbyte
370 This shall never happen if nbyte<= {PIPE_BUF}. If it does happen
372 (with nbyte> {PIPE_BUF}), this volume of IEEE Std 1003.1-2001
373 does not guarantee atomicity, even if ret<= {PIPE_BUF}, because
374 atomicity is guaranteed according to the amount requested, not
375 the amount written.
376 Deferred:
378 ret=-1, errno=[EAGAIN]
379 This error indicates that a later request may succeed. It does
381 not indicate that it shall succeed, even if nbyte<= {PIPE_BUF},
382 because if no process reads from the pipe or FIFO, the write
383 never succeeds. An application could usefully count the number
384 of times [EAGAIN] is caused by a particular value of nbyte>
385 {PIPE_BUF} and perhaps do later writes with a smaller value, on
386 the assumption that the effective size of the pipe may have
387 decreased.
388 Partial and deferred writes are only possible with O_NONBLOCK set.
391 The relations of these properties are shown in the following tables:
393 Write to a Pipe or FIFO with O_NONBLOCK clear
395 Immediately Writable: None Some nbyte
396 nbyte<={PIPE_BUF} Atomic blocking Atomic blocking Atomic immediate
398 nbyte nbyte nbyte
399 nbyte>{PIPE_BUF} Blocking nbyte Blocking nbyte Blocking nbyte
400 If the O_NONBLOCK flag is clear, a write request shall block if the
402 amount writable immediately is less than that requested. If the flag is
403 set (by fcntl()), a write request shall never block.
404 Write to a Pipe or FIFO with O_NONBLOCK set
406 Immediately Writable: None Some nbyte
407 nbyte<={PIPE_BUF} -1, [EAGAIN] -1, [EAGAIN] Atomic nbyte
408 nbyte>{PIPE_BUF} -1, [EAGAIN] <nbyte or -1, <=nbyte or -1,
409 [EAGAIN] [EAGAIN]
410 There is no exception regarding partial writes when O_NONBLOCK is set.
412 With the exception of writing to an empty pipe, this volume of
413 IEEE Std 1003.1-2001 does not specify exactly when a partial write is
414 performed since that would require specifying internal details of the
415 implementation. Every application should be prepared to handle partial
416 writes when O_NONBLOCK is set and the requested amount is greater than
417 {PIPE_BUF}, just as every application should be prepared to handle par‐
418 tial writes on other kinds of file descriptors.
419 The intent of forcing writing at least one byte if any can be written
421 is to assure that each write makes progress if there is any room in the
422 pipe. If the pipe is empty, {PIPE_BUF} bytes must be written; if not,
423 at least some progress must have been made.
424 Where this volume of IEEE Std 1003.1-2001 requires -1 to be returned
426 and errno set to [EAGAIN], most historical implementations return zero
427 (with the O_NDELAY flag set, which is the historical predecessor of
428 O_NONBLOCK, but is not itself in this volume of IEEE Std 1003.1-2001).
429 The error indications in this volume of IEEE Std 1003.1-2001 were cho‐
430 sen so that an application can distinguish these cases from end-of-
431 file. While write() cannot receive an indication of end-of-file,
432 read() can, and the two functions have similar return values. Also,
433 some existing systems (for example, Eighth Edition) permit a write of
434 zero bytes to mean that the reader should get an end-of-file indica‐
435 tion; for those systems, a return value of zero from write() indicates
436 a successful write of an end-of-file indication.
437 Implementations are allowed, but not required, to perform error check‐
439 ing for write() requests of zero bytes.
440 The concept of a {PIPE_MAX} limit (indicating the maximum number of
442 bytes that can be written to a pipe in a single operation) was consid‐
443 ered, but rejected, because this concept would unnecessarily limit
444 application writing.
445 See also the discussion of O_NONBLOCK in read().
447 Writes can be serialized with respect to other reads and writes. If a
449 read() of file data can be proven (by any means) to occur after a
450 write() of the data, it must reflect that write(), even if the calls
451 are made by different processes. A similar requirement applies to mul‐
452 tiple write operations to the same file position. This is needed to
453 guarantee the propagation of data from write() calls to subsequent
454 read() calls. This requirement is particularly significant for net‐
455 worked file systems, where some caching schemes violate these seman‐
456 tics.
457 Note that this is specified in terms of read() and write(). The XSI
459 extensions readv() and writev() also obey these semantics. A new "high-
460 performance" write analog that did not follow these serialization
461 requirements would also be permitted by this wording. This volume of
462 IEEE Std 1003.1-2001 is also silent about any effects of application-
463 level caching (such as that done by stdio).
464 This volume of IEEE Std 1003.1-2001 does not specify the value of the
466 file offset after an error is returned; there are too many cases. For
467 programming errors, such as [EBADF], the concept is meaningless since
468 no file is involved. For errors that are detected immediately, such as
469 [EAGAIN], clearly the pointer should not change. After an interrupt or
470 hardware error, however, an updated value would be very useful and is
471 the behavior of many implementations.
472 This volume of IEEE Std 1003.1-2001 does not specify behavior of con‐
474 current writes to a file from multiple processes. Applications should
475 use some form of concurrency control.
476
478 None.
479
481 chmod(), creat(), dup(), fcntl(), getrlimit(), lseek(), open(), pipe(),
482 ulimit(), writev(), the Base Definitions volume of
483 IEEE Std 1003.1-2001, <limits.h>, <stropts.h>, <sys/uio.h>, <unistd.h>
484
486 Portions of this text are reprinted and reproduced in electronic form
487 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
488 -- Portable Operating System Interface (POSIX), The Open Group Base
489 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
490 Electrical and Electronics Engineers, Inc and The Open Group. In the
491 event of any discrepancy between this version and the original IEEE and
492 The Open Group Standard, the original IEEE and The Open Group Standard
493 is the referee document. The original Standard can be obtained online
494 at http://www.opengroup.org/unix/online.html .
495IEEE/The Open Group 2003 WRITE(3P)