pwrite.html

IEEE 1003.1-2003, Single Unix Specification v3

<dd>The write operation was terminated due to the receipt of a signal, and no data was transferred.</dd>

<dt>[EIO]</dt>

<dd>The process is a member of a background process group attempting to write to its controlling terminal, TOSTOP is set, the
process is neither ignoring nor blocking SIGTTOU, and the process group of the process is orphaned. This error may also be returned
under implementation-defined conditions.</dd>

<dt>[ENOSPC]</dt>

<dd>There was no free space remaining on the device containing the file.</dd>

<dt>[EPIPE]</dt>

<dd>An attempt is made to write to a pipe or FIFO that is not open for reading by any process, or that only has one end open. A
SIGPIPE signal shall also be sent to the thread.</dd>

<dt>[ERANGE]</dt>

<dd><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
The transfer request size was outside the range supported by the STREAMS file associated with <i>fildes</i>. <img src=
"../images/opt-end.gif" alt="[Option End]" border="0"></dd>
</dl>

<p>The <i>write</i>() function shall fail if:</p>

<dl compact>
<dt>[EAGAIN] or [EWOULDBLOCK]</dt>

<dd><br>
The file descriptor is for a socket, is marked O_NONBLOCK, and write would block.</dd>

<dt>[ECONNRESET]</dt>

<dd>A write was attempted on a socket that is not connected.</dd>

<dt>[EPIPE]</dt>

<dd>A write was attempted on a socket that is shut down for writing, or is no longer connected. In the latter case, if the socket
is of type SOCK_STREAM, the SIGPIPE signal is generated to the calling process.</dd>
</dl>

<p>The <i>write</i>() and <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
"[Option Start]" border="0"> <i>pwrite</i>() <img src="../images/opt-end.gif" alt="[Option End]" border="0"> functions may fail
if:</p>

<dl compact>
<dt>[EINVAL]</dt>

<dd><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
The STREAM or multiplexer referenced by <i>fildes</i> is linked (directly or indirectly) downstream from a multiplexer. <img src=
"../images/opt-end.gif" alt="[Option End]" border="0"></dd>

<dt>[EIO]</dt>

<dd>A physical I/O error has occurred.</dd>

<dt>[ENOBUFS]</dt>

<dd>Insufficient resources were available in the system to perform the operation.</dd>

<dt>[ENXIO]</dt>

<dd>A request was made of a nonexistent device, or the request was outside the capabilities of the device.</dd>

<dt>[ENXIO]</dt>

<dd><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
A hangup occurred on the STREAM being written to. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
</dl>

<p><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> A
write to a STREAMS file may fail if an error message has been received at the STREAM head. In this case, <i>errno</i> is set to the
value included in the error message. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>

<p>The <i>write</i>() function may fail if:</p>

<dl compact>
<dt>[EACCES]</dt>

<dd>A write was attempted on a socket and the calling process does not have appropriate privileges.</dd>

<dt>[ENETDOWN]</dt>

<dd>A write was attempted on a socket and the local network interface used to reach the destination is down.</dd>

<dt>[ENETUNREACH]</dt>

<dd><br>
A write was attempted on a socket and no route to the network is present.</dd>
</dl>

<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
The <i>pwrite</i>() function shall fail and the file pointer remain unchanged if: <img src="../images/opt-end.gif" alt=
"[Option End]" border="0"></p>

<dl compact>
<dt>[EINVAL]</dt>

<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
The <i>offset</i> argument is invalid. The value is negative. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>

<dt>[ESPIPE]</dt>

<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
<i>fildes</i> is associated with a pipe or FIFO. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
</dl>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_03_866_06"></a>EXAMPLES</h4>

<blockquote>
<h5><a name="tag_03_866_06_01"></a>Writing from a Buffer</h5>

<p>The following example writes data from the buffer pointed to by <i>buf</i> to the file associated with the file descriptor
<i>fd</i>.</p>

<pre>
<tt>#include &lt;sys/types.h&gt;
#include &lt;string.h&gt;
...
char buf[20];
size_t nbytes;
ssize_t bytes_written;
int fd;
...
strcpy(buf, "This is a test\n");
nbytes = strlen(buf);
<br>
bytes_written = write(fd, buf, nbytes);
...
</tt>
</pre>
</blockquote>

<h4><a name="tag_03_866_07"></a>APPLICATION USAGE</h4>

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

<h4><a name="tag_03_866_08"></a>RATIONALE</h4>

<blockquote>
<p>See also the RATIONALE section in <a href="read.html"><i>read</i>()</a> .</p>

<p>An attempt to write to a pipe or FIFO has several major characteristics:</p>

<ul>
<li>
<p><i>Atomic/non-atomic</i>: A write is atomic if the whole amount written in one operation is not interleaved with data from any
other process. This is useful when there are multiple writers sending data to a single reader. Applications need to know how large
a write request can be expected to be performed atomically. This maximum is called {PIPE_BUF}. This volume of
IEEE&nbsp;Std&nbsp;1003.1-2001 does not say whether write requests for more than {PIPE_BUF} bytes are atomic, but requires that
writes of {PIPE_BUF} or fewer bytes shall be atomic.</p>
</li>

<li>
<p><i>Blocking/immediate</i>: Blocking is only possible with O_NONBLOCK clear. If there is enough space for all the data requested
to be written immediately, the implementation should do so. Otherwise, the process may block; that is, pause until enough space is
available for writing. The effective size of a pipe or FIFO (the maximum amount that can be written in one operation without
blocking) may vary dynamically, depending on the implementation, so it is not possible to specify a fixed value for it.</p>
</li>

<li>
<p><i>Complete/partial/deferred</i>: A write request:</p>

<pre>
<tt>int fildes;
size_t nbyte;
ssize_t ret;
char *buf;
<br>
ret = write(fildes, buf, nbyte);
</tt>
</pre>

<p>may return:</p>

<dl compact>
<dt>Complete</dt>

<dd><i>ret</i>=<i>nbyte</i></dd>

<dt>Partial</dt>

<dd><i>ret</i>&lt;<i>nbyte</i> 

<p>This shall never happen if <i>nbyte</i>&lt;= {PIPE_BUF}. If it does happen (with <i>nbyte</i>&gt; {PIPE_BUF}), this volume of
IEEE&nbsp;Std&nbsp;1003.1-2001 does not guarantee atomicity, even if <i>ret</i>&lt;= {PIPE_BUF}, because atomicity is guaranteed
according to the amount <i>requested</i>, not the amount <i>written</i>.</p>
</dd>

<dt>Deferred:</dt>

<dd><i>ret</i>=-1, <i>errno</i>=[EAGAIN] 

<p>This error indicates that a later request may succeed. It does not indicate that it <i>shall</i> succeed, even if
<i>nbyte</i>&lt;= {PIPE_BUF}, because if no process reads from the pipe or FIFO, the write never succeeds. An application could
usefully count the number of times [EAGAIN] is caused by a particular value of <i>nbyte</i>&gt; {PIPE_BUF} and perhaps do later
writes with a smaller value, on the assumption that the effective size of the pipe may have decreased.</p>
</dd>
</dl>

<p>Partial and deferred writes are only possible with O_NONBLOCK set.</p>
</li>
</ul>

<p>The relations of these properties are shown in the following tables:</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>clear</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">Atomic blocking</p>
</td>
<td align="left">
<p class="tent">Atomic blocking</p>
</td>
<td align="left">
<p class="tent">Atomic immediate</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent"><i>nbyte</i></p>
</td>
<td align="left">
<p class="tent"><i>nbyte</i></p>
</td>
<td align="left">
<p class="tent"><i>nbyte</i></p>