Creating and Using Libraries

For additional background, refer to the HP-UX Online Linker and Libraries User's Guide which is frequently referenced in these sections.

• HP aC++ Libraries
• Creating and Using Shared Libraries
• Advanced Shared Library Features
• Standard HP-UX Libraries and Header Files

Migration

• Migration Considerations when Using Libraries

See Also

• Mixing C++ with Other Languages

HP aC++ Libraries

In addition to standard HP-UX system libraries, HP aC++ provides the following C++ libraries.

Standards Based Libraries

• Standard C++ Library
• Tools.h++ Library
• HP aC++ Run-time Support Library

HP C++ (cfront) Compatibility Libraries

NOTE: HP aC++ provides the following libraries whose functionality is also provided with HP C++ (cfront). These libraries are not standards based.

• IOStream Library

See Also:

• HP aC++ File Locations
• Linking to C++ Libraries
• Migration Considerations when Using Libraries

Standard C++ Library

• Introductory Concepts
• Details
• Standard C++ Library Documentation and Example Code
• Run-time Libraries and Header Files

Introductory Concepts

• A subset of data structures and algorithms, updated from the original library developed at Hewlett Packard by Alex Stepanov and Meng Lee and known as the C++ Standard Template Library (STL).

  NOTE: The public domain C++ Standard Template Library is not supported by this Standard C++ Library.

  For an introduction, see the following topics:

  • How the Standard C++ Library Differs from Other Libraries
  • The Non-Object-Oriented Design of the Standard C++ Library

• A templatized string class
• A templatized class for representing complex numbers
• A uniform framework for describing the execution environment, through the use of a template class named numeric_limits and specializations for each fundamental data type
• Memory management features
• Language support features
• Exception handling features

For More Information

• Introduction to Using the Standard C++ Library

How the Standard C++ Library Differs from Other Libraries

An emphasis on encapsulation is a key hallmark of object-oriented programming. The emphasis on combining data and functionality into an object is a powerful organization principle in software development; indeed it is the primary organizational technique. Through the proper use of encapsulation, even exceedingly complex software systems can be divided into manageable units and assigned to various members of a team of programmers for development.

Inheritance is a powerful technique for permitting code sharing and software reuse, but it is most applicable when two or more classes share a common set of basic features. For example, in a graphical user interface, two types of windows may inherit from a common base window class, and the individual subclasses will provide any required unique features. In another use of inheritance, object-oriented container classes may ensure common behavior and support code reuse by inheriting from a more general class, and factoring out common member functions.

The designers of the STL decided against using an entirely object-oriented approach, and separated the tasks to be performed using common data structures from the representation of the structures themselves. The STL was designed as a collection of algorithms and, separate from these, a collection of data structures that could be manipulated using the algorithms.

The Non-Object-Oriented Design of the Standard C++ Library

Smaller Source Code

Flexibility

Efficiency

Iterators: Mismatches and Invalidations

Templates: Errors and "Code Bloat"

Multithreading Problems

Introduction to Using the Standard C++ Library

The key is to use the right tool for each task. Object-oriented design methods and programming techniques are almost without peer as guideposts in the development of large complex software. For the large majority of programming tasks, object-oriented techniques will remain the preferred approach. Products such as Rogue Wave's Tools.h++ Library which encapsulates the Standard C++ Library with a familiar object-oriented interface, can provide you with the power and the advantages of object-orientation.

Use Standard C++ Library components directly when you need flexibility or highly efficient code. Use the more traditional approaches to object-oriented design, such as encapsulation and inheritance, when you need to model larger problem domains and knit all the pieces into a full solution. When you need to devise an architecture for your application, always consider the use of encapsulation and inheritance to compartmentalize the problem. But if you discover that you need an efficient data structure or algorithm for a compact problem (the kind of problem that often resolves to a single class), look to the Standard C++ Library. The library excels in the creation of reusable classes, where low-level constructs are needed, while traditional OOP techniques really shine when those classes are combined to solve a larger problem.

