                                                              Updated 2002/04/17

 Forte[tm] Developer 7: C++ Compiler Readme

     Contents

       A. Introduction
       B. About the Forte Developer 7 C++ Compiler
       C. New and Changed Features
       D. Software Corrections
       E. Problems and Workarounds
       F. Limitations and Incompatibilities
       G. Documentation Errors
       H. Shippable Libraries
       I. Standards Not Implemented



     ------------------------------------------------------------------

     A. Introduction

     This document contains information about the Forte[tm] Developer 7
     C++ compiler. Throughout this document, the compiler is also
     referred to as version 5.4 of the C++ compiler. This document
     describes the new features that are included with this release,
     software corrections that are addressed by this release, and lists
     known problems, limitations, and incompatibilities. Information in
     this document updates and extends information in the software
     manuals.

     Information in the release notes updates and extends information
     in all readme files. To access the release notes and the complete
     Forte Developer documentation set, go to the documentation index
     at file:/opt/SUNWspro/docs/index.html. The documentation index
     provides access to the following C++ documents:

        * C++ FAQ
        * C++ User's Guide
        * C++ Migration Readme
        * C++ Migration Guide
        * Standard C++ Library Class Reference
        * Standard C++ Library User's Guide
        * Tools.h++ 7.1.0 Readme
        * Tools.h++ User's Guide
        * Tools.h++ Class Library Reference
        * Interval Arithmetic Readme
        * C++ Interval Arithmetic Programming Reference
        * Math Libraries Readme
        * Runtime Libraries Readme
        * Numerical Computation Guide
        * Incremental Link Editor Readme
        * CC(1) man page
        * 3C++ man pages (Standard C++ Library)
        * 3CC4 man pages (Compatibility Mode Libraries)

     To view the text version of this readme, type the following at a
     command prompt:

        CC -xhelp=readme

     To view the HTML version of this readme, go to:

        file:/opt/SUNWspro/docs/index.html

     Note - If your Forte Developer 7 software is not installed in the
     /opt directory, ask your system administrator for the equivalent
     path on your system.



     ------------------------------------------------------------------

     B. About the C++ Compiler

     This release of the C++ compiler is available on the Solaris[tm]
     operating environment (SPARC[tm] Platform Edition) versions 7, 8,
     and 9.

     This 5.4 version of the C++ compiler is upwardly source-compatible
     and binary-compatible with C++ compiler versions 5.0, 5.1, 5.2,
     and 5.3. That is, you can compile source code written for versions
     5.0, 5.1, 5.2, and 5.3 of the C++ compiler using the 5.4 C++
     compiler. In addition, you can link object code that was generated
     by C++ compiler versions 5.0, 5.1, 5.2, and 5.3 with object code
     that was generated by the 5.4 C++ compiler. You should always link
     with the latest compiler which, for this release, is version 5.4.

     The 5.4 C++ compiler also offers the -compat option for compiling
     source code that was written for the 4.2 C++ compiler. The -compat
     option was introduced in version 5.0.



     ------------------------------------------------------------------

     C. New and Changed Features

     This section describes the new and changed features for the C++
     compiler. For information about other Forte Developer components,
     see the What's New manual. To access this manual on your local
     system or network, go to file:/opt/SUNWspro/docs/index.html. You
     can also access this manual by going to http://docs.sun.com.

        * Support for OpenMP in C++ (SPARC)
        * Type-Based Alias Analysis and Optimizations (SPARC)
        * Compiling for the Native Connector Tool
        * Enhanced Interprocedural Optimizations (SPARC)
        * New Prefetch Levels (SPARC)
        * Stack-Overflow Checking (SPARC)
        * Support for STLport Standard Library Implementation 4.5.2
        * +w Behavior Changes
        * +w2 Behavior Changes
        * #error Directive Aborts Compilation

        * Support for OpenMP in C++ (SPARC)

          This release of the C++ compiler implements the OpenMP
          interface for explicit parallelization including a set of
          source code directives, run-time library routines, and
          environment variables with the following new option:

          CC -xopenmp[=i]

          where i is parallel, stubs, or none.

             o If you do not issue -xopenmp, the compiler sets the
               option to -xopenmp=none.

             o If you issue only -xopenmp, the compiler sets the option
               to -xopenmp=parallel which enables recognition of OpenMP
               pragmas and applies to SPARC only. The optimization
               level under -xopenmp=parallel is -x03. The compiler
               issues a warning if the optimization level of your
               program is changed from a lower level to -x03.

             o The -xopenmp=stubs command links with the stubs routines
               for the OpenMP API routines. Use this options if you
               need to compile your application to execute serially.
               The -xopenmp=stubs command also defines the _OPENMP
               preprocessor token.

             o The -xopenmp=none command does not enable recognition of
               OpenMP pragmas, makes no change to the optimization
               level of your program, and does not predefine any
               preprocessor tokens.

          Note: The following list details the known limitations of the
          OpenMP functionality in the C++ compiler:

             o No support for C++ - specific features
               C++ - specific features have not been implemented. That
               is, using class objects within OpenMP regions or using
               OpenMP pragmas within member functions can result in
               errors or incorrect results. Throwing exceptions within
               OpenMP regions may result in undefined behavior.

             o No support for nested parallelism
               The C++ compiler does not support nested parallelism as
               defined in the OpenMP 1.0 draft standard.

             o No checks for loop index modification
               The compiler does not confirm that OpenMP for loop
               indices are not modified within the body of the loop.

             o No check for same chunksize across all threads
               The compiler does not check that a variable used as an
               argument to chunksize has the same value for all
               threads.

             o No checks for overloaded operators used in reduction
               clause
               The compiler does not detect when operators used as
               arguments in the reduction clause are overloaded.

             o Error message text still in review
               The OpenMP error message system is under review and
               revision. Some messages may be inaccurate or unhelpful.



        * Type-Based Alias Analysis and Optimizations (SPARC)

          The C++ compiler now accepts the -xalias_level option which
          allows it to perform type-based alias analysis and
          optimizations.

          -xalias_level[=i]

          where i is any, simple, or compatible.

          If you do not issue -xalias_level, the compiler sets the
          option to -xalias_level=any. If you issue -xalias_level but
          do not provide a value, the compiler sets the option to
          -xalias_level=compatible.

             o -xalias_level=any

               At this level of analysis, the compiler assumes that any
               type may alias any other type. However, despite this
               assumption, some optimization is possible.

             o -xalias_level=simple

               The compiler assumes that fundamental types are not
               aliased. Specifically, a storage object with a dynamic
               type that is one of the following fundamental types:

                  + char, signed char, and unsigned char,
                  + wchar_t,
                  + short int, unsigned short int,
                  + int, unsigned int,
                  + long int, unsigned long int,
                  + long long int, unsigned long long int,
                  + float, double, long double,
                  + enumeration types,
                  + data pointer types,
                  + function pointer types,
                  + data member pointer types, or
                  + function member pointer types

               is only accessed through lvalues of the following types:

                  + the dynamic type of the object,
                  + a constant or volatile qualified version of the
                    dynamic type of the object,
                  + a type that is the signed or unsigned type
                    corresponding to the dynamic type of the object,
                  + a type that is the signed or unsigned type
                    corresponding to a constant or volatile qualified
                    version of the dynamic type of the object,
                  + an aggregate or union type that includes one of the
                    aforementioned types among its members (including,
                    recursively, a member of a subaggregate or
                    contained union), or
                  + a char or unsigned char type.

             o -xalias_level=compatible

               This level of type-based alias analysis includes the
               requirements of -xalias_level=simple. In addition, the
               compiler assumes that layout-incompatible types are not
               aliased. A storage object is only accessed through
               lvalues of the following types:

                  + the dynamic type of the object,
                  + a constant or volatile qualified version of the
                    dynamic type of the object,
                  + a type that is the signed or unsigned type which
                    corresponds to the dynamic type of the object,
                  + a type that is the signed or unsigned type which
                    corresponds to the constant or volatile qualified
                    version of the dynamic type of the object,
                  + an aggregate or union type that includes one of the
                    aforementioned types among its members (including,
                    recursively, a member of a subaggregate or
                    contained union),
                  + a type that is (possibly constant or volatile
                    qualified) base class type of the dynamic type of
                    the object, or
                  + a char or unsigned char type.

               The compiler assumes that the types of all references
               are layout compatible with the dynamic type of the
               corresponding storage object. Two types are
               layout-compatible under the following conditions:

                  + If two types are the same type, then they are
                    layout-compatible types.
                  + If two types differ only in constant or volatile
                    quailification, then they are layout-compatible
                    types.
                  + For each of the signed integer types, there exists
                    a corresponding (but different) unsigned integer
                    type. These corresponding types are layout
                    compatible.
                  + Two enumeration types are layout-compatible if they
                    have the same underlying type.
                  + Two Plain Old Data (POD) struct types are layout
                    compatible if they have the same number of members,
                    and corresponding members (in order) have layout
                    compatible types.
                  + Two POD union types are layout compatible if they
                    have the same number of members, and corresponding
                    members (in any order) have layout compatible
                    types.

               References may be non-layout-compatible with the dynamic
               type of the storage object under limited circumstances:

                  + If a POD union contains two or more POD structs
                    that share a common initial sequence, and if the
                    POD union object currently contains one of those
                    POD structs, it is permitted to inspect the common
                    initial part of any of them. Two POD structs share
                    a common initial sequnce if corresponding members
                    have layout compatible types and, as applicable to
                    bit fields, the same widths, for a sequence of one
                    or more initial members.
                  + A pointer to a POD struct object, suitably
                    converted using a reinterpret_cast, points to its
                    initial member, or if that member is a bit field,
                    to the unit in which it resides.

        * Compiling for the Native Connector Tool

          Use the -xnativeconnect option when you want to include
          interface information inside object files and subsequent
          shared libraries so that the shared library can interface
          with code written in the Java[tm] programming language (Java
          code). You must also include -xnativeconnect when you build
          the shared library with CC -G.

          When you compile with -xnativeconnect, you are providing the
          maximum, external, visibility of the native code interfaces.
          The Native Connector Tool (NCT) enables the automatic
          generation of Java code and Java Native Interface (JNI) code
          so that C++ shared libraries can be called from Java code.
          For more information on how to use the NCT, see the Forte
          Developer online help.

          -xnativeconnect[=a[,a]...]
          a can be one of the following:
          {%all|%none|[no%]inlines|[no%]interfaces}

             o If you do not issue -xnativeconnect, the compiler sets
               the option to -xnativeconnect=%none.
             o If you issue only -xnativeconnect, the compiler sets the
               option to -xnativeconnect=inlines,interfaces.
             o -xnativeconnect=inlines forces the generation of
               out-of-line instances of referenced inline functions.
               External functions generated as part of a native
               connector may be bound to these out-of-line instances.
               The normal inlining of these functions at call sites is
               unaffected
             o -xnative=interfaces forces the generation of Binary
               Interface Descriptors (BIDS).

          Note: Do not compile with -compat=4 if you plan to use
          -xnativeconnect. Remember that if you issue -compat without
          any arguments, the compiler sets it to -compat=4. If you do
          not issue -compat, the compiler sets it to -compat=5. You can
          also explicitly set the compatibility mode by issuing
          -compat=5.

          This option does not accumulate. The compiler uses the last
          setting that is issued. For example, if you issue CC
          -xnativeconnect=inlines first.o -xnativeconnect=interfaces
          second.o -O -G -o library.so, the compiler sets the option to
          -xnativeconnect=no%inlines,interfaces.

        * Enhanced Interprocedural Optimizations (SPARC)

          With -xipo=1, the compiler performs inlining across all
          source files. With -xipo=2, the compiler performs
          interprocedural aliasing analysis as well as optimizations of
          memory allocation and layout to improve cache performance.

        * New Prefetch Levels (SPARC)

          Use the new -xprefetch_level=n option to control the
          aggressiveness of the automatic insertion of prefetch
          instructions as determined with -xprefetch=auto. n must be
          one of 1, 2, or 3. The compiler becomes more aggressive, or
          in other words, introduces more prefetches with each, higher,
          level of -xprefetch_level.

          The appropriate value for -xprefetch_level depends on the
          number of cache misses your application has. Higher
          -xprefetch_level values have the potential to improve the
          performance of applications with a high number of cache
          misses.

          This option is effective only when when it is compiled with
          -xprefetch=auto, with optimization level 3 or greater (-xO3),
          and on a platform that supports prefetch (v8plus, v8plusa,
          v9, v9a, v9b, generic64, native64).

             o -xprefetch_level=1
               Enables automatic generation of prefetch instructions.

             o -xprefetch_level=2
               Targets additional loops, beyond those targeted at
               -xprefetch_level=1, for prefetch insertion. Additional
               prefetches may be inserted beyond those that were
               inserted at -xprefetch_level=1

             o -xprefetch_level=3
               Targets additional loops, beyond those targeted at
               -xprefetch_level=2, for prefetch insertion. Additional
               prefetches may be inserted beyond those that were
               inserted at -xprefetch_level=2

          For C++, the default is -xprefetch_level=2 when you specify
          -xprefetch=auto.

        * Stack-Overflow Checking (SPARC)

          Compiling with -xcheck=stkovf adds a runtime check for stack
          overflow of the main thread in a singly-threaded program as
          well as slave-thread stacks in a multithreaded program. If a
          stack overflow is detected, a SIGSEGV is generated. If your
          application needs to handle a SIGSEGV caused by a stack
          overflow differently than it handles other address-space
          violations, see sigaltstack(2).

          You can turn off stack-overflow checking by issuing
          -xcheck=no%stkovf.

          Defaults:
             o If you do not issue -xcheck, the compiler defaults to
               -xcheck=%none.
             o If you issue -xcheck without any arguments, the compiler
               defaults to -xcheck=%none.
             o The -xcheck option does not accumulate on the command
               line. The compiler sets the flag in accordance with the
               last occurance of the command.

        * Support for STLport Standard Library Implementation 4.5.2

          The C++ compiler now supports STLport's Standard Library
          implementation version 4.5.2. libCstd is still the default
          library, but STLport's product is now available as an
          alternative. This release includes both a static archive
          called libstlport.a and a dynamic library called
          libstlport.so.

          Issue the following compiler option to turn off libCstd and
          use STLport:

          -library=stlport4

          Consider the following information before you decide whether
          or not you are going to use the STLport implementation:

             o STLport is an open source product and does not guarantee
               compatibility across different releases. In other words,
               compiling with a future version of STLport may break
               applications compiled with STLport 4.5.2. It also might
               not be possible to link binaries compiled using STLport
               4.5.2 with binaries compiled using a future version of
               STLport.

             o Future releases of the compiler might not include
               STLport4. They might include only a later version of
               STLport. The compiler option -library=stlport4 might not
               be available in future releases, but could be replaced
               by an option referring to a later STLport version.

             o Tools.h++ is not supported with STLport.

             o STLport is binary incompatible with the default libCstd.
               If you use STLport's implementation of the standard
               library, then you must compile and link all files with
               the option -library=stlport4.

             o If you decide to use the STLport implementation, be
               certain to include header files that your code
               implicitly references. The standard headers are allowed,
               but not required, to include one another as part of the
               implementation. Consider the following example:

               The following test case does not compile with STLport
               because the code in the test case makes unportable
               assumptions about the library implementation. In
               particular, it assumes that either <vector> or
               <iostream> automatically include <iterator>, which is
               not a valid assumption.

               #include <vector>
               #include <iostream>

               using namespace std;

               int main ()
               {
                   vector <int> v1 (10);
                   vector <int> v3 (v1.size());
                   for (int i = 0; i < v1.size (); i++)
                     {v1[i] = i; v3[i] = i;}
                   vector <int> v2(v1.size ());
                   copy_backward (v1.begin (), v1.end (), v2.end ());
                   ostream_iterator<int> iter (cout, " ");
                   copy (v2.begin (), v2.end (), iter);
                   cout << endl;
                   return 0;
               }

               To fix the problem, include <iterator> in the source.

        * +w Behavior Change Identifies code that might have unintended
          consequences. The +w option no longer generates a warning if
          a function is too large to inline or if a declared program
          element is unused. These warnings do not identify real
          problems in the source, and were thus inapproprate to some
          development environments. Removing these warnings from +w
          enables more aggressive use of +w in those environments.
          These warnings are still available with the +w2 option.

        * +w2 Behavior Change The +w2 option no longer reports the use
          of implementation-dependent constructs in the system header
          files. Because the system header files are the
          implementation, the warning was inappropriate. Removing these
          warnings from +w2 enables more aggressive use of the option.

          Emits all the warnings emitted by +w plus warnings about
          technical violations that are probably harmless, but that
          might reduce the maximum portability of your program.

        * #error Directive Aborts Compilation

          The previous behavior of the #error directive was to issue a
          warning and continue compilation. The new behavior,
          consistent with other compilers, is to issue an error message
          and immediately halt compilation. The compiler quits and
          reports the failure.



     ------------------------------------------------------------------

     D. Software Corrections

     This section discusses the following software corrections.

       1. C++ OpenMP Bug
       2. Ambiguity: Constructor Call or Pointer-to-Function
       3. __ctype Not Defined Errors Fixed in Solaris 8 update 2 and
          Patch
       4. Support for -instance=static and -instance=semiexplicit With
          Static Variables Within Templates
       5. Different Behavior for Function-Local Static Variables for
          Extern Inline Functions
       6. Template Syntax Error is No Longer Ignored
       7. The -staticlib Option Now Works With -G

       1. C++ OpenMP Bug

          The following bug has been fixed in patch 111715-01.

          If a function has a local variable of a type with a
          destructor, and if the function also has an omp parallel
          region containing a function call, the compiler aborts. The
          following example aborts upon compilation:

          class A {
              public:
                 ~A(){};
          };

          void bar();    // any function

          void foo()
          {
              A a;       // local variable having a destructor
              #pragma omp parallel
              {
                  bar(); // function call in a parallel region
              }
          }

          example% CC try.cc -xO3 -xopenmp
          compiler(iropt) error:  connect_labelrefs: undefined label L77000031
          example%

       2. Ambiguity: Constructor Call or Pointer-to-Function

          Some C++ statements could potentially be interpreted as a
          declaration or as an expression-statement. The C++
          disambiguation rule is that if a statement can be a
          declaration, it is a declaration.

          The earlier versions of the compiler misinterpreted cases
          like the following:

              struct S {
                S();
              };
              struct T {
                T( const S& );
              };
              T v( S() );    // ???

          The programmer probably intended the last line to define a
          variable v initialized with a temporary of type S. Previous
          versions of the compiler interpreted the statement that way.

          But the construct "S()" in a declaration context can also be
          an abstract declarator (that is, one without an identifier)
          meaning "function with no parameters returning of value of
          type S." In that case, it is automatically converted to the
          function pointer "S(*)()". The statement is thus also valid
          as a declaration of a function v having a parameter of
          function-pointer type, returning a value of type T.

          The compiler now makes the correct interpretation, which
          might not be what the programmer intended.

          There are two ways to modify the code to make it unambiguous:

              T v1( (S()) );  // v1 is an initialized object
              T v2( S(*)() ); // v2 is a function

          The extra pair of parentheses in the first line is not valid
          syntax for v1 as a function declaration, so the only possible
          meaning is "an object of type T initialized with a temporary
          value of type S."

          Similarly, the construct "S(*)()" cannot possibly be a value,
          so the only possible meaning is as a function declaration.

          The first line can also be written as

              T v1 = S();

          Although the meaning is completely clear, this form of
          initialization can sometimes result in extra temporaries
          being created, although it usually does not.

          Writing code like the following is not recommended because
          the meaning is not clear, and different compilers might give
          different results.

              T v( S() ); // not recommended

       3. __ctype Not Defined Errors Fixed in Solaris update 2 and
          Patch

          The Solaris 8 operating environment had a bug that could
          cause "__ctype not defined" errors from the C++ compiler when
          you used MB_CUR_MAX from <stdlib.h>.

          This bug has been fixed in the Solaris 8 update 2 operating
          environment. The fix is available in Solaris patches
          109607-01 (SPARC) and 109608-01 (IA) as well.

          If the update or the patches have not been installed, the
          workaround is to include the standard header <ctype.h> before
          including the header <stdlib.h>.

       4. Support for -instance=static and -instance=semiexplicit With
          Static Variables Within Templates

          With prior versions of the C++ compiler, use of the static
          instances method and use of the semi-explicit instances
          method were not supported with static variables within
          templates. This restriction does not exist with the 5.2, 5.3
          and 5.4 versions of the C++ compiler.

       5. Different Behavior for Function-Local Static Variables for
          Extern Inline Functions

          Under the ARM rules, function-local static variables for
          extern inline functions are file static. Under the ISO
          standard, function-local static variables for extern inline
          functions are global variables that are shared among
          compilation units.

          The 5.0 and 5.1 versions of the C++ compiler implemented the
          ARM behavior for both compatibility mode (-compat) and
          standard mode (the default mode). The 5.2, 5.3 and 5.4
          versions of the C++ compiler implement the ARM behavior for
          compatibility mode and the ISO behavior for standard mode.
          For example,

          one.cc

              inline int inner() {
                static int variable = 0; return variable++;
              }
              int outer() { return inner(); }

          two.cc

              inline int inner() {
                static int variable = 0; return variable++;
              }
              int main() { return inner() + outer(); }

          When compiled in compatibility mode (-compat), the two
          variables are different and the result of main is 0 (zero).

          When compiled in standard mode (the default mode), the two
          variables are the same and the result of main is 1 (one). To
          obtain the old behavior in standard mode, declare the inline
          function static.

       6. Template Syntax Error is No Longer Ignored

          The following template syntax has never been valid, but Sun
          C++ 4 and 5.0 did not report the error. The 5.1, 5.2, 5.3,
          and 5.4 versions of the C++ compiler report this syntax error
          when you compile in standard mode (the default mode).

            template<class T> class MyClass<T> { ... }; // definition error
            template<class T> class MyClass<T>;         // declaration error

          In both cases, the "<T>" on "MyClass<T>" is invalid, and must
          be removed, as shown in the following example,

            template<class T> class MyClass { ... }; // definition
            template<class T> class MyClass;         // declaration

       7. The -staticlib Option Now Works With -G

          Previously, the -staticlib option had no effect when building
          shared libraries. Now it does.



     ------------------------------------------------------------------

     E. Problems and Workarounds

     This section discusses known software problems and possible
     workarounds for those problems. For updates, check Forte Developer
     Hot Product News at http://www.sun.com/forte/fcc/hotnews.html.

       1. Cross-Language Linking Error
       2. Name Mangling Linking Problems
       3. Using make With Standard Library Header Files on Version 7 of
          the Solaris Operating Environment
       4. Debugging Tools Erroneously Report Extra Leading Parameter
          for Member Functions
       5. Reference From Template to Non-Global File-Scope Object is
          Not Supported
       6. #pragma align Inside Namespace Requires Mangled Names
       7. Function Overload Resolution
       8. Multithreaded C++ Programs Using Alternate Threads Hang When
          Debugged in Solaris 8 Operating Environment

       1. Cross-Language Linking Error

          If you issue the -xlang=f77 command, the compilation process
          encounters a linker error. To avoid the error and still
          include the appropriate runtime libraries, issue
          -xlang=f77,f90 instead.

       2. Name Mangling Linking Problems

          The following conditions may cause linking problems.

             o A function is declared in one place as having a const
               parameter and in another place as having a non-const
               parameter.

               Example:

                 void foo1(const int);
                 void foo1(int);

               These declarations are equivalent, but the compiler
               mangles the names differently. To prevent this problem,
               do not declare value parameters as const. For example,
               use void foo1(int); everywhere, including the body of
               the function definition.

             o A function has two parameters with the same composite
               type, and just one of the parameters is declared using a
               typedef.

               Example:

                 class T;
                 typedef T x;
                 // foo2 has composite (that is, pointer or array)
                 // parameter types
                 void foo2(T*, T*)
                 void foo2(T*, x*);
                 void foo2(x*, T*);
                 void foo2(x*, x*);

               All declarations of foo2 are equivalent and should
               mangle the same. However, the compiler mangles some of
               them differently. To prevent this problem, use typedefs
               consistently.

               If you cannot use typedefs consistently, a workaround is
               to use a weak symbol in the file that defines the
               function to equate a declaration with its definition.
               For example:

               #pragma weak "__1_undefined_name" = "__1_defined_name"

               Note -- Some mangled names are dependent on the target
               architecture. (For example, size_t is unsigned long for
               the SPARC V9 architecture, and unsigned int otherwise.)
               In such a case, two versions of the mangled name are
               involved, one for each model. Two pragmas must be
               provided, controlled by appropriate #if directives.

          For more information, see the C++ Migration Guide. To access
          this guide in HTML, point your browser to
          file:/opt/SUNWspro/docs/index.html.

       3. Using make With Standard Library Header Files on Version 7 of
          the Solaris Operating Environment

          The standard library file names do not have ".h" suffixes.
          Instead, they are named istream, fstream, and so forth. In
          addition, the template source files are named istream.cc,
          fstream.cc, and so forth.

          If, in the Solaris 7 operating environment, you include a
          standard library header in your program, such as <istream>,
          and your makefile has .KEEP_STATE, you will encounter
          problems. For example, if you include <istream>, make thinks
          that istream is an executable and uses the default rules to
          build istream from istream.cc resulting in very misleading
          error messages. (Both istream and istream.cc are installed
          under the C++ include files directory). Here are possible
          workarounds:

             o Use the -r option which disables the default make rules.
               This solution may break the build process.
             o Use the dmake utility in serial mode instead of make:
               dmake -m serial
             o Avoid the use of .KEEP_STATE.

       4. Debugging Tools Erroneously Report Extra Leading Parameter
          for Member Functions

          In compatibility mode (-compat), the C++ compiler incorrectly
          mangles the link names for pointers to member functions. The
          consequence of this error is that the demangler, and hence
          some debugging tools, like dbx and c++filt, report the member
          functions as having an extra leading parameter consisting of
          a reference to the class type of which the function is a
          member. To correct this problem, add the flag -Qoption ccfe
          -abiopt=pmfun1. Note, however, that sources compiled with
          this flag may be binary incompatible with sources compiled
          without the flag. In standard mode (the default mode), there
          is no problem with mangled names.

       5. Reference From Template to Non-Global File-Scope Object is
          Not Supported

          A program using templates and static objects causes link-time
          errors of undefined symbols. The compiler currently does not
          support reference to non-global file-scope objects from
          templates.

       6. #pragma align Inside Namespace Requires Mangled Names

          When you use #pragma align inside a namespace, you must use
          mangled names. For example, in the following code, the
          #pragma align statement has no effect. To correct the
          problem, replace a, b, and c in the #pragma align statement
          with their mangled names.

            namespace foo {
              #pragma align 8 (a, b, c)
              static char a;
              static char b;
              static char c;
            }

       7. Function Overload Resolution

          Earlier releases of the C++ compiler did not perform function
          overload resolution in accordance with the requirements of
          the C++ standard. The current release fixes many bugs in
          resolving calls to overloaded functions. In particular, the
          compiler would sometimes pick a function when a call was
          actually ambiguous, or complain that a call was ambiguous
          when it actually was not.

          Some workarounds for ambiguity messages are no longer
          necessary. You may see new ambiguity errors that were not
          previously reported.

          One major cause of ambiguous function calls is overloading on
          only a subset of built-in types.


          int f1(short);
          int f1(float);
          ...
          f1(1); // ambiguous, "1" is type int
          f1(1.0); // ambiguous, "1.0" is type double

          To fix this problem, either do not overload f1 at all, or
          overload on each of the types that do not undergo promotion:
          int, unsigned int, long, unsigned long, and double. (And
          possibly also types long long, unsigned long long, and long
          double.)

          Another major cause is type conversion functions in classes,
          especially when you also have overloaded operators.

          class T {
          public:
                  operator int();
                  T(int);
                  T operator+(const T&);
          };
          T t;
          1 + t // ambiguous

          The operation is ambiguous because it can be resolved as

          T(1) + t     // overloaded operator
          1 + t.operator int()    // built-in int addition

          You can provide overloaded operators or type conversion
          functions, but providing both leads to ambiguities.

          In fact, type conversion functions by themselves often lead
          to ambiguities and conversions where you did not intend for
          them to occur. If you need to have the conversion available,
          prefer to use a named function instead of a type conversion
          function. For example, use int to_int(); instead of operator
          int();

          With this change, the operation 1 + t is not ambiguous. It
          can be interpreted only as T(1) + t. If you want the other
          interpretation, you must write
          1 + t.to_int().

       8. Multithreaded C++ Programs Using Alternate Threads Hang When
          Debugged in Solaris 8 Operating Environment

          Multithreaded C++ programs built with alternate threads hang
          when you attempt to debug them in the Solaris 8 operating
          environment. 32-bit multithreaded C++ programs built with the
          -R /usr/lib/lwp compiler option hang when run within dbx.
          64-bit multithreaded C++ programs built with the -R
          /usr/lib/lwp/sparcv9 compiler option are likely to hang,
          especially when runtime checking is used.

          This symptom occurs with C++ code compiled in standard
          (default) mode (with the -compat=5 compiler option); it does
          not occur with code compiled in compatibility mode (with the
          -compat compiler option).

          In cases where alternate threads are being considered for
          performance tuning, it is strongly recommended that the
          multithreaded program first be debugged using the default
          thread library, and that alternate threads be used afterward.



     ------------------------------------------------------------------

     F. Limitations and Incompatibilities

     This section discusses limitations and incompatibilities with
     systems or other software.

       1. Incompatiblity between -xia and -library=stlport4

          You cannot use C++ interval math with the STLport C++
          library. A program using the -xia option can be compiled and
          linked only as documented in the C++ Interval Arithmetic
          Programming Reference.

       2. C++ Shared Library Patch

          A SUNWlibC patch is provided for each version of the Solaris
          Operating Environment supported by this Forte Developer 7
          release on each of the supported platforms. Without these
          patches, some programs fail to link and some programs
          terminate in unusual ways due to runtime errors. For example,
          the linker may report a message similar to the following:

                                                                     First
           Undefined symbol                                          referenced
                                                                     in file
           std::basic_ostream<char,std::char_traits<char>
           >&operator<<(td::basic_ostream<char,std::char_traits<char>test.o
           >&,const RWCString&)

              ld: fatal: Symbol referencing errors. No output written to test

          You may also see an error message such as the following:

              Hint: try checking whether the first non-inlined,
              non-pure virtual function of ...


          For information about required and optional patches for this
          Forte Developer release, see the Forte Developer 7 Release
          Notes. The release notes are available as a text file on the
          Forte Developer 7 CD at
          /cdrom/devpro_v10n1_sparc/release_notes.txt. The release
          notes are available through the documentation index page on
          the Forte Developer 7 web site at
          http://www.sun.com/forte/fcc/documentation.

       3. Compiler Version Incompatibilities

          The remainder of this section discusses the incompatibilities
          between Sun WorkShop C++ compiler versions 4.0, 4.1, 4.2, and
          the following versions:

                  o Sun WorkShop C++ (5.0) compiler
                  o Forte Developer 6 C++ (5.1) compiler
                  o Forte Developer 6 update 1 C++ (5.2) compiler
                  o Forte Developer 6 update 2 C++ (5.3) compiler
                  o Forte Developer 7 (5.4) compiler

            a. Cache Version Differences May Cause Compilation Errors
            b. C++ Interface Incompatibilities
            c. Using Tools.h++
            d. Using Multiple Template Repositories; -ptr Option
               Ignored
            e. Linking With 4.0.1 Libraries Containing Pointers to
               const Member Functions
            f. Linking With Libraries Compiled With Earlier Compilers
            g. Mixing Object Code From Different Versions


            a. Cache Version Differences May Cause Compilation Errors

               When changing compilers, it is always good practice to
               run CCadmin -clean on every directory that contains a
               SunWS_cache subdirectory (alternately, you can use rm
               -rf SunWS_cache). Failure to do so can result in
               compilation errors such as the following:

                  + SunWS_cache: Error: Database version mismatch
                    <path>/SunWS_cache/CC_version.

                  + "<path>/SunWS_cache/CC_state",
                    line 3: Error: "" not allowed here. ** Assertion **
                    : 0

            b. C++ Interface Incompatibilities

               The 5.0, 5.1, 5.2, 5.3, and 5.4 versions of the C++
               compiler are not binary compatible with versions 4.0,
               4.1, and 4.2 of the C++ compiler unless the -compat
               option is used when compiling with the 5.0, 5.1, 5.2,
               5.3, or 5.4 compiler. The incompatibility is due to the
               changes in the class layouts, the calling sequences, and
               the way names are mangled to meet the requirements
               defined in the ANSI/ISO C++ Standard.

               The 5.0, 5.1, 5.2, 5.3, and 5.4 versions of the C++
               compiler are binary compatible.

               See the C++ Migration Guide for more information. To
               access this document in HTML, point your browser to
               file:/opt/SUNWspro/docs/index.html.

            c. Using Tools.h++

               The C++ compiler now uses standard iostreams as the
               default. If you use Tools.h++ in standard mode, you must
               either use the -library=rwtools7_std option or include
               libiostream as shown in the following compiler option:

               example% CC -library=rwtools7_std foo.cc -> uses standard iostreams
               example% CC -library=rwtools7,iostream foo.cc -> uses classic iostreams

               However, in compatibility mode (with the -compat
               compiler option), you cannot issue -library=rwtools7_std
               because the standard library is not available:

               example% CC -compat foo.cc -> compatibility mode, standard library not available

               Do not issue -library=rwtools7, -library=rwtools7_dbg,
               -library=rwtools7_std, or -library=rwtools7_std_dbg with
               -library=stlport4. Tools.h++ is not supported with
               STLport.

               The binaries produced by the options
               -library=rwtools7_std and -library=rwtools7,iostream are
               not compatible. If you use one of these options, you
               should use the same option to compile all source files.

               See also the C++ Migration Guide for more information.
               To access this guide in HTML, point your browser to
               file:/opt/SUNWspro/docs/index.html.

            d. Using Multiple Template Repositories; -ptr Option
               Ignored

               In compilers prior to C++ compiler 5.0, the -ptr flag
               was used to designate repositories for template
               instantiations. With the 5.0, 5.1, 5.2, 5.3, and 5.4
               versions of the C++ compiler, the -ptr flag is no longer
               required, as the compilation system reads from the
               template repositories corresponding to the object files
               that it reads, and writes template instances into the
               repository contained in the directory of the output
               location specified by the CC command.

               In this release, the -ptr option is obsolete and is
               ignored by the compiler. Even though the option is
               ignored, you should remove -ptr from all compilation
               commands because, in a later release, it may be
               reimplemented with a different behavior.

               Note -- Sharing a single template repository for more
               than one application or library has not been and is
               currently not supported. Attempting to do so can lead to
               compilation failure and unpredictable results at runtime
               because of template redefinitions. See the C++ User's
               Guide for more information.

            e. Linking With 4.0.1 Libraries Containing Pointers to
               const Member Functions

               The C++ 4.0.1 compiler generated different mangled names
               for pointers to const member functions than the C++
               compiler versions 4.1, 4.2, 5.0, 5.1, 5.2, 5.3, and 5.4
               do. If you are using the C++ compiler and you are unable
               to link with a library that was built with 4.0.1 and
               that contains such names, you should either recompile
               the library, or compile the rest of the program with the
               -compat -Qoption ccfe -abirel=4.0.1 flags.

               Note -- Future releases may not support the
               -abirel=4.0.1 flag.

            f. Linking With Libraries Compiled With Earlier Compilers

               The C++ 4.0.1 and C++ 4.1 compilers generated a mangled
               name that was unparsable for templates instantiated with
               an extern "C" function. As a consequence, debugging
               tools behaved incorrectly. We have corrected the
               problem, but some users may be unable to link objects
               that are compiled using versions 5.0, 5.1, 5.2, 5.3, or
               5.4 of the C++ compiler with libraries compiled with
               earlier compilers. This incompatibility should be
               extremely rare, but in the event that it does happen,
               you can either

                  + Recompile the library with the Forte Developer 7
                    C++ (5.4) compiler, or
                  + Compile the new objects using the Forte Developer 7
                    C++ (5.4) compiler with the -compat and -Qoption
                    ccfe -abirel=4.1 flags.

               Note -- Future releases may not support the -abirel=4.1
               flag.

            g. Mixing Object Code From Different Versions

               You can mix object code from different versions of the
               Forte Developer 7 C++ compiler in the same program, as
               long as you don't mix compatibility-mode and
               standard-mode code. However, you must link the final
               program using a compiler at least as new as the newest
               compiler version in the mix.

               Note-- You cannot link 4.2 and standard-mode C++ code
               together.



     ------------------------------------------------------------------

     G. Documentation Errors

        * Neither the Forte Developer 7 C++ User's Guide nor the Forte
          Developer 7 CC.1 manpage provide the following description
          for the -xmemalign option:

          -xmemalign[=ab]

          Specify maximum assumed memory alignment and behavior of
          misaligned data accesses. There must be a value for both a
          (alignment) and b (behavior). a specifies the maximum assumed
          memory alignment and b specifies the behavior for misaligned
          memory accesses.

          The compiler generates the appropriate load/store instruction
          sequence for data in a particular alignment when the compiler
          can determine the alignment at compile time. However, for
          memory accesses where the alignment cannot be determined at
          compile time, the compiler makes assumptions about the
          alignment in order to generate the needed load/store
          sequence.

          The -xmemalign flag lets you specify the maximum memory
          alignment the compiler can assume in these indeterminable
          situations. The flag also specifies the error behavior the
          compiler should follow at run time if a misaligned memory
          access takes place.

          Values

          The following table lists the alignment and behavior values
          for -xmemalign:

                            Table 1: -xmemalign Values

            a                           b

            1   Assume at most 1        i  Interpret access and
                byte alignment.            continue execution.

            2   Assume at most 2        s  Raise signal SIGBUS.
                byte alignment.

                                           Raise signal SIGBUS for
                                           alignments less or equal
            4   Assume at most 4        f  to 4, otherwise interpret
                byte alignment.
                                           access and continue
                                           execution.

            8   Assume at most 8
                byte alignment.

            16  Assume at most 16
                byte alignment.

          Defautls

          The following default values only apply when no -xmemalign
          flag is present:

             o -xmemalgin=4s when -xarch has the value generic, v7, v8,
               v8a, v8plus, v8plusa.
             o -xmemalign=8s when -xarch has the value v9, v9a, v9b.

          The following default applies only when the -xmemalign flag
          is present but no value is given:

             o -xmemalign=1i for all -xarch values.

          Examples

          The following table shows how you can use -xmemalign to
          handle different alignment situations.

                           Table 2: -xmemalign Examples

               Command                      Situation

            -xmemalign=1s  There are many misaligned accesses so trap
                           handling is too slow.

                           There are occasional, intentional,
            -xmemalign=8i  misaligned accesses in code that is
                           otherwise correct.

            -xmemalign=8s  There should be no misaligned accesses in
                           the program.

            -xmemalign=2s  You want to check for possible odd-byte
                           accesses.

            -xmemalign=2i  You want to check for possible odd-byte
                           access and you want the program to work.



        * The C++ readme file for Forte 6 update 2 contains an
          incorrectly spelled directory name. Any path that includes
          SUNWSpro is incorrect. The correct directory name is
          SUNWspro. The paths listed in section C.1.b should read as
          follows:
             o ln -s /usr/lib/libCstd.so.1 /opt/SUNWspro/lib/libCstd.so
             o ln -s /usr/lib/libCstd.so.1
               /opt/SUNWspro/lib/v8plus/libCstd.so
             o ln -s /usr/lib/sparcv9/libCstd.so.1
               /opt/SUNWspro/lib/v9/libCstd.so

          Any references to /opt/SUNWSpro should be references to
          /opt/SUNWspro.

        * The C++ readme file for Forte 6 update 2 also contains
          instructions for linking with libCstd. Those instructions
          should be changed to read as follows:

             o For the shared version of libCstd on SPARC:

               ln -s /usr/lib/libCstd.so.1             /opt/SUNWspro/lib/libCstd.so
               ln -s /usr/lib/libCstd.so.1             /opt/SUNWspro/lib/v8plus/libCstd.so
               ln -s /usr/lib/libCstd.so.1             /opt/SUNWspro/lib/v8plusa/libCstd.so
               ln -s /usr/lib/libCstd.so.1             /opt/SUNWspro/lib/v8plusb/libCstd.so
               ln -s /usr/lib/sparcv9/libCstd.so.1     /opt/SUNWspro/lib/v9/libCstd.so
               ln -s /usr/lib/sparcv9/libCstd.so.1     /opt/SUNWspro/lib/v9a/libCstd.so
               ln -s /usr/lib/sparcv9/libCstd.so.1     /opt/SUNWspro/lib/v9b/libCstd.so

             o For the shared version of libCstd on Intel:

               ln -s /usr/lib/libCstd.so.1             /opt/SUNWspro/lib/libCstd.so



     ------------------------------------------------------------------

     H. Shippable Libraries

        * If your executable uses a Sun dynamic library listed in the
          file named below, your license includes the right to
          redistribute the library to your customer.

             /opt/SUNWspro/READMEs/runtime.libraries

          Note - If your Forte Developer 7 software is not installed in
          the /opt directory, ask your system administrator for the
          equivalent path on your system.

          You cannot redistribute or otherwise disclose the header
          files, source code, object modules, or static libraries of
          object modules in any form.

          The License to Use appears in the End User Object Code
          License, which you can view from the back of the plastic case
          containing the CD-ROM.

        * If you want to use the shared-library version of libCstd
          and/or libiostream you have two options:

            1. Distribute the SUNWlibC patch with your product, or

            2. require your customers to download the latest SUNWlibC
               patch from a Sun web site, such as
               http://www.sunsolve.sun.com. The patch is free, and is
               freely re-distributable.

          As before, if you choose to link either library statically,
          you can do so with no further action or permissions needed.



     ------------------------------------------------------------------

     I. Standards Not Implemented

        * The C++ compiler (CC) supports the ISO standard for C++, ISO
          IS 14882:1998, Programming Language C++. The following list
          describes requirements in the standard that are not supported
          in this release:

             o Expressions involving non-type template parameters in
               the function parameter list for function templates, such
               as

               template<int I> void foo(mytype<2*I> ) { ... }

             o Template template parameters (templates as template
               parameters)

             o Universal character names

             o The export model of template compilation is not
               supported.

        * The following functions, which appeared in the 1994 Addendum
          to the 1990 C standard and are included by reference in the
          1998 C++ standard, are supported on versions 7 and 8 of the
          Solaris operating environment, but are not supported on
          version 2.6. With version 2.6 of the Solaris operating
          environment, the declarations do not appear in any headers,
          and the functions are not available in the Solaris run-time
          libraries.

            btowc
            fwide
            fwprintf
            fwscanf
            mbrlen
            mbrtowc
            mbsinit
            mbsrtowcs
            swprintf
            swscanf
            vfwprintf
            vswprintf
            vwprintf
            wcrtomb
            wcsrtombs
            wcsstr
            wctob
            wmemchr
            wmemcmp
            wmemcpy
            wmemmove
            wmemset
            wprintf
            wscanf

        * Comparing the address of the same inline in two different
          compilation units is suppose to yield an equal result.
          However, this release of the C++ compiler does not yield an
          equal result. This disparity is only evident if you compare
          the pointers.

        * Some compiler features are disabled when building libCstd and
          this results in missing functionality in the library. For
          more information, check the C++ FAQ link at
          file:/opt/SUNWspro/docs/index.html.



     ------------------------------------------------------------------

     Copyright  2002 Sun Microsystems, Inc. All rights reserved. Use
     is subject to license terms.
