Sun Logo

C++ User's Guide

Suntrademark Studio 11




Code Samples

Before You Begin

How This Book Is Organized

Typographic Conventions

Shell Prompts

Supported Platforms

Accessing Sun Studio Software and Man Pages

Accessing Sun Studio Documentation

Accessing Related Solaris Documentation

Accessing C++ Related Man Pages

Commercially Available Books

Resources for Developers

Contacting Sun Technical Support

Sending Your Comments

Part I C++ Compiler

1. The C++ Compiler

1.1 New Features and Functionality of the Sun Studio 10 C++ 5.8 Compiler

1.2 New Features and Functionality of the Sun Studio 10 C++ 5.7 Compiler

1.3 Standards Conformance

1.4 C++ Readme File

1.5 Man Pages

1.6 C++ Utilities

1.7 Native-Language Support

2. Using the C++ Compiler

2.1 Getting Started

2.2 Invoking the Compiler

2.2.1 Command Syntax

2.2.2 File Name Conventions

2.2.3 Using Multiple Source Files

2.3 Compiling With Different Compiler Versions

2.4 Compiling and Linking

2.4.1 Compile-Link Sequence

2.4.2 Separate Compiling and Linking

2.4.3 Consistent Compiling and Linking

2.4.4 Compiling for SPARC V9

2.4.5 Diagnosing the Compiler

2.4.6 Understanding the Compiler Organization

2.5 Preprocessing Directives and Names

2.5.1 Pragmas

2.5.2 Macros With a Variable Number of Arguments

2.5.3 Predefined Names

2.5.4 #error

2.6 Memory Requirements

2.6.1 Swap Space Size

2.6.2 Increasing Swap Space

2.6.3 Control of Virtual Memory

2.6.4 Memory Requirements

2.7 Simplifying Commands

2.7.1 Using Aliases Within the C Shell

2.7.2 Using CCFLAGS to Specify Compile Options

2.7.3 Using make

3. Using the C++ Compiler Options

3.1 Syntax

3.2 General Guidelines

3.3 Options Summarized by Function

3.3.1 Code Generation Options

3.3.2 Compile-Time Performance Options

3.3.3 Debugging Options

3.3.4 Floating-Point Options

3.3.5 Language Options

3.3.6 Library Options

3.3.7 Licensing Options

3.3.8 Obsolete Options

3.3.9 Output Options

3.3.10 Run-Time Performance Options

3.3.11 Preprocessor Options

3.3.12 Profiling Options

3.3.13 Reference Options

3.3.14 Source Options

3.3.15 Template Options

3.3.16 Thread Options

Part II Writing C++ Programs

4. Language Extensions

4.1 Linker Scoping

4.2 Thread-Local Storage

4.3 Overriding With Less Restrictive Virtual Functions

4.4 Making Forward Declarations of enum Types and Variables

4.5 Using Incomplete enum Types

4.6 Using an enum Name as a Scope Qualifier

4.7 Using Anonymous struct Declarations

4.8 Passing the Address of an Anonymous Class Instance

4.9 Declaring a Static Namespace-Scope Function as a Class Friend

4.10 Using the Predefined __func__ Symbol for Function Name

5. Program Organization

5.1 Header Files

5.1.1 Language-Adaptable Header Files

5.1.2 Idempotent Header Files

5.2 Template Definitions

5.2.1 Template Definitions Included

5.2.2 Template Definitions Separate

6. Creating and Using Templates

6.1 Function Templates

6.1.1 Function Template Declaration

6.1.2 Function Template Definition

6.1.3 Function Template Use

6.2 Class Templates

6.2.1 Class Template Declaration

6.2.2 Class Template Definition

6.2.3 Class Template Member Definitions

6.2.4 Class Template Use

6.3 Template Instantiation

6.3.1 Implicit Template Instantiation

6.3.2 Explicit Template Instantiation

6.4 Template Composition

6.5 Default Template Parameters

6.6 Template Specialization

6.6.1 Template Specialization Declaration

6.6.2 Template Specialization Definition

6.6.3 Template Specialization Use and Instantiation

6.6.4 Partial Specialization

6.7 Template Problem Areas

6.7.1 Nonlocal Name Resolution and Instantiation

