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 OpenVMS x86-64 and OpenVMS I64 systems, the linker creates only native images—x86-64 images on x86-64 systems, I64 images on I64 systems.

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

On both OpenVMS Alpha and OpenVMS VAX systems, the linker supports /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 Chapter 10, LINK Command Reference). As a result, the linker can create VAX images on an Alpha system, and vice versa.

Image Types

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.

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 linkers 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 x86-64 and I64 object languages. As a result, the OpenVMS x86-64 and OpenVMS I64 linkers do not create this special type of image.

Input Files

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 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, “Specifying Input to the Linker” provides more information about all the types of input files accepted by the linker. Section 1.3, “Specifying Linker Output Files” provides more information about the output files created by the linker.

Figure 1.1, “Position of the Linker in Program Development” illustrates the relationship of the linker to the language processor in the program development process.

Different Image Layout on x86-64 and Itanium

When porting an application from Itanium to x86-64, be aware that the image layout may change in an incompatible way – although the compile and link commands/options did not change. This is an architectural difference.

On Itanium, the compiler may generate short data, which is accessed in an efficient way. See Section 3.2.1.5, “Short Data Sections (I64 Only)” for more information on short data.

On x86-64, there is no short data. All data defined in an object module will go where the module goes (except the defining PSECT which is moved with an explicit COLLECT option). That is, on x86-64, for partially protected shareable images, all data defined by an object module which is collected into a protected linker cluster will be protected. User-mode code in the shareable image cannot write to it.

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 Chapter 10, LINK Command Reference.

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

$ 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, “Hello World! Program (HELLO.C)”, the printf routine is referenced by the module but is not defined in it. The printf routine is defined in the VSI C Run-Time Library (DECC$SHR).

$ 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 2.2.3.3, “Processing Default Libraries” (x86-64 and I64) and Section 6.2.3.3, “Processing Default Libraries” (Alpha and VAX) 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 2, Understanding Symbol Resolution (x86-64 and I64) (x86-64 and I64) and Chapter 6, Understanding Symbol Resolution (Alpha and VAX) (Alpha and VAX) provide 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 systems, 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, Understanding Image File Creation (Alpha and VAX) provides more information about Alpha and VAX image creation.

On x86-64 and I64 systems, the linker gathers ELF sections with similar attributes 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, Understanding Image File Creation (x86-64 and I64) provides more information about creation of x86-64 and I64 images.

$ 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, “Options Files as Linker Input Files” describes the benefits of using options files and describes how to create them. Chapter 10, LINK Command Reference provides descriptions of the qualifiers and options supported by the linker. Section 1.4, “Controlling a Link Operation” contains a summary table of these qualifiers and options.

When a language processor translates a source language program, it produces an output file that contains one or more object modules. This output file, called an object file, has the default file type of .OBJ and is the primary form of linker input. At least one object file must be specified in any link operation. An object file may be specified in the command line or in an options file.

$ LINK HELLO

The linker processes the entire contents of an object file, that is, every object module in the file. It cannot selectively process object modules within an object file. The linker can process object modules selectively in an object module library (.OLB) file only.

You cannot examine an object module by using a text editor. The only way to examine an object file is by using the ANALYZE/OBJECT utility. This utility produces a report that lists the records that make up the object module. This report is primarily useful to compiler writers. For information about using the ANALYZE command, see the VSI OpenVMS DCL Dictionary: A–M.

A shareable image file consists of activation information, image binaries (code and data), and a symbol table. This symbol table contains definitions of universal symbols exported by the shareable image. A universal symbol is to a shareable image what a global symbol is to a module. That is, where a global symbol can be used to satisfy references external to an object module, a universal symbol can be used to satisfy references external to the shareable image.

MY_SHARE/SHAREABLE

$ LINK MY_MAIN_PROGRAM,MY_OPTIONS_FILE/OPTIONS

$ INSTALL ADD/SHARED WORK:[PROGRAMS]MY_SHARE.EXE

A library file is a file produced by the Librarian utility (default file type is .OLB). The linker accepts object module libraries and shareable image libraries as input files.

$ LIBRARY/CREATE/INSERT  MY_LIB MY_PROG

$ LIBRARIAN/LIST/NAMES MYMATH_LIB
Directory of ELF OBJECT library WORK:[PROGS]MYMATH_LIB.OLB;1 on 8-MAR-2019 09:59:06
Creation date:  8-MAR-2019 09:58:53       Creator:  Librarian I01-42
Revision date:  8-MAR-2019 09:58:53       Library format:   6.0
Number of modules:      1                 Max. key length:  1024
Other entries:          4                 Preallocated index blocks:    213
Recoverable deleted blocks:        0      Total index blocks used:        2
Max. Number history records:      20      Library history records:        0
Module MYMATHROUTS
MYADD
MYDIV
MYMUL
MYSUB

A symbol table file is the product of a previous link operation or a language processor. A symbol table file is similar to an object module but it contains only a symbol table.

For VAX linking, you can specify a symbol table file as input in a link operation as you would any other object module, as in the following example:

$ LINK MY_MAIN_PROGRAM, MY_SYMBOL_TABLE

The linker processes the symbol table file during symbol resolution. If the symbol table file is the by-product of a link operation in which an executable image or system image was created, the symbol table contains the names and values of every global symbol in the image. If the symbol table file is associated with a shareable image, it contains by default the names and values of the symbols in the image declared as universal.

For a symbol table file to be useful in link operations, the values associated with the symbols in the symbol table file must be constants. The value of symbols that represent addresses, such as a procedure entry point, can vary each time the image is activated (unless the image is based).

Note also that a symbol table file associated with a shareable image should not be specified as an input file in a link operation in place of the shareable image. The shareable image itself must be specified as input because the linker requires more information than can be found in a symbol table file, such as the memory requirements of the shareable image (contained in the image header).

Symbol table files created by the linker on 64-bit systems can be used as an aid to debugging with the System Dump Analyzer utility (SDA).

An options file is a standard text file you must use to specify linker options and shareable images specified as input files. You cannot specify linker options or shareable images on the LINK command line. Linker options, similar to linker qualifiers, allow you to control various aspects of the linker operation. Chapter 10, LINK Command Reference includes descriptions of the options supported by the linker.

MOD1.OBJ,MOD7.OBJ,LIB3.OLB/LIBRARY,-
LIB4/LIBRARY/INCLUDE=(MODX,MODY,MODZ),-
MOD12.OBJ/SELECTIVE_SEARCH
STACK=75
SYMBOL=JOBCODE,5

$ LINK PROGA,PROGB,PROJECT3/OPTIONS

If you precede the link operation with the SET VERIFY command, DCL displays the contents of the options file as the file is processed.

$ !  LINK command
$ LINK  MAIN,SUB1,SYS$INPUT/OPTIONS
MYPROC/SHAREABLE
SYS$LIBRARY:APPLPCKGE/SHAREABLE
STACK=75
$

$ LINK MAIN,SUB1,SUB2,SYS$INPUT:/OPTIONS
MYPROC/SHAREABLE
SYS$LIBRARY:APPLPCKGE/SHAREABLE
STACK=75
Ctrl/Z

$ @LINKPROC

An executable image is a file that can be executed by the RUN command.

On x86-64 and I64 systems, an executable image conforms to the ELF specification. Typically, this image consists of header tables, note sections containing the image identification information, a dynamic segment containing the image activation information and shareable image dependencies, and program segments containing the image binaries that define the memory requirements of the image.

On Alpha and VAX systems, an executable image is usually made up of an image header which contains image identification information and the image section descriptors (ISDs) that define the memory requirements and shareable image dependencies of the image binaries.

An executable image can reference one or more shareable images.

$ LINK HELLO

By default, the linker uses the name of the first input file specified as the name of the image file, giving the file the .EXE file type. However, you can alter this default naming convention. For more information, see the LINK command description in Chapter 10, LINK Command Reference.

A shareable image is similar in structure and content to an executable image, though it differs in the way that shareable program sections are sorted. To make use of a shareable image, include it in a link operation in which another image is created.

In x86-64 and I64 images, the symbol table is an ELF section that contains the symbol information.

In Alpha and VAX images, the symbol table resembles an appended object module that only contains the symbol information.

Note that the following LINK command includes an options file using SYS$INPUT. To make symbols in the shareable image available for other images to link against, you must declare them as universal symbols in a linker options file. The mechanism used to declare universal symbols for I64 and Alpha linking differs from VAX linking. For information and examples about creating and using shareable images, see Chapter 4, Creating Shareable Images (x86-64 and I64) (x86-64 and I64) and Chapter 8, Creating Shareable Images (Alpha and VAX) (Alpha and VAX).

$ LINK/SHAREABLE MY_SHARE, SYS$INPUT/OPTIONS
SYMBOL_VECTOR=(-
MY_ROUTINE=PROCEDURE,-
MY_COUNTER=DATA)
$

A system image is an image that does not run under the control of the operating system. It is intended for standalone operation only.

On x86-64 and I64 systems, system images have no special format; they are simply OpenVMS images that conform to the ELF specification. These system images might have constraints that you may have to address (for example, limits to the number of program segments).

By default, Alpha and VAX system images do not contain an image header, as do executable and shareable images. You can create a system image with a header by specifying the /HEADER qualifier. System images do not contain global symbol tables.

$ LINK/SYSTEM MY_SYSTEM_IMAGE

A symbol table file is like an object module that contains all the global symbol definitions in the image. You can create a symbol table for any type of image: executable, shareable, or system. For executable images and system images, the symbol table contains a listing of the global symbols in the image. For shareable images, the symbol table lists the universal symbols in the image.

On 64-bit systems, the symbol table files created by the linker cannot be used as input files in subsequent link operations.

For VAX linking, symbol table files can be specified as input files in link operations. For more information, see Section 1.2.4, “Symbol Table Files as Linker Input Files (VAX Only)”.

On all platforms, symbol table files are intended to be used with SDA as an aid to debugging.

$ LINK/SYMBOL_TABLE MY_EXECUTABLE_IMAGE

By default, the linker uses the name of the first input file specified as the name of the symbol table file, giving the file the .STB file type. However, you can alter this default naming convention. For more information, see the description of the /SYMBOL_TABLE qualifier in Chapter 10, LINK Command Reference.

To create an image map file, specify the /MAP qualifier on the LINK command line. In batch mode, the linker creates a map file by default. When you invoke the linker interactively (at the DCL command prompt), you must request a map explicitly. By default, the linker uses the name of the first input file specified as the name of the map file, giving the file the .MAP file type. However, you can alter this default naming convention. For more information, see the LINK command description in Chapter 10, LINK Command Reference.

$ LINK/MAP HELLO

You can determine the information contained in the image map by specifying additional qualifiers that are related to the /MAP qualifier. For example, by specifying the /BRIEF qualifier with the /MAP qualifier, you can generate a map file that contains only a subset of the total information that can be returned. For information about creating a map file and the contents of a map file, see Chapter 5, Interpreting an Image Map File (x86-64 and I64) (x86-64 and I64) and Chapter 9, Interpreting an Image Map File (Alpha and VAX) (Alpha and VAX).