In the future, most libraries will use the Standard C++ Library as their foundation. By using the Standard C++ Library, either directly or through an encapsulation such as Tools.h++ Library, you help insure interoperability. This is especially important in large projects that may rely on communication between several libraries. A good rule of thumb is to use the highest encapsulation level available to you, but make sure that the Standard C++ Library is available as the base for interlibrary communication and operation.

The C++ language supports a wide range of programming approaches because the problems we need to solve require that range. The language, and now the Standard C++ Library that supports it, are designed to give you the flexibility to approach each unique problem from the best possible angle. The Standard C++ Library, when combined with more traditional OOP techniques, puts a very flexible tool into the hands of anyone building a collection of C++ classes, whether those classes are intended to stand alone as a library or are tailored to a specific task.

Standard C++ Library Reference

Select from the following categories to see further explanation from the Rogue Wave Software Standard C++ Library 1.2.1 Class Reference. Corresonding header file(s) are noted at the beginning of each category. Note that system man pages are also available.

NOTE: If you are accessing this guide from the World Wide Web URL, http://docs.hp.com, rather than from a system on which HP aC++ is installed, Rogue Wave documentation is not available. The following links will not succeed.

• Algorithms
• Allocators
• Complex Number Library
• Containers
• Exception Class
• Function Adaptors
• Function Objects
• Generalized Numeric Operations
• Insert Iterators
• Iterator Operations
• Iterators
• Memory Handling Primitives
• Memory Management
• Numeric Limits Library
• Stream Iterators
• String Library
• Utility Classes
• Utility Operators

Algorithms

• adjacent_find-- find the first adjacent pair of elements in a sequence that are equivalent
• binary_search-- algorithm to perform a binary search on ordered containers
• copy-- algorithm to copy values from one specified range to another; use to copy values from one container to another, or to copy values from one location in a container to another location in the same container
• copy_backward-- algorithm to copy elements in one specified range to another, starting from the end of the sequence and progressing to the front
• count-- count the number of elements in a container that satisfy a given value
• count_if-- count the number of elements in a container that satisfy a given predicate
• equal-- compares two ranges for equality
• equal_range-- find the largest subrange in a collection into which a given value can be inserted without violating the ordering of the collection
• fill-- initialize a range with a given value
• fill_n-- assign a value to the elements in a sequence
• find-- find an occurence of value in a sequence
• find_end-- find a subsequence of equal values in a sequence
• find_first_of-- find the first occurrence of any value from one sequence in another sequence
• find_if-- in a sequence, find an occurrence of a value that satisfies a specifed predicate
• for_each-- apply a function to each element in a range
• generate-- initialize a container with values produced by a value-generator class
• generate_n-- initialize a container with values produced by a value-generator class
• includes-- compare two sorted sequences and returns true if every element in one range is contained in the other
• inplace_merge -- merge two sorted sequences into one
• iter_swap-- exchange values pointed at in two locations
• lexicographical_compare-- compares two ranges lexicographically
• lower_bound-- determine the first valid position for an element in a sorted container
• make_heap-- creates a heap
• max-- find and return the maximum of a pair of values
• max_element-- find the maximum value in a range
• merge-- merge two sorted sequences into a third sequence
• min-- find and return the minimum of a pair of values
• min_element-- find the minimum value in a range
• mismatch-- compare elements from two sequences and return the first two elements that don't match
• next_permutation-- generate successive permutations of a sequence based on an ordering function
• nth_element-- rearrange a collection so that all elements lower in sorted order than the nth element come before it and all elements higher in sorter order than the nth element come after it
• partial_sort-- templated algorithm for sorting collections of entities
• partial_sort_copy-- templated algorithm for sorting collections of entities
• partition-- place all of the entities that satisfy the given predicate before all of the entities that do not
• pop_heap-- move the largest element off the heap
• prev_permutation-- generate successive permutations of a sequence based on an ordering function
• push_heap-- place a new element into the heap
• random_shuffle -- randomly shuffle elements of a collection
• remove-- move desired elements to the front of a container, and return an iterator that describes where the sequence of desired elements ends
• remove_copy-- similar to remove
• remove_copy_if-- similar to remove
• remove_if-- similar to remove
• replace-- substitute elements stored in a collection with new values
• replace_copy-- similar to replace
• replace_copy_if-- similar to replace
• replace_if-- similar to replace
• reverse-- reverse the order of elements in a collection
• reverse_copy-- reverse the order of elements in a collection while copying them to a new collecton
• rotate-- left rotates the order of items in a collection, placing the first item at the end, second item first, etc., until the item pointed to by a specified iterator is the first item in the collection
• rotate_copy-- rotate elements as in rotate, but instead of swapping elements within the same sequence, copies the result of the rotation to a container specified by result
• search-- find a subsequence within a sequence of values that is element-wise equal to the values in an indicated range
• search_n-- similar to search but searches for a given number of occurrences
• set_difference-- construct a sorted difference that includes copies of the elements present in one range but not in another, return the end of the constructed range
• set_intersection-- construct a sorted intersection of elements from two ranges, return the end of the constructed range
• set_symmetric_difference -- construct a sorted symmetric difference of the elements from two ranges, include copies of the elements present in only one of the ranges
• set_union-- construct a sorted union of the elements from two ranges, return the end of the constructed range
• sort-- templated algorithm for sorting collections of entities
• sort_heap-- convert a heap into a sorted collection
• stable_partition-- place all entities that satisfy the given predicate before all entities that do not, while maintaining the relative order of elements in each group
• stable_sort-- templated algorithm for sorting collections of entities
• swap-- exchange values
• swap_ranges-- exchange a range of values in one location with those in another
• transform-- apply an operation to a range of values in a collection and stores the result
• unique-- remove consecutive duplicates from a range of values and place the resulting unique values into the result, overwriting the existin elements
• unique_copy-- remove consecutive duplicates from a range of values and place the resulting unique values into the resulting OutputIterator
• upper_bound-- determines the last valid position for a value in a sorted container