6.7.2 Local Types as Template Arguments

6.7.3 Friend Declarations of Template Functions

6.7.4 Using Qualified Names Within Template Definitions

6.7.5 Nesting Template Names

6.7.6 Referencing Static Variables and Static Functions

6.7.7 Building Multiple Programs Using Templates in the Same Directory

7. Compiling Templates

7.1 Verbose Compilation

7.2 Repository Administration

7.2.1 Generated Instances

7.2.2 Whole-Class Instantiation

7.2.3 Compile-Time Instantiation

7.2.4 Template Instance Placement and Linkage

7.3 External Instances

7.3.1 Static Instances

7.3.2 Global Instances

7.3.3 Explicit Instances

7.3.4 Semi-Explicit Instances

7.4 The Template Repository

7.4.1 Repository Structure

7.4.2 Writing to the Template Repository

7.4.3 Reading From Multiple Template Repositories

7.4.4 Sharing Template Repositories

7.4.5 Template Instance Automatic Consistency With -instances=extern

7.5 Template Definition Searching

7.5.1 Source File Location Conventions

7.5.2 Definitions Search Path

7.5.3 Troubleshooting a Problematic Search

8. Exception Handling

8.1 Synchronous and Asynchronous Exceptions

8.2 Specifying Runtime Errors

8.3 Disabling Exceptions

8.4 Using Runtime Functions and Predefined Exceptions

8.5 Mixing Exceptions With Signals and Setjmp/Longjmp

8.6 Building Shared Libraries That Have Exceptions

9. Cast Operations

9.1 const_cast

9.2 reinterpret_cast

9.3 static_cast

9.4 Dynamic Casts

9.4.1 Casting Up the Hierarchy

9.4.2 Casting to void*

9.4.3 Casting Down or Across the Hierarchy

10. Improving Program Performance

10.1 Avoiding Temporary Objects

10.2 Using Inline Functions

10.3 Using Default Operators

10.4 Using Value Classes

10.4.1 Choosing to Pass Classes Directly

10.4.2 Passing Classes Directly on Various Processors

10.5 Cache Member Variables

11. Building Multithreaded Programs

11.1 Building Multithreaded Programs

11.1.1 Indicating Multithreaded Compilation

11.1.2 Using C++ Support Libraries With Threads and Signals

11.2 Using Exceptions in a Multithreaded Program

11.2.1 Thread Cancellation

11.3 Sharing C++ Standard Library Objects Between Threads

11.4 Using Classic Iostreams in a Multithreading Environment

11.4.1 Organization of the MT-Safe iostream Library

11.4.2 Interface Changes to the iostream Library

11.4.3 Global and Static Data

11.4.4 Sequence Execution

11.4.5 Object Locks

11.4.6 MT-Safe Classes

11.4.7 Object Destruction

11.4.8 An Example Application

Part III Libraries

12. Using Libraries

12.1 The C Libraries

12.2 Libraries Provided With the C++ Compiler

12.2.1 C++ Library Descriptions

12.2.2 Accessing the C++ Library Man Pages

12.2.3 Default C++ Libraries

12.3 Related Library Options

12.4 Using Class Libraries

12.4.1 The iostream Library

12.4.2 The complex Library

12.4.3 Linking C++ Libraries

12.5 Statically Linking Standard Libraries

12.6 Using Shared Libraries

12.7 Replacing the C++ Standard Library

12.7.1 What Can Be Replaced

12.7.2 What Cannot Be Replaced

12.7.3 Installing the Replacement Library

12.7.4 Using the Replacement Library

12.7.5 Standard Header Implementation

13. Using The C++ Standard Library

13.1 C++ Standard Library Header Files

13.2 C++ Standard Library Man Pages

13.3 STLport

13.3.1 Redistribution and Supported STLport Libraries

14. Using the Classic iostream Library

14.1 Predefined iostreams

14.2 Basic Structure of iostream Interaction

14.3 Using the Classic iostream Library

14.3.1 Output Using iostream

14.3.2 Input Using iostream

14.3.3 Defining Your Own Extraction Operators

14.3.4 Using the char* Extractor

14.3.5 Reading Any Single Character

14.3.6 Binary Input

14.3.7 Peeking at Input

14.3.8 Extracting Whitespace

