Kenwood HP 9000 User Manual

HP-UX Linker and Libraries User's Guide

HP 9000 Computers

B2355-90655

November 1997

Legal Notices

The information contained in this document is subject to change without notice.

Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and ﬁtness for a particular purpose. Hewlett-Packard

shall not be liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material.

rights are reserved. Reproduction, adaptation, or translation without prior written permission is prohibited, except as allowed under the copyright laws.

Corporate Ofﬁces:

Hewlett-Packard Co. 3000 Hanover St. Palo Alto, CA 94304

Use, duplication or disclosure by the U.S. Government Department of Defense is subject to restrictions as set forth in paragraph (b)(3)(ii) of the Rights in Technical Data and Software clause in FAR 52.227-7013.

Rights for non-DOD U.S. Government Departments and Agencies are as set forth in FAR 52.227-19(c)(1,2).

Use of this manual and ﬂexible disc(s), compact disc(s), or tape cartridge(s) supplied for this pack is restricted to this product only. Additional copies of the programs may be made for security and back-up purposes only. Resale of the programs in their present form or with alterations, is expressly prohibited.

A copy of the speciﬁc warranty terms applicable to your Hewlett-Packard product and replacement parts can be obtained from your local Sales and Service Ofﬁce.

UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited.

© Copyright 1979, 1980, 1983, 1985-1990 Regents of the University of California. This software is based in part on the Fourth Berkeley Software Distribution under license from the Regents of the University of California.

This document has been reproduced and modiﬁed with the permission of the Regents of the University of Colorado, a body corporate.

PostScript is a trademark of Adobe Systems, Inc. Intel is a registered trademark and Intel 80386 is a trademark of Intel

Window System is a trademark of the Massachussetts Institute of Technology.

MS-DOS and Microsoft are U.S. registered trademarks of Microsoft Corporation.

OSF/Motif is a trademark of the Open Software Foundation, Inc. in the U.S. and other countries. Certiﬁcation for conformance with OSF/Motif user environment pending.

Contents

Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Printing History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

1. What's New in Recent Releases

PA-RISC Changes in Hardware Compatibility . . . . . . . . . . . . . . . . . . . .21

PA-RISC 2.0 Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

PA-RISC Architectures and Their System Models. . . . . . . . . . . . . . . .22

64-bit Mode Linker Toolset Compatibility with De Facto Industry

Standards. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

64-bit Mode ELF Object File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

New Features for 64-bit Mode Linking. . . . . . . . . . . . . . . . . . . . . . . . . . .25

64-bit Mode Linker Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

64-bit Mode Linker-deﬁned Symbols. . . . . . . . . . . . . . . . . . . . . . . . . . .26

64-bit Mode Link-time Differences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

64-bit Mode Run Time Differences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30

Changes in Future Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32

Online Help for Linker and Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . .33

Accessing Help with ld +help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33

Accessing Help with the HP CDE Front Panel. . . . . . . . . . . . . . . . . . .33

Accessing Help with the dthelpview Command . . . . . . . . . . . . . . . . . .33

Accessing Help with the charhelp Command. . . . . . . . . . . . . . . . . . . .33

2. What Happens When You Compile and Link a Program

Compiling Programs on HP-UX:

An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

Looking “inside” a Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

What is an Object File? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

Local Deﬁnitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

Contents

Global Deﬁnitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

External References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Compiler-Linker Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Linking Programs on HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

The crt0.o Startup File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

The a.out File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

File Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Linking with Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Library Naming Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Default Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

The Default Library Search Path. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Link Order. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Running the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Loading Programs: exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Binding Routines to a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Deferred Binding is the Default. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Linker Thread-Safe Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

3. Linker Tasks

Using the Compiler to Link. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Changing the Default Library Search Path with -Wl, -L . . . . . . . . . . 53

Getting Verbose Output with -v. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Passing Linker Options from the Compiler Command with -Wl . . . . 54

Renaming the Output File with -o. . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Specifying Libraries with -l . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Suppressing the Link-Edit Phase with -c . . . . . . . . . . . . . . . . . . . . . . 55

Using Linker commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Linking with the 32-bit crt0.o Startup File. . . . . . . . . . . . . . . . . . . . . 57