Allocators

The Standard C++ Library provides a default allocator class that implements this interface using the standard new and delete operators for all storage management.

Complex Number Library

• complex-- a template class used to create objects for representing and manipulating complex numbers

Containers

Collection classes are often described as Containers. A container stores a collection of other objects and provides certain basic functionality that supports the use of generic algorithms. Containers come in two basic flavors: sequences and associative_containers. They are further distinguished by the type of iterator they support.

• bitset-- random access to a set of binary values; operations can be performed using logical bit-wise operators, no iterators for accessing elements
• deque -- random access, insertion at front or back
• list-- insertion and removal throughout
• map -- access to values via keys, insertion and removal
• multimap-- map permitting duplicate keys
• multiset-- set with repeated copies
• priority_queue-- access and removal of largest value
• queue-- insertion at back, removal from front
• set-- elements maintained in order, test for inclusion, insertion, and removal
• stack-- insertion and removal only from top
• vector-- random access to elements, insertions at end

Allocation Policies for Containers

For -AP Standard Library

  template <>
  inline size_t __rw-allocation_size(bar*,size_t) {
  return 1;
  }

For -AA Standard Library

  template <>
  inline size_t __rw_new_capacity (size_t __size, const _Container*)

The defaults have been tuned with speed vs. space optimization of container performance with regard to allocation of memory.

The ratio parameter must be above one for an amortized constant time algorithm. Lowering the ratio will lower rapidity and improve space efficiency. This effect will be most noticable when working with containers of few elements (few being less than 32).

Exception Class

• exception-- base class to support logic and runtime errors

Function Adaptors

• not1-- use to reverse the sense of a unary predicate function object
• not2-- use to reverse the sense of a binary predicate function object
• ptr_fun-- adapt a pointer to a function to work where a function is called for

Function Objects

