JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris Studio 12.3: C++ User's Guide     Oracle Solaris Studio 12.3 Information Library
search filter icon
search icon

Document Information

Preface

Part I C++ Compiler

1.  The C++ Compiler

2.  Using the C++ Compiler

3.  Using the C++ Compiler Options

Part II Writing C++ Programs

4.  Language Extensions

5.  Program Organization

6.  Creating and Using Templates

7.  Compiling Templates

8.  Exception Handling

9.  Improving Program Performance

10.  Building Multithreaded Programs

Part III Libraries

11.  Using Libraries

11.1 C Libraries

11.2 Libraries Provided With the C++ Compiler

11.2.1 C++ Library Descriptions

11.2.2 Accessing the C++ Library Man Pages

11.2.3 Default C++ Libraries

11.3 Related Library Options

11.4 Using Class Libraries

11.4.1 iostream Library

11.4.1.1 Note About Classic iostreams and Legacy RogueWave Tools

11.4.2 Linking C++ Libraries

11.5 Statically Linking Standard Libraries

11.6 Using Shared Libraries

11.7 Replacing the C++ Standard Library

11.7.1 What Can Be Replaced

11.7.2 What Cannot Be Replaced

11.7.3 Installing the Replacement Library

11.7.4 Using the Replacement Library

11.7.5 Standard Header Implementation

11.7.5.1 Replacing Standard C++ Headers

11.7.5.2 Replacing Standard C Headers

12.  Using the C++ Standard Library

13.  Using the Classic iostream Library

14.  Building Libraries

Part IV Appendixes

A.  C++ Compiler Options

B.  Pragmas

Glossary

Index

11.7 Replacing the C++ Standard Library

Replacing the standard library that is distributed with the compiler is risky, and good results are not guaranteed. The basic operation is to disable the standard headers and library supplied with the compiler and to specify the directories where the new header files and library are found, as well as the name of the library itself.

The compiler supports the STLport and Apache stdcxx implementations of the standard library. See 12.2 STLport and 12.3 Apache stdcxx Standard Library for more information.

11.7.1 What Can Be Replaced

You can replace most of the standard library and its associated headers. The replaced library is libCstd, and the associated headers are the following:

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

The replaceable part of the library consists of what is loosely known as “STL”, plus the string classes, the iostream classes, and their helper classes. Because these classes and headers are interdependent, replacing just a portion of them is unlikely to work. You should replace all of the headers and all of libCstd if you replace any part.

11.7.2 What Cannot Be Replaced

The standard headers <exception>, <new>, and <typeinfo> are tied tightly to the compiler itself and to libCrun, and cannot reliably be replaced. The library libCrun contains many “helper” functions that the compiler depends on, and cannot be replaced.

The 17 standard headers inherited from C (<stdlib.h>, <stdio.h>, <string.h>, and so forth) are tied tightly to the Oracle Solaris operating system and the basic Solaris runtime library libc, and cannot reliably be replaced. The C++ versions of those headers (<cstdlib>, <cstdio>, <cstring>, and so forth) are tied tightly to the basic C versions and cannot reliably be replaced.

11.7.3 Installing the Replacement Library

To install the replacement library, you must first decide on the locations for the replacement headers and on the replacement for libCstd. For purposes of discussion, assume the headers are placed in /opt/mycstd/include and the library is placed in /opt/mycstd/lib. Assume the library is called libmyCstd.a. (Usually library names start with “lib”.)

11.7.4 Using the Replacement Library

On each compilation, use the -I option to point to the location where the headers are installed. In addition, use the -library=no%Cstd option to prevent finding the compiler’s own versions of the libCstd headers. For example:

example% CC -I/opt/mycstd/include -library=no%Cstd... (compile)

During compiling, the -library=no%Cstd option prevents searching the directory where the compiler’s own version of these headers is located.

