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
Using Mapfiles 191
Writing and Generating Position-Independent Code 185
Improving Your Application Performance 202
Glossary 225
Document conventions and symbols
Intended Audience
Related Information
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 Example
Overview
Compiling Programs on HP-UX An Example
What is an Object File?
Looking Inside a Compiler
Compiler-Linker Interaction
Local Definitions
Global Definitions
External References
Cc Entering Link editor
Linking Programs on HP-UX
Crt0.o Startup File
A.out File
Magic Numbers PA-RISC only
Programs Entry Point
Linker uses four startup files
32-bit Mode Magic Number Linker Options
Library Naming Conventions Default Libraries Link Order
Linking with Libraries
File Permissions
Default Libraries
Default Library Search Path
Library Naming Conventions
Link Order
Deferred Binding is the Default
Running the Program
Loading Programs exec
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 Link
Changing the Default Library Search Path with -Wl, -L
Passing Linker Options from the Compiler Command with -Wl
Example Using -Wl
Getting Verbose Output with
Renaming the Output File with -o
Using Linker Commands
Suppressing the Link-Edit Phase with -c
Linking 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 +origin
Using $ORIGIN
Augmenting the Default Linker Search Path with -L
Changing the Default Shared Library Binding with -B
Example Using -B immediate
Nonfatal 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 group
Lazydirect Shared Library Binding with -B lazydirect
Shared Library Binding with -B nodelete
Improving Shared Library Performance with -B symbolic
Example Using -B symbolic
Comparing -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 -a
Choosing Archive or Shared Libraries with -a
Linking Shared Libraries with -dynamic
Exporting Symbols with +e
Example Using +e
When to use -h versus +e
Linking Archived Libraries with -noshared
Emitting debug information in a separate file
Exporting Symbols with +ee
Exporting Symbols from main with -E
Hiding Symbols from Export with +hideallsymbols
Hiding Symbols with -h
Example Using -h
Tips on 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
Not Recording Link Time Paths with +nodefaultrapth
Moving Libraries after Linking with +b
Specifying 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 +noenvvar
Specifying a Path List with +s and Shlibpath
For more information Path List
Thereafter, the following commands would be equivalent
Controlling Archive Library Loading with +noforceload
Passing Linker Options in a file with -c
Passing Linker Options with Ldopts
Flagging Unsatisfied Symbols with +noallowunsats
Using the -l option
Example Using -l
Specifying Libraries with -l and -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
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 +compat
Changing 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 executable
Allocating 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 systems
Options to change various attributes
Libname
+as mode
Immediate
Deferred
+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
Symbol
Viewing 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 files
Level with level
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 size1
Reducing Storage Space with strip1
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 lorder1
Example 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
Versions of PA-RISC architecture
PA-RISC 2.0 Compatibility
PA-RISC Architectures and Their System Models
+objdebug mode
+nosrcpos
This section describes the PA64 mode linker options
PA64 Mode Linker Options
Linker-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 Extension
System Library Location
Statically-bound programs archive-bound programs
Using Libraries on HP-UX
Overview of Shared and Archive Libraries
Creating Libraries on HP-UX
Creating Archive Libraries Creating Shared Libraries
What are Archive Libraries?
Out files
Dynamic Loader
Default Behavior When Searching for Libraries at Run Time
What 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
Summary of Keys to the ar1 Command
Replacing, Adding, and Deleting an Object Module
Replacing or Adding an Object Module
Deleting an Object Module
Using /usr/lib and /usr/lib/pa2064
Using /usr/local/lib or /usr/contrib/lib
Creating Shared Libraries
Archive Library Location IPF
Example Using +z
Creating Position-Independent Code PIC
Creating 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 IPF
Improving Shared Library Performance
Incompatible Changes to a Shared Library
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
Using the +ESlit/+Olit=all Option to cc
Making Shared Libraries Non-Writable
Y.o
None
Building Filtered Shared Libraries
+condrodata Command-Line Option
Using Filtered Shared Libraries 32-bit Mode Only
Run time behavior of filtered shared libraries
Initializers
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
Using shlload3X with Library-Level Versioning
Then set up the corresponding file system links
Intra-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
Specifying a Version Date
Switching from Archive to Shared Libraries
Relying on Undocumented Linker Behavior
Absolute Virtual Addresses
Stack Usage
Version Control
Debugger Limitations
Profiling Limitations
Using the chroot Command with Shared Libraries
Summary 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 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
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 Link
You can use chatr+s to enable a.out in file1 and file2
Linking Libraries with +b pathlist
When linking main.o, the link order is 1. ./libbar.so found
Linker issues the following error message
Above example, if you type
Instead
Shared Library Management Routine Summaries
Dlopen Routines Summary
Do not mix use of the shlload and dlopen APIs
Dl* routines for shared library management
Related Files and Commands
Shared Library Header Files
Shlload Routine Summary
Routines for shared library management
Using Shared Libraries with cc and ld Options
Initializers for Shared Libraries
Styles of Initializers
Init/Fini Style Initializers
Init and Fini Usage Example
Using Init/Fini Initializers
HP-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 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
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 Routines
Dlopen 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 Routine
Dlgetfileinfo Routine
Multithread Usage
Shared Library Management Routines
Dlsym Routine
Dlerror Routine
Using dlerror to get diagnostic information
Usage
Handle
Dlget Routine
Index
Desc
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 Routine
Dlclose routine closes a shared library
Int dlclosevoid *handle
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
Using dlgetmodinfo
Following example shows how to use dlgetmodinfo
Shlload Shared Library Management Routines
Shlload Routine
Parameters
Shlload routine explicitly loads a library
Enomem
Loadlib Function to Load a Shared Library
Shlload Usage
Shlload Example
Bindnonfatal Modifier
Bindverbose Modifier
Bindfirst Modifier
Dynamicpath Modifier
LibG together and correctly resolves all symbols
Shlfindsym Routine
Bindtogether Modifier
Bindbreadthfirst Modifier
Shlt handle
Handle = Null
Shlfindsym&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 Symbols
Members of the shlsymbol structure are defined as follows
Example 17 shlgetsymbols Example
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
Shlunload Routine
Fpumodelstorage
Dynamic Loader Compatibility Warnings
Unsupported Shared Library Management Routines
Unsupported 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 Calls
Assigned Goto Statements
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 +nodefaultmap
Mapfile Example Using -k mapfile and +nodefaultmap
Using Mapfiles
Default HP-UX 11.0 Release Mapfile
IPF 32-bit linker uses the following default mapfile
Simple Mapfile
Following directives show how a simple mapfile would appear
Using Mapfiles
Defining Syntax for Mapfile Directives
Defining Mapfile Segment Declarations
Segment Flags
Attributes and their values
Segment declarations support the following segment flags
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
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 +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
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 +df
Specifying 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 Itanium
Incremental Linking
Example 19 Examples
Any of the padding spaces have been exhausted
Using Incremental Linking Options
Archive Library Processing
Shared 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 fastbind
Improving Shared Library Start-Up Time with fastbind
Example 20 Example
How to Tell if fastbind Information is Current
Invoking the fastbind Tool
Invoking fastbind from the Linker
Example 21 Example
Removing fastbind Information from a File
Turning off fastbind at Run Time
Example 22 Example
See the fastbind1 man
Glossary
SOM
PBO
Rpath