[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

HP OpenVMS Linker Utility Manual

Order Number: BA554-90004

July 2006

This manual describes the OpenVMS Linker utility. The linker creates images containing binary code and data that run on OpenVMS I64, Alpha, or VAX systems. These images are primarily executable images activated at the DCL command line. The linker also creates shareable images that can be called by executable or by other shareable images.

Revision/Update Information: This manual supersedes the HP OpenVMS Linker Utility Manual, Version 7.3

Software Version: OpenVMS I64 Version 8.3
OpenVMS Alpha Version 8.3

Hewlett-Packard Company Palo Alto, California

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

ZK4548

The HP OpenVMS documentation set is available on CD-ROM.

Contents

Index

Preface

Intended Audience

Programmers at all levels of experience can use this manual effectively.

Document Structure

This book is organized in four parts, as follows:

Part I provides an introduction to the linker running on OpenVMS I64, Alpha, and VAX systems:

Chapter 1 introduces the OpenVMS Linker utility and how to use the LINK command and its qualifiers and parameters.

Part II contains chapters specific to linking on OpenVMS I64 systems:

Chapter 2 describes how the linker resolves symbolic references among input files on I64 systems.

Chapter 3 describes how the linker creates image files on I64 systems.

Chapter 4 describes how to create shareable images and use them in link operations on I64 systems.

Chapter 5 describes how to interpret the I64 linker image map.

Part III contains chapters specific to linking on OpenVMS Alpha and VAX systems:

Chapter 6 describes how the linker resolves symbolic references among input files on Alpha and VAX systems.

Chapter 7 describes how the linker creates image files on Alpha and VAX systems.

Chapter 8 describes how to create shareable images and use them in link operations on Alpha and VAX systems.

Chapter 9 describes how to interpret the Alpha/VAX image map.

Part IV provides a reference section that describes the LINK command and its qualifiers and options.

The glossary contains a list of important terms to refer to hardware and/or software entities, for the OpenVMS Linker running on a variety of OpenVMS operating systems and computers.

Reader's Comments

HP welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet	openvmsdoc@hp.com
Postal Mail	Hewlett-Packard Company OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

How To Order Additional Documentation

For information about how to order additional documentation, visit the following World Wide Web address:

http://www.hp.com/go/openvms/doc/order

Conventions

The following conventions may be used in this manual:

Ctrl/ x	A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x	A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
`[Return]`	In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) In the HTML version of this document, this convention appears as brackets, rather than a box.
...	Horizontal ellipsis points in examples indicate one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . .	Vertical ellipsis points indicate the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( )	In command format descriptions, parentheses indicate that you must enclose choices in parentheses if you specify more than one.
[ ]	In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.
\|	In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.
{ }	In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.
bold type	Bold type represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.
italic text	Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
`Example`	This typeface indicates code examples, command examples, and interactive screen displays. In text, this type also identifies URLs, UNIX commands and pathnames, PC-based commands and folders, and certain elements of the C programming language.
UPPERCASE TYPE	Uppercase type indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
-	A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Part 1
Introduction to the OpenVMS Linker

Chapter 1
Introduction

This chapter introduces the OpenVMS Linker utility (the linker), describing its primary functions and its role in software development. The chapter describes the following:

Definition of the linker and its main functions
How to invoke the linker
How to specify input files in a link operation
How to specify which output files the linker produces

In addition, this chapter provides an overview of how you can control a link operation by using qualifiers and options.

1.1 Overview

This section provides a list of key terms used in this manual and an overview of the OpenVMS linker.

1.1.1 Terminology Used in this Manual

The OpenVMS Linker utility runs on a variety of OpenVMS operating systems and computers. Several important terms are used in this manual to refer to these hardware and/or software entities. The following list defines these terms. For a complete list of linker terminology, see the Glossary.

system---The computer hardware, the server; distinguish from the operating system (for example, OpenVMS Alpha).
platform---The system architecture; includes all systems running, for example, Intel® Itanium® processors.
OpenVMS system---An HP system running the OpenVMS operating system. These include OpenVMS I64, Alpha, and VAX.
OpenVMS I64 system (or I64 system)--- An HP Integrity server running the OpenVMS I64 operating environment.
OpenVMS Alpha system (or Alpha system)---An HP Alpha system running the OpenVMS Alpha operating system.
OpenVMS VAX system (or a VAX system)---An HP VAX system running the OpenVMS VAX operating system. tion.
Executable and Linkable Format (ELF)---The object and image format described in the System V Application Binary Interface. See the Glossary for a complete definition of this term and additional terms.

