C++ User’s Guide Sun™ Studio 11 Sun Microsystems, Inc. www.sun.com Part No. 819-3690-10 November 2005, Revision A Submit comments about this document at: http://www.sun.com/hwdocs/feedback Copyright © 2005 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Use is subject to license terms. This distribution may include materials developed by third parties. Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and in other countries, exclusively licensed through X/Open Company, Ltd. Sun, Sun Microsystems, the Sun logo, Java, and JavaHelp are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon architecture developed by Sun Microsystems, Inc. This product is covered and controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited. DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. Copyright © 2005 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, Etats-Unis. Tous droits réservés. L’utilisation est soumise aux termes de la Licence. Cette distribution peut comprendre des composants développés par des tierces parties. Des parties de ce produit pourront être dérivées des systèmes Berkeley BSD licenciés par l’Université de Californie. UNIX est une marque déposée aux Etats-Unis et dans d’autres pays et licenciée exclusivement par X/Open Company, Ltd. Sun, Sun Microsystems, le logo Sun, Java, et JavaHelp sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Etats-Unis et dans d’autres pays.Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d’autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc. Ce produit est soumis à la législation américaine en matière de contrôle des exportations et peut être soumis à la règlementation en vigueur dans d’autres pays dans le domaine des exportations et importations. Les utilisations, ou utilisateurs finaux, pour des armes nucléaires,des missiles, des armes biologiques et chimiques ou du nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou réexportations vers les pays sous embargo américain, ou vers des entités figurant sur les listes d’exclusion d’exportation américaines, y compris, mais de manière non exhaustive, la liste de personnes qui font objet d’un ordre de ne pas participer, d’une façon directe ou indirecte, aux exportations des produits ou des services qui sont régis par la législation américaine en matière de contrôle des exportations et la liste de ressortissants spécifiquement désignés, sont rigoureusement interdites. LA DOCUMENTATION EST FOURNIE "EN L’ÉTAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L’APTITUDE A UNE UTILISATION PARTICULIERE OU A L’ABSENCE DE CONTREFAÇON. Contents Before You Begin xxvii How This Book Is Organized xxvii Typographic Conventions xxviii Shell Prompts xxix Supported Platforms xxix Accessing Sun Studio Software and Man Pages xxx Accessing Sun Studio Documentation xxxiii Accessing Related Solaris Documentation xxxv Accessing C++ Related Man Pages xxxv Commercially Available Books xxxvi Resources for Developers xxxvii Contacting Sun Technical Support xxxvii Sending Your Comments xxxvii Part I C++ Compiler 1. The C++ Compiler 1–1 1.1 New Features and Functionality of the Sun Studio 10 C++ 5.8 Compiler 1–1 1.2 New Features and Functionality of the Sun Studio 10 C++ 5.7 Compiler 1–3 iii 1.3 Standards Conformance 1–5 1.4 C++ Readme File 1–6 1.5 Man Pages 1–6 1.6 C++ Utilities 1–7 1.7 Native-Language Support 1–7 2. Using the C++ Compiler 2–1 2.1 Getting Started 2–1 2.2 Invoking the Compiler 2–3 2.2.1 Command Syntax 2–3 2.2.2 File Name Conventions 2–4 2.2.3 Using Multiple Source Files 2–4 2.3 Compiling With Different Compiler Versions 2–5 2.4 Compiling and Linking 2–6 2.4.1 Compile-Link Sequence 2–6 2.4.2 Separate Compiling and Linking 2–6 2.4.3 Consistent Compiling and Linking 2–7 2.4.4 Compiling for SPARC V9 2–8 2.4.5 Diagnosing the Compiler 2–8 2.4.6 Understanding the Compiler Organization 2–9 2.5 Preprocessing Directives and Names 2–10 2.5.1 Pragmas 2–10 2.5.2 Macros With a Variable Number of Arguments 2–10 2.5.3 Predefined Names 2–11 2.5.4 #error 2–11 2.6 Memory Requirements 2–12 2.6.1 Swap Space Size 2–12 2.6.2 Increasing Swap Space 2–12 2.6.3 Control of Virtual Memory 2–13 iv C++ User’s Guide • November 2005 2.6.4 Memory Requirements 2–14 2.7 Simplifying Commands 2–14 2.7.1 Using Aliases Within the C Shell 2–14 2.7.2 Using CCFLAGS to Specify Compile Options 2–14 2.7.3 Using make 2–15 3. Using the C++ Compiler Options 3–1 3.1 Syntax 3–1 3.2 General Guidelines 3–2 3.3 Options Summarized by Function 3–2 3.3.1 Code Generation Options 3–3 3.3.2 Compile-Time Performance Options 3–4 3.3.3 Debugging Options 3–4 3.3.4 Floating-Point Options 3–5 3.3.5 Language Options 3–6 3.3.6 Library Options 3–6 3.3.7 Licensing Options 3–8 3.3.8 Obsolete Options 3–8 3.3.9 Output Options 3–9 3.3.10 Run-Time Performance Options 3–10 3.3.11 Preprocessor Options 3–12 3.3.12 Profiling Options 3–12 3.3.13 Reference Options 3–13 3.3.14 Source Options 3–13 3.3.15 Template Options 3–13 3.3.16 Thread Options 3–14 Part II Writing C++ Programs 4. Language Extensions 4–1 Contents v 4.1 Linker Scoping 4–1 4.2 Thread-Local Storage 4–3 4.3 Overriding With Less Restrictive Virtual Functions 4–3 4.4 Making Forward Declarations of enum Types and Variables 4–4 4.5 Using Incomplete enum Types 4–5 4.6 Using an enum Name as a Scope Qualifier 4–5 4.7 Using Anonymous struct Declarations 4–5 4.8 Passing the Address of an Anonymous Class Instance 4–7 4.9 Declaring a Static Namespace-Scope Function as a Class Friend 4–8 4.10 Using the Predefined __func__ Symbol for Function Name 4–8 5. Program Organization 5–1 5.1 Header Files 5–1 5.1.1 Language-Adaptable Header Files 5–1 5.1.2 Idempotent Header Files 5–3 5.2 Template Definitions 5–3 5.2.1 Template Definitions Included 5–3 5.2.2 Template Definitions Separate 5–4 6. Creating and Using Templates 6–1 6.1 Function Templates 6–1 6.1.1 Function Template Declaration 6–1 6.1.2 Function Template Definition 6–2 6.1.3 Function Template Use 6–2 6.2 Class Templates 6–3 6.2.1 Class Template Declaration 6–3 6.2.2 Class Template Definition 6–3 6.2.3 Class Template Member Definitions 6–4 6.2.4 Class Template Use 6–5 vi C++ User’s Guide • November 2005 6.3 Template Instantiation 6–6 6.3.1 Implicit Template Instantiation 6–6 6.3.2 Explicit Template Instantiation 6–6 6.4 Template Composition 6–8 6.5 Default Template Parameters 6–9 6.6 Template Specialization 6–9 6.6.1 Template Specialization Declaration 6–9 6.6.2 Template Specialization Definition 6–10 6.6.3 Template Specialization Use and Instantiation 6–10 6.6.4 Partial Specialization 6–10 6.7 Template Problem Areas 6–11 6.7.1 Nonlocal Name Resolution and Instantiation 6–11 6.7.2 Local Types as Template Arguments 6–13 6.7.3 Friend Declarations of Template Functions 6–14 6.7.4 Using Qualified Names Within Template Definitions 6–16 6.7.5 Nesting Template Names 6–16 6.7.6 Referencing Static Variables and Static Functions 6–17 6.7.7 Building Multiple Programs Using Templates in the Same Directory 6–17 7. Compiling Templates 7–1 7.1 Verbose Compilation 7–1 7.2 Repository Administration 7–1 7.2.1 Generated Instances 7–2 7.2.2 Whole-Class Instantiation 7–2 7.2.3 Compile-Time Instantiation 7–2 7.2.4 Template Instance Placement and Linkage 7–3 7.3 External Instances 7–3 7.3.1 Static Instances 7–5 Contents vii 7.3.2 Global Instances 7–5 7.3.3 Explicit Instances 7–6 7.3.4 Semi-Explicit Instances 7–6 7.4 The Template Repository 7–6 7.4.1 Repository Structure 7–7 7.4.2 Writing to the Template Repository 7–7 7.4.3 Reading From Multiple Template Repositories 7–7 7.4.4 Sharing Template Repositories 7–7 7.4.5 Template Instance Automatic Consistency With -instances= extern 7–8 7.5 Template Definition Searching 7–8 7.5.1 Source File Location Conventions 7–9 7.5.2 Definitions Search Path 7–9 7.5.3 Troubleshooting a Problematic Search 7–9 8.