Changing the Default Library Search Path with -L and LPATH. . . . 57

Contents

Changing the Default Shared Library Binding with -B. . . . . . . . . . . .58

Improving Shared Library Performance with -B symbolic . . . . . . . . .60

Choosing Archive or Shared Libraries with -a . . . . . . . . . . . . . . . . . . .63

Dynamic Linking with -A and -R. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65

Exporting Symbols with +e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79

Exporting Symbols with +ee . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

Exporting Symbols from main with -E . . . . . . . . . . . . . . . . . . . . . . . . .81

Hiding Symbols with -h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

Moving Libraries after Linking with +b . . . . . . . . . . . . . . . . . . . . . . . .84

Moving Libraries After Linking with +s and SHLIB_PATH . . . . . . . .86

Passing Linker Options in a ﬁle with -c . . . . . . . . . . . . . . . . . . . . . . . .86

Passing Linker Options with LDOPTS. . . . . . . . . . . . . . . . . . . . . . . . .87

Specifying Libraries with -l and l:. . . . . . . . . . . . . . . . . . . . . . . . . . . . .87

Stripping Symbol Table Information from the Output File with -s and

-x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89

Using 64-bit Mode Linker Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90

Using the 64-bit Mode Linker with +compat or +std. . . . . . . . . . . . . .90

Linking Shared Libraries with -dynamic . . . . . . . . . . . . . . . . . . . . . . .93

Linking Archived Libraries with -noshared . . . . . . . . . . . . . . . . . . . . .93

Controlling Archive Library Loading with +[no]forceload. . . . . . . . . .93

Flagging Unsatisﬁed Symbols with +[no]allowunsats. . . . . . . . . . . . .94

Hiding Symbols from export with +hideallsymbols . . . . . . . . . . . . . . .95

Changing Mapﬁles with -k and +nodefaultmap. . . . . . . . . . . . . . . . . .95

Ignoring Dynamic Path Environment Variables with +noenvvar . . . .96

Linking in 64-bit Mode with +std . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96

Linking in 32-bit Mode Style with +compat . . . . . . . . . . . . . . . . . . . . .96

Controlling Output from the Unwind Table with +stripwind . . . . . . .96

Selecting Verbose Output with +vtype . . . . . . . . . . . . . . . . . . . . . . . . .97

Linking with the 64-bit crt0.o Startup File . . . . . . . . . . . . . . . . . . . . .98

Linker Compatibility Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99

Linking to Archive Libraries with Unsatisﬁed Symbols . . . . . . . . . .100

Contents

4. Linker Tools

Changing a Program's Attributes with chatr(1). . . . . . . . . . . . . . . . . . 104

Using chatr for 32-bit Program Attributes . . . . . . . . . . . . . . . . . . . . 104

Using chatr for 64-bit Program Attributes . . . . . . . . . . . . . . . . . . . . 105

Viewing Symbols in an Object ﬁle with nm(1) . . . . . . . . . . . . . . . . . . . 107

Viewing the Contents of an Object File with elfdump(1). . . . . . . . . . . 111

Viewing library dependencies with ldd(1). . . . . . . . . . . . . . . . . . . . . . . 113

Viewing the Size of Object File Elements with size(1). . . . . . . . . . . . . 115

Reducing Storage Space with strip(1). . . . . . . . . . . . . . . . . . . . . . . . . . 116

Improving Program Start-up with fastbind(1) . . . . . . . . . . . . . . . . . . . 118

Finding Object Library Ordering Relationships with lorder(1). . . . . . 120

5. Creating and Using Libraries

Overview of Shared and Archive Libraries. . . . . . . . . . . . . . . . . . . . . . 122

What are Archive Libraries? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

What are Shared Libraries? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

The Dynamic Loader dld.sl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Default Behavior When Searching for Libraries at Run Time. . . . . 127

Caution on Using Dynamic Library Searching. . . . . . . . . . . . . . . . . 127

Example Program Comparing Shared and Archive Libraries. . . . . . . 128

Shared Libraries with Debuggers, Proﬁlers, and Static Analysis. . . . 130

Creating Archive Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Overview of Creating an Archive Library . . . . . . . . . . . . . . . . . . . . . 131