$ LINK/DSF MY_PROJ.OBJ

By default, the linker uses the name of the first input file specified as the name of the DSF file, giving the file the .DSF file type. However, you can alter this default naming convention. For more information, see the description of the /DSF qualifier in Chapter 10, LINK Command Reference.

Note that linker options must be specified in a linker options file. (See Section 1.2.5, “Options Files as Linker Input Files” for information about creating linker options files and specifying them in link operations).

Symbols can be categorized by their scope, that is, the range of modules over which they are intended to be visible. Some symbols, called local symbols, are meant to be visible only within a single module. Because the definition and the references to these symbols must be confined to a single module, language processors such as compilers can resolve these references.

Other symbols, called global symbols, are meant to be visible to external modules. A module can reference a global symbol that is defined in another module. Because the value of the symbol is not available to the compiler processing the source file, it cannot resolve the symbolic reference. Instead, a compiler creates an ELF symbol table (SYMTAB) in an object module that includes all of the global symbol references and global symbol definitions it contains. These symbols are part of the global symbol directory (GSD).

On x86-64 and I64 systems, the GSD has a conceptual meaning. It no longer indicates an area within an object module, in which all named entities are listed. For ELF objects, the named entities for data and code are listed in the ELF symbol table; the name identities for sections are listed in the section header table. To use the traditional name GSD on x86-64 and I64 systems, the GSD can be seen as a subset of the ELF symbol table, plus a subset of the section header table.

In most programming languages, you can explicitly specify whether a symbol is global or local by setting or omitting particular attributes in the symbol definition or reference. For example, in C all functions are global symbols by default but the functions with the static attribute are local symbols.

In shareable images, symbols that are intended to be visible to external modules are called universal symbols. A universal symbol in a shareable image is the equivalent of a global symbol in an object module. Note, however, that only those global symbols that have been declared as universal are listed in the ELF symbol table (SYMTAB) of the shareable image and are available to external modules to link against. These symbols are part of the global symbol table (GST).

Similar to the GSD, the GST has a conceptual meaning on x86-64 and I64 systems; that is, it no longer indicates an area within an image file, in which all named entities are listed. For ELF images, the named entities for data and code are listed in the ELF symbol table and the named entities for sections are listed in the section header table. To use the traditional name GST on x86-64 and I64 systems, the GST can be seen as a subset of the ELF symbol table, plus a subset of the section header table.

You must explicitly declare universal symbols as part of the link operation in which the shareable image is created. For more information about declaring universal symbols, see Chapter 4, Creating Shareable Images (x86-64 and I64).

#pragma extern_model common_block
struct { int first; int second; } numbers;

INTEGER*4 first, second
COMMON /numbers/ first, second

/* module A */ #pragma extern_model relaxed_refdef int my_data;
/* module B */ #pragma extern_model relaxed_refdef int my_data;

During its first pass through the input files specified in the link operation, the linker attempts to find the definition for every symbol referenced in the input files. By default, the linker processes all the global symbols defined and referenced in the symbol table of each object module (GSD) and all the universal symbols defined in the global symbol table (GST) of each shareable image and any symbol defined by linker options. The definition of the symbol provides the value of the symbol. The linker substitutes this value for each instance where the symbol is referenced in the image being created. This value might not be the actual value of the virtual address at run-time, because the values might be relocated by the image activator.

The value of a symbol depends on what the symbol represents. A symbol can represent a routine entry point or a data location within an image. For these symbols, the value of the symbol is an address. A symbol can also represent a data constant (for example, the linker option SYMBOL=X,10). In this case, the value of the symbol is its actual value.

For symbols that represent addresses in object modules, the value is expressed initially as an offset into a section. (This is the manner in which language processors express addresses). Later in its processing, the linker determines the symbol's preliminary value after combining all module contributions into segments, which yields the proposed memory layout. For information about how the linker determines the virtual memory layout of an image, see Chapter 3, Understanding Image File Creation (x86-64 and I64).

For x86-64 and I64 images, at link time, the value of a symbol in a shareable image (as listed in the GST of the image) is the index of the symbol's entry in the symbol vector of the image.

An x86-64 symbol vector entry is a pair of quadwords. The contents of the two quadwords depend on whether the symbol represents a procedure entry point, data location, or absolute constant. For procedure entries, the first quadword is the procedure's canonical address (that is, its procedure value); and the second quadword is the procedure's actual entry address. For data locations and constant values, the first quadword contains the address, offset, or constant value, and the second quadword contains zero. Figure 2.1, “Symbol Vector Contents on x86-64” shows the contents of the x86-64 symbol vector at link time and at image activation time.

An I64 symbol vector entry is a quadword that contains the value of the symbol. The contents of the quadword depends on whether the symbol represents a procedure entry point, data location, or a constant. At link time, a symbol vector entry for a procedure entry point or a data location is expressed as an offset into the image. At image activation time, when the image is loaded into memory and the base address of the image is known, the image activator converts the image offset into a virtual address. Figure 2.2, “Symbol Vector Contents on I64” shows the contents of the I64 symbol vector at link time and at image activation time.

Note that the linker does not allow programs to make procedure calls to symbols that represent data locations.

Figure 2.3, “Symbol Resolution” illustrates the interdependencies created by symbolic references among the modules that make up an application. In the figure, arrows point from a symbol reference to a symbol definition. (The statements do not reflect a specific programming language).

$ LINK MY_MAIN  ! The module MY_MATH is omitted
%ILINK-W-NUDFSYMS, 1 undefined symbol:
 %ILINK-I-UDFSYM,        MYSUB
 %ILINK-W-USEUNDEF, undefined symbol MYSUB referenced
         section: $CODE$
         offset: %X0000000000000110  slot: 2
         module: MY_MAIN
         file: WORK:[PROGRAMS]MY_MAIN.OBJ;1

$ RUN MY_MAIN
%SYSTEM-F-CALLUNDEFSYM, Call using undefined function symbol
%TRACE-F-TRACEBACK, symbolic stack dump follows
image     module    routine     line      rel PC           abs PC
MY_MAIN                            0 00000000000101B2 00000000000101B2
MY_MAIN  MY_MAIN  main          1594 0000000000000120 0000000000010120
MY_MAIN  MY_MAIN  __main        1586 00000000000000C0 00000000000100C0
                                   0 FFFFFFFF80B7FB30 FFFFFFFF80B7FB30
DCL                                0 000000000006BD60 000000007AE25D60
%TRACE-I-END, end of TRACE stack dump

#include <stdio.h>
int mysub( int value_1, int value_2 );
main()
{
    int num1, num2, result;
    num1 = 5;
    num2 = 6;
    result = 0;
    result = mysub( num1, num2 );
    printf( "Result is: %d\n", result );
}

int myadd( int value_1, int value_2 )
{
    int result;
    result = value_1 + value_2;
    return result;
}
int mysub ( int value_1, int value_2 )
{
    int result;
    result = value_1 - value_2;
    return result;
}
int mymul( int value_1, int value_2 )
{
    int result;
    result = value_1 * value_2;
    return result;
}
int mydiv( int value_1, int value_2 )
{
    int result;
    result = value_1 / value_2;
    return result;
}

$ CC MY_MAIN.C
$ ANALYZE/OBJECT/SECTION=SYMTAB MY_MAIN.OBJ
   .
   .
   .
Description                  Hex <bitmask>    Decimal Interpretation
-----------                  ---------------  ------- --------------
Symbol 16. (00000010)        "MYSUB" 
  Name Index in Sec. 8.:            0000004C      76.
  Symbol Info Field:                      12
    Symbol Type:                          02          STT_FUNC 
    Symbol Binding:                       01          STB_GLOBAL 
  Symbol 'Other' Field:                   80
    Symbol Visibility                     00          STV_DEFAULT
      .
      .
      .
  Bound to section:                     0000       0. (SHDR$K_SHN_UNDEF) 
  Symbol Value              0000000000000000       0. 
  Size associated with sym: 0000000000000000

The GSD created by the language processor for the object module MY_MATH.OBJ contains the definition of the symbol mysub, as well as the other symbols defined in the module. The definition of the symbol includes the value of the symbol.

$ CC MY_MATH.C
$ ANALYZE/OBJECT/SECTION=SYMTAB MY_MATH.OBJ
   .
   .
   .
Description                  Hex <bitmask>  Decimal Interpretation
-----------                  -------------  ------- --------------
Symbol 12. (0000000C)        "MYSUB"
 Name Index in Sec. 8.:            00000027      39.
 Symbol Info Field:                      12
   Symbol Type:                          02          STT_FUNC
   Symbol Binding:                       01          STB_GLOBAL
 Symbol 'Other' Field:                   80
   Symbol Visibility                     00          STV_DEFAULT
     .
     .
     .
 Bound to section:                     0003       3. "$CODE$" 
 Symbol Value              0000000000000020      32. 
 Size associated with sym: 0000000000000020          

$ LINK MY_MAIN, MY_MATH 

When the linker processes these object modules, it reads the contents of the GSDs, obtaining the value of the symbol from the symbol definition.

The function descriptor created by the linker is a pair of quadwords that contain the Global Pointer (GP) for the image and the pointer to the entry point of the function. Note that on I64, the linker creates the function descriptors rather than the compiler. The linker also chooses the value for the GP, which is an address that the code segment uses to access the short data segment. It accesses different parts of the short data segment by using different offsets to the value the linker has chosen for the GP.

For x86-64 images, a function symbol's value is always a code address. There is no GP and no short data segment.

If the symbol is data, it can be either relocatable or not relocatable. The linker uses the R prefix or suffix in the map to indicate relocation.

When the linker processes a shareable image, it processes all the universal symbol definitions in the GST of the image. Because the linker creates the GST of a shareable image in the same format as an object module's symbol table, the processing of shareable images for symbol resolution is similar to the processing of object modules. The linker sets an attribute that flags the symbol as protected, which also indicates a universal symbol when the linker creates an image. Note that the linker includes only those universal symbols in the map file that resolve references, thus eliminating extraneous symbols in the linker map.

$ LINK/MAP/FULL MY_MAIN, SYS$INPUT/OPT
MY_MATH.EXE/SHAREABLE
Ctrl/Z

The GST created by the linker for the shareable image MY_MATH.EXE contains the universal definition of the symbol MYSUB, as well as the other symbols defined in the module.

Because images cannot be examined using a text editor, the following representations of the GST are taken from the output of the ANALYZE/IMAGE utility:

$ CC MY_MATH.C
$ LINK/MAP/FULL/CROSS/SHAREABLE MY_MATH.OBJ,SYS$INPUT/OPT
SYMBOL_VECTOR=(MYADD=PROCEDURE,-
               MYSUB=PROCEDURE,-
               MYMUL=PROCEDURE,-
               MYDIV=PROCEDURE)
