DEC_C++_Version_5.6_________________________________ Release Notes for DIGITAL UNIX Systems June 16, 1997 This document contains information about new and changed features in this version of DEC C++ for DIGITAL UNIX Systems. Digital Equipment Corporation Maynard, Massachusetts _______________________________________________________________ Contents DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1.1 Introduction.................................. 1-1 1.2 Important Compatibility Information........... 1-1 1.3 Installation Notes............................ 1-3 1.3.1 Installation Notes for DIGITAL UNIX Version 3.n Systems ...................... 1-3 1.3.2 General Installation Notes................ 1-4 1.4 DEC C++ Compiler Release Notes................ 1-4 1.4.1 Enhancements and Changes in Version 5.6... 1-4 1.4.2 Enhancements and Changes in Version 5.5... 1-5 1.4.3 Enhancements and Changes in Version 5.4... 1-6 1.4.4 Enhancements and Changes in Version 5.3... 1-7 1.4.5 Problems Fixed in Version 5.6............. 1-10 1.4.6 Problems Fixed in Version 5.5............. 1-11 1.4.7 Problems Fixed in Version 5.4............. 1-12 1.4.8 Problems Fixed in Version 5.3............. 1-13 1.4.9 Current Restrictions...................... 1-15 1.4.9.1 Restrictions on DIGITAL UNIX Version 3.n Systems................................. 1-15 1.4.9.2 General Restrictions.................... 1-16 1.4.10 Other Restrictions........................ 1-19 1.5 Improving Build Performance................... 1-19 1.5.1 Object File Compression................... 1-20 1.5.2 Use of Shared Libraries................... 1-20 1.5.3 Template Instantiation.................... 1-20 1.6 Linking a DEC C++ Program or Shared Library... 1-21 1.7 Namespaces Support............................ 1-22 1.7.1 Namespace definition and namespace extension................................. 1-23 1.7.2 Unnamed namespaces........................ 1-23 1.7.3 Namespace Alias........................... 1-24 1.7.4 using Declaration......................... 1-24 iii 1.7.5 using Directive........................... 1-25 1.7.5.1 Unqualified Name Lookup With using Directives.............................. 1-26 1.7.5.2 Qualified Name Lookup with using Directives.............................. 1-26 1.7.6 Restrictions.............................. 1-28 1.7.6.1 Restrictions in the Current Implementation.......................... 1-28 1.7.6.2 Debugging Programs That Use Namespaces.............................. 1-29 1.8 Reducing Object File Size During Debugging.... 1-30 1.8.1 Using the -gall option.................... 1-31 1.8.2 Hints for using the -gall option effectively............................... 1-33 1.9 Additional Template Instantiation Options for Version 5.5................................... 1-34 1.10 Explicit Instantiation........................ 1-36 1.11 Release Notes for the DEC C++ Class Library... 1-37 1.11.1 Features and Problems Fixed in Version 5.4....................................... 1-37 1.11.2 Features and Problems Fixed in Version 5.3....................................... 1-37 1.11.3 Restrictions.............................. 1-39 1.12 Release Notes for the C++ Standard Library.... 1-40 1.12.1 Enhancements and Changes in Version 5.6... 1-40 1.12.2 Differences between Version 5.5 and Version 5.6............................... 1-41 1.12.3 Problems Fixed in Version 5.6............. 1-42 1.12.4 Enhancements and Changes in 5.5........... 1-44 1.12.5 Problems Fixed in 5.5..................... 1-44 1.12.6 Problems Fixed in Version 5.4............. 1-44 1.12.7 Known Problems............................ 1-48 1.12.8 Restrictions.............................. 1-52 1.13 Ladebug Debugger Restrictions................. 1-53 1.14 DEC FUSE Restrictions......................... 1-54 1.15 About This Product............................ 1-55 1.16 Trademarks.................................... 1-55 iv 1 _________________________________________________________________ DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1.1 Introduction This document contains the release notes for DEC C++ Version 5.6 for DIGITAL UNIX Systems. The DEC C++ product requires DIGITAL UNIX Version 3.2 or higher. The compiler version installed by this kit is Version V5.6- 010. To check the version of the compiler you are using, use the cxx -V command. The ladebug version installed by this kit is 4.0-39. 1.2 Important Compatibility Information o A new version of ladebug is included with the DEC C++ Version 5.6 kit and is required for use with this version of the compiler. Note that this version is required on DIGITAL UNIX Version 3.n and 4.n systems. For information on restrictions, see Section 1.13. o Version 5.6 significantly reduces the sizes of object files and executables when compiling for debugging. If the debugger describes a class as or lacks debugging information, you may need to compile using the -gall option. See Section 1.8 for more information. o If your application uses the STL that was provided with a previous version of DEC C++, please read Section 1.12 for important information about using the C++ Standard Library provided with the current version of DEC C++. Remember that the ANSI C++ Standard is not yet finalized and thus our STL releases are not guaranteed to be compatible with prior releases. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-1 o If you compile with DEC C++ Version 5.6 and link on Digital UNIX Version 3.n systems, you need to take special actions if you want to be able to execute C++ programs on other DIGITAL UNIX Version 3.n systems. The CXXSHRDA307 subset on the DEC C++ Version 5.6 kit includes updated run-time sharable libraries (the RTLs). This subset must be installed to use DEC C++ Version 5.6 on DIGITAL UNIX Version 3.n systems. Executables that are linked with the -call_shared command line option (the default) and that contain code generated by DEC C++ Version 5.6 can only be run on DIGITAL UNIX Version 3.n systems on which CXXSHRDA307 or a later version has been installed. If you want to run C++ programs on other DIGITAL UNIX Version 3.n systems, you can link specifying cxx -non_ shared. Programs linked in this manner can be run on other systems that do not have CXXSHRDA307 or later installed. Alternatively, the CXXSHRDA307 subset on the DEC C++ Version 5.6 kit, can be redistributed under the conditions stated in the Software Product Description. o Using DEC FUSE If you use DEC C++ Version 5.6 on DIGITAL UNIX Version 3.n systems, it is important to read Section 1.14 before installing. This section describes restrictions on the use of DEC FUSE with DEC C++ Version 5.6 on these systems. o oldc89 and ild DEC C++ prior to Version 5.3 included oldc89, a C compiler, and ild, an incremental linker. These are no longer supported and are not provided with this release. If you wish to retain these files, you should not delete subset CXXOLDAnnn when installing DEC C++. The oldc89 compiler was a very old version of the DEC C compiler. Because the DEC C compiler is shipped as part of the DIGITAL UNIX operating system, the oldc89 compiler is no longer packaged with DEC C++. When you use the cxx command and specifiy C files, DEC C++ invokes the cc command to compile those files. 1-2 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes On DIGITAL UNIX Version 3.n systems, the DEC C compiler is packaged with DEC OSF/1 in the OSFDECCnnn subset. Once this subset has been loaded, the DEC C compiler is invoked using cc with the -migrate option. The cc command offers a number of compilation modes. For best compatability with oldc89, Digital recommends using cc -migrate. Starting with DIGITAL UNIX Version 4.0 systems, the DEC C compiler is the default compiler that is used when you invoke the cc command. The ild linker was an experimental, incremental linker. This linker was of limited utility because of several restrictions and is no longer supplied. Starting with DEC C++ Version 5.0, the cxx command no longer invoked ild but linked programs using the ld linker. [ld is invoked indirectly by the cxx command through the cc command.] 1.3 Installation Notes These notes apply to DEC C++ Version 5.6 for DIGITAL UNIX. For detailed directions on installing the kit, see the DEC C++ Installation Guide for DIGITAL UNIX Systems. 1.3.1 Installation Notes for DIGITAL UNIX Version 3.n Systems These notes apply to DEC C++ for DIGITAL UNIX on DIGITAL UNIX Version 3.n systems. o If you use DEC FUSE, read Section 1.14 before installing DEC C++ for DIGITAL UNIX. o The installation procedure differs depending on whether your system is Version 3.n or Version 4.0 and later. For details, the DEC C++ Installation Guide for DIGITAL UNIX Systems. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-3 1.3.2 General Installation Notes These notes apply generally to DEC C++ for DIGITAL UNIX. o This version of DEC C++ requires DIGITAL UNIX Version 3.2 or higher. o Before installing any of the subsets for this release, you must delete any old versions of these subsets. See the DEC C++ Installation Guide for DIGITAL UNIX Systems for more information. o This DEC C++ version requires a new version of ladebug, which is included with the DEC C++ kit. To install, first delete existing LDB subsets and then install the ladebug subsets when installing DEC C++. Note that this version of ladebug must be installed on Version 3.n and 4.n systems. Section 1.13 describes restrictions that pertain to the use of ladebug with these systems. o If you install a newer version of DIGITAL UNIX, after you install DEC C++, delete all DEC C++ subsets and reinstall DEC C++ (see the DEC C++ Installation Guide for DIGITAL UNIX Systems). Doing this will ensure that any files specifically supplied for a older version of DIGITAL UNIX will not be present to potentially detract from the functioning of DEC C++ under more recent versions of DIGITAL UNIX. 1.4 DEC C++ Compiler Release Notes This is Version 5.6 of the DEC C++ compiler. 1.4.1 Enhancements and Changes in Version 5.6 This section briefly summarizes changes and enhancements that were made in Version 5.6. o Version 5.6 significantly reduces the sizes of object files and executables when compiling for debugging. In some cases you may need to compile particular files using the new -gall option so that the debugger has complete debugging information. See Section 1.8 for more information. 1-4 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes o HTML files are provided for the release notes and some of the product manuals for use with a web browser. These files are installed by selecting the following subset: DEC C++ HTML documentation To view this documentation, open the following file using your web browser: /usr/share/doclib/cplusplus/cxx.html o With Version 5.6, DEC C++ provides support for most of the namespace features described in the current draft ANSI/ISO C++ standard. See Section 1.7. o On DIGITAL UNIX Version 4.0 or later, object files are now compressed by default, which results in smaller object files. See Section 1.5 for more information. To disable object file compression, compile using the -nocompress option. o Previously, the error diagnostics that occurred during a template instantiation have always been generated at the site of the template definition and have not included any useful information about the point of instantiation. With this version, all error diagnostics generated during an instantiation will now be accompanied by another diagnostic indicating the template name, the type being used for the instantiation, and the point of instantiation location. 1.4.2 Enhancements and Changes in Version 5.5 This section briefly summarizes changes and enhancements that were made in Version 5.5. o With Version 5.5, DEC C++ provides additional template instantiation options. See Section 1.9 for details. o Chapter 5 (Using Templates) of Using DEC C++ for DIGITAL UNIX Systems has been expanded to include discussion and examples of building a project using automatic template instantiation. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-5 1.4.3 Enhancements and Changes in Version 5.4 This section briefly summarizes changes and enhancements that were made in Version 5.4. o Substantial performance improvements have been implemented for automatic instantiation of C++ templates. The -pt command line option remains the default but now directs DEC C++ to automatically instantiate multiple member functions and static data members of a particular template class in one object file within the repository. If you want to take advantage of this performance enhancement, DIGITAL suggests that you delete the contents of your old Version 5.3 repository. o The DEC C++ compiler accepts template default parameters as specified in the January 26, 1996 ANSI C++ Working Paper, Section 14.7, with some restrictions (see Section 1.4.9.2). o The compiler now accepts the syntax for explicit instantiation of templates from the January 26, 1996 ANSI C++ Working Paper, Section 14.1. See Section 1.10 of the release notes. o The default optimization levels and optimization options have changed to match the cc command in DIGITAL UNIX Version 4.0. This change only occurs if you do not specify the -migrate option. The behavior is the same as DEC C++ Version 5.3 if you use the -migrate option with the cxx command. For more information, see the cxx(1) reference page. o Symbol preemption behavior when using shared libraries has changed. The default behavior of this release is to support module preemption. Module preemption allows the replacement of the definitions of all of the symbols corresponding to a compilation unit (that is, a single object file generated from a .cxx file). Module preemption would take effect if you modified and recompiled a .cxx file, and linked the new .o file into the main object, thus "replacing" all of the .cxx file's external symbols from the shared library. Unlike full symbol preemption, module preemption does not support 1-6 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes replacing individual symbols because the compiler may perform optimizations that take advantage of information about symbols defined within a module. Full symbol preemption differs from module preemption in that it allows the replacement of the definition of an individual external symbol (function or data) in a shared library. This "replacement" occurs at runtime when the dynamic loader uses a definition of the symbol from the main object or some other shared library in preference to the definition in the original shared library. This behavior may be important when a particular symbol is defined in both the main object and in a shared library (or in multiple shared libraries). You can override the default behavior and obtain full symbol preemption by using the -preempt_symbol option. o New command-line options The following new option is supported in this release. -pts Direct DEC C++ to automatically instantiate needed templates. Each member function or static data member is instantiated in its own separate file. 1.4.4 Enhancements and Changes in Version 5.3 This section briefly summarizes changes and enhancements that were made in Version 5.3. See Using DEC C++ for DIGITAL UNIX Systems for details and additional information. o Automatic instantiation of templates. DEC C++ automatically instantiates C++ templates when special conventions are followed regarding the naming and location of template declaration and definition files. For details, see Chapter 5 of Using DEC C++ for DIGITAL UNIX Systems. o The Standard Template Library (STL), ported for use beginning with DEC C++ Version 5.3. See Chapter 6 in Using DEC C++ for DIGITAL UNIX Systems. o Thread safety DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-7 As of DIGITAL UNIX Version 4.0 and DEC C++ Version 5.3 for DIGITAL UNIX, the DEC C++ Class Library is threadsafe. Refer to the DEC C++ Class Library Reference Manual for details on the threadsafe support, including a new Mutex Package. Support for the -thread_safe command line option has been withdrawn because it is no longer needed. As of Version 5.3, all code generated by the DEC C++ compiler is threadsafe. o New command-line options A number of new options are supported in this release. See Using DEC C++ for DIGITAL UNIX Systems or the cxx manpage for additional information. -assume Allow the compiler to make assumptions keyword to improve run-time performance. -compress Produce a compressed object file. -feedback Optimize based on a feedback file produced by prof to improve run-time performance (Also see -gen_feedback and -cord). -ieee Support all portable features of the IEEE Standard for Binary Floating Point Arithmetic (Also see -denorm and -fprm). -inline Control compiler decisions regarding the keyword inline expansion of functions. -nopragma_ Disable all #pragma define_template template directives in the source code. -O3, -O4, and Perform additional code optimization -O5 in the compiler, for better run-time performance. -om Perform code optimization after linking. -pt Automatically instantiate templates (Also see -nopt, -ptr, -ptsuf, and -ptv). This is the default -strong_ Control the manner in which bytes and volatile words are accessed (Also see -weak_ volatile). 1-8 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes -unroll Control loop unrolling done by the optimizer. o asm support This version of DEC C++ provides asm support so that you can embed assembly language instructions in your C++ code. See the header file /usr/include/c_asm.h for information and examples on how to use asm support. See the header file /usr/include/machine/regdef.h for register names that can be used in asm builtins. The following example shows the use of an asm for the umulh instruction: #include f(long *pl, long op1, long op2){ *pl = asm("umulh %a0, %a1, %v0", op1, op2); } Some restrictions apply; see Section 1.4.9.1 for details. o Language extension The expression T(), where T is a simple type specifier, now creates an rvalue of the specified type, whose value is determined by default initialization. According to the The Annotated C++ Reference Manual, the behavior is undefined if the type is not a class with a constructor, but the ANSI working draft removes this restriction. With this change you can now write: int i=int(); // i must be initialized to 0 o Additional file name suffixes The DEC C++ compiler assumes a file is a C++ source file if the file name has any of the following suffixes: .cxx .cc .C .cpp .CPP .CC .CXX Previously, only the suffixes, .cxx, .cc, and .C were recognized. o oldc89 and ild The oldc89 compiler and ild incremental linker are not included with this release. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-9 1.4.5 Problems Fixed in Version 5.6 The following problems have been fixed in Version 5.6: o A problem that sometimes led to excessive recompilation of templates during link-time automatic instantiation has been corrected. This problem could contribute to long rebuild times after modifying some source files. [4295, BRO100975] o Occassionally, an infinite recursion in the compiler would result in a segmentation fault and a message can't grow stack space when instantiating a template. This problem has been fixed. [3827] o The compiler no longer incorrectly diagnoses an error due to not casting an object to a parent class. [3965, ZUO101051] o The compiler now generates a copy constructor for any class when it is needed, even if the user has not specified any explicit constructor. o Member functions of classes nested within template classes are now automatically instantiated. [3807, 3433] o Incomplete type-name template-args now work under automatic template instantiation. [3864] o Overload resolution now only instantiates functions when necessary. This eliminates unjustified illegal argument combination diagnostics for unnecessary functions. [3860, 3858, 3655, 3636] o The -feedback switch now works. [3874] o Template pure virtual functions with defined bodies are now automatically instantiated. [3887] o If the destructor for an object with static storage duration threw an unhandled exception, the application would loop in the exception handling facility. Such exceptions now call the library function terminate. [3922] o Now code is generated for friend functions defined within a class declaration under automatic template instantiation. [3926] 1-10 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes o Diagnostics generated during an instantiation are now accompanied by another diagnostic indicating the template name and the type currently being used for the instantiation as well as the location of instantiation. [2314] o The compiler could run out of memory while processing complex programs such as STL applications. The internal memory corruption problem that caused this has been fixed. [3626] o Function template overload resolution now takes cv- qualification into account when resolving arguments that are pointers to functions. [4138] o Non-type template-arguments of nested enum type no longer crash the compiler. [4141] o Passing a (non-const) temporary value to a non-member user-defined operators whose first argument is a non- const reference type no longer gives an error-level diagnostic. [4107] o Pointers to members are now allowed as template parameters. [3194] o User-defined reference conversion operators are now called by casts under -ms mode. o Carriage return/line feed line terminators are now legal in -ms mode. [3958] o Explicit destructor calls for types with no destructors will now execute any side-effect causing operators in the call's prefix argument. [4269] o cxx -o /tmp/t.o -Hf t.cxx will now write .o files into cxx_repository. [4231] 1.4.6 Problems Fixed in Version 5.5 The following problems have been fixed in Version 5.5: o This version fixes a problem that caused incorrect debugging information to be generated by the compiler in some instances. This problem could cause Ladebug to display warnings when loading an executable or to display incorrect line number information. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-11 o This version fixes a problem that caused the compiler to incorrectly generate a diagnostic for the parameter list of method in the sample code below [3750]: template class opiRef; class opiRef { opiRef(); void method(double, opiRef); }; o This version eliminates extraneous instructions that were sometimes generated after a throw [3693]. o With this version, DEC C++ automatic instantiation no longer instantiates inline member functions of a class template if these functions are not used within the application. o See Section 1.12.3 for problems fixed in the C++ Standard Library. 1.4.7 Problems Fixed in Version 5.4 The following problems have been fixed in Version 5.4: o This version fixes a problem that caused the ladebug debugger to give an assertion failure or crash when loading an executable. [3401, 3453] o This version fixes a problem involving try blocks within handlers where a throw caused a segmentation fault before the catch block was reached. [3437] o The DEC C++ compiler now accepts calls of destructors on built-in types. [321] o See Section 1.12 for problems fixed in the STL. 1-12 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1.4.8 Problems Fixed in Version 5.3 The following problems have been fixed in Version 5.3: o Previously, an attempt to use dlclose(3) to deallocate a dynamic library containing C++ static objects with destructors would fail. The destructors would not be run by dlclose, and a segmentation fault would occur at process exit. This problem has now been fixed; dlclose will now correctly invoke all of a dynamic library's static destructors. [1718] o DEC C++ used to require explicit definitions for static data members. Tentative definitions are now provided automatically when compiling with the -cfront compatibility mode switch. [127] o Previously, DEC C++ would only allow references to static data members within default arguments in member functions if the static data members had been declared earlier in the class. Now, forward references are allowed. [290] o Previously, DEC C++ would reject as an error the use of a protected or private type in an invocation of #pragma define_template. This is now accepted. [646] o Previously, DEC C++ required template-names within the bodies of template declarations to have a template- arg-list argument, and did not allow the names of constructors and destructors to have template-arg-list arguments, as, for example, in the following : template class C { public: C(); ~C(); C *p; }; Such template-arg-list arguments (for example, ) are now optional. Thus, DEC C++ now accepts the following: [1316] DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-13 template class C { public: C(); ~C(); C *p; }; o The -define_templates option now instantiates template friend functions. [1738] o Inline function templates with const arguments are now successfully instantiated by calls with non-const arguments. [1742] o The -define_templates option no longer causes multiply- defined symbols for explicit specializations. For example, DEC C++ now accepts the following: [1970] template class C { void f(T); }; template void C::f(T) {} void C::f(char) {} o DEC C++ no longer diagnoses extraneous semicolons at file scope under the -cfront and -ms compatibility modes. [2175] o DEC C++ no longer bugchecks when compiling a program containing a call to a virtual function of a template- arg type. For example, DEC C++ now accepts the following: [2454] template class HANDLE { public: HANDLE(T &t) { t.use(); } }; class CHAR { public: virtual void use() {} HANDLE resize(); }; o Previously, DEC C++ would reject as an error the declaration of a union containing a struct, which in turn contained a volatile member. Such declarations are now accepted. [2971] 1-14 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1.4.9 Current Restrictions This section contains usage notes and known problems with DEC C++ Version 5.6. 1.4.9.1 Restrictions on DIGITAL UNIX Version 3.n Systems These restrictions apply exclusively to the DIGITAL UNIX operating system, Versions 3.n. o You cannot use the -shared option with the cxx command. For information on linking shared libraries, see Section 1.6. [2531] o Currently, DECthreads exceptions and Distributed Computing Environment (DCE) exceptions are not compatible with C++ exceptions. DCE and DECthreads exceptions cannot be caught by C++ exception handlers. Neither do destructors get called when a DCE or DECthreads exception causes an unwind past a C++ stack frame containing objects needing destruction. Likewise, thrown C++ exceptions cannot be handled by DCE or DECthreads exception handlers. Neither do DCE or DECthreads finally clauses get executed if a C++ exception unwinds past a stack frame containing DCE or DECthreads finally clauses. If you avoid using DCE and DECthreads exceptions, then you can safely use C++ exceptions in multi-threaded programs so long as the handling of an exception does not cause the destruction of a running thread. The DEC C++ Class Library task package has a similar restriction pertaining to return from such a constructor. [1445] o Some restrictions apply when using .s files and asm in-line assembly language support. - Although .s files can be generated (using the -S flag) on DIGITAL UNIX Version 3.n systems, these files use features supported only by as in DIGITAL UNIX Version 4.0 or later. - Some complex asm builtins require DEC C++ to create an .s file as an intermediate step in the creation of a .o file. This will result in an error on DIGITAL UNIX Version 3.n systems because of the above mentioned .s file restriction. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-15 - On DIGITAL UNIX systems released prior to Version 4.0, the header file c_asm.h contains the following lines: #ifdef __cplusplus #error is not a valid C++ header #endif To enable desired asm support, you can copy the corresponding function declarations and pragmas from c_asm.h. For example, if you want to use the asm that returns a long, include the following: long asm( const char *,...); #pragma intrinsic( asm ) 1.4.9.2 General Restrictions These restrictions apply generally to DEC C++ for DIGITAL UNIX, regardless of the operating system version. o See Section 1.7.6 (namespace restrictions) for restrictions related to support for namespaces. o When compiling with -g, debugging scope information for classes, structs, and unions is not represented accurately. All classes, structs, and unions are described as being at file scope. Nesting is preserved, however; only the outermost class, struct or union is placed in file scope. For example, consider the following source program: main() { class C {} c; return 0; } foo() { class C { class D {} d; } c; return 0; } 1-16 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes This program is described as follows to the debugger: class C {}; main() { C c; // Still gets class C {} return 0; } class C { class D{} d; } c; foo() { C c; // Still gets class C { class D {} d; } return 0; } This has a few implications for ladebug, namely: o The whereis command, when executed on class, struct, or union names, will always report the item as being defined in file scope. However, variable instances of those classes, structs, and unions will be reported correctly. o If you have more than one class, struct, or union with the same name in a particular file, commands dealing directly with class names (for example class, whatis) may not work correctly (they may choose the wrong class). You will not be able to use ladebug's scope resolution to override this. However, variable instances of those classes, structs, and unions will behave correctly. o If stepping into member functions of classes, structs, or unions defined within functions, variables local to those functions may not be visible to ladebug. Other operations working on classes, structs, or unions behave as expected. o DEC C++ signals an error indicating multiple definitions of the exception class if you, directly or indirectly, include both the and header files in your program. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-17 Two workarounds are possible (presuming you are not actually using the math.h exception class): 1) you can compile with the -D_ANSI_C_SOURCE macro, or 2) you can insert the following lines into your program: #define exception #include #undef exception #include o DEC C++ does not accept the last four productions in the syntax for template type-parameters as specified in section 14.7 of the ANSI C++ Working Paper. o The compiler does not accept a parameter-declaration (non-type template parameters) for function templates. o The DEC C++ compiler reports an error when argument signatures of overloaded functions differ from each other only in enumeration types of the same name defined in different classes. For example: void overloaded_function(class1::enum_name x) { } void overloaded_function(class2::enum_name x) { } To work around this problem, use different names for enumeration types defined within different classes. [1940] o Some restrictions that pertain when using STL with DEC C++ are documented in Section 1.12. [3145] o The -nocleanup option results in smaller and faster programs because it suppresses all runtime invocation of destructors during transfer of control out of a scope by way of a throw or longjmp. Therefore, you should not use the -nocleanup option to build programs that expect destructors to be invoked for local variables when the stack is unwound by a thrown exception, or a call to longjmp. o The -xref command line option directs the DEC C++ compiler to generate a data file that the DEC FUSE Database Manager uses to create a cross-reference database file. This improves the performance of the DEC FUSE C++ Class Browser, Call Graph Browser, and Cross-Referencer, which use the database file for their 1-18 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes operations. However, when you use the DEC C++ scanner, the C++ source files cannot contain nonmember template function declarations (in contrast to a class template or member function template declaration). If a source file does have such a declaration, the DEC C++ compiler terminates abnormally at the line of the declaration. The cross-reference database that is subsequently created has incomplete information about the source file. o In versions of DIGITAL UNIX prior to Version 4.0, the header file /usr/include/alloca.h declared the alloca function to return a pointer of type char * . Starting with DIGITAL UNIX Version 4.0, the alloca function will return a void * pointer. This will cause any C++ program which assigns the alloca function's result to a char * to be rejected. The error can be eliminated by casting the alloca function's return value to char *. [3166] o Programs that declare a function parameter that is an array of an incomplete type will not compile with the DEC C++ compiler. [47] 1.4.10 Other Restrictions This section describes problems, of interest to DEC C++ users, that DIGITAL has no current plans to fix. Where feasible, a way to work around the problem is provided. o The dlclose routine cannot be used to delete a shared object (.so) until after any handlers handling an exception, thrown from the shared object, have exited. This restriction is necessary because, when exiting from a handler, the C++ exception support needs to reference data structures that were defined at the throw point. o The dbx debugger does not support DEC C++. To debug programs written in C++, use the Ladebug debugger. 1.5 Improving Build Performance This section contains suggestions for improving the performance of DEC C++ on your system. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-19 1.5.1 Object File Compression On DIGITAL UNIX V4.0 or later, object files are compressed by default. (Object file compression is not supported on versions prior to DIGITAL UNIX V4.0.) Object file compression reduces object file size. Compressed object files may result in shorted link times, depending on characteristics of the system and the application. If link times are an issue, compare the times to build your application when compiling with -compress (the default on DIGITAL UNIX V4.0) and -nocompress. 1.5.2 Use of Shared Libraries Partitioning a large application into several shared libraries, which are then linked into an executable, is a useful technique for reducing link times during development. See Section 3.4.4 Using DEC C++ for DIGITAL UNIX Systems. 1.5.3 Template Instantiation The cxx command automatically instantiates templates by prelinking to find unresolved symbols due to uninstantiated templates. Instantiations are completed by compiling instantiation source files in the repository. The prelinking and compiling process is repeated until all template instantiations have been compiled. For some applications, the link-time automatic instantiation process can be time consuming. The following approaches may be helpful in reducing the amount of time it takes to build your application: o Selectively use compile-time instantiation options for some modules. These options can improve build performance because templates are instantiated when the original C++ sources files are compiled without the need to reprocess large header files. See Section 1.9 for more information concerning the -define_templates, -tused, and -tlocal command line options. o Build a reusable library of instantiations. With this approach, stable and common instantiations are compiled, and the resulting object files are put in a library. When building your program, you link with this library rather than redoing all instantiations every time you 1-20 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes build. At the end of Section 5.2 in Using DEC C++ for DIGITAL UNIX Systems is a step by step example on how to create a library of common instantiations. 1.6 Linking a DEC C++ Program or Shared Library DIGITAL generally recommends that you use the cxx command to invoke the linker rather than invoking it directly. If you need to use the ld linker directly, you may have to modify your ld command whenever you install a new version of DEC C++ or DIGITAL UNIX. After doing such an installation, invoke the cxx command and specify the - v option to display the ld command generated by the cxx command. Then, compare this ld command with your ld command and make any necessary changes. The -shared option for the cxx command cannot be used on DIGITAL UNIX V3.n systems because the cc command that the cxx command generates does not support the -shared option for linking shared libraries. If you use the -shared option on a DIGITAL UNIX V3.n system, the cc command adds -call_shared when invoking the linker. This generates the following error: ld: -call_shared: must specify only one of -shared, -call_shared, -non_shared To link shared libraries on DIGITAL UNIX V3.n systems, you need to invoke the linker directly, using -shared and the options and parameters that would normally be passed to ld by the cxx command. You can determine what these options and parameters are by specifying -v on the cxx command. If you are using the cxx command to compile multiple source files, you can use the following procedure to build a shared library. 1. Specify the -v and -call_shared options on the cxx command. For example: cxx -v -call_shared -o mylib.so file1.cxx file2.cxx 2. Relink by invoking ld directly using the last ld command that is displayed by the previous step, after substituting -shared for the -call_shared option. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-21 Note that with automatic instantiation, ld is normally invoked multiple times from the cxx command. Repeat only the very last link that is displayed by cxx -v (replacing -call_shared by -shared). If you are compiling a single source file, a slight modification is needed to the procedure because the object file is deleted after a successful link. To handle this case, compile first with the -c option (compile-only) and invoke the cxx command with the resulting object file. For example: cxx -c file.cxx cxx -v -call_shared -o mylib.so file.o Relink after replacing -call_shared with -shared. 1.7 Namespaces Support DEC C++ Version 5.6 has added support for namespaces, as specified in the draft ANSI C++ Standard. Section 1.7.6 describes restrictions that pertain to namespaces support. A namespace is an optionally named region in which you can place declarations. They are useful for avoiding name clashes. For example, namespace N { int x; } namespace M { double x; } Placing these conflicting declarations of x into differently-named namespaces, lets you use both variables safely in your program; you can use the appropriate qualified names (N::x, M::x), or use one of the other means described in this section. You can split the definition of a namespace into separate parts that can appear in one or more translation units. A translation unit can be thought of as a single source file together with any header files that the source file pulls in. 1-22 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1.7.1 Namespace definition and namespace extension A namespace is defined as follows: namespace identifier { namespace-body } namespace-body Is a sequence of declarations. Defining another namespace using the same name constitutes an extension namespace definition. For example: namespace N { int n; } ... namespace N { // extend namespace N void func(void); } The identifier used to name a namespace must be unique in the region where it appears. Every namespace definition must appear in the global scope or in a namespace scope. Namespaces can be nested. 1.7.2 Unnamed namespaces You may omit the identifier in a namespace definition: namespace { namespace-body } An unnamed namespace definition behaves as though it was written as: namespace unique {} using namespace unique; namespace unique { namespace-body } DEC C++ replaces all occurrences of unique in a translation unit with the same identifier, and this identifier is different from all other identifiers Unnamed namespaces are intended to be the preferred alternative to using the static keyword in namespace scope. Unnamed namespaces allow items to be visible within an entire compilation unit, but not visible in other translation units. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-23 1.7.3 Namespace Alias A namespace alias declares an alternate name for an existing namespace, according to the following syntax: namespace-alias-definition: namespace identifier = qualified-namespace-specifier ; qualified-namespace-specifier: ::opt nested-name-specifier opt namespace-name The identifier in a namespace alias definition becomes a synonym for the qualified namespace specifier. For example: namespace Outer { namespace A_Long_Inner_Name { int x; } } namespace N = Outer::A_Long_Inner_Name; N::x = 0; // same as Outer::A_Long_Inner_Name::x = 0; 1.7.4 using Declaration A using declaration introduces a name into a declarative region. That name is a synonym for a name declared somewhere else. The name specified in a using declaration in a class or namespace scope shall not already be a member of that scope. The syntax of a using declaration is as follows: using-declaration: using ::opt nested-name-specifier unqualified-id ; using :: unqualified-id ; Using declarations can result in function overloading. For example: namespace M { void f(double); } namespace N { void f(int); } 1-24 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes void sub(void) { using M::f; using N::f; f('a'); // calls N::f(int) f(1); // calls N::f(int) f(1.2); // calls M::f(double) } A using declaration that declares a class member, must refer to a member of a base class. Using declarations in classes are similar to access declarations. 1.7.5 using Directive A using directive specifies that the names in the nominated namespace can be used in the scope where the directive appears, after the directive. A using directive cannot be used in class scope, but only in namespace scope or block scope. Further, a using directive does not declare names in the scope where the directive appears, it merely allows access to the names declared in the nominated namespace. Using directives are transitive, for example: namespace M { int i; int j; } namespace N { int i; using namespace M; } void f() { using namespace N; j = 0; // assigns 0 to M::j i = 1; // ambiguous, both M::i and N::i are visible } If a namespace is extended after a using directive for that namespace, the additional members can be used after the extension namespace definition. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-25 1.7.5.1 Unqualified Name Lookup With using Directives For unqualified name lookup, names appear in the nearest scope that contains both the using directive and the namespace definition. For example: namespace N { int n = 1; } namespace A { int n = 2; namespace B { using namespace N; void f() { cout << n; } } } ... A::B::f(); // prints out the value 2 from A::n This example shows that a using directive does not insert the declarations from a namespace into the region where the using directive apprears. The name lookup would look in the following scopes, in the following order: Namespace B Namespace A File scope, including namespace N Because name n is not locally declared in B, a unqualified name lookup must proceed upward through various scopes. The using namespace N directive signifies that looking in namespace N to resolve names is permitted. However, the definition of namespace N is at file scope, so any names from N are not available until the lookup has walked through scope all the way to file scope. Thus, in this example, the name from namespace A is found and used. 1.7.5.2 Qualified Name Lookup with using Directives Given a qualified name, X::m, the compiler creates a set of all declarations of m in namespace X, and in all the namespaces nominated by using directives in X. Recall that using directives are transitive. Also, if any namespace directly contains a declaration of m, then any using directives in that namespace are not followed. The following is an example: 1-26 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes int x; namespace Y { void f(float); void h(int); } namespace Z { void h(double); } namespace A { using namespace Y; void f(int); void g(int); int i; } namespace B { using namespace Z; void f(char); int i; } namespace AB { using namespace A; using namespace B; void g(); } void h() { AB::g(); // g is declared directly in AB, // therefore S is { AB::g() } and AB::g() is chosen AB::f(1); // f is not declared directly in AB so the rules are // applied recursively to A and B; // namespace Y is not searched and Y::f(float) // is not considered; // S is { A::f(int), B::f(char) } and overload // resolution chooses A::f(int) AB::f('c'); // as above but resolution chooses B::f(char) AB::f(1.0f); // no best match between A::f(int) and B::f(char) DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-27 AB::x++; // x is not declared directly in AB, and // is not declared in A or B, so the rules are // applied recursively to Y and Z, // S is { } so no x is found AB::i++; // i is not declared directly in AB so the rules are // applied recursively to A and B, // S is { A::i, B::i } so the use is ambiguous // and the program is ill-formed AB::h(16.8); // h is not declared directly in AB and // not declared directly in A or B so the rules are // applied recursively to Y and Z, // S is { Y::h(int), Z::h(double) } and overload // resolution chooses Z::h(double) } 1.7.6 Restrictions This section describes restrictions to namespace support in DEC C++. 1.7.6.1 Restrictions in the Current Implementation o DEC C++ Version 5.6 does not allow a forward declaration of a class in a namespace followed by the definition of the class outside of the namespace. For example: namespace N { class C; } ... class N::C { ... }; If a forward class declaration is needed, the workaround it to define the class in a namespace extension: namespace N { class C; } ... namespace N { class C { ... }; } 1-28 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes o When a using declaration brings a name from a base class into a derived class, a member function in the derived class should override the function (with the same name and parameters) from the base class. This currently does not work correctly. o Version 5.6 does not support automatic instantiation of templates that are defined within a namespace. Manual instantiation is supported for these templates. o Version 5.6 does not support the dependent name lookup rules for templates defined inside namespaces. An example of this is: namespace A { int f(char) {return 1;} template int g(T) {return f(0);} } int i = A::g(12.34); int f(int) {return 2;} The correct value for i is 2. When A::g is called, it should see f as an overloaded function, for all versions of f visible at the scope where A::g is defined, and the scope where A::g is being instantiated, that is: the file scope. Version 5.6 currently uses the versions of f visible from the scope where A::g is defined, namely the scope of namespace A. 1.7.6.2 Debugging Programs That Use Namespaces For this version of DEC C++, namespaces are presented as classes of the same name to the debugger. This affects ladebug in the following ways: o Ladebug does not make a distinction between namespaces and classes. For example, Ladebug reports a namespace as being a class if you issue the whatis namespace-name command. o The using declaration is not supported; you must fully qualify names in a namespace. For example: namespace_name::name DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-29 o Namespace definitions may be different between different files. Thus, you may need to qualify a namespace with a filename or set your file scope to view namespace extensions. For example, suppose your program has two source files: one.cxx and two.cxx as follows: //one.cxx namespace ns { int a; } void two(); main() { two(); } //two.cxx namespace ns { int a; } namespace ns { // extend the namespace float b; } void two() { } While you are in main(), you can view ns::b using either of the following methods: print "two.cxx"`ns::b #qualifying with name file two.cxx ; print ns::b #setting file scope 1.8 Reducing Object File Size During Debugging Starting with Version 5.6, the compiler reduces the amount of debugging information in object files when -g is specified. If the debugger describes a class as or lacks debugging information, you may need to compile using the -gall option. See Section 1.8.1 for information on how to use the -gall option. 1-30 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes In versions of DEC C++ prior to Version 5.6, debug information for classes and structs was generated whenever they were processed by the compiler. Thus, debug information for particular classes and structs defined in header files often appeared in multiple object files, which increased the overall size of objects and executables. To reduce debuggable executable size, DEC C++ now attempts to generate debug information for a particular class or struct as few times as possible. Describing classes and structs this way has tremendous savings; reductions in executable sizes of up to 70% have been observed for some applications. In most cases, the object file that contains the debug information for a particular class is linked into the executable and is available to the debugger. However, there are some situations where this might not be the case: o A class description may be in a library object file that is not linked into the final debuggable executable. o A class description may be in a different shared object than the shared object you may be trying to debug. o The object file that would have contained the class description does not because it was compiled without the -g option. 1.8.1 Using the -gall option If ladebug describes a class or struct as , you should compile the file in which the class or struct is described as with the -gall option. Compiling a file with the -gall option generates debug information for all classes and structs that appear in that source file. You can generate complete debugging information when compiling a particular file by specifying the -gall option on the command line. You can also define a pattern so that a file is compiled with complete debugging only if the file name matches the pattern. Specifying a pattern lets you compile all files with the same command and still have particular files compiled with the -gall option to generate complete debugging information. You can specify a pattern in two ways: o Specify "-gall " on the command line DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-31 o Define environment variable CXX_GALL_PATTERN as the pattern can be a list of file names (with each file name separated by a comma or colon), filename patterns, or a combination of a file name list and filename patterns. See fnmatch(3) for valid filename patterns. The -gall option is ignored unless -g, -g2, or -g3 is also specified. Example: The following example shows how opaque_class is initially descibed as by ladebug, and how this is remedied by compiling the file opaque_file.cxx with the -gall option: Welcome to the Ladebug Debugger Version 4.0-39 . . . object file name: opaque_file Reading symbolic information ...done (ladebug) # First, note the class is (ladebug) whatis opaque_class class opaque_class Information: An type was presented during execution of the previous command. For complete type information on this symbol, recompilation of the program will be necessary. Consult the compiler man pages for details on producing full symbol table information using the -g (and -gall for cxx) flags. (ladebug) # Next, find the offending file with ladebug's "file" command (ladebug) file opaque_file.cxx (ladebug) # Quit to recompile opaque_file.cxx with the -gall option (ladebug) quit Recompile the file opaque_file.cxx with the -gall option in one of the following ways: o Supply -gall on the command line (useful for hand builds): cxx -g -gall -O0 opaque_file.cxx 1-32 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes o Supply -gall with a pattern (useful for a generic rule in a makefile): cxx -g -gall opaque_file.cxx -O0 opaque_file.cxx In a makefile, this may look something like the following: CXX = cxx CXXFLAGS = -g -gall opaque_file.cxx -O0 $(CXX) $(CXXFLAGS) opaque_file.cxx o Supply the pattern to the environment variable CXX_GALL_ PATTERN (useful for not modifying the makefile): setenv CXX_GALL_PATTERN "opaque_file.cxx" cxx -g -O0 opaque_file.cxx Here are some alternate methods, showing the pattern capabilities of the -gall option: o Compile both opaque_file.cxx and another_file.cxx with -gall: cxx -g -gall opaque_file.cxx,another_file.cxx -O0 opaque_file.cxx o Compile any file starting with opaque or another with -gall: setenv CXX_GALL_PATTERN "opaque*.cxx:another*.cxx" cxx -g -O0 opaque_file.cxx 1.8.2 Hints for using the -gall option effectively For best debugging and smallest objects and executables, we recommend that you use the -gall option selectively as follows: o Only use the -gall option when you see a class or struct described as . o Try to compile as few files with -gall as possible. o Choose these few files wisely. If you are seeing types in only one file, try compiling only that file with the -gall option. If you are seeing types in many files, try compiling a file that includes many project header files with the -gall option. Doing so will increase the chance that messages will disappear for the entire application. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-33 1.9 Additional Template Instantiation Options for Version 5.5 In addition to link-time automatic instantiation (the default) and compile-time instantiation using the - define_templates option, DEC C++ Version 5.5 provides two additional forms of compile-time instantiation, as follows: -tlocal Instantiate only the template entities that are used in this compilation, and force those entities to be local to this compilation. -tused Instantiate only the template entities that are used in this compilation. The template entities are instantiated with external linkage. Similarities and differences between the three compile-time instantiation options are as follows: o With all three options, if a module contains a call to a function template (or takes its address), an instance of the template is generated. o The options differ when a class template is used within a module. With the -define_templates option, all member functions within a class template are instantiated, whether or not they are used. With the -tused and -tlocal options, only the member functions that are actually used in the module are instantiated. o The options differ with regard to the linkage chosen for the instantiated functions and static data members. With the -define_templates and -tused options, functions and static data members are instantiated with external linkage. This can lead to multiply defined symbol errors at link time, if the same template entities are instantiated in different modules. Thus, these options generally should not be specified for all modules in an application. With the -tlocal option, functions and static data members are instantiated with internal linkage and are thus local to the module that generates the instantiation. This avoids the problem of multiply defined symbol errors that can occur at link time when you specify either the -define_templates or -tused option for more than one module in an application. 1-34 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes o With all three options, static members of a requested class template are instantiated, whether or not they are used. When you specify the -tlocal option, each module contains an instance of any static data members instantiated from a requested class template. If the initializers for such static data members cause side- effects at runtime, note that the side-effects will occur for each instantiation in each module. o With all three instantiation options, instantiations for requested template entities are generated at compile time when the template is used. This implies that the module requesting the template entity must contain the corresponding template definition for that particular template and any dependencies that the template definition contains, prior to the template's point of use. If the template definition is not present within the compilation prior to the instantiation request, DEC C++ will be unable to materialize the requested template entity. Determining When to Use the Compile-time Instantiation Options The compile-time instantiation options are primarily useful for reducing the time required to build an application. One approach to reduce build times, would be to identify within your application the one module that contains the most uses of template entities. Once identified, this module can be compiled with either the -define_templates or -tused option and the remaining modules compiled with automatic instantiation. This approach avoids the problem of multiply defined symbols at link time that can occur when using these options; this approach also offers the convenience of automatic instantiation. You can also use the -tlocal option to improve build times, provided that any redundant initializers for static data members do not have unwanted side effects. You can specify the -tlocal option for all modules in your application, something you cannot do with the -define_templates and - tused options. With the -tlocal option, instantiations are local to each module. These local instantiations are not shared across the various modules within an application. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-35 For some applications, multiple copies of the same instance can greatly increase the size of executables. 1.10 Explicit Instantiation The new ANSI syntax for explicit instantiation has been implemented in the DEC C++ compiler. The syntax for this (as of the January 26th, ANSI C++ working paper) is as follows: template declaration Currently, DEC C++ accepts only template function declarations and template class declarations. DEC C++ does not yet support explicitly instantiating template member functions or template static data members. Note that because explicit specification of function template arguments is not yet implemented, a template argument list may not be specified in an explicit instantiation. Examples of use: template class X { public: // stuff; }; template void f(const T &t) { printf("f(const T&) called\n"); } template class X; // instantiate template class X with T=int template void f(int &); // instantiate template function f with T=int template void f(int &); // not yet implemented The ANSI syntax is unambiguous regarding template functions. Only the template function that matches the declaration in the explicit instantiation will be instantiated. The DEC C++ #pragma define_template directive is ambiguous, and instantiates all the template functions that have the same number of template parameters as specified in the pragma. To explicitly instantiate templates, DIGITAL now recommends that you use the new ANSI syntax instead of the #pragma define_template directive because the new syntax is more portable, as other compiler vendors implement the ANSI standard. 1-36 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes Note that the ANSI syntax for explicit instantiation uses a semicolon at the end of the declaration, while the syntax for the #pragma define_template directive does not. Omitting the semicolon can lead to obtuse error messages, because the code that follows may look like part of the declaration in the explicit instantiation. Explicit instantiation currently has the same restrictions on code ordering as does the #pragma define_template directive. The explicit instantiation must appear in the code after the definitions of a class and its member functions or after the definition of the template function. 1.11 Release Notes for the DEC C++ Class Library This section describes the problems fixed, known problems, and restrictions for the DEC C++ Class Library. See Section 1.12 for information on the C++ Standard Library. Please note that String Package, which is part of the DEC C++ Class Library, is entirely different from the String class that is part of the newly-implemented C++ Standard Library and known as the String Library. Do not confuse these two contrasting implementations. 1.11.1 Features and Problems Fixed in Version 5.4 o The reference (man) pages have been reorganized to reflect the latest edition of the DEC C++ Class Library Reference Manual. New pages have been added, namely cxxlib.intro, Mutex, iostream, and stdiostream. A new sbuf page has been substituted for the sbuf.prot and sbuf.pub pages. The contents of the c_exception page have been merged with the complex reference page. 1.11.2 Features and Problems Fixed in Version 5.3 o The istrstream class has two new constructors which accept (const char*) and (const char*, int). o Within the String class, two versions of the operator[] member function have been added. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-37 o As of DIGITAL UNIX Version 4.0, within the String class, the operator() member function is now declared const. The non const version of this routine is retained for compatibility. o As of DIGITAL UNIX Version 4.0 and DEC C++ for DIGITAL UNIX Version 5.3, the DEC C++ Class Library is threadsafe. Refer to the DEC C++ Class Library Reference Manual for details on the threadsafe support, including a new Mutex Package. o Within the ios class, the following member functions are now declared const: bad() eof() fail() fill() flags() good() precision() rdstate() *tie() width() o Prior to DIGITAL UNIX Version 4.0, if you link using the -non_shared command line option, the cxx driver inserts the following into the ld command to ensure that the initialization of the iostream package is performed before your application's initialization code is run: -u __ct__13Iostream_initXv -lcxx This is essential if your application contains non- local static objects whose constructors use the iostream package. If you use ld directly to link your application, insert the above in your ld command after _main.o and before your application's modules. This change is not required on DIGITAL UNIX Version 4.0 and later. o The header file iomanip.hxx now includes the header file iostream.hxx. o As of DIGITAL UNIX Version 4.0, there are new String class operator+ functions with argument lists of (const char *), (const String &), and (const String &), (const char *). o As of DIGITAL UNIX Version 4.0, within the complex class, the following operator routines now return a reference to the complex object: += -= *= /= Previously, these routines had no return value. 1-38 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1.11.3 Restrictions o Conflict with redefinition of clear() If your program includes both and , DEC C++ may fail to compile your program because clear() is defined by both header files. In , clear() is defined as a macro whereas in clear() is defined as a member function. Workarounds: If your program does not use either clear() or uses the clear(), include the header first, followed by . If your program uses the ios::clear() function, undefine the clear() macro directly after the #include statement. o Because of a bug in the task package, if you are using that package and you compiled your application with DEC C++ Version 5.6, your application may encounter runtime errors such as segmentation faults. To avoid these problems, recompile your application specifying the DEC C++ -preempt_symbol option. For more information about the -preempt_symbol option, see the cxx(1) reference page. o Use of clog() and the iostream package's clog A single application is restricted from using both the math library function clog() and the iostream Package's clog object. This restriction is necessary because libm and libcxx each contain a definition for the global symbol clog and these definitions are incompatible. Furthermore, applications that reference either of the clog symbols must not include both -lcxx and -lm on their ld command line. Any attempt to do so causes ld to generate an error because clog is multiply defined. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-39 1.12 Release Notes for the C++ Standard Library This section describes the enhancements, problems fixed, known problems, and restrictions for the C++ Standard Library. See Section 1.11 for information on the DEC C++ Class Library. Please note that the current version of DEC C++ implements the new standard string class, known as the String Library. Do not confuse this with the String Package, which is part of the DEC C++ Class Library implemented in earlier versions of DEC C++. 1.12.1 Enhancements and Changes in Version 5.6 o Version 5.6 of DEC C++ includes a subset of the C++ Standard Library. The set includes components supplied with 5.5, plus the Complex Math library. Note that portions of the ANSI C++ Standard Library have been implemented in DEC C++ using source licensed from and copyrighted by Rogue Wave Software, Inc. Information pertaining to the C++ Standard Library has been edited and incorporated into DEC C++ documentation with permission of Rogue Wave Software, Inc. All rights reserved. Portions copyright 1994-1996 Rogue Wave Software, Inc. o The default allocator type parameter for the map and multimap containers has changed to accurately reflect the ANSI draft standard. In Version 5.5, the template parameters looked like: template , class Allocator = allocator< pair > > class map {}; In Version 5.6, they appear as follows: template , class Allocator = allocator > class map {}; 1-40 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1.12.2 Differences between Version 5.5 and Version 5.6 o The function object "times" has been renamed to "multiplies". This helps avoid conflict with the name times in sys/times.h. o The ostream_iterator and istream_iterator classes have two additional template arguments. Instead of ostream_ iterator they are now also templatized on character type and traits type; that is, they are now declared as: class ostream_iterator; class istream_iterator; o The file no longer contains workarounds for missing compiler features. They are now in and have different names. o The select1st function object, which used to be in the header file , has been moved to . This was never in the ANSI draft standard, and is meant to be used only in the implementation of the map container. o The basic_string class now is implemented using copy- on-write reference semantics. This should make the class much more efficient. o The buffer used by rb_tree (and hence by map and set) to store container elements has been reduced from 4028 to 1024 bytes. o The allocator now allocates raw bytes of storage rather than typed storage. The allocator uses an allocator_ interface class to provide its "typed" implementation. This change is to work around the lack of support for member templates. For details, see the section on allocators in Using DEC C++ for DIGITAL UNIX Systems. o Strings now have support for wide characters. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-41 1.12.3 Problems Fixed in Version 5.6 o If your system was a version of DIGITAL UNIX prior to Version 4.0, and your application defined a non-local static object of type map, multimap, set, or multiset or defined a non-local static object which constructs one of those types, certain modificatons were advised to avoid a segmentation fault during image activation. Such precautions are no longer necessary. o Prior to DEC C++ V5.6, the following overloaded function templates found in and made use of the SL_INLINE_FCTS macro to force their code to be inlined. __advance __equal_range __distance __lower_bound __reverse __rotate __unique_copy __upper_bound This worked around the lack of compiler support for manually instantiating overloaded function templates. Inlining was the only way to manually instantiate overloaded function templates. For example, the following would not work: class C { public: C operator++(int) { return *this; } }; class D { }; class D_tag {}; class C_tag {}; template void __distance(T iter, D_tag) {} template void __distance(T iter, C_tag) {iter++;} 1-42 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes //Generates an error because the compiler instantiates all //occurrences of __distance and operator++ is not supported //for class D. #pragma define_template __distance int main() { __distance(D(),D_tag()); return 0; } The current DEC C++ compiler supports explicit instantiation, which can be used to manually instantiate overloaded function templates. Therefore SL_INLINE_FCTS is obsolete and has been removed from and . If you want to use one of the function templates in and , you must change your sources to use explicit instantiation directly. The following example illustrates use of the new explicit instantiation syntax: class C { public: C operator++(int) { return *this; } }; class D { }; class D_tag {}; class C_tag {}; template void __distance(T iter, D_tag) {} template void __distance(T iter, C_tag) {iter++;} //Use explicit instantiation syntax to force instantiation of //void __distance(D,D_tag) when using manual instantiation. template void __distance(D, D_tag); int main() { __distance(D(),D_tag()); return 0; } DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-43 1.12.4 Enhancements and Changes in 5.5 Version 5.5 of DEC C++ included a subset of the C++ Standard Library. The set included: The Standard Template Library (STL) The String library The Numeric Limits class The auto_ptr class The Standard exception classes 1.12.5 Problems Fixed in 5.5 o A memory leak has been found and fixed in the map() utility. The memory leak was obvious if map() was used within a loop. o The binary_compose and unary_compose functions are no longer in the header. These functions were part of the original Hewlett-Packard C++ Standard Library implementation but they do not exist in the ANSI C++ draft. o The Standard Library no longer uses the new operator during initialization. 1.12.6 Problems Fixed in Version 5.4 o The C++ Standard Library is threadsafe on all versions of the operating system when you use the -D_REENTRANT flag to compile your programs. This flag is turned on by default when you compile with the -threads option. If you compile with -D_REENTRANT on a system earlier than DIGITAL UNIX Version 4.0, you must include -lc_r when you link your program. ________________________ Note ________________________ If you used the threadsafe STL with DEC C++ Version 5.3, you must recompile your modules that use the STL before linking with the new STL run-time provided with DEC C++ Version 5.4 or later. Otherwise you may encounter link errors or unpredictable run-time results. ______________________________________________________ 1-44 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes o The allocate() functions in use the current new_handler flag; they no longer clear the new_handler flag by calling set_new_handler(0). o When you instantiate an STL container with a user- defined type and operate on your container using an algorithm from the header, you will no longer receive compilation errors in stating that T is a struct type but is supposed to be scalar. o Manual Instantiation of Overloaded Function Templates Prior to DEC C++ Version 5.4, the only way to manually instantiate a template function was to use the #pragma define_template directive. However, this directive does not allow you to specify which of a set of overloaded functions to instantiate. This can cause problems, for example, if you try to manually instantiate a map object and compile the following code without automatic instantiation: #include #pragma define_template map > #pragma define_template rb_tree, select1st, int>, less > int main(void) { map > m; return 0; } Without automatic instantiation, the compiler generates undefined symbols for the __distance function. For example: DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-45 ld: Unresolved: __distance(rb_tree, select1st, int>, less >::iterator, rb_tree, select1st, int>, less >::iterator, unsigned long&, bidirectional_ iterator_tag) __distance(rb_tree, select1st, int>, less >::const_iterator, rb_tree, select1st , int>, less >::const_iterator, unsigned long&, bidirectional_iterator_tag) The __distance function is overloaded, so you cannot add a #pragma define_template directive for it because the compiler tries to instantiate all of the __distance functions and reports compilation errors. This problem occurs for the following template functions in the STL: __advance __equal_range __distance __lower_bound __reverse __rotate __unique_copy __upper_bound This problem can now be solved using the explicit instantiation syntax described in Section 1.10. The example code from above now looks like the following: #include #pragma define_template map > #pragma define_template rb_tree, select1st, int>, less > template void __distance(rb_tree, select1st, int>, less >::iterator, rb_tree, select1st, int>, less >::iterator, unsigned long&, bidirectional_iterator_tag); 1-46 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes template void __distance(rb_tree, select1st, int>, less >::const_iterator, rb_tree, select1st, int>, less >::const_iterator, unsigned long&, bidirectional_iterator_tag); int main(void) { map > m; return 0; } o Specialization of destroy Functions You no longer need to define specializations for the destroy functions. For example, if your program builds a container of pointers to a user-defined class, my_xxx, then you no longer need to provide the following two specializations for my_xxx: void destroy (my_xxx**) {} void destroy (my_xxx**, my_xxx**) {} o Template Function Matching on String Literals of Different Lengths The latest ANSI C++ draft no longer considers the following code valid: template inline const T& max(const T& a, const T& b) { return 0; } int main () { max ("Joe", "Smith"); // Joe and Smith are different lengths return 0; } The DEC C++ compiler Version 5.3 did not accept this code and previously DIGITAL had recommended a workaround, specifically to cast the arguments as follows: max((const char*) "Joe", (const char*) "Smith"); Now DIGITAL recommends that you remove such code from your program. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-47 1.12.7 Known Problems The following are known problems when using the current release of the STL with the DEC C++ compiler. Where appropriate, workarounds are suggested. o When creating very complicated instantiations (for example, a map of a map of string), you may get a link error when using automatic instantiation (the name of the undefined symbol will be longer than 1022 chars). To workaround this, you can use manual instantiation or local instantiation (see Section 1.10). o The mem_fun classes are now implemented in . Unfortunately they will not work with any member functions that return void (Most of the member functions that are currently in the containers return void). The ANSI standards committee will decide how best to fix this at a future meeting; the committee will either relax the language rules for use of void types in templates or mandate that all these classes have partial specializations for the return type void. The same applies to the adaptors for pointers to the functions pointer_to_unary_function and pointer_to_ binary_function. o Although the following basic_string::compare function should throw out_of_range if the input argument pos1 is greater than str.size(), it does not: int compare(size_type pos1, size_type n1, const basic_string& str) const; For example, the following does not throw out_of_range but should: string s1("long"); string s2; s1.compare(5, 4, s2); o Although the following basic_string constructor should throw out_of_range if n == npos, it does not: basic_string(const charT *s, size_type n, const Allocator& a = Allocator()); 1-48 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes For example, the following does not throw out_of_range but should: string s1("a",string::npos) o The following basic_string::compare function does not return a correct result if the input argument n1 is npos: int compare(size_type pos, size_type n1, charT *s, size_type n2 = npos) const; For example, the following does not return 0 but should: string a("abcd"); // this comparison doesn't work. if (a.compare(0, string::npos, "abcd",4)==0) cout << "comparison worked" << endl; o The following is the string typedef defined in : typedef basic_string, allocator > string; Compare this with the following string typedef, as defined by the 24 September 1996 draft: typedef basic_string, allocator > string; The difference provides bug fixes and will be corrected in a future release of DEC C++. Be aware that this deviation from the draft standard may effect how you would declare a common instantiation for string and how you would use the string allocator_type typedef. o The DEC C++ V5.6 allocator class does not conform to the 24 September 1996 draft standard. For details, see the Allocator Class section in Using DEC C++ for DIGITAL UNIX Systems. o The allocate member function of the allocator class allocates memory for n objects of type T but does not construct them. Until the DEC C++ compiler supports member function template arguments, the allocate member function will return a void* rather than a T* as specified by the ANSI C++ Working Paper. To workaround this problem you need to make use of the allocator_interface class. For example, if you declare the following: DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-49 allocator a; The following will give an error message: allocator::pointer p = a.allocate (5); ........................1 %CXX-E-PTRMISMATCH, (1) In the initializer for p, the referenced type of the pointer value "a.allocate(5)" is "void", which is not compatible with "X". Workaround this by using the allocator_interface class as follows: typedef allocator allocator_type; typedef allocator_interface value_alloc_type; allocator_type a; allocator_type::pointer p = value_alloc_type(a).allocate(5,0); o The pow() function defined in may give incorrect results. For example, the following should return 0 but does not: #include #include main() { complex c1(-1,0); complex c3 = pow(c1,-1); double d = c3.imag(); cout << "d: " << d << endl; } o The complex operator<< does not respect precision or ios flags. o Problems with the -ms and -cfront command line options. To preserve existing semantics with cfront or MSVC++, DIGITAL loosened access protection in many places in the Standard Library. If you are compiling with either of these options, consult the ANSI C++ draft to make sure you are not accessing member data or member functions to which you should not have access. o Problem with automatic instantiation and template function matching a string literal to a template argument that expects a const T &. 1-50 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes Consider the following code, which generates the following link error: Unresolved: foo(const char &) //b.h template void foo(const T& value) {} //main.cxx #include "b.h" int main () { foo("ff"); return 0; } You may encounter this error when using the following STL algorithms: binary_search() count() fill() fill_n() find() find_if() lower_bound() max() min() remove() remove_copy() replace() replace_copy() replace_copy_if() replace_if() upper_bound() Workaround: Cast ff to a const char *. In the previous example, change the call to foo to the following: foo((const char*) "ff"); o Problem inserting pairs into maps and multimaps. Calling the pair constructor or using the make_pair() function will not return a pair that can be inserted into a map or multimap. This is because the template instantiation will not infer a const Key type. Workaround: Instead of using these functions, create a pair using the value_type typedefs. For example, in place of the following code: map mymap; mymap.insert(make_pair(10,20)); Substitute the following code: map mymap; map::value_type mvt(10,20); mymap.insert(mvt); DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-51 1.12.8 Restrictions This section describes problems of interest to Standard Library users that DIGITAL has no current plans to fix. Where feasible, a way to work around the problem is suggested. o DEC C++ ships the following non-Standard headers which are for internal use only. Their contents are subject to change and can not be relied on. o Because of a DEC C++ compiler bug, taking the address of a static const data member may produce either a link- time or run-time error. The effect of this bug on the numeric_limits class follows. A link-time error occurs if you take the address of a numeric_limits static const data member for which a specialization is not provided. For example, consider the following program: #include #include main() { numeric_limits NL; const int* ip = &NL.digits10; cout << *ip << endl; } When compiled, this code generates an unresolved symbol link error for numeric_limits::digits10. If you take the address of a static const numeric_limits data member for which a specialization is provided, dereferencing the address yields invalid run-time results. For example, consider the following program: 1-52 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes #include #include main() { numeric_limits NL; const int* ip = &NL.digits10; cout << *ip << endl; } When executed, a program containing this code should print the number nine, instead it prints a zero. o Auto-instantiation does not work correctly when declarations of types that are used to instantiate a particular template are defined in the source file. To avoid this problem, use pragmas or explicit instantiation (see Section 1.10) to force manual instantiation (see Chapter 5 of Using DEC C++ for DIGITAL UNIX Systems), or move the type declarations into a template declaration file. 1.13 Ladebug Debugger Restrictions The DEC C++ Version 5.6 kit includes subsets for the Version 4.0-39 Ladebug debugger and debugger window interface. After installation, you specify the ladebug command to use the command line debugger and the dxladebug command to use the Ladebug window interface (GUI). The following restrictions affect the use of the Ladebug debugger: o You must debug C++ programs generated by DEC C++ Version 5.6 using Ladebug Version 4.0-39 or later. Prior versions of Ladebug do not work with code generated by DEC C++ Versions Version 5.6. When installing DEC C++, you should install the debugger subsets that appear in the setld menu; for example: Ladebug Debugger Version 4.0-39 Ladebug release notes Ladebug Debugger Window Interface DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-53 o The Version 4.0-39 Ladebug window interface (dxladebug) exposes a kernel memory leak that can hang some DIGITAL UNIX Version 3.n systems, requiring a system reboot. This problem does not occur on DIGITAL UNIX Version 4.n systems. If you are affected by this problem, you can use the Ladebug command line interface (ladebug) rather than the window interface (dxladebug). Alternatively, you can contact your local DIGITAL Customer Support Center and request a patch for this problem: ________________________________________________________ Version__Patch_ID_______________________________________ 3.2 OSF320-231 3.2B OSF325-035 3.2C OSF350-147 3.2D-1___OSF360-350147__________________________________ 1.14 DEC FUSE Restrictions The following restrictions affect users of DEC FUSE: o If you use DEC FUSE and C++ templates, you may get DEC FUSE error messages because DEC FUSE is scanning files in the cxx_repository directory. As a workaround, include in your .xrefrc file a statement such as the following: ignore: cxx_repository/* The following restrictions apply if you use DEC FUSE Version 2.1 or 2.1A: o The Version 4.0-39 Ladebug debugger does not work when invoked from within DEC FUSE V2.1 or V2.1A. If you want to use a graphical window interface, specify the dxladebug commmand. (Note the previous restriction, however.) o If you use DEC FUSE Version 2.1 or 2.1A with languages other than DEC C++ and want to continue to invoke Ladebug from within DEC FUSE when debugging those 1-54 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes languages, then you need to take the following steps before installing DEC C++ Version 5.6: 1. Copy the existing Ladebug debugger, /usr/bin /decladebug, to a "safe" area, such as the directory /usr/opt/fuse/bin. 2. Install DEC C++ Version 5.6, including the ladebug subsets. To use the older debugger from within FUSE, define environment variable DEBUGGERENGINE to be the path name of the debugger copied in step 1. o If you install DEC FUSE Version 2.1 or 2.1A after installing DEC C++ Version 5.6, you will need to reinstall the ladebug subsets from the DEC C++ Version 5.6 kit. 1.15 About This Product Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. ©Digital Equipment Corporation 1997. All Rights Reserved. 1.16 Trademarks The following are trademarks of Digital Equipment Corporation: Alpha, Bookreader, DEC, DECnet, Ladebug, DECthreads, OpenVMS, VAX, VAX DOCUMENT, VMS, and the DIGITAL logo. PostScript is a trademark of Adobe Systems Incorporated. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Ltd. DEC C++ Version 5.6 for DIGITAL UNIX Release Notes 1-55 Portions of the ANSI C++ Standard Library have been implemented using source licensed from and copyrighted by Rogue Wave Software, Inc. All rights reserved. The software and information pertaining to such portions of the C++ Standard Library are proprietary to, and comprise valuable trade secrets of, Rogue Wave Software, Inc., which intends to preserve as trade secrets such software and information. This software and information is furnished pursuant to a written license agreement and may be used, copied, transmitted, and stored only in accordance with the terms of such license and with the inclusion of the above copyright notice. This software and information or any other copies thereof may not be provided or otherwise made available to any other person. 1-56 DEC C++ Version 5.6 for DIGITAL UNIX Release Notes