HP UX Software Transition Kit (STK) specification

© Copyright 2011 Hewlett-Packard Development Company L.P.

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. UNIX is a registered trademark of The Open Group.

Itanium® is a trademark of Intel Corporation in the U.S. and other countries.

Image 2

HP UX Software Transition Kit (STK) manual

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