Contents of an Archive File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Example of Creating an Archive Library. . . . . . . . . . . . . . . . . . . . . . 133

Replacing, Adding, and Deleting an Object Module . . . . . . . . . . . . . 134

Contents

Summary of Keys to the ar(1) Command . . . . . . . . . . . . . . . . . . . . . .135

crt0.o . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136

Archive Library Location. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136

Creating Shared Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138

Creating Position-Independent Code (PIC). . . . . . . . . . . . . . . . . . . . .138

Creating the Shared Library with ld. . . . . . . . . . . . . . . . . . . . . . . . . .139

Shared Library Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140

Updating a Shared Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144

Shared Library Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144

Improving Shared Library Performance. . . . . . . . . . . . . . . . . . . . . . .145

Version Control with Shared Libraries . . . . . . . . . . . . . . . . . . . . . . . . .149

When to Use Shared Library Versioning . . . . . . . . . . . . . . . . . . . . . .149

Maintaining Old Versions of Library Modules . . . . . . . . . . . . . . . . . .150

Library-Level Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150

Intra-Library Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154

Switching from Archive to Shared Libraries . . . . . . . . . . . . . . . . . . . . .158

Library Path Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158

Relying on Undocumented Linker Behavior. . . . . . . . . . . . . . . . . . . .158

Absolute Virtual Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159

Stack Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160

Version Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160

Debugger Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161

Using the chroot Command with Shared Libraries . . . . . . . . . . . . . .161

Proﬁling Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161

Summary of HP-UX Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162

Caution When Mixing Shared and Archive Libraries. . . . . . . . . . . . . .164

Example 1: Unsatisﬁed Symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . . .164

Example 2: Using shl_load(3X) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167

Example 3: Hidden Deﬁnitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171

Summary of Mixing Shared and Archive Libraries . . . . . . . . . . . . . .175

Contents

Using Shared Libraries in 64-bit mode. . . . . . . . . . . . . . . . . . . . . . . . . 176

Internal Name Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Dynamic Path Searching for Shared Libraries. . . . . . . . . . . . . . . . . 177

Shared Library Symbol Binding Semantics . . . . . . . . . . . . . . . . . . . 178

Mixed Mode Shared Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

64-bit Mode Library Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

6. Shared Library Management Routines

Shared Library Management Routine Summaries . . . . . . . . . . . . . . . 196

The shl_load Routine Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

The dlopen Routines Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Related Files and Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Shared Library Header Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Using Shared Libraries with cc and ld Options . . . . . . . . . . . . . . . . . . 200

Initializers for Shared Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Styles of Initializers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

32-bit Mode Initializers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

64-bit Mode Initializers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

The shl_load Shared Library Management Routines . . . . . . . . . . . . . 215

The shl_load and cxxshl_load Routines. . . . . . . . . . . . . . . . . . . . . . . 215

The shl_ﬁndsym Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

The shl_get and shl_get_r Routines. . . . . . . . . . . . . . . . . . . . . . . . . . 226

The shl_gethandle and shl_gethandle_r Routines . . . . . . . . . . . . . . 230

The shl_deﬁnesym Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

The shl_getsymbols Routine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

The shl_unload and cxxshl_unload Routines . . . . . . . . . . . . . . . . . . 238

The dlopen Shared Library Management Routines. . . . . . . . . . . . . . . 240

The dlopen Routine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

The dlerror Routine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Contents

The dlsym Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245

The dlget Routine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248

The dlmodinfo Routine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249

The dlgetname Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252

The dlclose Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253

Dynamic Loader Compatibility Warnings . . . . . . . . . . . . . . . . . . . . . . .256

Unsupported Shared Library Management Routines . . . . . . . . . . . .256

Unsupported Shared Library Management Flags . . . . . . . . . . . . . . .256

7. Position-Independent Code

What Is Relocatable Object Code? . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260

What is Absolute Object Code?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .261

What Is Position-Independent Code? . . . . . . . . . . . . . . . . . . . . . . . . . . .262

Generating Position-Independent Code . . . . . . . . . . . . . . . . . . . . . . . . .263

For More Information: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264

PIC Requirements for Compilers and Assembly Code. . . . . . . . . . . .264

