HP UX Software Transition Kit (STK) guide

•BIND_RESTRICTED

•BIND_TOGETHER

•BIND_NONFATAL

•BIND_VERBOSE

•DYNAMIC_PATH

The following shl_findsym() flags may become unsupported in a future release:

•TYPE_PROCEDURE

•TYPE_DATA

•TYPE_STORAGE

NOTE: The IPF PA-64 mode linker does not support the TYPE_STORAGE flag.

184 Shared Library Management Routines

Image 184

HP UX Software Transition Kit (STK) manual Typeprocedure Typedata Typestorage

Contents

HP-UX Linker and Libraries Users Guide Page Contents Contents Linker Tools for Itanium-Based Systems Creating and Using LibrariesLinker Tools for PA-RISC 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 Document conventions and symbols Intended AudienceRelated Information Document conventions HP Encourages Your Comments Document Organization Using Mapfiles Improving Your Application Performance Overview Compiling Programs on HP-UX An ExampleThis chapter addresses the following Compiling Programs on HP-UX An Example What is an Object File? Looking Inside a Compiler Compiler-Linker Interaction Local DefinitionsGlobal Definitions External References Cc Entering Link editor Linking Programs on HP-UX Crt0.o Startup File A.out File Magic Numbers PA-RISC onlyPrograms Entry Point Linker uses four startup files 32-bit Mode Magic Number Linker Options Library Naming Conventions Default Libraries Link OrderLinking with Libraries File Permissions Default Libraries Default Library Search PathLibrary Naming Conventions Link Order Deferred Binding is the Default Running the ProgramLoading Programs exec Binding Routines to a Program Linker Thread-Safe Features Determining How to Link Programs or Libraries Linker Tasks Changing the Default Library Search Path with -Wl, -L Using the Compiler to LinkExample Using -Wl, -L Passing Linker Options from the Compiler Command with -Wl Example Using -WlGetting Verbose Output with Renaming the Output File with -o Using Linker Commands Suppressing the Link-Edit Phase with -cLinking with the crt0.o Startup File in 32-bit mode PA-RISC Overriding the Default Linker Search Path with Lpath Augmenting the Default Linker Search Path with -L Using $ORIGINAugmenting the Default Linker Search Path with +origin Changing the Default Shared Library Binding with -B Example Using -B immediateNonfatal Shared Library Binding with -B nonfatal Restricted Shared Library Binding with -B restricted Direct Shared Library Binding with -B direct Shared Library Binding with -B groupLazydirect Shared Library Binding with -B lazydirect Shared Library Binding with -B nodelete Improving Shared Library Performance with -B symbolic Example Using -B symbolicComparing -B symbolic with -h and +e Case 1 Building a Shared Library with -B symbolic Or export the convertrtn symbol Symbol Hidden in a Shared Library Option Settings to -a Example Using -aChoosing Archive or Shared Libraries with -a Linking Shared Libraries with -dynamic Exporting Symbols with +e Example Using +eWhen to use -h versus +e Linking Archived Libraries with -noshared Exporting Symbols from main with -E Exporting Symbols with +eeEmitting debug information in a separate file Hiding Symbols from Export with +hideallsymbols Hiding Symbols with -hExample Using -h Tips on Using -h Hiding Symbols when Combining .o Files with the -r Option Hiding and Exporting Symbols When Building a Shared LibraryHiding and Exporting Symbols when Creating an a.out File Not Recording Link Time Paths with +nodefaultrapth Moving Libraries after Linking with +bSpecifying a Path List with +b Syntax of the +b option is Path List Moving Libraries After Linking with +s and Shlibpath Ignoring Dynamic Path Environment Variables with +noenvvarSpecifying a Path List with +s and Shlibpath For more information Path List Thereafter, the following commands would be equivalent Controlling Archive Library Loading with +noforceloadPassing Linker Options in a file with -c Passing Linker Options with Ldopts Flagging Unsatisfied Symbols with +noallowunsats Using the -l optionExample Using -l Specifying Libraries with -l and -l Using the Linker with +compat for Compatibility Mode Using the IPF Linker with +compat or +stdControlling Output from the Unwind Table with +strip unwind Using the Linker with +std for Standard Mode Dynamicflag is passed to shlload Linking in PA-64 Mode with +std Linking in PA-32 Mode with +compatChanging Mapfiles with -k and +nodefaultmap Selecting Verbose Output with +vtype All Turning on the linkage table protection with +protect Creating read-only text segment in Mpas executableAllocating Storage for Uninitialized Data with +nobss Initializing Floating Point Environment with +FP Flags that are supported Turn Off Linker Warnings with -w Changing a Programs Attributes with chatr1 Linker toolset for Itanium-Based systemsOptions to change various attributes Libname +as mode ImmediateDeferred +b flag Enabledisable +protect disable+md flag +memcheck Viewing Symbols in an Object file with nm1 Format Viewing the Contents of an Object File with elfdump1 +linkmap +linkmapbss+linkmapfile +objdebug Symbol resolution problems to stderr SymbolViewing Library Dependencies with ldd1 +T num2 Example 3 Using the ldd command Listing Dynamic Libraries with pldd1 Printing a Stack Trace with pstack1 Options to view information specified filesLevel with level Parameter Example 5 Calling pstack with a process id Example 6 Calling pstack with -level option Linker Tools for Itanium-Based Systems Reducing Storage Space with strip1 Viewing the Size of Object File Elements with size1Example 9 Calling pstack with special argument Improving Program Start-up with fastbind1 Options to control the amount of information stripped Tracing Inter-Module Procedure Calls with ltrace1 Finding Object Library Ordering Relationships with lorder1Example 10 Example 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 For the 64-bit only syntax +dz+si +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 PA-RISC Architectures and Their System Models PA-RISC 2.0 CompatibilityVersions of PA-RISC architecture +objdebug mode +nosrcpos Linker-Defined Symbols PA64 Mode Linker OptionsThis section describes the PA64 mode linker options 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 System Library Location System Libraries Locations and Library Name ExtensionShared Library Extension suffix Statically-bound programs archive-bound programs Using Libraries on HP-UX Overview of Shared and Archive LibrariesCreating Libraries on HP-UX Creating Archive Libraries Creating Shared Libraries What are Archive Libraries? Out files What are Shared Libraries? Default Behavior When Searching for Libraries at Run TimeDynamic Loader 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 Summary of Keys to the ar1 Command Replacing, Adding, and Deleting an Object ModuleReplacing or Adding an Object Module Deleting an Object Module Using /usr/lib and /usr/lib/pa2064 Using /usr/local/lib or /usr/contrib/libCreating Shared Libraries Archive Library Location IPF Example Using +z Creating Position-Independent Code PICCreating the Shared Library with ld Comparing +z and +Z Shared Library Dependencies Order in Which Libraries are Loaded Load Graph Placing Loaded Libraries in the Search List LibD Updating a Shared Library Shared Library Location IPFImproving Shared Library Performance Incompatible Changes to a Shared Library That is, a.out is built with commands like these Consider a case where a.out has the following dependentsLdpreload Example Ldpreload Example PA-RISC Symbol resolution order for the user libraries isBit Behavior Out -- libA.sl -- libC.sl -- libD.sl -- libB.sl Exporting Only the Required Symbols Using Profile-Based Optimization on Shared LibrariesPlacing Frequently-Called Routines Together Using the +ESlit/+Olit=all Option to cc Making Shared Libraries Non-WritableY.o None Using Filtered Shared Libraries 32-bit Mode Only +condrodata Command-Line OptionBuilding Filtered Shared Libraries Run time behavior of filtered shared libraries Initializers Version Control with Shared Libraries When to Use Shared Library VersioningFunction Level Versioning Maintaining Old Versions of Library Modules How to Use Library-Level VersioningLibrary-Level Versioning Creating a New, Incompatible Version of the Library File System Links to Shared Libraries+h Option and Internal Names Using shlload3X with Library-Level Versioning Then set up the corresponding file system linksIntra-Library Versioning PA-RISC only Version Number Compiler Directive Shared Library Dependencies and Version Control Adding New Versions to a Shared Library#pragma Hpshlibversion date $SHLIBVERSION date Relying on Undocumented Linker Behavior Switching from Archive to Shared LibrariesSpecifying a Version Date Absolute Virtual Addresses Stack UsageVersion Control Debugger Limitations Summary of HP-UX Libraries Using the chroot Command with Shared LibrariesProfiling Limitations 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 Link-Time Symbol Resolution in Shared Libraries Shared Library Symbol Binding SemanticsDynamic Path Searching for Shared Libraries If these files are compiled and linked as Resolution of Unsatisfied Shared Library ReferencesPA-32 linker toolset produces 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 You can use chatr+s to enable a.out in file1 and file2 Library Example IPF Compatibility Mode LinkFor the following libraries with dependencies Linking Libraries with +b pathlist When linking main.o, the link order is 1. ./libbar.so found Linker issues the following error messageAbove example, if you type Instead Shared Library Management Routine Summaries Dlopen Routines SummaryDo not mix use of the shlload and dlopen APIs Dl* routines for shared library management Related Files and Commands Shared Library Header FilesShlload Routine Summary Routines for shared library management Using Shared Libraries with cc and ld Options Initializers for Shared LibrariesStyles of Initializers Init/Fini Style Initializers HP-UX-10.X Style Initializers Using Init/Fini InitializersInit and Fini Usage Example 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 Declaring the Initializer with the +I Option Using HP-UX 10.X Style InitializersOrder of Execution of Multiple Initializers Initializer Syntax Accessing Initializers AddressesExample An Initializer for Each Library 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 Following is the command to create the executable testlib2 Dlopen Shared Library Management RoutinesDlopen Routine 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 Errors Dlerrno RoutineDlgetfileinfo Routine Multithread Usage Shared Library Management Routines Using dlerror to get diagnostic information Dlerror RoutineDlsym Routine Usage Handle Dlget Routine IndexDesc Descsize Using dlget to retrieve information about loaded modules Dlmodinfo Routine Using dlmodinfo to retrieve information about a load module Dlgetname Routine Using dlgetname to retrieve pathname Dlclose RoutineDlclose routine closes a shared library Int dlclosevoid *handle Dladdr routine gets the symbolic information for an address Using dlclose to unload a shared libraryDladdr Routine Diagnostics Following example shows how to use dladdr to Using dladdr to get the symbolic information for an addressDlmodadd Routine Dlmodremove Routine Dlmodremove removes information registered using dlmodaddDlgetmodinfo Routine Using dlgetmodinfo Following example shows how to use dlgetmodinfo Shlload Shared Library Management Routines Shlload RoutineParameters Shlload routine explicitly loads a library Enomem Shlload Example Shlload UsageLoadlib Function to Load a Shared Library Bindnonfatal Modifier Bindverbose ModifierBindfirst Modifier Dynamicpath Modifier LibG together and correctly resolves all symbols Shlfindsym RoutineBindtogether Modifier Bindbreadthfirst Modifier Shlt handle Handle = NullShlfindsym&handle,foo Same as Typedata Shlfindsym Example Shlget and shlgetr Routines Index Example Shlgethandle and shlgethandler Routines Shldefinesym Routine Shlgetsymbols Routine Typeprocedure Shlsymbol Structure Showsymbols Display Shared Library SymbolsMembers of the shlsymbol structure are defined as follows Example 17 shlgetsymbols Example Showall program shown above was compiled with the command Showall Use showsymbols to Show All SymbolsOutput produced by running this program is shown below Shlunload Routine Fpumodelstorage Dynamic Loader Compatibility Warnings Unsupported Shared Library Management RoutinesUnsupported Shared Library Management Flags 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 Long Branches and Switch Tables Long CallsAssigned Goto Statements Literal References Procedure Labels Global and Static Variable References Writing and Generating Position-Independent Code Mapfile Example Using -k mapfile and +nodefaultmap Changing Mapfiles with -k filename and +nodefaultmapControlling Mapfiles with the -k Option Using Mapfiles Default HP-UX 11.0 Release Mapfile IPF 32-bit linker uses the following default mapfileSimple Mapfile Following directives show how a simple mapfile would appear Using Mapfiles Defining Syntax for Mapfile Directives Defining Mapfile Segment Declarations Segment FlagsAttributes and their values Segment declarations support the following segment flags Mapfile Segment Declaration Examples Defining Mapfile Section Mapping DirectivesSection attributes and their valid values are as follows Internal Map Structure Placement of Segments in an ExecutableMapping Input Sections to Segments Map Structure Mapfile Option Error Messages Fatal Errors Mapfile Option Error Messages Linker Optimizations Invoking Linker Optimizations from the Compile Line Incompatibilities with other Options Unused Procedure Elimination with +OprocelimComplete Executables Profile-Based Optimization PA-RISC When to Use PBO Using PBOHow to Use PBO Instrumenting +I/-I -I Linker Option Startup File icrt0.oCode Generation from I-SOMs Profiling Building Portable Code with Linker Optimization Storing Profile Information for Multiple Programs Optimizing Based on Profile Data +P/-P -P Linker Option Using The flow.data File Specifying a Different flow.data File with +dfSpecifying a Different flow.data with Flowdata 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 Options to Improve TLB Hit Rates Profile-Based Optimization ItaniumIncremental Linking Example 19 Examples Any of the padding spaces have been exhausted Using Incremental Linking Options Archive Library ProcessingShared 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 Performance with Function Symbol Aliasing Using fastbindImproving Shared Library Start-Up Time with fastbind Example 20 Example How to Tell if fastbind Information is Current Invoking the fastbind ToolInvoking fastbind from the Linker Example 21 Example Removing fastbind Information from a File Turning off fastbind at Run TimeExample 22 Example See the fastbind1 man Glossary SOM PBO Rpath