1WRITE(2)                   Linux Programmer's Manual                  WRITE(2)
2
3
4

NAME

6       write - write to a file descriptor
7

SYNOPSIS

9       #include <unistd.h>
10
11       ssize_t write(int fd, const void *buf, size_t count);
12

DESCRIPTION

14       write() writes up to count bytes from the buffer starting at buf to the
15       file referred to by the file descriptor fd.
16
17       The number of bytes written may be less than  count  if,  for  example,
18       there  is  insufficient space on the underlying physical medium, or the
19       RLIMIT_FSIZE resource limit is encountered (see setrlimit(2)),  or  the
20       call was interrupted by a signal handler after having written less than
21       count bytes.  (See also pipe(7).)
22
23       For a seekable file (i.e., one to which lseek(2) may  be  applied,  for
24       example,  a  regular  file) writing takes place at the file offset, and
25       the file offset is incremented by the number of bytes actually written.
26       If  the  file was open(2)ed with O_APPEND, the file offset is first set
27       to the end of the file before writing.  The adjustment of the file off‐
28       set and the write operation are performed as an atomic step.
29
30       POSIX  requires  that  a  read(2)  that  can be proved to occur after a
31       write() has returned will return the  new  data.   Note  that  not  all
32       filesystems are POSIX conforming.
33
34       According to POSIX.1, if count is greater than SSIZE_MAX, the result is
35       implementation-defined; see NOTES for the upper limit on Linux.
36

RETURN VALUE

38       On success, the number of bytes written is returned.  On error,  -1  is
39       returned, and errno is set to indicate the cause of the error.
40
41       Note  that  a  successful  write() may transfer fewer than count bytes.
42       Such partial writes can occur for various reasons; for example, because
43       there  was  insufficient  space  on the disk device to write all of the
44       requested bytes, or because a blocked write() to  a  socket,  pipe,  or
45       similar  was  interrupted  by a signal handler after it had transferred
46       some, but before it had transferred all of the requested bytes.  In the
47       event  of  a partial write, the caller can make another write() call to
48       transfer the remaining bytes.  The subsequent call will either transfer
49       further  bytes  or  may  result  in  an error (e.g., if the disk is now
50       full).
51
52       If count is zero and fd refers to a  regular  file,  then  write()  may
53       return  a failure status if one of the errors below is detected.  If no
54       errors are detected, or error detection is not  performed,  0  will  be
55       returned  without  causing  any  other effect.  If count is zero and fd
56       refers to a file other than a regular file, the results are not  speci‐
57       fied.
58

ERRORS

60       EAGAIN The  file descriptor fd refers to a file other than a socket and
61              has been marked nonblocking (O_NONBLOCK), and  the  write  would
62              block.  See open(2) for further details on the O_NONBLOCK flag.
63
64       EAGAIN or EWOULDBLOCK
65              The  file  descriptor  fd refers to a socket and has been marked
66              nonblocking   (O_NONBLOCK),   and   the   write   would   block.
67              POSIX.1-2001  allows  either error to be returned for this case,
68              and does not require these constants to have the same value,  so
69              a portable application should check for both possibilities.
70
71       EBADF  fd is not a valid file descriptor or is not open for writing.
72
73       EDESTADDRREQ
74              fd  refers to a datagram socket for which a peer address has not
75              been set using connect(2).
76
77       EDQUOT The user's quota of disk blocks on the filesystem containing the
78              file referred to by fd has been exhausted.
79
80       EFAULT buf is outside your accessible address space.
81
82       EFBIG  An attempt was made to write a file that exceeds the implementa‐
83              tion-defined maximum file size or the process's file size limit,
84              or to write at a position past the maximum allowed offset.
85
86       EINTR  The  call  was interrupted by a signal before any data was writ‐
87              ten; see signal(7).
88
89       EINVAL fd is attached to an object which is unsuitable for writing;  or
90              the  file  was  opened  with  the  O_DIRECT flag, and either the
91              address specified in buf, the value specified in count,  or  the
92              file offset is not suitably aligned.
93
94       EIO    A  low-level I/O error occurred while modifying the inode.  This
95              error may relate to the write-back of data written by an earlier
96              write(2),  which  may  have  been  issued  to  a  different file
97              descriptor on the same file.   Since  Linux  4.13,  errors  from
98              write-back come with a promise that they may be reported by sub‐
99              sequent.  write(2) requests, and will be reported  by  a  subse‐
100              quent  fsync(2)  (whether  or  not  they  were  also reported by
101              write(2)).  An alternate cause of EIO on  networked  filesystems
102              is when an advisory lock had been taken out on the file descrip‐
103              tor and this lock has been lost.  See the Lost locks section  of
104              fcntl(2) for further details.
105
106       ENOSPC The device containing the file referred to by fd has no room for
107              the data.
108
109       EPERM  The operation was prevented by a file seal; see fcntl(2).
110
111       EPIPE  fd is connected to a pipe or socket whose reading end is closed.
112              When  this  happens the writing process will also receive a SIG‐
113              PIPE signal.  (Thus, the write return value is seen only if  the
114              program catches, blocks or ignores this signal.)
115
116       Other errors may occur, depending on the object connected to fd.
117

CONFORMING TO

119       SVr4, 4.3BSD, POSIX.1-2001.
120
121       Under  SVr4  a  write may be interrupted and return EINTR at any point,
122       not just before any data is written.
123

NOTES

125       The types size_t and ssize_t are,  respectively,  unsigned  and  signed
126       integer data types specified by POSIX.1.
127
128       A  successful return from write() does not make any guarantee that data
129       has been committed to disk.  On some  filesystems,  including  NFS,  it
130       does  not  even guarantee that space has successfully been reserved for
131       the data.  In this case, some errors might be delayed  until  a  future
132       write(2),  fsync(2),  or  even close(2).  The only way to be sure is to
133       call fsync(2) after you are done writing all your data.
134
135       If a write() is interrupted by a signal handler before  any  bytes  are
136       written, then the call fails with the error EINTR; if it is interrupted
137       after at least one byte  has  been  written,  the  call  succeeds,  and
138       returns the number of bytes written.
139
140       On  Linux,  write()  (and  similar  system calls) will transfer at most
141       0x7ffff000 (2,147,479,552) bytes, returning the number of  bytes  actu‐
142       ally transferred.  (This is true on both 32-bit and 64-bit systems.)
143
144       An  error  return  value while performing write() using direct I/O does
145       not mean the entire write has failed. Partial data may be  written  and
146       the  data  at the file offset on which the write() was attempted should
147       be considered inconsistent.
148

BUGS

150       According to POSIX.1-2008/SUSv4 Section XSI 2.9.7 ("Thread Interactions
151       with Regular File Operations"):
152
153           All of the following functions shall be atomic with respect to each
154           other in the effects specified in POSIX.1-2008 when they operate on
155           regular files or symbolic links: ...
156
157       Among  the  APIs  subsequently  listed  are write() and writev(2).  And
158       among the effects that should be atomic across threads (and  processes)
159       are updates of the file offset.  However, on Linux before version 3.14,
160       this was not the case:  if  two  processes  that  share  an  open  file
161       description  (see open(2)) perform a write() (or writev(2)) at the same
162       time, then the I/O operations were not atomic with respect updating the
163       file  offset, with the result that the blocks of data output by the two
164       processes might (incorrectly) overlap.  This problem was fixed in Linux
165       3.14.
166

SEE ALSO

168       close(2),  fcntl(2),  fsync(2), ioctl(2), lseek(2), open(2), pwrite(2),
169       read(2), select(2), writev(2), fwrite(3)
170

COLOPHON

172       This page is part of release 5.02 of the Linux  man-pages  project.   A
173       description  of  the project, information about reporting bugs, and the
174       latest    version    of    this    page,    can     be     found     at
175       https://www.kernel.org/doc/man-pages/.
176
177
178
179Linux                             2019-03-06                          WRITE(2)
Impressum