Ctrl/Z
$ ANALYZE/IMAGE/SECTION=SYMTAB MY_MATH.EXE
Ctrl/Z
   .
   .
   .
  Symbol 3. (00000003)        "MYSUB"
    Name Index in Sec. 2.:            0000000D      13.
    Symbol Info Field:                      12
      Symbol Type:                          02          STT_FUNC
      Symbol Binding:                       01          STB_GLOBAL
    Symbol 'Other' Field:                   93
      Symbol Visibility                     03          STV_PROTECTED
      Function Type                         10          VMS_SFT_SYMV_IDX
       .
       .
       .
    Bound to section:                     0008       8. "$LINKER RELOCATABLE_SYMBOL"
    Symbol Value              0000000000000001       1.
    Size associated with sym: 0000000000000000

For x86-64 and I64 images, STV_PROTECTED indicates a universal definition. The "Symbol Type", STT_FUNC, indicates that this symbol represents a function (or procedure). The Function Type, VMS_SFT_SYMV_IDX, indicates that the symbol value (in this case 1) is the index into the symbol vector of the pointer to the function descriptor for MYSUB.

The analysis also lists all the indexes in the symbol vector. The following Index, which matches the previous value for the symbol, is 1.

SYMBOL VECTOR                         4. Elements
-------------                         -----------
Index   Value                         Size            Symbol or Section Name
-----   -----                         ----            ----------------------
    0.  0000000000002070 PROCEDURE                    "MYADD"
        0000000080000000
    1.  0000000000002080 PROCEDURE                    "MYSUB"
        0000000080000020
    2.  0000000000002090 PROCEDURE                    "MYMUL"
        0000000080000040
    3.  00000000000020A0 PROCEDURE                    "MYDIV"
        0000000080000060
            .
            .
            .

For I64 images, the entry in the symbol vector with the index value of 1, contains the value 30080, which is the address of a function descriptor for MYSUB. The function descriptor is a quadword pair. The first quadword is the address of the entry point for MYSUB (10020). The address 10020 is in a segment that has the execute flag set (that is, a code segment). The second quadword contains the global pointer chosen by the linker for the image (230000).

SYMBOL VECTOR                         4. Elements
-------------                         -----------
Index   Value                       Entry/GP or Size  Symbol or Section Name
-----   -----                       ----------------  ----------------------
    0.  0000000000030068 PROCEDURE  0000000000010000  "MYADD"
                                    0000000000230000
    1.  0000000000030080 PROCEDURE  0000000000010020  "MYSUB"
                                    0000000000230000
    2.  0000000000030098 PROCEDURE  0000000000010040  "MYMUL"
                                    0000000000230000
    3.  00000000000300B0 PROCEDURE  0000000000010090  "MYDIV"
                                    0000000000230000
            .
            .
            .

$ LINK/MAP/FULL/CROSS MY_MAIN,SYS$INPUT/OPT
MY_MATH.EXE/SHAREABLE
Ctrl/Z
$ ANALYZE/IMAGE MY_MAIN
   .
   .
   .
Image Activation Information, in segment 4.
     Global Pointer:                             0000000000240000
     Whole program FP-mode:                      IEEE DENORM_RESULTS
     Link flags
         Call SYS$IMGSTA
         Image has main transfer
         Traceback records in image file
     Shareable Image List
         MY_MATH
             (EQUAL, 9412., 468313704).
         DECC$SHR
             (LESS/EQUAL, 1., 1).

Libraries specified as input files in link operations contain either object modules or shareable images. The way in which the linker processes library files depends on how you specify the library in the link operation. Sections 2.2.3.1, 2.2.3.2, and 2.2.3.3 describe these differences. Note, however, that once an object module or shareable image is included from the library into the link operation, the linker processes the file as it would any other object module or shareable image.

$ LIBRARY/CREATE/INSERT MYMATH_LIB MY_MATH

$ LIBRARY/LIST/NAMES MYMATH_LIB
Directory of ELF OBJECT library WORK:[PROGRAMS]MYMATH_LIB.OLB;1 on 8-MAR-2019 17:49:14
Creation date:   8-MAR-2019 17:48:57      Creator:  Librarian I01-42
Revision date:   8-MAR-2019 17:48:57      Library format:   6.0
Number of modules:      1                 Max. key length:  1024
Other entries:          4                 Preallocated index blocks:    213
Recoverable deleted blocks:        0      Total index blocks used:        2
Max. Number history records:      20      Library history records:        0
 Module MY_MATH
MYADD
MYDIV
MYMUL
MYSUB

$ LINK/MAP/FULL/CROSS MY_MATH, MYMATH_LIB/LIBRARY

The map file produced by the link operation verifies that the object module MY_MATH.OBJ was included in the link operation.

By default, the linker processes all the symbol definitions and references in an object module or a shareable image specified as input in a link operation. However, if you append the /SELECTIVE_SEARCH qualifier to an input file specification, the linker processes from the input file only those symbol definitions that resolve references in previously processed input files.

For example, in the link operation in Section 2.2.2, “Processing Shareable Images”, the linker processes the shareable image MY_MATH.EXE before it processes the object module MY_MAIN.OBJ because of the way in which the linker clusters input files. (For information about how the linker clusters input files, see Section 2.3.1, “Understanding Cluster Creation”). When it processes the shareable image, the linker includes on its list of symbol definitions all the symbols defined in the shareable image. When it processes the object module MY_MAIN.OBJ and encounters the reference to the symbol mysub, the linker has the definition to resolve the reference.

$ LINK MY_MAIN, SYS$INPUT/OPT
MY_MATH.EXE/SHAREABLE/SELECTIVE_SEARCH
Ctrl/Z
%ILINK-W-NUDFSYMS, 1 undefined symbol:
%ILINK-I-UDFSYM,        MYSUB
%ILINK-W-USEUNDEF, undefined symbol MYSUB referenced
         section: $CODE$
         offset: %X0000000000000110  slot: 2
         module: MY_MAIN
         file: WORK:[PROGRAMS]MY_MAIN.OBJ;1

To process object modules or shareable images in a library selectively, you must specify the /SELECTIVE_SEARCH qualifier when you insert the module in the library. For more information about using the Librarian utility, see the VSI OpenVMS Command Definition, Librarian, and Message Utilities Manual.

As it parses the command line, the linker groups the input files you specify into clusters and places these clusters on a cluster list. A cluster is an internal linker construct that determines segment creation. The position of an input file in a cluster and the position of that cluster on the linker's cluster list determine the order in which the linker processes the input files you specify.

The linker always creates at least one cluster, called the default cluster. The linker may create additional clusters, called named clusters, depending on the types of input files you specify and the linker options you specify. If it creates additional clusters, the linker places them on the cluster list ahead of the default cluster, in the order in which it encounters them in the options file. The default cluster appears at the end of the cluster list. (Within the default cluster, input files appear in the same order in which they are specified on the LINK command line).

Clusters for shareable images, specified in shareable image libraries, appear after the default cluster on the cluster list because they are created later in linker processing, when the linker knows which shareable images in the library are needed for the link operation.

$ DEFINE LNK$LIBRARY  SYS$DISK:[]MY_DEFAULT_LIB.OLB
$ LINK  MY_MAIN.OBJ, MY_LIB.OLB/LIBRARY, SYS$INPUT/OPT
CLUSTER=MY_CLUS,,,MY_PROG.OBJ
MY_SHARE.EXE/SHAREABLE
MY_SHARE_LIB.OLB/LIBRARY
Ctrl/Z

The linker processes input files in cluster order, processing each input file starting with the first file in the first cluster, then processing the second file, and so on, until it has processed all files in the first cluster. The linker continues processing the input files in the second, and subsequent, clusters in the same manner. Processing concludes when the linker has processed all files in all clusters.

The linker records each symbol definition and each symbol reference in its internal global symbol table. For each symbol, the linker notes whether the symbol is strong, VMS-style weak, or UNIX-style weak.

The linker processes strong symbol definitions differently than it does UNIX-style weak symbol definitions (see Section 2.5.2, “Strong and Weak Definitions”). In general, a symbol can have only one strong or one VMS-style weak definition but it can have multiple UNIX-style weak definitions. When linking against libraries, note that there is also a difference between VMS-style weak and UNIX-style weak symbol definitions.

The linker processes weak references differently than it does strong references, although it handles both types of weak references in the same manner. Strong references must be resolved, whereas VMS-style and UNIX-style weak can be resolved optionally. If any weak symbol is not resolved, then the linker puts the value zero in place of the reference. In this case, the linker does not display a warning message.

By default, all global symbols generated by most x86-64 and I64 language processors are strong. That is, object modules usually contain strong symbol definitions and strong symbol references. You can decide to make some symbols VMS-weak definitions and references. To do so, you must use a language feature and explicitly mark the code or data as VMS-style weak. (For example, you would explicitly mark the code or data as VMS-style weak with the intention of performing a link operation on partially complete development code). See Section 2.5.1.2, “VMS-Style Weak Symbols” for more information about creating and using VMS-style weak symbols.

For some language constructs, the VSI C++ compiler generates UNIX-style weak symbols. That is, some object modules may contain strong and weak symbol definitions and references. The compiler produces redundant code or data in multiple object modules and the linker resolves to the first symbol encountered in the link operation.

An exception to the rules presented in Table 2.3, “Symbol Definition Handling” is for the special symbol, ELF$TFRADR, which defines the image entry point. Typically, each compiler defines one symbol for each module that contains code. If the module contains a main entry, then a strong symbol is defined. Conversely, if there is no main entry, a VMS-style weak symbol is defined (which behaves differently than a strong symbol).

This section describes how the x86-64 and I64 linkers process strong and weak references to resolve symbols. In general, a strong reference can be resolved by a strong symbol definition or any type of weak symbol definition.

For a strong reference, the linker searches all input files (explicit and implicit) for a definition of the symbol. If the linker cannot locate the definition needed to resolve the strong reference, it reports the undefined symbol and assigns the symbol a value, which usually results in a run-time error for accessing the data or calling the routine.

By default, most global definitions in x86-64 and I64 languages are strongly defined.

In the dialects of MACRO, BLISS, and Pascal supported on x86-64 and I64 systems, you can define a global symbol as either strong or VMS-style weak, and you can make either a strong or a VMS-style weak reference into a global symbol.

In these languages, all definitions and references are strong by default. To make a VMS-style weak definition or a VMS-style weak reference, you must use the .WEAK assembler directive (in MACRO), the WEAK attribute (in BLISS), or the WEAK_GLOBAL or WEAK_EXTERNAL attribute (in Pascal).

One purpose for making a weak reference is need to write and test incomplete programs. Resolving all symbolic references is crucial to a successful link operation. Therefore, a problem arises when the definition of a referenced global symbol does not yet exist. (This would be the case, for example, if the global symbol definition is an entry point to a module that is not yet written). The solution to this condition is to make the reference to the symbol VMS-style weak, which informs the linker that the resolution of this particular global symbol is not crucial to the link operation.

When linking modules, the first occurrence of a group makes its symbols known to the linker. The linker regards any additional occurrence of the group with the same name as redundant and therefore, ignores it.

Because the concept of groups (as described in the ELF specification) is limited to object modules, the use of shareable images requires a different approach: the VMS extension to ELF allows groups for shareable images. A shareable image group always takes precedence over groups found in object modules. For global symbols and identical groups, this means that all group symbols from an already processed group of an object module are replaced by the ones from the shareable image. The linker's intention is to always use the code and data from the shareable image.

