DIGITAL_C++_Version_V6.1-027__________________ Release Notes for Compaq's DIGITAL UNIX September, 1998 This document contains information about new and changed features in this version of DIGITAL C++ for Compaq's DIGITAL UNIX. Digital Equipment Corporation Maynard, Massachusetts __________________________________________________________ September 1998 The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. © Digital Equipment Corporation 1998. All Rights Reserved. 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. This document was prepared using VAX DOCUMENT, Version 2.1. ________________________________________________________________ Contents 1 Introduction.................................... 1 2 Important Compatibility Information............. 1 3 Enhancements and Changes in Version 6.0......... 2 3.1 Language Mode Options ........................ 3 3.2 Message Control Options ...................... 5 3.3 Message Information Options .................. 6 3.4 Standard Library Options ..................... 7 3.5 Precompiled Header Options ................... 8 3.6 Template Options ............................. 9 3.7 Language Feature Options ..................... 9 3.8 Performance Optimization Options ............. 10 3.9 Changing the Default Compiler Options ........ 11 3.10 Compiler Version Options ..................... 12 3.11 Compatibility With Previous Versions ......... 12 3.11.1 Language Differences....................... 13 3.11.2 Implementation Differences................. 15 3.11.3 Library Differences........................ 16 3.11.4 Run-Time Library Differences............... 16 3.12 Language Differences Between the Final Draft International Standard and DIGITAL C++........ 19 4 Compiler Problems Fixed in Version V6.1-027..... 20 5 Library Problems Fixed in Version V6.1-027...... 22 6 General Version 6.1 Restrictions................ 24 7 Improving Build Performance..................... 35 7.1 Object File Compression ...................... 35 7.2 Using Shared Libraries ....................... 36 7.3 Using Precompiled Headers .................... 36 8 Reducing Object File Size During Debugging...... 36 8.1 Using the -gall and -gall_pattern Options .... 37 8.2 Hints for Using the -gall Option Effectively................................... 39 iii 9 Release Notes for the DIGITAL C++ Class Library......................................... 39 9.1 Restrictions ................................. 40 10 Release Notes for the C++ Standard Library...... 42 10.1 Enhancements and Changes in Version V6.1-027...................................... 42 10.2 Restrictions ................................ 47 11 About This Product.............................. 56 12 Trademarks..................................... 57 iv 1 Introduction This document contains the release notes for DIGITAL C++ Version V6.1-027 for Compaq's DIGITAL UNIX. This kit installs two compilers: o The cxx command invokes the Version V6.1-027 compiler. The version is V6.1. o The cxx -oldcxx command invokes the Version 5.7 compiler. The version is V5.7-002. The Ladebug version installed by this kit is 4.0-44 or higher. HTML files are provided for the release notes and some of the product manuals for use with a web browser. You can install these files by selecting the subset DIGITAL C++ HTML documentation. To view this documentation, open the following file using your web browser: /usr/share/doclib/cplusplus/cxx.html 2 Important Compatibility Information Starting with Version 6.0, the DIGITAL C++ compiler differs significantly from previous versions. There are several major differences that you should be aware of before using a Version 6 compiler for the first time. These differences are summarized here and discussed in more detail in Section 3.11. o Language differences Version 6.1 implements most of the Final Draft International ANSI C++ standard (FDIS), which differs significantly from the language specified in The Annotated C++ Reference Manual and implemented by the Version 5.n compilers. When switching from a Version 5.n compiler, you might need to modify your source files, especially if you use the default language mode. In addition, language changes can affect the run-time behavior of your programs. If you want to compile existing source code with minimal source changes, compile using the -std arm option. See Section 3.1. 1 o Diagnostic differences The Version 6.1 compiler does more error checking than Version 5.7 and generates more diagnostics. If you want the number of diagnostics issued by Version 6.1 to be similar to Version 5.7, compile with the -msg_quiet option. See Sections 3.2 and 3.11.1. o Run-time library differences The C++ run-time library (libcxx) ships with Compaq's DIGITAL UNIX. The Version 6.1 compiler requires a newer version of libcxx than is provided with Compaq's DIGITAL UNIX Versions prior to Version 4.0D. To support development on earlier versions, a special version of libcxx is provided with the DIGITAL C++ kit, and the compiler links with this version by default. However, if you want to run programs linked in this manner on older operating systems, special actions are required. See Section 3.11.4. o Implementation differences The automatic template instantiation model has been redesigned for the current version. While code compiled with Version 5.n and 6.n compilers can be combined, you must complete the Version V5.n instantiation process with a V5.n compiler (or using -oldcxx) before linking with code compiled with Version 6.n. See the discussion of templates in Using DIGITAL C++ for Compaq's DIGITAL UNIX. If Version 6.n requires excessive changes to your applications even when you use the -std arm option, or if you encounter problems using the Version 6.1 compiler, you can compile using the cxx -oldcxx command. See Section 3.10. 3 Enhancements and Changes in Version 6.0 This section briefly summarizes changes and enhancements made in Version 6.0. o Support for the Final Draft International Standard ANSI C++ Standard (FDIS) (with some differences, as described in Section 3.12), including the C++ Standard 2 Library. See Section 10 for information on and changes to the Standard Library. o Language mode and diagnostic message options to increase compatibility with earlier versions. See Sections 3.1 and 3.2. o Improved automatic instantiation of templates, including fewer restrictions. In particular, DIGITAL C++ no longer requires that template declarations and definitions appear in header files. o Build-time performance improvements, including a new -ttimesstamp option which further reduces build times for applications that use templates extensively. For complete information, refer to Using DIGITAL C++ for Compaq's DIGITAL UNIX. o Support for precompiled headers to decrease compilation times. For complete information, refer to Using DIGITAL C++ for Compaq's DIGITAL UNIX. o Behavior of the -gall option (see Section 8.1). Section 3.11 discusses compatibility issues that you might encounter in using Version V6.1-027 if you have used Version 5.n in the past. New command options, introduced Version 6.0, are described in the following sections. 3.1 Language Mode Options With Version 6.1, DIGITAL C++ supports most of the Final Draft International Draft ANSI C++ standard (FDIS). DIGITAL C++ releases prior to Version 6.1 implemented the ARM (The Annotated C++ Reference Manual, 1991, by Ellis and Stroustrup) with some ANSI C++ extensions. The FDIS ANSI C++ language standard differs in significant ways from the language implemented by DEC C+ Version 5.n. The default language mode for Version 6.1 is ANSI, and many programs developed using Version 5.n require modifications before they can be compiled in the default ANSI mode. Version 6.1 also supports an ARM language mode for greater compatibility with previous versions. Version 6.1 provides the following language mode options: 3 -std ansi Specify this option if you want an ANSI C++ compiler that supports some commonly used extensions and is somewhat less strict than the standard. This is the default compiler mode. If you want to use ANSI mode but find that the compiler generates too many diagnostics in that mode, you can use the -msg_quiet option with the -std ansi option. The -msg_quiet option relaxes error checking and suppresses or reduces the severity of many diagnostics. It also suppresses many warnings that are generated in ANSI mode but were not issued by Version 5.6. For information on message control options, see Section 3.2. -std arm Specify this option if you want to compile programs developed using DIGITAL C++ Version 5.n and want to minimize source changes. If you usually want your compilations done in this mode and don't want to specify -std arm on each cxx command, define environment variable DEC_CXX as follows: setenv DEC_CXX "-std arm" See Section 3.9 for more information on environment variable DEC_CXX. DIGITAL C++ Version 6.1 also provides support for other C++ dialects and language modes. You can specify the following options: -std ms Specify this option if you want the compiler to accept additional Microsoft Visual C++ extensions. -std cfront Specify this option if you want to compile programs developed using cfront or a compiler based on cfront. -std strict_ansi Specify this option if you want the compiler to enforce the ANSI C++ standard strictly but permit some ANSI violations that should be errors to be warnings. 4 -std strict_ansi_errors Specify this option if you want strict_ansi and also want errors to be issued for all ANSI violations. With either -std ms or -std cfront you may also want to specify -msg_quiet to reduce the number of diagnostic messages generated. 3.2 Message Control Options DIGITAL C++ V6.1 supports the following message control options. The options apply only to discretionary, warning and informational messages. The tag variable can be the keyword all, a tag obtained from -msg_display_tag, or a number obtained from -msg_display_number. The tag variable is preferred. -msg_inform tag,... Alter message(s) severity to informational. -msg_warn tag,... Alter message(s) severity to warning. -msg_error tag,... Alter message(s) severity to error -msg_enable tag,... Enable specific messages that would normally not be issued when using -msg_quiet. This option can also be used to enable messages disabled with -msg_disable. -msg_disable tag,... Disable message. This can be used for any "non-error" message. -msg_quiet Be more like DIGITAL C++ Version 5.n error reporting. Fewer messages are issued using this option. This is the default in arm mode (-std arm). All other modes default to -nomsg_quiet. You can use the msg_enable option with this option to enable specific messages normally disabled using -msg_quiet. 5 3.3 Message Information Options DIGITAL C++ Version 6.1 supports the following message information options. Both are off by default. ________________________Note ________________________ "D" (meaning discretionary) indicates that the severity of the message can be controlled from the command line. The message number can be used as the tag in the above message control options. If "D" is not displayed with the message number, any attempt to control the message is ignored. _____________________________________________________ -msg_display_tag A more descriptive tag is issued at the end of each message issued. "D" indicates the severity of the message can be controlled from the command line. The tag displayed can be used as the tag in the above message control options. Example: cxx -msg_display_tag t.cxx cxx: ... is nonstandard ("int" assumed) (D:nonstd_implicit_int) cxx -msg_disable nonstd_implicit_int t.cxx Note that you can change the severity of a diagnostic message if the message is discretionary. For example, - msg_inform nonstd_implicit_int changes the severity this to an informational. These options interact with -w0, -w1, and -w2. -msg_display_number The error number is displayed at the beginning of each message issued. Example: cxx -msg_display_number t.cxx cxx: Warning: t.cxx, line 1: #117-D non-void function "f" ... cxx -msg_disable 117 t.cxx 6 3.4 Standard Library Options The following are new Standard Library options. For detailed information about the DIGITAL C++ Standard Library, see Using DIGITAL C++ for Compaq's DIGITAL UNIX. -[no]using_std Controls whether standard library header files are processed as though the compiled code were written as follows: using namespace std; #include
These options are provided for compatibility for users who do not want to qualify use of each standard library name with std:: or put using namespace std; at the top of their sources. -using_std turns implicit using namespace std on; this is the default when compiling -std arm, -std cfront, -std ms, or -std ansi. -nousing_std turns implicit using namespace std off; this is the default when compiling -std strict_ansi or -std strict_ansi_errors. -[no]stdnew Controls whether calls are generated to the ANSI or pre- ANSI implementation of the operator new(). On memory allocation failure, the ANSI implementation throws std::bad_alloc, while the pre-ANSI implementation returns 0. -stdnew generates calls to the ANSI new() implementation; this is the default when compiling -std ansi, -std strict_ ansi and -std strict_ansi_errors. -nostdnew generates calls to the pre-ANSI new() implemen- tation; this is the default when compiling -std arm, -std cfront and -std ms. -[no]global_array_new Controls whether calls to global array new and delete are generated as specified by ANSI. Pre-ANSI global array new 7 generated calls to operator new(). According to ANSI, use of global array new generate calls to operator new()[]. -global_array_new generates calls to operator new()[] for global array new expressions such as new int[4]; this is the default when compiling -std ansi, -std strict_ansi, -std strict_ansi_errors, and -std ms. -noglobal_array_new generates calls to operator new() for global array new expressions such as new int[4] and preserves compatibility with Version 5.n; this is the default when compiling -std arm and -std cfront. 3.5 Precompiled Header Options You can specify the following options for precompiled headers. For detailed information about precompiled headers, see Using DIGITAL C++ for Compaq's DIGITAL UNIX. -pch Automatically use and/or create a precompiled header file. If -use_pch or -create_pch (manual PCH mode) appears on the command line following this option, the last option is used. -create_pch file-name If other conditions are satisfied, create a precompiled header file with the specified name. If -pch (automatic PCH mode) or -use_pch appears on the command line following this option, the last option is used. -use_pch file-name Use a precompiled header file of the specified name as part of the current compilation. If -pch (automatic PCH mode) or -create_pch appears on the command line following this option, the last option is used. -pch_dir directory-name The directory in which to search for and/or create a precompiled header file. This option may be used with automatic PCH mode (-pch) or manual PCH mode (-create_pch or -use_pch). 8 -[no]pch_messages Enable or disable the display of a message indicating that a precompiled header file was created or used in the current compilation. The default is -pch_messages. 3.6 Template Options Version 6.1 provides the following new options for templates. For detailed information about using templates, see Using DIGITAL C++ for Compaq's DIGITAL UNIX. -implicit_include Enable inclusion of source files as a method of finding definitions of template entities. By default it is enabled for normal compilation, and disabled for preprocessing only, -E and -P. The search rules for finding template definition files is the same as for include files. -no_implicit_include Disables inclusion of source files as a method of finding definitions of template entities. You may want to use this option in conjunction with -ms and -std ms command line options, in order to more closely match the behavior on Microsoft C++. 3.7 Language Feature Options The Version 6.1 compiler emits type information for run- time type identification (RTTI) in the object module with the virtual function table, for classes that have virtual function tables. You can specify the following options: -[no]rtti Enable or disable support for RTTI (runtime type identification) features: dynamic_cast and typeid. Disabling runtime type identification can also save space in your object file because static information to describe polymorphic C++ types is not generated. The default is to enable runtime type information features and generate static information in the object file. Note that specifying -no_rtti does not disable exception handling. 9 The type information for the class may include references to the type information for each base class and informa- tion on how to convert to each. The typeinfo references are mangled in the form __T__. 3.8 Performance Optimization Options Version 6.1 provides the following performance optimiza- tion options: -[no]ansi_alias Specifies whether the compiler assumes the ANSI C aliasing rules to generate better optimized code. With the current version, if a program does not access the same data through pointers of a different type (and for this purpose, signed and qualified versions of an otherwise same type are considered to be the same type), then assuming ANSI C aliasing rules allows the compiler to generate better optimized code. If a program does access the same data through pointers of a different type (for example, by a "pointer to int" and a "pointer to float"), you must not allow the compiler to assume ANSI C aliasing rules, because these rules can result in the generation of incorrect code. Per the C++ language rules, the default is -ansi_alias. -assume [no]pointers_to_globals Controls whether the compiler can safely assume that global variables have not had their addresses taken in code that is not visible to the current compilation. The default is -assume pointers_to_globals, which directs the compiler to assume that global variables have had their addresses taken in separately compiled modules and that, in general, any pointer dereference could be accessing the same memory as any global variable. This is often a significant barrier to optimization. While the -ansi_alias option allows some resolution based on data type, -assume pointers_to_globals provides signif- icant additional resolution and improved optimization in many cases. 10 The -assume pointers_to_globals option tells the compiler that any global variable accessed through a pointer in the compilation must have had its address taken within that compilation. The compiler can see any code that takes the address of an extern variable. If it does not see the address of the variable being taken, the compiler can assume that no pointer points to the variable. Note that -assume pointers_to_globals does not tell the compiler that the compilation never uses pointers to access global variables. -assume [no]whole_program Tells the compiler that except for "well-behaved library routines", the whole program consists only of the single object module being produced by this compilation. The optimizations enabled by -assume whole_program include all those enabled by -assume nopointer_to_globals and possibly other optimizations. The default is -assume nowhole_program. 3.9 Changing the Default Compiler Options You can define the DEC_CXX environment variable to change the "default" behavior of the cxx command. For example, to make ARM language mode the default using csh shell, define DEC_CXX as follows: setenv DEC_CXX "-std arm" You can place a single vertical bar ("|") within the variable. All arguments preceding the bar are evaluated before any explicit command-line arguments; all arguments following the bar are evaluated afterwards. In the absence of a vertical bar, all arguments are evaluated before the explicit command-line arguments. If -v is specified, the definition of environment variable is reported. For example, assuming the definition of DEC_ CXX above, the cxx -v command results in the following: % cxx -v $DEC_CXX contains: -std arm 11 3.10 Compiler Version Options This release provides the following compiler version options: -newcxx Invokes the Version 6.1 compiler. This is the default. -oldcxx Invokes a bug fix update to the Version 5.7 compiler. The -oldcxx option is provided for cases where the Version 6.1 compiler requires excessive source changes or for problems in using the Version 6.1 compiler. If extensive source changes are required to correct errors, try using the -std arm option (see Section 3.1). For excessive warnings, try the -msg_quiet option (see Section 3.2). If you want -oldcxx to be the default, define the DEC_CXX environment variable as follows: setenv DEC_CXX "-oldcxx" See Section 3.9. Note that the optional -oldcxx subset must be installed before you can use the -oldcxx option. See the DIGITAL C++ Installation Guide for Compaq's DIGITAL UNIX . 3.11 Compatibility With Previous Versions This section provides details about differences between the current and previous compiler versions: o Language differences o Implementation differences o Library differences o Run-time library differences 12 3.11.1 Language Differences Users should be aware of the following language differ- ences between the current and previous versions of the compiler: o The most important language differences result from the implementation of the Final International Draft ANSI C++ Standard (FDIS) in Version 6.1. If you want to compile existing source code with minimal source changes, compile using the -std arm option. See Section 3.1. o Because the current compiler performs more error checking than previous versions, it generates significantly more diagnostic messages. However, you can use the -msg_quiet option to relax error checking and reduce the severity of many diagnostics. See Section 3.2. With some option combinations, you might see unwanted diagnostics from system header files. If so, you might obtain better results if you protect your system header files using the script provided in /usr/lib/cmplrs/cxx/protect_system_headers.sh. For more information, see the discussion on Protecting System Header Files in Using DIGITAL C++ for Compaq's DIGITAL UNIX. o The current compiler fixes several class member access bugs in previous versions. Some illegal programs that compiled cleanly with previous versions require modification to compile with the current version. o The following keywords, introduced with the FDIS, are always keywords in all compiler modes: bool, const_cast, explicit, export, false, mutable, dynamic_cast, reinterpret_cast, static_cast, truce, typeid, typename, wchar_t Alternative representation keywords are as follows: and, and_eq, bitand, bitor, compl, not, not_eq, or, or_eq, xor, xor_eq o Creation of temporaries and their lifetimes vary among compiler modes. o Taking the address of a bit field is not allowed in the current version. 13 o Macro expansion in pragmas can give different results in the current and previous versions. o The following are distinct types in the current version; they were the same type in previous versions: typedef void (*PF)(); // Pointer to an extern "C++" function extern "C" typedef void (*PCF)(); // Pointer to an extern "C" function void f(PF); void f(PCF); o The current version does not allow converting a pointer to member from a derived class to a virtual base class. o Calling a nonstatic member function through a null pointer is undefined behavior. Certain cases that used to run without errors in previous versions no longer run in the current version. For example: #include struct A { int a; }; struct D : public virtual A { A* toA(){ return (A*) this; } }; main () { D* d = NULL; A* ad = d->toA(); if (ad==NULL) cout << "ok"; // will seg fault } o In the current version, bool is a built in type. In previous versions, it is user defined, typically as int in system header files. Mangling therefore differs between the current and previous versions. In the current version, the size of bool is 1. In previous versions, bool is user defined, typically as int with a size of 4. 14 In the current version, the size of a boolean expression ( sizeof(a && b) ) is 1. In previous versions, the size is 4, independent of the size of bool. o The current version does not cause pragmas to become effective within function bodies when scanning template definitions. o The current version does not permit dropping qualifiers on pointer assignments. For example, the following is not permitted: volatile int *vptr; int *ptr=vptr; o The current version does not allow the "virtual" storage class modifier to be used with member function definitions outside a class. o The current version does not allow typedef void Z::* any_ptom;. 3.11.2 Implementation Differences Users should be aware of the following implementation differences between the current and previous versions of the compiler: o The automatic template instantiation model has been redesigned for the current version. See Using DIGITAL C++ for Compaq's DIGITAL UNIX for details. o The current version does not support the following features implemented in Version 5.7: -show expansion -show statistics o The current version drops qualifiers on parameters when determining the function type, as dictated by the Final Draft International Standard. For instance, in the following example, the function declarations are the same function. f(const int p1); f(int p1); For compatibility with previous versions, if qualifiers are included in function declarations, they are also included in the mangled name. 15 o The current and previous versions differ in inter- preting undefined behavior, as when incrementing takes effect in this example: f(i++, i++); o The current version cannot handle a #pragma define_ template that spans multiple lines without the backslash ( \ ) delimiter. Version 5.6 can handle this without problems. o The current version displays #line number in -E output. The previous version displays #number. o After encountering an illegal multibyte character sequence, the current version issues a warning diagnostic and continues processing. The previous version issues an error and stops processing. 3.11.3 Library Differences Aspects of memory allocation and deallocation have changed. See -[no]stdnew and -[no]global_array_new in Section 3.4 for more information. 3.11.4 Run-Time Library Differences Code generated by the Version 6.1 compiler requires a newer version of the C++ run-time library (libcxx than is provided by DIGITAL UNIX Versions prior to 4.0D. Using DIGITAL C++ on DIGITAL UNIX Version 4.0D or Later On DIGITAL UNIX Version 4.0D or later, the version of libcxx.so required for use with DIGITAL C++ Version 6.1 is installed by the operating system; no special actions are required. Using DIGITAL C++ on DIGITAL UNIX Version 4.0C or Earlier to Link and Run Programs On versions prior to 4.0D, you must install the following subset from the DIGITAL C++ Version 6.1 kit before you can link or execute programs: DIGITAL C++ Run-Time Library (libcxx) for DIGITAL UNIX V4.0C and earlier 16 If you attempt to link code generated by DIGITAL C++ Version 6.1 before installing this subset, the link might fail because of unresolved symbols. For example, if you have not installed the libcxx subset and you attempt to link code using C++ exception handling, the link will fail as follows: % cxx -o etest.out etest.cxx ld: Unresolved: __cxx_exception_caught __cxx_handler_exit(need, new, libcxxso) __cxx_v60_dispatch(need, new, libcxxso) This subset also must be installed on any system on which you want to execute code generated by DIGITAL C++ Version 6.1. If you attempt to execute a program before installing this subset, the execution will fail because of unresolved symbols; for example: % etest.out etest.out: /sbin/loader: Error: unresolvable symbol in etest.out: __cxx_exception_caught etest.out: /sbin/loader: Error: unresolvable symbol in etest.out: __cxx_handler_exit__X4need3new8libcxxso etest.out: /sbin/loader: Error: unresolvable symbol in etest.out: __cxx_v60_dispatch__X4need3new8libcxxso etest.out: /sbin/loader: Fatal Error: this executable has unresolvable symbols For both cases, different unresolved symbols may appear depending on the particular language features used. Note that you can install the libcxx subset without installing the base compiler subset. Redistributing libcxx.so If you distribute your software for use on pre-Version 4.0D systems on which DIGITAL C++ Version 6.1 might not be installed, you can redistribute libcxx.so under the conditions stated in the Software Product Description. The recommended mechanism for redis- tributing libcxx.so is for you to provide the .tar file /usr/lib/cmplrs/cxx/CXXREDIST601V01.tar. This tar file contains a setld kit that installs /usr/lib/cmplrs/cxx/libcxx.so. 17 You should also provide the following instructions for installing libcxx.so from the tar file: 1. Check which CXX subsets are installed: setld -i | grep CXX | grep installed If either subset CXXLIB601 or CXXREDIST601 is in- stalled, there is no need to install from CXXREDIST601V01.tar. 2. Untar the file by entering the command tar xvf CXXREDIST601V01.tar. This creates a setld kit for installing libcxx.so in directory CXXREDIST601.kit. 3. Log in as superuser. 4. Install by typing the following and selecting the subset displayed: /usr/sbin/setld -l CXXREDIST601.kit Implementation Notes For DIGITAL UNIX Version 4.0D and later, /usr/shlib/libcxx.so (installed by the operating system) contains the support needed for DIGITAL C++ Version 6.1. For DIGITAL UNIX versions prior to V4.0D, the libcxx sub- set and the restribution subset both install /usr/lib/cmplrs/cxx/libcxx.so to avoid overwriting the version of libcxx.so installed by the operating system (/usr/shlib/libcxx.so). When linking, the compiler passes -rpath /usr/lib/cmplrs/cxx -L/usr/lib/cmplrs/cxx to ld. This causes ld to search /usr/lib/cmplrs/cxx before searching the system libraries, and the loader to search for libraries in that directory when loading code for execution. If you specify - rpath explicity, you need to make sure to specify /usr/lib/cmplrs/cxx in the path string in addition to any other directories that you want searched. 18 3.12 Language Differences Between the Final Draft International Standard and DIGITAL C++ The following items, specified in the Final Draft International Standard (FDIS), are not supported in Version V6.1-027 but will be supported in a future version: o Enums larger than can be contained in an int o reinterpret_cast casting a pointer to member of one class to a pointer to member of another class if the classes are unrelated o Name binding in templates in the style of N0288/93-0081 o Evaluation of f in a reference of the form f()->g(), with g as a static member o Class name injection o Putting a try/catch around the initializers and body of a constructor o Templates as template parameters, as shown in the following example: template class C> class Xrefd { // not yet allowed C mems; C refs; }; o Koenig lookup of function names on all calls (see Sections 8.2.6 and 11.2.4 of The C++ Programming Language, 3rd Edition) o Finding friend functions of the argument class types on name lookup on the function name in calls o String literals do not have a const type o Universal character set escapes (for example, uabcd) o The export keyword for templates o All the resolutions passed at the ANSI/ISO meeting in January 1998 in Morristown, NJ are not implemented yet. Most of these were relatively minor changes. 19 4 Compiler Problems Fixed in Version V6.1-027 This section briefly summarizes compiler changes, enhancements, and the most important problems fixed in Version V6.1-027. o The Version 6.0 compiler incorrectly mangled the name of a class virtual function table when that class was nested within another class or namespace. If object modules compiled with Version 5.n and Version 6.0 were linked together, the compiler might display the following message: ld: Unresolved: std::__vtbl_3std9type_info This problem has been fixed. Any code generated with Version 6.0 that demonstrates this problem should be recompiled with the current compiler. [5144] o The compiler used to mark all member functions of the class that had not already been specialized as needing to be instantiated when processing a #pragma define_template class . But the compiler did not instantiate the functions until processing the end of the scope. If a specialization occurred after the #pragma but before the compiler tried to instantiate it, the compiler found that the member function had already been specialized and reported the following error: "function" cannot be instantiated -- it has been explicitly specialized This error is reduced to a warning and is issued only once per instantiation. The warning can be suppressed by using the command-line switch -msg_disable 490. See the discussion of Message Control Options in Section 3.2. [43-4-137] o The compiler no longer generates incorrect code when dereferencing an element of an array of pointers. [5236] 20 o A problem creating shareable libraries has been fixed by allocating static local const variables initialized with pointers to .rdata instead of to .rconst. [43-4- 166] o To facilitate setting default compiler flags, you can now create an optional configuration file named comp.config or an environment variable named DEC_CXX. - The comp.config file allows system administrators to establish a set of compilation flags that are applied to compilations on a system-wide basis. The compiler flags in comp.config must be specified on a single line, and the comp.config file should be stored in the compiler target directory, /usr/lib/cmplrs/cxx. - The DEC_CXX environment variable allows users to establish a set of compilation flags that are applied to subsequent compilation on a per user basis. The DEC_CXX environment variable can contain two distinct sets of compilation flags separated by a single vertical bar ( | ). The flags before the vertical bar are known as prologue flags and the flags after the bar are know as epilogue flags. The DEC_CXX environment variable can begin or end with a vertical bar, or have no vertical bar at all. If no vertical bar is present, the flags are treated as prologue flags by default. Any vertical bar found after the first vertical bar is treated as whitespace and a warning is issued. Compiler flags are processed in the following order during a compilation: 1. comp.config flags 2. DEC_CXX prologue flags 3. command line flags 4. DEC_CXX epilogue flags If -v is specified on the command line, the contents of DEC_CXX and comp.config, if present, are displayed. [4488] 21 o By default, C files are compiled with -std. Users can now override the default by specifying -std0/-std1. [4392] o The compiler no longer mishandles "?" operations on a boolean type in constructs like the following: bool f(int i) { return (i<5 ? false : true ); } [43-4-135] o Parallel compiles now work correctly because the com- piler no longer deletes an empty template repository. [5544] o The current version does not support the following features implemented in Version 5.7: -show expansion -show statistics The following are now supported: -nocpp -xref -xref_stdout listing of predefined macros #pragma message 5 Library Problems Fixed in Version V6.1-027 This section describes library problems fixed in Version V6.1-027. o STL map containers are now accessible in multithreaded environments Erasing elements from two STL map containers in a multithreaded environment no longer causes a segmentation fault. With previous versions, the problem was caused by an incorrect locking mechanism in an implementation class used when a map is being "erased". 22 To correct the original problem reported against the STL map class, we reworked map's entire underlying implementation class. The underlying implementation class is found in the header. This class has been modified so that it no longer contains static data members. o Standard Library IOStream cerr.flush() no longer hangs in multithreaded environments Applications making use of the Standard Library IOStream cerr.flush() function in combination with other I/O related activities in a multithreaded environment no longer experience hangs in their executing code. o Piping Standard Output or Standard Error to a file no longer loses output when using Standard Library IOStreams The symptoms of this Standard Library bug varied. One noticeable effect could be seen when executing a program using Standard Library IOStreams which inserted items to cout and then piped this output along with other output to a file. For example, if a program inserted into cout as follows: #define __USE_STD_IOSTREAM #include void main() { cout << "Hello from C++" << endl; } And if a script, d.sh executed the above program and made use of a command that output to Standard Error like this: a.out ls -X And if you piped both Standard Output and Standard Error to a file like this: d.sh >& testlog 23 The output to Standard Output was lost. The testlog would contain: + ls -X ls: illegal option -- X usage: ls [ -1ACFLRabcdfgilmnopqrstux ] [files] Rather than: Hello from C++ + ls -X ls: illegal option -- X usage: ls [ -1ACFLRabcdfgilmnopqrstux ] [files] This problem has been corrected. 6 General Version 6.1 Restrictions The following general restrictions apply for Version 6.1: o Version 6.1 is not totally compatible with previous versions, and source changes might be required to use this version. See Sections 3.1 and 3.2. o Some features implemented in Version 5.7 are not supported by Version 6.1. See Section 3.11.2. o The UNIX utility nm does not always work on DUNIX V4.n systems with object files generated by DIGITAL C++ Version 6.1. The symptom is a seg fault when nm attempts to dump its list. An alternative to nm might be the odump utility. For example, the command odump -tv foo.o lists all the symbols in the archive. See the odump reference page for more details on the odump utility. Another possible workaround is to compile your object file with -g (debugging), then recompile it without -g. That procedure might avoid triggering the nm bug. If you want to obtain a version of nm that fixes this problem, these are the patch kit identifiers: 24 _______________________________________________________ OPERATING_SYSTEM_VERSION__PATCH_ID_____________________ v40 OSF400-438 v40a OSF405-438 v40b OSF410-438 v40c OSF415-438 v40d______________________OSF420-42____________________ o If you use a non-default pointer size or member alignment and header files are not protected, the following warning is issued: < cxx: Warning: A non-default pointer size or member alignment is specified and the system header files are not protected. This may yield unpredictable results. The protect_headers_setup script can help. See the protect_headers_setup(8) man page for details. The protect_headers_setup(8) reference page page is planned for a future release of DIGITAL UNIX. For now, see the discussion about Protecting System Header Files in Using DIGITAL C++ for Compaq's DIGITAL UNIX. o The Final Draft International ANSI C++ Standard (FDIS) permits overriding a virtual member function based only on a derived class return type. The current release does not support this capability. o Debugging programs that use namespaces For this version of DIGITAL C++, namespaces are presented as classes of the same name to the debugger. This affects Ladebug in the following ways: - 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. - Ladebug does not support the using declaration; you must fully qualify names in a namespace. For example: namespace_name::name - Namespace definitions can be different between different files. 25 You might 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 o Ladebug support for Version 6.1-specific features, such as run-time type identification (RTTI), has not yet been added. o Restricted address space size for precompiled headers in some versions of DIGITAL C++. Some versions of DIGITAL C++ might restrict the size of the address space available for use by precompiled headers. If the compiler terminates with a message about mapped memory, this may be the problem. To increase the address space available for precompiled headers you need to increase the mapentries limit. 26 Follow these steps to change the mapentries limit: 1. Become the root user. 2. Create a new file named /tmp/xxx and insert the following lines: vm: vm-mapentries=5000 3. Execute the sysconfigdb command as follows: # /sbin/sysconfigdb -f /tmp/xxx -m vm 4. Reboot the system. This procedure increases the mapentries limit from the default 200 to 5000. Increasing the limit by that amount has no adverse effect on the system. o Files implicitly included are not listed as dependen- cies. o When using PCH, the line number associated with an inline function is the line at which the PCH stop is encountered. o Certain utilities, such as GNU Make, do not recognize compressed object files, which the compiler creates by default. If you encounter problems, you can specify the -nocompress command-line option. o Instantiating function templates with array types can result in different external name encoding than with C++ Version 5.n. To avoid link errors, recompile the template definition with the current version of the compiler. o Class and Standard Libraries generate Third degree messages. None of the following messages contribute to memory corruption in programs or cause memory depletion in long running applications. 1. Third degree 576 byte leak and 16 byte leak messages from __init_cxx_exc 27 When you instrument a DIGITAL C++ program with Third degree, the tool might generate 576 byte leak and 16 byte leak messages like the following from the Class Library routine __init_cxx_exe: 576 bytes in 1 leak created at: malloc libc.so pc = 0x3ff81d35c04 libcxx.so pc = 0x3ff81d35e20 libcxx.so __init_cxx_exc libcxx.so 16 bytes in 1 leak (including 1 super leak) created at: malloc libc.so pc = 0x3ff81d35c04 libcxx.so pc = 0x3ff81d35ca4 libcxx.so pc = 0x3ff81d35dfc libcxx.so __init_cxx_exc libcxx.so A program like the following would generate the previous messages: int main () {return 0;} These two leaks are generated by the C++ exception handling code. This storage is memory allocated to process exception handling during program startup and is deleted by the operating system when the program exits. Third degree reports a leak because the operating system, rather than C++ code, deletes the storage. The operating system deletes this storage for these reasons: o The compiler does not slow down exit for all C++ programs. o After the program terminates, the compiler verifies that no additional C++ exceptions need handling. 2. Third degree 8/24/48 byte leak messages from __init_cxx_exc When you instrument a DIGITAL C++ program with Third degree, the tool might generate four 8, four 24, and four 48 byte leak messages like the following from the Class Library routine __init_cxx_exe: 28 48 bytes in 1 leak created at: malloc libc.so __cma_tis_mutex_create libc.so AllocateInternalMutex(void) libcxx.so Mutex::Mutex(void) libcxx.so Iostream_init::initialize(void) libcxx.so Iostream_init::Iostream_init(void) libcxx.so __init_cxxl_init142DB80C libcxx.so 24 bytes in 1 leak created at: operator new(unsigned long) libcxx.so AllocateInternalMutex(void) libcxx.so Mutex::Mutex(void) libcxx.so Iostream_init::initialize(void) libcxx.so Iostream_init::Iostream_init(void) libcxx.so __init_cxxl_init142DB80C libcxx.so 8 bytes in 1 leak (including 1 super leak) created at: operator new(unsigned long) libcxx.so Iostream_init::initialize(void) libcxx.so Iostream_init::Iostream_init(void) libcxx.so __init_cxxl_init142DB80C libcxx.so A program like the following would generate the previous messages: int main () {return 0;} The messages originate from the creation of Class Library Iostream mutexes for cin, cout, clog, and cerr, which are created at program startup. The operating system cleans up the memory rather than deleting it at program exit from C++. 3. Additional Third degree 48/24 byte leak messages from __init_cxx_exc When you instrument a DIGITAL C++ program with Third degree, the tool might generate an additional 24 and 48 byte leak messages like the following from the Class Library routine __init_cxx_exe: 29 48 bytes in 1 leak created at: malloc libc.so __cma_tis_mutex_create libc.so AllocateInternalMutex(void) libcxx.so Mutex::Mutex(void) libcxx.so Iostream_init::Iostream_init(void) libcxx.so __init_cxxl_init142DB80C libcxx.so 24 bytes in 1 leak created at: operator new(unsigned long) libcxx.so AllocateInternalMutex(void) libcxx.so Mutex::Mutex(void) libcxx.so Iostream_init::Iostream_init(void) libcxx.so __init_cxxl_init142DB80C libcxx.so A program like the following would generate the previous messages: int main () {return 0;} The messages also come from a mutex used in Iostream locking; they are created at program startup and are cleaned up by the operating system rather than being deleting at program exit by C++. 4. Third degree 48 byte leak messages from __init_ cxxl_initxxxxxxxx When you instrument a DIGITAL C++ program with Third degree, the tool might generate an additional 48 byte leak message like the following from the Class Library routine __init_cxxl_initxxxxxxxx: 48 bytes in 1 leak (including 1 super leak) created at: malloc libc.so __cma_tis_mutex_create libc.so pc = 0x3ff81d3a46c libcxx.so __cma_tis_once libc.so __cxx_test_and_set_atomic libcxx.so __init_cxxl_init142DB80C libcxx.so A program like the following would generate the previous message: int main () {return 0;} 30 This message comes from the mutex used to initialize the Class Library; the mutex is created at program startup and is deleted by the operating system rather than by C++ code at program exit. 5. Third degree fon warning message from __init_cxx_ exe When you instrument a C++ program with Third degree, the tool might generate a fon warning like the following from the C++ Class Library routine __init_cxx_exe: ------------------------------------------------ fon -- 0 -- calling free(0) free fon pc = 0x120068090 fon __init_cxx_exc fon -------------------------------------------------------------- A program like the following would generate the previous message: int main () {return 0;} The message, freeing a NULL pointer, is only a warning. In this case, the library does in fact free a NULL pointer, but this is valid behavior. You can ignore the message. 6. Third degree wis error from __vec_new_eh When you instrument a C++ program with Third degree, the tool might generate a wis error like the following from the C++ Standard Library routine __vec_new_eh: 31 ------------------------------------------------ wis -- 1 -- wis.cxx: 5: writing invalid stack at byte 64 of 64 in frame of array_new_general (void*, int, unsigned long, void*, void (*)(void*, int), void* (*)(unsigned long), void (*)(void*), int, int, unsigned int) array_new_general(void*, int, unsigned long, void*, void (*)(void*, int), void* (*)(unsigned long), void (*)(void*), int, int, unsigned int) wis __vec_new_eh wis -------------------------------------------------------------- A program like the following would generate the previous message: struct C {C() {};}; int main () { C* pc = new C[5]; delete []pc; return 0; } Programs using global array new can generate the message when Third degree encounters a special scheduling instruction. This false positive message has been reported to Third degree. 7. Third degree rin error message The following error message is generated in programs that use exception handling in the Class Library. This false positive message has been reported to Third degree. rin.c: 7: reading invalid stack at byte 656 of 656 in frame of main proc_at_0x12000e350 rin __exc_virtual_unwind rin exc_virtual_unwind rin main rin, rin.c, line 7 __start rin 8. Third degree might report false positive uninitiated memory errors 32 As of Atom 2.47, Third degree might report false positive uninitiated memory errors where variables of less than 32 bits are involved. Note that bool data types, which the Standard Library uses extensively, fall into this category. For example, when you instrument a C++ program with Third degree, the tool might generate a rus error with Atom version 2.47 in the STL map class. The error would be generated by a program like the following: #include main() { map the_test_map; the_test_map[1] = 1; the_test_map[2] = 2; } The following is an example of a small, self- contained program (reduced from the above program) that generates the same error. struct tree { bool b; void init () {;} tree(const int i = 3, bool b = true) : b(b) { init(); } }; void main() { tree t; } o The -tall (or -define_templates) option is not guaranteed to work with the Standard Library. Specify -tused instead. When compiled with -define_templates or -tall, the following generates compilation errors indicating that no operator "<" (and ">" or "+" or "-") matches these operands. 33 #include map foo; These template instantiaton options are not guaranteed to work with the Standard Library because they request the compiler to instantiate all templates, even those that are not used. The -tall option does not work because rb_tree, the underlying implementation of map and set supports a bidirectional iterator class. Thus, operator+, operator-, operator< and operator> are not defined in the iterator for that class. When you instantiate the tree with cxx -tall or cxx -define_templates, the compiler attempts to instantiate recursively everything that is typedefed, even if not used. Thus, the tree contains a typedef for std::reverse_iterator, which then instantiates the global class reverse_iterator with the tree iterator as the template argument RandomAccessIterator, a misnomer in this case. This behavior generates undefined symbols for these operators because they are used within the definition of the operator member functions inside reverse_iterator. The compiler therefore attempts to instantiate them even though they do not exist. Specifying -tused for the Standard Library directs the compiler to only instantiate those templates that are used. o Description of the initial state of the stringstream Ctor There has been some controversy in the comp.lang.c++ reflector and within the standards committee on the semantics of the stringstream constructor. Consider the following example: #define __USE_STD_IOSTREAM #include 34 void main() { ostringstream ost("Hello, "); // ost.rdbuf()->pubseekoff(0,ios::end,ios::out); ost << "world!"; cout << ost.str() << endl; } Depending on the setting of the streambuf put pointer after the initial construction, the program could print either "Hello, world!" or "world!". The Rogue Wave (and DIGITAL C++) interpretation is that the stringstream constructor does not change the initial position of the streambuf pointer, so that the program prints "world!". If you want to change the setting of the put pointer to match the other interpretation (that the pointer should move to the end of the initializer string), you must insert a call to pubseekoff(), as shown in the commented line. If the ANSI C++ committee issues a clarification on this matter DIGITAL C++ will implement their decision. 7 Improving Build Performance This section contains suggestions for improving build performance when using DIGITAL C++ on your system. 7.1 Object File Compression By default, DIGITAL C++ compresses object files. This reduces object file size and can result in shortened link times, depending on characteristics of the system and the application. For some large applications, object file compression can significantly slow down the compiler and the linker and can significantly increase the amount of virtual memory required when linking. For some large applications, it is advantageous to compile without object file compression. To do so, specify the -nocompress option on the cxx command. 35 7.2 Using 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 Using DIGITAL C++ for Compaq's DIGITAL UNIX for details. 7.3 Using Precompiled Headers Using precompiled headers can reduce compilation time in environments where o Many primary sources include the same set of headers in the same order. o These headers introduce many lines of code. See Using DIGITAL C++ for Compaq's DIGITAL UNIX for details. 8 Reducing Object File Size During Debugging With DIGITAL C++ Version 5.6 and higher, 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 8.1 for information on how to use the -gall option. Before 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, DIGITAL 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: 36 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. 8.1 Using the -gall and -gall_pattern Options 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 using the -gall_pattern option so that a file is compiled with complete debugging only if the file name matches the pattern. Specifying -gall_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_pattern on the command line o Define environment variable CXX_GALL_PATTERN as the pattern The -gall_pattern option accepts 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. If you specify -gall, -g is assumed. The -gall_pattern option is ignored unless -g, -g2, or -g3 is also specified. 37 Example: The following example shows how opaque_class is initially described 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-44 . . . 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 o Supply -gall_pattern (useful for a generic rule in a makefile): cxx -g -gall_pattern opaque_file.cxx -O0 opaque_file.cxx In a makefile, this may look something like the following: CXX = cxx CXXFLAGS = -g -gall_pattern opaque_file.cxx -O0 $(CXX) $(CXXFLAGS) opaque_file.cxx 38 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_pattern option: o Compile both opaque_file.cxx and another_file.cxx with -gall_pattern: cxx -g -gall_pattern opaque_file.cxx,another_file.cxx -O0 opaque_file.cxx o Compile any file starting with opaque or another with -gall_pattern: setenv CXX_GALL_PATTERN "opaque*.cxx:another*.cxx" cxx -g -O0 opaque_file.cxx 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 Use the -gall option only 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. 9 Release Notes for the DIGITAL C++ Class Library This section describes the problems fixed, known problems, and restrictions for the DIGITAL C++ Class Library. See Section 10 for information on the C++ Standard Library. Please note that String Package, which is part of the DIGITAL C++ Class Library, is entirely different from the String class that is part of the newly-implemented C++ 39 Standard Library and known as the String Library. Do not confuse these two contrasting implementations. 9.1 Restrictions The following restrictions apply for Version 6.1: o Conflict with redefinition of clear() If your program includes both and , DIGITAL C++ might 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 DIGITAL C++ Version V6.1-027, your application may encounter runtime errors such as segmentation faults. To avoid these problems, recompile your application specifying the DIGITAL 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. For example, consider a program that makes use of the iostream clog object: 40 #include void main() { clog << "abc"; } If you link with the math library first as: cxx clog.cxx -lm -lcxx Executing the program results in a segmentation fault. DIGITAL C++ on DIGITAL C++ links against shared object libraries by default. Identical symbols in subsequent object libraries are resolved to the first definition by the symbol preemption feature. So in this case use of clog from iostreams is resolved to the definition in libm. If you link -non_shared with the math library first as: cxx clog.cxx -non_shared -lm -lcxx The linker gives a multiply defined message similar to the following: ld: /usr/lib/cmplrs/cxx/libcxx.a(iostream_globals.o): clog: multiply defined In this case, if you link with the Class library first, the program executes correctly. As described earlier, DIGITAL C++ on DIGITAL C++ links against shared object libraries by default. Identical symbols in subsequent object libraries are resolved to the first definition by the symbol preemption feature. So in this case use of clog from iostreams is resolved to the definition in libcxx: cxx clog.cxx -lcxx -lm Therefore, applications that reference either of the clog symbols should not include both -lcxx and -lm on their ld command line. o Displacing global operator new in C++ Standard Library/Class Library 41 If a C++ program defines a global operator new() which is intended to displace the version used by the C++ Standard Library, it must be compiled with the compiler command line switch -stdnew. If a C++ program defines a global operator new() which is intended to displace the version used by the C++ Class Library, it must be compiled with the compiler command line switch -nostdnew. o No support for 128-bit long doubles The Class Library does not include support for 128-bit long doubles. 10 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 9 for information on the DIGITAL C++ Class Library. Please note that the current version of DIGITAL 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 DIGITAL C++ Class Library implemented in earlier versions of DIGITAL C++. Note that portions of the ANSI C++ Standard Library have been implemented in DIGITAL 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 DIGITAL C++ documentation with permission of Rogue Wave Software, Inc. All rights reserved. Portions copyright 1994-1998 Rogue Wave Software, Inc. 10.1 Enhancements and Changes in Version V6.1-027 The C++ Standard Library provided with this release defines a complete specification (with some differences) of the Final Draft International ANSI C++ Standard (FDIS). The library includes the ANSI locale and iostream libraries. Reference pages describing the standard library are provided; you can type man cxxlib_intro to access them. 42 Tutorial programs illustrating functionality found in the standard C++ library including the locale, iostream, and STL classes shipped with this release can be found in: /usr/examples/cxx/*.cxx You can compile and run these programs and use them as models for your own coding. The expected output for each program can be found in: /usr/examples/cxx/*.res Version 6.1 introduces the following major enhancements and changes. For detailed information, on the DIGITAL C++ Standard Library, refer to Using DIGITAL C++ for Compaq's DIGITAL UNIX. o Support for standard iostream and locale The Version 6.1 kit contains detailed documentation in PostScript and PDF formats: /usr/share/doclib/cplusplus/intzln.ps /usr/share/doclib/cplusplus/intzln.pdf /usr/share/doclib/cplusplus/locale.ps /usr/share/doclib/cplusplus/locale.pdf o Reference pages for the standard library. You can access the pages by typing man cxxlib_intro. o Several new options (see Section 3.4). o pre-ANSI/ANSI iostreams compatibility. o Support for ANSI/pre-ANSI operator new(). o Support for global array new and delete. Additional changes include the following: o Support for long long and unsigned long long types. The non-ANSI standard types long long and unsigned long long are now supported in the standard library iostreams as well as being valid types for numeric_ limits specializations and as types for which destroy() specializations are provided. For example, you can now say: 43 long long l; cout << l << endl; // compiles without error Note that these types are not supported under -std strict_ansi or -std strict_ansi_errors compiler mode. long long and unsigned long long are also supported in the iostream class library in the default compiler mode. o Common Instantiation Libraries No Longer Needed Because Version 6.1 uses compile time rather than link time template instantiation, there is no use for common instantiation libraries and we have therefore not supplied any build_common_instantiation_library script. See the discussion of templates in Using DIGITAL C++ for Compaq's DIGITAL UNIX. o Interface Change for STL distance() function Because the Version 6.1 compiler now supports partial specialization of class templates, the interface to the distance() algorithm has been updated to conform to the latest C++ standard. This means that previously, if you made a call to distance, the result was returned by using a reference argument for the third argument: distance(first,last,d); // pre 6.1 the result was returned in d Beginning with V6.1, the result is returned in the return type: d = distance(first,last); // 6.1 You must therefore change all your calls to distance(). o Specific Changes to match the November 1997 C++ Final Draft International Standard: o iterator_traits::distance_type now iterator_ traits::difference_type The name of the typedef inside the classes iterator_ traits and iterator that specifies the type of the result when two iterators are subtracted has been changed from distance_type to difference_type. o typedef name changes in iterator classes 44 The names of some of the typedefs in the reverse_ iterator and reverse_bidirectional_iterator classes have changed as follows: iter_type is now iterator_type reference_type is now reference pointer_type is now pointer distance_type is now difference_type o slice/gslice classes member function length() name change The member function length() in the slice and gslice classes has changed its name to size(). o has_denorm data member of the numeric_limits class changed The has_denorm data member of the numeric_ limits class, , has been updated. has_ denorm is changed from type bool to an enum type, float_denorm_style, to reflect that support for denormalized values might not be detectable at compile time. The float_denorm_style type looks like this: namespace std { enum float_denorm_style { denorm_indeterminate = -1; denorm_absent = 0; denorm_present = 1; }; } The values representing the presence or absence of denorms are as follows: denorm_indeterminate: cannot determine if type supports denormalized at compile time denorm_absent: the type does not support denormalized values denorm_present: the type supports denormalized values o Default allocator value for map and multimap has changed The default value for the template argument Allocator in map and multimap has changed from allocator to allocator >. o Some Standard Library ambiguities corrected 45 The Standard Library vector, deque and list containers no longer generate ambiguities when using their constructors or insert member functions. However, if you declare a basic_string of int, you might encounter ambiguities in the constructors, append, assign, insert, and replace member functions. For example if you write: #include int main() { basic_string si (5,0); return 0; } A compilation error results from the overload resolution between integral and iterator types. The constructors involved are: // construct n elements and initialize with value basic_string(size_type n, charT c, const Allocator& a = Allocator()); // construct a vector using iterator ranges template basic_string(InputIterator begin, InputIterator end, const Allocator& a = Allocator()); The compiler matches on the constructor basic_ string(InputIterator begin, InputIterator end, ...) The reason is that size_type a size_t is an unsigned long on DIGITAL C++. So you have: basic_string(unsigned long, int, ...) vs. basic_string(int, int,...) The second constructor is the better match, but it is not what we want, because we are not constructing with iterator ranges. The workaround is to avoid matching on iterator types by casting integral arguments. So for example, the previous program would compile correctly if the size argument were cast to a (size_t): 46 #include int main() { basic_string si ((size_t)5,0); return 0; } 10.2 Restrictions This section describes problems when using the current release of the C++ Standard Library with the DIGITAL C++ compiler. Where appropriate, workarounds are suggested. o Do Not Use Standard Library Template Definition File Names The standard library supplies the following template definition files in /usr/include/cxx: algorithm.cfstream.cc locale.cc streambuf.cvector.cc bitset.cc ios.cc locimpl.cc string.cc byname.cc istream.cc numbrw.cc tree.cc complex.cc iterator.ccostream.cc valarray.cc deque.cc list.cc sstream.cc valimp.cc If you use the same prefix name for any of your local files and have the directory that contains them in your include search path before /usr/include/cxx then the automatic instantiation mechanism will pick up your local copy and will not correctly find the library files. (See Using DIGITAL C++ for Compaq's DIGITAL UNIX for more information on how the prelinker finds template definition files.) We suggest that you not use any of these names as source file names for your application. o Redeclaration of Standard Library Functions Many of the prototypes in the standard library have been changed to conform to the ANSI draft standard by the addition of exception specifications. This means that if you have redeclared the declarations in your own code, you need to add the correct exception specification in order to match what's declared in the header. 47 For example: #include // override default operator new inline void* operator new(size_t s); // this will give an error To prevent this, you'd need to change your new() declaration to: inline void* operator new(size_t s) throw(bad_alloc); o Files/Macros for Internal Use Only DIGITAL C++ Version 6.1 ships the following non- Standard headers which are for internal use only. Their contents are subject to change and can not be relied on. In addition both Standard and non-Standard headers make use of macros beginning with _RW or __RW. These _RW* and __RW* macros are for internal use only. They are subject to change and can not be relied on. o Warning on Cast to CV_qualified Types When using STL container classes with DIGITAL C++ Version 6.1 the compiler might issue a warning the following: 48 cxx: Warning: /usr/include/cxx/utility, line 131: type qualifier is meaningless on cast type detected during: instantiation of "std::pair::pair() ... : first(T1()), second(T2()) --------^ The preceding was generated from the following: typedef multimap > mmap; typedef pair pair_type; pair_type p1 (3, 'c'); pair_type p2 (4, 'd'); ... pair_type array [] = {p1,p2,p3,p4,p5,p6}; mmap m (array, array + 6); The reason for this warning is that internally the container classes may make calls to Standard Library utilities like pair() which make use of functional- notation casts. For example pair() makes use of first(T1()). In this example T1() is a functional- notation cast to type T1. The type in a functional- notation cast has to be a single type identifier. Internally the library may add the const qualifier to a template type to ensure "constness". In the above example this has happened leading to an instantiation of first (const int()), which generates a warning. We plan to stop warning about casts to cv_qualified types when the types come from a template parameter in the future. In the meantime suppress such warning by compiling with: -msg_disable cast_to_qualified_type o Pre-ANSI iterators no longer available The following classes are no longer in the ANSI draft standard and should not be used: input_iterator output_iterator forward_iterator bidirectional_iterator random_access_iterator 49 The functionality of these classes is now provided by the single class iterator, which is templatized on the iterator category o Container Ambiguities The Standard Library shipped for this field test release contains ambiguities in the constructors, assignment operators, and insert functions for STL containers and strings. The problem, best illustrated by an example, results from overload resolution between integral and iterator types. Consider vector and two of its constructors (the second becomes visible in DIGITAL C++ Version 6.1 with compiler support for member template functions). // construct n elements and initialize with value explicit vector(size_type n, const T& value = T(), const Allocator&=Allocator()); // construct a vector using iterator ranges template vector (InputIterator first, InputIterator last, const Allocator&=Allocator()); To create a vector of five elements and initialize each to 0, you write the following: vector v2(5,0); With member function support we will match on the constructor vector(InputIterator first, InputIterator last, . . . ) The reason is that size_type a size_t is an unsigned long on DIGITAL C++. So you have the following: vector(unsigned long, int) vs. vector(int, int) These lines match on the second constructor. This is not what we want, we are not constructing by way of iterator ranges. These ambiguities show up in the assignment operators and insert member functions for deque<>, list<>, vector<>, vector as well as in the constructor for vector. (Note that this field test release corrected the problem for vector<>, deque<> and list<> 50 constructors). The ambiguity is also present for the insert map<>, multimap<>, set<>, and multiset<> member function and in the basic_string<> constructor, append, assign, insert and replace operators. The workaround for this field test release is to cast integral arguments to avoid matching on iterator types. For example, the following does not compile correctly for this field test release: #include using namespace std; int main () { vector v(5,0); //no ambiguity - corrected in library v.assign(5,3); //ambiguity not yet corrected return 0; } Casting the vector assign member function size argument to size_t provides a workaround. #include using namespace std; int main () { vector v(5,0); v.assign((size_t)5,3); //workaround with cast to size_t return 0; } o Restrictions on Printing Some Cases of bool/wchar_t Types with pre-ANSI Library Objects of a class which contain a user defined conversion operator to either bool or wchar_t can not be output directly with cout when including . For example, the following program will give compilation errors indicating that more than one operator "<<" matches these operands: 51 #include struct B { operator bool() { return true; } }; struct W { operator wchar_t() { return L'0'; } }; int main() { B b; cout << b << endl; // V6.1 ambiguity error W w; cout << w << endl; // V6.1 ambiguity error return 0; } If you try to output the subscript operator of vector directly with cout, you will encounter this problem in the library. The following will generate an ambiguity error: #include #include int main () { vector vb; cout << vb[1] << endl; // V6.1 ambiguity error return 0; } The workaround is to cast your class to either (bool) or (wchar_t) respectively. You would code the previous programs as follows: int main() { B b; cout << (bool)b << endl; W w; cout << (wchar_t)w << endl; return 0; } 52 int main () { vector vb; cout << (bool)vb[1] << endl; return 0; } o Compiling STL and "Arg list too long" Error Compiling STL code may generate a compilation error similar to that below indicating "Arg list to long": Error: Can't find or exec: /usr/lib/cmplrs/cxx/cc : Arg list too long If you are building an executable image the workaround is to add the following to your command line: -use_ld_input You cannot use this workaround to create a library. o Use of exception in and Standard C++ Library In DIGITAL C++ Version 6.1, namespaces resolve a conflict between the name exception found in the header , which represents a structure, and the name exception found in the C++ Standard Library header , which represents the Standard Library exception class. The structure exception from is visible in the global namespace. The Standard Library exception class from is visible in the std namespace. Because of this behavior, if you include, directly or indirectly, both of the headers and you must qualify actual uses of exception to avoid name conflicts: #include #include int main () { ::exception e; // exception from math.h std::exception e1; // Standard Library exception class return 0; } o collate_byname::do_transform() 53 The function collate_byname::do_transform() seg faults if you use it with any locale other than the "C" locale. This happens because of a bug with the underlying C function wcsxfrm(). No workaround currently exists for this problem. o ctype_base::graph In the current implementation of the ctype_base class, a character has a graph property if and only if it also has an alpha, a digit or a punct property. Thus, mathematical and scientific symbols and dingbats from the UNICODE character set will not be classified properly. o IOStreams cannot output IEEE NaNs/Infinities The Standard IOStreams Library does not support output for IEEE NaNs and Infinities. o ios_base::out does not truncate a file to zero length The ios_base::openmode ios_base::out should open a file for output. This means that the file is either truncated to zero length if it exists or created for writing if it does not. Therefore ios_base::out is the same as ios_base::out | ios_base_trunc. With our sources, the following program behaves incorrectly. #include #include using namespace std; int main() { fstream fs ("t.in",ios_base::out); fs << "A"; return 0; } Where t.in contains xyz. After running this program, t.in contains Ayz 54 It should contain A You can work around this problem by replacing ios_ base::out with ios_base::out | ios_base::trunc. o ios_base::in creates a file when it should not. ios_base::openmode ios_base::in should open a file for input. This means that if the file does not exist, it is not created. With our sources, the following program behaves incorrectly. #include #include int main() { fstream fs ("t.in",ios_base::in); return 0; } If t.in does not exist and this program is run, then t.in should not be created. Because of a bug, it is created in our ANSI library. o Overriding operator new in library If you want to define a global operator new() to displace the version used by the C++ Standard Library or C++ Class Library, follow these steps: 1. Define one module that you will always compile with -nostdnew. 2. The module will contain two entry points for your version of global operator new(): one entry point for the name generated to link with the C++ Standard Library and one entry point for the name generated to link with the C++ Class Library. The name of the entry point for linking with the C++ Class Library is operator new. The name for linking with the C++ Standard Library is based on the mangled name for that library and is __stdnw_XUl. 55 3. Define global operator new in terms of the entry point new. Then define global operator new in terms of __stdnw_XUl. The __stdnw_XUl version is declared with extern C and simply calls the first version. Your module will contain two routines similar to the following: #include ... // redefine global operator new, // entry point into C++ Class Library // based on compiling -nostdnew void *operator new(size_t size) { printf("in my global new\n"); ... } // entry point into C++ Standard Library // based on compiling -stdnew extern "C" void *__stdnw__XUl(size_t size) { return ::operator new(size); } 4. When you link with this module, your version of the global operator new() displaces the version used by either the C++ Standard Library or C++ Class Library. 11 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 1998. All Rights Reserved. 56 12 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. 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. 57