8322 nl: misleading-indentation
[unleashed/tickless.git] / usr / src / man / man2 / write.2
blob64787b4b2a6d75b0e7da180a4d749b613f339ddb
1 '\" te
2 .\" Copyright (c) 2087, Sun Microsystems, Inc.  All Rights Reserved.
3 .\" Copyright 1989 AT&T
4 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
5 .\" Copyright (c) 2015, Joyent, Inc.  All rights reserved.
6 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
7 .\" http://www.opengroup.org/bookstore/.
8 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
9 .\"  This notice shall appear on any product containing this material.
10 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
11 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
12 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
13 .TH WRITE 2 "Jan 15, 2015"
14 .SH NAME
15 write, pwrite, writev, pwritev\- write on a file
16 .SH SYNOPSIS
17 .LP
18 .nf
19 #include <unistd.h>
21 \fBssize_t\fR \fBwrite\fR(\fBint\fR \fIfildes\fR, \fBconst void *\fR\fIbuf\fR, \fBsize_t\fR \fInbyte\fR);
22 .fi
24 .LP
25 .nf
26 \fBssize_t\fR \fBpwrite\fR(\fBint\fR \fIfildes\fR, \fBconst void *\fR\fIbuf\fR, \fBsize_t\fR \fInbyte\fR,
27      \fBoff_t\fR \fIoffset\fR);
28 .fi
30 .LP
31 .nf
32 #include <sys/uio.h>
34 \fBssize_t\fR \fBwritev\fR(\fBint\fR \fIfildes\fR, \fBconst struct iovec *\fR\fIiov\fR, \fBint\fR \fIiovcnt\fR);
35 .fi
36 .LP
37 .nf
38 \fBssize_t\fR \fBpwritev\fR(\fBint\fR \fIfildes\fR, \fBconst struct iovec *\fR\fIiov\fR, \fBint\fR \fIiovcnt\fR, \fBoff_t\fR \fIoffset\fR);
39 .fi
41 .SH DESCRIPTION
42 .LP
43 The \fBwrite()\fR function attempts to write \fInbyte\fR bytes from the buffer
44 pointed to by \fIbuf\fR to the file associated with the open file descriptor,
45 \fIfildes\fR.
46 .sp
47 .LP
48 If \fInbyte\fR is 0, \fBwrite()\fR will return 0 and have no other results if
49 the file is a regular file; otherwise, the results are unspecified.
50 .sp
51 .LP
52 On a regular file or other file capable of seeking, the actual writing of data
53 proceeds from the position in the file indicated by the file offset associated
54 with \fIfildes\fR. Before successful return from \fBwrite()\fR, the file offset
55 is incremented by the number of bytes actually written. On a regular file, if
56 this incremented file offset is greater than the length of the file, the length
57 of the file will be set to this file offset.
58 .sp
59 .LP
60 If the \fBO_SYNC\fR bit has been set, write I/O operations on the file
61 descriptor complete as defined by synchronized I/O file integrity completion.
62 .sp
63 .LP
64 If \fIfildes\fR refers to a socket, \fBwrite()\fR is equivalent to
65 \fBsend\fR(3SOCKET) with no flags set.
66 .sp
67 .LP
68 On a file not capable of seeking, writing always takes place starting at the
69 current position.  The value of a file offset associated with such a device is
70 undefined.
71 .sp
72 .LP
73 If the \fBO_APPEND\fR flag of the file status flags is set, the file offset
74 will be set to the end of the file prior to each write and no intervening file
75 modification operation will occur between changing the file offset and the
76 write operation.
77 .sp
78 .LP
79 For regular files, no data transfer will occur past the offset maximum
80 established in the open file description with \fIfildes\fR.
81 .sp
82 .LP
83 A \fBwrite()\fR to a regular file is blocked if mandatory file/record locking
84 is set (see \fBchmod\fR(2)), and there is a record lock owned by another
85 process  on the segment of the file to be written:
86 .RS +4
87 .TP
88 .ie t \(bu
89 .el o
90 If \fBO_NDELAY\fR or \fBO_NONBLOCK\fR is set, \fBwrite()\fR returns \fB\(mi1\fR
91 and sets \fBerrno\fR to \fBEAGAIN\fR.
92 .RE
93 .RS +4
94 .TP
95 .ie t \(bu
96 .el o
97 If \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are clear, \fBwrite()\fR sleeps until
98 all blocking locks are removed or the \fBwrite()\fR is terminated by a signal.
99 .RE
102 If a  \fBwrite()\fR requests that more bytes be written than there is room
103 for\(emfor example, if the write would exceed the process file size limit (see
104 \fBgetrlimit\fR(2) and \fBulimit\fR(2)), the system file size limit, or the
105 free space on the device\(emonly as many bytes as there is room for will be
106 written. For example, suppose there is space for 20 bytes more in a file before
107 reaching a limit. A \fBwrite()\fR of 512-bytes returns 20. The next
108 \fBwrite()\fR of a non-zero number of bytes gives a failure return (except as
109 noted for pipes and FIFO below).
112 If \fBwrite()\fR is interrupted by a signal before it writes any data, it will
113 return \(mi1 with \fBerrno\fR set to \fBEINTR\fR.
116 If \fBwrite()\fR is interrupted by a signal after it successfully writes some
117 data, it will return the number of bytes written.
120 If \fBwrite()\fR exceeds the process file size limit, the application generates
121 a \fBSIGXFSZ\fR signal, whose default behavior is to dump core.
124 After a \fBwrite()\fR to a regular file has successfully returned:
125 .RS +4
127 .ie t \(bu
128 .el o
129 Any successful \fBread\fR(2) from each byte position in the file that was
130 modified by that write will return the data specified by the \fBwrite()\fR for
131 that position until such byte positions are again modified.
133 .RS +4
135 .ie t \(bu
136 .el o
137 Any subsequent successful \fBwrite()\fR to the same byte position in the file
138 will overwrite that file data.
142 Write requests to a pipe or FIFO are handled the same as a regular file with
143 the following exceptions:
144 .RS +4
146 .ie t \(bu
147 .el o
148 There is no file offset associated with a pipe, hence each write request
149 appends to the end of the pipe.
151 .RS +4
153 .ie t \(bu
154 .el o
155 Write requests of \fB{PIPE_BUF}\fR bytes or less are guaranteed not to be
156 interleaved with data from other processes doing writes on the same pipe.
157 Writes of greater than \fB{PIPE_BUF}\fR bytes may have data interleaved, on
158 arbitrary boundaries, with writes by other processes, whether or not the
159 \fBO_NONBLOCK\fR or \fBO_NDELAY\fR flags are set.
161 .RS +4
163 .ie t \(bu
164 .el o
165 If \fBO_NONBLOCK\fR and \fBO_NDELAY\fR are clear, a write request may cause the
166 process to block, but on normal completion it returns \fInbyte\fR.
168 .RS +4
170 .ie t \(bu
171 .el o
172 If \fBO_NONBLOCK\fR and \fBO_NDELAY\fR are set, \fBwrite()\fR does not block
173 the process. If a \fBwrite()\fR request for \fBPIPE_BUF\fR or fewer bytes
174 succeeds completely  \fBwrite()\fR returns \fInbyte\fR. Otherwise, if
175 \fBO_NONBLOCK\fR is set, it returns \fB\(mi1\fR and sets \fBerrno\fR to
176 \fBEAGAIN\fR or if \fBO_NDELAY\fR is set, it returns \fB0\fR.  A \fBwrite()\fR
177 request for greater than \fB{PIPE_BUF}\fR bytes  transfers what it can and
178 returns the number of bytes written or it transfers no data and, if
179 \fBO_NONBLOCK\fR is set, returns \fB\(mi1\fR with \fBerrno\fR set to
180 \fBEAGAIN\fR or if \fBO_NDELAY\fR is set, it returns \fB0\fR.  Finally, if a
181 request is greater than \fBPIPE_BUF\fR bytes and all data previously written to
182 the pipe has been read, \fBwrite()\fR transfers at least \fBPIPE_BUF\fR bytes.
186 When attempting to write to a file descriptor (other than a pipe, a FIFO, a
187 socket, or a stream) that supports nonblocking writes and cannot accept the
188 data immediately:
189 .RS +4
191 .ie t \(bu
192 .el o
193 If \fBO_NONBLOCK\fR and \fBO_NDELAY\fR are clear, \fBwrite()\fR blocks until
194 the data can be accepted.
196 .RS +4
198 .ie t \(bu
199 .el o
200 If \fBO_NONBLOCK\fR or \fBO_NDELAY\fR is set, \fBwrite()\fR does not block the
201 process. If some data can be written without blocking the process,
202 \fBwrite()\fR writes what it can and returns the number of bytes written.
203 Otherwise, if \fBO_NONBLOCK\fR is set, it returns \fB\(mi1\fR  and sets
204 \fBerrno\fR to \fBEAGAIN\fR or if \fBO_NDELAY\fR is set,  it returns \fB0\fR.
208 Upon successful completion, where \fInbyte\fR is greater than 0, \fBwrite()\fR
209 will mark for update the \fBst_ctime\fR and \fBst_mtime\fR fields of the file,
210 and if the file is a regular file, the \fBS_ISUID\fR and \fBS_ISGID\fR bits of
211 the file mode may be cleared.
214 For streams files (see \fBIntro\fR(2) and \fBstreamio\fR(7I)), the operation of
215 \fBwrite()\fR is determined by the values of the minimum and maximum
216 \fInbyte\fR range ("packet size") accepted by the stream. These values are
217 contained in the topmost stream module, and can not be set or tested from user
218 level. If \fInbyte\fR falls within the packet size range, \fInbyte\fR bytes are
219 written. If \fInbyte\fR does not fall within the range and the minimum packet
220 size value  is zero, \fBwrite()\fR breaks the buffer into maximum packet size
221 segments prior  to sending the data downstream (the last segment may be smaller
222 than the maximum  packet size). If \fInbyte\fR does not fall within the range
223 and the minimum value is non-zero, \fBwrite()\fR fails and sets \fBerrno\fR to
224 \fBERANGE\fR. Writing a zero-length buffer (\fInbyte\fR is zero) to a streams
225 device sends  a zero length message with zero returned. However, writing a
226 zero-length buffer to a pipe or FIFO sends no message  and zero is returned.
227 The user program may issue the \fBI_SWROPT\fR \fBioctl\fR(2) to enable
228 zero-length messages to be sent across the pipe or FIFO (see
229 \fBstreamio\fR(7I)).
232 When writing to a stream, data messages are created with a priority band of
233 zero. When writing to a socket or to a stream that is not a pipe or a FIFO:
234 .RS +4
236 .ie t \(bu
237 .el o
238 If \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are not set, and the stream cannot
239 accept data (the stream write queue is full due to internal flow control
240 conditions), \fBwrite()\fR blocks until data can be accepted.
242 .RS +4
244 .ie t \(bu
245 .el o
246 If \fBO_NDELAY\fR or \fBO_NONBLOCK\fR is set and the stream cannot accept data,
247 \fBwrite()\fR returns \fB-1\fR and sets \fBerrno\fR to \fBEAGAIN\fR.
249 .RS +4
251 .ie t \(bu
252 .el o
253 If \fBO_NDELAY\fR or \fBO_NONBLOCK\fR is set and part of the buffer has already
254 been written when a condition occurs in which the stream cannot accept
255 additional data, \fBwrite()\fR terminates and returns the number of bytes
256 written.
260 The \fBwrite()\fR and \fBwritev()\fR functions will fail if the stream head had
261 processed an asynchronous error before the call.  In this case, the value of
262 \fBerrno\fR does not reflect the result of \fBwrite()\fR or \fBwritev()\fR but
263 reflects the prior error.
264 .SS "\fBpwrite()\fR"
266 The \fBpwrite()\fR function is equivalent to \fBwrite()\fR, except that it
267 writes into a given position and does not change the file offset (regardless of
268 whether \fBO_APPEND\fR is set). The first three arguments to \fBpwrite()\fR are
269 the same as \fBwrite()\fR, with the addition of a fourth argument \fIoffset\fR
270 for the desired position inside the file.
271 .SS "\fBwritev()\fR"
273 The \fBwritev()\fR function performs the same action as \fBwrite()\fR, but
274 gathers the output data from the \fIiovcnt\fR buffers specified by the members
275 of the \fIiov\fR array: \fIiov\fR[0], \fIiov\fR[1], \&.\|.\|.,
276 \fIiov\fR[\fIiovcnt\fR\|\(mi\|1]. The \fIiovcnt\fR buffer is valid if greater
277 than 0 and less than or equal to \fB{IOV_MAX}\fR. See \fBIntro\fR(2) for a
278 definition of \fB{IOV_MAX}\fR.
280 .SS "\fBpwritev()\fR"
282 The \fBpwritev()\fR function is equivalent to \fBwritev()\fR, except that it
283 writes into a given position and does not change the file offset (regardless of
284 whether \fBO_APPEND\fR is set). The first three arguments to \fBpwritev()\fR are
285 the same as \fBwritev()\fR, with the addition of a fourth argument \fIoffset\fR
286 for the desired position inside the file.
288 The \fBiovec\fR structure contains the following members:
290 .in +2
292 caddr_t  iov_base;
293 int      iov_len;
295 .in -2
299 Each \fBiovec\fR entry specifies the base address and length of an area in
300 memory from which data should be written.  The \fBwritev()\fR function always
301 writes all data from an area before proceeding to the next.
304 If \fIfildes\fR refers to a regular file and all of the \fBiov_len\fR members
305 in the array pointed to by \fIiov\fR are 0, \fBwritev()\fR will return 0 and
306 have no other effect.  For other file types, the behavior is unspecified.
309 If the sum of the \fBiov_len\fR values is greater than \fBSSIZE_MAX\fR, the
310 operation fails and no data is transferred.
311 .SH RETURN VALUES
313 Upon successful completion, \fBwrite()\fR returns the number of bytes actually
314 written to the file associated with \fIfildes\fR. This number is never greater
315 than \fInbyte\fR. Otherwise, \fB\(mi1\fR is returned, the file-pointer remains
316 unchanged, and \fBerrno\fR is set to indicate the error.
319 Upon successful completion, \fBwritev()\fR returns the number of bytes actually
320 written.  Otherwise, it returns  \fB\(mi1\fR, the file-pointer remains
321 unchanged, and \fBerrno\fR is set to indicate an error.
322 .SH ERRORS
324 The \fBwrite()\fR, \fBpwrite()\fR, \fBwritev()\fR, and \fBpwritev()\fR
325 functions will fail if:
327 .ne 2
329 \fB\fBEAGAIN\fR\fR
331 .RS 11n
332 Mandatory file/record locking is set, \fBO_NDELAY\fR or \fBO_NONBLOCK\fR is
333 set, and there is a blocking record lock; an attempt is made to write to a
334 stream that can not accept data with the \fBO_NDELAY\fR or \fBO_NONBLOCK\fR
335 flag set; or a write to a pipe or FIFO of \fBPIPE_BUF\fR bytes or less is
336 requested and less than \fInbytes\fR of free space is available.
340 .ne 2
342 \fB\fBEBADF\fR\fR
344 .RS 11n
345 The \fIfildes\fR argument is not a valid file descriptor open for writing.
349 .ne 2
351 \fB\fBECONNRESET\fR\fR
353 .RS 11n
354 The \fIfiledes\fR argument refers to a connection oriented socket and the
355 connection was forcibly closed by the peer and is no longer valid.  I/O can no
356 longer be performed to \fIfiledes\fR.
360 .ne 2
362 \fB\fBEDEADLK\fR\fR
364 .RS 11n
365 The write was going to go to sleep  and cause a deadlock situation to occur.
369 .ne 2
371 \fB\fBEDQUOT\fR\fR
373 .RS 11n
374 The user's quota of disk blocks on the file system containing the file has been
375 exhausted.
379 .ne 2
381 \fB\fBEFBIG\fR\fR
383 .RS 11n
384 An attempt is made to write a file that exceeds the process's file size limit
385 or the maximum file size (see \fBgetrlimit\fR(2) and \fBulimit\fR(2)).
389 .ne 2
391 \fB\fBEFBIG\fR\fR
393 .RS 11n
394 The file is a regular file, \fInbyte\fR is greater than 0, and the starting
395 position is greater than or equal to the offset maximum established in the file
396 description associated with \fIfildes\fR.
400 .ne 2
402 \fB\fBEINTR\fR\fR
404 .RS 11n
405 A signal was caught during the write  operation and no data was transferred.
409 .ne 2
411 \fB\fBEIO\fR\fR
413 .RS 11n
414 The process is in the background and is attempting to write to its controlling
415 terminal whose \fBTOSTOP\fR flag is set, or the process is  neither ignoring
416 nor blocking \fBSIGTTOU\fR signals and the process  group of the process is
417 orphaned.
421 .ne 2
423 \fB\fBENOLCK\fR\fR
425 .RS 11n
426 Enforced record locking was enabled and \fB{LOCK_MAX}\fR regions  are already
427 locked in the system, or the system record lock table was full and the write
428 could not go to sleep  until the blocking record lock was removed.
432 .ne 2
434 \fB\fBENOLINK\fR\fR
436 .RS 11n
437 The \fIfildes\fR argument is on a remote machine and the link to that machine
438 is no longer active.
442 .ne 2
444 \fB\fBENOSPC\fR\fR
446 .RS 11n
447 During a write to an ordinary file, there is no  free space left on the device.
451 .ne 2
453 \fB\fBENOSR\fR\fR
455 .RS 11n
456 An attempt is made to write to a streams with insufficient streams memory
457 resources  available in the system.
461 .ne 2
463 \fB\fBENXIO\fR\fR
465 .RS 11n
466 A hangup occurred on the stream being written to.
470 .ne 2
472 \fB\fBEPIPE\fR\fR
474 .RS 11n
475 An attempt is made to write to a pipe or a \fBFIFO\fR that is not open for
476 reading by any process, or that has only one end open (or to a file descriptor
477 created by \fBsocket\fR(3SOCKET), using type \fBSOCK_STREAM\fR that is no
478 longer connected to a peer endpoint). A \fBSIGPIPE\fR signal will also be sent
479 to the thread. The process dies unless special provisions were taken to catch
480 or ignore the signal.
484 .ne 2
486 \fB\fBERANGE\fR\fR
488 .RS 11n
489 The transfer request size was outside the range supported by the streams file
490 associated with \fIfildes\fR.
495 The \fBwrite()\fR and \fBpwrite()\fR functions will fail if:
497 .ne 2
499 \fB\fBEFAULT\fR\fR
501 .RS 10n
502 The \fIbuf\fR argument points to an illegal address.
506 .ne 2
508 \fB\fBEINVAL\fR\fR
510 .RS 10n
511 The \fInbyte\fR argument overflowed an \fBssize_t\fR.
516 The \fBpwrite()\fR and \fBpwritev()\fR functions fail and the file pointer
517 remains unchanged if:
519 .ne 2
521 \fB\fBESPIPE\fR\fR
523 .RS 10n
524 The \fIfildes\fR argument is associated with a pipe or FIFO.
529 The \fBwrite()\fR and \fBwritev()\fR functions may fail if:
531 .ne 2
533 \fB\fBEINVAL\fR\fR
535 .RS 10n
536 The stream or multiplexer referenced by \fIfildes\fR is linked (directly or
537 indirectly) downstream from a multiplexer.
541 .ne 2
543 \fB\fBENXIO\fR\fR
545 .RS 10n
546 A request was made of a non-existent device, or the request was outside the
547 capabilities of the device.
551 .ne 2
553 \fB\fBENXIO\fR\fR
555 .RS 10n
556 A hangup occurred on the stream being written to.
561 A write to a streams file may fail if an error message has been received at the
562 stream head.  In this case, \fBerrno\fR is set to the value included in the
563 error message.
566 The \fBwritev()\fR and \fBpwritev()\fR functions may fail if:
568 .ne 2
570 \fB\fBEINVAL\fR\fR
572 .RS 10n
573 The \fIiovcnt\fR argument was less than or equal to 0 or greater than
574 {\fBIOV_MAX\fR}; one of the \fBiov_len\fR values in the \fIiov\fR array was
575 negative; or the sum of the \fBiov_len\fR values in the \fIiov\fR array
576 overflowed an \fBssize_t\fR.
579 .SH USAGE
581 The \fBpwrite()\fR function has a transitional interface for 64-bit file
582 offsets.  See \fBlf64\fR(5).
583 .SH ATTRIBUTES
585 See \fBattributes\fR(5) for descriptions of the following attributes:
590 box;
591 c | c
592 l | l .
593 ATTRIBUTE TYPE  ATTRIBUTE VALUE
595 Interface Stability     Committed
597 MT-Level        \fBwrite()\fR is Async-Signal-Safe
599 Standard        See \fBstandards\fR(5).
602 .SH SEE ALSO
604 \fBIntro\fR(2), \fBchmod\fR(2), \fBcreat\fR(2), \fBdup\fR(2), \fBfcntl\fR(2),
605 \fBgetrlimit\fR(2), \fBioctl\fR(2), \fBlseek\fR(2), \fBopen\fR(2),
606 \fBpipe\fR(2), \fBulimit\fR(2), \fBsend\fR(3SOCKET), \fBsocket\fR(3SOCKET),
607 \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5), \fBstreamio\fR(7I)