Long Calls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265

Long Branches and Switch Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . .265

Assigned GOTO Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .266

Literal References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .266

Global and Static Variable References . . . . . . . . . . . . . . . . . . . . . . . .267

Procedure Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .267

8. Ways to Improve Performance

Linker Optimizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .270

Invoking Linker Optimizations from the Compile Line. . . . . . . . . . .270

Incompatibilities with other Options . . . . . . . . . . . . . . . . . . . . . . . . .271

Unused Procedure Elimination with +Oprocelim. . . . . . . . . . . . . . . .271

Options to Improve TLB Hit Rates. . . . . . . . . . . . . . . . . . . . . . . . . . . . .273

Contents

Proﬁle-Based Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

General Information about PBO . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Using PBO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

When to Use PBO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

How to Use PBO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Instrumenting (+I/-I). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Proﬁling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Optimizing Based on Proﬁle Data (+P/-P). . . . . . . . . . . . . . . . . . . . . 283

Selecting an Optimization Level with PBO. . . . . . . . . . . . . . . . . . . . 285

Using PBO to Optimize Shared Libraries . . . . . . . . . . . . . . . . . . . . . 286

Using PBO with ld -r . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Restrictions and Limitations of PBO. . . . . . . . . . . . . . . . . . . . . . . . . 288

Compatibility with 9.0 PBO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Improving Shared Library Start-Up Time with fastbind . . . . . . . . . . 293

Using fastbind. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Invoking the fastbind Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Invoking fastbind from the Linker. . . . . . . . . . . . . . . . . . . . . . . . . . . 294

How to Tell if fastbind Information is Current. . . . . . . . . . . . . . . . . 294

Removing fastbind Information from a File . . . . . . . . . . . . . . . . . . . 294

Turning off fastbind at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

For More Information: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

A. Using Mapﬁles

Controlling Mapﬁles with the -k Option. . . . . . . . . . . . . . . . . . . . . . . . 296

Mapﬁle Example: Using -k ﬁlename (without +nodefaultmap Option)

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Changing Mapﬁles with -k ﬁlename and +nodefaultmap . . . . . . . . . . 298

Mapﬁle Example: Using -k mapﬁle and +nodefaultmap . . . 298

Simple Mapﬁle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Default HP-UX Release 11.0 Mapﬁle . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Contents

Deﬁning Syntax for Mapﬁle Directives . . . . . . . . . . . . . . . . . . . . . . . . .303

Deﬁning Mapﬁle Segment Declarations. . . . . . . . . . . . . . . . . . . . . . . . .304

Segment Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .304

Mapﬁle Segment Declaration Examples. . . . . . . . . . . . . . . . . . . . . . .306

Deﬁning Mapﬁle Section Mapping Directives . . . . . . . . . . . . . . . . . . . .307

Internal Map Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309

Placement of Segments in an Executable. . . . . . . . . . . . . . . . . . . . . .309

Mapping Input Sections to Segments . . . . . . . . . . . . . . . . . . . . . . . . .309

Interaction between User-deﬁned and Default Mapﬁle Directives. .312

Mapﬁle Option Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313

Fatal Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313

Warnings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Contents

Preface

This Guide covers the following topics:

• Chapter 1, “What's New in Recent Releases,” lists new features added

in recent releases.

• Chapter 2, “What Happens When You Compile and Link a Program,”

provides details on compiling and linking programs.

• Chapter 3, “Linker Tasks,” lists many ways you can specify how you

want your program linked.

• Chapter 4, “Linker Tools,” list the tools available in the linker toolset.

• Chapter 5, “Creating and Using Libraries,” discusses all aspects of

both archive and shared libraries.

• Chapter 6, “Shared Library Management Routines,” explains how to

explicitly load libraries at run time using shared library management routines.

• Chapter 7, “Position-Independent Code,” describes how to write

position-independent assembly code.

• Chapter 8, “W a ys to Improve Performance, ” discusses several w a ys to

optimize your program.

• Appendix A, “Using Mapﬁles,” describes mapﬁles.

• Glossary contains deﬁnitions of important terms in this manual.

Printing History

New editions of this manual will incorporate all material updated since the previous edition. The manual printing date and part number indicate its current edition. The printing date changes when a new edition is printed. The manual part number changes when extensive technical changes are incorporated.

• November 1997, Edition 1, part number B2355-90655. This manual

supersedes HP-UX Linker and Libraries User’s Guide part number B2355-90655. The main reason for this new edition is to document new functionality for the HP-UX 11.00 release:

• Add the +ee linker option to export symbols.

• Add 64-bit linker toolset support for linker options.

• Add 64-bit mode linker tools and describe the enhancements to the 32-bit mode toolset.

• Describe 32-bit and 64-bit mode behavior differences.

• Add 64-bit mode dynamic path searching mechanisms.

• Add 64-bit mode symbol binding semantics.

• Add the dl* shared library management routines for 64-bit mode support and describe enhancement to the shl_load routines for shared libraries.

• Add init/ﬁni style initializers for 64-bit mode support for shared libraries.

• Add the BIND_BREADTH_FIRST ﬂag to the shl_load routine to control search path behavior.

• Add description of support for ELF object ﬁle format.

• April 1997, Edition 1, part number B2355-90654. This manual supersedes Programming on HP-UX part number B2355-90652. The main reason for this new edition is to document new functionality for the HP-UX 10.30 release:

• Announce linker thread-safe features for ld, dld.sl, crt0.o,

and libdld.sl.

• Add the +pd size linker option to set the virtual memory page size

for program data.

• Add the +pi size linker option to set the virtual memory page size

for program instructions.

• Add the +k linker option (see ld(1)) to only create an executable if

no errors are found at link time.

• Add the chatr +k option to enable or disable kernel-assisted

branch prediction.

• Add the chatr +pd size and +pi size virtual memory page setting

options.

• July 1996, Edition 1, part number B2355-90653. This manual supersedes Programming on HP-UX part number B2355-90652. The main reason for this new edition is to document new functionality for the HP-UX 10.20 release and to describe what's ahead in a future release of the linker toolset:

• Add a -B symbolic option to help improve shared library

performance.

• Introduce the fastbind tool to improve the start up time of

programs that use shared libraries.

• Introduce the Linker and Libraries Online User Guide.

• Announce changes in PA-RISC hardw are compatibility—PA-RISC

1.1 systems, by default, generate PA-RISC 1.1 code; PA-RISC 2.0 systems generate 2.0 code.

• Describe compatibility warnings generated by the linker and

dynamic loader for HP 9000 architecture issues and linker toolset features that may change in a future release.

• Describe what's changing in a future release of the linker toolset.

• Add the +Ostaticprediction option to use with proﬁle-based

optimization.

• January 1995, Edition 1, part number B2355-90652. This manual supersedes Programming on HP-UX part number B2355-90026. The main reason for this new edition is to document new functionality for the HP-UX 10.0 release:

• Update path names to reﬂect the new System V Release 4 ﬁle

system. Some of the changes are:

• Most ﬁles in /lib are now in /usr/lib.

• Most optional products are in /opt. For example, HP C is in

/opt/ansic, HP C is in /opt/CC, HP FORTRAN/9000 is in /opt/fortran, and HP/DDE is in /opt/langtools/dde.

• Caution against mixing shared and archive libraries.

• Describe a new library-level versioning scheme for shared

libraries.

• Update the chapter on proﬁle-based optimization.

• Describe changes in optimization levels 3 and 4.

• Describe thread-safe interfaces shl_get_r and shl_gethandle_r.

• Add a new BIND_TOGETHER ﬂag to the shl_load routine.

• Add a new chapter "Porting Applications to HP-UX."

What's New in Recent Releases

1 What's New in Recent Releases

This section contains information about recent releases of the HP-UX linker toolset:

For This Release

The HP-UX 11.00 linker toolset contains new features: If you use the 32-bit mode linker toolset, see the following items:

• “PA-RISC Changes in Hardware Compatibility” updated in this chapter.

• “Exporting Symbols with +ee” on page 81.

• “Changes in Future Releases” updated in this chapter.

If you use the 64-bit mode linker toolset, see the following items:

• “PA-RISC Changes in Hardware Compatibility” updated in this chapter.

• “64-bit Mode Linker Toolset Compatibility with De Facto Industry Standards” described in this chapter.

• “64-bit Mode ELF Object File Format” described in this chapter.

• “Dynamic Path Searching for Shared Libraries” on page 177 describes differences in the run time searching of shared libraries.

• “Shared Library Symbol Binding Semantics” on page 178 describes differences in shared library binding semantics.

• New 64-bit mode linker options, symbols, and features, described in“New Features for 64-bit Mode Linking” in this chapter.

• Unsupported 32-bit mode features, behavior, and linker options, described in “64-bit Mode Link-time Differences” and“64-bit Mode Run Time Differences” in this chapter.

• “64-bit Mode Initializers” on page 210 describes the init/ﬁni support for 64-bit mode shared libraries.

Chapter 1 19

What's New in Recent Releases

• “The dlopen Shared Library Management Routines” on page 240 describes the dl* family of shared library management routines for 64-bit mode.

• “BIND_BREADTH_FIRST Modiﬁer” on page 222 describes the ﬂag added to the shl_load routine to modify search behavior.

• “Changes in Future Releases” updated in this chapter.

For Previous Releases

The following items were added in the HP-UX 10.30 release:

• “Linker Thread-Safe Features” on page 50.

• “Options to Improve TLB Hit Rates” on page 273.

• The +k linker option (see ld(1)) to remove an executable if the link fails.

• The +k chatr option (see chatr(1)) to improve branch prediction on PA-RISC 2.0.

The following items were added in the HP-UX 10.20 release:

• “Improving Shared Library Performance with -B symbolic” on page

60.

• “Improving Shared Library Start-Up Time with fastbind” on page

293.

• “Online Help for Linker and Libraries” described in this chapter.

• “PA-RISC Changes in Hardware Compatibility” described in this chapter.

• “Linker Compatibility Warnings” on page 99.

• “Dynamic Loader Compatibility Warnings” on page 256.

• The +Ostaticprediction linker option described in the ld(1) man page to use with proﬁle-based optimization

20 Chapter 1

What's New in Recent Releases

PA-RISC Changes in Hardware Compatibility

The HP-UX 10.20 release introduced HP 9000 systems based on the PA-RISC 2.0 architecture. Also, beginning with that release, HP compilers by default generate executable code for the PA-RISC architecture of the machine on which you are compiling.

In previous releases, the compilers generated PA-RISC 1.0 code on all HP 9000 Series 800 servers and PA-RISC 1.1 code on Series 700 workstations. HP compilers now by default generate PA-RISC 1.1 code on 1.1 systems and 2.0 code on 2.0 systems.

Using the +DAportable compiler option provides compatibility of code between PA-RISC 1.1 and 2.0 systems. Note that the HP-UX 10.10 release is the last supported release for PA-RISC 1.0 systems, so code generated by the HP-UX 10.20 release of HP compilers is not supported on PA-RISC 1.0 systems.

NOTE The +DA1.0 option will be obsolete in a future release. You can achieve

better performance on PA-RISC 1.1 and 2.0 systems by not using this option.

PA-RISC 2.0 Compatibility

The instruction set on PA-RISC 2.0 is a superset of the instruction set on PA-RISC 1.1. As a result, code generated for PA-RISC 1.1 systems will run on PA-RISC 2.0 systems. However, code generated for PA-RISC 2.0 systems will not run on P A-RISC 1.1 or 1.0. The linker issues a hardw are compatibility warning whenever it links in any PA-RISC 2.0 object ﬁles:

/usr/ccs/bin/ld: (Warning) At least one PA 2.0 object file (sum.o) was detected. The linked output may not run on PA 1.x system.

If you try to run a PA-RISC 2.0 program on a 1.1 system, you'll see a message like:

$ a.out ksh: ./a.out: Executable file incompatible with hardware

Chapter 1 21

What's New in Recent Releases

PA-RISC Changes in Hardware Compatibility

In this example, the +DAportable compiler option can be used to create code compatible for PA-RISC 1.1 and 2.0 systems.

PA-RISC Architectures and Their System Models