• binary_function-- base class for creating binary function objects
• binary_negate-- returns the complement of the result of its binary predicate
• bind1st and binder1st-- templatized utilities to bind a value to the first argument of a binary function object
• bind2nd and binder2nd-- templatized utilities to bind a value to the second argument of a binary function object
• divides-- returns the result of dividing its first argument by its second
• equal_to-- returns true if its first argument equals its second
• greater-- returns true if its first argument is greater than its second
• greater_equal-- returns true if its first argument is greater than or equal to its second
• less-- returns true if its first argument is less than its second
• less_equal-- returns true if its first argument is less than or equal to its second
• logical_and-- returns true if both of its arguments are true
• logical_not-- returns true if its argument is false
• logical_or-- returns true if either of its arguments is true
• minus-- returns the result of subtracting its second argument from its first
• modulus-- returns the remainder obtained by dividing the first argument by the second argument
• negate-- returns the negation of its argument
• not_equal_to-- returns true if its first argument is not equal to its second
• plus-- returns the result of adding its first and second arguments
• pointer_to_binary_function-- adapts a pointer to a binary function to work where a binary_function function object is called for
• pointer_to_unary_function-- adapts a pointer to a function to work where a unary_function function object is called for
• times-- returns the result of multiplying its first and second arguments
• unary_function-- base class for creating unary function objects
• unary_negate-- function object class that returns the complement of the result of its unary predicate

Generalized Numeric Operations

• accumulate-- accumulates all elements within a range into a single value
• adjacent_difference-- outputs a sequence of the differences between each adjacent pair of elements in a range
• inner_product-- computes the inner product A X B of two ranges A and B
• partial_sum-- calculates successive partial sums of a range of values

Insert Iterators

Insert Iterators are adaptors that allow an iterator to insert into a container rather than overwrite elements in the container.

• back_insert_iterator-- class to insert items at the end of a collection
• back_inserter-- function to create an instance of a back_insert_iterator for a particular collection type
• front_insert_iterator-- class to insert items at the beginning of a collection
• front_inserter-- function to create an instance of a front_insert_iterator for a particular collection type
• insert_iterator-- class to insert items into a specified location of a collection
• inserter-- function to create an instance of an insert_iterator given a particular collection type and iterator

Iterator Operations

• advance-- move an iterator forward or backward (if available) by a specified distance
• distance-- compute the distance between two iterators
• distance_type-- determine the type of distance used by an iterator
• iterator_category-- determine the category to which an iterator belongs
• value_type-- determine the type of value to which an iterator points

Iterators

• reverse_bidirectional_iterator-- read and write, forward and backward moving
• reverse_iterator-- read and write, random access

Memory Handling Primitives

• get_temporary_buffer-- pointer based primitive to reserve the largest possible buffer that is less than or equal to the size requested
• return_temporary_buffer-- pointer based primitive to return to available mamory a buffer previously allocated via get_temporary_buffer

Memory Management

• auto_ptr -- a simple, smart pointer class
• raw_storage_iterator-- enable iterator-based algorithms to store results into uninitialized memory
• uninitialized_copy-- algorithm that uses the construct primitive to copy values from one range to another location
• uninitialized_fill-- algorithm that uses the construct primitive to set values in a collection
• uninitialized_fill_n-- algorithm that uses the construct primitive to set values in a collection

Numeric Limits Library

• numeric_limits-- a class for representing information about scalar types

Stream Iterators

• istream_iterator-- stream iterator provides iterator capabilities for istreams
• ostream_iterator-- stream iterator to provide iterator capabilities for ostreams and istreams

String Library

• basic_string-- templated class for handling sequences of character-like entities
• string-- a specialization of the basic_string class
• string_char_traits -- a traits class providing types and operations to the basic_string container
• wstring-- a specializatio of the basic_string class

Utility Classes

• pair-- class that provides a template for encapsulating pairs of values that may be of different types

Utility Operators

• operator!=
• operator>
• operator<=
• operator>=

Tools.h++ Library