I64, Alpha, or VAX might be used as prefixes as well. For example:

I64 image---An OpenVMS I64 image that includes binary data and Itanium instructions.
Alpha object file--- An OpenVMS Alpha object that includes binary data and Alpha instructions.
VAX linking---The process of using the OpenVMS Linker utility to create an OpenVMS VAX image.

1.1.2 Linker Overview

The primary purpose of the linker is to create images. An image is a file containing binary code and data that can be executed on an OpenVMS system.

On I64 systems, the linker creates OpenVMS I64 images by default. On Alpha systems, the linker creates OpenVMS Alpha images by default. On OpenVMS VAX systems, the linker creates OpenVMS VAX images by default.

On both Alpha and VAX systems, the linker provides /ALPHA and /VAX qualifiers that allow you to instruct the linker to accept Alpha or VAX object files on each respective system (see information about these linker qualifiers in Part 4.) As a result, the linker can create VAX images on an Alpha system and vice versa.

The primary type of image the linker creates is an executable image. An executable image can be activated at the DCL command line by issuing the RUN command. At run time, the image activator, which is part of the operating system, opens the image file and reads activation information from the image to set up process page tables and pass control to the location (transfer address) where image execution is to begin.

The linker can also create a shareable image. A shareable image is a collection of procedures and data that can be called by executable images or by other shareable images. A shareable image is similar to an executable image. The linker separates shareable from nonshareable code and data. Shareable code and data can be shared via global sections that are set up by the Install utility or by the image activator.

In order to use the procedures or data of a shareable image, the shareable image has to be included in a link operation for another image, either explicitly in a linker option or implicitly from a default shareable image library. At run time, when the image activator processes an executable image, it activates all the shareable images to which the executable image was linked.

The OpenVMS Alpha and OpenVMS VAX linker can also create a system image, which can be run as a standalone system. System images generally do not contain image activation information and are not activated by the image activator. Images without activation information are not defined in the OpenVMS I64 object language. As a result, the OpenVMS I64 linker does not create this special type of image.

The linker creates images by processing the input files you specify. The primary type of input file that can be specified in a link operation is an object file. Object files that contain one or more object modules are produced by language processors, such as compilers or assemblers.

The binary code and data in an object module is in a platform-specific format:

On I64 platforms, the object module (and the resulting image) is in the Executable and Linkable Format (ELF).
On Alpha platforms, the object module is in the Alpha Object Language format.
On VAX platforms, the object module is in the VAX Object Language format.

Note

This manual frequently refers to parts of the format of the object language. As such, different terminology is occasionally used when referring to the same item on different platforms.

For example, on OpenVMS Alpha and VAX systems, the linker collects program sections (generally called psects) into image sections. Comparatively, on OpenVMS I64 systems the linker collects sections into segments. Although the names appear similar, there are considerable differences between the structure and content of an image section on OpenVMS Alpha and VAX compared with a segment on OpenVMS I64.

OpenVMS I64 compilers also take advantage of a short data section when constructing code with offsets from the global pointer (GP) register, neither of which are present on Alpha and VAX.

When the manual refers to a specific part of the object language, distinctions are made as to whether the reference pertains to the object language used by OpenVMS I64, Alpha, or VAX.

The linker also accepts other input files such as shareable images, and on VAX platforms, symbol table files, which are both products of previous link operations. Section 1.2 provides more information about all the types of input files accepted by the linker. Section 1.3 provides more information about the output files created by the linker.

Figure 1-1 illustrates the relationship of the linker to the language processor in the program development process.

Figure 1-1 Position of the Linker in Program Development

1.1.3 Linker Functions

To create an image from the input files you specify, the linker performs the following primary functions:

Symbol resolution. Source modules can use symbols to represent the location of a routine entry point, the location of a data item, or a constant value. A source module may reference symbols that are defined externally to the module. When a language processor, such as a compiler or assembler, processes the source module, it cannot find the value of a symbol defined externally to the module. A language processor flags these externally defined symbols as unresolved symbolic references and leaves it to the linker to find their definitions among the other input files you specify. When the linker finds the definition of a symbol, it substitutes the value of the symbol (its definition) for the reference to the symbol. Chapter 6 provides more information about symbol resolution.
Virtual memory allocation. After resolving symbolic references among the input files, the linker allocates virtual memory for the image, based on the memory requirements specified by the input files. Chapter 7 provides more information about memory allocation.
Image initialization. After the linker resolves references and obtains the memory requirements of the image, it initializes the image by filling it with the compiled binary data and code. The linker also inserts the actual value of resolved symbols at each instance where the symbol is referenced.
For certain global symbols, the linker does not write their value into the image. For example, when taken from shareable images, the value of a symbol that represents an address cannot be determined until run time; that is, when the image activator loads the image into memory. The linker lists these symbols in the fix-up information, to which the image activator provides the actual address at run time.
When the image activator loads a shareable image in memory and relocates all the symbols in the shareable image, it must ensure that the other images that reference these symbols in the shareable image have their correct addresses. Chapter 3 and Chapter 7 provide more information about image initialization.
Image optimization. For OpenVMS Alpha images, the linker can perform certain optimizations to improve the run time performance of the image it is creating. For OpenVMS I64 images, the linker can optimize data references to the short data segment.
For more information, see Chapter 3 and Chapter 7.
For Alpha images, optimizations include replacing JSR instruction sequences with the more efficient Branch to Subroutine (BSR) instruction sequence wherever the language processors specify.

1.1.4 Using the Linker

You start the linker interactively by entering the LINK command together with the appropriate input file names at the DCL prompt. You can also start the linker by including the LINK command in a command procedure. (For more information about starting the linker, see Part 4.)

The simple program shown in Example 1-1 prints the greeting "Hello World!" on the terminal.

Example 1-1 Hello World! Program (HELLO.C)


#include <stdio.h>
main() {
   printf( "Hello World!\n" );
}

To run this program, you must first compile the source file to create an object module. To compile this HP C example, invoke the appropriate HP C compiler to create an object module, as in the following example:

$ CC HELLO

During compilation, the compiler translates the statements in the source file into machine instructions and groups portions of the program into program sections according to their memory use and other characteristics. In addition, the compiler lists all the global symbols defined in the module and referenced by the module in the symbol table. In Alpha and VAX object modules this table is also called a global symbol directory (GSD). In Example 1-1, the printf routine is referenced by the module but is not defined in it. The printf routine is defined in the HP C Run-Time Library (DECC$SHR).

To create an executable image, you usually link the object file produced by the compiler, as in the following example:

$ LINK HELLO

By default, the linker processes DECC$SHR because it resides in the default system shareable image library [IMAGELIB.OLB]. Because of this, you do not need to specify this as input unless you are changing the behavior of the default library scans (for example, linking with /NOSYSLIB). See Section 6.2.3.3 for more information about how the linker processes default system libraries.

The linker processes the input files you specify in two passes. In its first pass through the input files, the linker resolves symbolic references between the modules. Because the linker processes different types of input files in different ways, the order in which you specify input files can affect symbol resolution. Chapter 6 provides more information about this topic.

After performing symbol resolution and determining all the input modules necessary to create the image, the linker ascertains the memory requirements of the image based on the memory requirements of the input files. The compilers have specified the memory requirements of the object modules as program section attributes.

On Alpha and VAX, the linker gathers together program sections with similar attributes into image sections. At activation time, the image activator reads the memory requirements of the image that the linker has stored in the image file by processing the list of image section descriptors (ISDs) and begins to set up the image for execution. (Chapter 7 provides more information about Alpha and VAX image creation.)

On I64, the linker gathers ELF sections with similar attritutes into ELF segments. At run time, the image activator reads the memory requirements of the image that the linker has stored in the image file by processing the segments. (Chapter 3 provides more information about creation of I64 images.)

If the image that results from the link operation is an executable image, it can be executed at the DCL command line. The following example illustrates how to execute the program in Example 1-1:

$ RUN HELLO
Hello World!

Note that a LINK command required to create a real application, unlike the Hello World! example, can involve specifying hundreds of input files of various types.

As with most other DCL commands, the LINK command supports numerous qualifiers with which you can control various aspects of a link operation. The linker also supports linker options, which you can use to further control a link operation. Linker options can be specified in an options file, which is then specified as an input file in a link operation. Section 1.2.5 describes the benefits of using options files and describes how to create them. Part 4 provides descriptions of the qualifiers and options supported by the linker. Section 1.4 contains a summary table of these qualifiers and options.