Kenwood HP 9000 The dlopen Routines Summary

Chapter 6 197

Shared Library Management Routines

Shared Library Management Routine Summaries

Except for shl_get and shl_gethandle, all these routines are thread

safe.

These routines are described in the shl_load(3x) man page.

The dlopen Routines Summary

The dlopen family of shared library management routines is available

only for the 64-bit linker.

The dlopen family of routines use Unix SVR4 shared library

mechanisms.

Use the following dl* routines for shared library management:

shl_definesym Adds a new symbol to the global shared library

symbol table.

shl_getsymbols Returns a list of symbols in a shared library.

shl_unload and

cxxshl_load Unload a shared library and a C++ shared

library, respectively. They have the same

syntax.

Routine Action

dlopen Loads a shared library. This routine does

breadth-ﬁrst searching.

dlerror Prints the last error message recorded by dld.

dlsym Gets the address of a symbol in a shared library.

dlget Returns information on a loaded module.

dlmodinfo Returns information about a loaded module.

dlgetname Retrieves the name of a loaded module given a

load model descriptor.

dlclose Unloads a shared library previously loaded by

dlopen().

Routine Action

Contents

Main Legal Notices Page Page Page Page Page Page Page Page Page Page Page Page Preface Printing History Page Page Page 1 What's New in Recent Releases Page PA-RISC Changes in Hardware Compatibility PA-RISC 2.0 Compatibility PA-RISC Architectures and Their System Models 64-bit Mode Linker Toolset Compatibility with De Facto Industry Standards 64-bit Mode ELF Object File Format New Features for 64-bit Mode Linking 64-bit Mode Linker Options 64-bit Mode Linker-dened Symbols Page 64-bit Mode Link-time Differences Page 64-bit Mode Run Time Differences Page Changes in Future Releases Online Help for Linker and Libraries Accessing Help with ld +help Accessing Help with the HP CDE Front Panel Accessing Help with the dthelpview Command Accessing Help with the charhelp Command Page 2 What Happens When You Compile and Link a Program Compiling Programs on HP-UX: An Example Page Looking inside a Compiler Page What is an Object File? Local Denitions Global Denitions External References Compiler-Linker Interaction Linking Programs on HP-UX The crt0.o Startup File The Program's Entry Point The a.out File Magic Numbers File Permissions Linking with Libraries Library Naming Conventions Default Libraries The Default Library Search Path Link Order Running the Program Loading Programs: exec Binding Routines to a Program Deferred Binding is the Default Linker Thread-Safe Features 3 Linker Tasks Page Using the Compiler to Link Changing the Default Library Search Path with -Wl, -L Example Using -Wl, -L Getting Verbose Output with -v Passing Linker Options from the Compiler Command with -Wl Example Using -Wl Renaming the Output File with -o Specifying Libraries with -l Linking with the crt0.o Startup File in 32-bit mode Suppressing the Link-Edit Phase with -c Page Using Linker commands Linking with the 32-bit crt0.o Startup File Changing the Default Library Search Path with -L and LPATH Overriding the Default Linker Search Path with LPATH 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 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. Page Choosing Archive or Shared Libraries with -a Example Using -a Dynamic Linking with -A and -R Overview of Dynamic Linking Step 1: Determine how much space is required to load the module. Step 2: Allocate the required memory and obtain its starting address. Step 3: Link the module from the running application. Step 4: Get information about the module's text, data, and bss segments from the module's header. Step 5: Read the text and data into the allocated space. Step 6: Clear (zero out) the bss segment. Step 7: Flush the text from the data cache before executing code from the loaded module. Step 8: Get the addresses of routines and data that are referenced in the module. An Example Program The Build Environment. Source for dynprog. Chapter 3 71 le1.o and le2.o . Output of dynprog . dynload.c . The alloc_load_space Function . Page 74 Chapter 3 The dyn_load Function . Page Page Page 78 Chapter 3 The ush_cache Function . Exporting Symbols with +e Example Using +e When to use -h versus +e Exporting Symbols with +ee Exporting Symbols from main with -E Hiding Symbols with -h Example Using -h Tips on Using -h Hiding and Exporting Symbols When Building a Hiding Symbols When Combining .o Files with the -r Option Hiding and Exporting Symbols When Creating an a.out File Moving Libraries after Linking with +b Specifying a Path List with +b The Path List Moving Libraries After Linking with +s and SHLIB_PATH Specifying a Path List with +s and SHLIB_PATH For More Information: Passing Linker Options in a le with -c Passing Linker Options with LDOPTS Specifying Libraries with -l and l: Specifying Libraries (-l) Using the -l: option Example Using -l: Stripping Symbol Table Information from the Output File with -s and -x Using 64-bit Mode Linker Options Using the 64-bit Mode Linker with +compat or +std Using the Linker with +compat for Compatibility Mode Using the 64-bit Linker with +std for Standard Mode Page Linking Shared Libraries with -dynamic Linking Archived Libraries with -noshared Controlling Archive Library Loading with +[no]forceload Flagging Unsatised Symbols with +[no]allowunsats Hiding Symbols from export with +hideallsymbols Changing Maples with -k and +nodefaultmap Ignoring Dynamic Path Environment Variables with +noenvvar Linking in 64-bit Mode with +std Linking in 32-bit Mode Style with +compat Controlling Output from the Unwind Table with +stripwind Selecting Verbose Output with +vtype Linking with the 64-bit crt0.o Startup File Linker Compatibility Warnings Linking to Archive Libraries with Unsatised Symbols Page Page 4 Linker Tools Changing a Program's Attributes with chatr(1) Using chatr for 32-bit Program Attributes Using chatr for 64-bit Program Attributes Page Viewing Symbols in an Object le with nm(1) Page Page Page Viewing the Contents of an Object File with elfdump(1) Page Viewing library dependencies with ldd(1) Page Viewing the Size of Object File Elements with size(1) Reducing Storage Space with strip(1) Page Improving Program Start-up with fastbind(1) Page Finding Object Library Ordering Relationships with lorder(1) 5 Creating and Using Libraries Overview of Shared and Archive Libraries Page Page What are Archive Libraries? Example What are Shared Libraries? The Dynamic Loader dld.sl Default Behavior When Searching for Libraries at Run Time Caution on Using Dynamic Library Searching Example Program Comparing Shared and Archive Libraries Page Page Creating Archive Libraries Overview of Creating an Archive Library Contents of an Archive File Example of Creating an Archive Library Replacing, Adding, and Deleting an Object Module Replacing or Adding an Object Module Deleting an Object Module Summary of Keys to the ar(1) Command Useful ar Keys crt0.o Archive Library Location Using /usr/lib and /usr/lib/pa20_64 Using /usr/local/lib or /usr/contrib/lib Creating Shared Libraries Creating Position-Independent Code (PIC) Example Using +z Comparing +z and +Z Compiler Support for +z and +Z Creating the Shared Library with ld Shared Library Dependencies The Order in Which Libraries Are Loaded (Load Graph) For 32-bit mode. For 64-bit mode. Placing Loaded Libraries in the Search List Updating a Shared Library Incompatible Changes to a Shared Library Shared Library Location Improving Shared Library Performance Using Prole-Based Optimization on Shared Libraries Exporting Only the Required Symbols Placing Frequently-Called Routines Together Page Making Shared Libraries Non-Writable Using the +ESlit Option to cc Version Control with Shared Libraries When to Use Shared Library Versioning Maintaining Old Versions of Library Modules Library-Level Versioning How to Use Library-Level Versioning Creating a New, Incompatible Version of the Library Migrating an Existing Library to Use Library-Level Versioning The +h Option and Internal Names File System Links to Shared Libraries Page Using shl_load(3X) with Library-Level Versioning Intra-Library Versioning The Version Number Compiler Directive Shared Library Dependencies and Version Control Adding New Versions to a Shared Library Specifying a Version Date Switching from Archive to Shared Libraries Library Path Names Relying on Undocumented Linker Behavior Absolute Virtual Addresses Stack Usage Version Control Debugger Limitations Using the chroot Command with Shared Libraries Proling Limitations Summary of HP-UX Libraries Page Caution When Mixing Shared and Archive Libraries Example 1: Unsatised Symbols Page Page Example 2: Using shl_load(3X) Page Page Page Example 3: Hidden Denitions Page Page Page Summary of Mixing Shared and Archive Libraries Using Shared Libraries in 64-bit mode Internal Name Processing Dynamic Path Searching for Shared Libraries Shared Library Symbol Binding Semantics Link-Time Symbol Resolution in Shared Libraries Page Resolution of Unsatised Shared Library References Promotion of Uninitialized Global Data Items Symbol Searching in Dependent Libraries Page Mixed Mode Shared Libraries Page 64-bit Mode Library Examples Library Example: Creating a 64-bit Mode Compatibility Mode Shared Library. Library Example: Creating a 64-bit Standard Mode Library example: 64-bit Mode Dynamic Path Searching 188 Chapter 5 Creating and Using Libraries Using Shared Libraries in 64-bit mode Library Example: 64-bit Mode Compatibility Mode Link You can usechatr +s to enable a.out in file1 and file2: Chapter 5 189 Creating and Using Libraries Using Shared Libraries in 64-bit mode Library Example: Using 64-bit Mode Compatibility and Standard Shared Libraries Comparing Breadth-rst and Depth-rst Search in 64-bit Mode For the following libraries, with the dependencies: Library Example: Using RPATH with Standard Mode Linking Libraries with +b pathlist Library Example: Linking to Libraries with +b path_list in 64-bit Mode. Library Example: Linking to Libraries with +b path_list in 32-bit Mode. Page Page 6 Shared Library Management Routines Shared Library Management Routine Summaries The shl_load Routine Summary The dlopen Routines Summary Related Files and Commands Shared Library Header Files Using Shared Libraries with cc and ld Options Initializers for Shared Libraries Styles of Initializers HP-UX-10.X-Style Initializers Init/Fini Style Initializers Init. Fini. 32-bit Mode Initializers Using HP-UX 10.X Style Initializers Declaring the Initializer with the +I Option Order of Execution of Multiple Initializers . Initializer Syntax Accessing Initializers' Addresses . Example: An Initializer for Each Library Page Example: A Common Initializer for Multiple Libraries 208 Chapter 6 Initializers for Shared Libraries C Source for _INITIALIZER (le init.c) Chapter 6 209 Initializers for Shared Libraries C Source for libtwo.sl Here are the commands used to build these libraries: The following is an example program that loads these two libraries: C Source for testlib2 64-bit Mode Initializers Init and Fini Usage Example Ordering Within an Executable or Shared Library Ordering Among Executables and Shared Libraries Page The shl_load Shared Library Management Routines The shl_load and cxxshl_load Routines Page Page shl_load Usage shl_load Example BIND_NONFATAL Modier BIND_VERBOSE Modier BIND_FIRST Modier DYNAMIC_PATH Modier BIND_NOSTART Modier BIND_RESTRICTED Modier BIND_TOGETHER Modier BIND_BREADTH_FIRST Modier The shl_ndsym Routine Page Page shl_ndsym Example The shl_get and shl_get_r Routines Page Page Page The shl_gethandle and shl_gethandle_r Routines The shl_denesym Routine The shl_getsymbols Routine Page Page The shl_symbol Structure shl_getsymbols Example Page Page The shl_unload and cxxshl_unload Routines Usage The dlopen Shared Library Management Routines The dlopen Routine Page Page Page The dlerror Routine The dlsym Routine Usage Examples The dlget Routine Chapter 6 249 The dlopen Shared Library Management Routines The dlmodinfo Routine Retrieves information about a loaded module (program or shared library). Page Page The dlgetname Routine The dlclose Routine Page Page Dynamic Loader Compatibility Warnings Unsupported Shared Library Management Routines Unsupported Shared Library Management Flags Page Page 7 Position-Independent Code What Is Relocatable Object Code? What is Absolute Object Code? What Is Position-Independent Code? Generating Position-Independent Code For More Information: PIC Requirements for Compilers and Assembly Code Long Calls Long Branches and Switch Tables Assigned GOTO Statements Literal References Global and Static Variable References Procedure Labels Page 8 Ways to Improve Performance Linker Optimizations Invoking Linker Optimizations from the Compile Line See Also: Incompatibilities with other Options Unused Procedure Elimination with +Oprocelim Complete Executables Incomplete Executables Shared Libraries Relocatable Objects Affects on Symbolic Debugging Options to Improve TLB Hit Rates Prole-Based Optimization General Information about PBO Using PBO When to Use PBO How to Use PBO A Simple Example Instrumenting (+I/-I) The Startup File icrt0.o The -I Linker Option Code Generation from I-SOMs Proling Choosing Input Data The ow.data File Storing Prole Information for Multiple Programs Sharing the ow.data File Among Multiple Processes Forking an Instrumented Application Optimizing Based on Prole Data (+P/-P) The -P Linker Option Using The ow.data File Specifying a Different ow.data File with +df Specifying a Different ow.data with FLOW_DATA Interaction between FLOW_DATA and +df Specifying a Different Program Name (+pgm) Selecting an Optimization Level with PBO Using PBO to Optimize Shared Libraries Using PBO with ld -r Restrictions and Limitations of PBO Temporary Files Source Code Changes and PBO Prole-Based Optimization (PBO) and High-Level Optimization (HLO) Example . I-SOM File Restrictions ld . nm . ar . strip . Compatibility with 9.0 PBO Page Improving Shared Library Start-Up Time with fastbind Using fastbind Invoking the fastbind Tool Invoking fastbind from the Linker How to Tell if fastbind Information is Current Removing fastbind Information from a File Turning off fastbind at Run Time For More Information: A Using Maples Controlling Maples with the -k Option Maple Example: Using -k lename (without +nodefaultmap Option): Appendix A 297 Controlling Maples with the -k Option 298 Appendix A Changing Maples with -k lename and +nodefaultmap Changing Maples with -k lename and +nodefaultmap Maple Example: Using -k maple and +nodefaultmap Appendix A 299 Changing Maples with -k lename and +nodefaultmap Simple Maple Appendix A 301 Default HP-UX Release 11.0 Maple Default HP-UX Release 11.0 Maple The HP-UX Release 11.0 64-bit linker uses the following default maple: Page Dening Syntax for Maple Directives Dening Maple Segment Declarations Segment Flags Page Maple Segment Declaration Examples Dening Maple Section Mapping Directives Page Internal Map Structure Placement of Segments in an Executable Mapping Input Sections to Segments Page Page Interaction between User-dened and Default Maple Directives Maple Option Error Messages Fatal Errors Warnings