<html>
<head>
<title>WG14: N1308; WG21: N2604=08-0114  Thoughts on Implementing errno as a Macro</title>
<style type="text/css" title="text/css">
/* <![CDATA[ */
* { font-family: serif; }
*.code { font-size: 120%; font-family: monospace; font-weight: bolder; }
*.non-code { font-style: italic; font-family: monospace; }
p > span.non-code { font-size: 120%; }
*.link-target { font-weight: bolder; }
*.copyright { font-style: italic; }
h1 { text-align: center; }
div.group { border-bottom: double; padding-bottom: .5em; }
div.subgroup { border-bottom: thin solid; padding-bottom: .5em; }
div.added { color: green; text-decoration: underline; }
div.removed { color: red; text-decoration: line-through; }
div.block { border-bottom: thin solid; border-top: thin solid; }
div.menu { padding-top: .5em; padding-bottom: .5em; }
div.menu a { padding-right: .3em; }
div.menu a + a { padding-left: .45em; border-left: thin solid; line-height: 1.3em; }
table.heading { border-collapse: separate; float: right; padding-right: 1em; }
td.descr { padding: 0; text-align: right; font-style: italic; font-weight: bold; }
td.descr:after { content: ":"; }
td.emptydescr { padding: 0; }
td.value { padding: 0; padding-left: 1ex; }
pre { font-family: monospace; }
pre a.code { font-size: 100%; }
pre .decl { font-weight: bolder; font-size: 80%; }
span.reqmt { font-style: italic; }
span.reqmt:after { content: ":" }
span.title { font-style: italic; }
span.added { color: green; text-decoration: underline; }
span.addedd { color: blue; text-decoration: underline; }
span.math { font-style: italic; }
span.removed { color: red; text-decoration: line-through; }
/* ]]> */
</style>
</head>
<body>
<div class="group">
<H1>Thoughts on Implementing <span class=code>errno</span> as a Macro</h1>

<table class="heading">
<tr>
  <td class="descr">WG 14 Document number</td><td class="value">N1308</td>
</tr>
<tr>
  <td class="descr">WG 21 Document number</td><td class="value">N2604=08-0114</td>
</tr>
<tr>
  <td class="descr">Date</td><td class="value">2008-04-25</td>

</tr>
<tr>
  <td class="descr">Projects</td><td class="value">Programming Languages C &amp; C++</td>
</tr>
<tr>
  <td class="descr">Reference</td><td class="value">ISO/IEC IS 9899:1999</td>
</tr>
<tr>
  <td class="descr">Reference</td><td class="value">ISO/IEC IS 14882:2003(E)</td>
</tr>
<tr>
  <td class="descr">Reply to</td><td class="value">Nick Stoughton</td>

</tr>
<tr>
  <td class="emptydescr"></td><td class="value">USENIX Association</td>
</tr>
<tr>
  <td class="emptydescr"></td><td class="value">nick@usenix.org</td>
