Introduction

This document contains last minute information about the Sun WorkShop 6 C++ compiler. It describes the software corrections addressed by this release and lists the known problems, limitations, and incompatibilities.

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

   example% CC -xhelp=readme

To access the HTML version of this document, point your Netscape(TM) Communicator 4 or compatible Netscape version browser to:

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

For more information about this product, see:

• Sun WorkShop 6 Release Notes -- Describes installation-related and late-breaking information about this Sun WorkShop release. Information in the release notes overrides information in all readme files.

• About Sun WorkShop 6 Documentation -- Describes the documentation available with this Sun WorkShop release and how to access it.

• What's New in Sun WorkShop 6 -- Describes the new features in this release.

Contents 

1. About the Sun WorkShop 6 C++ Compiler
2. Software Corrections 
3. Problems and Workarounds 
4. Limitations and Incompatibilities 
5. Documentation Errata 
6. Shippable Libraries 
7. New Features 
8. Standards Not Implemented

The Sun WorkShop 6 C++ compiler (CC) runs on SPARC(TM) processors running Solaris(TM) SPARC Platform Edition versions 2.6, 7, and 8, and Intel(R) processors running Solaris Intel Platform Edition, versions 2.6, 7, and 8. Information unique to one or more platforms is identified as "(SPARC)" or "(IA)." 

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.

  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

This section discusses the following software bugs that could not be fixed in time for this release. For updates, check Hot News for Sun WorkShop 6 (http://www.sun.com/workshop/users/ws.html).

1. Name Mangling Linking Problems

2. Using make With Standard Library Header Files on Versions 2.6 and 7 of the Solaris Operating Environment

3. -ptr Option is Obsolete but No Warning

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. Standard Header Warning Messages

7. #pragma align Inside Namespace Requires Mangled Names

8. __ctype Not Defined Errors

1. Name Mangling Linking Problems

   The following conditions may cause linking problems:

   • 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.

   • 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 will mangle some of them differently.

   New extensions to #pragma weak allow you to work around some mangling problems.

   • First, if possible, rewrite the function so that it is consistent in its use of typedefs.

   • Second, in the file that defines the function use a weak symbol 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 will be 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.

   For related information, see Name Mangling Incompatibility With Some Early Access Releases in Section D of this document.

2. Using make With Standard Library Header Files on Versions 2.6 and 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 2.6 or 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:

   • Use the -r option which disables the default make rules. This solution may break the build process.

   • Use the dmake utility in serial mode instead of make:
     dmake -m serial

   • Avoid the use of .KEEP_STATE.

3. -ptr Option is Obsolete but No Warning

   The -ptr option is obsolete. However, the compiler will not emit a warning that the option is ignored.

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

   In compatability mode (-compat=4), 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. Standard Header Warning Messages

   There are known problems with standard headers that cause lots of warnings when +w is used.

7. #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;
     }
   

8. __ctype Not Defined Errors

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

   The bug will be fixed in an update to the Solaris 8 operating environment. The workaround is to include the standard header <ctype.h> as well as the header <stdlib.h>.

1. C++ Shared Library Patch

A SUNWlibC patch is provided for each version of the Solaris Operating Environment supported by this Sun WorkShop 6 release on each of the supported platforms. Without these patches, some programs will not link and some programs will terminate in unusual ways due to runtime errors.

For more information about the shared library patch for C++, see the Sun WorkShop 6 Release Notes, accessible in HTML by pointing your browser to file:/opt/SUNWspro/docs/index.html and clicking on the document title. (If your Sun WorkShop software is not installed in the /opt directory, ask your system administrator for the equivalent path on your system.)

2. 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:

• Sun WorkShop C++ compiler 5.0
• Sun WorkShop 6 C++ compiler 5.1

1. Cache Version Differences May Cause Compilation Errors

2. Name Mangling Incompatibility With Some Early Access Releases

3. C++ Interface Incompatibilities

4. Using Tools.h++ With iostreams

5. Using Multiple Template Repositories; -ptr Option Ignored

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

7. Linking With Libraries Compiled With Earlier Compilers

8. Mixing Object Code From Different Versions

1. Cache Version Differences May Cause Compilation Errors

   When upgrading 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 
     

2. Name Mangling Incompatibility With Some Early Access Releases

   Code that is compiled with this version of the compiler will link with code that was compiled with the Sun WorkShop C++ 5.0 compiler. However, code compiled by the early access versions prior to EA5 might not link with code compiled by this version of the compiler because of name mangling incompatibilities. If you have code that was compiled by early access Sun WorkShop 6 C++ compiler versions EA0, EA1, EA2, EA3, or EA4, delete the old .o files and clean the SunWS_cache subdirectories.

3. C++ Interface Incompatibilities

   The Sun WorkShop 6 C++ compiler is not binary compatible with versions 4.0, 4.1, and 4.2 of the compiler unless the -compat option is used with the Sun WorkShop 6 C++ 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 SunWorkShop 6 C++ compiler and the Sun WorkShop C++ compiler 5.0 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.