The following VSI C++ examples demonstrate how symbols are resolved when you link with compiler-generated UNIX-style weak and group symbols.

The examples apply a user-written function template called myswap. Note that you can also use class templates, which are implemented in a similar manner. If you are an experienced C++ programmer, you will also recognize that there is a "swap" function in the VSI C++ standard library, which you should use instead of writing your own function.

In the examples, the compiler combines code sections (and other required data)into a group, giving it a unique group name derived from the template instantiation.

The linker includes the first occurrence of this group in the image. All UNIX-style weak definitions obtained from that group are now defined by the module providing this group. All subsequent groups with the same name do not contribute code or data; that is, the linker ignores all subsequent sections. The UNIX-style weak definitions from these ignored sections become references, which are resolved by the definition from the designated instance (that is, first-encountered instance) of the group. In this manner, code (and data) from templates are included only once for the image.

//  file: my_asc.cxx
template <typename T> 
void myswap (T &v1, T &v2) { 
        T tmp;
        tmp = v1;
        v1 = v2;
        v2 = tmp;
}
void ascending (int &v1, int &v2) {
        if (v2&lt;v1)
                myswap (v1,v2); 
}
//  file: my_desc.cxx
template <typename T> 
void myswap (T &v1, T &v2) { 
        T tmp;
        tmp = v1;
        v1 = v2;
        v2 = tmp;
}
void descending (int &v1, int &v2) {
        if (v1&lt;v2)
                myswap (v1,v2); 
}
//  file: my_main.cxx
#include <cstdlib>
#include <iostream>
using namespace std;
static int m = 47;
static int n = 11;
template <typename T> void myswap (T &v1, T &v2);
extern void ascending (int &v1, int &v2);
extern void descending (int &v1, int &v2);
int main (void) {
        cout << "original: " << m << " " << n << endl;
        myswap (m,n); 
        cout << "swapped: " << m << " " << n << endl;
        ascending (m,n);
        cout << "ascending: " << m << " " << n << endl;
        descending (m,n);
        cout << "descending: " << m << " " << n << endl;
        return EXIT_SUCCESS;
}

$ CXX/OPTIMIZE=NOINLINE/STANDARD=STRICT_ANSI MY_MAIN 
$ CXX/OPTIMIZE=NOINLINE/STANDARD=STRICT_ANSI MY_ASC  
$ CXX/OPTIMIZE=NOINLINE/STANDARD=STRICT_ANSI MY_DESC 
$ CXXLINK MY_MAIN, MY_ASC, MY_DESC                   

In the examples, the compiler combines code sections (and other required data) into a group, giving it a unique group name derived from the template instantiation.

To create a VMS shareable image, you must define the interface in a symbol vector at link time with a SYMBOL_VECTOR option. VSI C++ generated objects contain mangled symbols and may contain compiler-generated data, which belongs to a public interface. In the SYMBOL_VECTOR option, the interface is describe with the names from the object modules. Because they contain mangled names, such a relationship may not be obvious from the source code and the symbols as seen in an object module.

If you do not export all parts of an interface, code that is intended to update one data cell may be duplicated in the executable and the shareable image along with the data cell. That is, data can become inconsistent at run-time, producing a severe error condition. This error condition can not be detected at link time nor at image activation time. Conversely, if you export all symbols from an object module, you may export the same symbol which is already public from other shareable images.

A conflict arises when an application is linked with two shareable images that export the same symbol name. In this case, the linker flags the multiple definitions with a MULDEF warning that should not be ignored. This type of error most often results when using templates defined in the C++ standard library but instantiated by the user with common data types. Therefore, VSI recommends that you only create a shareable image when you know exactly what belongs to the public interface. In all other cases, use object libraries and let applications link against these libraries.

The VSI C++ run-time library contains pre-instantiated templates. The public interfaces for these are known and therefore, the VSI C++ run-time library ships as a shareable image. The universal symbols from the VSI C++ run-time library and the group symbols take precedence over user instantiated templates with the same data types. As with other shareable images, this design is upwardly compatible and does not require you to recompile or relink to make use of the improved VSI C++ run-time library.

Unlike the VAX and Alpha linkers, the x86-64 and I64 linkers create new sections as well as contributions to existing sections for loadable segments.

When the linker assigns a name for a section, the name can be a reserved name containing an embedded space (for example, $LINKER UNWIND$). The linker uses the embedded space in a reserved name to prevent you from changing the section attributes. The PSECT_ATTR option reads the embedded space and compresses it out of the name. As such, the name is not read by the linker as you intended and the attributes are preserved.

addl r15=<offset>,r1;;
ld8 r16=[r15],8
nop.i
-----
ld8 r1=[r15]
mov b6=r16
br.few b6;;   
-----

addl r15=<offset>,r1;;
ld8 r16=[r15]
nop.i
-----
nop.m
mov b6=r16
br.few b6;;   
-----

nop.m 0x0
movl r15=<offset between the next instruction and the target> 
-----
nop.m 0x0
mov r16=ip;;  
add r16=r15,r16;;
-----
nop.m 0x0
mov b6=r16
br.few b6;;   
-----

3.2.1.5. Short Data Sections (I64 Only)

In order to make position-independent code that does not require any relocations, Itanium platforms allow code to make a reference to pointers and other short data using offsets from an address in a register. This special register is called the Global Pointer (GP) register. The language processors place such data into sections named short data sections. It is the task of the linker to collect these sections into a segment or segments and to determine the GP value. The GP value is determined so that the beginning of the first (or only) short data segment is the negative-most offset from the GP within range. For the Intel Itanium architecture, the negative-most offset is 2 MB. Therefore, the GP value is the virtual address of the beginning of the first (or only) short data segment plus 2 MB. If the address range for your short data segment or segments is less than 2 MB, the GP value may not even point to a virtual address mapped by your image. The compilers usually place data in the short data sections that are relatively short (like quadwords or smaller) and not long (like an array).

There are two kinds of short data sections — read-only and read-write. The I64 linker is a major contributor to the read-only short data section. In this section, the linker puts addresses of data and function descriptors (termed procedure descriptors on Alpha) that can be reached by code with a short offset from the Global Pointer register. This section is named $LINKER SDATA$. In the map, <Linker> is used to label the linker contributions to this section.

Function descriptors placed in the read-only short data section have varying lengths depending on their type. The types are official and local. Official function descriptors are always three quadwords long. Local function descriptors can be two quadwords or four quadwords long, depending on whether the qualifier /NONATIVE_ONLY is present. If the image is supposed to interoperate with translated images, the /NONATIVE_ONLY qualifier must be used, and local function descriptors will be four quadwords long.

Official function descriptors represent functions that are defined by an image. One example of functions defined by an image are those functions which can be exported from a shareable image by the symbol vector and called by other images. Official function descriptors always contain the address of the first instruction of the function in the first quadword. The GP value under which the function executes is in the second quadword. The third quadword contains a zero, or if the /NONATIVE_ONLY qualifier is used it contains the function's signature or a pointer to the function's signature. A signature describes the parameters and return status of the function. If the third quadword is zero then the function descriptor has no signature, and a translated image is not allowed to call the function.

An official function descriptor has the following format at run-time:

A local function descriptor represents a function outside of the image. Local function descriptors made for images that do not interoperate with translated images contain at run-time the address of the first instruction of the function in the first quadword. The GP value under which the function executes is in the second quadword. The linker generates a fix-up for the function descriptor because it has no knowledge of those addresses. The fix-up is applied by the image activator which has already activated the image with those addresses in it.

A local function descriptor has the following format at run-time:

Local function descriptors made by the linker for images that can interoperate with translated images are four quadwords long. At run-time, after the image activator has determined that the target shareable image is translated, the four quadwords in the function descriptor contain the following:

• Entry (code) address of the routine that mediates calls between native and translated code

• Address of this function descriptor

• Signature information for the call

• Pointer to the official function descriptor for the entry point in the translated image (or some other unique identification that can be interpreted by the support facility the mediates calls between native and translated code)

The linker assumes the image activator will find a native image, and issues a fix-up to the image activator to fill in the first two (of four) quadwords with the code address and GP. The third quadword is filled in with signature information, like an official function descriptor. The fourth quadword is filled in with a zero. If the image activator determines that the function referenced by this function descriptor in a native image, it applies the fix-up and ignores the last two quadwords.

To create segments, the linker processes the section definitions in the input files you specify in the LINK command. The linker processes these input files on a cluster-by-cluster basis (as described in Section 2.3.1, “Understanding Cluster Creation”).

Each cluster spawns segments into which sections are placed. However, the linker crosses cluster boundaries when processing sections with the global (GBL) attribute. (In ELF, GBL corresponds to SHF_VMS_GLOBAL). When the linker encounters a section with the global attribute, it searches all the previously processed clusters for a section with the same name and attributes and, if it finds one, places the new definition of the global section in the same cluster as the first definition of the program section.

The linker processes input files in the order by which they appear in the clusters. Note that on x86-64 and I64 systems, there are no based clusters, that is, the x86-64 and I64 linkers do not allow you to enter a base address with the CLUSTER= option. In addition, the linkers only have to process clusters once.

For more information about creating clusters, see the descriptions of the CLUSTER= and the COLLECT= option in Chapter 10, LINK Command Reference.

$ LINK/MAP/FULL/CROSS MYTEST, MYADD, SYS$INPUT/OPT
CLUSTER=MYSUB_CLUS,,,MYSUB
Ctrl/Z

The linker always processes the default cluster after any user-specified cluster (MYSUB_CLUS). DECC$SHR was automatically picked up from IMAGELIB.OLB by the x86-64 and I64 linkers after the preceding clusters were processed and there were still unresolved symbols.

The linker creates segments by grouping together sections with similar attributes. Within a segment, the linker organizes sections alphabetically by name. If more than one object module contributes to the same section, the linker lays out their contributions in the order it processes them.

Figure 3.5, “Combining Sections into Image Segments — Part 1” shows how the linker groups the sections in the object modules from the sample link into segments, based on the setting of their significant attributes. In the figure, the settings of these significant attributes are represented by shading. (The figure considers attributes that are significant when creating executable images, and does not consider the SHR attribute as significant as it does with shareable images. Section 3.3.4, “Processing Significant Section Attributes” provides more information about which program section attributes are significant).

Note that in Figure 3.5, “Combining Sections into Image Segments — Part 1”, the relaxed definition from MYTEST.OBJ for GLOBAL_DATA appears in the MYSUB_CLUS cluster, even though the object module MYTEST.OBJ is in the default cluster. In general, the linker puts all contributions to a global section in the cluster in which it is first defined. In the relaxed case, the linker chooses the memory from the hard definition that occurs in MYSUB.OBJ.

Figure 3.6, “Combining Sections into Image Segments — Part 2” continues the representation in Figure 3.5, “Combining Sections into Image Segments — Part 1”.

Tables 3.4 and 3.5 list all the possible combinations of the significant section attributes for executable images and shareable images. Note that the order in which the combinations appear in the table (each row) is the same order in which the linker processes them.

