Order Number: BA554-90004
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
© 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 countries.
ZK4548
The HP OpenVMS documentation set is available on CD-ROM.
| Contents | Index |
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 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.
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:
http://h71000.www7.hp.com/doc/os732_index.html |
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:
http://www.hp.com/go/openvms |
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 |
For information about how to order additional documentation, visit the following World Wide Web address:
http://www.hp.com/go/openvms/doc/order |
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:
|
|
.
. . |
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. |
This chapter introduces the OpenVMS Linker utility (the linker), describing its primary functions and its role in software development. The chapter describes the following:
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.
I64, Alpha, or VAX might be used as prefixes as well. For example:
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:
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
To create an image from the input files you specify, the linker performs the following primary functions:
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.
| Next | Contents | Index |