Libraries provide a way to share code among several applications and a way to reduce the complexity of very large applications. The C++ compiler gives you access to a variety of libraries. This chapter explains how to use these libraries.
The Solaris operating system comes with several libraries installed in /usr/lib. Most of these libraries have a C interface. Of these, the libc and libm, libraries are linked by the CC driver by default. The library libthread is linked if you use the–mt option. To link any other system library, use the appropriate –l option at link time. For example, to link the libdemangle library, pass –ldemangle on the CC command line at link time:
example% CC text.c -ldemangle |
The C++ compiler has its own runtime support libraries. All C++ applications are linked to these libraries by the CC driver. The C++ compiler also comes with several other useful libraries, as explained in the following section.
Several libraries are shipped with the C++ compiler. Some of these libraries are available only in compatibility mode (-compat=4), some are available only in the standard mode (–compat=5), and some are available in both modes. The libgc and libdemangle libraries have a C interface and can be linked to an application in either mode.
The following table lists the libraries that are shipped with the C++ compiler and the modes in which they are available.
Table 12–1 Libraries Shipped With the C++ Compiler
Library |
Description |
Available Modes |
---|---|---|
libstlport |
STLport implementation of the standard library. |
–compat=5 |
libstlport_dbg |
STLport library for debug mode |
–compat=5 |
C++ runtime |
–compat=5 |
|
C++ standard library |
–compat=5 |
|
Classic iostreams |
–compat=5 |
|
C++ runtime, classic iostreams |
–compat=4 |
|
Supports the -xia option |
–compat=5 |
|
complex library |
–compat=4 |
|
librwtool |
Tools.h++ 7 |
–compat=4,– compat=5 |
Debug-enabled Tools.h++ 7 |
–compat=4,–compat=5 |
|
Garbage collection |
C interface |
|
Demangling |
C interface |
Do not redefine or modify any of the configuration macros for STLport, Rogue Wave or Sun Microsystems C++ libraries. The libraries are configured and built in a way that works with the C++ compiler. libCstd and Tool.h++ are configured to inter-operate so modifying the configuration macros results in programs that will not compile, will not link, or do not run properly.
A brief description of each of these libraries follows.
libCrun: This library contains the runtime support needed by the compiler in the standard mode (–compat=5). It provides support for new/delete, exceptions, and RTTI.
libCstd: This is the C++ standard library. In particular, it includes iostreams. If you have existing sources that use the classic iostreams and you want to make use of the standard iostreams, you have to modify your sources to conform to the new interface. See the C++ Standard Library Reference online manual for details. You can access this manual by pointing your web browser to:
file:/opt/SUNWspro/docs/index.html |
If your compiler software is not installed in the /opt directory, ask your system administrator for the equivalent path on your system.
libiostream: This is the classic iostreams library built with– compat=5. If you have existing sources that use the classic iostreams and you want to compile these sources with the standard mode (–compat=5), you can use libiostream without modifying your sources. Use– library=iostream to get this library.
Much of the standard library depends on using standard iostreams. Using classic iostreams in the same program can cause problems.
libC: This is the library needed in compatibility mode (–compat=4). It contains the C++ runtime support as well as the classic iostreams.
libcomplex: This library provides complex arithmetic in compatibility mode (-compat=4). In the standard mode, the complex arithmetic functionality is available in libCstd.
libstlport: This is the STLport implementation of the C++ standard library. You can use this library instead of the default libCstd by specifying the option -library=stlport4. However, you cannot use libstlport and libCstd in the same program. You must compile and link everything, including imported libraries, using one or the other exclusively.
librwtool (Tools.h++): Tools.h++ is a C++ foundation class library from RogueWave. Version 7 of this library is provided with this release. This library is available in classic-iostreams form (-library=rwtools7) and standard-iostreams form (-library=rwtools7_std). For further information about this library, see the following online documentation.
Tools.h++ User’s Guide (Version 7)
Tools.h++ Class Library Reference (Version 7)
You can access this documentation by pointing your web browser to:
file:/opt/SUNWspro/docs/index.html |
If your compiler software is not installed in the /opt directory, ask your system administrator for the equivalent path on your system.
libgc: This library is used in deployment mode or garbage collection mode. Simply linking with the libgc library automatically and permanently fixes a program’s memory leaks. When you link your program with the libgc library, you can program without calling free or delete while otherwise programming normally. The garbage collection library has a dependency on the dynamic load library so specify -lgc and -ldl when you link your program.
Additional information can be found in the gcFixPrematureFrees(3) and gcInitialize(3) man pages.
libdemangle: This library is used for demangling C++ mangled names.
The man pages associated with the libraries described in this section are located in:
/opt/SUNWspro/man/man1
/opt/SUNWspro/man/man3
/opt/SUNWspro/man/man3C++
/opt/SUNWspro/man/man3cc4
If your compiler software is not installed in the /opt directory, ask your system administrator for the equivalent path on your system.
To access these man pages, ensure that your MANPATH includes /opt/SUNWspro/man (or the equivalent path on your system for the compiler software).
To access man pages for the C++ libraries, type:
example% man library-name |
To access man pages for version 4.2 of the C++ libraries, type:
example% man -s 3CC4 library-name |
You can also access the man pages by pointing your browser to:
file:/opt/SUNWspro/docs/index.html |
Some of the C++ libraries are linked by default by the CC driver, while others need to be linked explicitly. In the standard mode, the following libraries are linked by default by the CC driver:
In compatibility mode (-compat), the following libraries are linked by default:
-lC -lm -lc
See A.2.49 -library=l[,l...] for more information.
The CC driver provides several options to help you use libraries.
Use the– L option to specify a directory to be searched for the library.
Use the -mt option compile and link multithreaded code.
Use the -xia option to link the interval arithmetic libraries.
Use the -xlang option to link Fortran runtime libraries.
Use the– library option to specify the following libraries that are shipped with the Sun C++ compiler:
libCrun
libCstd
libiostream
libC
libcomplex
libstlport, libstlport_dbg
librwtool, librwtool_dbg
libgc
To use the classic-iostreams form of librwtool, use the -library=rwtools7 option. To use the standard-iostreams form of librwtool, use the -library=rwtools7_std option.
A library that is specified using both –library and –staticlib options will be linked statically. Some examples:
The following command links the classic-iostreams form of Tools.h++ version 7 and libiostream libraries dynamically.
example% CC test.cc -library=rwtools7,iostream |
The following command links the libgc library statically.
example% CC test.cc -library=gc -staticlib=gc |
The following command compiles test.cc in compatibility mode and links libC statically. Because libC is linked by default in compatibility mode, you are not required to specify this library using the– library option.
example% CC test.cc -compat=4 -staticlib=libC |
The following command excludes the libraries libCrun and libCstd, which would otherwise be included by default.
example% CC test.cc -library=no%Crun,no%Cstd |
By default, CC links various sets of system libraries depending on the command line options. If you specify -xnolib (or -nolib), CC links only those libraries that are specified explicitly with the -l option on the command line. (When -xnolib or -nolib is used, the -library option is ignored, if present.)
The –R option allows you to build dynamic library search paths into the executable file. At execution time, the runtime linker searches these paths for the shared libraries needed by the application. The CC driver passes– R/opt/SUNWspro/lib to ld by default (if the compiler is installed in the standard location). You can use -norunpath to disable building the default path for shared libraries into the executable.
Generally, two steps are involved in using a class library:
Include the appropriate header in your source code.
Link your program with the object library.
The C++ compiler provides two implementations of iostreams:
Classic iostreams. This term refers to the iostreams library shipped with the C++ 4.0, 4.0.1, 4.1, and 4.2 compilers, and earlier with the cfront-based 3.0.1 compiler. There is no standard for this library, but a lot of existing code uses it. This library is part of libC in compatibility mode and is also available in libiostream in the standard mode.
Standard iostreams. This is part of the C++ standard library, libCstd, and is available only in standard mode. It is neither binary-, nor source-compatible with the classic iostreams library.
If you have existing C++ sources, your code might look like the following example, which uses classic iostreams.
// file prog1.cc #include <iostream.h> int main() { cout << "Hello, world!" << endl; return 0; } |
The following command compiles in compatibility mode and links prog1.cc into an executable program called prog1. The classic iostream library is part of libC, which is linked by default in compatibility mode.
example% CC -compat prog1.cc -o prog1 |
The next example uses standard iostreams.
// file prog2.cc #include <iostream> int main() { std::cout << "Hello, world!" << std::endl; return 0; } |
The following command compiles and links prog2.cc into an executable program called prog2. The program is compiled in standard mode and libCstd, which includes the standard iostream library, is linked by default.
example% CC prog2.cc -o prog2 |
For more information about libCstd, see Caveats:. For more information about libiostream, see 13.3.1 Redistribution and Supported STLport Libraries.
For a full discussion of compilation modes, see the C++ Migration Guide.
The standard library provides a templatized complex library that is similar to the complex library provided with the C++ 4.2 compiler. If you compile in standard mode, you must use <complex> instead of <complex.h>. You cannot use <complex> in compatibility mode.
In compatibility mode, you must explicitly ask for the complex library when linking. In standard mode, the complex library is included in libCstd, and is linked by default.
There is no complex.h header for standard mode. In C++ 4.2, “complex” is the name of a class, but in standard C++, “complex” is the name of a template. It is not possible to provide typedefs that allow old code to work unchanged. Therefore, code written for 4.2 that uses complex numbers will need some straightforward editing to work with the standard library. For example, the following code was written for 4.2 and will compile in compatibility mode.
// file ex1.cc (compatibility mode) #include <iostream.h> #include <complex.h> int main() { complex x(3,3), y(4,4); complex z = x * y; cout << "x=" << x << ", y=" << y << ", z=" << z << endl; } |
The following example compiles and links ex1.cc in compatibility mode, and then executes the program.
example% CC -compat ex1.cc -library=complex example% a.out x=(3, 3), y=(4, 4), z=(0, 24) |
Here is ex1.cc rewritten as ex2.cc to compile in standard mode:
// file ex2.cc (ex1.cc rewritten for standard mode) #include <iostream> #include <complex> using std::complex; int main() { complex<double> x(3,3), y(4,4); complex<double> z = x * y; std::cout << "x=" << x << ", y=" << y << ", z=" << z << std::endl; } |
The following example compiles and links the rewritten ex2.cc in standard mode, and then executes the program.
% CC ex2.cc % a.out x=(3,3), y=(4,4), z=(0,24) |
For more information about using the complex arithmetic library, see Table 14–4.
The following table shows the compiler options for linking the C++ libraries. See A.2.49 -library=l[,l...] for more information.
Table 12–2 Compiler Options for Linking C++ Libraries
Library |
Compilation Mode |
Option |
---|---|---|
–compat=5 |
None needed -library=iostream |
|
complex |
–compat=4 -compat=5 |
-library=complex None needed |
–compat=4 –compat=5 |
-library=rwtools7 -library=rwtools7_std |
|
Tools.h++ version 7 debug |
–compat=4 –compat=5 |
-library=rwtools7_dbg -library=rwtools7_dbg,iostream -library=rwtools7_std_dbg |
–compat=4 –compat=5 |
-library=gc -library=gc |
|
STLport version 4 |
–compat=5 |
-library=stlport4 |
STLport version 4 debug |
–compat=5 |
-library=stlport4_dbg |
The CC driver links in shared versions of several libraries by default, including libc and libm, by passing a -llib option for each of the default libraries to the linker. (See 12.2.3 Default C++ Libraries for the list of default libraries for compatibility mode and standard mode.)
If you want any of these default libraries to be linked statically, you can use the -library option along with the –staticlib option to link a C++ library statically. This alternative is much easier than the one described earlier. For example:
example% CC test.c -staticlib=Crun |
In this example, the -library option is not explicitly included in the command. In this case the -library option is not necessary because the default setting for -library is Cstd,Crun in standard mode (the default mode).
Alternately, you can use the -xnolib compiler option. With the -xnolib option, the driver does not pass any -l options to ld; you must pass these options yourself. The following example shows how you would link statically with libCrun, and dynamically with libm, and libc in the Solaris 8, or Solaris 9 operating systems:
example% CC test.c– xnolib– lCstd– Bstatic– lCrun– Bdynamic– lm– lc |
The order of the -l options is important. The– lCstd,– lCrun, and -lm options appear before -lc.
Some CC options link to other libraries. These library links are also suppressed by -xnolib. For example, using the -mt option causes the CC driver to pass -lthread to ld. However, if you use both–mt and –xnolib, the CC driver does not pass-lthread to ld. See A.2.149 –xnolib for more information. See Linker and Libraries Guide for more information about ld.
The following shared libraries are included with the C++ compiler:
libCrun.so
libC.so
libcomplex.so
libstlport.so
librwtool.so
libgc.so
libgc_dbg.so
libCstd.so
libiostream.so
The occurrence of each shared object linked with the program is recorded in the resulting executable (a.out file); this information is used by ld.so to perform dynamic link editing at runtime. Because the work of incorporating the library code into an address space is deferred, the runtime behavior of the program using a shared library is sensitive to an environment change—that is, moving a library from one directory to another. For example, if your program is linked with libcomplex.so.5 in /opt/SUNWspro/lib, and the libcomplex.so.5 library is later moved into /opt2/SUNWspro/lib, the following message is displayed when you run the binary code:
ld.so: libcomplex.so.5: not found |
You can still run the old binary code without recompiling it by setting the environment variable LD_LIBRARY_PATH to the new library directory.
In a C shell:
example% setenv LD_LIBRARY_PATH \ /opt2/SUNWspro/release/lib:${LD_LIBRARY_PATH} |
In a Bourne shell:
example$ LD_LIBRARY_PATH=\ /opt2/SUNWspro/release/lib:${LD_LIBRARY_PATH} example$ export LD_LIBRARY_PATH |
release is specific for each release of the compiler software.
The LD_LIBRARY_PATH has a list of directories, usually separated by colons. When you run a C++ program, the dynamic loader searches the directories in LD_LIBRARY_PATH before it searches the default directories.
Use the ldd command as shown in the following example to see which libraries are linked dynamically in your executable:
example% ldd a.out |
This step should rarely be necessary, because the shared libraries are seldom moved.
When shared libraries are opened with dlopen, RTLD_GLOBAL must be used for exceptions to work.
See Linker and Libraries Guide for more information on using shared libraries.
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 implementation of the standard library. See 13.3 STLport for more information.
You can replace most of the standard library and its associated headers. The replaced library is libCstd, and the associated headers are listed in the following table:
<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.
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 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.
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. (It is often convenient if the library name starts with “lib”.)
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. 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.
C has 17 standard headers (<stdio.h>, <string.h>, <stdlib.h>, and others). These headers are delivered as part of the 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. On versions of the Solaris operating system prior to version 8, the C++ compiler supplies its own versions of these headers instead of replacing those in the /usr/include directory.
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:
You cannot search for just header files or create a makefile rule for the header files if they do not have file name suffixes.
If you have a directory or executable program named string, it might erroneously be found instead of the standard header file.
On versions of the Solaris operating system prior to the Solaris 8 operating system, the default dependencies for makefiles when .KEEP_STATE is enabled can result in attempts to replace standard headers with an executable program. (A file without a suffix is assumed by default to be a program to be built.)
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 12–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.
Because of the search algorithm described in 12.7.5 Standard Header Implementation, you do not need to supply SUNWCCh versions of the replacement headers described in 12.7.3 Installing the Replacement Library. But you might run into some of the described problems. If so, 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 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.
Replacing the standard C headers is not supported. If you nevertheless wish to provide your own versions of standard headers, the recommended procedure is as follows:
Put all the replacement headers in one directory.
Create a .SUNWCCh symbolic link to each of the replacement headers in that directory.
Cause the directory that contains the replacement headers to be searched by using the -I directives on each invocation of the compiler.
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 these commands:
example% ln -s stdio.h stdio.h.SUNWCCh example% ln -s cstdio cstdio.SUNWCCh |
Use the option -I/myproject/mydir on every compilation.
If you replace any C headers, you must replace them in pairs. For example, if you replace <time.h>, you should also replace <ctime>.
Replacement headers must have the same effects as the versions being replaced. That is, the various runtime libraries such as libCrun, libC, libCstd, libc, and librwtool are built using the definitions in the standard headers. If your replacements do not match, your program is unlikely to work.