For example, the linker first processes all sections with the WRT, NOEXE, NOVEC, MOD, and NOSHORT attributes, creating a segment of sections with these attributes. The linker then processes all sections with the WRT, NOEXE, NOVEC, NOMOD, and NOSHORT attributes, creating another segment for those sections. The linker continues this processing until all the combinations of significant attributes have been processed and all the sections in the cluster have been placed in a segment.

The tables include only sections that are relocatable (with the REL attribute). Absolute sections (with the ABS attribute), by definition, can have no allocation (they contain only constants) and cannot contribute to a segment.

To simplify the tables, they do not include the ALLOC_64BIT attribute. ALLOC_64BIT only determines if the section should be allocated in P2 space. The default is NOALLOC_64BIT. This attribute does not influence the segment attributes of the created segment. But obviously, two sections, whose attribute only differ in ALLOC_64BIT, end up in different segments. On I64, the ALLOC_64BIT attribute can be set for all sections except the ones with the SHORT attribute.

The linker creates additional segments that cannot be controlled by the user (see Section 3.4.3, “Other Image Segments”).

The tables assume that the images are linked using the /DEMAND_ZERO qualifier, which is the default. (When this qualifier is specified, the linker groups sections that do not contain any data into demand-zero segments, allocating memory for the segment but not writing zeros to disk). If the image is linked with the /NODEMAND_ZERO qualifier, then the linker allocates space for the segment in the image file. Note that the /NODEMAND_ZERO qualifier does not affect how the linker sorts sections; it proceeds exactly as specified by the table. However, when the image is written, the linker allocates disk space for the segment and fills the space with zeros.

The linker collects all these sections in segments in the named cluster MYSUB_CLUS, as requested with the CLUSTER= option in Example 3.6, “Linking Examples 3.1, 3.2, and 3.3”.

                                   +------------------------+
                                   ! Image Segment Synopsis !
                                   +------------------------+
Seg#  Cluster            Type       Base Addr     Protection  Attributes
----  -------            ----       ---------     ----------  ----------
   0  MYSUB_CLUS         LOAD       00010000      READ WRITE
   1                     LOAD       00020000      READ ONLY   EXECUTABLE
   2                     LOAD       00030000      READ ONLY
   3                     LOAD       00040000      READ ONLY   [UNWIND] 
   4  DEFAULT_CLUSTER    LOAD       00050000      READ WRITE
   5                     LOAD       00060000      READ ONLY   EXECUTABLE
   6                     LOAD       00070000      READ ONLY
   7                     LOAD       00080000      READ ONLY   [UNWIND] 
   8                     LOAD       00090000      READ ONLY   SHORT 
   9                     DYNAMIC  Q-00000000
                                    80000000      READ ONLY 

For more information about the image segment synopsis section of a map file, see Chapter 5, Interpreting an Image Map File (x86-64 and I64).

                               +--------------------------+
                               ! Program Section Synopsis !
                               +--------------------------+
Psect Name Module/Image   Base     End       Length            Attributes 
---------- ------------   ----     ---       ------            ----------
GLOBAL_DATA             00010000 00010003 00000004 (   4.) NOEXE,  WRT
           MYSUB        00010000 00010003 00000004 (   4.) Initializing Contribution
SUB_DATA                00010010 00010013 00000004 (   4.) NOEXE,  WRT
           MYSUB        00010010 00010013 00000004 (   4.) Initializing Contribution
$CODE$                  00020000 0002008F 00000090 ( 144.)   EXE,NOWRT
           MYSUB        00020000 0002006F 00000070 ( 112.)
           <Linker>     00020070 0002008F 00000020 (  32.)
$LITERAL$               00030000 0003000C 0000000D (  13.) NOEXE,NOWRT
           MYSUB        00030000 0003000C 0000000D (  13.)
$LINKER UNWIND$         00040000 00040017 00000018 (  24.) NOEXE,NOWRT
           MYSUB        00040000 00040017 00000018 (  24.)
$LINKER UNWINFO$        00040018 0004002F 00000018 (  24.) NOEXE,NOWRT
           MYSUB        00040018 0004002F 00000018 (  24.)
ADD_DATA                00050000 00050003 00000004 (   4.) NOEXE,  WRT
           MYADD        00050000 00050003 00000004 (   4.) Initializing Contribution
$CODE$                  00060000 000602CF 000002D0 ( 720.)   EXE,NOWRT
           MYTEST       00060000 000601BF 000001C0 ( 448.)
           MYADD        000601C0 0006022F 00000070 ( 112.)
           <Linker>     00060230 000602CF 000000A0 ( 160.)
$LITERAL$               00070000 0007003C 0000003D (  61.) NOEXE,NOWRT
           MYTEST       00070000 00070027 00000028 (  40.)
           MYADD        00070030 0007003C 0000000D (  13.)
$LINKER UNWIND$         00080000 00080047 00000048 (  72.) NOEXE,NOWRT
           MYTEST       00080000 0008002F 00000030 (  48.)
           MYADD        00080030 00080047 00000018 (  24.)
$LINKER UNWINFO$        00080048 000800A7 00000060 (  96.) NOEXE,NOWRT
           MYADD        000601C0 0006022F 00000070 ( 112.)
           <Linker>     00060230 000602CF 000000A0 ( 160.)
$LITERAL$               00070000 0007003C 0000003D (  61.) NOEXE,NOWRT
           MYTEST       00070000 00070027 00000028 (  40.)
           MYADD        00070030 0007003C 0000000D (  13.)
$LINKER UNWIND$         00080000 00080047 00000048 (  72.) NOEXE,NOWRT
           MYTEST       00080000 0008002F 00000030 (  48.)
           MYADD        00080030 00080047 00000018 (  24.)
$LINKER UNWINFO$        00080048 000800A7 00000060 (  96.) NOEXE,NOWRT
           MYTEST       00080048 0008008F 00000048 (  72.)
           MYADD        00080090 000800A7 00000018 (  24.)
$LINKER SDATA$          00090000 000900B7 000000B8 ( 184.) NOEXE,NOWRT,SHORT
           <Linker>     00090000 000900B7 000000B8 ( 184.)

For more information about the Program Synopsis Section of a map file, see Section 5.2.4, “Program Section Synopsis Section”.

When it creates a segment, the linker allocates enough memory for the image segment to accommodate all the sections it contains. Each section definition includes its size.

The linker aligns segments on CPU-specific page boundaries. Within a segment, the linker assigns to each section a virtual address relative to the base address of the segment.

Concatenated Sections

If the sections have the concatenated (CON) attribute set, the linker positions the sections one after the other within a segment, inserting padding bytes between the sections if necessary to achieve the alignment requirement of a particular contribution to a section. The linker retains the alignment specified for each section contribution but uses the largest alignment of a contributing module as the alignment of the whole section.

With a PSECT_ATTR= option you can align the section within the segment. However, aligning the section does not influence the alignment of the individual contributions to the section. The linker follows the compiler's alignment specification when it aligns each individual contribution. If you specify a smaller alignment for a section than any compiler-assigned alignment from all contributions, the linker issues a warning.

Overlaid Program Sections

If the sections have the overlaid (OVR) attribute set, the linker uses the same start address for the sections so that they occupy the same virtual memory (that is, the sections overlay each other). For overlaid sections, the linker allocates enough space to accommodate the largest of all the section contributions. Note that the linker does not generate a warning message if the contributions specify different size allocations.

Any module can initialize the contents of an overlaid program section. However, the x86-64 and I64 linkers only allow compatible initializations for the same section data. See Section 3.4.1, “Handling of Initialized Overlaid Sections” for an explanation of a compatible initialization.

Assigning Virtual Addresses

The linker allocates virtual memory to all the segments beginning at a page size boundary.

The x86-64 linker places code segments in the P2 region by default and uses the default page size of 2000 hexadecimal. The /SEGMENT=CODE=P0 option can be specified to place code segments in the P0 region. Non-code segments (without the ALLOC_64BIT attribute specified) are placed in the P0 region by default.

The I64 linker places segments in the P0 region by default and uses the default page size of 10000 hexadecimal. The /SEGMENT=CODE=P2 option can be specified to place segments in the P2 region.

For x86-64 and I64 linking, you can specify the page size value using the /BPAGE qualifier. For information about the /BPAGE qualifier, see Chapter 10, LINK Command Reference.

On x86-64 systems, the first P0 segment is placed at 2000 hexadecimal. On I64 systems, the first P0 segment is placed at 10000 hexadecimal, leaving the first page unused as a guard page. The first P2 segment (for example, containing sections with the ALLOC_64BIT attribute) is placed at 80000000 hexadecimal. However, all segment base addresses are only suggestions for the OpenVMS image activator. The image activator can determine a different base address for each segment (within the address region) to map the segment. This is always the case for shareable images. This is also the case for all images being installed as resident images, where the INSTALL utility determines the addresses. Unlike the Alpha and VAX platforms, executable images can also have their segment base addresses determined by the image activator or the INSTALL utility.

An image not activated by the OpenVMS image activator might need a specific base address for the first segment. For such an image, you can specify this address with the /BASE_ADDRESS qualifier. (For information about the /BASE_ADDRESS qualifier, see Chapter 10, LINK Command Reference).

Because the linker processes clusters in the order in which they appear in the cluster list, the virtual address space of the final image will generally contain contiguous segments of consecutive clusters on the basis of their order in the cluster list.

When creating segments, the linker assigns attributes to the segment based on the attributes of the sections it contains. The segment attributes describe certain characteristics of the portion of memory they represent, for example, the protection characteristics. For example, a segment that contains sections with the writability attribute also has the writability attribute set. Tables 3.4 and 3.5 include the segment attributes associated with a segment that contains sections with a particular set of attributes. Table 3.7, “Segment Attributes” lists all the segment attributes. Segment attributes, like section attributes, are Boolean values that are either on or off.

SEGMENT HEADER ENTRY 0.
Offset    Description                    Hex (<bitmask>)  Interpretation
------    -----------                    ---------------  --------------
00000000  Segment Type:                         00000001  PHDR$K_PT_LOAD
00000004  Segment Flags:                        00000006 
          Segment is writeable:                 <00000002> PHDR$M_PF_W
          Segment is readable:                  <00000004> PHDR$M_PF_R
00000008  Offset to Segment Data:       0000000000000400 
00000010  Memory Virtual Address:       0000000000010000 
00000018  Page Fault Cluster Size:      0000000000000000 
00000020  Segment Size in File:         0000000000000014 
00000028  Segment Size in Memory:       0000000000000014 
00000030  Alignment Constraint:         0000000000000010
SEGMENT HEADER ENTRY 1. (0001)               56. (0038) bytes
Offset    Description                    Hex (<bitmask>)  Interpretation
------    -----------                    ---------------  --------------
00000000  Segment Type:                         00000001  PHDR$K_PT_LOAD
00000004  Segment Flags:                        00000005 
          Segment is executable:                <00000001> PHDR$M_PF_X
          Segment is readable:                  <00000004> PHDR$M_PF_R