On each program or library link, use the -library=no%Cstd option to prevent finding the compiler’s own libCstd, the -L option to point to the directory where the replacement library is, and the -l option to specify the replacement library. For example:

example% CC -library=no%Cstd -L/opt/mycstd/lib -lmyCstd... (link)

Alternatively, you can use the full path name of the library directly, and omit using the -L and -l options. For example:

example% CC -library=no%Cstd /opt/mycstd/lib/libmyCstd.a... (link)

During linking, the -library=no%Cstd option prevents linking the compiler’s own version of libCstd.

11.7.5 Standard Header Implementation

C has 17 standard headers (<stdio.h>, <string.h>, <stdlib.h>, and others). These headers are delivered as part of the Oracle Solaris operating system in the directory /usr/include. C++ has those same headers, with the added requirement that the various declared names appear in both the global namespace and in namespace std.

C++ also has a second version of each of the C standard headers (<cstdio>, <cstring>, and <cstdlib>, and others) with the various declared names appearing only in namespace std. Finally, C++ adds 32 of its own standard headers (<string>, <utility>, <iostream>, and others).

The obvious implementation of the standard headers would use the name found in C++ source code as the name of a text file to be included. For example, the standard headers <string> (or <string.h>) would refer to a file named string (or string.h) in some directory. That obvious implementation has the following drawbacks:

To solve these problems, the compiler include directory contains a file with the same name as the header, along with a symbolic link to it that has the unique suffix .SUNWCCh (SUNW is the prefix for all compiler-related packages, CC is the C++ compiler, and h is the usual suffix for header files). When you specify <string>, the compiler rewrites it to <string.SUNWCCh> and searches for that name. The suffixed name will be found only in the compiler’s own include directory. If the file so found is a symbolic link (which it normally is), the compiler dereferences the link exactly once and uses the result (string in this case) as the file name for error messages and debugger references. The compiler uses the suffixed name when emitting file dependency information.

The name rewriting occurs only for the two forms of the 17 standard C headers and the 32 standard C++ headers, only when they appear in angle brackets and without any path specified. If you use quotes instead of angle brackets, specify any path components, or specify some other header, no rewriting occurs.

The following table illustrates common situations.

Table 11-3 Header Search Examples

Source Code
Compiler Searches For
Comments
<string>
string.SUNWCCh
C++ string templates
<cstring>
cstring.SUNWCCh
C++ version of C string.h
<string.h>
string.h.SUNWCCh
C string.h
<fcntl.h>
fcntl.h
Not a standard C or C++ header
"string"
string
Double-quotation marks, not angle brackets
<../string>
../string
Path specified

If the compiler does not find header.SUNWCCh, the compiler restarts the search looking for the name as provided in the #include directive. For example, given the directive #include <string>, the compiler attempts to find a file named string.SUNWCCh. If that search fails, the compiler looks for a file named string.

11.7.5.1 Replacing Standard C++ Headers

Because of the search algorithm described in 11.7.5 Standard Header Implementation, you do not need to supply SUNWCCh versions of the replacement headers described in 11.7.3 Installing the Replacement Library. However, if you run into some of the described problems, the recommended solution is to add symbolic links having the suffix .SUNWCCh for each of the unsuffixed headers. That is, for file utility, you would run the following command:

example% ln -s utility utility.SUNWCCh

When the compiler looks first for utility.SUNWCCh, it will find it, and not be confused by any other file or directory called utility.

11.7.5.2 Replacing Standard C Headers

Replacing the standard C headers is not supported. If you nevertheless want to provide your own versions of standard headers, the recommended procedure is as follows:

For example, suppose you have replacements for <stdio.h> and <cstdio>. Put the files stdio.h and cstdio in directory /myproject/myhdr. In that directory, run the following commands:

example% ln -s stdio.h stdio.h.SUNWCCh
example% ln -s cstdio cstdio.SUNWCCh

Use the option -I/myproject/mydir on every compilation.

Caveats: