524 lines
28 KiB
HTML
524 lines
28 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>read</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="read"></a> <a name="tag_03_594"></a><!-- read -->
|
|
<!--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_594_01"></a>NAME</h4>
|
|
|
|
<blockquote>pread, read - read from a file</blockquote>
|
|
|
|
<h4><a name="tag_03_594_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 pread(int</tt> <i>fildes</i><tt>, void *</tt><i>buf</i><tt>, size_t</tt> <i>nbyte</i><tt>,
|
|
off_t</tt> <i>offset</i><tt>); <img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
ssize_t read(int</tt> <i>fildes</i><tt>, void *</tt><i>buf</i><tt>, size_t</tt> <i>nbyte</i><tt>);<br>
|
|
</tt></blockquote>
|
|
|
|
<h4><a name="tag_03_594_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>read</i>() function shall attempt to read <i>nbyte</i> bytes from the file associated with the open file descriptor,
|
|
<i>fildes</i>, into the buffer pointed to by <i>buf</i>. The behavior of multiple concurrent reads on the same pipe, FIFO, or
|
|
terminal device is unspecified.</p>
|
|
|
|
<p>Before any action described below is taken, and if <i>nbyte</i> is zero, the <i>read</i>() function may detect and return errors
|
|
as described below. In the absence of errors, or if error detection is not performed, the <i>read</i>() function shall return zero
|
|
and have no other results.</p>
|
|
|
|
<p>On files that support seeking (for example, a regular file), the <i>read</i>() shall start at a position in the file given by
|
|
the file offset associated with <i>fildes</i>. The file offset shall be incremented by the number of bytes actually read.</p>
|
|
|
|
<p>Files that do not support seeking-for example, terminals-always read from the current position. The value of a file offset
|
|
associated with such a file is undefined.</p>
|
|
|
|
<p>No data transfer shall occur past the current end-of-file. If the starting position is at or after the end-of-file, 0 shall be
|
|
returned. If the file refers to a device special file, the result of subsequent <i>read</i>() requests is
|
|
implementation-defined.</p>
|
|
|
|
<p>If the value of <i>nbyte</i> is greater than {SSIZE_MAX}, the result is implementation-defined.</p>
|
|
|
|
<p>When attempting to read from an empty pipe or FIFO:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>If no process has the pipe open for writing, <i>read</i>() shall return 0 to indicate end-of-file.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If some process has the pipe open for writing and O_NONBLOCK is set, <i>read</i>() shall return -1 and set <i>errno</i> to
|
|
[EAGAIN].</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If some process has the pipe open for writing and O_NONBLOCK is clear, <i>read</i>() shall block the calling thread until some
|
|
data is written or the pipe is closed by all processes that had the pipe open for writing.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>When attempting to read a file (other than a pipe or FIFO) that supports non-blocking reads and has no data currently
|
|
available:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>If O_NONBLOCK is set, <i>read</i>() shall return -1 and set <i>errno</i> to [EAGAIN].</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If O_NONBLOCK is clear, <i>read</i>() shall block the calling thread until some data becomes available.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The use of the O_NONBLOCK flag has no effect if there is some data available.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The <i>read</i>() function reads data previously written to a file. If any portion of a regular file prior to the end-of-file
|
|
has not been written, <i>read</i>() shall return bytes with value 0. For example, <a href=
|
|
"../functions/lseek.html"><i>lseek</i>()</a> allows the file offset to be set beyond the end of existing data in the file. If data
|
|
is later written at this point, subsequent reads in the gap between the previous end of data and the newly written data shall
|
|
return bytes with value 0 until data is written into the gap.</p>
|
|
|
|
<p>Upon successful completion, where <i>nbyte</i> is greater than 0, <i>read</i>() shall mark for update the <i>st_atime</i> field
|
|
of the file, and shall return the number of bytes read. This number shall never be greater than <i>nbyte</i>. The value returned
|
|
may be less than <i>nbyte</i> if the number of bytes left in the file is less than <i>nbyte</i>, if the <i>read</i>() request was
|
|
interrupted by a signal, or if the file is a pipe or FIFO or special file and has fewer than <i>nbyte</i> bytes immediately
|
|
available for reading. For example, a <i>read</i>() from a file associated with a terminal may return one typed line of data.</p>
|
|
|
|
<p>If a <i>read</i>() is interrupted by a signal before it reads any data, it shall return -1 with <i>errno</i> set to [EINTR].</p>
|
|
|
|
<p>If a <i>read</i>() is interrupted by a signal after it has successfully read some data, it shall return the number of bytes
|
|
read.</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>read</i>() shall be equivalent to <a href="../functions/recv.html"><i>recv</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 and O_RSYNC bits have been set, read I/O operations on the file descriptor shall complete as defined by synchronized
|
|
I/O data integrity completion. If the O_SYNC and O_RSYNC bits have been set, read 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>read</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>read</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"> A
|
|
<i>read</i>() from a STREAMS file can read data in three different modes: <i>byte-stream</i> mode, <i>message-nondiscard</i> mode,
|
|
and <i>message-discard</i> mode. The default shall be byte-stream mode. This can be changed using the I_SRDOPT <a href=
|
|
"../functions/ioctl.html"><i>ioctl</i>()</a> request, and can be tested with I_GRDOPT <a href=
|
|
"../functions/ioctl.html"><i>ioctl</i>()</a>. In byte-stream mode, <i>read</i>() shall retrieve data from the STREAM until as many
|
|
bytes as were requested are transferred, or until there is no more data to be retrieved. Byte-stream mode ignores message
|
|
boundaries.</p>
|
|
|
|
<p>In STREAMS message-nondiscard mode, <i>read</i>() shall retrieve data until as many bytes as were requested are transferred, or
|
|
until a message boundary is reached. If <i>read</i>() does not retrieve all the data in a message, the remaining data shall be left
|
|
on the STREAM, and can be retrieved by the next <i>read</i>() call. Message-discard mode also retrieves data until as many bytes as
|
|
were requested are transferred, or a message boundary is reached. However, unread data remaining in a message after the
|
|
<i>read</i>() returns shall be discarded, and shall not be available for a subsequent <i>read</i>(), <a href=
|
|
"../functions/getmsg.html"><i>getmsg</i>()</a>, or <a href="../functions/getpmsg.html"><i>getpmsg</i>()</a> call.</p>
|
|
|
|
<p>How <i>read</i>() handles zero-byte STREAMS messages is determined by the current read mode setting. In byte-stream mode,
|
|
<i>read</i>() shall accept data until it has read <i>nbyte</i> bytes, or until there is no more data to read, or until a zero-byte
|
|
message block is encountered. The <i>read</i>() function shall then return the number of bytes read, and place the zero-byte
|
|
message back on the STREAM to be retrieved by the next <i>read</i>(), <a href="../functions/getmsg.html"><i>getmsg</i>()</a>, or <a
|
|
href="../functions/getpmsg.html"><i>getpmsg</i>()</a>. In message-nondiscard mode or message-discard mode, a zero-byte message
|
|
shall return 0 and the message shall be removed from the STREAM. When a zero-byte message is read as the first message on a STREAM,
|
|
the message shall be removed from the STREAM and 0 shall be returned, regardless of the read mode.</p>
|
|
|
|
<p>A <i>read</i>() from a STREAMS file shall return the data in the message at the front of the STREAM head read queue, regardless
|
|
of the priority band of the message.</p>
|
|
|
|
<p>By default, STREAMs are in control-normal mode, in which a <i>read</i>() from a STREAMS file can only process messages that
|
|
contain a data part but do not contain a control part. The <i>read</i>() shall fail if a message containing a control part is
|
|
encountered at the STREAM head. This default action can be changed by placing the STREAM in either control-data mode or
|
|
control-discard mode with the I_SRDOPT <a href="../functions/ioctl.html"><i>ioctl</i>()</a> command. In control-data mode,
|
|
<i>read</i>() shall convert any control part to data and pass it to the application before passing any data part originally present
|
|
in the same message. In control-discard mode, <i>read</i>() shall discard message control parts but return to the process any data
|
|
part in the message.</p>
|
|
|
|
<p>In addition, <i>read</i>() shall fail if the STREAM head had processed an asynchronous error before the call. In this case, the
|
|
value of <i>errno</i> shall not reflect the result of <i>read</i>(), but reflect the prior error. If a hangup occurs on the STREAM
|
|
being read, <i>read</i>() shall continue to operate normally until the STREAM head read queue is empty. Thereafter, it shall return
|
|
0. <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>pread</i>() function shall be equivalent to <i>read</i>(), except that it shall read from a given position in the file
|
|
without changing the file pointer. The first three arguments to <i>pread</i>() are the same as <i>read</i>() with the addition of a
|
|
fourth argument <i>offset</i> for the desired position inside the file. An attempt to perform a <i>pread</i>() on a file that is
|
|
incapable of seeking shall result in an error. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_594_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, <i>read</i>() <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src=
|
|
"../images/opt-start.gif" alt="[Option Start]" border="0"> and <i>pread</i>() <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"> shall return a non-negative integer indicating the number of bytes actually read. Otherwise, the
|
|
functions shall return -1 and set <i>errno</i> to indicate the error.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_594_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<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 shall fail
|
|
if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EAGAIN]</dt>
|
|
|
|
<dd>The O_NONBLOCK flag is set for the file descriptor and the process would be delayed.</dd>
|
|
|
|
<dt>[EBADF]</dt>
|
|
|
|
<dd>The <i>fildes</i> argument is not a valid file descriptor open for reading.</dd>
|
|
|
|
<dt>[EBADMSG]</dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
The file is a STREAM file that is set to control-normal mode and the message waiting to be read includes a control part. <img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt>[EINTR]</dt>
|
|
|
|
<dd>The read operation was terminated due to the receipt of a signal, and no data was transferred.</dd>
|
|
|
|
<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>The process is a member of a background process attempting to read from its controlling terminal, the process is ignoring or
|
|
blocking the SIGTTIN signal, or the process group is orphaned. This error may also be generated for implementation-defined
|
|
reasons.</dd>
|
|
|
|
<dt>[EISDIR]</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>fildes</i> argument refers to a directory and the implementation does not allow the directory to be read using <i>read</i>()
|
|
or <i>pread</i>(). The <a href="../functions/readdir.html"><i>readdir</i>()</a> function should be used instead. <img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt>[EOVERFLOW]</dt>
|
|
|
|
<dd>The file is a regular file, <i>nbyte</i> is greater than 0, the starting position is before the end-of-file, 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>
|
|
</dl>
|
|
|
|
<p>The <i>read</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 no data is waiting to be received.</dd>
|
|
|
|
<dt>[ECONNRESET]</dt>
|
|
|
|
<dd>A read was attempted on a socket and the connection was forcibly closed by its peer.</dd>
|
|
|
|
<dt>[ENOTCONN]</dt>
|
|
|
|
<dd>A read was attempted on a socket that is not connected.</dd>
|
|
|
|
<dt>[ETIMEDOUT]</dt>
|
|
|
|
<dd>A read was attempted on a socket and a transmission timeout occurred.</dd>
|
|
</dl>
|
|
|
|
<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 <sys/types.h>
|
|
#include <unistd.h>
|
|
...
|
|
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 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>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 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 Std 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 Std 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 Std 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 Std 1003.1-2001. The concept was suggested to the
|
|
developers of the ISO 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 "unrecoverable error". It is considered beyond the scope of this volume
|
|
of IEEE Std 1003.1-2001 to describe what happens in the case of hardware errors.</p>
|
|
|
|
<p>Previous versions of IEEE Std 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 Std 1003.1-2001 should support only
|
|
one of these behaviors. Historical practice on AT&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 Std 1003.1-2001 is to return the number of bytes transferred.</p>
|
|
|
|
<p>IEEE Std 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 Std 1003.1-2001, <a href="../basedefs/xbd_chap11.html#tag_11">Chapter 11, General Terminal
|
|
Interface</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_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 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>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 "may fail".</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 ® 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>
|
|
|