00000008  Offset to Segment Data:       0000000000000600 
00000010  Memory Virtual Address:       0000000000020000 
00000018  Page Fault Cluster Size:      0000000000000000 
00000020  Segment Size in File:         0000000000000090 
00000028  Segment Size in Memory:       0000000000000090 
00000030  Alignment Constraint:         0000000000000010
   .
   .
   .

On x86-64 and I64 systems, the ELF object language does not implement the feature of the Alpha and VAX object language which allows the initialization of portions of the sections. When an initializations made, the entire section is initialized. Subsequent initializations of this section can be performed only if they are compatible. A subsequent initialization is compatible if the number of initializers are less or equal to the existing ones and all the values match or if there are more initializers than the existing ones but all the existing values match.

%ILINK-E-INVOVRINI, incompatible multiple initializations for
 overlaid section
        section:  <section name>
        module:   <module name for first overlaid section>
        file:  <file name for first overlaid section>
        module:  <module name for second overlaid section>
        file:  <file name for second overlaid section>

In this message, the linker lists the first module, which contributes an initialization, and the first module with an incompatible initialization. Note that this is not a full list of all incompatible initializations; it is simply the first one that the linker encounters.

In the Program Section Synopsis of the linker map, each module with an initialization is flagged as Initializing Contribution. Use this information to identify and resolve all the incompatible initializations.

$ cre one.c
#pragma extern_model common_block
int common_data[]={0,1,2,3};
int main (void) {return 1;}
Ctrl/Z
$ cc one
$ cre two.c
#pragma extern_model common_block
int common_data[]={0,1};
Ctrl/Z
$ cc two
$ cre three.c
#pragma extern_model common_block
int common_data[]={0,1,2,3,4,5,6,7};
Ctrl/Z
$ cc  three
$ link/map one,two,three
$

                               +--------------------------+
                               ! Program Section Synopsis !
                               +--------------------------+

Psect Name Module/Image   Base     End       Length            Attributes
---------- ------------   ----     ---       ------            ------------

COMMON_DATA             00010000 0001001F 00000020 (  32.) OVR,NOEXE, WRT,NOVEC, MOD
           ONE          00010000 0001000F 00000010 (  16.) Initializing Contribution
           TWO          00010000 00010007 00000008 (   8.) Initializing Contribution
           THREE        00010000 0001001F 00000020 (  32.) Initializing Contribution

$ cre four.c
#pragma extern_model common_block
int common_data[]={0,1,0,0};
Ctrl/Z
$ cc /extern=common four
$ link one,two,three,four
%ILINK-E-INVOVRINI, incompatible multiple initializations for
 overlaid section
        section: COMMON_DATA
        module: ONE
        file: DISK$USER:[JOE]ONE.OBJ;1
        module: FOUR
        file: DISK$USER:[JOE]FOUR.OBJ;1

Note that the sources use a #pragma to force the extern common model. For OpenVMS, the default extern model is the relaxed reference/definition (ref/def) model. In that model, only one explicit initialization is allowed. That is, even identical initializations result in a linker MULDEF message.

An object module contains sections with compiler-initialized data. The linker copies the data into the corresponding segment buffer. For overlaid sections, subsequent data overwrites already existing data. With the compatibility check for overlaid sections, (as explained in Section 3.4.1, “Handling of Initialized Overlaid Sections”) the linker ensures, that existing data is only overwritten with identical values.

If the compilers initialized data with binary zeros, the buffer contains zeros as well. To save some disk space, the linker can check a segment buffer contents for trailing zeros. This time-consuming operation is not performed by default. You can request it with the PER_PAGE keyword for the /DEMAND_ZERO qualifier. Similar to a demand-zero section, the trailing zeros are not written to the image file. The amount of trailing demand-zero bytes for such a segment is expressed as the difference between the memory size (including these zeros) and the file size (excluding them). For information about the PER_PAGE keyword and the /DEMAND_ZERO qualifier, see Chapter 10, LINK Command Reference.

An object module can contain information to express link time calculations for addresses, offsets or values. For example, an offset between two global variables defined in two different object modules can be calculated by the linker and can be used to initialize another global variable. The link time expressions in the object modules are implemented in object relocations. The linker processes them similar to the other object relocations. The calculation is done in a linker internal accumulator and the results written into the corresponding buffer of the segment.

When this processing is complete, the linker has written the binary contents of all code and data sections into segment buffers in its own address space.

On OpenVMS, uninitialized static data is initialized with bytes of zeros. Language processors usually do not provide explicit bytes of zeros for uninitialized static data within the object file. Instead, they create conceptual sections filled with bytes of zeros. In ELF, these are sections with a section type specified as SHT_NOBITS (equivalent to the traditional NOMOD section attribute). These sections occupy virtual memory when the image is activated but do not occupy any space in the object file. As these sections are collected together, they will generate demand-zero segments in the image file that will occupy virtual memory at image activation time but do not occupy space in the image file (just as the NOBITS sections do in object files).

When a reference is made to data in a demand-zero segment at run-time, the operating system will map an in-memory page of zeros rather than having to access the image file on disk to load a page of zeros (a much slower process). Along with that benefit, demand-zero segments keep the image file size smaller.

If one or more contributions to a section do not have the NOMOD attribute set,the section is considered a non-demand-zero section and will be collected into anon-demand-zero segment.

On OpenVMS x86-64 and I64 systems, the linker can create demand-zero segments for both executable and shareable images. However, sections with the SHR and the NOMOD attributes set are not sorted into demand-zero segments in shareable images.

At run-time, uninitialized static data is identical to zero-initialized data. However, x86-64 and I64 language processors supply actual sections with bytes of zeros for static data explicitly initialized to zero in your source code. Such sections are not collected into demand-zero segments. However, the linker can search these non-demand-zero segment buffers for whole pages of trailing zero data and create demand-zero pages from them. Because this process, called trailing demand-zero compression, can be time-consuming, it is not done by default. To have this processing done, you must specify the PER_PAGE keyword in the /DEMAND_ZERO qualifier.

Trailing demand-zero compression reduces the size of the image file and usually enhances the performance of the program. As with demand-zero segments, a run-time reference made to data in a demand-zero page will cause the operating system to map an in-memory page of zeros rather than having to go out to disk for a block of zeros.

Debugger and traceback sections are processed only if you requested in the LINK command that the debug information be included using the /DEBUG qualifier and that the traceback information not be excluded using the /NOTRACE qualifier. Otherwise, this information is ignored. These sections contain their information in the Debugging With Attribute Record Format, or DWARF. DWARF information is kept in several sections, identified by a few section types and distinguished by name. You are not able to control these sections with the PSECT_ATTR= or the COLLECT= option clauses. Also, the linker does not collect these sections into segments.

The DWARF sections are combined according to their section type and are usually written into the image file. You can request that the debug information go into a separate file called a debug symbol file (DSF) by using the /DSF qualifier. For information about the /DSF qualifier, see Chapter 10, LINK Command Reference.

The linker saves some image information in the .note ELF section, referred to as the note section. It saves the link time and the linker ID,as well as the image name and the global symbol table name (GSTNAM). This section contains a copy of some of the original link-time value settings for additional fields that can be modified by the SET IMAGE command. Further, it contains a modification time stamp field, updated when the SET IMAGE command changes field values. Finally, it contains a modification timestamp the PATCH utility uses when it changes any data in the image file.

The linker creates the required ELF sections, to implement the symbol table. It creates a section named .symtab to contain the values and symbol attributes together with a pointer to a string section, .strtab, which contains the symbol names.

On x86-64 and I64 systems, the linker cannot overlay sections that are referenced by symbol definitions with shareable image sections of the same name.

For example, the VSI C compiler generates symbol definitions when the relaxed ref/def extern model is used (the default).

For hard symbol definitions, the compiler creates an overlaid section defining the memory requirements for that symbol. For tentative symbol definitions, there is no virtual memory allocated by the compiler. At link time, if there is no virtual memory for a symbol found, the linker creates an overlaid section defining the memory.

If an overlaid section was created for a symbol definition, such a section cannot be overlaid with shareable image sections that are created when you link a shareable image and use the PSECT keyword in your SYMBOL_VECTOR option. For more information on the extern models, see VSI C User Manual.

%LINK-E-SHRSYMFND, shareable image psect <name> was pointed
to by a symbol definition
%LINK-E-NOIMGFIL, image file not created

The link continues, but no image is created. To work around this restriction, change the symbol vector keyword to DATA, or recompile your C program with the qualifier /EXTERN=COMMON.

For more information, see the VSI C User Manual.

If the section specified in a SYMBOL_VECTOR= option does not exist, the linker issues a warning, places zeros in the symbol vector entry and does not create an entry for the section in the image's GST.

The SYMBOL_VECTOR= option allows you to create upwardly compatible shareable images. You can create a shareable image that can be modified, recompiled, and relinked without causing the images that were linked against previous versions of the image to be relinked.

To ensure upward compatibility when using a SYMBOL_VECTOR= option, you must preserve the order and placement of the entries in the symbol vector with each relinking. Do not delete existing entries and only add new entries at the end of the list. If you use multiple SYMBOL_VECTOR= option statements in a single options file to declare the universal symbols, you must also maintain the order of the SYMBOL_VECTOR= option statements in the options file. If you specify SYMBOL_VECTOR= options in separate options files, make sure the linker always processes the options files in the same order. (The linker creates only one symbol vector for an image).

By using the major and minor IDs in this manner, along with the LEQUAL keyword, you can create upwardly compatible shareable images. For example, a main image linked against minor ID 2 of a shareable image is not allowed to run against the shareable image with a minor ID less than 2, if the shareable image was linked with the keyword LEQUAL. For more information, see the description of the GSMATCH= option in Chapter 10, LINK Command Reference.

$ LINK/SHAREABLE MY_MATH, SYS$INPUT/OPT
GSMATCH=LEQUAL,1,1000
SYMBOL_VECTOR=(MYADD=PROCEDURE,-
               MYSUB=PRIVATE_PROCEDURE,-
               MYMUL=PROCEDURE,-
               MYDIV=PROCEDURE,-
               MY_SYMBOL=DATA,-
               MY_DATA=PSECT)
Ctrl/z

When you specify the PRIVATE_PROCEDURE or PRIVATE_DATA keyword in the SYMBOL_VECTOR= option, the linker creates symbol vector entries for the symbols but does not create an entry for the symbol in the GST of the image. The symbol still exists in the symbol vector and none of the other symbol vector entries have been disturbed. Images that were linked with previous versions of the shareable image that reference the symbol still work, but the symbol is not available for new images to link against.

Using the PRIVATE_PROCEDURE keyword, you can replace an entry for an obsolete procedure with a private entry for a procedure that returns a message that explains the status of the procedure.

If you use shareable images in your application, you may want to ship a run-time kit with versions of these shareable images that cannot be used in link operations.

To do this, you must first link your application, declaring the universal symbols in the shareable images using the SYMBOL_VECTOR= option so that references to these symbols can be resolved. After the application is linked, you must then relink the shareable images so that they have fully populated symbol vectors but empty global symbol tables (GSTs). The fully populated symbol vectors allow your application to continue to use the shareable images at run-time. The empty GSTs prevent other images from linking against your application.

