Skip to content

R
riscv-gcc-1
Commit 320f9548 by Felix Natter Committed by Phil Edwards
Options

porting-howto.html: New version. 

2000-08-07  Felix Natter  <fnatter@gmx.net>

	* docs/17_intro/porting-howto.html:  New version.

From-SVN: r35555
parent 10120687
Showing with 508 additions and 295 deletions
libstdc++-v3/ChangeLog
2000-08-07 Felix Natter <fnatter@gmx.net>
* docs/17_intro/porting-howto.html: New version.
2000-08-03 Mark Mitchell <mark@codesourcery.com>
* bits/locale_facets.h (ctype::ctype): Don't name unused
......
libstdc++-v3/docs/17_intro/porting-howto.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Libstdc++-porting-howto</title>
<meta content="DocBook XSL Stylesheets V1.16" name="generator">
</head>
<body>
<h1>Porting to libstdc++-v3</h1>
<center>
<li><a href = "#std">Namespaces std</a>
<li><a href = "#nocreate">File-flags: <tt>ios::nocreate</tt> and
<tt>ios::noreplace</tt></a>
<li><a href = "#headers">The new headers</a>
<li><a href = "#iterators">Iterator-changes</a>
<li><a href = "#macros">Libc-macros</a>
<li><a href = "#about">Comments, suggestions, corrections, questions...</a>
</center>
<p>
In the following, when I say portable, I will refer to "portable among ISO
14882-implementations". On the other hand, if I say "backportable" or
"conservative", I am talking about "compiles with older
libstdc++-implementations".
</p>
<a name = "std">
<h2>Namespace std::</h2>
</a>
<p>
The latest C++-standard (ISO-14882) requires that the standard C++-library
is defined in namespace std::. Thus, to use classes from the standard c++
library, you can do one of three things:
<ul>
<li>wrap your code in <tt>namespace std { ... }</tt> => This is not an
option because only symbols from the standard c++-library are defined in
namespace std::.
<li>put a kind of <dfn>using-declaration</dfn> in your source (either
<tt>using namespace std;</tt> or i.e. <tt>using std::string;</tt>)
=> works well for source-files, but cannot be used in header-files
<li>use a <dfn>fully qualified name</dfn> for each libstdc++-symbol
(i.e. <tt>std::string</tt>, <tt>std::cout</tt>) => can always be used
</ul>
</p>
<p>
Because there are many compilers which still use an implementation that
does not have the standard C++-library in namespace <tt>std::</tt>, some
care is required to support these as well.
</p>
<p>
Namespace back-portability-issues are generally not a problem with g++,
because versions of g++ that do not have libstdc++ in <tt>std::</tt> use
<tt>-fno-honor-std</tt> (ignore <tt>std::</tt>, <tt>:: = std::</tt>) by
default. That is, the responsibility for enabling or disabling
<tt>std::</tt> is on the user; the maintainer does not have to care about it.
This probably applies to some other compilers as well.
</p>
<p>
The following sections list some possible solutions to support compilers
that cannot ignore std::.
</p>
<a name = "gtkmm">
<h3>Using <dfn>namespace composition</dfn> if the project uses a separate
namespace</h3>
</a>
<p>
<a href = "http://gtkmm.sourcforge.net">Gtk--</a> defines most of its
classes in namespace Gtk::. Thus, it was possible to adapt Gtk-- to
namespace std:: by using a C++-feature called <dfn>namespace
composition</dfn>. This is what happens if you put a
<dfn>using</dfn>-declaration into a namespace-definition: the imported
symbol(s) gets imported into the currently active namespace(s). For example:
<pre>
namespace Gtk {
using std::string;
class Window { ... }
}
</pre>
In this example, <tt>std::string</tt> gets imported into namespace Gtk::.
The result is that you don't have to use <tt>std::string</tt> in this
header, but still <tt>std::string</tt> does not get imported into
user-space (the global namespace ::) unless the user does <tt>using
namespace Gtk;</tt> (which is not recommended practice for Gtk--, so it is
not a problem). Additionally, the <tt>using</tt>-declarations are wrapped
in macros that are set based on autoconf-tests to either "" or
i.e. <tt>using std::string;</tt> (depending on whether the system has
libstdc++ in <tt>std::</tt> or not).
(ideas from llewelly@dbritsch.dsl.xmission.com,
Karl Nelson <kenelson@ece.ucdavis.edu>)
</p>
<h3>Defining an empty namespace std</h3>
<p>
By defining an (empty) namespace <tt>std::</tt> before using it, you can
avoid getting errors on systems where no part of the library is in
namespace std:
<pre>
namespace std { }
using namespace std;
</pre>
</p>
<h3>Avoid to use fully qualified names (i.e. std::string)</h3>
<p>
If some compilers complain about <tt>using std::string;</tt>, and if the
"hack" for gtk-- mentioned above does not work, then it might be a good idea
to define a macro <tt>NS_STD</tt>, which is defined to either "" or "std"
based on an autoconf-test. Then you should be able to use
<tt>NS_STD::string</tt>, which will evaluate to <tt>::string</tt> ("string
in the global namespace") on systems that do not put string in std::.
(This is untested)
</p>
<h3>How some open-source-projects deal with this</h3>
<p>
<table>
<tr><td><a href = "http://www.clanlib.org">clanlib</a></td> <td>usual</td>
</tr>
<tr><td><a href = "http://pingus.seul.org">pingus</a></td> <td>usual</td>
</tr>
<tr><td><a href = "http://www.mozilla.org">mozilla</a></td> <td>usual</td>
</tr>
<tr><td><a href = "http://www.mnemonic.org">mnemonic</a></td> <td>none</td>
</tr>
<tr><td><a href = "http://libsigc.sourceforge.net">libsigc++</a></td>
<td>conservative-impl</td>
</tr>
</table>
<table>
<caption>Notations for categories</caption>
<tr>
<td>usual</td> <td>mostly fully qualified names and some
using-declarations (but not in headers)</td>
</tr>
<tr>
<td>none</td> <td>no namespace std at all</td>
</tr>
<tr>
<td>conservative-impl</td> <td>wrap all namespace-handling in macros to
support compilers without namespace-support (no libstdc++ used in
headers)</td>
</tr>
</table>
As you can see, this currently lacks an example of a project which uses
libstdc++-symbols in headers in a back-portable way
(except for the <a href = "#gtkmm">Gtk-- "hack"</a>).
</p>
<a name = "nocreate">
<h2>there is no ios::nocreate/ios::noreplace in ISO 14882</h2>
</a>
<p>
I have seen <tt>ios::nocreate</tt> being used for input-streams, most
probably because the authors thought it would be more correct to specify
nocreate "explicitly". So you can simply leave it out for
input-streams.
</p>
<p>
For output streams, "nocreate" is probably the default, unless you specify
<tt>std::ios::trunc</tt> ? To be safe, you can open the file for
reading, check if it has been opened, and then decide whether you want to
create/replace or not. To my knowledge, even older implementations support
<tt>app</tt>, <tt>ate</tt> and <tt>trunc</tt> (except for <tt>app</tt> ?).
</p>
<a name = "attach">
<h2><tt>stream::attach(int fd)</tt> is not in the standard any more</h2>
</a>
<p>
With libstdc++-v3, you can use
<pre>
basic_filebuf(int __fd, const char*__name, ios_base::openmode __mode)
</pre>
For a portable solution (if there is one), you need to implement
a subclass of <tt>streambuf</tt> which opens a file given a descriptor,
and then pass an instance of this to the stream-constructor (from the
Josuttis-book).
</p>
<a name = "headers">
<h2>The new headers</h2>
</a>
<p>
The new headers can be seen in this
<a href = "../../testsuite/17_intro/headers.cc">source file</a>.
</p>
<p>
I think it is a problem for libstdc++-v3 to add links or wrappers for the
old headers, because the implementation has changed, and the
header-name-changes indicate this. It might be preferable to use the new
headers and tell users of old compilers that they should create links
(which is what they will have to do sometime anyway).
</p>
<a name = "cheaders">
<h3>New headers replacing C-headers</h3>
</a>
<p>
You should not use the C-headers (except for system-level headers) from C++
programs. Instead, you should use a set of headers that are named by
prepending 'c' and, as usual, ommiting the extension (.h). For example,
instead of using <tt>&lt;math.h&gt;</tt>, you should use
<tt>&lt;cmath&gt;</tt>. The standard specifies that if you include the
C-style header (<tt>&lt;math.h&gt;</tt> in this case), the symbols will be
available both in the global namespace and in namespace <tt>std::</tt>
(libstdc++-v3, version 2.90.8 currently puts them in <tt>std::</tt> only)
On the other hand, if you include only the new header
(i.e. <tt>&lt;cmath&gt;</tt>), the symbols will only be defined in
namespace <tt>std::</tt> (and macros will be converted to
inline-functions).
</p>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="article" id="libstdporting">
<div class="titlepage">
<h1 class="title">
<a name="libstdporting">Libstdc++-porting-howto</a>
</h1>
<h3 class="author">Felix Natter</h3>
<p>
For more information on this, and for information on how the GNU C++
implementation reuses ("shadows") the C library-functions, have
a look at <a href = "http://www.cantrip.org/cheaders.html">www.cantrip.org</a>.
</p>
<h3><tt>&lt;fstream&gt;</tt> does not define <tt>std::cout</tt>,
<tt>std::cin</tt> etc.</h3>
This document can be distributed under the FDL
(<a href="http://www.gnu.org">www.gnu.org</a>)
</p>
<p class="pubdate">what kind of a date ? I don't drink !</p>
<div class="revhistory">
<table width="100%" border="1">
<tr>
<th colspan="3" valign="top" align="left"><b>Revision History</b></th>
</tr>
<tr>
<td align="left">Revision 0.5</td><td align="left">Thu Jun 1 13:06:50 2000</td><td align="left">fnatter</td>
</tr>
<tr>
<td colspan="3" align="left">First docbook-version.</td>
</tr>
<tr>
<td align="left">Revision 0.8</td><td align="left">Sun Jul 30 20:28:40 2000</td><td align="left">fnatter</td>
</tr>
<tr>
<td colspan="3" align="left">First released version using docbook-xml
+ second upload to libstdc++-page.
</td>
</tr>
</table>
</div>
<div class="abstract">
<p>
<a name="N2672"></a><b>Abstract</b>
</p>
<p>
Some notes on porting applications from libstdc++-2.90 (or earlier
versions) to libstdc++-v3. Not speaking in terms of the GNU libstdc++
implementations, this means porting from earlier versions of the
C++-Standard to ISO 14882.
</p>
</div>
<hr>
</div>
<div class="toc">
<p>
In previous versions of the standard, <tt>&lt;fstream.h&gt;</tt>,
<tt>&lt;ostream.h&gt;</tt> and <tt>&lt;istream.h&gt;</tt> used to define
<tt>cout</tt>, <tt>cin</tt> and so on. Because of the templatized iostreams
in libstdc++-v3, you need to include <tt>&lt;iostream&gt;</tt> explicitly
to define these.
</p>
<a name = "iterators">
<h2>Iterators</h2>
</a>
<p>
The following are not proper uses of iterators, but may be working fixes
for existing uses of iterators.
<ul>
<li>you cannot do <tt>ostream::operator<<(iterator)</tt> to print the
address of the iterator => use <tt><< &*iterator</tt> instead ?
<li>you cannot clear an iterator's reference (<tt>iterator = 0</tt>)
=> use <tt>iterator = iterator_type();</tt> ?
<li><tt>if (iterator)</tt> won't work any more
=> use <tt>if (iterator != iterator_type())</tt> ?
</ul>
</p>
<a name = "macros">
<h2>Libc-macros (i.e. <tt>isspace</tt> from <tt>&lt;cctype&gt;</tt>)</h2>
</a>
<p>
Glibc 2.0.x and 2.1.x define the <tt>&lt;ctype.h&gt;</tt>-functionality
as macros (isspace, isalpha etc.). Libstdc++-v3 "shadows" these macros
as described in the <a href = "#cheaders">section on C-headers</a>.
</p>
<b>Table of Contents</b>
</p>
<dl>
<dt>1. <a href="#sec-nsstd">Namespace std::</a>
</dt>
<dd>
<dl>
<dt>1.1.1. <a href="#sec-gtkmm-hack">Using <i>namespace
composition</i> if the project uses a separate
namespace</a>
</dt>
<dt>1.1.2. <a href="#sec-emptyns">Defining an empty namespace std</a>
</dt>
<dt>1.1.3. <a href="#sec-avoidfqn">Avoid to use fully qualified names
(i.e. std::string)</a>
</dt>
<dt>1.1.4. <a href="#sec-osprojects">How some open-source-projects deal
with this</a>
</dt>
</dl>
</dd>
<dt>2. <a href="#sec-nocreate">there is no ios::nocreate/ios::noreplace
in ISO 14882</a>
</dt>
<dt>3. <a href="#sec-stream::attach"><b>stream::attach(int
fd)</b> is not in the standard any more</a>
</dt>
<dt>4. <a href="#sec-headers">The new headers</a>
</dt>
<dd>
<dl>
<dt>4.4.1. <a href="#sec-cheaders">New headers replacing C-headers</a>
</dt>
<dt>4.4.2. <a href="#sec-fstream-header">
<tt>&lt;fstream&gt;</tt> does
not define <b>std::cout</b>,
<b>std::cin</b> etc.</a>
</dt>
</dl>
</dd>
<dt>5. <a href="#sec-iterators">Iterators</a>
</dt>
<dt>6. <a href="#sec-macros">
Libc-macros (i.e. <b>isspace</b> from
<tt>&lt;cctype&gt;</tt>)</a>
</dt>
<dt>7. <a href="#sec-about">About...</a>
</dt>
</dl>
</div>
<p>
Older implementations of libstdc++ (g++-2 for egcs 1.x and g++-3 for
gcc 2.95.2), however, keep these functions as macros, and so it is not
back-portable to use fully qualified names. For example:
<pre>
#include &lt;cctype&gt;
int main() { std::isspace('X'); }
</pre>
will result in something like this (unless using g++-v3):
<pre>
std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ;
</pre>
Another problem arises if you put a <tt>using namespace std;</tt>
declaration at the top, and include <tt>&lt;ctype.h&gt;</tt>. This will
result in ambiguities between the definitions in the global namespace
(<tt>&lt;ctype.h&gt;</tt>) and the definitions in namespace <tt>std::</tt>
(<tt>&lt;cctype&gt;</tt>).
</p>
<p>
One solution I can think of is to test for -v3 using autoconf-macros, and
define macros for each of the C-functions (maybe that is possible with one
"wrapper" macro as well ?).
</p>
<p>
Another solution which would fix g++ is to tell the user to modify
a header-file so that g++-2 (egcs 1.x) and g++-3 (gcc 2.95.2)
enable a macro which tells &lt;ctype.h&gt; to define functions instead of
macros:
<pre>
// This keeps isanum, et al from being propagated as macros.
#if __linux__
#define __NO_CTYPE 1
#endif
[ now include &lt;ctype.h&gt; ]
</pre>
</p>
In the following, when I say portable, I will refer to "portable among ISO
14882-implementations". On the other hand, if I say "backportable" or
"conservative", I am talking about "compiles with older
libstdc++-implementations".
</p>
<div class="section" id="sec-nsstd">
<h2 class="title" style="clear: all">
<a name="sec-nsstd"><b>1. Namespace std::</b></a>
</h2>
<p>
The latest C++-standard (ISO-14882) requires that the standard
C++-library is defined in namespace std::. Thus, in order to use
classes from the standard C++-library, you can do one of three
things:
<div class="itemizedlist">
<ul>
<li>
<a name="N2696"></a>
<p>wrap your code in <b>namespace std {
... }</b> =&gt; This is not an option because only symbols
from the standard c++-library are defined in namespace std::.
</p>
</li>
<li>
<a name="N2705"></a>
<p>put a kind of
<i>using-declaration</i> in your source (either
<b>using namespace std;</b> or i.e. <b>using
std::string;</b>) =&gt; works well for source-files, but
cannot be used in header-files.
</p>
</li>
<li>
<a name="N2720"></a>
<p>use a <i>fully qualified name</i> for
each libstdc++-symbol (i.e. <b>std::string</b>,
<b>std::cout</b>) =&gt; can always be used
</p>
</li>
</ul>
</div>
</p>
<p>
Because there are many compilers which still use an implementation
that does not have the standard C++-library in namespace
<b>std::</b>, some care is required to support these as
well.
</p>
<p>
Namespace back-portability-issues are generally not a problem with
g++, because versions of g++ that do not have libstdc++ in
<b>std::</b> use <b>-fno-honor-std</b>
(ignore <b>std::</b>, <b>:: = std::</b>) by
default. That is, the responsibility for enabling or disabling
<b>std::</b> is on the user; the maintainer does not have
to care about it. This probably applies to some other compilers as
well.
</p>
<p>
The following sections list some possible solutions to support compilers
that cannot ignore std::.
</p>
<div class="section" id="sec-gtkmm-hack">
<h3 class="title">
<a name="sec-gtkmm-hack"><b>1.1.1. Using <i>namespace
composition</i> if the project uses a separate
namespace</b></a>
</h3>
<p>
<a href="http://gtkmm.sourceforge.net">Gtk--</a> defines
most of its classes in namespace Gtk::. Thus, it was possible to
adapt Gtk-- to namespace std:: by using a C++-feature called
<i>namespace composition</i>. This is what happens if
you put a <i>using</i>-declaration into a
namespace-definition: the imported symbol(s) gets imported into the
currently active namespace(s). For example:
<pre class="programlisting">
namespace Gtk {
using std::string;
class Window { ... }
}
</pre>
In this example, <b>std::string</b> gets imported into
namespace Gtk::. The result is that you don't have to use
<b>std::string</b> in this header, but still
<b>std::string</b> does not get imported into
user-space (the global namespace ::) unless the user does
<b>using namespace Gtk;</b> (which is not recommended
practice for Gtk--, so it is not a problem). Additionally, the
<b>using</b>-declarations are wrapped in macros that
are set based on autoconf-tests to either "" or i.e. <b>using
std::string;</b> (depending on whether the system has
libstdc++ in <b>std::</b> or not). (ideas from
<tt>&lt;<a href="mailto:llewelly@dbritsch.dsl.xmission.com">llewelly@dbritsch.dsl.xmission.com</a>&gt;</tt>, Karl Nelson
<tt>&lt;<a href="mailto:kenelson@ece.ucdavis.edu">kenelson@ece.ucdavis.edu</a>&gt;</tt>)
</p>
</div>
<div class="section" id="sec-emptyns">
<h3 class="title">
<a name="sec-emptyns"><b>1.1.2. Defining an empty namespace std</b></a>
</h3>
<p>
By defining an (empty) namespace <b>std::</b> before
using it, you avoid getting errors on systems where no part of the
library is in namespace std:
<pre class="programlisting">
namespace std { }
using namespace std;
</pre>
</p>
</div>
<div class="section" id="sec-avoidfqn">
<h3 class="title">
<a name="sec-avoidfqn"><b>1.1.3. Avoid to use fully qualified names
(i.e. std::string)</b></a>
</h3>
<p>
If some compilers complain about <b>using
std::string;</b>, and if the "hack" for gtk-- mentioned above
does not work, then it might be a good idea to define a macro
NS_STD, which is defined to either "" or "std"
based on an autoconf-test. Then you should be able to use
<b>NS_STD::string</b>, which will evaluate to
<b>::string</b> ("string in the global namespace") on
systems that do not put string in std::. (This is untested)
</p>
</div>
<div class="section" id="sec-osprojects">
<h3 class="title">
<a name="sec-osprojects"><b>1.1.4. How some open-source-projects deal
with this</b></a>
</h3>
<p>
This information was gathered around May 2000. It may not be correct
by the time you read this.
</p>
<div class="table">
<p>
<a name="N2885"></a><b>Table 1. Namespace std:: in Open-Source programs</b>
</p>
<table border="1">
<colgroup>
<col>
<col>
</colgroup>
<tbody>
<tr>
<td><a href="http://www.clanlib.org">clanlib</a></td><td>usual</td>
</tr>
<tr>
<td><a href="http://pingus.seul.org">pingus</a></td><td>usual</td>
</tr>
<tr>
<td><a href="http://www.mozilla.org">mozilla</a></td><td>usual</td>
</tr>
<tr>
<td><a href="http://www.mnemonic.org">mnemonic</a></td><td>none</td>
</tr>
<tr>
<td><a href="http://libsigc.sourceforge.net">
libsigc++</a></td><td>conservative-impl</td>
</tr>
</tbody>
</table>
</div>
<div class="table">
<p>
<a name="N2962"></a><b>Table 2. Notations for categories</b>
</p>
<table border="1">
<colgroup>
<col>
<col>
</colgroup>
<tbody>
<tr>
<td>usual</td><td>mostly fully qualified names and some
using-declarations (but not in headers)</td>
</tr>
<tr>
<td>none</td><td>no namespace std at all</td>
</tr>
<tr>
<td>conservative-impl</td><td>wrap all
namespace-handling in macros to support compilers without
namespace-support (no libstdc++ used in headers)</td>
</tr>
</tbody>
</table>
</div>
<p>
As you can see, this currently lacks an example of a project which
uses libstdc++-symbols in headers in a back-portable way (except
for Gtk--: see the <a href="#sec-gtkmm-hack">section on the Gtk-- hack
</a>).
</p>
</div>
</div>
<div class="section" id="sec-nocreate">
<h2 class="title" style="clear: all">
<a name="sec-nocreate"><b>2. there is no ios::nocreate/ios::noreplace
in ISO 14882</b></a>
</h2>
<p>
I have seen <b>ios::nocreate</b> being used for input-streams,
most probably because the authors thought it would be more correct
to specify nocreate "explicitly". So you can simply leave it out
for input-streams.
</p>
<p>
For output streams, "nocreate" is probably the default, unless you
specify <b>std::ios::trunc</b> ? To be safe, you can open
the file for reading, check if it has been opened, and then decide
whether you want to create/replace or not. To my knowledge, even
older implementations support <b>app</b>,
<b>ate</b> and <b>trunc</b> (except for
<b>app</b> ?).
</p>
</div>
<div class="section" id="sec-stream::attach">
<h2 class="title" style="clear: all">
<a name="sec-stream::attach"><b>3. <b>stream::attach(int
fd)</b> is not in the standard any more</b></a>
</h2>
<p>
When using libstdc++-v3, you can use
<div id="N3066" class="funcsynopsis">
<p>
</p>
<a name="N3066"></a>
<pre class="funcsynopsisinfo">
#include &lt;fstream&gt;
</pre>
<p>
<code><code class="funcdef">int <b class="fsfunc">basic_filebuf</b></code>(<var class="pdparam">__fd</var>, <var class="pdparam">__name</var>, <var class="pdparam">__mode</var>);<br>int <var class="pdparam">__fd</var>;<br>const char* <var class="pdparam">__name</var>;<br>ios_base::openmode <var class="pdparam">__mode</var>;</code>
</p>
<p>
</p>
</div>
For a portable solution (if there is one), you need to implement a
subclass of <b>streambuf</b> which opens a file given a
descriptor, and then pass an instance of this to the
stream-constructor (from the Josuttis-book).
</p>
</div>
<div class="section" id="sec-headers">
<h2 class="title" style="clear: all">
<a name="sec-headers"><b>4. The new headers</b></a>
</h2>
<p>
All new headers can be seen in this <a href="../../testsuite/17_intro/headers.cc">source-code</a>.
</p>
<p>
I think it is a problem for libstdc++-v3 to add links or wrappers
for the old headers, because the implementation has changed, and
the header name-changes indicate this. It might be preferable to
use the new headers and tell users of old compilers that they
should create links (which is what they will have to do sometime
anyway).
</p>
<div class="section" id="sec-cheaders">
<h3 class="title">
<a name="sec-cheaders"><b>4.4.1. New headers replacing C-headers</b></a>
</h3>
<p>
You should not use the C-headers (except for system-level headers)
from C++ programs. Instead, you should use a set of headers that
are named by prepending 'c' and, as usual, ommiting the extension
(.h). For example, instead of using <tt>&lt;math.h&gt;</tt>, you should use <tt>&lt;cmath&gt;</tt>. The standard
specifies that if you include the C-style header (<tt>&lt;math.h&gt;</tt> in this case), the symbols
will be available both in the global namespace and in namespace
<b>std::</b> (libstdc++-v3, version 2.90.8 currently
puts them in <b>std::</b> only) On the other hand, if
you include only the new header (i.e. <tt>&lt;pcmath&gt;</tt>), the symbols will only be
defined in namespace <b>std::</b> (and macros will be
converted to inline-functions).
</p>
<p>
For more information on this, and for information on how the GNU
C++ implementation reuses ("shadows") the C library-functions, have
a look at <a href="http://www.cantrip.org/cheaders.html">
www.cantrip.org</a>.
</p>
</div>
<div class="section" id="sec-fstream-header">
<h3 class="title">
<a name="sec-fstream-header"><b>4.4.2.
<tt>&lt;fstream&gt;</tt> does
not define <b>std::cout</b>,
<b>std::cin</b> etc.</b></a>
</h3>
<p>
In previous versions of the standard, <tt>&lt;fstream.h&gt;</tt>, <tt>&lt;ostream.h&gt;</tt> and <tt>&lt;istream.h&gt;</tt> used to define
<b>cout</b>, <b>cin</b> and so on. Because
of the templatized iostreams in libstdc++-v3, you need to include
<tt>&lt;iostream&gt;</tt>
explicitly to define these.
</p>
</div>
</div>
<div class="section" id="sec-iterators">
<h2 class="title" style="clear: all">
<a name="sec-iterators"><b>5. Iterators</b></a>
</h2>
<p>
The following are not proper uses of iterators, but may be working
fixes for existing uses of iterators.
<div class="itemizedlist">
<ul>
<li>
<a name="N3266"></a>
<p>you cannot do
<b>ostream::operator&lt;&lt;(iterator)</b> to
print the address of the iterator =&gt; use
<b>operator&lt;&lt; &amp;*iterator</b> instead ?
</p>
</li>
<li>
<a name="N3287"></a>
<p>you cannot clear an iterator's reference
(<b>iterator = 0</b>) =&gt; use
<b>iterator = iterator_type();</b> ?
</p>
</li>
<li>
<a name="N3300"></a>
<p>
<b>if (iterator)</b> won't work any
more =&gt; use <b>if (iterator != iterator_type())</b>
?</p>
</li>
</ul>
</div>
</p>
</div>
<div class="section" id="sec-macros">
<h2 class="title" style="clear: all">
<a name="sec-macros"><b>6.
Libc-macros (i.e. <b>isspace</b> from
<tt>&lt;cctype&gt;</tt>)</b></a>
</h2>
<p>
Glibc 2.0.x and 2.1.x define the <tt>&lt;ctype.h&gt;</tt> -functionality as
macros (isspace, isalpha etc.). Libstdc++-v3 "shadows" these macros
as described in the <a href="#sec-cheaders">section on C-headers</a>.
</p>
<p>
Older implementations of libstdc++ (g++-2 for egcs 1.x and g++-3
for gcc 2.95.2), however, keep these functions as macros, and so it
is not back-portable to use fully qualified names. For example:
<pre class="programlisting">
#include &lt;cctype&gt;
int main() { std::isspace('X'); }
</pre>
will result in something like this (unless using g++-v3):
<pre class="programlisting">
std:: (__ctype_b[(int) ( ( 'X' ) )] &amp; (unsigned short int)
_ISspace ) ;
</pre>
</p>
<p>
One solution I can think of is to test for -v3 using
autoconf-macros, and define macros for each of the C-functions
(maybe that is possible with one "wrapper" macro as well ?).
</p>
<p>
Another solution which would fix g++ is to tell the user to modify a
header-file so that g++-2 (egcs 1.x) and g++-3 (gcc 2.95.2) define a
macro which tells <tt>&lt;ctype.h&gt;</tt> to define functions
instead of macros:
<pre class="programlisting">
// This keeps isalnum, et al from being propagated as macros.
#if __linux__
#define __NO_CTYPE 1
#endif
<a name = "about">
<h2>About...</h2>
</a>
<p>
Please send any experience, additions, corrections or questions to <a href
= "mailto:fnatter@gmx.net">fnatter@gmx.net</a> or for discussion to the
libstdc++-v3-mailing-list.
</p>
[ now include &lt;ctype.h&gt; ]
</pre>
</p>
<p>
Another problem arises if you put a <b>using namespace
std;</b> declaration at the top, and include <tt>&lt;ctype.h&gt;</tt>. This will result in
ambiguities between the definitions in the global namespace
(<tt>&lt;ctype.h&gt;</tt>) and the
definitions in namespace <b>std::</b>
(<b>&lt;cctype&gt;</b>).
</p>
<p>
The solution to this problem was posted to the libstdc++-v3
mailing-list:
Benjamin Kosnik <tt>&lt;<a href="mailto:bkoz@redhat.com">bkoz@redhat.com</a>&gt;</tt> writes:
"
--enable-cshadow-headers is currently broken. As a result, shadow
headers are not being searched....
"
</p>
</div>
<div class="section" id="sec-about">
<h2 class="title" style="clear: all">
<a name="sec-about"><b>7. About...</b></a>
</h2>
<p>
Please send any experience, additions, corrections or questions to
<a href="mailto:fnatter@gmx.net">fnatter@gmx.net</a> or for
discussion to the libstdc++-v3-mailing-list.
</p>
</div>
</div>
</body>
</html>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment