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

• Closing a Library with the +inst_close Option (for libraries that contain templates)
• Mixing C++ with Other Languages

HP aC++ Libraries

Standards Based Libraries

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

HP C++ (cfront) Compatibility Libraries

• IOStream Library
• Standard Components 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
• Incompatibilities Between the Library and the Standard
• 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

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

#include <algorithm>

• 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 onw 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

#include <complex>

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

Containers

#include <bitset> 
#include <deque> 
#include <ul> 
#include <map> for map and multimap 
#include <queue> for queue and priority_queue 
#include <set> for set and multiset 
#include <stack> 
#include <vector>

• 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

Exception Class

#include <exception>

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

Function Adaptors

#include <functional>

• 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

#include <functional>

• 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

#include <numeric>

• 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

#include <iterator>

• 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

#include <iterator>

• 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

#include <iterator>

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

Memory Handling Primitives

#include <memory>

• 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

#include <memory>

• 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

#include <limits>

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

Stream Iterators

#include <iterator>

Stream iterators allow generic algorithms to be used directly on streams.

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

String Library

#include <string>

• 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

#include <utility>

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

Utility Operators

#include <utility>

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

Incompatibilities Between the Library and the Standard

If you want to use "multiplies" in your code, to be compatible with the ANSI/ISO C++ International Standard, use a conditional compilation flag on the aCC command line.

For example, for the following program, compile with the command line:

aCC -D__HPACC_USING_MULTIPLIES_IN_FUNCTIONAL test.c

// test.c
int times;                   //user defined variable
#include <functional>
// multiplies can be used in

int main() {}
// end of test.c

So, if you have old source that uses "times" in header functional and also new source that uses "multiplies", the sources cannot be mixed. Mixing the two sources would constitute a non-conforming program, and the old and new sources may or may not link.

If your code uses the old name "times," and you want to continue to use the now non-standard "times" function object, you do not need to do anything to compile the old source.

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

For More Information

• Migration Considerations when Using Libraries

Standard Components Library

The library is not standards based. It is strongly recommended that you use the capabilities of the Standard C++ Library.

For More Information

• Migration Considerations when Using Libraries.

Linking to C++ Libraries

• /usr/lib/libCsup.so (the HP aC++ run-time support library)
• /usr/lib/libstd.so (standard C++ library)
• /usr/lib/libstream.so(iostream library)
• /opt/aCC/lib/cpprt0.o (for an executable)
• /opt/aCC/lib/shlrt0.o (for a shared library)
• /opt/aCC/lib/cxxshl.o (routines used when creating archived executables with the +A option; used instead of libdld.so)
• /opt/langtools/lib/crt0.o (start-up routines)
• /usr/lib/libc.so (the HP-UX system library)
• /usr/lib/libdld.so (routines for managing shared libraries)
• /usr/lib/libcl.so (routines for exception handling)
• /usr/lib/libm.so (math library)

Linking with Shared or Archive Libraries

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

Example

aCC -c +z util.C

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 +z Strings.C Arrays.C

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

aCC draw_shapes.C libshape.so

Linking Archive or Shared Libraries

NOTE: You can use the +A option if you are using only archive libraries to create a completely archived executable.

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}

-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 with the +z or +Z option, 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

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:

#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

Adding New Versions to a Shared Library

For more information refer to the HP-UX Online Linker and Libraries User's Guide.

Standard HP-UX Libraries and Header Files

Location of Standard HP-UX Header Files

Using Header Files

#include <filename.h>

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

Example of Using a Standard Header File

#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/lbin/assigner -- assigner


implements the automatic instantiation algorithm

• /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

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

• Standard C++ Library
  • /usr/lib/hpux32/libstd.so -- 32-bit shared version
  • /usr/lib/hpux32/libstd.a -- 32-bit archive version
  • /usr/lib/hpux64/libstd.so -- 64-bit shared version
  • /usr/lib/hpux64/libstd.a -- 64-bit archive version
• HP aC++ Run-time Support Library
  • /usr/lib/hpux##/libCsup.so
  • /usr/lib/hpux##/libstd.so and libstd_v2.so
  • /usr/lib/hpux##/libstd_v2.so and librwtool_v2.so
  • /usr/lib/hpux##/libstream.so
  • Libraries in /usr/include/hpux32 or /usr/include/hpux64.
    (Where ## is 32 or 64 - provided as part of the HP-UX core system).
• IOStream Library
  • /usr/lib/hpux32/libstream.so -- 32-bit shared version
  • /usr/lib/hpux32/libstream.a -- 32-bit archive version
  • /usr/lib/hpux64/libstream.so -- 64-bit shared version
  • /usr/lib/hpux64/libstream.a -- 64-bit archive version