Contents of an Archive File | HP UX Software Transition Kit (STK)

•“Replacing, Adding, and Deleting an Object Module” (page 97)

•“Summary of Keys to the ar(1) Command” (page 97)

•“Archive Library Location (IPF) ” (page 98)

Overview of Creating an Archive Library

To create an archive library:

1.Create one or more object files containing relocatable object code. Typically, each object file contains one function, procedure, or data structure, but an object file can have multiple routines and data.

2.Combine these object files into a single archive library file with the ar command. Invoke ar with the r key.

("Keys" are like command line options, except that they do not require a preceding -.)

Figure 9 (page 95) summarizes the procedure for creating archive libraries from three C source files (file1.c, file2.c, and file3.c). The process is identical for other languages, except that you use a different compiler.

Figure 9 Creating an Archive Library

Contents of an Archive File

An archive library file consists of four main components:

1.A header string, "!<arch>\n", identifying the file as an archive file created by ar (\n represents the newline character)

2.A symbol table, used by the linker and other commands to find the location, size, and other information for each routine or data item contained in the library

3.An optional string table used by the linker to store file names that are greater than 15 bytes long (only created if a long file name is encountered)

4.Object modules, one for each object file specified on the ar command line

To see what object modules a library contains, run ar with the t key, which displays a table of contents. For example, to view the "table of contents" for libm.a:

$ ar t /usr/lib/hpux32/libm.a

//Run ar with the t key.

Creating Archive Libraries

95

Image 95

HP UX Software Transition Kit (STK) manual Overview of Creating an Archive Library, Contents of an Archive File

Contents