4. Using Tools.h++ With iostreams

   The C++ compiler now uses standard iostreams as the default. However, Tools.h++ version 7 is built with classic iostreams. If you use Tools.h++ in standard mode, you must include libiostream as shown in the following compiler option:

     -library=rwtools7,iostream
   

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

5. 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 C++ compiler 5.0 and with the Sun WorkShop 6 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.

6. 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, and the Sun WorkShop 6 C++ compiler do. If you are using the Sun WorkShop 6 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.

7. 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 with either the C++ 5.0 compiler or the Sun WorkShop 6 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 Sun WorkShop 6 C++ compiler, or

   • Compile the new objects using the Sun WorkShop 6 C++ compiler with the -compat=4 and -Qoption ccfe -abirel=4.1 flags.

• Section 1.3.2 "Mixing Old and New Binaries" of the C++ Migration Guide says that you can mix code if no exceptions cross the boundary, but we have found that not to be true. If you mix compat=4 with compat=5 code in the same program, you can use exceptions in the compat=4 code or in the compat=5 code, but not in both. If you have exceptions in the compat=4 code, link libC before linking libCrun. If you have exceptions in the compat5 code, link libCrun before linking libC.

 

• The C++ User's Guide does not mention generic64 and native64 as possible settings for -xtarget, -xarch, and -xchip. See the CC(1) man page for details.

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.

    <install-directory>/SUNWspro/READMEs/runtime.libraries

You may not 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, viewable from the back of the plastic case containing the CDROM.

This version of the Sun WorkShop C++ compiler includes the following new features:

1. Partial Specialization

2. Explicit Function Template Argument

3. Non-Type Function Template Parameters

4. Member Templates

5. Definitions-Separate Template Organization Restriction Removed

6. Prefetch Instructions

7. Extern Inline Functions

8. Ordering of Static Variable Destruction

9. Sub-Aggregate Initialization

10. Using Your Own C++ Standard Library

11. Cache Versioning

12. Restrictions on Bitfield Size Removed

13. Warnings About Conversions Between Pointer-To-Function and void*

14. New and Changed Options

1. Partial Specialization

   A template can be (fully) specialized, meaning that an implementation is defined for specific template arguments. For example:

     template<class T, class U> class A { ... }; //primary template
     template<> class A<int, double> { ... }; //specialization
   

   A template can also be partially specialized, meaning that only some of the template parameters are specified, or that one or more parameters are limited to certain categories of type. The resulting partial specialization is itself still a template. The following examples use the previous primary template:

     template<classU> class A<int> { ... }; // Example no. 1
     template<class T, class U> class A<T*> { ... }; // Example no. 2 
     template<class T> class A<T**, char> { ... }; //Example no.3
   

   • Example 1 provides a special template definition for cases when the first template parameter is type int.

   • Example 2 provides a special template definition for cases when the first template parameter is any pointer type.

   • Example 3 provides a special template definition for cases when the first template parameter is pointer-to-pointer of any type, and the second template parameter is type char.

2. Explicit Function Template Argument

   If a template argument cannot be deduced from the function arguments, you can now specify it explicitly using the syntax f<template args>(function args). For example:

       template<class Mytype> Mytype* construct(float, float); 
       ...
       int* x = construct<int>(a, b);
   

3. Non-Type Function Template Parameters

   This release supports non-type function template parameters, such as:

       template<int I> void foo( int a[I] ) { ... }
       template<int I> void foo( mytype<I> m ) { ... }
   

   This release does not allow expressions involving non-type template parameters in the function parameter list, as illustrated in the following examples:

       // these are not supported
       template<int I> void foo( mytype<2*I> ) { ... } 
       template<int I, int J> void foo( int a[I+J] ) { ... }
   

4. Member Templates

   In standard mode, classes and class templates can have templates as members, as illustrated in the following code sample:

       template <class T1> 
       class OuterClass { 
       public: 
           // class member template 
           template <class T2> 
               class MemberClass 
           { 
               T2 MCmember; 
               T1 OCmember; 
           }; 
           template<class T3> operator T3() { ... }
       ... 
       };
   
   

   Note -- Member templates are not supported in compatiblity mode (-compat[=4]).

5. Definitions-Separate Template Organization Restriction Removed

   The compiler no longer has a restriction against "definitions-separate template organization" for -instances != extern (that is, -instances=explicit, -instances=global, -instances=semiexplicit, or -instances=static). Regardless of the -instances setting, the compiler will now, by default, include separate source files in the search for definitions.

   To turn this restriction back on, use the -template=no%extdef option. Note, however, that when the -template=no%extdef option is specified, the compiler will not search for separate source files even with -instances=extern.

6. Prefetch Instructions

   You can use -xprefetch in conjunction with the header file <sun_prefetch.h> to specify prefetch instructions on those architectures that support prefetch, such as UltraSPARC II (-xarch=v8plus, v8plusa, v8plusb, v9, v9a, or v9b).

7. Extern Inline Functions

   This version of the compiler allows extern inline functions. If there is any local static data in an inline function, only one copy of the static data is used in all compilation units. However, the addresses of inline functions taken in different translation units will not compare as equal.