• Introduction to Using the Standard C++ Library
• Tools.h++ Library Documentation and Example Code
• Run-time Libraries and Header Files

HP aC++ Run-time Support Library

The library supports the following functionality:

• Exception Handling
• Memory Management (operators new and delete)
• Start and termination of a C++ program
• Run-time type identification (type_info)
• static object constructors and desctructors

For More Information

• Run-time Libraries and Header Files

IOStream Library

NOTE: At this release of HP aC++, the standards based iostream capabilities of the Standard C++ Library are still evolving. As a result, an HP C++ (cfront) compatible IOStream library is provided.

For More Information

• Migration Considerations when Using Libraries

Linking to C++ Libraries

You can compile and link any C++ modules to one or more libraries. HP aC++ automatically links the following with a C++ executable. Note that when you specify the -b option to create a shared library, these defaults do not apply.

• /usr/lib/hpux##/libCsup.so (the HP aC++ run-time support library)
• /usr/lib/hpux##/libstd.so (standard C++ library)
• /usr/lib/hpux##/libstd_v2.so (standard C++ library -AA)
• /usr/lib/hpux##/libstream.so(iostream library)
• /usr/lib/hpux##/libc.so (the HP-UX system library)
• /usr/lib/hpux##/libdld.so (routines for managing shared libraries)
• /usr/lib/hpux##/libm.so (math library)
• /usr/lib/hpux##/libunwind.so (routines for unwinding)

For ## substitute either 32 or 64 as appropriate.

Linking with Shared or Archive Libraries

If you want archive libraries instead of shared libraries, use the -a,archive linker option.

NOTE: To maintain compatibility on future releases, archive and shared libraries should not be mixed. Refer to the "Mixing Shared and Archive Libraries" section in the HP-UX Online Linker and Libraries User's Guide.

Specifying Other Libraries

aCC myapp.C -lrwtool

Creating and Using Shared Libraries

Select one of the following topics:

• Compiling for Shared Libraries
• Creating a Shared Library
• Using a Shared Library
• Example of Creating and Using a Shared Library
• Linking Archive or Shared Libraries
• Updating a Shared Library

For More Information

• Refer to Advanced Shared Library Features.

• For additional information about creating and using shared libraries, refer to the HP-UX Online Linker and Libraries User's Guide

• For information on using the options to the aCC command, select command-line options.

Compiling for Shared Libraries

Creating a Shared Library

CAUTION: You must use the aCC command to create a C++ shared library. This is because the aCC command ensures that any static constructors and destructors in the shared library are executed at the appropriate times.

Example

aCC -b -o util.so util.o

Using a Shared Library

The linker links the shared library to the executable file it creates. Once you create an executable file that uses a shared library, you must not move the shared library or the dynamic loader (dld.so(5)) will not be able to find it.

CAUTION: You must use the aCC command to link any program that uses a C++ shared library. This is because the aCC command ensures that any static constructors and destructors in the shared library are executed at the appropriate times.

Example

aCC prog.C util.so

Example of Creating and Using a Shared Library

aCC -c  Strings.C Arrays.C

The following command builds a shared library named libshape.so from the object files Strings.o and Arrays.o:

aCC -b -o libshape.so Strings.o Arrays.o

The following command compiles a program, draw_shapes.C, that uses the shared library, libshape.so:

aCC draw_shapes.C libshape.so

Linking Archive or Shared Libraries

The -a linker option tells the linker which type of library to use. The -a option is positional and applies to all subsequent libraries specified with the -l option until the end of the command line or until the next -a option is encountered. Pass the -a option to the linker with the -Wx,args option.

Syntax:

-Wl,-a,{archive
        shared
        default}

The different meanings of this option are:

-Wl,-a,archive

Select archive libraries. If the archive library does not exist, the linker generates a warning message and does not create the output file.

-Wl,-a,shared

Select shared libraries. If the shared library does not exist, the linker generates a warning message and does not create the output file.

-Wl,-a,default

