OpenVMS Linker Utility Manual

Document revision date: 19 July 1999

OpenVMS Linker Utility Manual

Order Number: AA--PV6CC--TK

January 1999

This manual describes the OpenVMS Linker utility.

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

Software Version: OpenVMS Alpha Version 7.1 OpenVMS VAX Version 7.1 The content of this document has not changed since OpenVMS Version 7.1.

Compaq Computer Corporation Houston, Texas

Reprinted January 1999

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor.

Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Compaq Computer Corporation: Alpha, Compaq, DECdirect, DIGITAL, OpenVMS, VAX, VAX BLISS-32, VAX C, VAX FORTRAN, VAX MACRO, VAXcluster, VMS, and the Compaq logo.

The following are third-party trademarks:

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

All other trademarks and registered trademarks are the property of their respective holders.

ZK4548

The OpenVMS documentation set is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents Index

Preface

Intended Audience

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

Document Structure

This book has two parts and two appendixes. Part 1 includes five chapters that describe the linker. Part 2 is a reference section that describes the LINK command and its qualifiers and options. The appendixes contain the VAX Object Language specification and the Alpha Object Language specification. (The appendixes are primarily useful to compiler developers.)

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

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

Chapter 3 describes how the linker creates image files.

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

Chapter 5 describes how to interpret image map files.

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 884-0120, Attention: OSSG Documentation, ZK03-4/U08

Mail Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.openvms.digital.com:81/

If you need help deciding which documentation best meets your needs, call 800-344-4825.

Conventions

The following conventions are 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 the options in parentheses if you choose more than one.

[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)

{ } In command format descriptions, braces indicate required elements; you must choose one of the options listed.

bold text This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
This style is also used to show user input in Bookreader versions of the manual.

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).

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace text Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

- 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
Linker Utility Description

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:

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

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. When invoked on a VAX system, the linker creates OpenVMS VAX images by default; when invoked on an Alpha system, the linker creates OpenVMS Alpha images by default.

The primary type of image the linker creates is an executable image. This type of 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 information from the image header 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 that can be called by executable images or other shareable images. A shareable image is similar to an executable image; however, it cannot be executed by issuing the RUN command (shareable images do not contain a transfer address). Before a shareable image can be run, you must include it as an input file in a link operation in which an executable image is created. At run time, when the image activator processes the header in an executable image, it activates all the shareable images to which the executable image was linked.

The linker can also create a system image, which can be run as a standalone system. System images generally do not have image headers and are not activated by the image activator.

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 are produced by language processors, such as compilers or assemblers. The linker also accepts other input files such as shareable images and symbol table files, both the 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.1 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. The language processors flag 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 2 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 in the program section definitions processed during symbol resolution. Chapter 3 provides more information about memory allocation.
Image initialization. After it resolves references and specifies the memory requirements of the image, the linker 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.
Certain global symbols cannot be resolved at link time. For example, in shareable images, the value of a symbol that represents an address cannot be determined until run time, when the image activator loads the image in memory. The linker lists the symbols it cannot resolve in a fix-up section and the image activator supplies their actual address at run time by relocating the symbols.
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 the symbols in the shareable image have their correct addresses. Chapter 3 provides more information about image initialization.
Image optimization. For Alpha images, the linker can perform certain optimizations to improve the performance of the image it is creating. These optimizations include replacing JSR instruction sequences with the more efficient Branch to Subroutine (BSR) instruction sequence wherever the language processors specify. For more information, see Section 1.4.

1.1.2 Using the Linker

You invoke the linker interactively by typing the LINK command together with the appropriate input file names at the DCL prompt. You may also invoke the linker by including the LINK command in a command procedure. (For more information about invoking the linker, see Part 2.)

For example, the simple program illustrated in Example 1-1 prints the greeting "Hello World!" on the terminal.

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

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

To run this program, you must first compile the source file to create an object module. To compile the example, written in C, invoke the appropriate 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 in the module in the global symbol directory (GSD). For example, in Example 1-1, the printf routine is referenced in the module but is not defined in it.

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

$ LINK HELLO

In the link operation, you must specify as input files all the modules required to create the image. For example, you must include the C run-time library in the link of the program in Example 1-1 to resolve the reference to the printf routine.

For Alpha linking, the linker processes the C run-time library shareable image [DECC$SHARE] by default because it resides in the default system shareable image library [IMAGELIB.OLB]. See Section 2.2.3.3 for more information about how the linker processes default system libraries.

For VAX linking, you must specify the C run-time shareable image [VAXCRTL] as an input file in the link operation explicitly, as in the following example:

$ LINK HELLO, SYS$INPUT/OPT SYS$LIBRARY:VAXCRTL/SHARE [Ctrl/Z]

