pread.html

IEEE 1003.1-2003, Single Unix Specification v3

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

<dl compact>
<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>[ENOMEM]</dt>

<dd>Insufficient memory was available to fulfill the request.</dd>

<dt>[ENXIO]</dt>

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

<p>The <i>pread</i>() function shall fail, and the file pointer shall remain unchanged, if:</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>[EOVERFLOW]</dt>

<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
The file is a regular file and an attempt was made to read at or beyond the offset maximum associated with the file. <img src=
"../images/opt-end.gif" alt="[Option End]" border="0"></dd>

<dt>[ENXIO]</dt>

<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
A request was outside the capabilities of the device. <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_594_06"></a>EXAMPLES</h4>

<blockquote>
<h5><a name="tag_03_594_06_01"></a>Reading Data into a Buffer</h5>

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

<pre>
<tt>#include &lt;sys/types.h&gt;
#include &lt;unistd.h&gt;
...
char buf[20];
size_t nbytes;
ssize_t bytes_read;
int fd;
...
nbytes = sizeof(buf);
bytes_read = read(fd, buf, nbytes);
...
</tt>
</pre>
</blockquote>

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

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

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

<blockquote>
<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>Note that a <i>read</i>() of zero bytes does not modify <i>st_atime</i>. A <i>read</i>() that requests more than zero bytes, but
returns zero, shall modify <i>st_atime</i>.</p>

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

<h5><a name="tag_03_594_08_01"></a>Input and Output</h5>

<p>The use of I/O with large byte counts has always presented problems. Ideas such as <i>lread</i>() and <i>lwrite</i>() (using and
returning <b>long</b>s) were considered at one time. The current solution is to use abstract types on the ISO&nbsp;C standard
function to <i>read</i>() and <a href="../functions/write.html"><i>write</i>()</a>. The abstract types can be declared so that
existing functions work, but can also be declared so that larger types can be represented in future implementations. It is presumed
that whatever constraints limit the maximum range of <b>size_t</b> also limit portable I/O requests to the same range. This volume
of IEEE&nbsp;Std&nbsp;1003.1-2001 also limits the range further by requiring that the byte count be limited so that a signed return
value remains meaningful. Since the return type is also a (signed) abstract type, the byte count can be defined by the
implementation to be larger than an <b>int</b> can hold.</p>

<p>The standard developers considered adding atomicity requirements to a pipe or FIFO, but recognized that due to the nature of
pipes and FIFOs there could be no guarantee of atomicity of reads of {PIPE_BUF} or any other size that would be an aid to
applications portability.</p>

<p>This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 requires that no action be taken for <i>read</i>() or <a href=
"../functions/write.html"><i>write</i>()</a> when <i>nbyte</i> is zero. This is not intended to take precedence over detection of
errors (such as invalid buffer pointers or file descriptors). This is consistent with the rest of this volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, but the phrasing here could be misread to require detection of the zero case before any other
errors. A value of zero is to be considered a correct value, for which the semantics are a no-op.</p>

<p>I/O is intended to be atomic to ordinary files and pipes and FIFOs. Atomic means that all the bytes from a single operation that
started out together end up together, without interleaving from other I/O operations. It is a known attribute of terminals that
this is not honored, and terminals are explicitly (and implicitly permanently) excepted, making the behavior unspecified. The
behavior for other device types is also left unspecified, but the wording is intended to imply that future standards might choose
to specify atomicity (or not).</p>

<p>There were recommendations to add format parameters to <i>read</i>() and <a href="../functions/write.html"><i>write</i>()</a> in
order to handle networked transfers among heterogeneous file system and base hardware types. Such a facility may be required for
support by the OSI presentation of layer services. However, it was determined that this should correspond with similar C-language
facilities, and that is beyond the scope of this volume of IEEE&nbsp;Std&nbsp;1003.1-2001. The concept was suggested to the
developers of the ISO&nbsp;C standard for their consideration as a possible area for future work.</p>

