HP OpenVMS Linker Utility Manual
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.
This manual supersedes the HP OpenVMS Linker Utility Manual, Version 7.3
OpenVMS I64 Version 8.3
OpenVMS Alpha Version 8.3
Hewlett-Packard Company Palo Alto, California
© Copyright 2006 Hewlett-Packard Development Company, L.P.
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
The HP OpenVMS documentation set is available on CD-ROM.
Programmers at all levels of experience can use this manual effectively.
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
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
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.
Information about the Alpha or VAX object language formats used by the
linker can be found in the respective appendixes in the OpenVMS
Alpha/VAX Version 7.3 OpenVMS Linker Utility Manual, available
from the documentation bookshelf at the following URL:
For information on including the debugger in the linking operation and
about debugging in general, see the HP OpenVMS Debugger Manual.
For additional information about HP OpenVMS products and services,
visit the following World Wide Web address:
HP welcomes your comments on this manual. Please send comments to
either of the following addresses:
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:
The following conventions may be used in this manual:
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.
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
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
- 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 represents the introduction of a new term. It also represents
the name of an argument, an attribute, or a reason.
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).
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 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
All numbers in text are assumed to be decimal unless otherwise noted.
Nondecimal radixes---binary, octal, or hexadecimal---are explicitly
Introduction to the OpenVMS Linker
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.
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
- 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
I64, Alpha, or VAX might be used as prefixes as well. For example:
- I64 image---An OpenVMS I64 image that includes binary data and
- 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
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
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
- 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
- On VAX platforms, the object module is in the VAX Object Language
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
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
- 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.
more information, see Chapter 3 and Chapter 7.
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
The simple program shown in Example 1-1 prints the greeting
"Hello World!" on the terminal.
|Example 1-1 Hello World! Program
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:
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
routine is referenced by the module but is not defined in it. The
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:
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 188.8.131.52 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
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:
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