14.3.9 Handling Input Errors

14.3.10 Using iostreams With stdio

14.4 Creating iostreams

14.4.1 Dealing With Files Using Class fstream

14.5 Assignment of iostreams

14.6 Format Control

14.7 Manipulators

14.7.1 Using Plain Manipulators

14.7.2 Parameterized Manipulators

14.8 Strstreams: iostreams for Arrays

14.9 Stdiobufs: iostreams for stdio Files

14.10 Streambufs

14.10.1 Working With Streambufs

14.10.2 Using Streambufs

14.11 iostream Man Pages

14.12 iostream Terminology

15. Using the Complex Arithmetic Library

15.1 The Complex Library

15.1.1 Using the Complex Library

15.2 Type complex

15.2.1 Constructors of Class complex

15.2.2 Arithmetic Operators

15.3 Mathematical Functions

15.4 Error Handling

15.5 Input and Output

15.6 Mixed-Mode Arithmetic

15.7 Efficiency

15.8 Complex Man Pages

16. Building Libraries

16.1 Understanding Libraries

16.2 Building Static (Archive) Libraries

16.3 Building Dynamic (Shared) Libraries

16.4 Building Shared Libraries That Contain Exceptions

16.5 Building Libraries for Private Use

16.6 Building Libraries for Public Use

16.7 Building a Library That Has a C API

16.8 Using dlopen to Access a C++ Library From a C Program

Part IV Appendixes

A. C++ Compiler Options

A.1 How Option Information Is Organized

A.2 Option Reference

A.2.1 -386

A.2.2 -486

A.2.3 -a

A.2.4 -Bbinding

A.2.5 -c

A.2.6 -cg{89|92}

A.2.7 -compat[={4|5}]

A.2.8 +d

A.2.9 -D[ ]name[=def]

A.2.10 -d{y|n}

A.2.11 -dalign

A.2.12 -dryrun

A.2.13 -E

A.2.14 +e{0|1}

A.2.15 -erroff[=t]

A.2.16 -errtags[=a]

A.2.17 -errwarn[=t]

A.2.18 -fast

A.2.19 -features=a[,a...]

A.2.20 -filt[=filter[,filter...]]

A.2.21 -flags

A.2.22 -fnonstd

A.2.23 -fns[={yes|no}]

A.2.24 -fprecision=p

A.2.25 -fround=r

A.2.26 -fsimple[=n]

A.2.27 -fstore

A.2.28 -ftrap=t[,t...]

A.2.29 -G

A.2.30 -g

A.2.31 -g0

A.2.32 -H

A.2.33 -h[ ]name

A.2.34 -help

A.2.35 -Ipathname

A.2.36 -I-

A.2.37 -i

A.2.38 -inline

A.2.39 -instances=a

A.2.40 -instlib=filename

A.2.41 -KPIC

A.2.42 -Kpic

A.2.43 -keeptmp

A.2.44 -Lpath

A.2.45 -llib

A.2.46 -libmieee

A.2.47 -libmil

A.2.48 -library=l[,l...]

A.2.49 -mc

A.2.50 -migration

A.2.51 -misalign

A.2.52 -mr[,string]

A.2.53 -mt

A.2.54 -native

A.2.55 -noex

A.2.56 -nofstore

A.2.57 -nolib

A.2.58 -nolibmil

A.2.59 -noqueue

A.2.60 -norunpath

A.2.61 -O

A.2.62 -Olevel

A.2.63 -o filename

A.2.64 +p

A.2.65 -P

A.2.66 -p

A.2.67 -pentium

A.2.68 -pg

A.2.69 -PIC

A.2.70 -pic

A.2.71 -pta

A.2.72 -ptipath

A.2.73 -pto

A.2.74 -ptr

A.2.75 -ptv

A.2.76 -Qoption phase option[,option...]

A.2.77 -qoption phase option

A.2.78 -qp

A.2.79 -Qproduce sourcetype

A.2.80 -qproduce sourcetype

A.2.81 -Rpathname[:pathname...]

A.2.82 -readme

A.2.83 -S

A.2.84 -s

A.2.85 -sb

A.2.86 -sbfast

A.2.87 -staticlib=l[,l...]

A.2.88 -sync_stdio=[yes|no]

