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

Note that the link command line and the linker options are part of the Link Run Statistics Section.

Example 5-7 Link Run Statistics

+---------------------+ ! 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(1) 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(2) A total of 1 global symbol table entries was written(3) LINK/MAP/FULL/CROSS/SHARE GETJPI/OPT <DISK$USER:[JOE]GETJPI.OPT;1> cluster=myclu,,,getjpi.obj symbol_vector=(getjpi/internal_getjpi=procedure)(3)

The following description corresponds to the callout number in the preceding linker map figure:

1. Quota usage. For I64, includes Quota usage information in the Link Run Statistics section. This information can help you to keep track of the quotas that are being used by the Linker. If quota issues occur, the linker is usually able to work around them. However, the linker outputs a special message to the Quota Usage section indicating what quota should be increased to improve performance. For example:

   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

2. Library searches were for symbols not in the library searched. When resolving undefined symbols, libraries are searched for definitions (see Chapter 2 for more information on symbol resolution). The printed number shows how often undefined symbols are not found in a library. For example, assume that module MAIN references the symbols MY_ADD and MY_SUB, which are defined by modules in ADDLIB.OLB and SUBLIB.OLB. Using the link command: $ LINK MAIN, MAINLIB/LIB, ADDLIB/LIB, SUBLIB/LIB
   if the MY_ADD and MY_SUB symbols are not found in MAINLIB, MY_SUB is not found in ADDLIB. This results in "3 library searches for symbols not in the library searched".
3. The number of global symbols written into a shareable image corresponds to the procedure and data entries in the symbol vector option. In this example, there is only a single entry in the symbol vector option.

5.3 Shortened Names with Footnotes in the Cross-Reference

The following example demonstrates how to read the footnotes. The long names were constructed for demonstration purpose only. In Example 5-8, the qualifiers /MAP/CROSS/FULL were specified to get both the cross-reference and the symbol value list.

Example 5-8 Shortened Symbol and Module Names

+------------------------+ ! Symbol Cross Reference ! +------------------------+ (1) (2) Symbol Value Defined By Referenced By ... ------ ----- ---------- ----------------- a_very_very_very_very_very_very_very_very_very_very_very_very_very_very_very_very_very_long_variable_name...[1] 00010000-R A_VERY_LONG_MODULE_NAME_JUST_F...[2] +------------------+ ! Symbols By Value ! +------------------+ (3) Value Symbols... ----- ---------- 00010000 R-a_very_very_very_very_very_very_very_very_very_very_very_very_very_very_very_very_lon...[1]

The items in the following list correspond to the numbered items in the preceding figure:

1. In the symbol cross reference, the symbol name does not fit on one line. The name is shortened, which is shown with the trailing ellipses. And index of the footnote is in the rightmost column.
2. In the symbol cross reference, the module name exceeds the size for the column Defined By. Again, ellipses show that the names is shortened and an index of the footnote is attached.
3. The same symbol shows in the Symbols By Value section. Even less space is provided to fit the symbol into the Symbols... column. The name, therefore, is shortened with ellipses and a footnote index is attached. Because this is the same symbol as in the Cross-Reference Section (although more shortened), the same index points to the same full name, and the entry in the footnote section.

Example 5-9 shows an example of a Cross Reference Footnotes section, automatically added by the linker.

Example 5-9 Cross Reference Footnotes

+---------------------------+ ! Cross Reference Footnotes ! +---------------------------+ (1) Index Full Symbol Name ----- ---------------- 1 a_very_very_very_very_very_very_very_very_very_very_very_very_very_very_very_long_variable_name _used_only_for_demonstration_purpose 2 A_VERY_LONG_MODULE_NAME_JUST_FOR_DEMO

1. In this example, the full name does not fit into the footnote column. The full symbol name will be wrapped to multiple lines, as necessary.

Some compilers mangle symbol names to implement language features (for example, overloading) or to use shortened, unique names. Ada and C++ compilers, for example, do so. The linker receives only mangled names from the compilers for resolving symbols and for exporting universal symbols. There is no general rule to derive a mangled name from a source code name or vice versa. If you need to know the source code name for a given mangled name, you need the demangler support from that programming language processor.

Recent compilers are able to add demangling information to the object modules. With this information and the language specific demangler routines (usually available with run-time libraries), the linker can create a translation table for mangled names. To obtain this table, use the DEMANGLED_SYMBOLS keyword for the /FULL qualifier when requesting a map. The linker lists all the global symbol definitions from the input object modules with their source code names. Example 5-10 shows a translation table in the linker map.