The HP 9000 PA-RISC (Precision Architecture Reduced Instruction Set Computing) Series 700/800 family of workstations and servers has evolved from three versions of PA-RISC:

PA-RISC 1.0 The original version of PA-RISC ﬁrst introduced on

Series 800 servers. The following Series are included: 840, 825, 835/SE, 845/SE, 850, 855, 860, 865, 870/x00, 822, 832, 842, 852, 890, 808, 815, 635, 645.

PA-RISC 1.1 The second version of PA-RISC ﬁrst introduced on

Series 700 workstations. Newer Series 800 systems also use this version of the architecture. The following Series are included: 700, 705, 710, 715, 720, 725, 730, 735, 750, 755, B132L, B160L, B132L+, B180L, C100, C110, J200, J210, J210XC, 742i, 742rt, 743i, 743rt, 745i, 747i, 748i, 8x7, D (except Dx70, Dx80), E, F, G, H, I, K (except Kx50, Kx60, Kx70), T500, T520.

PA-RISC 2.0 The newest version of PA-RISC. The following Series

are included: C160, C180, C180XP, C200, C240, J280, J282, J2240, Dx70, Dx80, Kx50, Kx60, Kx70, T600, V2200.

For More Information

• See your compiler online help or documentation for details on the +DA option.

• See the ﬁle /opt/langtools/lib/sched.models for a complete list of model numbers and their architectures. Use the command model to determine the model number of your system.

22 Chapter 1

What's New in Recent Releases

64-bit Mode Linker Toolset Compatibility with De Facto Industry Standards

The 64-bit mode linker and dynamic loader provide linking and loading behaviors found widely across the Unix industry, considered, with the SVR4 standards, to deﬁne the de facto industry standards. The following 64-bit linker behavior is compliant with de facto industry standard:

• ELF object ﬁle format and libelf(3x) routines

• Dynamic path searching

• Library-level versioning

• dl* family of dynamic loading routines

• Breadth-ﬁrst symbol searching The HP-UX 11.00 release maintains certain behaviors to make

transition from 32-bit to 64-bit mode easier:

• Creation of default run-time path environment variable (RPATH) if no ld +b is seen on the link line, to improve transition from the 32-bit mode linker.

• ld +compat option for compatibility with 32-bit linking and loading behavior.

Chapter 1 23

What's New in Recent Releases

64-bit Mode ELF Object File Format

Starting with HP-UX release 11.00, the 64-bit linker toolset supports the ELF (executable and linking format) object ﬁle format. The 64-bit linker toolset provides new tools to display and manipulate ELF ﬁles. The

libelf(3x) library routines provide access to ELF ﬁles. The command elfdump(1) displays contents of an ELF ﬁle.

The following options instruct the compiler to generate 64-bit ELF object code.

Option Compiler

+DA2.0W C and aC++ +DD64 C

See the HP-UX Software Transition Toolkit (STK) at http://www.software.hp.com/STK/ for more information on the structure of ELF object ﬁles.

24 Chapter 1

What's New in Recent Releases

New Features for 64-bit Mode Linking

This section introduces new features of the 64-bit linker for HP-UX release 11.00.

64-bit Mode Linker Options

The ld(1) command supports the following new options in 64-bit mode:

Option Action

-dynamic Forces the linker to create a shared executable. The linker looks for shared libraries ﬁrst and then archived libraries. This option is on by default when you compile in 64-bit mode.

-noshared Forces the linker to create a fully bound archive program.

-k ﬁlename Allows you to control the mapping of input section in the object ﬁle to segments in the output ﬁle.

+[no]allowunsats Instructs the linker how to report errors for

output ﬁles with unsatisﬁed symbols.

+compat Instruct the linker to use 32-bit mode

linking and dynamic loading behaviors.

+[no]forceload Enables/disables forced loading of all the

object ﬁles from archive libraries.

+hideallsymbols +nodefaultmap Instructs the linker not to load the default

Chapter 1 25

Hides all symbols from being exported.

mapﬁle. See the -k option.

What's New in Recent Releases

New Features for 64-bit Mode Linking

Option Action

+noenvvar Instructs the dynamic loader not to look at

the LD_LIBRARY_PATH and SHLIB_PATH environment variables at runtime.

+std Instructs the linker to use SVR4 compatible

linking and loading behaviors. Default for 64-bit mode.

+stripunwind Instructs the linker not to output the

unwind table.

+vtype type Produces verbose output about selected link

operations.

a. The linker accepts but ignores this option in 32-bit mode. It

creates an executable (a.out).

64-bit Mode Linker-deﬁned Symbols

The 64-bit linker reserves the following symbol names:

Symbol Deﬁnition

__SYSTEM_ID Largest architecture revision level used by

any compilation unit

_FPU_STATUS Initial value of FPU status register _end Address of ﬁrst byte following the end of the

main program’s data segment; identiﬁes the beginning of the heap segment

__TLS_SIZE Size of the Thread Local Storage segment

required by the program

__text_start Beginning of the text segment _etext End of the text segment __data_start Beginning of the data segment

26 Chapter 1

What's New in Recent Releases

New Features for 64-bit Mode Linking

Symbol Deﬁnition

_edata End of initialized data __gp Global pointer value __init_start Beginning of the .init section __init_end End of the .init section __fini_start Beginning of the .ﬁni section __fini_end End of the .ﬁni section __unwind_start Beginning of the unwind table __unwind_end End of the unwind table

NOTE The linker generates an error if a user application also deﬁnes these

symbols.

Chapter 1 27

What's New in Recent Releases

64-bit Mode Link-time Differences

The 64-bit mode linker toolset does not support the following 32-bit mode features.

Option or

Behavior

-A name Speciﬁes incremental loading. 64-bit applications must use shared libraries instead.

-C n Does parameter type checking. This option is unsupported.

-S Generates an initial program loader header ﬁle. This option is unsupported.

-T Save data and relocation information in temporary ﬁles to reduce virtual memory requirements during linking. This option is unsupported.

-q, -Q, -n Generates an executable with ﬁle type DEMAND_MAGIC, EXEC_MAGIC, and SHARE_MAGIC

respectively. These options have no effect and are ignored in 64-bit mode.

-N Causes the data segment to be placed immediately after the text segment. This option is accepted but ignored in 64-bit mode. If this option is used because your application data segment is large, then the option is no longer needed in 64-bit mode. If this option is used because your program is used in an embedded system or other specialized application, consider using mapﬁle support with the -k option.

Description

+cg pathname Speciﬁes pathname for compiling I-SOMs to SOMs.

This option is unsupported.

28 Chapter 1

What's New in Recent Releases

64-bit Mode Link-time Differences

Option or

Behavior

+dpv Displays verbose messages regarding procedures

which have been removed due to dead procedure elimination. Use the -v linker option instead.

Intra-library versioning

Duplicate code and data symbols

All internal and undocumented linker options

For more information, see the HP-UX Linker and Libraries Online User Guide (ld +help).

Speciﬁed by using the HP_SHLIB_VERSION pragma (C and aC++) or SHLIB_VERSION directive (Fortran90).

In 32-bit mode, the linker lets you version your library by object ﬁles. 64-bit applications must use SVR4 library-level versioning instead.

Code and data cannot share the same namespace in 64-bit mode. You should rename the conﬂicting symbols.

These options are unsupported.

Description

Chapter 1 29

What's New in Recent Releases

64-bit Mode Run Time Differences

Applications compiled and linked in 64-bit mode use a run-time dynamic loading model similar to other SVR4 systems. There are two main areas where program startup changes in 64-bit mode:

• Dynamic path searching for shared libraries.

• Symbol searching in dependent libraries. It is recommended that you use the standard SVR4 linking option

(+std), which is on by default when linking 64-bit applications. There may be circumstances while you transition, that you need 32-bit compatible linking behavior. The 64-bit linker provides the +compat option to force the linker to use 32-bit linking and dynamic loading behavior.

The following table summarizes the dynamic loader differences between 32-bit and 64-bit mode:

Linker and Loader

Functions

+s and +b path_list

ordering

32-bit Mode Behavior 64-bit Mode Behavior

Ordering is signiﬁcant. Ordering is insigniﬁcant by default.

Use +compat to enforce ordering.

30 Chapter 1

+ 303 hidden pages