A.2.89 -temp=path

A.2.90 -template=opt[,opt...]

A.2.91 -time

A.2.92 -Uname

A.2.93 -unroll=n

A.2.94 -V

A.2.95 -v

A.2.96 -vdelx

A.2.97 -verbose=v[,v...]

A.2.98 +w

A.2.99 +w2

A.2.100 -w

A.2.101 -Xm

A.2.102 -xa

A.2.103 -xalias_level[=n]

A.2.104 -xar

A.2.105 -xarch=isa

A.2.106 -xautopar

A.2.107 -xbinopt={prepare|off}

A.2.108 -xbuiltin[={%all|%none}]

A.2.109 -xcache=c

A.2.110 -xcg[89|92]

A.2.111 -xchar[=o]

A.2.112 -xcheck[=i]

A.2.113 -xchip=c

A.2.114 -xcode=a

A.2.115 -xcrossfile[=n]

A.2.116 -xdebugformat=[stabs|dwarf]

A.2.117 -xdepend=[yes|no]

A.2.118 -xdumpmacros[=value[,value...]]

A.2.119 -xe

A.2.120 -xF[=v[,v...]]

A.2.121 -xhelp=flags

A.2.122 -xhelp=readme

A.2.123 -xia

A.2.124 -xinline[=func_spec[,func_spec...]]

A.2.125 -xipo[={0|1|2}]

A.2.126 -xjobs=n

A.2.127 -xlang=language[,language]

A.2.128 -xldscope={v}

A.2.129 -xlibmieee

A.2.130 -xlibmil

A.2.131 -xlibmopt

A.2.132 -xlic_lib=sunperf

A.2.133 -xlicinfo

A.2.134 -xlinkopt[=level]

A.2.135 -xM

A.2.136 -xM1

A.2.137 -xMerge

A.2.138 -xmaxopt[=v]

A.2.139 -xmemalign=ab

A.2.140 -xmodel=[a]

A.2.141 -xnativeconnect[=i]

A.2.142 -xnolib

A.2.143 -xnolibmil

A.2.144 -xnolibmopt

A.2.145 -xOlevel

A.2.146 -xopenmp[=i]

A.2.147 -xpagesize=n

A.2.148 -xpagesize_heap=n

A.2.149 -xpagesize_stack=n

A.2.150 -xpch=v

A.2.151 -xpchstop=file

A.2.152 -xpg

A.2.153 -xport64[=(v)]

A.2.154 -xprefetch[=a[,a...]]

A.2.155 -xprefetch_auto_type=a

A.2.156 -xprefetch_level[=i]

A.2.157 -xprofile=p

A.2.158 -xprofile_ircache[=path]

A.2.159 -xprofile_pathmap

A.2.160 -xregs=r[,r...]

A.2.161 -xrestrict[=f]

A.2.162 -xs

A.2.163 -xsafe=mem

A.2.164 -xsb

A.2.165 -xsbfast

A.2.166 -xspace

A.2.167 -xtarget=t

A.2.168 -xthreadvar[=o]

A.2.169 -xtime

A.2.170 -xtrigraphs[={yes|no}]

A.2.171 -xunroll=n

A.2.172 -xustr={ascii_utf16_ushort|no}

A.2.173 -xvector[=a]

A.2.174 -xvis[={yes|no}]

A.2.175 -xwe

A.2.176 -Yc,path

A.2.177 -z[ ]arg

B. Pragmas

B.1 Pragma Forms

B.1.1 Overloaded Functions as Pragma Arguments

B.2 Pragma Reference

B.2.1 #pragma align

B.2.2 #pragma does_not_read_global_data

B.2.3 #pragma does_not_return

B.2.4 #pragma does_not_write_global_data

B.2.5 #pragma dumpmacros

B.2.6 #pragma end_dumpmacros

B.2.7 #pragma fini

B.2.8 #pragma hdrstop

B.2.9 #pragma ident

B.2.10 #pragma init

B.2.11 #pragma no_side_effect

B.2.12 #pragma opt

B.2.13 #pragma pack(n)

B.2.14 #pragma rarely_called

B.2.15 #pragma returns_new_memory

B.2.16 #pragma unknown_control_flow

B.2.17 #pragma weak