Example 5-10 Mangled/Demangled Symbols

+---------------------------+ ! Mangled/Demangled Symbols ! +---------------------------+ Symbol = Source Code Name ------------------------- CX3$ZN4RW22RWRDNRYXCHNGI2LM6VES(1) = "int __rw::__rw_ordinary_exchange<int, int>(int&, int const&)" CX3$_Z10DESCENDINGRIS_2OLL9N5 = "descending(int&, int&)"(2) CX3$_Z6MYSWAPIIEVRT_S1_1658A7V = "void myswap<int>(int&, int&)"(2) CX3$_Z9ASCENDINGRIS_162K6TK = "ascending(int&, int&)"(2) CXXL$ZN4RW10RWGARDC1ERNS1UGN3D2 = "__rw::__rw_guard::$complete$__rw_guard(__rw::__rw_mutex_base&)" CXXL$ZN4RW10RWGARDC2EPNS05KBR8A = "__rw::__rw_guard::$subobject$__rw_guard(__rw::__rw_mutex_base*)" CXXL$ZN4RW10RWGARDC9EPNS20LCU4S = "__rw::__rw_guard::__rw_guard(__rw::__rw_mutex_base*)" CXXL$ZN4RW10RWGARDC9ERNS2NGDC8S = "__rw::__rw_guard::__rw_guard(__rw::__rw_mutex_base&)" CXXL$ZN4RW17RWSTTCMTXB8C19J9SHI = "__rw::__rw_static_mutex<bool>::_C_mutex" CXXL$ZN4RW17RWSTTCMTXJ8C1AJH16C = "__rw::__rw_static_mutex<unsigned int>::_C_mutex" CXXL$ZN4RW20RWTMCXCHNGII0DCUDA8 = "int __rw::__rw_atomic_exchange<int, int>(int&, int const&, __rw::__rw_mutex_base&)" CXXL$ZNKST15BSCSTRAMBFCS03029KV = "std::basic_streambuf<char, std::char_traits<char> >::_C_write_avail() const" CXXL$ZNKST5CTYPEICE5WDNC2S864U0 = "std::ctype<char>::widen(char) const"

1. The translation table is sorted by the mangled names. Sorting the names by the source code name is not helpful. For example, the C++ source code function names contain the return type, which would determine the sort order rather than the function names.
   Note that the mangled names might contain a dollar sign ($) character. This does not necessarily indicate an OpenVMS reserved name.
2. The table only contains global symbol definitions from the object modules included in the link. However, there might be more names than expected; the compiler may generate some names (for example, when implementing C++ templates). In the map extract, "descending(int&, int&)", "void myswap<int>(int&, int&)" and "ascending(int&, int&)" are the user-defined template functions from the example Example 2-3. Other names are C++ generated names.

This chapter describes how the linker performs symbol resolution on OpenVMS Alpha and VAX systems. For information on performing symbol resolution on I64 systems, see Chapter 2.

As one of its primary tasks, the linker must resolve symbolic references between modules. This chapter describes how you can control the process to ensure that the linker resolves symbolic references as you intend.

6.1 Overview

Programs are typically made up of many interdependent modules. For example, one module may define a symbol to represent a program location or data element that is referenced by many other modules. The linker is responsible for finding the correct definition of each symbol referenced in all the modules included in the link operation. This process of matching symbolic references with their definitions is called symbol resolution.

6.1.1 Types of Symbols

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 for more information).

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

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 HP C compiler supports the globalref and globaldef language extensions. In addition, HP 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 HP C documentation.

6.1.2 Linker Symbol Resolution Processing

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

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 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 shows the contents of the symbol vector at link time and at image activation time.

Figure 6-1 Symbol Vector Contents

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

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

Figure 6-2 Symbol Resolution

The linker creates an image even if it cannot find a definition for every symbol referenced in the input files it processes. The linker reports these undefined symbols as in the following example, if at least one of these unresolved references is a strong reference. (For information about strong and weak symbolic references, see Section 6.5.) The linker includes the message in the map file, if a map file was requested.

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

1. The linker issues an informational message for each symbol for which it cannot find a definition.
2. The linker issues a warning message for each instance where an undefined symbol is referenced in the image.

If you run an image that contains undefined symbols and the symbols are never accessed, the program will run successfully. If you run an image that contains undefined symbols and the image accesses the symbols at run time, the image will abort, in most cases, with an access violation because the linker assigns the value zero to undefined symbols, as in the following example:

$ 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