(For more information about linking against the C run-time library for VAX images, see the VAX C compiler documentation.)

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 2 provides more information about this topic.

After performing symbol resolution, when the linker has determined all the input modules necessary to create the image, the linker determines the memory requirements of the image based on the memory requirements of each object module. The compilers have specified the memory requirements of the object modules as program section specifications. The linker gathers together program sections with similar attributes into image sections. (Chapter 3 provides more information about image creation.) At run time, the image activator reads the memory requirements of the image by processing the list of image section descriptors (ISDs) the linker has stored in the image header.

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 must 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 2 provides reference descriptions of all the qualifiers and options supported by the linker. Section 1.5 contains a summary table of these qualifiers and options.

1.2 Specifying Input to the Linker

You specify the files you want the linker to process on the LINK command line or in a linker options file. (Library files may also be specified as a user library, which the linker processes by default.) You must specify at least one input file in every link operation and, in every link operation, at least one input file must be an object module. Table 1-1 lists the different types of input files accepted by the linker, along with their default file types. (The defaults are used for both VAX and Alpha linking.) The table also describes how you can specify the file in a link operation.

Table 1-1 Input Files Accepted by the Linker
File Default
File Type Description

Object file .OBJ Created by a language processor. May be specified on LINK command line or in a linker options file. This is the default input file accepted by the linker.

Shareable image .EXE Produced by a previous link operation. Must be specified in a linker options file; you cannot specify a shareable image as an input file on the command line. Identify the input file as a shareable image by appending the /SHAREABLE qualifier to the file specification.

Library file .OLB Produced by the Librarian utility. May contain object modules or shareable images. May be specified on the LINK command line, in a linker options file, or as a default user library processed by the linker. Identify the input file as a library file by appending the /LIBRARY qualifier to the library file specification. You can also include specific modules from a library in a link operation by appending the /INCLUDE qualifier to the library file specification.

Symbol table file .STB Produced by a previous link operation or a language processor. May be specified on the LINK command line or in an options file. Because a symbol table file is processed as an object module, it requires no identifying qualifier.
Note that symbol table files produced by the linker during Alpha links cannot be specified as input files in a link operation. They are intended to be used only as an aid to debugging with the System Dump Analyzer utility (See Section 1.2.4 for more information.)

Options file .OPT Text file containing link option specifications or link input file specifications. May be specified only on the command line; you cannot specify an options file inside another options file. Identify the input file as an options file by appending the /OPTIONS qualifier to the end of the file specification.

**Table 1-1 Input Files Accepted by the Linker**
File	Default File Type	Description
Object file	.OBJ	Created by a language processor. May be specified on LINK command line or in a linker options file. This is the default input file accepted by the linker.
Shareable image	.EXE	Produced by a previous link operation. Must be specified in a linker options file; you cannot specify a shareable image as an input file on the command line. Identify the input file as a shareable image by appending the /SHAREABLE qualifier to the file specification.
Library file	.OLB	Produced by the Librarian utility. May contain object modules or shareable images. May be specified on the LINK command line, in a linker options file, or as a default user library processed by the linker. Identify the input file as a library file by appending the /LIBRARY qualifier to the library file specification. You can also include specific modules from a library in a link operation by appending the /INCLUDE qualifier to the library file specification.
Symbol table file	.STB	Produced by a previous link operation or a language processor. May be specified on the LINK command line or in an options file. Because a symbol table file is processed as an object module, it requires no identifying qualifier. Note that symbol table files produced by the linker during Alpha links cannot be specified as input files in a link operation. They are intended to be used only as an aid to debugging with the System Dump Analyzer utility (See Section 1.2.4 for more information.)
Options file	.OPT	Text file containing link option specifications or link input file specifications. May be specified only on the command line; you cannot specify an options file inside another options file. Identify the input file as an options file by appending the /OPTIONS qualifier to the end of the file specification.

You must specify only native OpenVMS Alpha object modules and shareable images as input files when creating an OpenVMS Alpha image. The same holds true when building an OpenVMS VAX image. (Note, however, that OpenVMS VAX images can run as translated images on OpenVMS Alpha systems and translated images can interoperate with native OpenVMS Alpha images. See Migrating an Application from OpenVMS VAX to OpenVMS Alpha for more information.)

Contents

Index

privacy and legal statement

4548PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 884-0120, Attention: OSSG Documentation, ZK03-4/U08
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

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 the options in parentheses if you choose more than one.
[ ]	In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
{ }	In command format descriptions, braces indicate required elements; you must choose one of the options listed.
bold text	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason. This style is also used to show user input in Bookreader versions of the manual.
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).
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Monospace text	Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
-	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.