8. Ordering of Static Variable Destruction

   The standard has defined the order of destruction of objects with static storage duration more fully; static objects must be destroyed in the reverse order of their construction. Previous language definitions left some aspects unspecified.

   This stricter ordering is implemented for standard mode only. In compatibility mode (-compat[=4]), the order of destruction is implemented as before.

   If your program depends on a particular order of destruction and worked with an older compiler, the order required by the standard might break the program in standard mode. The -features=no%strictdestrorder command option disables the strict ordering of destruction.

9. Sub-Aggregate Initialization

   When using brace-initialization of class objects (for types where brace-initialization is allowed), the C++ standard permits a member which is itself an aggregate class to be initialized by a value of its own type. For example:

       struct S {  // an aggregate type
           int i, j;
       };
   
       struct T { // an aggregate type
           S s; // aggregate member
           int k;
       };
   
       T t1 = { {1, 2}, 3 }; // traditional initialization
       S s1 = { 1, 2 };
       T t2 = { s1, 3 }; // sub-aggregate initialization
   

10. Using Your Own C++ Standard Library

    If you want to use your own version of the C++ standard library instead of the version supplied with the compiler, you can do so by specifying the -library=no%Cstd option. This option prevents the finding any of the following headers:

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

    When -library=no%cstd is specified, the libCstd library, which implements those headers, is not automatically linked with your program. To use any of the features declared in the above headers, you must use the -I option to point to the directory where the replacement headers are located, and you must link your program with a library or set of object files containing the implementation of the replacement headers.

    You cannot reliably replace just a portion of the headers listed above, nor can you reliably link libCstd with all or part of another library implementation. (For example, you cannot replace just the string classes and use libCstd for everything else.) Either use the library supplied with the compiler, or replace all of the functionality listed above.

    The remaining headers (<exception>, <new>, <typeinfo>, and all the headers inherited from C) are integral to the compiler itself or to Solaris, and are not affected by the -library=no%Cstd option. Linking of the library libCrun also is not affected by the -library=no%Cstd option.

    There is no mechanism to replace any of the functionality of libCrun. If you replace the standard library, the code must be compiled with the versions of <exception>, <new>, and <typeinfo> supplied with the compiler. In standard mode (the default mode) C++ programs must be linked with libCrun.

    Note - this option is available to "use at your own risk." That is, dropping in another library may not necessarily produce good results.

11. Cache Versioning

    The C++ compiler now has the ability to detect cache version differences and issue the appropriate error message. The compiler marks each template cache directory with a version string that uniquely identifies the template cache version. Subsequent releases of the compiler will also use cache version strings, although these versions may be different from the current one.

    This compiler and future compilers will detect the version strings from within the cache directories, and issue an error as appropriate. For example, a future compiler that uses a different template cache version string and processes a cache directory produced by this release of the compiler might issue the following error:

      SunWS_cache: Error: Database version mismatch
      /SunWS_cache/CC_version
    

    Similarly, this release of the compiler issues an error if it encounters a cache directory produced by a future compiler.

    The template cache directories produced by the Sun WorkShop C++ compiler 5.0 compiler are not versioned. However, the Sun WorkShop 6 C++ compiler processes these cache directories without an error or a warning. These cache directories are converted to the cache directory format used by the Sun WorkShop 6 C++ compiler.

    A template cache directory produced by the Sun WorkShop 6 C++ compiler or later releases cannot be used by the Sun WorkShop C++ compiler 5.0. The Sun WorkShop C++ compiler 5.0 is not capable of recognizing format differences and it will issue an assertion.

12. Restrictions on Bitfield Size Removed

    The restriction on the size of a bitfield to 32 or less is removed. Bitfields can now be any size.

13. Warnings About Conversions Between Pointer-To-Function and void*

    Previously, the compiler issued warnings about conversions between pointer-to-function and void*. Now, the compiler only issues these warnings when you use the +w2 option.

14. New and Changed Options

    The following list shows the new and changed options. For more information, see the entry for each option in the C++ User's Guide. To access this guide in HTML, point your browser to file:/opt/SUNWspro/docs/index.html.

    • New Options. -xcrossfile, -Bsymbolic, -features=[no%]strictdestrorder, -template=extdef.

    • Changed Options. -fast, -library=[no%]Cstd, +p, -ptr, -xprefetch.

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:

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

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

• Template template parameters (templates as template parameters).

• Universal character names.

• Cleaning up objects at the end of a full expression.

  The C++ standard specifies that a temporary object is destroyed at the end of the full expression in which it is created, unless it is used to initialize a reference. This compiler still implements the original behavior; such temporary objects are destroyed at the end of the block in which they are created.

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 not supported on version 2.6 and earlier versions 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.

These functions are supported on Solaris 7 and Solaris 8 operating environments.

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

Copyright 2000 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303, U.S.A. All rights reserved. 

Sun, Sun Microsystems, the Sun logo, docs.sun.com, and Solaris are trademarks, registered trademarks, or service marks of Sun Microsystems, Inc. in the U.S. and other countries.