Using Mapfiles 191 | HP UX Software Transition Kit (STK) manual

The shl_get and shl_get_r Routines	175
Syntax	175
Parameters	175
Return Value	176
Description	176
Example	176
The shl_gethandle and shl_gethandle_r Routines	177
Syntax	177
Parameters	177
Return Value	177
Description	177
Example	177
The shl_definesym Routine	177
Syntax	178
Parameters	178
Return Value	178
Description	178
The shl_getsymbols Routine	178
Syntax	178
Parameters	179
Return Value	179
The shl_symbol Structure	180
show_symbols - Display Shared Library Symbols	180
show_all - Use show_symbols to Show All Symbols	181
The shl_unload Routine	182
Syntax	182
Parameters	182
Return Value	182
Description	182
Usage	182
The shl_unload Routine Returning ETXTBSY	183
Dynamic Loader Compatibility Warnings	183
Unsupported Shared Library Management Routines	183
Unsupported Shared Library Management Flags	183
8 Writing and Generating Position-Independent Code	185
What is a Relocatable Object Code?	185
What is a Absolute Object Code?	185
What is a Position-Independent Code?	186
Generating Position-Independent Code	186
PIC Requirements for Compilers and Assembly Code	187
Long Calls	188
Long Branches and Switch Tables	188
Assigned GOTO Statements	188
Literal References	188
Global and Static Variable References	189
Procedure Labels	189
9 Using Mapfiles	191
Controlling Mapfiles with the -k Option	191
Changing Mapfiles with -k filename and +nodefaultmap	191
Mapfile Example: Using -k mapfile and +nodefaultmap	191
Simple Mapfile	193
Default HP-UX 11.0 Release Mapfile	193
Defining Syntax for Mapfile Directives	195
Defining Mapfile Segment Declarations	196

10 Contents

Image 10

HP UX Software Transition Kit (STK) manual Writing and Generating Position-Independent Code 185, Using Mapfiles 191

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 Related Information Document conventions and symbolsIntended Audience 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 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 Changing the Default Library Search Path with -Wl, -L Using the Compiler to LinkExample Using -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 -L Using $ORIGINAugmenting the Default Linker Search Path with +origin 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 Exporting Symbols from main with -E Exporting Symbols with +eeEmitting debug information in a separate file Example Using -h Hiding Symbols from Export with +hideallsymbolsHiding Symbols with -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 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 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 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 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 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 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 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 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 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 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 Y.o Using the +ESlit/+Olit=all Option to ccMaking Shared Libraries Non-Writable 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 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 Relying on Undocumented Linker Behavior Switching from Archive to Shared LibrariesSpecifying a Version Date Version Control Absolute Virtual AddressesStack Usage 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 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 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 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 Using dlerror to get diagnostic information Dlerror RoutineDlsym Routine 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 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 Parameters Shlload Shared Library Management RoutinesShlload Routine Shlload routine explicitly loads a library Enomem Shlload Example Shlload UsageLoadlib Function to Load a Shared Library 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 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 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 Mapfile Example Using -k mapfile and +nodefaultmap Changing Mapfiles with -k filename and +nodefaultmapControlling Mapfiles with the -k Option 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 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 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