</tr>
</table>
<p style="clear:both"></p>
</div>
<h2>Background</h2>
<p>
SC22 WG14 N1257 describes an inconsistency in the wording for
&lt;errno.h&gt;. In p1, &lt;errno.h&gt; defines several macros. In p2 "The macros
are ... <span class=code>errno</span>". But later in p2 "It is unspecified whether <span class=code>errno</span> is a
macro or an identifier declared with external linkage." So is <span class=code>errno</span> a macro
or not?
<p>
If we consider existing practice very old implementations, and some current embedded
implmentations, have <span class=code>errno</span> as a simple integer variable. On the other hand, any
implementation that has support for some form of multi-threading implements <span class=code>errno</span> as
a macro, expanding into a different modifiable lvalue for each thread. It could also, 
potentially, be implemented using some form of thread local storage.
<p>
N1257 took these factors into consideration, and proposed wording that removed the ambiguity but
preserved all existing implementations (no quiet changes).
The paper was considered during the Kona meeting, and N1270 (the Kona minutes) stated
<blockquote>
C++ is requiring that they be macros. It would not be a bad thing if we
did likewise. Make it required that <span class=code>errno</span> is a macro, rather than unspecified.
</blockquote>
<p>
The current wording in SC22 WG21 N2588 (the C++ Working Draft), states:
<blockquote>
The header &lt;cerrno&gt; is described in (Table 29). Its contents are the same as the POSIX header &lt;errno.h&gt;, except that
<span class=code>errno</span> shall be defined as a macro. [ Note: The intent is to remain in close alignment with the POSIX standard. -end
note ]
</blockquote>
<p>
In turn, POSIX defines <span class=code>errno</span> as
<blockquote>
The &lt;errno.h&gt; header shall provide a declaration or definition for <span class=code>errno</span>. The symbol <span class=code>errno</span> shall
expand to a modifiable lvalue of type int. It is unspecified whether <span class=code>errno</span> is a macro or an
identifier declared with external linkage. If a macro definition is suppressed in order to access an
actual object, or a program defines an identifier with the name <span class=code>errno</span>, the behavior is undefined.
</blockquote>
<p>
These are the same words proposed in WG14 N1257. The stated goal (in a note) of C++ is to align
with POSIX, but POSIX does not require that <span class=code>errno</span> be a macro.
<h2>The Way Forward</h2>
There are two possible solutions to the inconsistencies that exist both within the C standard
and between the C, C++ and POSIX standards.
<ol>
<li>Use the words in N1257 to fix the inconsistency in C. Use the words suggested below to modify the
C++ draft to align it with both POSIX and C, both of which are already stated goals in C++.
<li>Draft new words to force <span class=code>errno</span> to be a macro in C. Use similar words to modify POSIX.
<b>Note</b> although POSIX is undergoing revision at this time, it has completed FCD and is going to DIS
within the next month or two. Such a change would need to wait for the next revision. 
</ol>
<p>
For these reasons, this paper, while requested by WG 14, is being submitted to both WG14 and WG21
and contains proposed changes to the C++ working draft. It also seeks to try to handle any potential
conflict between C++ and POSIX over the content of the POSIX header &lt;errno.h&gt;.
<h2>Proposed Wording for C++</h2>
<p>

19.3 Error numbers [errno]
<p>
The header &lt;cerrno&gt; is described in (Table 29). 
Its contents are <span class=removed>the same as</span><span class=added>aligned with</span>
the POSIX header &lt;errno.h&gt;<span class=removed>, except that
<span class=code>errno</span> shall be defined as a macro</span><span class=added>; any
conflict between the requirements described here and the ISO POSIX standard is unintentional. This
standard defers to the POSIX standard</span>.
[ Note: The intent is to remain in close alignment with the POSIX standard. -end
note ]

