<html>
<head>
<link rel="Home" href="../" title="JdeBP's WWW site" />
<link rel="Up" href="index.html" title="Proposals" />
<link rel="Stylesheet" type="text/css" href="proposals.css" title="Proposals default style" />
<title>A proposal for eliminating the underscore madness that library writers have to suffer</title>
</head>
<body>
	<table summary="This table provides identifying information for this document.">
		<tr>
			<th>Doc. No.:</th>
			<td>PL22.16/12-0090<br />
				WG21/N3400</td>
		</tr>
		<tr>
			<th>Date:</th>
			<td>2012-09-21</td>
		</tr>
		<tr>
			<th>Reply to:</th>
			<td>Jonathan de Boyne Pollard</td>
		</tr>
	</table>
<h1 class="ruled">A proposal for eliminating the underscore madness that library writers have to suffer</h1>

<div class=sidebar>
<link rel="Contents" href="#Contents" title="Table of contents" />
<ul>
<li><p><a href="Background">Rationale and background</a></p></li>
<li><p><a href="Proposal">The proposal</a></p></li>
<li><p><a href="Practice">What happens in practice</a></p></li>
</ul>
</div>

<p>
This is a proposal for eliminating the necessity for the providers of
user-supplied libraries and standard C/C++ libraries to use double underscores
on practically every name that is internal to the implementation, even though
the C and C++ scoping rules mean that those names are not in scope in client
code.  It does this by a small modification to the rules for the pre-processing
phases of translation, making the pre-processor do less than it did before.
In other words: This proposal defines rules for when and where specific
preprocessor functionality, the expansion of macros, is <em>turned off</em>.
</p>

<link rel="Section" href="#Background" title="Rationale and background" />
<h2 class="ruled" id="Background">
Rationale and background
</h2>

<link rel="Section" href="#Scope" title="Scope of this proposal" />
<h3 class="ruled" id="Scope">
Scope of this proposal
</h3>

<p>
This proposal addresses a very specific, but long standing problem:  Library
implementors have to employ double underscores in their headers in order to
avoid their code being potentially broken by macros defined in code that
uses the library.  For example, here's some code from a real world application
library header (taken from 
<a href="http://mat.univie.ac.at./~coconut/coconut-environment/">the CONONUT API</a>)
that ensures that macros named <code>s</code>, <code>S</code>, <code>b</code>,
and <code>def</code> don't break the library header:
</p>
<blockquote><pre class="cpp-source">template &lt;class _S&gt;
inline void control_data::assign(
	const std::string &amp; __s, 
	const matrix&lt;_S&gt;* &amp; __b, 
	const matrix&lt;_S&gt;* __def
) const
{
	retrieve(__s, __b, __def);
} </pre></blockquote>

<p>
The problems with macros and libraries is threefold:
</p>

<ul>

<li><p> <strong>The code can get illegible very quickly.</strong>
C and C++ heavily overuse punctuation anyway, and the addition of underscores to
practically every single not-for-external-use identifier in a library header
only exacerbates the problem.  The example above is, if anything, a mild one.
</p>

<li><p> <strong>Every library has to do this.</strong>
This isn't just a problem for the C and C++ standard libraries that accompany
the compiler.  It's a problem for every <em>application</em> library, too, be
that a first-party or a third-party application library.  This
is because it is a general problem caused by the interaction between
<em>any</em> user-defined macros and <em>any</em> library headers.
</p>

<li><p> <strong>This technique is, strictly speaking, not allowed for
user-supplied libraries.</strong>
The C and C++ standard libraries can use such names beginning with double
underscores because those names are reserved to the implementation "for any use"
(i.e. including for use as a macro).  In other words, the C and C++ standards
provide this solution, but <em>only</em> for <em>implementation-supplied</em>
libraries, not for first-party and third-party user-supplied libraries.
</p>

</ul>