HP-UX Linker and Libraries Users Guide Page Contents Contents Linker Tools for PA-RISC Systems Creating and Using LibrariesLinker Tools for Itanium-Based Systems Contents Shared Library Management Routines 136 Contents Contents Writing and Generating Position-Independent Code 185 Using Mapfiles 191 Improving Your Application Performance 202 Glossary 225 Document conventions Document conventions and symbolsIntended Audience Related Information Document Organization HP Encourages Your Comments Improving Your Application Performance Using Mapfiles This chapter addresses the following Compiling Programs on HP-UX An ExampleOverview Compiling Programs on HP-UX An Example Looking Inside a Compiler What is an Object File? External References Compiler-Linker InteractionLocal Definitions Global Definitions Cc Entering Link editor Crt0.o Startup File Linking Programs on HP-UX Linker uses four startup files A.out FileMagic Numbers PA-RISC only Programs Entry Point File Permissions 32-bit Mode Magic Number Linker OptionsLibrary Naming Conventions Default Libraries Link Order Linking with Libraries Link Order Default LibrariesDefault Library Search Path Library Naming Conventions Binding Routines to a Program Deferred Binding is the DefaultRunning the Program Loading Programs exec Linker Thread-Safe Features Determining How to Link Programs or Libraries Linker Tasks Example Using -Wl, -L Using the Compiler to LinkChanging the Default Library Search Path with -Wl, -L Renaming the Output File with -o Passing Linker Options from the Compiler Command with -WlExample Using -Wl Getting Verbose Output with Overriding the Default Linker Search Path with Lpath Using Linker CommandsSuppressing the Link-Edit Phase with -c Linking with the crt0.o Startup File in 32-bit mode PA-RISC Augmenting the Default Linker Search Path with +origin Using $ORIGINAugmenting the Default Linker Search Path with -L Restricted Shared Library Binding with -B restricted Changing the Default Shared Library Binding with -BExample Using -B immediate Nonfatal Shared Library Binding with -B nonfatal Shared Library Binding with -B nodelete Direct Shared Library Binding with -B directShared Library Binding with -B group Lazydirect Shared Library Binding with -B lazydirect Case 1 Building a Shared Library with -B symbolic Improving Shared Library Performance with -B symbolicExample Using -B symbolic Comparing -B symbolic with -h and +e Symbol Hidden in a Shared Library Or export the convertrtn symbol Linking Shared Libraries with -dynamic Option Settings to -aExample Using -a Choosing Archive or Shared Libraries with -a Linking Archived Libraries with -noshared Exporting Symbols with +eExample Using +e When to use -h versus +e Emitting debug information in a separate file Exporting Symbols with +eeExporting Symbols from main with -E Tips on Using -h Hiding Symbols from Export with +hideallsymbolsHiding Symbols with -h Example Using -h Hiding and Exporting Symbols when Creating an a.out File Hiding and Exporting Symbols When Building a Shared LibraryHiding Symbols when Combining .o Files with the -r Option Syntax of the +b option is Not Recording Link Time Paths with +nodefaultrapthMoving Libraries after Linking with +b Specifying a Path List with +b Path List For more information Path List Moving Libraries After Linking with +s and ShlibpathIgnoring Dynamic Path Environment Variables with +noenvvar Specifying a Path List with +s and Shlibpath Passing Linker Options with Ldopts Thereafter, the following commands would be equivalentControlling Archive Library Loading with +noforceload Passing Linker Options in a file with -c Specifying Libraries with -l and -l Flagging Unsatisfied Symbols with +noallowunsatsUsing the -l option Example Using -l Controlling Output from the Unwind Table with +strip unwind Using the IPF Linker with +compat or +stdUsing the Linker with +compat for Compatibility Mode Dynamicflag is passed to shlload Using the Linker with +std for Standard Mode Selecting Verbose Output with +vtype Linking in PA-64 Mode with +stdLinking in PA-32 Mode with +compat Changing Mapfiles with -k and +nodefaultmap All Initializing Floating Point Environment with +FP Turning on the linkage table protection with +protectCreating read-only text segment in Mpas executable Allocating Storage for Uninitialized Data with +nobss Flags that are supported Turn Off Linker Warnings with -w Libname Changing a Programs Attributes with chatr1Linker toolset for Itanium-Based systems Options to change various attributes +b flag +as modeImmediate Deferred +memcheck Enabledisable+protect disable +md flag Viewing Symbols in an Object file with nm1 Format Viewing the Contents of an Object File with elfdump1 +objdebug +linkmap+linkmapbss +linkmapfile +T num2 Symbol resolution problems to stderrSymbol Viewing Library Dependencies with ldd1 Listing Dynamic Libraries with pldd1 Example 3 Using the ldd command Parameter Printing a Stack Trace with pstack1Options to view information specified files Level with level Example 6 Calling pstack with -level option Example 5 Calling pstack with a process id Linker Tools for Itanium-Based Systems Example 9 Calling pstack with special argument Viewing the Size of Object File Elements with size1Reducing Storage Space with strip1 Options to control the amount of information stripped Improving Program Start-up with fastbind1 Example 11 Examples Tracing Inter-Module Procedure Calls with ltrace1Finding Object Library Ordering Relationships with lorder1 Example 10 Example $/usr/ccs/bin/ltrace ./a.out -a arg1 arg2 arg3 .. argn Using chatr for 32-bit Program Attributes For the 32-bit compatible syntax Using chatr for 64-bit Program Attributes +sa For the 64-bit only syntax+dz +si $THISSHORTBSS$ Example 12 Viewing Symbols in an Object file with nm1 To view Optional list of symbol resolution problems to stderr Example 13 Viewing library dependencies with ldd1 To display Before you ran fastbind on it Example 14 Improving Program Start-up with fastbind1 $ ar cr library `lorder *.o tsort` ELF Object File Format PA-RISC Changes in Hardware Compatibility Versions of PA-RISC architecture PA-RISC 2.0 CompatibilityPA-RISC Architectures and Their System Models +nosrcpos +objdebug mode This section describes the PA64 mode linker options PA64 Mode Linker OptionsLinker-Defined Symbols Dynamic Path Searching for Shared Libraries Symbol names Runpath Perform 32-bit link PA-64, IPF 64-bit mode example Symbol Searching in Dependent Libraries Shared Library Extension suffix System Libraries Locations and Library Name ExtensionSystem Library Location Statically-bound programs archive-bound programs Creating Archive Libraries Creating Shared Libraries Using Libraries on HP-UXOverview of Shared and Archive Libraries Creating Libraries on HP-UX Out files What are Archive Libraries? Dynamic Loader Default Behavior When Searching for Libraries at Run TimeWhat are Shared Libraries? Running setuid Programs Example Program Comparing Shared and Archive Libraries Two Processes Sharing libc Profiling Shared Libraries with gprof1 Creating Archive Libraries Overview of Creating an Archive Library Contents of an Archive File Example of Creating an Archive Library Deleting an Object Module Summary of Keys to the ar1 CommandReplacing, Adding, and Deleting an Object Module Replacing or Adding an Object Module Archive Library Location IPF Using /usr/lib and /usr/lib/pa2064Using /usr/local/lib or /usr/contrib/lib Creating Shared Libraries Comparing +z and +Z Example Using +zCreating Position-Independent Code PIC Creating the Shared Library with ld Order in Which Libraries are Loaded Load Graph Shared Library Dependencies LibD Placing Loaded Libraries in the Search List Incompatible Changes to a Shared Library Updating a Shared LibraryShared Library Location IPF Improving Shared Library Performance Ldpreload Example Consider a case where a.out has the following dependentsThat is, a.out is built with commands like these Bit Behavior Symbol resolution order for the user libraries isLdpreload Example PA-RISC Out -- libA.sl -- libC.sl -- libD.sl -- libB.sl Placing Frequently-Called Routines Together Using Profile-Based Optimization on Shared LibrariesExporting Only the Required Symbols None Using the +ESlit/+Olit=all Option to ccMaking Shared Libraries Non-Writable Y.o Building Filtered Shared Libraries +condrodata Command-Line OptionUsing Filtered Shared Libraries 32-bit Mode Only Initializers Run time behavior of filtered shared libraries Function Level Versioning When to Use Shared Library VersioningVersion Control with Shared Libraries Library-Level Versioning How to Use Library-Level VersioningMaintaining Old Versions of Library Modules +h Option and Internal Names File System Links to Shared LibrariesCreating a New, Incompatible Version of the Library Version Number Compiler Directive Using shlload3X with Library-Level VersioningThen set up the corresponding file system links Intra-Library Versioning PA-RISC only $SHLIBVERSION date Shared Library Dependencies and Version ControlAdding New Versions to a Shared Library #pragma Hpshlibversion date Specifying a Version Date Switching from Archive to Shared LibrariesRelying on Undocumented Linker Behavior Debugger Limitations Absolute Virtual AddressesStack Usage Version Control Profiling Limitations Using the chroot Command with Shared LibrariesSummary of HP-UX Libraries Example 1 Unsatisfied Symbols Compiling Example 1 Unsatisfied Symbols Example 1 Unsatisfied Symbols Modifying a Function Example 1 Unsatisfied Symbols Creating the Executable Example 1 Unsatisfied Symbols Problem of Unsatisfied Symbol Example 2 Using shlload3X Example 2 Using shlload3X Creating the Executable Example 3 Hidden Definitions Example 2 Using shlload3X Rebuilding the Shared Library Example 3 Hidden Definitions Compiling Example 3 Hidden Definitions Modifying a Function Using Shared Libraries in Default Mode Dthpneeded entry Internal Name Processing Dynamic Path Searching for Shared Libraries Shared Library Symbol Binding SemanticsLink-Time Symbol Resolution in Shared Libraries PA-32 linker toolset produces Resolution of Unsatisfied Shared Library ReferencesIf these files are compiled and linked as Promotion of Uninitialized Global Data Items Symbol Searching in Dependent Libraries Search Order of Dependent Libraries Mixed Mode Shared Libraries Libfile4.so IPF Library Examples Library example IPF Dynamic Path Searching Following example builds a standard mode library For the following libraries with dependencies Library Example IPF Compatibility Mode LinkYou can use chatr+s to enable a.out in file1 and file2 Linking Libraries with +b pathlist Instead When linking main.o, the link order is 1. ./libbar.so foundLinker issues the following error message Above example, if you type Dl* routines for shared library management Shared Library Management Routine SummariesDlopen Routines Summary Do not mix use of the shlload and dlopen APIs Routines for shared library management Related Files and CommandsShared Library Header Files Shlload Routine Summary Init/Fini Style Initializers Using Shared Libraries with cc and ld OptionsInitializers for Shared Libraries Styles of Initializers Init and Fini Usage Example Using Init/Fini InitializersHP-UX-10.X Style Initializers Source for lib1.so file lib1.c lib1 Finis from any .o files used in my64bit.a Ordering Within an Executable or Shared Library Ordering Among Executables and Shared Libraries Order of Execution of Multiple Initializers Using HP-UX 10.X Style InitializersDeclaring the Initializer with the +I Option Example An Initializer for Each Library Accessing Initializers AddressesInitializer Syntax Source for testlib.c #include stdio.h #include dl.h main Source for Initializer file init.c #include dl.h Example a Common Initializer for Multiple Libraries Following are the commands used to build these libraries Syntax Following is the command to create the executable testlib2Dlopen Shared Library Management Routines Dlopen Routine Parameters Return Values Description Dlopen Shared Library Management Routines Using dlopen to load a shared library Synopsis Dlsetlibpath Routine Using dlsetlibpath to set the dynamic search path Rtldflagdisablestdpath Rtldflagdisablecwdpath Multithread Usage ErrorsDlerrno Routine Dlgetfileinfo Routine Shared Library Management Routines Dlsym Routine Dlerror RoutineUsing dlerror to get diagnostic information Handle Usage Descsize Dlget RoutineIndex Desc Dlmodinfo Routine Using dlget to retrieve information about loaded modules Dlgetname Routine Using dlmodinfo to retrieve information about a load module Int dlclosevoid *handle Using dlgetname to retrieve pathnameDlclose Routine Dlclose routine closes a shared library Dladdr Routine Using dlclose to unload a shared libraryDladdr routine gets the symbolic information for an address Diagnostics Dlmodadd Routine Using dladdr to get the symbolic information for an addressFollowing example shows how to use dladdr to Dlgetmodinfo Routine Dlmodremove removes information registered using dlmodaddDlmodremove Routine Following example shows how to use dlgetmodinfo Using dlgetmodinfo Shlload routine explicitly loads a library Shlload Shared Library Management RoutinesShlload Routine Parameters Enomem Loadlib Function to Load a Shared Library Shlload UsageShlload Example Dynamicpath Modifier Bindnonfatal ModifierBindverbose Modifier Bindfirst Modifier Bindbreadthfirst Modifier LibG together and correctly resolves all symbolsShlfindsym Routine Bindtogether Modifier Same as Typedata Shlt handleHandle = Null Shlfindsym&handle,foo Shlfindsym Example Index Shlget and shlgetr Routines Example Shldefinesym Routine Shlgethandle and shlgethandler Routines Shlgetsymbols Routine Typeprocedure Example 17 shlgetsymbols Example Shlsymbol StructureShowsymbols Display Shared Library Symbols Members of the shlsymbol structure are defined as follows Output produced by running this program is shown below Showall Use showsymbols to Show All SymbolsShowall program shown above was compiled with the command Fpumodelstorage Shlunload Routine Shlunload Routine Returning Etxtbsy Dynamic Loader Compatibility WarningsUnsupported Shared Library Management Routines Unsupported Shared Library Management Flags Typeprocedure Typedata Typestorage What is a Absolute Object Code? What is a Relocatable Object Code? Generating Position-Independent Code What is a Position-Independent Code? PIC Requirements for Compilers and Assembly Code Literal References Long Branches and Switch TablesLong Calls Assigned Goto Statements Global and Static Variable References Procedure Labels Writing and Generating Position-Independent Code Controlling Mapfiles with the -k Option Changing Mapfiles with -k filename and +nodefaultmapMapfile Example Using -k mapfile and +nodefaultmap Using Mapfiles Following directives show how a simple mapfile would appear Default HP-UX 11.0 Release MapfileIPF 32-bit linker uses the following default mapfile Simple Mapfile Using Mapfiles Defining Syntax for Mapfile Directives Segment declarations support the following segment flags Defining Mapfile Segment DeclarationsSegment Flags Attributes and their values Section attributes and their valid values are as follows Defining Mapfile Section Mapping DirectivesMapfile Segment Declaration Examples Mapping Input Sections to Segments Placement of Segments in an ExecutableInternal Map Structure Map Structure Fatal Errors Mapfile Option Error Messages Mapfile Option Error Messages Invoking Linker Optimizations from the Compile Line Linker Optimizations Complete Executables Unused Procedure Elimination with +OprocelimIncompatibilities with other Options Profile-Based Optimization PA-RISC How to Use PBO Using PBOWhen to Use PBO Instrumenting +I/-I Code Generation from I-SOMs Startup File icrt0.o-I Linker Option Building Portable Code with Linker Optimization Profiling Storing Profile Information for Multiple Programs -P Linker Option Optimizing Based on Profile Data +P/-P Interaction between Flowdata and +df Using The flow.data FileSpecifying a Different flow.data File with +df Specifying a Different flow.data with Flowdata Selecting an Optimization Level with PBO Using PBO to Optimize Shared Libraries Using PBO with ld -r Restrictions and Limitations of PBO Size Essentially empty Compatibility with 9.0 PBO Example 19 Examples Options to Improve TLB Hit RatesProfile-Based Optimization Itanium Incremental Linking Any of the padding spaces have been exhausted Performance Using Incremental Linking OptionsArchive Library Processing Shared Library Processing Improving Performance with the Global Symbol Table Reusing Compiled Object Files PA-RISC Improving Performance by Optimizing the Hash Table Size Example 20 Example Improving Performance with Function Symbol AliasingUsing fastbind Improving Shared Library Start-Up Time with fastbind Example 21 Example How to Tell if fastbind Information is CurrentInvoking the fastbind Tool Invoking fastbind from the Linker See the fastbind1 man Removing fastbind Information from a FileTurning off fastbind at Run Time Example 22 Example Glossary SOM PBO Rpath