Table 29: Header <cerrno> synopsis
<table>
<tr><td>Type</td><td>Name(s)</td></tr>
<tr><td><b>Macros:</b></td> <td>ECONNREFUSED</td> <td>EIO</td> <td>ENODEV</td> <td>ENOTEMPTY</td> <td>ERANGE</td></tr>
<tr><td></td><td>E2BIG</td> <td>ECONNRESET</td> <td>EISCONN</td> <td>ENOENT</td> <td>ENOTRECOVERABLE</td> <td>EROFS</td></tr>
<tr><td></td><td>EACCES</td> <td>EDEADLK</td> <td>EISDIR</td> <td>ENOEXEC</td> <td>ENOTSOCK</td> <td>ESPIPE</td></tr>
<tr><td></td><td>EADDRINUSE</td> <td>EDESTADDRREQ</td> <td>ELOOP</td> <td>ENOLCK</td> <td>ENOTSUP</td> <td>ESRCH</td></tr>
<tr><td></td><td>EADDRNOTAVAIL</td> <td>EDOM</td> <td>EMFILE</td> <td>ENOLINK</td> <td>ENOTTY</td> <td>ETIME</td></tr>
<tr><td></td><td>EAFNOSUPPORT</td> <td>EEXIST</td> <td>EMLINK</td> <td>ENOMEM</td> <td>ENXIO</td> <td>ETIMEDOUT</td></tr>
<tr><td></td><td>EAGAIN</td> <td>EFAULT</td> <td>EMSGSIZE</td> <td>ENOMSG</td> <td>EOPNOTSUPP</td> <td>ETXTBSY</td></tr>
<tr><td></td><td>EALREADY</td> <td>EFBIG</td> <td>ENAMETOOLONG</td> <td>ENOPROTOOPT</td> <td>EOVERFLOW</td> <td>EWOULDBLOCK</td></tr>
<tr><td></td><td>EBADF</td> <td>EHOSTUNREACH</td> <td>ENETDOWN</td> <td>ENOSPC</td> <td>EOWNERDEAD</td> <td>EXDEV</td></tr>
<tr><td></td><td>EBADMSG</td> <td>EIDRM</td> <td>ENETRESET</td> <td>ENOSR</td> <td>EPERM</td> <td><span class=removed>errno</span></td></tr>
<tr><td></td><td>EBUSY</td> <td>EILSEQ</td> <td>ENETUNREACH</td> <td>ENOSTR</td> <td>EPIPE</td></tr>
<tr><td></td><td>ECANCELED</td> <td>EINPROGRESS</td> <td>ENFILE</td> <td>ENOSYS</td> <td>EPROTO</td></tr>
<tr><td></td><td>ECHILD</td> <td>EINTR</td> <td>ENOBUFS</td> <td>ENOTCONN</td> <td>EPROTONOSUPPORT</td></tr>
<tr><td></td><td>ECONNABORTED</td> <td>EINVAL</td> <td>ENODATA</td> <td>ENOTDIR</td> <td>EPROTOTYPE</td></tr>
</table>
SEE ALSO: ISO C subclause 7.1.4, 7.2, Amendment 1 subclause 4.3.
<p><span class=added>
The &lt;cerrno&gt; header also provides a declaration or definition for <span class=code>errno</span>. The symbol
<span class=code>errno</span> shall expand to a modifiable lvalue of type int. It is unspecified
whether <span class=code>errno</span> is a macro or an identifier declared with external
linkage. If a macro definition is suppressed in order to access an
actual object, or a program defines an identifier with the name <span class=code>errno</span>,
the behavior is undefined.
<p>
The value of <span class=code>errno</span> is zero at program start-up, but is never set to zero
by any library function. The value of <span class=code>errno</span> may be set to nonzero
by a library function call whether or not there is an error, provided
the use of <span class=code>errno</span> is not documented in the description of the function
in this International Standard.
</span>
<h2>Proposed wording for C</h2>
<p>
The following is drawn from the wording suggested in WG14 N1257, and is repeated here for
clarity with minor editorial changes. In addition, this is now presented as change marked 
differences (using strikethrough etc)
to make it easier to understand the change.
<p>
In 7.5, change para 2 to read:
<p>
The macros are
<br>
EDOM
<br>
EILSEQ
<br>
ERANGE
<br>
which expand to integer constant expressions with type int, distinct positive values, and
which are suitable for use in #if preprocessing directives<span class=added>.</span><span class=removed>; and
<br>
<span class=code>errno</span>
<br>
which
</span>
<span class=added>The &lt;errno.h&gt; header also provides a declaration or definition for <span class=code>errno</span>. The symbol
<span class=code>errno</span></span>
expands to a modifiable lvalue<sup>175)</sup> that has type int, the value of which is set to a
positive error number by several library functions. It is unspecified whether <span class=code>errno</span> is a
macro or an identifier declared with external linkage. If a macro definition is suppressed
in order to access an actual object, or a program defines an identifier with the name
<span class=code>errno</span>, the behavior is undefined.
</body>
</html>
