pwrite.html

IEEE 1003.1-2003, Single Unix Specification v3

</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>nbyte</i>&gt;{PIPE_BUF}</p>
</td>
<td align="left">
<p class="tent">Blocking <i>nbyte</i></p>
</td>
<td align="left">
<p class="tent">Blocking <i>nbyte</i></p>
</td>
<td align="left">
<p class="tent">Blocking <i>nbyte</i></p>
</td>
</tr>
</table>
</center>

<p>If the O_NONBLOCK flag is clear, a write request shall block if the amount writable immediately is less than that requested. If
the flag is set (by <a href="../functions/fcntl.html"><i>fcntl</i>()</a>), a write request shall never block.</p>

<center>
<table border="1" cellpadding="3" align="center">
<tr valign="top">
<th colspan="4" align="center">
<p class="tent"><b>Write to a Pipe or FIFO with O_NONBLOCK <i>set</i></b></p>
</th>
</tr>

<tr valign="top">
<th align="center">
<p class="tent"><b>Immediately Writable:</b></p>
</th>
<th align="center">
<p class="tent"><b>None</b></p>
</th>
<th align="center">
<p class="tent"><b>Some</b></p>
</th>
<th align="center">
<p class="tent"><i>nbyte</i></p>
</th>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>nbyte</i>&lt;={PIPE_BUF}</p>
</td>
<td align="left">
<p class="tent">-1, [EAGAIN]</p>
</td>
<td align="left">
<p class="tent">-1, [EAGAIN]</p>
</td>
<td align="left">
<p class="tent">Atomic <i>nbyte</i></p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>nbyte</i>&gt;{PIPE_BUF}</p>
</td>
<td align="left">
<p class="tent">-1, [EAGAIN]</p>
</td>
<td align="left">
<p class="tent">&lt;<i>nbyte</i> or -1,</p>
</td>
<td align="left">
<p class="tent">&lt;=<i>nbyte</i> or -1,</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">[EAGAIN]</p>
</td>
<td align="left">
<p class="tent">[EAGAIN]</p>
</td>
</tr>
</table>
</center>

<p>There is no exception regarding partial writes when O_NONBLOCK is set. With the exception of writing to an empty pipe, this
volume of IEEE&nbsp;Std&nbsp;1003.1-2001 does not specify exactly when a partial write is performed since that would require
specifying internal details of the implementation. Every application should be prepared to handle partial writes when O_NONBLOCK is
set and the requested amount is greater than {PIPE_BUF}, just as every application should be prepared to handle partial writes on
other kinds of file descriptors.</p>

<p>The intent of forcing writing at least one byte if any can be written is to assure that each write makes progress if there is
any room in the pipe. If the pipe is empty, {PIPE_BUF} bytes must be written; if not, at least some progress must have been
made.</p>

<p>Where this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 requires -1 to be returned and <i>errno</i> set to [EAGAIN], most historical
implementations return zero (with the O_NDELAY flag set, which is the historical predecessor of O_NONBLOCK, but is not itself in
this volume of IEEE&nbsp;Std&nbsp;1003.1-2001). The error indications in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 were chosen
so that an application can distinguish these cases from end-of-file. While <i>write</i>() cannot receive an indication of
end-of-file, <a href="../functions/read.html"><i>read</i>()</a> can, and the two functions have similar return values. Also, some
existing systems (for example, Eighth Edition) permit a write of zero bytes to mean that the reader should get an end-of-file
indication; for those systems, a return value of zero from <i>write</i>() indicates a successful write of an end-of-file
indication.</p>

<p>Implementations are allowed, but not required, to perform error checking for <i>write</i>() requests of zero bytes.</p>

<p>The concept of a {PIPE_MAX} limit (indicating the maximum number of bytes that can be written to a pipe in a single operation)
was considered, but rejected, because this concept would unnecessarily limit application writing.</p>

<p>See also the discussion of O_NONBLOCK in <a href="read.html"><i>read</i>()</a> .</p>

<p>Writes can be serialized with respect to other reads and writes. If a <a href="../functions/read.html"><i>read</i>()</a> of file
data can be proven (by any means) to occur after a <i>write</i>() of the data, it must reflect that <i>write</i>(), even if the
calls are made by different processes. A similar requirement applies to multiple write operations to the same file position. This
is needed to guarantee the propagation of data from <i>write</i>() calls to subsequent <a href=
"../functions/read.html"><i>read</i>()</a> calls. This requirement is particularly significant for networked file systems, where
some caching schemes violate these semantics.</p>

