Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]
OpenVMS Linker Utility Manual

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.

© Compaq Computer Corporation 1999. All rights reserved.

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.

Related Documents

For information on including the debugger in the linking operation, and on debugging in general, see the OpenVMS Debugger Manual.

For additional information on the Open Systems Software Group (OSSG) products and services, access the following OpenVMS World Wide Web address:


http://www.openvms.digital.com 

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:

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:

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.

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


Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
4548PRO.HTML