<p>
This proposal is intended to enable application library implementors (and
indeed standard library implementors) to write code such as the following
&mdash; which is what they would <em>like</em> to write &mdash; in their headers and
have it be unaffectable by preprocessor macros defined by the library clients:
</p>
<blockquote><pre class="cpp-source">template &lt;class S&gt;
inline void control_data::assign(
	const std::string &amp; s, 
	const matrix&lt;S&gt;* &amp; b, 
	const matrix&lt;S&gt;* def
) const
{
	retrieve(s, b, def);
} </pre></blockquote>

<link rel="Section" href="#PriorFailures" title="Learning from prior failures" />
<h3 class="ruled" id="PriorFailures">
Learning from prior failures
</h3>

<p>
Previous failed attempts to solve this problem include Bjarne Stroustrup's
<code>#scope</code> proposal, that was proposed in 2004 but that never got off
the ground.  Its problems were twofold:
<p>

<ul>

<li><p> <strong>It was far too academic a solution.</strong>
The proposal introduced a general purpose mechanism, that provided a concept of
scoping for pre-processor macros and that solved the difficulties being
encountered by real world programmers as just <em>one</em> of the things that it
could do, instead of a mechanism specifically engineered to the problems actually at
hand and no more.  People got bogged down in what <em>else</em> the mechanism
could be made to do, and all of its various ramifications that were not central
to the issue at hand.
</p>

<li><p> <strong>It introduced several new pre-processor directives.</strong>
In addition to <code>#scope</code> and <code>#endscope</code> it included
<code>#import</code> and <code>#export</code>, which then became
<code>#imports</code> and <code>#exports</code>.  People became bogged down in
what even to <em>call</em> the new preprocessor directives.
</p>

</ul>

<p>
Therefore, this proposal adheres to several principles:
</p>

<ul>

<li><p> <strong>No new preprocessing directives are introduced.</strong>
There's no potential for the Golgafrinchams to fail to invent the wheel because
they cannot decide what colour it should be.  A side benefit of this is that
library implementors do not need to worry about how to properly employ new
directives in their headers to activate a new mechanism.
</p>

<li><p> <strong>No general-purpose mechanism is proposed.</strong>
This mechanism very specifically addresses the problem at hand and the problem
at hand only.  This proposal, after all, for the benefit of people who <em>don't
want the preprocessor mucking things up</em>; and who indeed would rather it
were not there at all for their purposes.  Expanding the feature set of the
preprocessor by providing more knobs to turn is not the goal.  Making the
preprocessor <em>less</em> intrusive is.
</p>

<li><p> <strong>No whiteboard-only ideas are included.</strong>
I have actually implemented this proposal, constructing and using a preprocessor
that employs its mechanism.  My implementation experience is related in a later
section.
</p>

</ul>

<link rel="Section" href="#Unaffected" title="Practices that are unaffected" />
<h3 class="ruled" id="Unaffected">
Practices that are unaffected
</h3>

<p>
Some additional goals of this proposal are that various implementation
practices should continue to work with this mechanism in place, even though
they rely upon interaction between library headers and library clients.  (This was
a significant problem with the "scopes" proposal.  Scoping necessitates ways
of becoming visible outwith a scope, and hence yet more mechanisms bolted on
to provide those ways.)
</p>

<ul>

<li><p> <strong>Interface-specification macros should not be affected.</strong>
Many libraries have mechanisms whereby client code sets macros before including
the library headers, to specify the API level that the library is expected to
provide.  Such macros are especially common with platform libraries and include
things like:
<ol>
<li>
<a href="http://msdn.microsoft.com/en-gb/library/aa383745%28v=vs.85%29.aspx">
the <code>WIN32_LEAN_AND_MEAN</code> and <code>NO</code><i>xxx</i> macros</a>
in the Microsoft Windows platform API
<li>
<a href="http://pubs.opengroup.org/onlinepubs/007904975/functions/xsh_chap02_02.html">
the <code>_POSIX_C_SOURCE</code> and <code>_XOPEN_SOURCE</code> macros</a>
in the POSIX platform API
</p>
</ol>
<p>This proposal was designed not to affect the function of such mechanisms.</p>

