xsh_chap02.html

IEEE 1003.1-2003, Single Unix Specification v3

<p>It was the consensus of the standard developers that to allow the conformance document to state that an error occurs and under
what conditions, but to disallow a statement that it never occurs, does not make sense. It could be implied by the current wording
that this is allowed, but to reduce the possibility of future interpretation requests, it is better to make an explicit
statement.</p>

<p>The ISO&nbsp;C standard requires that <i>errno</i> be an assignable lvalue. Originally, the definition in POSIX.1 was stricter
than that in the ISO&nbsp;C standard, <b>extern int</b> <i>errno</i>, in order to support historical usage. In a multi-threaded
environment, implementing <i>errno</i> as a global variable results in non-deterministic results when accessed. It is required,
however, that <i>errno</i> work as a per-thread error reporting mechanism. In order to do this, a separate <i>errno</i> value has
to be maintained for each thread. The following section discusses the various alternative solutions that were considered.</p>

<p>In order to avoid this problem altogether for new functions, these functions avoid using <i>errno</i> and, instead, return the
error number directly as the function return value; a return value of zero indicates that no error was detected.</p>

<p>For any function that can return errors, the function return value is not used for any purpose other than for reporting errors.
Even when the output of the function is scalar, it is passed through a function argument. While it might have been possible to
allow some scalar outputs to be coded as negative function return values and mixed in with positive error status returns, this was
rejected-using the return value for a mixed purpose was judged to be of limited use and error prone.</p>

<p>Checking the value of <i>errno</i> alone is not sufficient to determine the existence or type of an error, since it is not
required that a successful function call clear <i>errno</i>. The variable <i>errno</i> should only be examined when the return
value of a function indicates that the value of <i>errno</i> is meaningful. In that case, the function is required to set the
variable to something other than zero.</p>

<p>The variable <i>errno</i> is never set to zero by any function call; to do so would contradict the ISO&nbsp;C standard.</p>

<p>POSIX.1 requires (in the ERRORS sections of function descriptions) certain error values to be set in certain conditions because
many existing applications depend on them. Some error numbers, such as [EFAULT], are entirely implementation-defined and are noted
as such in their description in the ERRORS section. This section otherwise allows wide latitude to the implementation in handling
error reporting.</p>

<p>Some of the ERRORS sections in IEEE&nbsp;Std&nbsp;1003.1-2001 have two subsections. The first:</p>

<blockquote>
<pre>
&quot;The function shall fail if:''
</pre>
</blockquote>

<p>could be called the &quot;mandatory&quot; section.</p>

<p>The second:</p>

<blockquote>
<pre>
&quot;The function may fail if:''
</pre>
</blockquote>

<p>could be informally known as the &quot;optional&quot; section.</p>

<p>Attempting to infer the quality of an implementation based on whether it detects optional error conditions is not useful.</p>

<p>Following each one-word symbolic name for an error, there is a description of the error. The rationale for some of the symbolic
names follows:</p>

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

<dd>This spelling was chosen as being more common.</dd>

<dt>[EFAULT]</dt>

<dd>Most historical implementations do not catch an error and set <i>errno</i> when an invalid address is given to the functions <a
href="../functions/wait.html"><i>wait</i>()</a>, <a href="../functions/time.html"><i>time</i>()</a>, or <a href=
"../functions/times.html"><i>times</i>()</a>. Some implementations cannot reliably detect an invalid address. And most systems that
detect invalid addresses will do so only for a system call, not for a library routine.</dd>

<dt>[EFTYPE]</dt>

<dd>This error code was proposed in earlier proposals as &quot;Inappropriate operation for file type&quot;, meaning that the operation
requested is not appropriate for the file specified in the function call. This code was proposed, although the same idea was
covered by [ENOTTY], because the connotations of the name would be misleading. It was pointed out that the <a href=
"../functions/fcntl.html"><i>fcntl</i>()</a> function uses the error code [EINVAL] for this notion, and hence all instances of
[EFTYPE] were changed to this code.</dd>

<dt>[EINTR]</dt>

<dd>POSIX.1 prohibits conforming implementations from restarting interrupted system calls of conforming applications unless the
SA_RESTART flag is in effect for the signal. However, it does not require that [EINTR] be returned when another legitimate value
may be substituted; for example, a partial transfer count when <a href="../functions/read.html"><i>read</i>()</a> or <a href=
"../functions/write.html"><i>write</i>()</a> are interrupted. This is only given when the signal-catching function returns normally
as opposed to returns by mechanisms like <a href="../functions/longjmp.html"><i>longjmp</i>()</a> or <a href=
"../functions/siglongjmp.html"><i>siglongjmp</i>()</a>.</dd>

<dt>[ELOOP]</dt>

<dd>In specifying conditions under which implementations would generate this error, the following goals were considered: 

<ul>
<li>
<p>To ensure that actual loops are detected, including loops that result from symbolic links across distributed file systems.</p>
</li>

<li>
<p>To ensure that during pathname resolution an application can rely on the ability to follow at least {SYMLOOP_MAX} symbolic links
in the absence of a loop.</p>
</li>

<li>
<p>To allow implementations to provide the capability of traversing more than {SYMLOOP_MAX} symbolic links in the absence of a
loop.</p>
</li>

