789 lines
32 KiB
HTML
789 lines
32 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>write</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="write"></a> <a name="tag_03_866"></a><!-- write -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_866_01"></a>NAME</h4>
|
|
|
|
<blockquote>pwrite, write - write on a file</blockquote>
|
|
|
|
<h4><a name="tag_03_866_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>#include <<a href="../basedefs/unistd.h.html">unistd.h</a>><br>
|
|
<br>
|
|
</tt></code></p>
|
|
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> ssize_t pwrite(int</tt> <i>fildes</i><tt>, const void *</tt><i>buf</i><tt>, size_t</tt>
|
|
<i>nbyte</i><tt>,<br>
|
|
off_t offset); <img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
ssize_t write(int</tt> <i>fildes</i><tt>, const void *</tt><i>buf</i><tt>, size_t</tt> <i>nbyte</i><tt>);<br>
|
|
</tt></blockquote>
|
|
|
|
<h4><a name="tag_03_866_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>write</i>() function shall attempt to write <i>nbyte</i> bytes from the buffer pointed to by <i>buf</i> to the file
|
|
associated with the open file descriptor, <i>fildes</i>.</p>
|
|
|
|
<p>Before any action described below is taken, and if <i>nbyte</i> is zero and the file is a regular file, the <i>write</i>()
|
|
function may detect and return errors as described below. In the absence of errors, or if error detection is not performed, the
|
|
<i>write</i>() function shall return zero and have no other results. If <i>nbyte</i> is zero and the file is not a regular file,
|
|
the results are unspecified.</p>
|
|
|
|
<p>On a regular file or other file capable of seeking, the actual writing of data shall proceed from the position in the file
|
|
indicated by the file offset associated with <i>fildes</i>. Before successful return from <i>write</i>(), the file offset shall be
|
|
incremented by the number of bytes actually written. On a regular file, if this incremented file offset is greater than the length
|
|
of the file, the length of the file shall be set to this file offset.</p>
|
|
|
|
<p>On a file not capable of seeking, writing shall always take place starting at the current position. The value of a file offset
|
|
associated with such a device is undefined.</p>
|
|
|
|
<p>If the O_APPEND flag of the file status flags is set, the file offset shall be set to the end of the file prior to each write
|
|
and no intervening file modification operation shall occur between changing the file offset and the write operation.</p>
|
|
|
|
<p>If a <i>write</i>() requests that more bytes be written than there is room for (for example, <sup>[<a href=
|
|
"javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> the process'
|
|
file size limit or <img src="../images/opt-end.gif" alt="[Option End]" border="0"> the physical end of a medium), only as many
|
|
bytes as there is room for shall be written. For example, suppose there is space for 20 bytes more in a file before reaching a
|
|
limit. A write of 512 bytes will return 20. The next write of a non-zero number of bytes would give a failure return (except as
|
|
noted below).</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If the request would cause the file size to exceed the soft file size limit for the process and there is no room for any bytes to
|
|
be written, the request shall fail and the implementation shall generate the SIGXFSZ signal for the thread. <img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p>If <i>write</i>() is interrupted by a signal before it writes any data, it shall return -1 with <i>errno</i> set to [EINTR].</p>
|
|
|
|
<p>If <i>write</i>() is interrupted by a signal after it successfully writes some data, it shall return the number of bytes
|
|
written.</p>
|
|
|
|
<p>If the value of <i>nbyte</i> is greater than {SSIZE_MAX}, the result is implementation-defined.</p>
|
|
|
|
<p>After a <i>write</i>() to a regular file has successfully returned:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Any successful <a href="../functions/read.html"><i>read</i>()</a> from each byte position in the file that was modified by that
|
|
write shall return the data specified by the <i>write</i>() for that position until such byte positions are again modified.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Any subsequent successful <i>write</i>() to the same byte position in the file shall overwrite that file data.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Write requests to a pipe or FIFO shall be handled in the same way as a regular file with the following exceptions:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>There is no file offset associated with a pipe, hence each write request shall append to the end of the pipe.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Write requests of {PIPE_BUF} bytes or less shall not be interleaved with data from other processes doing writes on the same
|
|
pipe. Writes of greater than {PIPE_BUF} bytes may have data interleaved, on arbitrary boundaries, with writes by other processes,
|
|
whether or not the O_NONBLOCK flag of the file status flags is set.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the O_NONBLOCK flag is clear, a write request may cause the thread to block, but on normal completion it shall return
|
|
<i>nbyte</i>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the O_NONBLOCK flag is set, <i>write</i>() requests shall be handled differently, in the following ways:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The <i>write</i>() function shall not block the thread.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A write request for {PIPE_BUF} or fewer bytes shall have the following effect: if there is sufficient space available in the
|
|
pipe, <i>write</i>() shall transfer all the data and return the number of bytes requested. Otherwise, <i>write</i>() shall transfer
|
|
no data and return -1 with <i>errno</i> set to [EAGAIN].</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A write request for more than {PIPE_BUF} bytes shall cause one of the following:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>When at least one byte can be written, transfer what it can and return the number of bytes written. When all data previously
|
|
written to the pipe is read, it shall transfer at least {PIPE_BUF} bytes.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>When no data can be written, transfer no data, and return -1 with <i>errno</i> set to [EAGAIN].</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>When attempting to write to a file descriptor (other than a pipe or FIFO) that supports non-blocking writes and cannot accept
|
|
the data immediately:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>If the O_NONBLOCK flag is clear, <i>write</i>() shall block the calling thread until the data can be accepted.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the O_NONBLOCK flag is set, <i>write</i>() shall not block the thread. If some data can be written without blocking the
|
|
thread, <i>write</i>() shall write what it can and return the number of bytes written. Otherwise, it shall return -1 and set
|
|
<i>errno</i> to [EAGAIN].</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Upon successful completion, where <i>nbyte</i> is greater than 0, <i>write</i>() shall mark for update the <i>st_ctime</i> and
|
|
<i>st_mtime</i> fields of the file, and if the file is a regular file, the S_ISUID and S_ISGID bits of the file mode may be
|
|
cleared.</p>
|
|
|
|
<p>For regular files, no data transfer shall occur past the offset maximum established in the open file description associated with
|
|
<i>fildes</i>.</p>
|
|
|
|
<p>If <i>fildes</i> refers to a socket, <i>write</i>() shall be equivalent to <a href="../functions/send.html"><i>send</i>()</a>
|
|
with no flags set.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('SIO')">SIO</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If the O_DSYNC bit has been set, write I/O operations on the file descriptor shall complete as defined by synchronized I/O data
|
|
integrity completion.</p>
|
|
|
|
<p>If the O_SYNC bit has been set, write I/O operations on the file descriptor shall complete as defined by synchronized I/O file
|
|
integrity completion. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('SHM')">SHM</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If <i>fildes</i> refers to a shared memory object, the result of the <i>write</i>() function is unspecified. <img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('TYM')">TYM</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If <i>fildes</i> refers to a typed memory object, the result of the <i>write</i>() function is unspecified. <img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If <i>fildes</i> refers to a STREAM, the operation of <i>write</i>() shall be determined by the values of the minimum and maximum
|
|
<i>nbyte</i> range (packet size) accepted by the STREAM. These values are determined by the topmost STREAM module. If <i>nbyte</i>
|
|
falls within the packet size range, <i>nbyte</i> bytes shall be written. If <i>nbyte</i> does not fall within the range and the
|
|
minimum packet size value is 0, <i>write</i>() shall break the buffer into maximum packet size segments prior to sending the data
|
|
downstream (the last segment may contain less than the maximum packet size). If <i>nbyte</i> does not fall within the range and the
|
|
minimum value is non-zero, <i>write</i>() shall fail with <i>errno</i> set to [ERANGE]. Writing a zero-length buffer ( <i>nbyte</i>
|
|
is 0) to a STREAMS device sends 0 bytes with 0 returned. However, writing a zero-length buffer to a STREAMS-based pipe or FIFO
|
|
sends no message and 0 is returned. The process may issue I_SWROPT <a href="../functions/ioctl.html"><i>ioctl</i>()</a> to enable
|
|
zero-length messages to be sent across the pipe or FIFO.</p>
|
|
|
|
<p>When writing to a STREAM, data messages are created with a priority band of 0. When writing to a STREAM that is not a pipe or
|
|
FIFO:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>If O_NONBLOCK is clear, and the STREAM cannot accept data (the STREAM write queue is full due to internal flow control
|
|
conditions), <i>write</i>() shall block until data can be accepted.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If O_NONBLOCK is set and the STREAM cannot accept data, <i>write</i>() shall return -1 and set <i>errno</i> to [EAGAIN].</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If O_NONBLOCK is set and part of the buffer has been written while a condition in which the STREAM cannot accept additional data
|
|
occurs, <i>write</i>() shall terminate and return the number of bytes written.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>In addition, <i>write</i>() shall fail if the STREAM head has processed an asynchronous error before the call. In this case, the
|
|
value of <i>errno</i> does not reflect the result of <i>write</i>(), but reflects the prior error. <img src="../images/opt-end.gif"
|
|
alt="[Option End]" border="0"></p>
|
|
|
|
<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 be equivalent to <i>write</i>(), except that it writes into a given position without changing
|
|
the file pointer. The first three arguments to <i>pwrite</i>() are the same as <i>write</i>() with the addition of a fourth
|
|
argument offset for the desired position inside the file. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_866_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, <i>write</i>() <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src=
|
|
"../images/opt-start.gif" alt="[Option Start]" border="0"> and <i>pwrite</i>() <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"> shall return the number of bytes actually written to the file associated with <i>fildes</i>. This number
|
|
shall never be greater than <i>nbyte</i>. Otherwise, -1 shall be returned and <i>errno</i> set to indicate the error.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_866_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<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 shall fail
|
|
if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EAGAIN]</dt>
|
|
|
|
<dd>The O_NONBLOCK flag is set for the file descriptor and the thread would be delayed in the <i>write</i>() operation.</dd>
|
|
|
|
<dt>[EBADF]</dt>
|
|
|
|
<dd>The <i>fildes</i> argument is not a valid file descriptor open for writing.</dd>
|
|
|
|
<dt>[EFBIG]</dt>
|
|
|
|
<dd>An attempt was made to write a file that exceeds the implementation-defined maximum file size <sup>[<a href=
|
|
"javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> or the
|
|
process' file size limit, <img src="../images/opt-end.gif" alt="[Option End]" border="0"> and there was no room for any bytes
|
|
to be written.</dd>
|
|
|
|
<dt>[EFBIG]</dt>
|
|
|
|
<dd>The file is a regular file, <i>nbyte</i> is greater than 0, and the starting position is greater than or equal to the offset
|
|
maximum established in the open file description associated with <i>fildes</i>.</dd>
|
|
|
|
<dt>[EINTR]</dt>
|
|
|
|
<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 <sys/types.h>
|
|
#include <string.h>
|
|
...
|
|
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 Std 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><<i>nbyte</i>
|
|
|
|
<p>This shall never happen if <i>nbyte</i><= {PIPE_BUF}. If it does happen (with <i>nbyte</i>> {PIPE_BUF}), this volume of
|
|
IEEE Std 1003.1-2001 does not guarantee atomicity, even if <i>ret</i><= {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><= {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>> {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><={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"> </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>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><i>nbyte</i>>{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><={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>>{PIPE_BUF}</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">-1, [EAGAIN]</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"><<i>nbyte</i> or -1,</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"><=<i>nbyte</i> or -1,</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </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 Std 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 Std 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 Std 1003.1-2001). The error indications in this volume of IEEE Std 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 "high-performance" write analog that did not follow these serialization requirements would also be
|
|
permitted by this wording. This volume of IEEE Std 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 Std 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 Std 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 Std 1003.1-2001, <a href=
|
|
"../basedefs/limits.h.html"><i><limits.h></i></a>, <a href="../basedefs/stropts.h.html"><i><stropts.h></i></a>, <a
|
|
href="../basedefs/sys/uio.h.html"><i><sys/uio.h></i></a>, <a href="../basedefs/unistd.h.html"><i><unistd.h></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 "process" rather than
|
|
"thread".</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 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 Std 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 "may fail".</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 ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® 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>
|
|
|