<p>Note that this is specified in terms of <a href="../functions/read.html"><i>read</i>()</a> and <i>write</i>(). The XSI
extensions <a href="../functions/readv.html"><i>readv</i>()</a> and <a href="../functions/writev.html"><i>writev</i>()</a> also
obey these semantics. A new &quot;high-performance&quot; write analog that did not follow these serialization requirements would also be
permitted by this wording. This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 is also silent about any effects of application-level
caching (such as that done by <i>stdio</i>).</p>

<p>This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 does not specify the value of the file offset after an error is returned; there
are too many cases. For programming errors, such as [EBADF], the concept is meaningless since no file is involved. For errors that
are detected immediately, such as [EAGAIN], clearly the pointer should not change. After an interrupt or hardware error, however,
an updated value would be very useful and is the behavior of many implementations.</p>

<p>This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 does not specify behavior of concurrent writes to a file from multiple processes.
Applications should use some form of concurrency control.</p>
</blockquote>

<h4><a name="tag_03_866_09"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_866_10"></a>SEE ALSO</h4>

<blockquote>
<p><a href="chmod.html"><i>chmod</i>()</a> , <a href="creat.html"><i>creat</i>()</a> , <a href="dup.html"><i>dup</i>()</a> , <a
href="fcntl.html"><i>fcntl</i>()</a> , <a href="getrlimit.html"><i>getrlimit</i>()</a> , <a href="lseek.html"><i>lseek</i>()</a> ,
<a href="open.html"><i>open</i>()</a> , <a href="pipe.html"><i>pipe</i>()</a> , <a href="ulimit.html"><i>ulimit</i>()</a> , <a
href="writev.html"><i>writev</i>()</a> , the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../basedefs/limits.h.html"><i>&lt;limits.h&gt;</i></a>, <a href="../basedefs/stropts.h.html"><i>&lt;stropts.h&gt;</i></a>, <a
href="../basedefs/sys/uio.h.html"><i>&lt;sys/uio.h&gt;</i></a>, <a href="../basedefs/unistd.h.html"><i>&lt;unistd.h&gt;</i></a></p>
</blockquote>

<h4><a name="tag_03_866_11"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 1. Derived from Issue 1 of the SVID.</p>
</blockquote>

<h4><a name="tag_03_866_12"></a>Issue 5</h4>

<blockquote>
<p>The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX Threads Extension.</p>

<p>Large File Summit extensions are added.</p>

<p>The <i>pwrite</i>() function is added.</p>
</blockquote>

<h4><a name="tag_03_866_13"></a>Issue 6</h4>

<blockquote>
<p>The DESCRIPTION states that the <i>write</i>() function does not block the thread. Previously this said &quot;process&quot; rather than
&quot;thread&quot;.</p>

<p>The DESCRIPTION and ERRORS sections are updated so that references to STREAMS are marked as part of the XSI STREAMS Option
Group.</p>

<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>

<ul>
<li>
<p>The DESCRIPTION now states that if <i>write</i>() is interrupted by a signal after it has successfully written some data, it
returns the number of bytes written. In the POSIX.1-1988 standard, it was optional whether <i>write</i>() returned the number of
bytes written, or whether it returned -1 with <i>errno</i> set to [EINTR]. This is a FIPS requirement.</p>
</li>

<li>
<p>The following changes are made to support large files:</p>

<ul>
<li>
<p>For regular files, no data transfer occurs past the offset maximum established in the open file description associated with the
<i>fildes</i>.</p>
</li>

<li>
<p>A second [EFBIG] error condition is added.</p>
</li>
</ul>
</li>

<li>
<p>The [EIO] error condition is added.</p>
</li>

<li>
<p>The [EPIPE] error condition is added for when a pipe has only one end open.</p>
</li>

<li>
<p>The [ENXIO] optional error condition is added.</p>
</li>
</ul>

<p>Text referring to sockets is added to the DESCRIPTION.</p>

<p>The following changes were made to align with the IEEE&nbsp;P1003.1a draft standard:</p>

<ul>
<li>
<p>The effect of reading zero bytes is clarified.</p>
</li>
</ul>

<p>The DESCRIPTION is updated for alignment with IEEE&nbsp;Std&nbsp;1003.1j-2000 by specifying that <i>write</i>() results are
unspecified for typed memory objects.</p>

<p>The following error conditions are added for operations on sockets: [EAGAIN], [EWOULDBLOCK], [ECONNRESET], [ENOTCONN], and
[EPIPE].</p>

<p>The [EIO] error is changed to &quot;may fail&quot;.</p>

<p>The [ENOBUFS] error is added for sockets.</p>

<p>The following error conditions are added for operations on sockets: [EACCES], [ENETDOWN], and [ENETUNREACH].</p>

<p>The <a href="../functions/writev.html"><i>writev</i>()</a> function is split out into a separate reference page.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>