Select the shared library if it exists; otherwise, select the archive library.

Example:

aCC box.o sphere.o -Wl,-a,archive -lshape -Wl,-a,default

Updating a Shared Library

If, for example, a module in an existing shared library requires a fix, simply recompile the fixed module then recreate the shared library with the -b option. Any programs that use this library will now be using the new versions of the routines. That is, you do not have to relink any programs that use this shared library because they are attached at run time.

Advanced Shared Library Features

Select one of the following:

• Forcing the Export of Symbols in main
• Binding Times
• Side Effects of C++ Shared Libraries
• Routines and Options to Manage C++ Shared Libraries
• Version Control for Shared Libraries
• Adding New Versions to a Shared Library
• Pragmas for Improving Shared Library Performance

Forcing the Export of Symbols in main

Normally, this is a problem only when a program explicitly calls shared library management routines. (See Routines and Options to Manage C++ Shared Libraries.)

To make the linker export all symbols from a program, use the -Wl,-E option which passes the -E option to the linker.

Binding Times

Forcing Immediate Binding

Example

aCC -Wl,-B,immediate draw_shapes.o -lshape

To specify default binding, use -Wl,B,deferred.

For More Information

Side Effects of C++ Shared Libraries

Routines and Options to Manage C++ Shared Libraries

If an error occurs when calling shared library management routines, the system error variable, errno, is set to an appropriate error value. Constants are defined for these error values in /usr/include/errno.h (see errno(2)). Thus, if a program checks for these values, it must include errno.h:

Linker Options to Manage Shared Libraries

For More Information

• For more information about library management routines and linker options, refer to the HP-UX Online Linker and Libraries User's Guide.
• Man pages for shl_load(3X) and shl_unload(3X).

Version Control for Shared Libraries

For More Information

Standard HP-UX Libraries and Header Files

Location of Standard HP-UX Header Files

Using Header Files

#include <filename.h>

where filename.h is the name of the C++ header file for the library function you want to use. By enclosing filename.h in angle brackets, the HP aC++ compiler looks for that particular header file in a standard location on the system. The compiler first looks for header files in /opt/aCC/include; if none are found, it then searches /usr/include.

You can use header file options to modify the search path.

Example of Using a Standard Header File

#include <stdlib.h>

because the external declaration of getenv is found in the header file /usr/include/stdlib.h.

HP aC++ File Locations

• HP aC++ Executables
• Run-time Libraries and Header Files

HP aC++ Executable Files

• /opt/aCC/bin/aCC -- driver

  the only supported interface to HP aC++ and to the linker for HP aC++ object files

• /opt/aCC/lbin/ctcom -- compiler

  performs source compilation; preprocessing is incorporated into the compiler

• /opt/aCC/bin/c++filt -- name demangler

  implements the name demangling algorithm which encodes function name, class name, parameter number and name

• /usr/ccs/bin/ld -- linker

  links executables and builds shared libraries

HP aC++ Run-time Libraries and Header Files

Note that some of the following run-time libraries are provided in both shared and archive versions.

Header files for these libraries are located at /opt/aCC/include*.

For ## substitute 32 or 64 as appropriate.

• Standard C++ Library
  • /usr/lib/hpux##/libstd.so -- shared version
  • /usr/lib/hpux##/libstd.a -- archive version
  • /usr/lib/hpux##/libstd_v2.so -- shared version -AA
  • /usr/lib/hpux##/libstd_v2.a -- archive version -AA

• Tools.h++ Foundation Class Library
  • /usr/lib/hpux##/librwtool.so -- 32 bit shared version
  • /usr/lib/hpux##/librwtool.a -- 32 bit archive version

• HP aC++ Run-time Support Library
  • /usr/lib/hpux##/libCsup.so -- shared version
  • /usr/lib/hpux##/libCsup.a -- archive version

• IOStream Library
  • /usr/lib/hpux##/libstream.so -- shared version
  • /usr/lib/hpux##/libstream.a -- archive version