<li><p> <strong>Application libraries should still be able to use both
<code>&lt;</code>&nbsp;<code>&gt;</code> 
and
<code>"</code>&nbsp;<code>"</code>
forms of inclusion.</strong>
Unfortunately, some application library writers think that they are supplying
headers, and so use <code>&lt;</code>&nbsp;<code>&gt;</code> form inclusion all
over the place, whilst others think that they are supplying source files and so
use <code>"</code>&nbsp;<code>"</code> form inclusion all over the place.  The
form of inclusion chosen must not affect the operation of the mechanism.
</p>


<li><p> <strong>Feature-test and parameterization macros should not be
affected.</strong>
The most obvious examples of this are things like <code>FLT_MAX</code> from the
standard library itself.  This should not be broken.  So &mdash; for example
&mdash; headers should not be automatically assigned namespaces, or scopes,
from which macro definitions don't escape by default.  Such library-defined
macros should continue to be usable in library client code without alteration
to that code.
</p>

</ul>

<link rel="Section" href="#Proposal" title="The proposal" />
<h2 class="ruled" id="Proposal">
The proposal
</h2>

<link rel="Section" href="#Summary" title="The proposal in brief" />
<h3 class="ruled" id="Summary">
The proposal in brief
</h3>

<p>
Every macro has an associated priority.  Every source file and header has an
associated priority.  A macro with a lower priority is not expanded when it
occurs as an identifier in the non-preprocessing parts of a source file or
header of a higher priority.  Priority levels are assigned by the
implementation, but are expected at minimum to distinguish amongst the
user program, first-party and third-party user-supplied libraries, and
implementation standard C++ library.
</p>