<li>
<p>To allow implementations to detect loops and generate the error prior to encountering {SYMLOOP_MAX} symbolic links.</p>
</li>
</ul>
</dd>

<dt>[ENAMETOOLONG]</dt>

<dd><br>
When a symbolic link is encountered during pathname resolution, the contents of that symbolic link are used to create a new
pathname. The standard developers intended to allow, but not require, that implementations enforce the restriction of {PATH_MAX} on
the result of this pathname substitution.</dd>

<dt>[ENOMEM]</dt>

<dd>The term &quot;main memory&quot; is not used in POSIX.1 because it is implementation-defined.</dd>

<dt>[ENOTSUP]</dt>

<dd>This error code is to be used when an implementation chooses to implement the required functionality of
IEEE&nbsp;Std&nbsp;1003.1-2001 but does not support optional facilities defined by IEEE&nbsp;Std&nbsp;1003.1-2001. The return of
[ENOSYS] is to be taken to indicate that the function of the interface is not supported at all; the function will always fail with
this error code.</dd>

<dt>[ENOTTY]</dt>

<dd>The symbolic name for this error is derived from a time when device control was done by <a href=
"../functions/ioctl.html"><i>ioctl</i>()</a> and that operation was only permitted on a terminal interface. The term &quot;TTY&quot; is
derived from &quot;teletypewriter&quot;, the devices to which this error originally applied.</dd>

<dt>[EOVERFLOW]</dt>

<dd>Most of the uses of this error code are related to large file support. Typically, these cases occur on systems which support
multiple programming environments with different sizes for <b>off_t</b>, but they may also occur in connection with remote file
systems. 

<p>In addition, when different programming environments have different widths for types such as <b>int</b> and <b>uid_t</b>,
several functions may encounter a condition where a value in a particular environment is too wide to be represented. In that case,
this error should be raised. For example, suppose the currently running process has 64-bit <b>int</b>, and file descriptor
9223372036854775807 is open and does not have the close-on- <i>exec</i> flag set. If the process then uses <a href=
"../functions/execl.html"><i>execl</i>()</a> to <i>exec</i> a file compiled in a programming environment with 32-bit <b>int</b>,
the call to <a href="../functions/execl.html"><i>execl</i>()</a> can fail with <i>errno</i> set to [EOVERFLOW]. A similar failure
can occur with <a href="../functions/execl.html"><i>execl</i>()</a> if any of the user IDs or any of the group IDs to be assigned
to the new process image are out of range for the executed file's programming environment.</p>

<p>Note, however, that this condition cannot occur for functions that are explicitly described as always being successful, such as
<a href="../functions/getpid.html"><i>getpid</i>()</a>.</p>
</dd>

<dt>[EPIPE]</dt>

<dd>This condition normally generates the signal SIGPIPE; the error is returned if the signal does not terminate the process.</dd>

<dt>[EROFS]</dt>

<dd>In historical implementations, attempting to <a href="../functions/unlink.html"><i>unlink</i>()</a> or <a href=
"../functions/rmdir.html"><i>rmdir</i>()</a> a mount point would generate an [EBUSY] error. An implementation could be envisioned
where such an operation could be performed without error. In this case, if <i>either</i> the directory entry or the actual data
structures reside on a read-only file system, [EROFS] is the appropriate error to generate. (For example, changing the link count
of a file on a read-only file system could not be done, as is required by <a href="../functions/unlink.html"><i>unlink</i>()</a>,
and thus an error should be reported.)</dd>
</dl>

<p>Three error numbers, [EDOM], [EILSEQ], and [ERANGE], were added to this section primarily for consistency with the ISO&nbsp;C
standard.</p>

<h5><a name="tag_03_02_03_01"></a>Alternative Solutions for Per-Thread errno</h5>

<p>The usual implementation of <i>errno</i> as a single global variable does not work in a multi-threaded environment. In such an
environment, a thread may make a POSIX.1 call and get a -1 error return, but before that thread can check the value of
<i>errno</i>, another thread might have made a second POSIX.1 call that also set <i>errno</i>. This behavior is unacceptable in
robust programs. There were a number of alternatives that were considered for handling the <i>errno</i> problem:</p>

<ul>
<li>
<p>Implement <i>errno</i> as a per-thread integer variable.</p>
</li>

<li>
<p>Implement <i>errno</i> as a service that can access the per-thread error number.</p>
</li>

<li>
<p>Change all POSIX.1 calls to accept an extra status argument and avoid setting <i>errno</i>.</p>
</li>

<li>
<p>Change all POSIX.1 calls to raise a language exception.</p>
</li>
</ul>

<p>The first option offers the highest level of compatibility with existing practice but requires special support in the linker,
compiler, and/or virtual memory system to support the new concept of thread private variables. When compared with current practice,
the third and fourth options are much cleaner, more efficient, and encourage a more robust programming style, but they require new
versions of all of the POSIX.1 functions that might detect an error. The second option offers compatibility with existing code that
uses the <a href="../basedefs/errno.h.html"><i>&lt;errno.h&gt;</i></a> header to define the symbol <i>errno</i>. In this option,
<i>errno</i> may be a macro defined:</p>

<blockquote>
<pre>
<tt>#define errno  (*__errno())
extern int      *__errno();
</tt>
</pre>
</blockquote>