+2001-02-06 Phil Edwards <pme@sources.redhat.com>
+
+ * docs/html/configopts.html: Fix HTML markup.
+ * docs/html/install.html: Bring up to date.
+ * docs/html/17_intro/C++STYLE: Add global variable conventions.
+ * docs/html/21_strings/howto.html: More notes.
+ * docs/html/22_locale/howto.html: Fix HTML markup.
+ * docs/html/27_io/howto.html: More notes.
+ * docs/html/27_io/binary_iostreams_kanze.txt: New file.
+ * docs/html/27_io/binary_iostreams_kuehl.txt: New file.
+
2001-02-06 Jeffrey Oldham <oldham@codesourcery.com>
* src/misc-inst.cc (_S_pad_char): Modify declaration's parameters
it is intended to precede the recommendations of the GNU Coding
Standard, which can be referenced here:
-http://www.gnu.ai.mit.edu/prep/standards_toc.html
+http://www.gnu.org/prep/standards_toc.html
ChangeLog entries for member functions should use the
classname::member function name syntax as follows:
char &c = *p; // wrong
Reason: In C++, definitions are mixed with executable code. Here,
- p is being initialized, not *p. This is near-universal
+ p is being initialized, not *p. This is near-universal
practice among C++ programmers; it is normal for C hackers
to switch spontaneously as they gain experience.
return __ret;
+14. Location of global variables.
+ All global variables of class type, whether in the "user visable"
+ space (e.g., cin) or the implementation namespace, must be defined
+ as a character array with the appropriate alignment and then later
+ re-initialized to the correct value.
+
+ This is due to startup issues on certain platforms, such as AIX.
+ For more explanation and examples, see src/globals.cc. All such
+ variables should be contained in that file, for simplicity.
+
The library currently has a mixture of GNU-C and modern C++ coding
<META NAME="GENERATOR" CONTENT="vi and eight fingers">
<TITLE>libstdc++-v3 HOWTO: Chapter 21</TITLE>
<LINK REL=StyleSheet HREF="../lib3styles.css">
-<!-- $Id: howto.html,v 1.7 2000/12/03 23:47:47 jsm28 Exp $ -->
+<!-- $Id: howto.html,v 1.1 2000/12/10 04:04:55 pme Exp $ -->
</HEAD>
<BODY>
with reading the new function names, this version is recommended
as an example.
</P>
+ <P><B>Added February 2001:</B> Mark Wilden pointed out that the
+ standard <TT>std::getline()</TT> function can be used with standard
+ <A HREF="../27_io/howto.html">istringstreams</A> to perform
+ tokenizing as well. Build an istringstream from the input text,
+ and then use std::getline with varying delimiters (the three-argument
+ signature) to extract tokens into a string.
+ </P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:pme@sources.redhat.com">Phil Edwards</A> or
<A HREF="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</A>.
-<BR> $Id: howto.html,v 1.7 2000/12/03 23:47:47 jsm28 Exp $
+<BR> $Id: howto.html,v 1.1 2000/12/10 04:04:55 pme Exp $
</EM></P>
<META NAME="GENERATOR" CONTENT="vi and eight fingers">
<TITLE>libstdc++-v3 HOWTO: Chapter 22</TITLE>
<LINK REL=StyleSheet HREF="../lib3styles.css">
-<!-- $Id: howto.html,v 1.8 2000/12/03 23:47:47 jsm28 Exp $ -->
+<!-- $Id: howto.html,v 1.1 2000/12/10 04:04:55 pme Exp $ -->
</HEAD>
<BODY>
<HR>
<H2><A NAME="2">Nathan Myers on Locales</A></H2>
- <P> An article entitled "The Standard C++ Locale" was published in
- Dr. Dobb's Journal and can be found
- <A HREF="http://www.cantrip.org/locale.html">here</A>
+ <P> An article entitled "The Standard C++ Locale" was
+ published in Dr. Dobb's Journal and can be found
+ <A HREF="http://www.cantrip.org/locale.html">here</A>.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
<HR>
<H2><A NAME="5">class locale</A></H2>
<P> Notes made during the implementation of locales can be found
- <A HREF="locale.html">here</A>.
+
<A HREF="locale.html">here</A>.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
<HR>
<H2><A NAME="4">class codecvt</A></H2>
<P> Notes made during the implementation of codecvt can be found
- <A HREF="codecvt.html">here</A>.
+
<A HREF="codecvt.html">here</A>.
</P>
<P> The following is the abstract from the implementation notes:
<HR>
<H2><A NAME="5">class ctype</A></H2>
<P> Notes made during the implementation of ctype can be found
- <A HREF="ctype.html">here</A>.
+
<A HREF="ctype.html">here</A>.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
<H2><A NAME="6">Correct Transformations</A></H2>
<!-- Jumping directly here from chapter 21. -->
<P>A very common question on newsgroups and mailing lists is, "How
- do I do <foo> to a character string?" where <foo> is
+ do I do <foo> to a character string?" where <foo> is
a task such as changing all the letters to uppercase, to lowercase,
testing for digits, etc. A skilled and conscientious programmer
will follow the question with another, "And how do I make the
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:pme@sources.redhat.com">Phil Edwards</A> or
<A HREF="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</A>.
-<BR> $Id: howto.html,v 1.8 2000/12/03 23:47:47 jsm28 Exp $
+<BR> $Id: howto.html,v 1.1 2000/12/10 04:04:55 pme Exp $
</EM></P>
--- /dev/null
+
+From: James Kanze <kanze@gabi-soft.de>
+Newsgroups: comp.lang.c++.moderated
+Subject: Re: binary iostreams ?
+Date: 3 Feb 2001 14:28:19 -0500
+Message-ID: <86lmro86qp.fsf@alex.gabi-soft.de>
+
+"Plinio Conti" <plinio.contiNO@SPAMMINGmclink.it> writes:
+
+|> Why std c++ library stream classes are only text-oriented?
+
+Because that is the only universally recognized format.
+
+|> I mean, if I want to write an int, a float, etc. AS IT IS I can't
+|> use streams, because they write and read a human readable text
+|> format of numbers.
+
+Correct.
+
+|> Does anyone know how to solve the problem?
+
+It depends on what you really want to do. If you are just dumping a
+block of memory to disk, in order to free up memory, and will reread it
+later in the same run of the same program, ostream::write and
+istream::read are what you need. Note, however, that this ony works 1)
+in the same run of the same program, and 2) for PODs without pointers.
+
+If you are writing something that will be read by another program, or a
+later run of the same program, you'll have to define a specific format
+to use, and implement streams to input and output that. If you are
+writing something that will be read by an existing program, or be
+transmitted over a network to another machine, you will have to find out
+what protocol is expected, and adher to it.
+
+|> Any public library?
+
+Not that I know of. I think that there is a library somewhere that
+outputs in format RPC, or maybe some Internet format.
+
+|> What do you think about this choice?
+
+What other choice is possible? It's not reasonable to ask the standard
+to support all binary formats, and it's not reasonable for it to favor
+any one of them. Given that, what else can you do.
+
+--
+James Kanze mailto:kanze@gabi-soft.de
+Conseils en informatique orientée objet/
+ Beratung in objektorientierter Datenverarbeitung
+Ziegelhüttenweg 17a, 60598 Frankfurt, Germany Tel. +49(069)63198627
+
--- /dev/null
+
+From: kuehl@ramsen.informatik.uni-konstanz.de (Dietmar Kuehl)
+Newsgroups: comp.std.c++
+Subject: Re: binary iostreams ?
+Date: Sat, 3 Feb 2001 17:17:49 GMT
+Message-ID: <95hctq$suu$2@news.BelWue.DE>
+
+Hi,
+Plinio Conti (plinio.contiNO@SPAMMINGmclink.it) wrote:
+: Why std c++ library stream classes are only text-oriented?
+
+There is only a text oriented front end to stream buffers because text
+input and output does not vary between platforms. This is very
+different for binary output. For example, binary output has to consider
+
+- word sizes: Is an 'int' two, four, or eight bytes long? The same
+ questions arise for all other built-in types.
+
+- what is the bit pattern of a value? I think that at least implicitly
+ in the standard a binary representation for integer types is required.
+ I don't think that it is required to use two's complement. In any
+ case, the floating point representations do differ, eg. in their
+ number of bytes used.
+
+- what "endianess" is to be used?
+
+Basically it is possible to decide a format for each of those. This,
+however, implies inefficient implementations on platforms where the
+format does not match the internal representation.
+
+What many people asking for binary I/O forget is that binary I/O also
+requires some form of formatting! Assuming that just writing data and
+then reading it in will work is asking for problems, eg. when the
+compiler version changes and they decided to use a 32 bit integer
+rather than a 16 bit integer: It is not even necessary to switch
+platforms to run into problems!
+
+: I mean, if I want to write an int, a float, etc. AS IT IS I can't use
+: streams, because they write and read a human readable text format of
+: numbers.
+
+Which is for most I/O a reasonable approach. If it is not for you, you
+might want to consider a data base: File I/O is not really useful as a
+persistance mechanism. It is fine eg. for user interaction (text I/O),
+logging (text I/O), cross platfrom program interaction (formatted I/O),
+and data exchange (formatted I/O). In all these cases, the I/O is
+formatted, although possible using a binary format. For persistance,
+data bases are used. Depending on your needs, a relational or an object
+oriented one may be better suited.
+
+That said, it is worth to mention that it is easy to create a hierarchy
+similar to IOStreams built on top of stream buffers but doing binary
+formatting. A somewhat aged example is found at
+<ftp://ftp.fmi.uni-konstanz.de/pub/algo/personal/kuehl/binio.tar.gz>.
+This uses XDR formatting of the binary data (well, if I remmeber
+correctly, it is easy to plug in a different binary formatting).
+
+: Does anyone know how to solve the problem?
+
+Use a data base, text formatting, or binary formatting. With the
+details you have given it is impossible to tell which of those is the
+right approach because you haven't told *why* you want a binary format
+and *what* you want to do. That basically means that you came up with
+solution and you want us to confirm that it is the right one without
+telling us what problem is solved! Until I have seen the problem I
+doubt that binary I/O is the right approach...
+
+... and, BTW, using 'std::istream::read()' and 'std::ostream::write()'
+is almost certainly the *wrong* approach! These functions are an
+historical mistake which should have been corrected in the standard:
+It is my understanding that these methods were present in the IOStream
+version predating the rework from Jerry Schwartz and were left in to
+be compatible with the earlier stuff although they were not necessary:
+You could get binary I/O from the stream buffer level. The original
+IOStream library (maybe you remember using <stream.h>) did not have
+stream buffers and thus basic support for binary I/O was also present
+on the streams level.
+
+: What do you think about this choice?
+
+When I wrote the above paragraph about confirming your choice, I haven't
+read this question! As I said above: You told us what solution you have
+choosen without stating what problem is solved. We cannot determine
+whether your choice is the right one. Actually, I'm pretty sure it is
+the wrong one but without seen the details I can't be certain.
+--
+<mailto:dietmar_kuehl@yahoo.com> <http://www.dietmar-kuehl.de/>
+Phaidros eaSE - Easy Software Engineering: <http://www.phaidros.com/>
+
<META NAME="GENERATOR" CONTENT="vi and eight fingers">
<TITLE>libstdc++-v3 HOWTO: Chapter 27</TITLE>
<LINK REL=StyleSheet HREF="../lib3styles.css">
-<!-- $Id: howto.html,v 1.1 2000/12/10 04:04:56 pme Exp $ -->
+<!-- $Id: howto.html,v 1.2 2001/01/23 17:02:27 pme Exp $ -->
</HEAD>
<BODY>
<LI><A HREF="#4">Iostreams class hierarchy diagram</A>
<LI><A HREF="#5">What is this <sstream>/stringstreams thing?</A>
<LI><A HREF="#6">Deriving a stream buffer</A>
+ <LI><A HREF="#7">More on binary I/O</A>
</UL>
<HR>
<P>Sorry. Them's the breaks.
</P>
<P>This isn't going to try and be a complete tutorial on reading and
- writing binary files (because "binary" covers a lot of
- ground), but we will try and clear up a couple of misconceptions
- and common errors.
+ writing binary files (because "binary"
+ <A HREF="#7">covers a lot of ground)</A>, but we will try and clear
+ up a couple of misconceptions and common errors.
</P>
<P>First, <TT>ios::binary</TT> has exactly one defined effect, no more
and no less. Normal text mode has to be concerned with the newline
<P>Third, using the <TT>get()</TT> and <TT>put()/write()</TT> member
functions still aren't guaranteed to help you. These are
"unformatted" I/O functions, but still character-based.
- (This may or may not be what you want.)
+ (This may or may not be what you want, see below.)
</P>
<P>Notice how all the problems here are due to the inappropriate use
of <EM>formatting</EM> functions and classes to perform something
Try it yourself!
</P>
+<HR>
+<H2><A NAME="7">More on binary I/O</A></H2>
+ <P>Towards the beginning of February 2001, the subject of
+ "binary" I/O was brought up in a couple of places at the
+ same time. One notable place was Usenet, where James Kanze and
+ Dietmar Kühl separately posted articles on why attempting
+ generic binary I/O was not a good idea. (Here are copies of
+ <A HREF="binary_iostreams_kanze.txt">Kanze's article</A> and
+ <A HREF="binary_iostreams_kuehl.txt">Kühl's article</A>.)
+ </P>
+ <P>Briefly, the problems of byte ordering and type sizes mean that
+ the unformatted functions like <TT>ostream::put()</TT> and
+ <TT>istream::get()</TT> cannot safely be used to communicate
+ between arbitrary programs, or across a network, or from one
+ invocation of a program to another invocation of the same program
+ on a different platform, etc.
+ </P>
+ <P>The entire Usenet thread is instructive, and took place under the
+ subject heading "binary iostreams" on both comp.std.c++
+ and comp.lang.c++.moderated in parallel. Also in that thread,
+ Dietmar Kühl mentioned that he had written a pair of stream
+ classes that would read and write XDR, which is a good step towards
+ a portable binary format.
+ </P>
+
<!-- ####################################################### -->
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:pme@sources.redhat.com">Phil Edwards</A> or
<A HREF="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</A>.
-<BR> $Id: howto.html,v 1.1 2000/12/10 04:04:56 pme Exp $
+<BR> $Id: howto.html,v 1.2 2001/01/23 17:02:27 pme Exp $
</EM></P>
<META NAME="GENERATOR" CONTENT="vi and eight fingers">
<TITLE>libstdc++-v3 configure options</TITLE>
<LINK REL=StyleSheet HREF="lib3styles.css">
-<!-- $Id: configopts.html,v 1.4 2001/01/21 09:36:09 pme Exp $ -->
+<!-- $Id: configopts.html,v 1.5 2001/01/30 09:18:50 bkoz Exp $ -->
</HEAD>
<BODY>
model based on langinfo/iconv (from <A
HREF="http://sources.redhat.com/glibc/">glibc</A>, the GNU C
library), or 'generic' to use a generic "C"
- abstraction which consists of "C" locale info. The default is
- 'generic'.
+ abstraction which consists of "C" locale info.
+ The default is 'generic'.
</P>
<DT><TT>--enable-long-long </TT>
<TT>--with-gxx-include-dir=_dirname_</TT> during configuration.
</P>
-
<DT><TT>--with-gxx-include-dir=<include-files dir></TT>
<DD><P>Adds support for named libstdc++ include directory. For instance,
the following puts all the libstdc++ headers into a directory
<HR>
<P CLASS="fineprint"><EM>
-$Id: configopts.html,v 1.4 2001/01/21 09:36:09 pme Exp $
+$Id: configopts.html,v 1.5 2001/01/30 09:18:50 bkoz Exp $
</EM></P>
<META NAME="GENERATOR" CONTENT="vi and eight fingers">
<TITLE>libstdc++-v3 Installation Instructions</TITLE>
<LINK REL=StyleSheet HREF="lib3styles.css">
-<!-- $Id: install.html,v 1.2 2001/01/21 09:36:09 pme Exp $ -->
+<!-- $Id: install.html,v 1.3 2001/01/23 17:02:26 pme Exp $ -->
</HEAD>
<BODY>
<P>If you don't have bash, and want to run <TT>'make check'</TT> to
test your build, you'll need to get bash 2.x. Also recommended
is GNU Make, since it is the only 'make' that will parse these
- makefiles correctly.
+ makefiles correctly. We are moving to DejaGNU, so you'll
+ probably want to get that.
</P>
<P>As of June 19, 2000, libstdc++ attempts to use tricky and
<P><B>...with a gcc-2.9[67] snapshot</B>
<P>Unpack the <EM>gccsrcdir</EM> and go into that directory. For
instance, <TT>gcc-2.95.2</TT> is a valid <EM>gccsrcdir</EM>.
- Once in <EM>gccsrcdir</EM>, you'll need to rename the libstdc++-v3
- directory which comes with that snapshot:
+ Once in <EM>gccsrcdir</EM>, you'll need to rename or delete
+ the libstdc++-v3 directory which comes with that snapshot:
<PRE>
- mv libstdc++-v3 libstdc++-v3-previous</PRE>
+ mv libstdc++-v3 libstdc++-v3-previous <STRONG>[OR]</STRONG>
+ rm -r libstdc++-v3</PRE>
</P>
<P>Next, unpack the libstdc++-v3 library tarball into the
<EM>gccsrcdir</EM> directory; it will create a
<P><B>...with CVS gcc</B>
<P>Check out or download the gcc sources: the resulting source
directory is <EM>gccsrcdir</EM>. Once in <EM>gccsrcdir</EM>,
- you'll need to rename the libstdc++-v3 directory which comes
- with that snapshot:
- mv libstdc++-v3 libstdc++-v3-previous</PRE>
+ you'll need to rename or delete the libstdc++-v3 directory
+ which comes with that snapshot:
+ <PRE>
+ mv libstdc++-v3 libstdc++-v3-previous <STRONG>[OR]</STRONG>
+ rm -r libstdc++-v3</PRE>
</P>
<P>Next, unpack the libstdc++-v3 library tarball into this
<EM>gccsrcdir</EM> directory; it will create a
<P><PRE>
cd <EM>gccbuilddir</EM>
- <EM>gccsrcdir</EM>/configure --prefix=<EM>destdir</EM> --enable-libstdcxx-v3</PRE>
- </P>
-
- <P>Adding <TT>--enable-libstdcxx-v3</TT> automatically selects libstdc++-v3
- as the C++ library to be used alongside the C++ compiler being built,
- and also enables -fhonor-std by default. This option is not available
- with gcc-2.95.2.
+ <EM>gccsrcdir</EM>/configure --prefix=<EM>destdir</EM> --other-opts...</PRE>
</P>
This will configure and build the C++ library in the
<EM>gccbuilddir/cpu-vendor-OS/</EM>libstdc++ directory.
</P>
- <P>If the build fails with a "warning: can't inline call"
- message when compiling stringMAIN.cc, see <A HREF="#Werror">the
- resolution at the end of this document</A>.
- </P>
<P>If you are rebuilding from a previous build [attempt], some
information is kept in a cache file. This is stored in
<EM>gccbuilddir/cpu-vendor-OS/</EM> if you are building with
or
<PRE>
make install-gcc
- make install-target-<EM>libstdc++-rule</EM></PRE>
+ make install-target-libstdc++-v3</PRE>
</P>
include/g++-v3/
bits/
ext/
- cpu-vendor-OS/include/g++-v3/
+ CPU-vendor-OS/include/g++-v3/
bits/
ext/</PRE>
</P>
</P>
-<HR>
-<H3><A NAME="Werror"><TT>warning: can't inline call to</TT>...</A></H3>
- <P>When building the .8 snapshot with g++ 2.95.2, compilation may halt
- with this warning message. The "problem" is the -Werror
- flag being passed to the compiler, which says to treat warnings as
- errors. (This plus a high warning level makes us track down bugs
- <EM>quickly</EM>.) The compiler can't inline a certain call, prints
- a warning, and dies.
- </P>
- <P>The workaround is to edit either <EM>libsrcdir</EM>/src/Makefile.in
- (before configuring) or <EM>bld-libstdc++</EM>/src/Makefile
- (after configuring). There's one line that reads
- <PRE>
- WERROR = -Werror</PRE>
- Delete the flag itself, so that the line reads
- <PRE>
- WERROR =</PRE>
- Then the compiler will still print a warning, but it won't die.
- </P>
- <P>For the curious, this "problem" is actually a symptom
- of something else. The compiler in CVS could inline more than what
- 2.95.2 does, and the libstdc++ changes were made with that
- compiler. One of the libstdc++ maintainers explains this
-<A HREF="http://gcc.gnu.org/ml/libstdc++/2000-q1/msg00420.html">here</A>.
- </P>
- <P>This has been patched in current CVS sources.
- </P>
-
-
<!--
<HR>
<H2><A NAME=""></A></H2>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:pme@sources.redhat.com">Phil Edwards</A> or
<A HREF="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</A>.
-<BR> $Id: install.html,v 1.2 2001/01/21 09:36:09 pme Exp $
+<BR> $Id: install.html,v 1.3 2001/01/23 17:02:26 pme Exp $
</EM></P>
projects / gcc.git / commitdiff