1write(2) System Calls write(2)
2
6 write, pwrite, writev - write on a file
7
9 #include <unistd.h>
10 ssize_t write(int fildes, const void *buf, size_t nbyte);
12 ssize_t pwrite(int fildes, const void *buf, size_t nbyte,
15 off_t offset);
16 #include <sys/uio.h>
19 ssize_t writev(int fildes, const struct iovec *iov, int iovcnt);
21
24 The write() function attempts to write nbyte bytes from the buffer
25 pointed to by buf to the file associated with the open file descriptor,
26 fildes.
27 If nbyte is 0, write() will return 0 and have no other results if the
30 file is a regular file; otherwise, the results are unspecified.
31 On a regular file or other file capable of seeking, the actual writing
34 of data proceeds from the position in the file indicated by the file
35 offset associated with fildes. Before successful return from write(),
36 the file offset is incremented by the number of bytes actually written.
37 On a regular file, if this incremented file offset is greater than the
38 length of the file, the length of the file will be set to this file
39 offset.
40 If the O_SYNC bit has been set, write I/O operations on the file
43 descriptor complete as defined by synchronized I/O file integrity com‐
44 pletion.
45 If fildes refers to a socket, write() is equivalent to send(3SOCKET)
48 with no flags set.
49 On a file not capable of seeking, writing always takes place starting
52 at the current position. The value of a file offset associated with
53 such a device is undefined.
54 If the O_APPEND flag of the file status flags is set, the file offset
57 will be set to the end of the file prior to each write and no interven‐
58 ing file modification operation will occur between changing the file
59 offset and the write operation.
60 For regular files, no data transfer will occur past the offset maximum
63 established in the open file description with fildes.
64 A write() to a regular file is blocked if mandatory file/record locking
67 is set (see chmod(2)), and there is a record lock owned by another
68 process on the segment of the file to be written:
69 o If O_NDELAY or O_NONBLOCK is set, write() returns −1 and
71 sets errno to EAGAIN.
72 o If O_NDELAY and O_NONBLOCK are clear, write() sleeps until
74 all blocking locks are removed or the write() is terminated
75 by a signal.
76 If a write() requests that more bytes be written than there is room
79 for—for example, if the write would exceed the process file size limit
80 (see getrlimit(2) and ulimit(2)), the system file size limit, or the
81 free space on the device—only as many bytes as there is room for will
82 be written. For example, suppose there is space for 20 bytes more in a
83 file before reaching a limit. A write() of 512-bytes returns 20. The
84 next write() of a non-zero number of bytes gives a failure return
85 (except as noted for pipes and FIFO below).
86 If write() is interrupted by a signal before it writes any data, it
89 will return −1 with errno set to EINTR.
90 If write() is interrupted by a signal after it successfully writes some
93 data, it will return the number of bytes written.
94 If write() exceeds the process file size limit, the application gener‐
97 ates a SIGXFSZ signal, whose default behavior is to dump core.
98 After a write() to a regular file has successfully returned:
101 o Any successful read(2) from each byte position in the file
103 that was modified by that write will return the data speci‐
104 fied by the write() for that position until such byte posi‐
105 tions are again modified.
106 o Any subsequent successful write() to the same byte position
108 in the file will overwrite that file data.
109 Write requests to a pipe or FIFO are handled the same as a regular file
112 with the following exceptions:
113 o There is no file offset associated with a pipe, hence each
115 write request appends to the end of the pipe.
116 o Write requests of {PIPE_BUF} bytes or less are guaranteed
118 not to be interleaved with data from other processes doing
119 writes on the same pipe. Writes of greater than {PIPE_BUF}
120 bytes may have data interleaved, on arbitrary boundaries,
121 with writes by other processes, whether or not the O_NON‐
122 BLOCK or O_NDELAY flags are set.
123 o If O_NONBLOCK and O_NDELAY are clear, a write request may
125 cause the process to block, but on normal completion it
126 returns nbyte.
127 o If O_NONBLOCK and O_NDELAY are set, write() does not block
129 the process. If a write() request for PIPE_BUF or fewer
130 bytes succeeds completely write() returns nbyte. Otherwise,
131 if O_NONBLOCK is set, it returns −1 and sets errno to EAGAIN
132 or if O_NDELAY is set, it returns 0. A write() request for
133 greater than {PIPE_BUF} bytes transfers what it can and
134 returns the number of bytes written or it transfers no data
135 and, if O_NONBLOCK is set, returns −1 with errno set to
136 EAGAIN or if O_NDELAY is set, it returns 0. Finally, if a
137 request is greater than PIPE_BUF bytes and all data previ‐
138 ously written to the pipe has been read, write() transfers
139 at least PIPE_BUF bytes.
140 When attempting to write to a file descriptor (other than a pipe, a
143 FIFO, a socket, or a stream) that supports nonblocking writes and can‐
144 not accept the data immediately:
145 o If O_NONBLOCK and O_NDELAY are clear, write() blocks until
147 the data can be accepted.
148 o If O_NONBLOCK or O_NDELAY is set, write() does not block the
150 process. If some data can be written without blocking the
151 process, write() writes what it can and returns the number
152 of bytes written. Otherwise, if O_NONBLOCK is set, it
153 returns −1 and sets errno to EAGAIN or if O_NDELAY is set,
154 it returns 0.
155 Upon successful completion, where nbyte is greater than 0, write() will
158 mark for update the st_ctime and st_mtime fields of the file, and if
159 the file is a regular file, the S_ISUID and S_ISGID bits of the file
160 mode may be cleared.
161 For streams files (see Intro(2) and streamio(7I)), the operation of
164 write() is determined by the values of the minimum and maximum nbyte
165 range ("packet size") accepted by the stream. These values are con‐
166 tained in the topmost stream module, and can not be set or tested from
167 user level. If nbyte falls within the packet size range, nbyte bytes
168 are written. If nbyte does not fall within the range and the minimum
169 packet size value is zero, write() breaks the buffer into maximum
170 packet size segments prior to sending the data downstream (the last
171 segment may be smaller than the maximum packet size). If nbyte does
172 not fall within the range and the minimum value is non-zero, write()
173 fails and sets errno to ERANGE. Writing a zero-length buffer (nbyte is
174 zero) to a streams device sends a zero length message with zero
175 returned. However, writing a zero-length buffer to a pipe or FIFO sends
176 no message and zero is returned. The user program may issue the
177 I_SWROPT ioctl(2) to enable zero-length messages to be sent across the
178 pipe or FIFO (see streamio(7I)).
179 When writing to a stream, data messages are created with a priority
182 band of zero. When writing to a socket or to a stream that is not a
183 pipe or a FIFO:
184 o If O_NDELAY and O_NONBLOCK are not set, and the stream can‐
186 not accept data (the stream write queue is full due to
187 internal flow control conditions), write() blocks until data
188 can be accepted.
189 o If O_NDELAY or O_NONBLOCK is set and the stream cannot
191 accept data, write() returns -1 and sets errno to EAGAIN.
192 o If O_NDELAY or O_NONBLOCK is set and part of the buffer has
194 already been written when a condition occurs in which the
195 stream cannot accept additional data, write() terminates and
196 returns the number of bytes written.
197 The write() and writev() functions will fail if the stream head had
200 processed an asynchronous error before the call. In this case, the
201 value of errno does not reflect the result of write() or writev() but
202 reflects the prior error.
203 pwrite()
205 The pwrite() function is equivalent to write(), except that it writes
206 into a given position and does not change the file offset (regardless
207 of whether O_APPEND is set). The first three arguments to pwrite() are
208 the same as write(), with the addition of a fourth argument offset for
209 the desired position inside the file.
210 writev()
212 The writev() function performs the same action as write(), but gathers
213 the output data from the iovcnt buffers specified by the members of the
214 iov array: iov[0], iov[1], ..., iov[iovcnt−1]. The iovcnt buffer is
215 valid if greater than 0 and less than or equal to {IOV_MAX}. See
216 Intro(2) for a definition of {IOV_MAX}.
217 The iovec structure contains the following members:
220 caddr_t iov_base;
222 int iov_len;
223 Each iovec entry specifies the base address and length of an area in
227 memory from which data should be written. The writev() function always
228 writes all data from an area before proceeding to the next.
229 If fildes refers to a regular file and all of the iov_len members in
232 the array pointed to by iov are 0, writev() will return 0 and have no
233 other effect. For other file types, the behavior is unspecified.
234 If the sum of the iov_len values is greater than SSIZE_MAX, the opera‐
237 tion fails and no data is transferred.
238
240 Upon successful completion, write() returns the number of bytes actu‐
241 ally written to the file associated with fildes. This number is never
242 greater than nbyte. Otherwise, −1 is returned, the file-pointer remains
243 unchanged, and errno is set to indicate the error.
244 Upon successful completion, writev() returns the number of bytes actu‐
247 ally written. Otherwise, it returns −1, the file-pointer remains
248 unchanged, and errno is set to indicate an error.
249
251 The write(), pwrite(), and writev() functions will fail if:
252 EAGAIN Mandatory file/record locking is set, O_NDELAY or O_NONBLOCK
254 is set, and there is a blocking record lock; an attempt is
255 made to write to a stream that can not accept data with the
256 O_NDELAY or O_NONBLOCK flag set; or a write to a pipe or
257 FIFO of PIPE_BUF bytes or less is requested and less than
258 nbytes of free space is available.
259 EBADF The fildes argument is not a valid file descriptor open for
262 writing.
263 EDEADLK The write was going to go to sleep and cause a deadlock
266 situation to occur.
267 EDQUOT The user's quota of disk blocks on the file system contain‐
270 ing the file has been exhausted.
271 EFBIG An attempt is made to write a file that exceeds the
274 process's file size limit or the maximum file size (see
275 getrlimit(2) and ulimit(2)).
276 EFBIG The file is a regular file, nbyte is greater than 0, and the
279 starting position is greater than or equal to the offset
280 maximum established in the file description associated with
281 fildes.
282 EINTR A signal was caught during the write operation and no data
285 was transferred.
286 EIO The process is in the background and is attempting to write
289 to its controlling terminal whose TOSTOP flag is set, or the
290 process is neither ignoring nor blocking SIGTTOU signals
291 and the process group of the process is orphaned.
292 ENOLCK Enforced record locking was enabled and {LOCK_MAX} regions
295 are already locked in the system, or the system record lock
296 table was full and the write could not go to sleep until
297 the blocking record lock was removed.
298 ENOLINK The fildes argument is on a remote machine and the link to
301 that machine is no longer active.
302 ENOSPC During a write to an ordinary file, there is no free space
305 left on the device.
306 ENOSR An attempt is made to write to a streams with insufficient
309 streams memory resources available in the system.
310 ENXIO A hangup occurred on the stream being written to.
313 EPIPE An attempt is made to write to a pipe or a FIFO that is not
316 open for reading by any process, or that has only one end
317 open (or to a file descriptor created by socket(3SOCKET),
318 using type SOCK_STREAM that is no longer connected to a peer
319 endpoint). A SIGPIPE signal will also be sent to the thread.
320 The process dies unless special provisions were taken to
321 catch or ignore the signal.
322 ERANGE The transfer request size was outside the range supported by
325 the streams file associated with fildes.
326 The write() and pwrite() functions will fail if:
330 EFAULT The buf argument points to an illegal address.
332 EINVAL The nbyte argument overflowed an ssize_t.
335 The pwrite() function fails and the file pointer remains unchanged if:
339 ESPIPE The fildes argument is associated with a pipe or FIFO.
341 The write() and writev() functions may fail if:
345 EINVAL The stream or multiplexer referenced by fildes is linked
347 (directly or indirectly) downstream from a multiplexer.
348 ENXIO A request was made of a non-existent device, or the request
351 was outside the capabilities of the device.
352 ENXIO A hangup occurred on the stream being written to.
355 A write to a streams file may fail if an error message has been
359 received at the stream head. In this case, errno is set to the value
360 included in the error message.
361 The writev() function may fail if:
364 EINVAL The iovcnt argument was less than or equal to 0 or greater
366 than {IOV_MAX}; one of the iov_len values in the iov array
367 was negative; or the sum of the iov_len values in the iov
368 array overflowed an ssize_t.
369
372 The pwrite() function has a transitional interface for 64-bit file off‐
373 sets. See lf64(5).
374
376 See attributes(5) for descriptions of the following attributes:
377 ┌─────────────────────────────┬─────────────────────────────┐
382 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
383 ├─────────────────────────────┼─────────────────────────────┤
384 │Interface Stability │Committed │
385 ├─────────────────────────────┼─────────────────────────────┤
386 │MT-Level │write() is Async-Signal-Safe │
387 ├─────────────────────────────┼─────────────────────────────┤
388 │Standard │See standards(5). │
389 └─────────────────────────────┴─────────────────────────────┘
390
392 Intro(2), chmod(2), creat(2), dup(2), fcntl(2), getrlimit(2), ioctl(2),
393 lseek(2), open(2), pipe(2), ulimit(2), send(3SOCKET), socket(3SOCKET),
394 attributes(5), lf64(5), standards(5), streamio(7I)
395SunOS 5.11 29 Jan 2008 write(2)