
            $Id$

               STDCXX - Apache C++ Standard Library 4.1.3
          (based on Rogue Wave(R) C++ Standard Library 4.1.3)
          ---------------------------------------------------

  i. Disclaimer
  -------------

  STDCXX  is an effort  undergoing incubation  at the  Apache Software
  Foundation (ASF), sponsored by  the Apache Incubator PMC. Incubation
  is required  of all newly  accepted projects until a  further review
  indicates  that  the  infrastructure, communications,  and  decision
  making  process have stabilized  in a  manner consistent  with other
  successful ASF projects.  While incubation status is not necessarily
  a reflection of  the completeness or stability of  the code, it does
  indicate that the project has yet to be fully endorsed by the ASF.


  0  Index
  --------

  Index ............................................................ 0
  Contents ......................................................... 1
  Requirements ..................................................... 2
  Unpacking Instructions ........................................... 3
  Directory Structure ...............................................4
    Source Directory Structure ................................... 4.1
    Library Files ................................................ 4.2
    Library Utilities ............................................ 4.3
    Locales ...................................................... 4.4
    Test Suite Files ............................................. 4.5
    Examples and Tutorials ....................................... 4.6
    Build Directory Structure .................................... 4.7
  Library Build Instructions ....................................... 5
    VisualStudio Setup Instructions .............................. 5.1
  Library Installation ............................................. 6
  Test Suite Build Instructions .................................... 7
    VisualStudio Test Suite Build Instructions ................... 7.1
  Library Configuration ............................................ 8
    Header config.h .............................................. 8.1
    Headers rw/_config.h and rw/_defs.h .......................... 8.2
    Configuration Macros ......................................... 8.3
      Platform Identification Macros ........................... 8.3.1
      Compiler Configuration Macros ............................ 8.3.2
      Runtime Library Configuration Macros ..................... 8.3.3
      C Library Configuration Macros ........................... 8.3.4
      Macros Controlling Strings ............................... 8.3.5
      Macros Controlling Iostreams ............................. 8.3.6
      Macros Controlling Locale ................................ 8.3.7
      Macros Controlling Implementation Properties ............. 8.3.8
      Other Configuration Macros ............................... 8.3.9
      Macros Controlling Extensions ........................... 8.3.10
  Library Organization ............................................. 9
    Organization of Headers ...................................... 9.1 
    Organization of Sources ...................................... 9.2
  Platform Notes .................................................. 10
    Apogee C++ .................................................. 10.1
    Borland C++ ................................................. 10.2
    Comeau C++ .................................................. 10.3
    Compaq C++ .................................................. 10.4
    EDG eccp .................................................... 10.5
    GNU gcc ..................................................... 10.6
    HP aCC ...................................................... 10.7
    IBM VisualAge C++ ........................................... 10.8
    Intel C++ ................................................... 10.9
    KAI C++ .................................................... 10.10
    Metrowerks CodeWarrior ..................................... 10.11
    Microsoft MSVC ............................................. 10.12
    SGI MIPSpro ................................................ 10.13
    Siemens CDS++ .............................................. 10.14
    Sun C++ .................................................... 10.15


  1  Contents
  -----------

  This  file is  part of  the STDCXX  distribution of  the  Apache C++
  Standard  Library.  The  distribution consists  of this  file  and a
  compressed (gzipped) tar file containing the header and source files
  comprising  the  Rogue  Wave  implementation  of  the  C++  Standard
  Library,  the configuration mechanism  required to  characterize the
  platform on which  the library is to be built, and  a set of scripts
  and makefiles to build the library.

  Optionally,  the  distribution  may  also  contain  the  Apache  C++
  Standard Library test suite, a set of examples demonstrating the use
  of the library, plus scripts and makefiles to build and run the test
  suite and the examples.

  The  audience  targeted by  this  document  is library  maintainers,
  developers,  and those porting  the library  to new  platforms.  The
  purpose  of the document  is to  describe in  detail the  process of
  unpacking, configuring, building, and testing the library.


  2  Requirements
  ---------------

  The following utilities are required in addition to the standard set
  of POSIX  utilities in order to  unpack and build  the library, test
  suite (*), and examples (*) on a UNIX system.

  * Where available.

  o  GNU gunzip
  o  GNU make, version 3.70 or later (referred to as gmake here)
  o  GNU gcc, version 2.95.2 or later, or
  o  EDG eccp 2.42 or later, or
  o  Comeau C++ 4.2.42 or later, or
  o  HP aCC 3.13 or later for PA-RISC, or
  o  HP aCC 5.36 or later for IPF, or
  o  Intel C++ 7.0 or later for Linux/IA32 or IA64, or
  o  Compaq C++ 6.2 or later for Tru64 UNIX, or
  o  IBM VisualAge 5.0 or later for AIX 4.3 or later
  o  SGI MIPSpro 7.3 or later for IRIX
  o  Sun C++ 5.3 or later for SunOS 5.6 or later


  3  Unpacking Instructions
  -------------------------

  To unpack the tarball, execute the following command:

  $ gunzip -c stdcxx-incubating-X.Y.Z-YYYYMMDD.tar.gz | tar -xf -

  Above, X, Y, and Z are the major, minor, and micro version number of
  the library,  respectively, and the  optional -YYYYMMDD part  is the
  date of the snapshot. The date part of the file name will be missing
  if the tarball is a final release rather than a snapshot.

  The  script  above will  expand  the  tarball  and create  a  single
  directory named stdcxx-X.Y.Z-YYYYMMDD/  (with the date part possibly
  missing). This  directory is referred to a  ${TOPDIR} throughout the
  rest of this document.


  4  Source Directory Structure
  -----------------------------

  The infrastructure  described in  this document expects  that source
  files  and any  support scripts  are organized  in a  directory tree
  described below. If  the files are arranged otherwise  you will need
  to move  them to  the expected directories  in order  to accommodate
  this  requirement  and  use  the infrastructure.  The  shell  script
  fixtree.sh that resides  in the config/ subdirectory can  be used to
  create the required directory structure from the alternate structure
  (not described here).

      ${TOPDIR}/GNUmakefile           master makefile
       +- etc/
       |  +- config/GNUmakefile.*     makefiles
       |  |  |     /*.config          compiler config files
       |  |  |     /fixtree.sh        directory tree configuration
       |  |  |                        script
       |  |  |     /makefile.*        common definitions and rules
       |  |  |     /runall.sh         testsuite run script
       |  |  +- src/                  configuration sources and
       |  |  |                        scripts
       |  |  +- windows/generate.wsf  solution generation script
       |  |            /configure.wsf configuration script
       |  |            /build.wsf     solution build script
       |  |            /makelog.wsf   log creation script
       |  |            /runall.wsf    testsuite run script
       |  |            /*.js          utility scripts
       |  |            /*.config      compiler config files
       |  +- nls/                     locale definitions and
       |     |                        charmaps
       |     +- charmaps/             character set description files
       |     +- src/                  locale definition files
       +- examples/                   set of examples and tutorials
       |  +- include/*.h              common example headers
       |  +- manual/*.cpp             example sources
       |  +- tutorial/*.cpp           tutorial sources
       +- include/*                   public library headers
       |  +- ansi/*                   C++ C library headers
       |  +- loc/_*.{h,c,cc}          private locale headers
       |  +- rw/_*.{h,c,cc}           other private library headers
       +- src/*.cpp                   library sources
       +- util/*.{h,c,cc,cpp}         utility headers and sources
       +- tests/                      test suite files
       |  +- include/*.h              common test headers
       |  +- */*.cpp                  test suite sources
       +- ../rwtest                   test suite infrastructure
             +- rw/
             |  +- rwtest/*.h         test suite infrastructure
             |                        headers
             +- src/*.cpp             test suite infrastructure
                                      sources


  4.1  Library Files
  ------------------

  The public interface to the library consists of the following header
  files specified by the C++ International Standard:

    +------------+------------+------------+------------+------------+
    |<algorithm> |<iomanip>   |<list>      |<ostream>   |<streambuf> |
    +------------+------------+------------+------------+------------+
    |<bitset>    |<ios>       |<locale>    |<queue>     |<string>    |
    +------------+------------+------------+------------+------------+
    |<complex>   |<iosfwd>    |<map>       |<set>       |<typeinfo>  |
    +------------+------------+------------+------------+------------+
    |<deque>     |<iostream>  |<memory>    |<sstream>   |<utility>   |
    +------------+------------+------------+------------+------------+
    |<exception> |<istream>   |<new>       |<stack>     |<valarray>  |
    +------------+------------+------------+------------+------------+
    |<fstream>   |<iterator>  |<numeric>   |<stdexcept> |<vector>    |
    +------------+------------+------------+------------+------------+
    |<functional>|<limits>    |            |            |            |
    +------------+------------+------------+------------+------------+

  These   header  files  are   contained  in   the  ${TOPDIR}/include/
  directory.  Some of them have  corresponding .cc and .c files in the
  same directory.  Those are private files that contain definitions of
  out of line template functions, member functions of class templates,
  or static data members of class templates.

  The  facilities  of the  Standard  C  library  are exposed  via  the
  following  header files  (along with  their deprecated  forms, i.e.,
  files having the same name except for the leading letter 'c' and the
  .h suffix) contained in the ${TOPDIR}/include/ansi/ directory:

    +------------+------------+------------+------------+------------+
    |<cassert>   |<ciso646>   |<csetjmp>   |<cstdio>    |<ctime>     |
    +------------+------------+------------+------------+------------+
    |<cctype>    |<climits>   |<csignal>   |<cstdlib>   |<cwchar>    |
    +------------+------------+------------+------------+------------+
    |<cerrno>    |<clocale>   |<cstdarg>   |<cstring>   |<cwctype>   |
    +------------+------------+------------+------------+------------+
    |<cfloat>    |<cmath>     |<cstddef>   |            |            |
    +------------+------------+------------+------------+------------+

  Any  other  header  files  not  mandated by  the  C++  Standard  are
  contained  in the include/rw/ or include/loc  subdirectories.  Their
  names start  with an underscore,  to prevent potential  clashes with
  any user  headers, and end  in a .h  suffix.  Some of them  may have
  corresponding .c and .cc files.

  In  addition to  header  files, the  library  consists of  a set  of
  private  source files.   Source  files may  have  a .cpp,  .s or  .S
  extension  (for  C++  or  assembly  source,  respectively)  and  are
  contained in the src/ subdirectory of the library source tree.


  4.2  Library Utilities
  ----------------------

  Two utility programs  are provided in complete source  form with the
  library sources:  locale and localedef. The header  and source files
  for these utilities are  contained in the ${TOPDIR}/util/ directory.
  The  localedef  utility  is   used  to  build  locales  from  locale
  definition  files  and  character  set  description  files.  Locales
  generated by the utility can be  read by the locale utility and used
  by the Apache C++ Standard Library's localization library.


  4.3  Locales
  ------------

  Locale  definition files  suitable for  processing by  the localedef
  utility     are    provided     in    the     ${TOPDIR}/etc/nls/src/
  directory. Character set description files that accompany the locale
  definition  files are  provided  in the  ${TOPDIR}/etc/nls/charmaps/
  directory. These files are copies of those distributed with GNU libc
  2.2.


  4.4  Test Suite Files
  ---------------------

  The test  suite consists of a  set of two components:  a test driver
  library, rwtest,  and a set of headers, in ${TOPDIR}/tests/include/,
  and   many   source   files,   in   several   subdirectories   under
  ${TOPDIR}/tests/. 

  Each test program links with  the test driver library which contains
  code  for command line  processing. When  run, tests  produce output
  files which can be read  and analyzed by the run_all.sh script found
  in the ${TOPDIR}/etc/config/ directory. The script presents the test
  results  in a  tabular format.  For  more information  refer to  the
  script's help output.


  4.5  Examples and Tutorials
  ---------------------------

  A  set of  example  and tutorial  files  may be  provided under  the
  ${TOPDIR}/examples/  directory,   in   subdirectories  manual/   and
  tutorial/.   Most but  not  all example  programs  expect input  and
  produce output. Sets  of input and output files  are provided in the
  in/ and out/ subdirectories, respectively.


  4.6  Build Directory Structure
  ------------------------------

  The  directory tree created  and partially  populated by  the master
  makefile, ${TOPDIR}/GNUmakefile, has the following structure (the ->
  symbol indicates  a symbolic link from  the file on the  left to the
  one on the right):

      ${BUILDDIR}/GNUmakefile  -> ${TOPDIR}/GNUmakefile
       |       /makefile.in
       |       /makefile.common-> ${TOPDIR}/makefile.common
       |       /makefile.rules -> ${TOPDIR}/makefile.rules
       |       /run            -> ${TOPDIR}/etc/config/runall.sh
       +- bin/GNUmakefile      -> ${TOPDIR}/etc/config/GNUmakefile.bin
       |     /*.{o,...}           binaries and temporary files
       |     /.depend/*.d         dependencies
       +- examples/GNUmakefile -> ${TOPDIR}/etc/config/GNUmakefile.exm
       |          /run         -> ${TOPDIR}/etc/config/runall.sh
       |          /*.{o,...}      binaries and temporary files
       |          /.depend/*.d    dependencies
       +- include/GNUmakefile  -> ${TOPDIR}/etc/config/GNUmakefile.cfg
       |         /config.h        generated config header
       |         /*.{o,...}       binaries and temporary files
       |         /.depend/*.d     dependencies
       +- lib/GNUmakefile      -> ${TOPDIR}/etc/config/GNUmakefile.lib
       |     /*.{a,o,so,...}      binaries and temporary files
       |     /.depend/*.d         dependencies
       +- nls/*                -> binary locale files
       +- rwtest/GNUmakefile.rwt->${TOPDIR}/etc/config/GNUmakefile.rwt
       |     /*.{a,o,so,...}      binaries and temporary files
       |     /.depend/*.d         dependencies
       .
       . ...test suite directories are optional...
       .
       +- plumhall/GNUmakefile -> ${TOPDIR}/etc/config/GNUmakefile.ph
       |          /*.{d,o,...}    binaries and temporary files
       +- tests/GNUmakefile    -> ${TOPDIR}/etc/config/GNUmakefile.tst
               /*.{o,...}         binaries and temporary files
               /.depend/*.d       dependencies


  5  Library Build Instructions
  -----------------------------

  To build the library, test  suite (*), and examples (*), perform the
  following steps: (* Where available.)

  o  $ cd stdcxx-X.Y.Z-YYYYMMDD/
     $ ls   # this is ${TOPDIR}
     GNUmakefile  etc  examples  include  src  tests

     If your distribution  does not contain the test  suite and/or the
     examples, the output will look like so:

     $ ls   # this is ${TOPDIR}
     GNUmakefile  etc  include  src

  o  $ gmake BUILDDIR=<build-dir>         \
             [   BUILDTYPE=<build-type>   \
               | BUILDMODE=<build-mode> ] \
             [ CONFIG=<config-file> ]

     <build-dir> is the pathname of the build directory where you want
                 to perform the build; the directory will be created
                 (as will all its required subdirectories)
                 this is a required argument

     <build-type> is one of {
                      8s, 8d, 11s, 11d, 12s, 12d, 15s, 15d,
                      8S, 8D, 11S, 11D, 12S, 12D, 15S, 15D
                  }

                  The  numeric  part  of <build-type>  determines  the
                  presence  or  absence   of  support  for  debugging,
                  whether  optimization is or  isn't enabled,  and the
                  thread safety level of the library, as follows:

                  --  optimization enabled: even  numbers (i.e., 8 and
                      12) 
                  --  debugging enabled: odd numbers (i.e., 11 and 15)
                  --  thread safe code: 12 and 15

                  The  single  letter following  the  numeric part  of
                  <build-type> determines whether an archive or shared
                  library is  built, and whether  narrow (32-bit) code
                  or wide (64-bit) code should be generated:

                  --  s and S implies an archive library 
                  --  d and D implies a shared library
                  --  lowercase letter implies narrow (32-bit) code
                  --  capital letter implies wide (64-bit) code

                  The  <build-type>  argument  is optional.  When  not
                  specified a build type of 11s is assumed.

    <build-mode> is a comma-separated list of keywords describing how
                 to build the library and the rest of the
                 binaries. The following arguments are recognized:

                 dcethreads - create a thread-safe library, use DCE
                              threads
                 debug - include debugging information
                 optimized - optimized
                 pthreads - create a thread safe library, use POSIX
                            threads
                 shared - create a shared library (archive is default)
                 shared,archive - create an AIX shared archive
                 threads - create a thread-safe library, use Solaris
                           threads
                 wide - generate wide (64-bit) code

    Note that exactly one of BUILDTYPE and BUILDMODE must be defined.
                   
    <config-file> name (not pathname) of a config file containing
                  compiler options; the available configuration files
                  are:
                  acc.config      - for HP aCC
                  como.config     - for Comeau C++
                  eccp.config     - for EDG eccp
                  gcc.config      - for gcc
                  icc.config      - for Intel C++ on Linux
                  mipspro.config  - for SGI MIPSpro
                  osf_cxx.config  - for Compaq C++
                  reliant_cds.config - for Siemens CDS++
                  sunpro.config   - for Sun C++
                  vacpp.config    - for IBM VisualAge C++ and XL C/C++
                  this argument is optional, the default is gcc.config

  o  Example:
       $ gmake BUILDDIR=/tmp/g++-15d   \
               BUILDTYPE=15d           \
               CONFIG=gcc.config

       or equivalently

       $ gmake BUILDDIR=/tmp/g++-15d             \
               BUILDMODE=debug,shared,pthreads   \
               CONFIG=gcc.config

     This command will create a build directory rooted at ${BUILDDIR},
     run  the configuration  scripts, and  build a  thread-safe shared
     library  with   debugging  information  included   and  debugging
     facilities enabled.  If the build is successful, the library will
     be    located   in   ${BUILDDIR}/lib/    and   will    be   named
     libstd${BUILDTYPE}.so.X.Y.Z (libstd${BUILDTYPE}.a  if building an
     archive).   A symbolic  link named  libstd${BUILDTYPE}.so  in the
     same  directory  will also  be  created  pointing  to the  shared
     library. Public library headers are in ${TOPDIR}/include/ and its
     subdirectories,     the      generated     config.h     is     in
     ${BUILDDIR}/include/.

  o  To  change  preprocessor, compiler,  or  linker  options you  can
     either set the make variables CPPOPTS, CXXOPTS, and LDOPTS on the
     command  line  (recommended,  except   with  HP  aCC)  or  modify
     ${BUILDDIR}/makefile.in.  The  second option is  recommended when
     compiling  with HP  aCC (as  the compiler  looks  for environment
     variables with the same names).

  o  To reconfigure and/or rebuild the library (perhaps after changing
     a preprocessor, compiler, or linker option), follow these steps:

     $ cd ${BUILDDIR}
     $ gmake -Cinclude [ config ]   # configure
     $ gmake config                 # same
     $ gmake lib                    # build the library
     $ gmake examples               # build examples
     $ gmake util                   # build utility programs
     $ gmake rwtest                 # build the test driver
     $ gmake tests                  # build tests
     $ gmake locales                # build locale databases

     Alternatively, you can cd  into the respective subdirectories and
     just type gmake:

     $ (cd ${BUILDDIR}/include && gmake)     # configure
     $ (cd ${BUILDDIR}/lib && gmake)         # build the library
     $ (cd ${BUILDDIR}/bin && gmake)         # build utilities
     $ (cd ${BUILDDIR}/examples && gmake)    # build examples
     $ (cd ${BUILDDIR}/tests && gmake)       # build tests
     $ (cd ${BUILDDIR}/bin && gmake locales) # build locale databases

     Parallel  builds  (gmake -j[N])  are  possible  in any  directory
     except for ${BUILDDIR}/include/.

     To remove intermediate files from the build directory, use one of
     the following commands:

     $ cd ${BUILDDIR}
     $ gmake clean       # remove all object files
     $ gmake dependclean # remove .d files (dependencies)
     $ gmake realclean   # remove all temporary files


  5.1  VisualStudio Setup Instructions
  ------------------------------------

  To generate a Microsoft VisualStudio solution (for .NET 2003 or 2005
  only) follow the step below.

  o  > CD stdlib-X.Y.Z-YYYYMMDD\stdlib
     > DIR /D  # this is ${TOPDIR}
     GNUmakefile  etc  examples  generate.bat include  src  tests

     If your distribution  does not contain the test  suite and/or the
     examples, the output will look like so:

     > DIR /D  # this is ${TOPDIR}
     GNUmakefile  etc  generate.bat include  src

  o  > .\generate.bat /BUILDDIR:<builddir> /CONFIG:<config>

     <builddir> is the pathname of the build directory where to create
                the solution  and  projects;  the  directory  will  be
                created  (as will  all  its  required  subdirectories)
                this is a required argument
     <config>   name  (not  pathname)  of  a  config  file  containing
                compiler options; the available configuration files
                are:
                icc-9.0.config  - for Intel C++ 9.0
                icc-9.1.config  - for Intel C++ 9.1
                msvc-7.0.config - for Microsoft Visual C++ .NET
                msvc-7.1.config - for Microsoft Visual C++ .NET 2003
                msvc-8.0.config - for Microsoft Visual C++ .NET 2005
                msvc-8.0-x64.config - for Microsoft Visual C++ .NET
                                      2005 (x64 platform)
                msvcex-8.0.config - for Microsoft Visual C++ Express
                                    2005
                this is a required argument

  o  Example:
       > generate.bat /BUILDDIR:C:\stdcxx /CONFIG:msvc-7.1

     This command will create a build directory rooted at ${BUILDDIR},
     the solution file  ${BUILDDIR}\msvc-7.1\msvc-7.1.sln, the project
     files in directory  ${BUILDDIR}\msvc-7.1\Projects, and batch file
     ${BUILDDIR}\build_msvc-7.1.bat.

  To build the library, test  suite (*), and examples (*), perform the
  following steps: (* Where available.)

  o  > cd ${BUILDDIR}

  o  > build_msvc-7.1.bat [<build-types>]

     <build-types> is one or more of {
                      8s, 8d, 11s, 11d, 12s, 12d, 15s, 15d
                  }

                  The  numeric  part  of <build-type>  determines  the
                  presence  or  absence   of  support  for  debugging,
                  whether  optimization is or  isn't enabled,  and the
                  thread safety level of the library, as follows:

                  --  optimization enabled: even  numbers (i.e., 8 and
                      12) 
                  --  debugging enabled: odd numbers (i.e., 11 and 15)
                  --  thread safe code: 12 and 15

                  The  single  letter following  the  numeric part  of
                  <build-type> determines  whether a static or dynamic
                  library is  built:

                  --  s implies an static library 
                  --  d implies a dynamic library

                  The <build-types>  argument  is optional.  When  not
                  specified a build type of 11s is assumed.

  o  Example:
       > build_msvc-7.1.bat 15d

     run  the configuration  scripts, and  build a thread-safe dynamic
     library  with   debugging  information  included   and  debugging
     facilities enabled.  If the build is successful, the library will
     be  located in ${BUILDDIR}\msvc-7.1\${BUILDTYPE}\lib\ and will be
     named libstd${BUILDTYPE}.dll  (libstd${BUILDTYPE}.lib if building
     a   static    library).    Public   library    headers   are   in
     ${TOPDIR}\include\ and its subdirectories, the generated config.h
     is in ${BUILDDIR}\msvc-7.1\${BUILDTYPE}\include\.

     Alternatively,  you can run Microsoft Visual Studio IDE,  open the
     generated solution file, select the desired solution configuration
     and invoke "Build"->"Build Solution" command.

  6  Library Installation
  -----------------------

  There  is no  automated  way  of installing  the  library binary  or
  headers.   To   install,  simply   copy  the  library   binary  from
  ${BUILDDIR}/lib/  into   the  directory   of   your  choice   (e.g.,
  /usr/local/lib)  and   copy  the  library   headers  (including  any
  implementation  .c and  .cc  files) from  ${TOPDIR}/include/ and its
  subdirectories to  the directory of  your choice. Make sure  to also
  copy  the  generated ${BUILDDIR}/include/config.h  into  one of  the
  directories in your preprocessor's search path.

  When  using   locale  databases,  also   copy  the  ${BUILDDIR}/nls/
  directory to wherever appropriate.

  For example,  to install the library binaries  (including the locale
  databases)    in    /usr/local/lib/,   and   the    headers    under
  /usr/local/include/ perform the following steps:

  $ cp ${BUILDDIR}/lib/*.a    \
       ${BUILDDIR}/lib/*.so   \
       ${BUILDDIR}/lib/*.so.* \
       /usr/local/lib
  $ cp -R ${BUILDDIR}/nls /usr/local/lib
  $ cp ${BUILDDIR}/include/config.h /usr/local/include
  $ cp -R ${TOPDIR}/include/* /usr/local/include

  When using the  installed library be sure to  define any macros also
  defined on the  command line when building the  library.  These are:
  _RWSTDDEBUG to  enable debugging support in the  library; when using
  compilers that do  not provide an option to  enable thread safety or
  to select a thread library, the following macros may also have to be
  defined:        _RWSTD_POSIX_THREADS,        _RWSTD_SOLARIS_THREADS,
  _RWSTD_DCE_THREADS, and  _RWSTDDEBUG.  Failing to do  so, or failing
  to  specify  the  same  compiler  options  that  affect  the  binary
  compatibility  of the  library leads  to undefined  behavior  of the
  produced executables.


  7  Test Suite Build Instructions
  --------------------------------

  When  available,  the test  suite  can  be  built by  following  the
  following steps.

  o  $ cd ${BUILDDIR}
     $ gmake [ rwtest ][ tests ] [ examples ]

     The rwtest library is a prerequisite for the test programs (gmake
     rwtest).

     From  ${BUILDDIR}, you  can proceed  to build  the tests  and the
     examples, either individually  or all at the same  time.  You can
     either  navigate   into  the  respective   subdirectories  (i.e.,
     ${BUILDDIR}/tests/,  or ${BUILDDIR}/examples/)  and type  gmake [
     target  ]  to  build  there   or  you  can  build  directly  from
     ${BUILDDIR} by typing gmake tests or gmake examples.

     The  library  sources  and  headers  are expected  to  reside  in
     ${TOPDIR}/src/ and  ${TOPDIR}/include/, respectively, tests(*) in
     ${TOPDIR}/tests/ and  examples(*) in ${TOPDIR}/examples/.  The .d
     (dependencies) , .o (object) files and the executables are placed
     in the respective subdirectories of ${BUILDDIR}.

     * Where available. 

     To run the tests(*) or examples(*), cd into ${BUILDDIR}/tests/ or
     ${BUILDDIR}/examples/,  respectively, and  type  gmake run.   For
     best results you should be using  bash and an xterm. To make sure
     that you use  bash either set your SHELL  environment variable or
     set  the SHELL  makefile  variable  on the  command  line to  the
     pathname of bash on your system.

     By default, the  output of gmake run is  formatted and colorized.
     If your  terminal cannot deal  with the escape sequences  used to
     produce colors you can make it monochrome by setting your RUNOPTS
     make    variable   to    -m    on   the    command   line    (see
     ${TOPDIR}/etc/config/runall.sh for other options).

     * Where available. 


  7.1  VisualStudio Test Suite Build Instructions
  -----------------------------------------------

  When  available,  the test  suite  can  be  built by  following  the
  following steps.

  o  Run  Microsoft Visual Studio IDE,  open  the  generated  solution
     file and select the desired solution configuration.

     To build  the examples  select the  .stdcxx_examples  project and
     invoke "Build"->"Build .stdcxx_examples" command.

     To build  the tests select  the .stdcxx_tests  project and invoke
     "Build"->"Build .stdcxx_tests" command.

     To run  the examples  select the .stdcxx_runexamples  project and
     invoke "Build"->"Build .stdcxx_runexamples" command.

     To run  the tests select the .stdcxx_runtests  project and invoke
     "Build"->"Build .stdcxx_runtests" command.


  8  Library Configuration
  ------------------------

  8.1  config.h
  -------------

  The library  is configured (or reconfigured) for the platform (i.e.,
  the compiler  and operating system) it  is to be  built by executing
  the following command in the ${BUILDDIR}/include/ directory:

  $ gmake config

  This  command   generates  a  new   config.h  header  file   in  the
  ${BUILDDIR}/include/  directory (replacing an  existing one  only if
  the new  one differs) containing configuration  macros describing to
  the library the properties of the platform.


  8.2  rw/_config.h and rw/_defs.h
  --------------------------------

  The  generated config.h  header  is #included  by  a single  private
  library header, ${TOPDIR}/include/rw/_config.h.  The purpose of this
  header  is to provide  a central  place for  the maintainers  of the
  project to  manually override  the configuration macros  #defined in
  the automatically generated config.h (e.g., by #undefining them when
  they  are  #defined  incorrectly  or  vice  versa)  based  on  their
  knowledge of the platform. 

  The  header is  divided into  three sets  of sections:  one  for the
  hardware architecture, one for  each supported compiler, and one for
  each  supported  operating  system.   Each section  may  #define  or
  #undefine  object-like   configuration  macros.   As   a  matter  of
  convention, function-like macros are not #defined in this header.

  The ${TOPDIR}/rw/_config.h  header is #included by  a single library
  header, ${TOPDIR}/include/rw/_defs.h. The  purpose of this header is
  to #define convenience function-like  macros, typically based on the
  value of  one or more  object-like configuration macros  #defined in
  ${BUILDDIR}/include/config.h  and/or ${TOPDIR}/include/rw/_config.h,
  that  can then be  easily used  in the  library headers  and sources
  without   the  need   for  complicated,   hard-to-read  preprocessor
  conditionals.  The idea is that all the complicated, unsightly logic
  is tucked  away in  one central place  and the  rest of the  code is
  clean, even if obfuscated by macros.

  Every other library header, whether public or private, #includes the
  ${TOPDIR}/include/rw/_defs.h header.


  8.3  Configuration Macros
  -------------------------

  The library and  the testsuite make use of a  large number of macros
  to adjust  their interface and  behavior to the capabilities  of the
  compiler,  the underlying  C  libraries, and  the operating  system.
  Many   of   the  macro   definitions   are   generated  during   the
  autoconfiguration     of    the     library     and    placed     in
  ${BUILDDIR}/include/config.h. Some (but  not necessarily all) of the
  important macros  are described  here.  This list  is intended  as a
  reference for maintainers or porters of the library.

  The symbols  in square  brackets next to  the macros below  have the
  following meaning:

  - abi: Affects  the binary (ABI or functional)  compatibility of the
    library. The macro must be consistently #defined to the same value
    (or consistently #undefined) during the compilation of the library
    as well while using it.

  - auto: Automatically  determined and #defined  during configuration

  - lib: Affects  library builds.  The macro is  not to be  set except
    when building the library.

  - over:  May be #defined  or overridden  on the  command line  or by
    editing one  of the  two config headers  either when  building the
    library or when using it (except for those marked lib).

  In addition,  whenever a  macro with the  same root but  a different
  suffix  appears in  the  description a  modified regular  expression
  syntax has been used to abbreviate the list.


  8.3.1  Platform Identification Macros
  -------------------------------------

  The configuration infrastructure #defines a number of macros some of
  which can and should be used instead of similar such macros #defined
  by some compilers.

  o  _RWSTD_OS_<os-name>

     The name of the macro depends on the name of the operating system
     typically reported by the uname utility:

     _RWSTD_OS_AIX:    AIX
     _RWSTD_OS_HP_UX:  HP-UX
     _RWSTD_OS_IRIX64: IRIX
     _RWSTD_OS_LINUX:  Linux
     _RWSTD_OS_OSF1:   Tru64 UNIX
     _RWSTD_OS_SUNOS:  SunOS and Solaris

  o  _RWSTD_OS_SYSNAME

     This  macro expands  to a  string literal  with the  name  of the
     operating system (the output of uname).

  o  _RWSTD_OS_RELEASE

     This  macro expands  to a  string literal  with the  name  of the
     operating system release (the output of uname -r).

  o  _RWSTD_OS_VERSION

     This  macro expands  to a  string literal  with the  name  of the
     operating system version (the output of uname -v).

  o  _RWSTD_OS_MAJOR

     This macro  expands to  the major operating  system version  as a
     constant   integer   expressions   suitable   for  use   in   #if
     preprocessing directives.

  o  _RWSTD_OS_MINOR

     This macro  expands to  the minor operating  system version  as a
     constant   integer   expressions   suitable   for  use   in   #if
     preprocessing directives.

  o  _RWSTD_OS_MICRO

     This macro  expands to  the micro operating  system version  as a
     constant   integer   expressions   suitable   for  use   in   #if
     preprocessing directives.


  8.3.2  Compiler Configuration Macros
  ------------------------------------

  o  _RWSTD_NO_CONST_CAST [auto, over]
  o  _RWSTD_NO_DYNAMIC_CAST [auto, over]
  o  _RWSTD_NO_REINTERPRET_CAST [auto, over]
  o  _RWSTD_NO_STATIC_CAST [auto, over]

     #defined when  the respective cast  operator is not  available or
     does  not  function   properly.   In  such  cases,  the  ordinary
     (C-style) cast is used instead.

  o  _RWSTD_NO_EXCEPTION_SPECIFICATION [auto]

     #defined when  function exception specification  is not supported
     or   not   functioning    properly.    All   function   exception
     specifications in the source code are removed.

  o  _RWSTD_NO_EXPORT [auto, over]

     #defined when  the export keyword  is not supported  or  when the
     export feature does not work as expected.

  o  _RWSTD_NO_EXPORT_KEYWORD [auto, over]

     #defined when the export keyword is not supported.

  o  _RWSTD_NO_FUNCTION_TRY_BLOCK [auto]

     #defined when the function try block syntax is not supported.

  o  _RWSTD_NO_EXCEPTIONS [auto, lib]

     #defined when exceptions are  not supported or disabled.  All try
     keywords in the  source code are removed, catch  expands to while
     (0) with the  assumption that an optimizing  compiler will remove
     the block.

  o  _RWSTD_NO_EXPLICIT_INSTANTIATION [abi, auto, lib]

     #defined when explicit template instantiation isn't supported.

  o  _RWSTD_NO_EXPLICIT_CTOR_INSTANTIATION [auto]

     #defined when explicit template instantiation of constructors
     isn't supported.

  o  _RWSTD_NO_EXPLICIT_FUNC_INSTANTIATION [abi, auto, lib]

     #defined when explicit function template instantiation isn't
     supported.

  o  _RWSTD_NO_EXPLICIT_INSTANTIATION_BEFORE_DEFINITION [auto, lib]

     #defined when class templates cannot be explicitly instantiated
     lexically  before the definitions of all their  members defined
     outside their bodies.

  o  _RWSTD_NO_EXPLICIT_INSTANTIATION_WITH_IMPLICIT_INCLUSION [auto]

     #defined when explicit  template instantiation isn't supported in
     conjunction  with the implicit  inclusion of  template definition
     files (i.e., the .c or .cc files). 

  o  _RWSTD_NO_EXPLICIT_MEMBER_INSTANTIATION [auto]

     #defined when  the explicit instantiation of  member functions of
     class templates isn't supported.

  o  _RWSTD_NO_EXTERN_TEMPLATE [auto, over]

     When #defined, the extern template C++ extension is not supported
     by the compiler.

  o  _RWSTD_NO_IMPLICIT_INSTANTIATION [auto]

     #defined  when  the explicit  instantiation  of  a template  that
     references   another   template   doesn't  cause   the   implicit
     instantiation of the other template.

  o  _RWSTD_NO_INSTANTIATE_DEFAULT_ARGS

     #defined when  the explicit instantiation of  a function template
     with a default argument causes the instantiation of the argument.

  o  _RWSTD_NO_HONOR_STD

     #defined when namespace std  is not completely honored. The macro
     is typically only  #defined when using gcc versions  prior to 3.0
     without the -fhonor-std compiler option.

  o  _RWSTD_NO_ICONV_CONST_CHAR [auto]

     #defined at  configuration time  according to the  declaration of
     the POSIX function iconv().

  o  _RWSTD_NO_INLINE_MEMBER_TEMPLATES [auto, lib, over]

     #defined  at  configuration  time  for C++  implementations  that
     reject member templates completely defined within the body of the
     class or template of which they are a member.

  o  _RWSTD_NO_INSTANTIATE_DEFAULT_ARGS [auto, over]

     #defined  at  configuration  time  for C++  implementations  that
     instantiate  default arguments of  function templates  (or member
     functions  of   class  templates)  that  depend   on  a  template
     parameter.

  o  _RWSTD_NO_ISO_10646_WCHAR_T

     #defined for libc implementations that do not represent values of
     wchar_t  type in the  ISO 10646  encoding (essentially  UCS-4, or
     UNICODE).

  o  _RWSTD_NO_IMPLICIT_INCLUSION

     #defined  for the  compilers that  use the  Borland instantiation
     model. It  is also  defined in some  tests and  example programs
     that  have  a  code  layout  which is  incompatible  with  using
     implicit inclusion on AIX 5.1 with VisualAge for C++ 5.0.2.0. 

  o  _RWSTD_NO_INSTANTIATE [abi, lib, over]

     When  #defined the  library will  not explicitly  instantiate any
     class or function templates.

  o  _RWSTD_NO_LIB_EXCEPTIONS [auto, lib]

     #defined  at configuration  time  when exceptions  throws from  a
     library  cannot  be caught  in  a  program  that links  with  the
     library.

  o  _RWSTD_NO_LIST_NODE_BUFFER [abi, over]

     #defined to disable node buffer management of the class template
     std::list.

  o  _RWSTD_NO_LONG_LONG [abi, auto]

     #defined if the C99 type  long long is not supported or disabled,
     or when _RWSTD_STRICT_ANSI is #defined.

  o  _RWSTD_NO_MEMBER_EXPLICIT_INSTANTIATION [auto, over]

     #defined when  explicit instantiation of member  templates is not
      supported.

  o  _RWSTD_NO_MEMBER_TEMPLATES [abi, auto]

     #defined  when member  templates are  not supported.  The library
     tries to  provide alternative solutions  wherever possible.  Some
     loss of functionality is inevitable. 

  o  _RWSTD_REENTRANT [abi, auto, lib]

     #defined  for multi-thread  safe  build types  12[sd] and  15[sd]
      either automatically,  when the library  detects the usage  of a
      special compiler switch (e.g.  -mt on HP-UX and Sun/Solaris), or
      through   the  compiler   configurations  files   in etc/config/
      directory.

  o  _RWSTD_NO_MUTABLE [auto, over]

     #defined at  configuration time  for C++ implementations  that do
     not recognize the word mutable as a valid keyword.

  o  _RWSTD_NO_NAMESPACE [abi, auto, lib]

     #defined  when namespaces  are  not supported  or disabled.   All
     namespace-scope symbols defined in  the sources are introduced to
     the global  namespace. All using declarations  and directives are
     removed.

  o  _RWSTD_NO_NATIVE_BOOL [abi, auto, lib]

     #defined  for C++  implementations that  do not  treat bool  as a
     distinct fundamental type (but perhaps provide a typedef).

  o  _RWSTD_NO_NATIVE_WCHAR_T

     #defined  for C++  implementations that do not treat wchar_t as a
     distinct fundamental type (but perhaps provide a typedef).

  o  _RWSTD_NO_NEW_HEADER [auto, over]

     When  #defined,  files will  #include  the  deprecated C  library
     header files  rather than  the "new" C++  C library  files (e.g.,
     <string.h> rather than <cstring>). 

  o  _RWSTD_NO_NEW_CLASS_TEMPLATE_SYNTAX
  o  _RWSTD_NO_NEW_FUNC_TEMPLATE_SYNTAX
  o  _RWSTD_NO_NEW_TEMPLATE_SYNTAX
  o  _RWSTD_NO_NONCLASS_ARROW_RETURN
  o  _RWSTD_NO_NONDEDUCED_CONTEXT
  o  _RWSTD_NO_NONTYPE_ARGS
  o  _RWSTD_NO_NONTYPE_ARGUMENT_DEDUCTION

  o  _RWSTD_NO_PARTIAL_CLASS_SPEC [abi, auto]

     #defined  when partial  specialization of  class  templates isn't
     supported or isn't functional.

  o  _RWSTD_NO_PART_SPEC_OVERLOAD

  o  _RWSTD_NO_PRAGMA_INSTANTIATE [lib, over]

     #defined when the #pragma instantiate directive isn't supported.

  o  _RWSTD_NO_PRETTY_FUNCTION [auto, lib, over]

     #defined  when  the  __PRETTY_FUNCTION__  special  identifier  (a
     common extension) is not supported.

  o  _RWSTD_NO_PTR_EXCEPTION_SPEC [auto, over]

     #defined   when  declaring   function  pointers   with  exception
     specification is not supported.

  o  _RWSTD_NO_PTR_VALUE_TEMPLATE_OVERLOAD
  o  _RWSTD_NO_REDUNDANT_DEFINITIONS

  o  _RWSTD_NO_REDUNDANT_DEFINITIONS [over]

     When  #defined,  public  library  headers will  #include  only  a
     minimum set of  other library headers necessary in  order for the
     definitions  of templates  contained therein  to  compile without
     actually instantiating any of  them.  #defining the macro has the
     potential to decrease compile times.

  o  _RWSTD_NO_SETLOCALE_ENVIRONMENT [auto, lib]

     #defined when the C locale is  not affected by the setting of the
     LC_XXX environment variables.

  o  _RWSTD_NO_SIMPLE_DEFAULT_TEMPLATES
  o  _RWSTD_NO_SPECIALIZED_FRIEND
  o  _RWSTD_NO_STATIC_CONST_MEMBER_INIT
  o  _RWSTD_NO_STATIC_TEMPLATE_MEMBER_INIT

  o  _RWSTD_NO_STATIC_MUTEX_INIT [abi, auto, lib, over]

     #defined when  mutex objects with static  storage duration cannot
     be statically initialized  (3.6.2 [basic.start.init]) but must be
     initialized during dynamic initialization instead.  The macro has
     an impact on thread-safety of the library.

  o  _RWSTD_NO_TEMPLATE_DEFINITIONS [over]

     When #defined, public library header files containing definitions
     of iostream  and locale templates do not  explicitly #include the
     corresponding implementation .cc  files. This option considerably
     decreases compile times on platforms that do not support implicit
     file  inclusion.    The  macro   has  no  effect   when  explicit
     instantiation is  not supported.  The macro must  not be #defined
     when  specializations other  than those  provided by  the library
     binary are instantiated.

  o  _RWSTD_NO_TEMPLATE_TEMPLATE [auto]

     #defined when template template arguments aren't supported.

  o  _RWSTD_NO_THROW_SPEC_ON_NEW

     When #defined, overloads of  operators new and delete declared in
     the  public library  header  <new> do  not  include the  required
     exception specifications.

  o  _RWSTD_NO_TYPENAME [auto]

     #defined when they keyword typename isn't fully supported.

  o  _RWSTD_NO_COLLAPSE_STATIC_LOCALS [auto]

     #defined when  the compiler/linker fail to  collapse static local
     variables defined in a function template instantiated on the same
     type in multiple translation units into one.

  o  _RWSTD_NO_COLLAPSE_TEMPLATE_LOCALS [auto]

     #defined when  the compiler/linker fail to  collapse static local
     variables whose type depends on a template parameter and that are
     defined in a  function template instantiated on the  same type in
     multiple translation units into one.

  o  _RWSTD_NO_COLLAPSE_TEMPLATE_STATICS [auto]

     #defined when  the compiler/linker  fail to collapse  static data
     members  of a  class template  instantiated on  the same  type in
     multiple translation units into one.

  o  _RWSTD_NO_USING_LIBC_IN_STD

  o  _RWSTD_NO_VECTOR_BOOL

     When #defined the vector<bool> partial specialization is disabled
     and the primary template is used instead.


  8.3.3  Runtime Library Configuration Macros
  -------------------------------------------

  o  _RWSTD_NO_NEW_THROWS [auto]

     When  #defined,  operator  new  doesn't throw  an  exception  but
     instead returns 0 on failure. 

  o  _RWSTD_NO_{GLOBAL,STD}_BAD_{ALLOC,CAST,EXCEPTION,TYPEID}
  o  _RWSTD_NO_{GLOBAL,STD}_EXCEPTION
  o  _RWSTD_NO_{GLOBAL,STD}_NOTHROW[_T]
  o  _RWSTD_NO_{GLOBAL,STD}_SET_{NEW_HANDLER,TERMINATE,UNEXPECTED}
  o  _RWSTD_NO_{GLOBAL,STD}_TERMINATE
     [abi, auto, lib]

     The macros above are  #defined at configuration time according to
     which namespace (global or std) each type (or the object nothrow)
     is defined in by the language runtime library.

  o  _RWSTD_NO_{BAD_ALLOC,BAD_CAST,BAD_EXCEPTION,BAD_TYPEID}_{ASSIGNMENT,
     COPY_CTOR,DEFAULT_CTOR,DTOR,WHAT} [abi, auto, lib]

     Each  macro is  #defined when  the corresponding  member  of each
     respective class is not defined in the language support library.

  o  _RWSTD_NO_OPERATOR_{DELETE,NEW}[_ARRAY][{_NOTHROW,_PLACEMENT}]
     [auto, over]

     #defined  at  configuration  time  when  the  definition  of  the
     corresponding operator  does not  appear in the  compiler support
     library.   The library  will provide  the missing  definitions by
     default.   If  any  definition  (except for  the  non-replaceable
     placement  forms) needs to  be replaced, user code  should either
     #undefine    the   corresponding    macro   first    or   #define
     _RWSTD_NO_EXT_OPERATOR_NEW to disable all definitions provided by
     the library.

     The library is autoconfigured to  detect the level of support for
     these  operators  provided by  the  compiler.  The  configuration
     macros below  are #defined if and  only if the  functions are not
     found  in   the  compiler  support   (a.k.a.   language  runtime)
     library.  For  each  #defined  macro, the  C++  Standard  library
     defines the corresponding function in header <new>.

       [x]  _RWSTD_NO_OPERATOR_DELETE_ARRAY
       [x]  _RWSTD_NO_OPERATOR_DELETE_ARRAY_NOTHROW
       [ ]  _RWSTD_NO_OPERATOR_DELETE_ARRAY_PLACEMENT
       [x]  _RWSTD_NO_OPERATOR_DELETE_NOTHROW
       [ ]  _RWSTD_NO_OPERATOR_DELETE_PLACEMENT
       [x]  _RWSTD_NO_OPERATOR_NEW_ARRAY
       [x]  _RWSTD_NO_OPERATOR_NEW_ARRAY_NOTHROW
       [ ]  _RWSTD_NO_OPERATOR_NEW_ARRAY_PLACEMENT
       [x]  _RWSTD_NO_OPERATOR_NEW_NOTHROW
       [ ]  _RWSTD_NO_OPERATOR_NEW_PLACEMENT

     In  addition, however,  since the  functions  whose corresponding
     config macros above are marked [x] must be replaceable, and since
     it may  not be possible  to achieve the effect  of replaceability
     without    compiler    support,    the   user-controlled    macro
     _RWSTD_NO_EXT_OPERATOR_NEW  may be  manually #defined  to prevent
     the library  from defining  the functions if  a program  needs to
     replace them.

     Finally,  the macro  _RWSTD_NO_PLACEMENT_DELETE  may be  #defined
     (either by the library headers or, if not, by a program) if it is
     necessary  to disable declarations  and definitions  of placement
     forms of operator delete, e.g., due to a compiler limitation or a
     bug.

  o  _RWSTD_NO_PLACEMENT_DELETE [auto, over]

     When #defined, placement forms of ::operator delete() will not be
     declared (or defined) by the header <new>. Provided in case their
     declarations cause problems in user code.

  8.3.4  C Library Configuration Macros
  -------------------------------------

  o  _RWSTD_NO_LIBC_IN_STD [auto, over]

     When #defined, the names defined by the C library are expected to
     be found  in namespace  std.  Otherwise they  are expected  to be
     defined only in the global namespace.

  o  _RWSTD_NO_{CASSERT,CCTYPE,CERRNO,CFLOAT,CISO646,CLIMITS,CLOCALE,
                CMATH,CSETJMP,CSIGNAL,CSTDARG,CSTDDEF,CSTDIO,CSTDLIB,
                CSTRING,CTIME,CWCHAR,CWCTYPE} [auto]

     #defined  when  the  respective   header  is  not  found  in  the
     preprocessor search path.

  o  _RWSTD_NO_${FUN}[_IN_LIBC] [auto]

     #defined when  the extern "C" function ${FUN}  declaration is not
     found  in the  expected C  header, or  if the  extern  "C" symbol
     ${FUN} is not found in the libc binary.

  o  _RWSTD_NO_{ABS,ACOS,ASIN,ATAN,ATAN2,CEIL,COS,COSH,EXP,FABS,FLOOR,
                FMOD,FREXP,LDEXP,LOG,LOG10,MODF,POW,POW,SIN,SINH,SQRT,
                TAN,TANH}{D,DBL,F,FLT,L,LDBL}[_IN_LIBM] [auto]

     #defined  when  the respective  functions  are  not found  during
     autoconfiguration in  the <math.h> header or in  the libm library
     binary.   For  example,  when   the  function  extern  "C"  float
     acosf(float) is  not declared in  <math.h> on a platform  but the
     symbol extern "C" acosf is  found in the libm library binary, the
     macro   _RWSTD_NO_ACOSF   will   be   #defined  but   the   macro
     _RWSTD_NO_ACOSF_IN_LIBM will be #undefined.

  o  _RWSTD_NO_PURE_C_HEADERS

  o  _RWSTD_NO_WCSFTIME_WCHAR_T_FMAT [auto]


  8.3.5  Macros Controlling Strings
  ---------------------------------

  o  _RWSTD_NO_STRING_MUTEX [abi, lib, over]

     When #defined std::basic_string objects are not reference counted.
  
  o  _RWSTD_ONE_STRING_MUTEX [abi, lib, over]

     When #defined std::basic_string  objects are reference counted. A
     single per-process mutex object is used for thread safety.


  8.3.6  Macros Controlling Iostreams
  -----------------------------------

  o  _RWSTD_NO_IOSTREAM_OBJECT_REFS [abi, auto, lib, over]

     When   #defined  while   _RWSTD_NO_STATIC_IOSTREAM_INIT   is  not
     #defined, the  eight standard  iostream objects (cout,  etc.) are
     declared  in  <iostream> to  be  of  their  respective types  but
     defined in the  library binary to be of an  unrelated POD type to
     prevent their destruction  during program lifetime.  Since object
     type isn't typically encoded in  its name and the declaration and
     definition  isn't   ever  seen  by  the  compiler   in  the  same
     translation unit this doesn't cause problems.

  o  _RWSTD_NO_NATIVE_IO [lib, over]

     #defined  to force  file streams  to use  the facilities  of libc
     stdio as opposed to the POSIX I/O interface.

  o  _RWSTD_DEFAULT_BUFSIZE [lib, over]

     #defined to  the size of the  character buffer used by objects of
     std::basic_filebuf<>, in characters. The default value is 512.

  o  _RWSTD_PBACK_SIZE [lib, auto]

     #defined  to  the size  of  the  basic_streambuf  putback area in
     characters. The default value is 4.

  o  _RWSTD_NO_REENTRANT_IO [abi, lib, over]

     #defined when the iostream library should not be thread-safe.

  o  _RWSTD_NO_REENTRANT_IO_DEFAULT [abi, lib, over]

     #defined  when  the  standard  iostream  objects  should  not  be
     thread-safe by default.

  o  _RWSTD_NO_STATIC_IOSTREAM_INIT [abi, auto, lib, over]

     When  #defined, the  eight standard  iostream  objects (std::cin,
     std::cout,  etc.)  are   ordinary  objects  with  static  storage
     duration  and  are   destroyed  during  program  lifetime  (which
     violates 27.3, p2).


  8.3.7  Macros Controlling Locale
  --------------------------------

  o  _RWSTD_NO_CAT_NAMES

     When #defined, combined locale names  do not include the names of
     locale categories. For example, on Solaris, combined locale names
     consist of the  name of each category in  a fixed order separated
     by slashes. On Linux, combined locale names, however, include the
     name of each category followed by the equals sign followed by the
     name  of  the locale,  with  the  categories  separated from  one
     another by a semicolon. E.g., "LC_CTYPE=C;LC_TIME=en;..."

  o  _RWSTD_NO_INITIAL_CAT_SEP [auto, lib]

     #defined  at configuration  time in  environments  where combined
     libc  locale  names do  not  begin  with  the character  used  to
     separate the names of  individual locale categories. For example,
     HP-UX 11.00 combined locale name has the  form "C C C en C C" but
     on  Solaris, the  equivalent  name would  be "/C/C/C/en/C/C".  On
     Solaris, then, the macro would be #defined.

  o  _RWSTD_CAT_SEP

     Expands to a character string that separates locale categories in
     combined  locale names  (such as  " "  on AIX  and HP-UX,  "/" on
     Solaris, or ";" on Linux).

  o  _RWSTD_NO_CAT_EQ

      When #defined, the names of locale categories in combined locale
      names  are not  separated from  the name  of the  locale  by the
      equals sign.

  o  _RWSTD_NO_CONDENSED_NAME

     When   #defined,  locale   names  always   include   all   locale
     categories,  even if they  are all  the same.  This is  true, for
     example, on HP-UX  when the name of the  "C" locale returned from
     setlocale (LC_ALL, 0) is "C C C C  C C" and not just "C" as it is
     on Solaris.

  o  _RWSTD_LDBL_PRINTF_PREFIX [auto, lib]

     #defined  the printf()  format modifier  as a string  literal for
     type  long double, when  supported. Typically,  the value  of the
     macro is "L".

  o  _RWSTD_NO_LDBL_PRINTF_PREFIX [auto, lib]

     #defined when no printf() format modifier for type long double is
     known.

  o  _RWSTD_LLONG_PRINTF_PREFIX [auto]

     #defined  the printf()  format  modifier as a string  literal for
     type long long, when supported. Typically, the value of the macro
     is "ll".

  o  _RWSTD_NO_LLONG_PRINTF_PREFIX [auto]

     #defined when no  printf() format modifier for type  long long is
     known.

  o  _RWSTD_EXPORT        [auto]
     _RWSTD_CLASS_EXPORT  [auto]
     _RWSTD_MEMBER_EXPORT [auto]

     These  three macros  control the  exporting of  symbols  from the
     library; the  latter two are used in  selectively controlling the
     exporting  of symbols  from  classes that  have member  templates
     (e.g. locale class).

  o  _RWSTD_NO_STRTOF_UFLOW   [auto, lib]
     _RWSTD_NO_STRTOD_UFLOW
     _RWSTD_NO_STRTOLD_UFLOW

     Each of these macros is #defined when the corresponding C library
     function fails to set errno (usually to ERANGE) on underflow.
 

  8.3.8  Macros Controlling Implementation Properties
  ---------------------------------------------------

  o  _RWSTD_BOOL_SIZE [abi, auto, lib]
     _RWSTD_CHAR_SIZE
     _RWSTD_SHRT_SIZE
     _RWSTD_INT_SIZE
     _RWSTD_LONG_SIZE
     _RWSTD_LLONG_SIZE
     _RWSTD_FLT_SIZE
     _RWSTD_DBL_SIZE
     _RWSTD_LDBL_SIZE
     _RWSTD_WCHAR_T_SIZE
     _RWSTD_PTR_SIZE
     _RWSTD_FUNPTR_SIZE   (function pointer)
     _RWSTD_MEMPTR_SIZE   (member pointer)

     Each of  the _RWSTD_<type>_SIZE macros above expands  to the size
     of the respective  fundamental type (as returned by  sizeof) as a
     constant   integer   expressions   suitable   for  use   in   #if
     preprocessing   directives.   If   no   such  type   exists   the
     corresponding macros are not #defined.

  o  _RWSTD_CHAR_BIT

     Expands  to   the  value  of  CHAR_BIT  as   a  constant  integer
     expressions suitable for use in #if preprocessing directives.

  o  _RWSTD_BOOL_{MAX,MIN}   [abi, auto, lib]
     _RWSTD_CHAR_{MAX,MIN}
     _RWSTD_SCHAR_{MAX,MIN}  (int)
     _RWSTD_UCHAR_{MAX,MIN}  (unsigned int)
     _RWSTD_SHRT_{MAX,MIN}   (int)
     _RWSTD_USHRT_{MAX,MIN}  (unsigned int)
     _RWSTD_INT_{MAX,MIN}
     _RWSTD_UINT_{MAX,MIN}
     _RWSTD_LONG_{MAX,MIN}
     _RWSTD_ULONG_{MAX,MIN}
     _RWSTD_LLONG_{MAX,MIN}
     _RWSTD_ULLONG_{MAX,MIN}
     _RWSTD_WCHAR_T_{MAX,MIN}   (int or long)
     _RWSTD_SIZE_{MAX,MIN}      (size_t)
     _RWSTD_PTRDIFF_{MAX,MIN}   (ptrdiff_t)
     _RWSTD_WINT_{MAX,MIN}      (wint_t)

     Each of  the _RWSTD_<type>_{MAX,MIN} macros above  expands to the
     maximum and minimum representable value in the respective integer
     type as  a constant integer  expressions suitable for use  in #if
     preprocessing  directives. Except  as  marked, the  type of  each
     macro is the corresponding type promoted according to the integer
     promotion rules.  If no such type exists the corresponding macros
     are not #defined.

  o  _RWSTD_INT8_T   [abi, auto, lib]
     _RWSTD_UINT8_T
     _RWSTD_INT16_T
     _RWSTD_UINT16_T
     _RWSTD_INT32_T
     _RWSTD_UINT32_T
     _RWSTD_INT64_T
     _RWSTD_UINT64_T

     Each of  the _RWSTD_INT<width>_T and  _RWSTD_UINT<width>_T macros
     above expands  to the signed  and unsigned, respectively,  type T
     for which (sizeof(T) * CHAR_BIT  == width) holds. If no such type
     exists the macro is not #defined. Note that each macro can expand
     to two or more tokens.

  o  _RWSTD_{FLT,DBL,LDBL}_{INF,SNAN,QNAN}_BITS [auto, lib]

     #defined at  configuration time to be the  byte representation of
     infinity, signaling NaN and  quiet NaN, respectively.  The macros
     are defined as brace-delimited arrays of chars.

  o  _RWSTD_{FLT,DBL,LDBL}_HAS_DENORM [auto, lib]

     #defined to 1 when the corresponding floating point type supports
     denormalized values and to 0 otherwise.

  o  _RWSTD_NO_DBL_TRAPS [auto, lib]

     #defined  when  values  of  type double  implement  trapping  for
      certain arithmetic operations (such division by zero).

  o  _RWSTD_NO_IEC559 [auto, over]

     #defined  at configuration  time  if it  is  determined that  the
     environment  fails to  satisfy the  requirements of  the  IEC 559
     standard.

  o  _RWSTD_NO_IEEEFP_H

  o  _RWSTD_NO_INFINITY [auto]

     #defined  at  configuration time  for  environments  that do  not
     support the concept of a floating point infinity.

  o  _RWSTD_NO_INT_TRAPS [auto, lib]

     #defined when  values of type int implement  trapping for certain
      arithmetic operations (such division by zero).

  o  _RWSTD_NO_NAN_TRAPS [auto, lib]

     #defined when the value NaN (Not a Number) causes a hardware trap
      when used in arithmetic expressions.

  o  _RWSTD_NO_SIGNALING_NAN


  8.3.9  Other Configuration Macros
  ---------------------------------

  o  _RWSTD_NO_OPTIMIZE_SPEED


  8.3.10  Macros Controlling Extensions
  -------------------------------------

  The  following options  are  provided to  allow  to disable  various
  library extensions. An extensions  is defined as a library interface
  or its behavior that is left unspecified by the standard or, in some
  rare  cases,  that is  specified  by  the  standard but  where  this
  implementation differs from the specification.

  In addition  to the  symbols in square  brackets defined  above, the
  symbol pure denotes  an extension that is not  conflict with the C++
  standard:

  o  _RWSTD_NO_EXTENSIONS [over]
  o  _RWSTD_STRICT_ANSI [over]

     When #defined, most library  extensions are disabled by #defining
     the  various  _RWSTD_NO_EXT_XXX  macros  documented  below.   The
     _RWSTD_STRICT_ANSI macro is deprecated and should be avoided.

  o  _RWSTD_NO_EXT_DEQUE_ASSIGN_IN_PLACE [over]
  o  _RWSTD_NO_EXT_DEQUE_INSERT_IN_PLACE [over]
  o  _RWSTD_NO_EXT_VECTOR_ASSIGN_IN_PLACE [over]
  o  _RWSTD_NO_EXT_VECTOR_INSERT_IN_PLACE [over]

     When  #defined,   the  multi-element  overloads   of  the  member
     functions assign()  and insert()  defined by the  class templates
     deque  and  vector  provide  the  basic  exception  guarantee  as
     required by the C++ Standard. Otherwise, when (size() >= N) holds
     for N being  the number elements being assigned  or inserted, and
     value_type's  assignment operator or  iterator operations  do not
     throw, the functions provide the nothrow exception guarantee.

  o  _RWSTD_NO_EXT_FILEBUF [pure, over]

     When    #defined,    extensions    to    the    class    template
     std::basic_filebuf and the std::basic_fstream family of templates
     are not available.

  o  _RWSTD_EXT_DEEP_STRING_COPY [pure]

     When  #defined,  the member  function  copy()  of class  template
     basic_string which  returns a deep  copy of the string  object is
     not declared.

  o  _RWSTD_NO_EXT_FAILURE [lib, over, pure]

     When #defined, disables  extensions to the std::ios_base::failure
     class  (i.e., the classes  std::ios_base::badbit_set, eofbit_set,
     and   failbit_set).   #defining  _RWSTD_STRICT_ANSI   causes  the
     #definition of this macro as well.

  o  _RWSTD_NO_EXT_BITSET_CTOR_CHAR_ARRAY [over, pure]

     When #defined,  disable the  declarations of the  two std::bitset
     constructor overloads  that take const char*  and const wchar_t*,
     respectively,  as  their  first  argument. The  purpose  of  this
     extension is to make it possible to construct std::bitset objects
     from string literals without dynamic memory allocation.

  o  _RWSTD_NO_EXT_BITSET_CTOR_STRING [over, pure]

     When  #defined, disable  the declaration  of the  two std::bitset
     constructor  overloads that  take  std::string and  std::wstring,
     respectively,  as  their  first  argument. The  purpose  of  this
     extension is to make it possible to construct std::bitset objects
     from string literals.

  o  _RWSTD_NO_EXT_BITSET_TO_STRING [over, pure]

     When #defined,  disables the declarations of  the three overloads
     of the  const member function  to_string() of the  class template
     std::bitset specified in LWG issue 434:
     http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#434

  o  _RWSTD_NO_EXT_BIN_IO [over, pure]

     When #defined,  disables support for  base 2 numerical  input and
     output  in iostreams  and the  std::num_get<>  and std::num_put<>
     facets, and  undefines the symbol  std::ios_base::bin.  #defining
     _RWSTD_STRICT_ANSI causes the #definition of this macro as well.

  o  _RWSTD_NO_EXT_IOS_SAFE_CONVERSION [over]

     When  #defined,  the  const member  function  operator void*() of
     the  class   template  basic_ios  is   declared.  Otherwise,  the
     resolution  of   the  Library   Working  Group's  issue   568  is
     implemented instead. See
     http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#468

  o  _RWSTD_NO_EXT_OPERATOR_NEW [auto, over]

     When #defined,  disables the replaceable  definitions provided in
     <new> for missing global  operators new and delete, allowing them
     to be defined by the user.

  o  _RWSTD_NO_EXT_PORTABLE_RANDOM_SEQUENCE [lib, pure]

     When  #defined,  the  random   number   generator  used  by  this
     implementation  of  the C++  Standard  Library generates  integer
     values  in the  full range  of the  type size_t.   Otherwise, the
     generator is  restricted to the  range of unsigned  32-bit values
     for data portability.

  o  _RWSTD_NO_EXT_REENTRANT_IO [over, pure]

     When #defined, disables support  for user-control of iostream and
     streambuf     locking,      and     undefines     the     symbols
     std::ios_base::nolock    and    std::ios_base::nolockbuf.    Only
     relevant  in  thread-safe  builds.  #defining  _RWSTD_STRICT_ANSI
     causes the #definition of this macro as well.

  o  _RWSTD_NO_EXT_SETBASE

     When  #defined,  the std::setbase  manipulator  accepts only  the
     required  numeric  bases  (i.e.,  0,  8, 10,  16,  and  2  unless
     _RWSTD_NO_EXT_BIN_IO is also #defined).

  o  _RWSTD_NO_EXT_VOID_COUNT [over, pure]

     When  #defined,  disables  the  non-conforming  versions  of  the
     std::count()  and std::count_if()  algorithms that  take  four or
     five arguments, respectively, and return void. The algorithms are
     provided for  backward compatibility or on  platforms that cannot
     handle partial  specialization of class templates.  The macro has
     no effect if partial specialization is not supported.

  o  _RWSTD_NO_EXT_VOID_DISTANCE [over, pure]

     When  #defined,  disables   the  non-conforming  version  of  the
     std::distance() algorithm that  takes three arguments and returns
     void. The algorithm is  provided for backward compatibility or on
     platforms  that  cannot handle  partial  specialization of  class
     templates. The  macro has no effect if  partial specialization is
     not supported.

  o  _RWSTD_NO_REENTRANT_IO_DEFAULT [lib, over, pure]

     When  #defined  in  thread-safe  builds,  all  newly  constructed
     iostream objects (i.e., other  than the standard iostream objects
     std::cin,   std::cout,   etc.)   are   created   with  the   bits
     std::ios_base::lock  and  std::ios_base::lockbuf  set (i.e.,  the
     same    object   will    be   safe    to   use    across   thread
     boundaries). Otherwise,  the are created with the  bits set.  Has
     no  effect  if   _RWSTD_NO_EXT_REENTRANT_IO  is  #defined  or  in
     non-thread-safe builds.

  o  _RWSTD_NO_EXT_CHAR_TRAITS_PRIMARY [over, pure]
  o  _RWSTD_NO_EXT_CODECVT_PRIMARY [over, pure]
  o  _RWSTD_NO_EXT_CTYPE_PRIMARY [over, pure]
  o  _RWSTD_NO_EXT_COLLATE_PRIMARY [over, pure]
  o  _RWSTD_NO_EXT_MONEYPUNCT_PRIMARY [over, pure]
  o  _RWSTD_NO_EXT_NUMPUNCT_PRIMARY [over, pure]
  o  _RWSTD_NO_EXT_TIME_GET_PRIMARY [over, pure]
  o  _RWSTD_NO_EXT_TIME_PUT_PRIMARY [over, pure]
  o  _RWSTD_NO_EXT_MESSAGES_PRIMARY [over, pure]

     When  #defined,  the  corresponding  primary  template, which  is
     otherwise defined as an  extension of this implementation, is not
     defined by the library.


  9  Library Organization
  -----------------------

  The symbols declared  and defined by this implementation  of the C++
  Standard Library  are organized  in a number  of public  and private
  headers,  template  implementation  files,  C++  source  files,  and
  assembly  files. The  purpose of  this  section is  to document  the
  conventions  used  in the  organization  of  the  symbols and  their
  declarations and definitions in the library files.


  9.1  Organization of Headers
  ----------------------------

  Every library  header starts with a comment  containing the relative
  pathname  of  the  file   with  respect  to  the  ${TOPDIR}/include/
  directory  (such as  iostream  or rw/_config.h) along  with a  brief
  description of the contents of the file and a copyright notice.

  Below  the comment is a  header #inclusion  guard that  prevents the
  contents of the same header  file from being expanded more than once
  in any translation unit from which the header might be included more
  than once. The naming convention used for the guard is as follows:

  #ifndef _RWSTD_<file-name>_INCLUDED
  #define _RWSTD_<file-name>_INCLUDED
  ... /* contents of the file*/
  #endif   // _RWSTD_<file-name>_INCLUDED

  Where  <file-name>  is the  relative  pathname  of  the header  with
  slashes  replaced by  underscores (e.g,  _RWSTD_IOSTREAM_INCLUDE for
  the    header    iostream    or   _RWSTD_RW_CONFIG_H_INCLUDED    for
  rw/_config.h).

  In order to minimize the size of translation units and the namespace
  pollution caused by #including  library headers in programs (as well
  as the library sources themselves) library headers #include only the
  absolute  minimum of other  C++ Standard  library headers,  and only
  those third party  (such as libc or OS)  headers that are absolutely
  necessary and whose symbols  cannot be forward-declared. This set of
  third party headers is at this point limited to <cstring>, <cwchar>,
  and  <ctime>,  and the  appropriate  threads  header in  thread-safe
  configurations.   Since no  other  headers are  #included, common  C
  library  symbols such  as ptrdiff_t,  size_t, or  CHAR_MAX  that are
  declared in  these headers  are determined at  library configuration
  time  and  available  under  the  appropriate  configuration  macros
  (_RWSTD_PTRDIFF_T,   _RWSTD_SIZE_T,  and  _RWSTD_CHAR_MAX   in  this
  example). The  C++ Standard library headers always  use these macros
  rather than their C library equivalents. In order to make sure these
  macros are  always available every  library header must  contain the
  #include <rw/_defs.h> directive.


  9.2  Organization of Sources
  ----------------------------

  Every library source  file starts with a comment  containing name of
  the file along with a brief  description of the contents of the file
  and a copyright notice.

  Below the  comment are any necessary  #include directives, including
  #include <rw/_defs.h>.   Since namespace pollution is  not a concern
  for  source  files, the  "deprecated"  C  library  headers (such  as
  <stdio.h>) are always #included in  favor of the "new" C++ C library
  equivalents  (i.e., <cstdio>) for  portability.  However,  since the
  size of library  translation units has an effect on  the size of the
  library itself as well as on  the size of executables linked with an
  archive version of  the library, each source file  must include only
  the bare minimum of the C++ Standard Library headers.

  In order to minimize code bloat, library source files must take care
  to instantiate only  the barest minimum of templates  defined by the
  library.  No  source file  instantiates any public  templates unless
  necessitated by the requirements  of the C++ Standard. For instance,
  while it  isn't possible  to avoid instantiating  std::string (since
  the type is  used in locale and iostreams),  instantiating any other
  container is unnecessary and thus avoided.

  In order to further minimize the  size of programs that link with an
  archive version of the library each library source file defines only
  the smallest set  of symbols that is to  the maximum possible extent
  independent of those defined in any other library source file.


  10  Platform Notes
  ------------------

    10.1  Apogee C++
    ----------------

    Port not maintained.

    10.2  Borland C++
    -----------------

    Not ported.

    10.3  Comeau C++
    ----------------

    Ported to Comeau C++ 4.2.42 or later on Solaris.

    10.4  Compaq C++
    ----------------

    Ported to Compaq C++ 6.2 or later for Tru64 UNIX.

    10.5  EDG eccp
    --------------

    Ported  to the  EDG  eccp demo  2.45.2  through 3.6  on Linux  and
    Solaris.

    10.6  GNU gcc
    -------------

    Ported  to gcc  2.95.2 through  4.0.0  on a  variety of  operating
    systems   and   architectures,   including   HP-UX,   Linux,   and
    Solaris. The  library has not been  ported to Apple  Darwin and is
    known to fail to build.

    10.7 HP aCC
    ------------

    Ported to HP  aCC 3.13 and later for PA-RISC,  and 5.36 and later,
    and 6.0 and later for IPF.

    10.8  IBM VisualAge C++
    -----------------------

    For  builds with  VisualAge for  C++ 5.0  and 6.0  there  are some
    special  considerations  when   building  programs  that  use  the
    implicit inclusion  mechanism (i.e.,  the -qtempinc mode  which is
    active by default).

    The mechanism imposes some restrictions on the way the source code
    is structured: template declarations  have to be present in header
    files  while  corresponding .c  source  files  must contain  these
    templates'  implementations.    Source  code  otherwise  perfectly
    correct, containing  template classes or  functions definitions or
    definitions of  types used in  instantiations of templates  in cpp
    files, will not be able to benefit from this feature.

    10.9  Intel C++
    ---------------

    Ported to  Intel C++ 7.0 through  9.0 on Linux  and Windows (x86,
    IA64, and EM64T).

    10.10  KAI C++
    --------------

    Port not maintained.

    10.11  Metrowerks CodeWarrior
    -----------------------------

    Not ported.

    10.12  Microsoft MSVC
    --------------------

    Ported to MSVC 6.0 through 8.0 on Windows (x86, IA64, and EM64T).


    10.13  SGI MIPSpro
    ------------------

    Ported to SGI MIPSpro 7.3 through 7.5 for IRIX 6.5.

    10.14  Siemens CDS++
    --------------------

    Port not maintained.

    10.15  Sun C++
    --------------

    Ported to Sun C++ 5.3 through 5.7 on Solaris and Linux (SPARC and
    x86_64).