<p>In 4.3 BSD, a <i>read</i>() or <a href="../functions/write.html"><i>write</i>()</a> that is interrupted by a signal before
transferring any data does not by default return an [EINTR] error, but is restarted. In 4.2 BSD, 4.3 BSD, and the Eighth Edition,
there is an additional function, <a href="../functions/select.html"><i>select</i>()</a>, whose purpose is to pause until specified
activity (data to read, space to write, and so on) is detected on specified file descriptors. It is common in applications written
for those systems for <a href="../functions/select.html"><i>select</i>()</a> to be used before <i>read</i>() in situations (such as
keyboard input) where interruption of I/O due to a signal is desired.</p>

<p>The issue of which files or file types are interruptible is considered an implementation design issue. This is often affected
primarily by hardware and reliability issues.</p>

<p>There are no references to actions taken following an &quot;unrecoverable error&quot;. It is considered beyond the scope of this volume
of IEEE&nbsp;Std&nbsp;1003.1-2001 to describe what happens in the case of hardware errors.</p>

<p>Previous versions of IEEE&nbsp;Std&nbsp;1003.1-2001 allowed two very different behaviors with regard to the handling of
interrupts. In order to minimize the resulting confusion, it was decided that IEEE&nbsp;Std&nbsp;1003.1-2001 should support only
one of these behaviors. Historical practice on AT&amp;T-derived systems was to have <i>read</i>() and <a href=
"../functions/write.html"><i>write</i>()</a> return -1 and set <i>errno</i> to [EINTR] when interrupted after some, but not all, of
the data requested had been transferred. However, the U.S. Department of Commerce FIPS 151-1 and FIPS 151-2 require the historical
BSD behavior, in which <i>read</i>() and <a href="../functions/write.html"><i>write</i>()</a> return the number of bytes actually
transferred before the interrupt. If -1 is returned when any data is transferred, it is difficult to recover from the error on a
seekable device and impossible on a non-seekable device. Most new implementations support this behavior. The behavior required by
IEEE&nbsp;Std&nbsp;1003.1-2001 is to return the number of bytes transferred.</p>

<p>IEEE&nbsp;Std&nbsp;1003.1-2001 does not specify when an implementation that buffers <i>read</i>()ss actually moves the data into
the user-supplied buffer, so an implementation may chose to do this at the latest possible moment. Therefore, an interrupt arriving
earlier may not cause <i>read</i>() to return a partial byte count, but rather to return -1 and set <i>errno</i> to [EINTR].</p>

<p>Consideration was also given to combining the two previous options, and setting <i>errno</i> to [EINTR] while returning a short
count. However, not only is there no existing practice that implements this, it is also contradictory to the idea that when
<i>errno</i> is set, the function responsible shall return -1.</p>
</blockquote>

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

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

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

<blockquote>
<p><a href="fcntl.html"><i>fcntl</i>()</a> , <a href="ioctl.html"><i>ioctl</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="readv.html"><i>readv</i>()</a> , the Base
Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/xbd_chap11.html#tag_11">Chapter 11, General Terminal
Interface</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_594_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_594_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>pread</i>() function is added.</p>
</blockquote>

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

<blockquote>
<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>read</i>() is interrupted by a signal after it has successfully read some data, it returns
the number of bytes read. In Issue 3, it was optional whether <i>read</i>() returned the number of bytes read, or whether it
returned -1 with <i>errno</i> set to [EINTR]. This is a FIPS requirement.</p>
</li>

<li>
<p>In the DESCRIPTION, text is added to indicate that for regular files, no data transfer occurs past the offset maximum
established in the open file description associated with <i>fildes</i>. This change is to support large files.</p>
</li>

<li>
<p>The [EOVERFLOW] mandatory error condition is added.</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>read</i>() results are
unspecified for typed memory objects.</p>

<p>New RATIONALE is added to explain the atomicity requirements for input and output operations.</p>

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

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

<p>The following error conditions are added for operations on sockets: [ENOBUFS] and [ENOMEM].</p>

<p>The <a href="../functions/readv.html"><i>readv</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>