<p>
Given that the macro priority mechanism gives a <em>stronger</em> guarantee
about macro invasion to a <em>wider</em> range of library writers (i.e. more
than just standard C++ library writers), we can even do away with some of the
constraints intended to avert these problems but that only apply to the standard
C++ library.
Although it should be noted that we still need to separately guarantee standard
library writers that preprocessor directives that employ standard macros (e.g.
<code>#if&nbsp;INT_MAX&nbsp;&lt;&nbsp;32768&hellip;</code>)
won't be broken.
</p>


<link rel="Section" href="#Standardese" title="Proposed standards text" />
<h3 class="ruled" id="Standardese">
Proposed standards text
</h3>

<p>
(Square bracketed ellipses, as per the normal editorial convention, here denote
parts of the text that do not change and have been omitted for brevity.)
</p>

<p>
Append an extra condition to &sect;16.3 &para;9 and &para;10:
</p>

<blockquote class="standard-text">
<ol start="9">
<li><p>
A preprocessing directive of the form</p>
<blockquote><pre># define identifier replacement-list new-line</pre></blockquote>
<p>
defines an <em>object-like macro</em> that causes each subsequent instance, 
<strong>that satisfies the priority rules (&sect;16.3.6),</strong> 
of the macro name<sup>151</sup> to be replaced by the replacement list of
preprocessing tokens that constitute the remainder of the
directive<sup>152</sup>. 
<i>[&hellip;]</i>
</p></li>
<li><p>
A preprocessing directive of the form <i>[&hellip;]</i>
defines a <em>function-like macro</em> with parameters, <i>[&hellip;]</i> Each
subsequent instance, 
<strong>that satisfies the priority rules (&sect;16.3.6),</strong> 
of the function-like macro name followed by a <code>(</code> as the next
preprocessing token introduces the sequence of preprocessing tokens that is
replaced by the replacement list in the definition (an invocation of the macro).
<i>[&hellip;]</i>
</p></li>
</ol>
</blockquote>

<p>
and to &sect;16.3.4 &para;1:
</p>

<blockquote class="standard-text">
<ol start="1">
<li><p>
After all parameters in the replacement list have been substituted and # and ##
processing has taken place, all placemarker preprocessing tokens are removed.
Then the resulting preprocessing token sequence is rescanned, along with all
subsequent preprocessing tokens of the source file, for more macro names to
replace, <strong>subject to the priority rules (&sect;16.3.6).</strong> 
</p></li>
</ol>
</blockquote>

<p>
Add a new section, &sect;16.3.6:
</p>

<blockquote class="standard-text">
<h3> &sect;16.3.6 Macro expansion priority</h3>
<ol start="1">
<li><p>
Every header (&sect;17.6.1.2) and source file &mdash; included (&sect;16.2) or
otherwise &mdash; in the translation unit is considered to have an associated
<em><defn>macro priority</defn></em>.  
These priorities are determined in an implementation defined manner
<sup><a class="footnote" href="#fn1">footnote 1</a></sup>
from the place where the source file or header exists.  <em>[Note:</em>  The
method of inclusion &mdash; 
<code>&lt;</code>&nbsp;<code>&gt;</code> 
versus
<code>"</code>&nbsp;<code>"</code>
&mdash; does not affect priority.  Only the place where the implementation's
search actually finds the source file or header does.
<sup><a class="footnote" href="#fn2">footnote 2</a></sup>
<em>&mdash; end note]</em>
The priorities of C++ and C standard library headers must be greater than the
priorities of any program source file or non-library header.
<sup><a class="footnote" href="#fn3">footnote 3</a></sup>
</p>
<p id="fn1"><small>
<sup>footnote 1</sup>  It is recommend that implementations at minimum employ
three priorities, for (in lowest to highest priority order) user program source
files, first-party and third-party user-supplied libraries, and
implementation-supplied libraries.
This standard does not specify that priorities be numeric, merely that they are
ordered.
</small></p>
<p id="fn2"><small>
<sup>footnote 2</sup>  The notion of "place" is implementation defined, of course.
It isn't a requirement that the same single source file or header found by
<code>&lt;</code>&nbsp;<code>&gt;</code> form inclusion via one search path and
by <code>"</code>&nbsp;<code>"</code> form inclusion via a different search path
be considered to be in the same "place" and thus be assigned the same macro
priority.  An implementation might define, for example, that inclusion of
<code>"dir/a"</code> by header <code>&lt;foo&gt;</code> is a logically different
"place" to inclusion of the same source file by some other pathname directly or
from some other header with a different priority.  Priority is not dependent
from inclusion <em>form</em> but may well depend from inclusion <em>route</em>.
</small></p>
<p id="fn3"><small>
<sup>footnote 3</sup>  Implementations are granted the leeway to not have all of
the C++ and C standard library headers at the same priority, and to have other
source files and headers at the same or higher priority than the standard
library headers.  Extra implementation-defined headers for freestanding
implementations (&sect;17.6.1.3) are but one example of where an implementation
might require the same or a higher priority than the standard headers.  This
constraint is simply to rule out perverse implementations that might otherwise
decide to make the standard headers equal to or even lower priority than user
program code.
</small></p>

</li>
<li><p>
Every macro is also considered to have an associated priority.  The priority of
a macro is the priority of the header or source file in which it was defined
(&sect;16.3).  If a macro is redefined in a header or source file of higher
priority, its priority is raised accordingly.  Otherwise a redefinition has no
effect on priority.  <em>[Note:</em> Priorities are not, in other words, lowered
by redefinitions. <em>&mdash; end note]</em>  The priorities of predefined
macros and other macros not defined by headers or source files are
implementation defined.
<sup><a class="footnote" href="#fn4">footnote 4</a></sup>
</p></li>
<p id="fn4"><small>
<sup>footnote 4</sup>  It is recommended that implementations give the standard
predefined macros the same priority as macros defined in the standard library
headers, and any user-defined macros (not defined by headers or source files)
the same priority as macros defined in user source files.
</small></p>
<li><p>
The priorities of macros, headers, and source files govern whether macros are
considered for expansion when their names occur as identifiers outside of
pre-processing directives.  <em>[Note:</em> Priorities do not affect
pre-processing directives at all. <em>&mdash; end note]</em>  
A macro of priority <code>N</code> is only considered for expansion (in such
contexts) if the header or source file in which its name occurs is lower than or
the same as <code>N</code>.  The macro is not expanded if the header's or source
file's priority is higher.
</p></li>
<li><p>
The replacement text of a macro, after it has been expanded, is considered to be
at the same priority as the source file or header in which the macro expansion
process began.
</p></li>
<li><p>
<em>[Example:</em> A translation unit comprises one header and two source files:
<blockquote><pre class="cpp-source">// third-party user-supplied library source file "lib.h"
#define M ... /* Identifier becomes the ... token. */
int f (int a); // ok: no expansion of any lower-priority macros named "f" or "a"
int g (int a, M); // ok: "M" is expanded as intended

// user program source file
#define f ... /* Identifier becomes the ... token. */
#define a ... /* Identifier becomes the ... token. */
#define basic_string ... /* Identifier becomes the ... token. */

#include &lt;string&gt; // ok: macro "basic_string" has lower priority than the header
#include &lt;lib.h&gt;

#define M ... /* replaces M, but does not lower its priority */

int h() 
{ 
	f();	// error: "f" is expanded because
		// the macro has the same priority as this source file
	M();	// error: "M" is expanded because
		// the macro has a higher priority than this source file
}</pre></blockquote>
<em>&mdash; end example]</em>
</p></li>
</ol></blockquote>

<p>
We can also curtail the prevously sweeping prohibition of &sect;17.6.4.3.1
&para;1:
</p>

<blockquote class="standard-text">
<ol start=1>
<li><p>
A translation unit that includes a standard library header shall not
<code>#define</code> or <code>#undef</code> <strong>macro</strong>
names defined in any standard library header.</s>
</p>
</ol>
</blockquote>

<link rel="Section" href="#Practice" title="Practice" />
<h2 class="ruled" id="Practice">
What happens in practice
</h2>

<p>
I have implemented a preprocessor that does this, and experimented with what
effects it has.  There is a limited amount of prior art in other
implementations, too.
</p>

<link rel="Section" href="#PriorArt" title="Prior art in other implementations" />
<h3 class="ruled" id="PriorArt">
Prior art in other implementations
</h3>

<p>
Some implementations <em>already</em> classify headers and included source
files by where they are found.
</p>

<p>
GCC, for example, has a two-level classification of user source files and
<a href="http://gcc.gnu.org/onlinedocs/cpp/System-Headers.html">
system headers</a>,
dependent from what directory a file is found in.  It takes special actions for
things defined in "system" headers.  This dichotomy isn't enough to make
<em>application</em> library headers safe from application-defined macros, since
both fall on the "user" side of the dividing line.  Nor does it extend to taking
special action in "system" headers for things defined in "user" files.  But it
is a fair start.
</p>

<p>
My first implementation even employed such a user/system two-level priority
system.  It wasn't enough in practice.  Ironically, it was pointing the
implementation at GNU libc and pretending to be GCC (by defining the same
predefined macros as it does) that revealed this.
</p>

<link rel="Section" href="#Priorities" title="Choosing priorities" />
<h3 class="ruled" id="Priorities">
Choosing priorities
</h3>

<p>
Experience led to the multiple-priority-level scheme as specified earlier.  I
eventually settled upon five priorities.
I used this mechanism to preprocess some programs using both the OpenWatcom
libraries on a Win32 system and the GNU libc and GCC libraries on a Linux
system.
The priorities were (in lowest to highest order):
</p>

<blockquote><dl>
<dt>application</dt>
<dd>
Source files for ordinary application code.  In other words: everything found in
or relative to the current directory, or in or relative to the same directory as
an application source file including it.
</dd>
<dt>application libraries</dt>
<dd>
Headers for first-party and third-party applications libraries.  The Xerces C++
library is an example of a third-party applications library.
</dd>
<dt>wrapper library</dt>
<dd>
Headers for special wrapper libraries.  This was an extra layer required for
GNU libc and GCC, more on which in a moment.
</dd>
<dt>platform API library</dt>
<dd>
Headers for the platform API library, such as <code>&lt;unistd.h&gt;</code>,
<code>&lt;os2.h&gt;</code>, and <code>&lt;windows.h&gt;</code>.
</dd>
<dt>C++ language standard library</dt>
<dd>
Headers for the C++ standard library, such as <code>&lt;string&gt;</code>,
<code>&lt;sstream&gt;</code>, and <code>&lt;stdio.h&gt;</code>.
</dd>
</dl></blockquote>

<p>
The "places", that header files are found in, map to priorities as follows:
</p>

<table style="border:4px ridge black; padding:0.2em; margin:0.5em;" width="100%" rules=all>
<caption>Places and priorities for OpenWatcom (with target NT)</caption>
<thead>
<colgroup width="20%"></colgroup>
<colgroup width="80%"></colgroup>
<tr>
	<th>priority</th>
	<th>place</th>
</tr>
</thead>
<tbody>
<tr valign=top>
	<td>application</td>
	<td>everything found relative to the current directory, either directly
	or indirectly</td>
</tr>
<tr valign=top>
	<td>application libraries</td>
	<td>everything found by prefixing a directory given by a <code>-I</code>
	option or listed in the <code>%INCLUDE%</code> or
	<code>%NT_INCLUDE%</code> environment variables, except for places
	explicitly given in other rows of this table</td>
</tr>
<tr valign=top>
	<td>wrapper library</td>
	<td>(none)</td>
</tr>
<tr valign=top>
	<td>platform API library</td>
	<td>everything found by prefixing
	<ul>
	<li><code>%WATCOM%/h/nt
	</ul>
	</td>
</tr>
<tr valign=top>
	<td>C++ language standard library</td>
	<td>everything found by prefixing
	<ul>
	<li><code>%WATCOM%/h
	</ul>
	</td>
</tr>
</tbody>
</table>

<table style="border:4px ridge black; padding:0.2em; margin:0.5em;" width="100%" rules=all>
<caption>Places and priorities for Microsoft Visual C++</caption>
<thead>
<colgroup width="20%"></colgroup>
<colgroup width="80%"></colgroup>
<tr>
	<th>priority</th>
	<th>places</th>
</tr>
</thead>
<tbody>
<tr valign=top>
	<td>application</td>
	<td>everything found relative to the current directory, either directly
	or indirectly</td>
</tr>
<tr valign=top>
	<td>application libraries</td>
	<td>everything found by prefixing a directory given by a
	<code>-I</code> option or listed in the <code>%INCLUDE%</code>
	environment variable, except for places explicitly given in other rows
	of this table</td>
</tr>
<tr valign=top>
	<td>wrapper library</td>
	<td>(none)</td>
</tr>
<tr valign=top>
	<td>platform API library</td>
	</td>
	<td>everything found by prefixing
	<ul>
	<li><code>$WindowsSdkDir/include</code>
	</ul>
	</td>
</tr>
<tr valign=top>
	<td>C++ language standard library</td>
	</td>
	<td>everything found by prefixing
	<ul>
	<li><code>$VCInstallDir/include</code>
	</ul>
	</td>
</tr>
</tbody>
</table>

<table style="border:4px ridge black; padding:0.2em; margin:0.5em;" width="100%" rules=all>
<caption>Places and priorities for GCC</caption>
<thead>
<colgroup width="20%"></colgroup>
<colgroup width="40%"></colgroup>
<colgroup width="40%"></colgroup>
<tr>
	<th rowspan=2>priority</th>
	<th colspan=2>places</th>
</tr>
<tr>
	<th>GCC on Linux with GNU libc</th>
	<th>Cygwin GCC</th>
</tr>
</thead>
<tbody>
<tr valign=top>
	<td>application</td>
	<td colspan="2">everything found relative to the current
	directory, either directly or indirectly</td>
</tr>
<tr valign=top>
	<td>application libraries</td>
	<td colspan="2">everything found by prefixing a directory given by a
	<code>-I</code> option (from which GCC automatically eliminates the
	places given in other rows in this table)</td>
</tr>
<tr valign=top>
	<td>wrapper library</td>
	<td colspan=2>some things found by prefixing
	<ul>
	<li><code>$prefix/$target/$version/include</code>
	</ul>
	</td>
</tr>
<tr valign=top>
	<td>platform API library</td>
	<td>(none)</td>
	<td>everything found by prefixing
	<ul>
	<li><code>/usr/include/w32api</code>
	</ul>
	</td>
</tr>
<tr valign=top>
	<td>C++ language standard library</td>
	<td>everything found by prefixing
	<ul>
	<li><code>/usr/include/c++/$version</code>
	<li><code>/usr/include/c++/$version/$target</code> 
	<li><code>/usr/include</code>
	</ul>
	some things found by prefixing
	<ul>
	<li><code>$prefix/$target/$version/include</code>
	</ul>
	</td>
	<td>everything found by prefixing
	<ul>
	<li><code>$prefix/$target/$version/include/c++</code>
	<li><code>/usr/include</code>
	</ul>
	some things found by prefixing
	<ul>
	<li><code>$prefix/$target/$version/include</code>
	</ul>
	</td>
</tr>
</tbody>
</table>

<link rel="Section" href="#Experience" title="Things that implementation experience teaches" />
<h3 class="ruled" id="Experience">
Things that implementation experience teaches
</h3>

<p>
A four-level scheme, for application, application library, target platform
library, and standard C++ library, would seem to be enough.  GCC and GNU libc
proved this wrong.  GCC has two sets of "special" headers, that it
unfortunately mashes together in a single directory:
</p>
<ul>
<li><p><strong>GCC headers that GNU libc depends from</strong>
Examples of this include <code>&lt;stdarg.h&gt;</code>, which provides things
such as <code>__gnuc_va_list</code> to GNU libc <code>&lt;libio.h&gt;</code>
(and thence GNU libc <code>&lt;stdio.h&gt;</code>).
These headers need to have <em>language library</em> macro priority, because the
macros that they define have to be expandable in language library headers.
</p>
<li><p><strong>GCC headers that wrap GNU libc</strong>
Examples of this include <code>&lt;limits.h&gt;</code>, which wraps around the
GNU libc <code>&lt;limits.h&gt;</code>.  
These headers need to have <em>wrapper library</em> macro priority, because the
macros that they define <em>must not</em> expand in language library headers.
(Indeed, the wrapper <code>&lt;limits.h&gt;</code> provided by GCC goes to some
effort to ensure that it overrides the GNU libc macros and not the other way
around.)  Giving them a priority lower than that of the language library also
makes it simpler to define what <code>#include_next</code> in those headers
does.  (It acts just as <code>#include</code>, except that it ignores all places
that have a lower or equal priority to the including file.)
</p>
</ul>

<p>
<a class="footnote" href="#fn2">The second footnote to &sect;16.3.6</a>
may seem somewhat obscure.  This is because it's condensing a fairly complex 
subject into a handful of sentences.  It has three forces driving it:
</p>
<ul>
<li><p>
It is <em>not</em>the intent to require implementations to figure out whether
filesystem aliasing mechanisms such as hard and symbolic links cause different
filenames to actually end up at the same physical file in the filesystem.
</p>
<li><p>
Implementations that give <code>"</code>&nbsp;<code>"</code> form inclusion the
semantics of "also search the directory containing the including file" can
simply define that any source file found that way will have the same priority as the
file including it, without having to worry about whether the relative pathname
actually ends up in a directory that maps to a different priority.
Implementations are given the leeway to consider each directory subtree on a
search path to be entirely disjoint from any other subtree on the search path.
Implementations need only look at the path prefix taken from the search path,
calculating priority from that, and not take into account any relative pathname
in the included file specification.
</p>
<li><p>
As mentioned earlier, some library writers expect to use
<code>&lt;</code>&nbsp;<code>&gt;</code> form inclusion all over the place,
whilst others use <code>"</code>&nbsp;<code>"</code> form inclusion all over
the place.  So the inclusion form cannot be used to select between "same
priority" and "higher priority", as an early version of my implementation did.
<p>
</ul>

<p>
Such leeway for self-relative inclusion is desirable in the case of library
incest.  To construct a hypothetical example:  Posit a <em>target platform</em>
priority library that has a header <code>&lt;windows.h&gt;</code> that includes
<code>"../stddef.h"</code> in order to incorporate various standard C++ library
internals within itself, because it "knows" that the directory for the language's
standard library is the parent of the directory for the target platform library.
Even though that therefore is the same actual file as
<code>&lt;stddef.h&gt;</code>, which has a higher <em>standard C++</em>
priority, every macro from the <code>"../stddef.h"</code> inclusion will have
the <em>target platform</em> priority, because the inclusion route by which it
was reached doesn't involve the standard C++ library headers.
</p>

<p>
Put another way: The <code>stddef.h</code> file effectively becomes a new header
belonging to the target platform library, distinct from the standard C++ header of
the same spelling, because the platform library uses self-relative inclusion to
include it.  Implementations are under no more obligation than to note that both
<code>&lt;windows.h&gt;</code> and <code>"../stddef.h"</code> were both found by
prefixing <code>/usr/include/w32api</code>, whereas
<code>&lt;stddef.h&gt;</code> is found by prefixing <code>/usr/include</code>.
Priority can be determined entirely by what part of the inclusion search path is
used, without reference to the additional <code>"../"</code> relative directory
prefix within the inclusion specification.
</p>

<p>
The rule about never lowering priority originates in the realization that macro
priority limits the <em>effective grasp</em> of a macro, and that redefinition
by a lower-priority header should not <em>narrow</em> the effective grasp of a
macro that was already defined at a higher priority with a larger grasp.  Higher
priority headers would be expecting that macro to remain effective once defined
by them.
</p>

<p>
The drastic curtailment of &sect;17.6.4.3.1 &para;1 comes from the experience
that the following program is no longer, with a macro priority system in place,
capable of breaking the standard C++ library.  Indeed, the pre-processed source
compiles cleanly with GCC and works.
</p>
<blockquote><pre class="cpp-source">#define std ... /* Widely-used identifier becomes the ... token. */
#include &lt;cstdio&gt;
#undef std
int main ()
{
	std::puts("Hello there!");
	return 0;
}</pre></blockquote>

<hr>
<link rel="Author" href="http://homepage.ntlworld.com/jonathan.deboynepollard/author.html" />
<link rel="Copyright"
href="http://homepage.ntlworld.com/jonathan.deboynepollard/Proposals/copyright.html" />
<p><font size=-2>
&copy; 
<a href="http://homepage.ntlworld.com/jonathan.deboynepollard/Proposals/copyright.html">Copyright</a> 2012
<a href="http://homepage.ntlworld.com/jonathan.deboynepollard/author.html">Jonathan de Boyne Pollard</a>.
"Moral" rights asserted.
</font></p>
<p><font size=-2>
Permission is hereby granted to copy and to distribute this WWW page in its
original, unmodified form as long as its last modification datestamp
information is preserved.
Further permission is hereby granted to copy and to distribute this WWW page
for the purposes of C++ standardization work by the ISO Working Group and the
various committees and panels of the national standardization bodies.
Finally, permission is hereby granted to include any and all of the proposed
standards text given herein under the usual ISO rules for committee work
products.
</font>
</p>
</body>
</html>