To create this type of shareable image for a run-time kit (without having to disturb the SYMBOL_VECTOR= option statements in your application's options files), relink the shareable image after development is completed, specifying the /NOGST qualifier on the LINK command line. When you specify the /NOGST qualifier, the linker builds a complete symbol vector, containing the symbols you declared universal in the SYMBOL_VECTOR= option, but does not create entries for the symbols that you declared universal in the GST of the shareable image. For more information about the /GST qualifier, see Chapter 10, LINK Command Reference.

$ LINK/SHAREABLE MY_MATH, SYS$INPUT/OPT
GSMATCH=LEQUAL,1,1000
SYMBOL_VECTOR=(MYADD=PROCEDURE,-
               SUB_ALIAS/MYSUB=PROCEDURE,-
               MYMUL=PROCEDURE,-
               MYDIV=PROCEDURE,-
               MY_SYMBOL=DATA,-
               MY_DATA=PSECT)
Ctrl/Z

You can specify universal alias names for symbols that represent procedures or data; you cannot declare a universal alias name for a symbol implemented as an overlaid section. In link operations in which the shareable image is included, the calling modules must refer to the universal symbol by its universal alias name to enable the linker to resolve the symbolic reference.

$ LINK/SHAREABLE MY_MATH, SYS$INPUT/OPT
CASE_SENSITIVE=YES
SYMBOL_VECTOR=(MYADD=PROCEDURE,-
               myadd/MYADD=PROCEDURE,-
               MYSUB=PROCEDURE,-
               mysub/MYSUB=PROCEDURE,-
               MYMUL=PROCEDURE,-
               mymul/MYMUL=PROCEDURE,-
               MYDIV=PROCEDURE,-
               mydiv/MYDIV=PROCEDURE,-
               MY_SYMBOL=DATA,-
               my_symbol/MY_SYMBOL=DATA,-
               MY_DATA=PSECT)CASE_SENSITIVE=NO
Ctrl/Z

In a privileged shareable image, calls from within the image that use the alias name result in a fix-up and subsequent vectoring through the privileged library vector (PLV), which results in a mode change. Calls from within the shareable image that use the internal name are done in the caller's mode. (Calls from external images always result in a fix-up). For more information about creating a PLV, see the VSI OpenVMS Programming Concepts Manual, Volume I.

The first section that appears in a map file is the Object and Image Synopsis, which lists the name of each object or shareable image included in the link operation in the order in which they were processed. This section of the map file also includes other information about each module, arranged in columns. Example 5.1, “Object and Image Synopsis” shows the Object and Image Synopsis map.

                                           +---------------------------+
                                           ! Object and Image Synopsis !
                                           +---------------------------+
                                                                                    
Module/Image     File        Ident       Attributes      Bytes  Creation Date     Creator
------------     ----        -----    ----------------   -----  -------------     -------
GETJPI                       V1.0         Lkg     Dnrm    280   8-MAR-2019 15:50  VSI C X7.4-151
                 DISK$USER:[JOE]GETJPI.OBJ;1
DECC$SHR                     V8.3-00      Lkg               0  28-FEB-2019 10:57  Linker I02-68
                 SYS$COMMON:[SYSLIB]DECC$SHR.EXE;1
SYS$PUBLIC_VECTORS           X-3          Sel Lkg           0  28-FEB-2019 10:56  Linker I02-68
                 SYS$COMMON:[SYSLIB]SYS$PUBLIC_VECTORS.EXE;1


                 Key for Attributes
                +------------------------------------------+
                ! Sel  - Module was selectively searched   !
                ! Lkg  - Contains call linkage information !
                ! Dnrm - Denormal IEEE FP model            !
                +------------------------------------------+ 

Module/Image      File           Ident               Attributes
------------      ----           -----            ----------------
NONE                              V1.0                 Lkg
                  DISK1:[JOE]NONE.OBJ;1
NOFLOAT_CASE                                           Lkg RFP
                  DISK1:[JOE]NOFLOAT.OBJ;1
DNORM_CASE                                             Lkg     Dnrm
                  DISK1:[JOE]DENORM_W.OBJ;1
FAST_CASE                                              Lkg     Fast
                  DISK1:[JOE]FAST_W.OBJ;1
NEPCT_CASE                                             Lkg     Inex
                  DISK1:[JOE]INEXACT_W.OBJ;1
SPCL_CASE                                              Lkg     Spcl
                  DISK1:[JOE]SPECIAL_W.OBJ;1
UNDER_CASE                                             Lkg     Undr
                  DISK1:[JOE]UNDERFLOW_W.OBJ;1
DG_FL_CASE                                             Lkg     VXfl
                  DISK1:[JOE]VAXFLOAT_W.OBJ;1
DECC$SHR                          V8.2-00              Lkg
                  RESD$:[SYSLIB]DECC$SHR.EXE;1
SYS$PUBLIC_VECTORS                X-2              Sel Lkg
                  RESD$:[SYSLIB]SYS$PUBLIC_VECTORS.EXE;1



                 Key for Attributes
                +------------------------------------------+
                ! Sel  - Module was selectively searched   !
                ! Lkg  - Contains call linkage information !
                ! RFP  - Conforms to the reduced FP model  !
                ! VXfl - VAX Float FP model                !
                ! Dnrm - Denormal IEEE FP model            !
                ! Fast - Fast IEEE FP model                !
                ! Inex - Inexact IEEE FP model             !
                ! Undr - Underflow-to-zero IEEE FP model   !
                ! Spcl - Special FP model                  !
                +------------------------------------------+ 

The Image Segment Synopsis section of the linker map file (Example 5.3, “Image Segment Synopsis”) lists the image segments created by the linker. The image segments appear in the order in which the linker created them. The order of the segments depends on the order of the clusters as shown in the linker's image cluster synopsis (see Section 5.2.2, “Cluster Synopsis Section”). On x86-64 and I64 systems, segments of the shareable images which are included in the link operation are not listed in the Image Segment Synopsis.

                                             +------------------------+
                                             ! Image Segment Synopsis !
                                             +------------------------+
                                                                        
Seg#  Cluster            Type    Pglts   Base Addr  Disk VBN  PFC  Protection  Attributes
----  -------            ----    -----   ---------  --------  ---  ----------  ----------
   0  MYCLU              LOAD        1    00010000         2    0  READ WRITE
   1                     LOAD        1    00020000         0    0  READ WRITE  DEMAND ZERO
   2                     LOAD        1    00030000         3    0  READ ONLY   EXECUTABLE,SHARED
   3                     LOAD        1    00040000         4    0  READ ONLY   SHARED
   4                     LOAD        1    00050000         5    0  READ ONLY   [UNWIND]
   5  DEFAULT_CLUSTER    LOAD        1    00060000         6    0  READ ONLY   SHORT
   6                     DYNAMIC     2  Q-00000000
                                          80000000         7    0  READ ONLY


              Key for special characters above
                +----------------------+
                !   Q  - Quad Value    !
                +----------------------+

Segment Offset Modified:   0000000000000050  imr$q_rela_offset
Image Relocation Type:             00000081  imr$l_type
Segment Being Modified:            00000003  imr$l_rela_seg
Image Relocation Addend:   0000000000000000  imr$q_addend
Symbol Segment Offset:     0000000000000000  imr$q_sym_offset
Symbol Segment Number:             00000000  imr$l_sym_seg
Virtual Address Affected:  0000000000040050

                                            +--------------------------+
                                            ! Program Section Synopsis !
                                            +--------------------------+

Psect Name    Module/Image    Base    End         Length     Align               Attributes
----------      ------------      ----     ---           ------       -----                 ----------
ITMLET                          00010000 0001000F 00000010 (    16.) OCTA  4 OVR,REL,GBL,NOSHR,NOEXE, WRT,NOVEC, MOD
                GETJPI          00010000 0001000F 00000010 (    16.) OCTA  4 Initializing Contribution
FILLEN                          00020000 00020003 00000004 (     4.) OCTA  4 OVR,REL,GBL,NOSHR,NOEXE, WRT,NOVEC,NOMOD
                <Linker>      00020000 00020003 00000004 (     4.) OCTA  4
FILLM                           00020010 00020013 00000004 (     4.) OCTA  4 OVR,REL,GBL,NOSHR,NOEXE, WRT,NOVEC,NOMOD
                <Linker>        00020010 00020013 00000004 (     4.) OCTA  4
IOSB                            00020020 00020023 00000004 (     4.) OCTA  4 OVR,REL,GBL,NOSHR,NOEXE, WRT,NOVEC,NOMOD
                <Linker>        00020020 00020023 00000004 (     4.) OCTA  4
STATUS                          00020030 00020033 00000004 (     4.) OCTA  4 OVR,REL,GBL,NOSHR,NOEXE, WRT,NOVEC,NOMOD
                <Linker>        00020030 00020033 00000004 (     4.) OCTA  4
$CODE$                          00030000 0003015F 00000160 (   352.) OCTA  4 CON,REL,LCL, SHR, EXE,NOWRT,NOVEC, MOD
                GETJPI          00030000 0003015F 00000160 (   352.) OCTA  4
$LINKER C$0                     00030160 0003019F 00000040 (    64.) OCTA  4 CON,REL,LCL, SHR, EXE,NOWRT,NOVEC, MOD
                <Linker>      00030160 0003019F 00000040 (    64.) OCTA  4
$LITERAL$                       00040000 00040012 00000013 (    19.) OCTA  4 CON,REL,LCL,  SHR,NOEXE,NOWRT,NOVEC, MOD
                GETJPI          00040000 00040012 00000013 (    19.) OCTA  4
$LINKER UNWIND$                 00050000 0005002F 00000030 (    48.) QUAD  3 CON,REL,LCL,NOSHR,NOEXE,NOWRT,NOVEC, MOD
                GETJPI          00050000 0005002F 00000030 (    48.) QUAD  3
$LINKER UNWINFO$                00050030 0005005F 00000030 (    48.) QUAD  3 CON,REL,LCL,NOSHR,NOEXE,NOWRT,NOVEC, MOD
                GETJPI          00050030 0005005F 00000030 (    48.) QUAD  3
$LINKER SYMBOL_VECTOR$          00060000 00060007 00000008 (     8.) OCTA  4 CON,REL,GBL,NOSHR,NOEXE,NOWRT,NOVEC, MOD,SHORT
                <Linker Option> 00060000 00060007 00000008 (     8.) OCTA  4
$LINKER SDATA$                  00060008 000600AF 000000A8 (   168.) OCTA  4 CON,REL,GBL,NOSHR,NOEXE,NOWRT,NOVEC, MOD,SHORT
                <Linker>        00060008 000600AF 000000A8 (   168.) OCTA  4

There are two types of line entries: first type is a section entry (Psect Name); the second type are individual module contributions to that section (Module/Image).

The Symbols By Value section lists all the global symbols in the image in ascending order by value. The linker formats the information into columns. Example 5.6, “Symbols by Value” shows the Symbols By Value map section.

                                                +------------------+
                                                ! Symbols By Value !
                                                +------------------+
               
Value           Symbols...
-----           ----------
00000000        GETJPI (U)
0000009A      X-SYS$GETJPIW
00000496      X-DECC$TXPRINTF
00010000      R-ITMLST
00020000      R-FILLEN
00020010      R-FILLM
00020020      R-IOSB
00020030      R-STATUS
00060050      R-ELF$TFRADR
00060098      R-INTERNAL_GETJPI

              Key for special characters above
                +----------------------+
                !   *  - Undefined     !
                !  (U) - Universal     !
                !   R  - Relocatable   !
                !   X  - External      !
                !   C  - Code Address  !
                !  WK  - Weak          !
                ! UxWk - Unix-Weak     !
                +----------------------+

The Link Run Statistics section contains miscellaneous statistical information about the link operation, such as performance indicators. Example 5.8, “Link Run Statistics” shows the formatting of this section.

                                              +---------------------+
                                              ! Link Run Statistics !
                                              +---------------------+

Performance Indicators                            Page Faults   CPU Time        Elapsed Time
----------------------                            -----------   --------        ------------
    Command processing:                                    52   00:00:00.01     00:00:00.00
    Pass 1:                                               187   00:00:00.01     00:00:00.01
    Allocation/Relocation:                                 10   00:00:00.01     00:00:00.02
    Pass 2:                                               537   00:00:00.00     00:00:00.00
    Write program segments:                                15   00:00:00.01     00:00:00.05
    Symbol table output:                                    3   00:00:00.00     00:00:00.06
    Map data after object module synopsis:                  6   00:00:00.00     00:00:00.01
Total run values:                                         810   00:00:00.04     00:00:00.17

Quota usage                                      ByteCount  FileCount  PgFlCount
------------                                       ---------  ---------  ---------
    Available:                                        255616        128     700000
    Command processing:                                  384          3       7040
    Pass 1:                                              384          3       9504
    Allocation/Relocation:                               576          4       9504
    Pass 2:                                              384          3      17824
    Write program segments:                              576          4      17952
    Symbol table output:                                 384          3      17952
    Map data after object module synopsis:               384          3      17952

Using a working set limited to 18784 pages and 11105 pages of data storage (excluding image)

Number of modules extracted explicitly             = 0
    with 0 extracted to resolve undefined symbols

1 library searches were for symbols not in the library searched

A total of 1 global symbol table entries was written

LINK/MAP/FULL/CROSS/SHARE GETJPI/OPT
<DISK$USER:[JOE]GETJPI.OPT;1>
cluster=myclu,,,getjpi.obj
symbol_vector=(getjpi/internal_getjpi=procedure)

Performance of this link operation could be improved by increasing quotas
   Quota related to status return:  %SYSTEM-SECTBLFUL, process or global
   section table is full
2688 extra file I/O operations performed due to current process quota(s)
36 performed on object files; 2652 performed on library files

$ LINK MAIN, MAINLIB/LIB, ADDLIB/LIB, SUBLIB/LIB

Symbols can be categorized by their scope, that is, the range of modules over which they are intended to be visible. Some symbols, called local symbols, are meant to be visible only within a single module. Because the definition and the references to these symbols must be confined to a single module, language processors such as compilers can resolve these references.

Other symbols, called global symbols, are meant to be visible to external modules. A module can reference a global symbol that is defined in another module. Because the value of the symbol is not available to the compiler processing the source file, it cannot resolve the symbolic reference. Instead, a compiler creates a global symbol directory (GSD) in an object module that lists all of the global symbol references and global symbol definitions it contains.

In shareable images, symbols that are intended to be visible to external modules are called universal symbols. A universal symbol in a shareable image is the equivalent of a global symbol in an object module. Note, however, that only those global symbols that have been declared as universal are listed in the global symbol table (GST) of the shareable image and are available to external modules to link against.

Language processors determine whether a symbol is local or global. For example, in VAX FORTRAN, statement numbers are local symbols and module entry points are global symbols. In other languages, you can explicitly specify whether a symbol is local or global by including or excluding particular attributes in the symbol definition. Note also that some languages allow you to specify symbols as weak or strong (see Section 6.5, “Defining Weak and Strong Global Symbols” for more information).

On VAX systems, the VAX C language extensions globalref and globaldef allow you to create external variables that appear as symbol references and definitions in the GSD. For more information, see the VAX C documentation.

On Alpha systems, the VSI C compiler supports the globalref and globaldef language extensions. In addition, VSI C supports command line qualifiers and source code pragma statements that allow you to control whether it implements external variables as program sections or as global symbol references and definitions. For more information, see the VSI C documentation.

During its first pass through the input files specified in the link operation,the linker attempts to find the definition for every symbol referenced in the input files. By default, the linker processes all the global symbols defined and referenced in the GSD of each object module and all the universal symbols defined and referenced in the GST of each shareable image. The definition of the symbol provides the value of the symbol. The linker substitutes this value for each instance where the symbol is referenced in the image.

The value of a symbol depends on what the symbol represents. A symbol can represent a routine entry point or a data location within an image. For these symbols, the value of the symbol is an address. A symbol can also represent a data constant (for example, X = 10). In this case, the value of the symbol is its actual value (in the example, the value of X is 10).

For symbols that represent addresses in object modules, the value is expressed initially as an offset into a program section. This is how language processors express addresses. Later in its processing, when the linker combines the program sections contributed by all the object modules into the image sections that define the virtual memory layout of the image, it determines the actual value of the address. For information about how the linker determines the virtual memory layout of an image, see Chapter 7, Understanding Image File Creation (Alpha and VAX).

For symbols that represent addresses in a shareable image, the value of the symbol at link time is architecture specific.

For Alpha images, at link time, the value of a symbol in a shareable image (as listed in the GST of the image) is the offset of the symbol's entry in the symbol vector of the image. A symbol vector entry is a pair of quadwords that contain information about the symbol. The contents of these quadwords depend on whether the symbol represents a procedure entry point, data location, or a constant. Figure 6.1, “Symbol Vector Contents” illustrates the contents of a symbol vector entry for each of these three types of symbols. Note that, at link time, a symbol vector entry for a procedure entry point or a data location is expressed as an offset into the image. At image activation time, when the image is loaded into memory and the base address of the image is known, the image activator converts the image offset into a virtual address. Figure 6.1, “Symbol Vector Contents” shows the contents of the symbol vector at link time and at image activation time.

Note that the linker does not allow programs to make procedure calls to symbols that represent data locations.

For VAX images, at link time, the value of a symbol in a shareable image (as listed in the GST of the image) is the offset into the image of the routine or data location, if the symbol was declared universal using the UNIVERSAL=option. If the symbol was declared universal using a transfer vector, the value of the symbol is the offset into the image of the transfer vector entry. If the symbol represents a constant, the GST contains the actual value of the constant.

The actual value of an address symbol in a shareable image is determined at run-time by the image activator when it loads the shareable image into memory. The image activator relocates all the address references within a shareable image when it loads the image into memory. Once it has determined the absolute values of these addresses, the image activator fixes up references to these addresses in the image that linked against the shareable image. Previously, the linker created fix-ups that flag to the image activator where it must insert the actual addresses to complete the linkage of a symbolic reference to its definition in an image. The linker listed these fix-ups in the fix-up section it creates for the image. For more information about shareable images, see Chapter 8, Creating Shareable Images (Alpha and VAX).

For VAX images, you can specify the address at which you want a shareable image loaded into memory by using the BASE= option. When you specify this option, the linker can calculate the absolute addresses of symbols within the shareable image because the base address of the shareable image is known. By specifying a base address, you eliminate the need for the image activator to perform fix-ups and relocations.

Note, however, that basing a shareable image can potentially destroy upward compatibility between the shareable image and other images that were linked against it.

Figure 6.2, “Symbol Resolution” illustrates the interdependencies created by symbolic references among the modules that make up an application. In the figure, arrows point from a symbol reference to a symbol definition. (The statements do not reflect a specific programming language.)

$ link  my_main  ! The module MY_MATH is omitted
%LINK-W-NUDFSYMS, 1 undefined symbols:
 %LINK-I-UDFSYM,         MYSUB
 %LINK-W-USEUNDEF, undefined symbol MYSUB referenced
        in psect $CODE offset %X0000001A
        in module MY_MAIN file WORK:[PROGRAMS]MY_MAIN.OBJ;1

$ run my_main
%SYSTEM-F-ACCVIO, access violation, reason mask=00, virtual address=00000000,
PC=00001018, PSL=03C00000
%TRACE-F-TRACEBACK, symbolic stack dump follows
module name     routine name                 line   rel PC    abs PC
MY_MAIN         main                          15   00000018  00001018

The way the linker processes object modules to resolve symbolic references illustrates how the linker processes most other input files. (Symbol table files are object modules. The GST of a shareable image, which the linker processes in symbol resolution, is also created as an object module appended to the shareable image).

#include <stdio.h>
int mysub();
main()
{
   int num1, num2, result;
   num1   = 5;
   num2   = 6;
   result = 0;
   result = mysub( num1, num2 );
   printf("Result is: %d\n", result);
}

int myadd(int value_1,int value_2) {
   int result;
   result = value_1 + value_2;
   return( result);
}
int mysub(int value_1,int value_2)
   int result;
   result = value_1 - value_2;
   return( result);
}
int mymul(int value_1,int value_2)
   int result;
   result = value_1 * value_2;
   return( result);
}
int mydiv(int value_1,int value_2)
   int result;
   result = value_1 / value_2;
   return( result);
}

