1WRITE(3P)                  POSIX Programmer's Manual                 WRITE(3P)
2
3
4

PROLOG

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

NAME

12       pwrite, write - write on a file
13

SYNOPSIS

15       #include <unistd.h>
16
17
18
19       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
23

DESCRIPTION

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
29       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
36       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
44       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
48       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
53       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
61       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
66       If  write()  is  interrupted  by a signal before it writes any data, it
67       shall return -1 with errno set to [EINTR].
68
69       If write() is interrupted by a signal after it successfully writes some
70       data, it shall return the number of bytes written.
71
72       If the value of nbyte is greater than {SSIZE_MAX}, the result is imple‐
73       mentation-defined.
74
75       After a write() to a regular file has successfully returned:
76
77        * 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
82        * Any  subsequent  successful write() to the same byte position in the
83          file shall overwrite that file data.
84
85       Write requests to a pipe or FIFO shall be handled in the same way as  a
86       regular file with the following exceptions:
87
88        * There  is  no  file  offset associated with a pipe, hence each write
89          request shall append to the end of the pipe.
90
91        * 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
97        * 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
100        * If  the  O_NONBLOCK  flag  is set, write() requests shall be handled
101          differently, in the following ways:
102
103           * The write() function shall not block the thread.
104
105           * 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
111           * A write request for more than {PIPE_BUF} bytes shall cause one of
112             the following:
113
114              * 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
119              * When no data can be written, transfer no data, and  return  -1
120                with errno set to [EAGAIN].
121
122       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
126        * If  the  O_NONBLOCK  flag  is clear, write() shall block the calling
127          thread until the data can be accepted.
128
129        * 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
134       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
139       For regular files, no data transfer shall occur past the offset maximum
140       established in the open file description associated with fildes.
141
142       If  fildes  refers  to  a socket, write() shall be equivalent to send()
143       with no flags set.
144
145       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
149       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
153       If fildes refers to a shared memory object, the result of  the  write()
154       function is unspecified.
155
156       If  fildes  refers  to a typed memory object, the result of the write()
157       function is unspecified.
158
159       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
175       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
178        * 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
182        * If  O_NONBLOCK  is  set  and  the STREAM cannot accept data, write()
183          shall return -1 and set errno to [EAGAIN].
184
185        * 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
189       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
193       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

RETURN VALUE

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

ERRORS

206       The write() and   pwrite()  functions shall fail if:
207
208       EAGAIN The  O_NONBLOCK  flag  is  set  for  the file descriptor and the
209              thread would be delayed in the write() operation.
210
211       EBADF  The fildes argument is not a  valid  file  descriptor  open  for
212              writing.
213
214       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
218       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
222       EINTR  The  write operation was terminated due to the receipt of a sig‐
223              nal, and no data was transferred.
224
225       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
231       ENOSPC There was no free space remaining on the device  containing  the
232              file.
233
234       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
238       ERANGE The transfer request size was outside the range supported by the
239              STREAMS file associated with fildes.
240
241
242       The write() function shall fail if:
243
244       EAGAIN or EWOULDBLOCK
245
246              The file descriptor is for a socket, is marked  O_NONBLOCK,  and
247              write would block.
248
249       ECONNRESET
250              A write was attempted on a socket that is not connected.
251
252       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
257
258       The write() and   pwrite()  functions may fail if:
259
260       EINVAL The  STREAM  or  multiplexer  referenced  by  fildes  is  linked
261              (directly or indirectly) downstream from a multiplexer.
262
263       EIO    A physical I/O error has occurred.
264
265       ENOBUFS
266              Insufficient  resources  were available in the system to perform
267              the operation.
268
269       ENXIO  A request was made of a nonexistent device, or the  request  was
270              outside the capabilities of the device.
271
272       ENXIO  A hangup occurred on the STREAM being written to.
273
274
275       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
279       The write() function may fail if:
280
281       EACCES A  write  was attempted on a socket and the calling process does
282              not have appropriate privileges.
283
284       ENETDOWN
285              A write was attempted on a socket and the local  network  inter‐
286              face used to reach the destination is down.
287
288       ENETUNREACH
289
290              A write was attempted on a socket and no route to the network is
291              present.
292
293
294       The pwrite() function shall fail and the file pointer remain  unchanged
295       if:
296
297       EINVAL The offset argument is invalid. The value is negative.
298
299       ESPIPE fildes is associated with a pipe or FIFO.
300
301
302       The following sections are informative.
303

EXAMPLES

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
309
310              #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
321
322              bytes_written = write(fd, buf, nbytes);
323              ...
324

APPLICATION USAGE

326       None.
327

RATIONALE

329       See also the RATIONALE section in read().
330
331       An attempt to write to a pipe or FIFO has  several  major  characteris‐
332       tics:
333
334        * 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
343        * 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
352        * Complete/partial/deferred: A write request:
353
354
355          int fildes;
356          size_t nbyte;
357          ssize_t ret;
358          char *buf;
359
360
361          ret = write(fildes, buf, nbyte);
362
363       may return:
364
365       Complete
366              ret=nbyte
367
368       Partial
369              ret<nbyte
370
371              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
377       Deferred:
378              ret=-1, errno=[EAGAIN]
379
380              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
389
390       Partial and deferred writes are only possible with O_NONBLOCK set.
391
392       The relations of these properties are shown in the following tables:
393
394                    Write to a Pipe or FIFO with O_NONBLOCK clear
395      Immediately Writable:  None             Some             nbyte
396
397      nbyte<={PIPE_BUF}      Atomic blocking  Atomic blocking  Atomic immediate
398                             nbyte            nbyte            nbyte
399      nbyte>{PIPE_BUF}       Blocking nbyte   Blocking nbyte   Blocking nbyte
400
401       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
405                    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
411       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
420       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
425       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
438       Implementations  are allowed, but not required, to perform error check‐
439       ing for write() requests of zero bytes.
440
441       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
446       See also the discussion of O_NONBLOCK in read().
447
448       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
458       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
465       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
473       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

FUTURE DIRECTIONS

478       None.
479

SEE ALSO

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 .
495
496
497
498IEEE/The Open Group                  2003                            WRITE(3P)
Impressum