HP-UX Linker and Libraries Users Guide
Page
Contents
Contents
Linker Tools for PA-RISC Systems
Creating and Using Libraries
Linker 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 symbols
Intended 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 Example
Overview
Compiling Programs on HP-UX An Example
Looking Inside a Compiler
What is an Object File?
External References
Compiler-Linker Interaction
Local Definitions
Global Definitions
Cc Entering Link editor
Crt0.o Startup File
Linking Programs on HP-UX
Linker uses four startup files
A.out File
Magic Numbers PA-RISC only
Programs Entry Point
File Permissions
32-bit Mode Magic Number Linker Options
Library Naming Conventions Default Libraries Link Order
Linking with Libraries
Link Order
Default Libraries
Default Library Search Path
Library Naming Conventions
Binding Routines to a Program
Deferred Binding is the Default
Running 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 Link
Changing the Default Library Search Path with -Wl, -L
Renaming the Output File with -o
Passing Linker Options from the Compiler Command with -Wl
Example Using -Wl
Getting Verbose Output with
Overriding the Default Linker Search Path with Lpath
Using Linker Commands
Suppressing 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 $ORIGIN
Augmenting the Default Linker Search Path with -L
Restricted Shared Library Binding with -B restricted
Changing the Default Shared Library Binding with -B
Example Using -B immediate
Nonfatal Shared Library Binding with -B nonfatal
Shared Library Binding with -B nodelete
Direct Shared Library Binding with -B direct
Shared 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 symbolic
Example 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 -a
Example Using -a
Choosing Archive or Shared Libraries with -a
Linking Archived Libraries with -noshared
Exporting Symbols with +e
Example Using +e
When to use -h versus +e
Emitting debug information in a separate file
Exporting Symbols with +ee
Exporting Symbols from main with -E
Tips on Using -h
Hiding Symbols from Export with +hideallsymbols
Hiding Symbols with -h
Example Using -h
Hiding and Exporting Symbols when Creating an a.out File
Hiding and Exporting Symbols When Building a Shared Library
Hiding Symbols when Combining .o Files with the -r Option
Syntax of the +b option is
Not Recording Link Time Paths with +nodefaultrapth
Moving 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 Shlibpath
Ignoring 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 equivalent
Controlling Archive Library Loading with +noforceload
Passing Linker Options in a file with -c
Specifying Libraries with -l and -l
Flagging Unsatisfied Symbols with +noallowunsats
Using the -l option
Example Using -l
Controlling Output from the Unwind Table with +strip unwind
Using the IPF Linker with +compat or +std
Using 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 +std
Linking 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 +protect
Creating 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 chatr1
Linker toolset for Itanium-Based systems
Options to change various attributes
+b flag
+as mode
Immediate
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 stderr
Symbol
Viewing Library Dependencies with ldd1
Listing Dynamic Libraries with pldd1
Example 3 Using the ldd command
Parameter
Printing a Stack Trace with pstack1
Options 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 size1
Reducing 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 ltrace1
Finding 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 Compatibility
PA-RISC Architectures and Their System Models
+nosrcpos
+objdebug mode
This section describes the PA64 mode linker options
PA64 Mode Linker Options
Linker-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 Extension
System Library Location
Statically-bound programs archive-bound programs
Creating Archive Libraries Creating Shared Libraries
Using Libraries on HP-UX
Overview 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 Time
What 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 Command
Replacing, Adding, and Deleting an Object Module
Replacing or Adding an Object Module
Archive Library Location IPF
Using /usr/lib and /usr/lib/pa2064
Using /usr/local/lib or /usr/contrib/lib
Creating Shared Libraries
Comparing +z and +Z
Example Using +z
Creating 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 Library
Shared Library Location IPF
Improving Shared Library Performance
Ldpreload Example
Consider a case where a.out has the following dependents
That is, a.out is built with commands like these
Bit Behavior
Symbol resolution order for the user libraries is
Ldpreload Example PA-RISC
Out -- libA.sl -- libC.sl -- libD.sl -- libB.sl
Placing Frequently-Called Routines Together
Using Profile-Based Optimization on Shared Libraries
Exporting Only the Required Symbols
None
Using the +ESlit/+Olit=all Option to cc
Making Shared Libraries Non-Writable
Y.o
Building Filtered Shared Libraries
+condrodata Command-Line Option
Using Filtered Shared Libraries 32-bit Mode Only
Initializers
Run time behavior of filtered shared libraries
Function Level Versioning
When to Use Shared Library Versioning
Version Control with Shared Libraries
Library-Level Versioning
How to Use Library-Level Versioning
Maintaining Old Versions of Library Modules
+h Option and Internal Names
File System Links to Shared Libraries
Creating a New, Incompatible Version of the Library
Version Number Compiler Directive
Using shlload3X with Library-Level Versioning
Then set up the corresponding file system links
Intra-Library Versioning PA-RISC only
$SHLIBVERSION date
Shared Library Dependencies and Version Control
Adding New Versions to a Shared Library
#pragma Hpshlibversion date
Specifying a Version Date
Switching from Archive to Shared Libraries
Relying on Undocumented Linker Behavior
Debugger Limitations
Absolute Virtual Addresses
Stack Usage
Version Control
Profiling Limitations
Using the chroot Command with Shared Libraries
Summary 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 Semantics
Link-Time Symbol Resolution in Shared Libraries
PA-32 linker toolset produces
Resolution of Unsatisfied Shared Library References
If 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 Link
You 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 found
Linker issues the following error message
Above example, if you type
Dl* routines for shared library management
Shared Library Management Routine Summaries
Dlopen Routines Summary
Do not mix use of the shlload and dlopen APIs
Routines for shared library management
Related Files and Commands
Shared Library Header Files
Shlload Routine Summary
Init/Fini Style Initializers
Using Shared Libraries with cc and ld Options
Initializers for Shared Libraries
Styles of Initializers
Init and Fini Usage Example
Using Init/Fini Initializers
HP-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 Initializers
Declaring the Initializer with the +I Option
Example An Initializer for Each Library
Accessing Initializers Addresses
Initializer 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 testlib2
Dlopen 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
Errors
Dlerrno Routine
Dlgetfileinfo Routine
Shared Library Management Routines
Dlsym Routine
Dlerror Routine
Using dlerror to get diagnostic information
Handle
Usage
Descsize
Dlget Routine
Index
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 pathname
Dlclose Routine
Dlclose routine closes a shared library
Dladdr Routine
Using dlclose to unload a shared library
Dladdr routine gets the symbolic information for an address
Diagnostics
Dlmodadd Routine
Using dladdr to get the symbolic information for an address
Following example shows how to use dladdr to
Dlgetmodinfo Routine
Dlmodremove removes information registered using dlmodadd
Dlmodremove Routine
Following example shows how to use dlgetmodinfo
Using dlgetmodinfo
Shlload routine explicitly loads a library
Shlload Shared Library Management Routines
Shlload Routine
Parameters
Enomem
Loadlib Function to Load a Shared Library
Shlload Usage
Shlload Example
Dynamicpath Modifier
Bindnonfatal Modifier
Bindverbose Modifier
Bindfirst Modifier
Bindbreadthfirst Modifier
LibG together and correctly resolves all symbols
Shlfindsym Routine
Bindtogether Modifier
Same as Typedata
Shlt handle
Handle = 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 Structure
Showsymbols 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 Symbols
Showall program shown above was compiled with the command
Fpumodelstorage
Shlunload Routine
Shlunload Routine Returning Etxtbsy
Dynamic Loader Compatibility Warnings
Unsupported 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 Tables
Long 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 +nodefaultmap
Mapfile Example Using -k mapfile and +nodefaultmap
Using Mapfiles
Following directives show how a simple mapfile would appear
Default HP-UX 11.0 Release Mapfile
IPF 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 Declarations
Segment Flags
Attributes and their values
Section attributes and their valid values are as follows
Defining Mapfile Section Mapping Directives
Mapfile Segment Declaration Examples
Mapping Input Sections to Segments
Placement of Segments in an Executable
Internal 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 +Oprocelim
Incompatibilities with other Options
Profile-Based Optimization PA-RISC
How to Use PBO
Using PBO
When 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 File
Specifying 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 Rates
Profile-Based Optimization Itanium
Incremental Linking
Any of the padding spaces have been exhausted
Performance
Using Incremental Linking Options
Archive 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 Aliasing
Using fastbind
Improving Shared Library Start-Up Time with fastbind
Example 21 Example
How to Tell if fastbind Information is Current
Invoking the fastbind Tool
Invoking fastbind from the Linker
See the fastbind1 man
Removing fastbind Information from a File
Turning off fastbind at Run Time
Example 22 Example
Glossary
SOM
PBO
Rpath