4.  GLOBAL SYMBOL DIRECTORY (EOBJ$C_GSD) , 344 bytes
               .
               .
               .
        9)  Global Symbol Specification (EGSD$C_SYM) 
                data type: DSC$K_DTYPE_Z (0)
                symbol flags:
                        (0)  EGSY$V_WEAK      0
                        (1)  EGSY$V_DEF       0
                        (2)  EGSY$V_UNI       0
                        (3)  EGSY$V_REL       0
                        (4)  EGSY$V_COMM      0
                        (5)  EGSY$V_VECEP     0 
                        (6)  EGSY$V_NORM      0 
                symbol: "MYSUB"

The GSD created by the language processor for the object module MY_MATH.OBJ contains the definition of the symbol mysub, as well as the other symbols defined in the module. The definition of the symbol includes the value of the symbol.

4.  GLOBAL SYMBOL DIRECTORY (EOBJ$C_GSD), 46 bytes
        .
        .
        .
        9)  Global Symbol Specification (EGSD$C_SYM)
                data type: DSC$K_DTYPE_Z (0)
                symbol flags:
                        (0)  EGSY$V_WEAK      0
                        (1)  EGSY$V_DEF       1
                        (2)  EGSY$V_UNI       0
                        (3)  EGSY$V_REL       1
                        (4)  EGSY$V_COMM      0
                        (5)  EGSY$V_VECEP     0
                        (6)  EGSY$V_NORM      1 
              psect: 3
              value: 64 (%X'00000040')
              code address psect: 5
              code address: 8 (%X'00000008')
                symbol: "MYSUB"
                 .
                 .
                 .