HP OpenVMS Linker Utility Manual

The linker resolves symbolic references with their definitions. For example, the program in Example 2-1 references the symbol mysub .

Example 2-1 Source File Containing a Symbolic Reference: MY_MAIN.C

#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 ); }

mysub , which Example 1 references, is defined in the program in Example 2-2.

Example 2-2 Source File Containing a Symbol Definition: MY_MATH.C

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; }

The GSD created by the language processor for the object module MY_MAIN.OBJ lists the reference to the symbol mysub . Because object modules cannot be examined using a text editor, the following representation of the GSD is taken from the output of the ANALYZE/OBJECT utility of the OpenVMS I64 object module MY_MAIN.OBJ.

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

1. In Example 2-2, MYSUB is defined in lowercase characters: mysub . The C compiler automatically upper cases all external symbol names unless you use the qualifier /NAMES=AS_IS.
2. The Symbol Type for MYSUB is STT_FUNC, which classifies MYSUB as a function (procedure). The linker checks the definition of mysub and make sure that its Symbol Type is also STT_FUNC. The linker issues an error if there is a discrepancy.
3. The Symbol Binding for MYSUB is STB_GLOBAL. For most applications, symbol types fall into two categories: global (STB_GLOBAL) and local (STB_LOCAL). Global symbols are visible across modules. Local symbols are visible only within the module.
4. References, or undefined symbols, are bound to a special section number which marks an undefined, missing, irrelevant or otherwise meaningless section (zero or SHDR$K_SHN_UNDEF). Definitions are bound to a section with a number greater than zero.
5. For references, the Symbol Value and the Size are not always known, and therefore are displayed as a zero.

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.

The following excerpt from an analysis of the OpenVMS I64 object module (performed using the ANALYZE/OBJECT utility) shows the format of a GSD symbol definition entry.

$ 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 Linkage Type 80 VMS_STL_STD Bound to section: 0003 3. "$CODE$" (1) Symbol Value 0000000000000020 32. (2) Size associated with sym: 0000000000000020 (3)

1. Since MYSUB is a procedure, it is associated with a code section.
2. The Symbol Value (32) is the byte offset of the code entry point into the section $CODE$.
3. The Size associated with the symbol is the amount of code in the routine (32 bytes).

When you link the modules shown in Example 2-1 and Example 2-2 together to create an image, you specify both object modules on the command line, as in the following example:

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

For I64 images, the value of a symbol that is a function can be expressed in two ways:

• If the linker has created a function descriptor (called a procedure descriptor on Alpha) the value is the address of the function descriptor. This is listed in the Symbol Cross Reference portion of the map with the suffix -R or in the Symbols By Value portion of the map with the prefix R-.
• If the symbol is a function, and the linker has not created a function descriptor, the value of a symbol is the location within the image of the entry point of the function. This information is listed in the Symbol Cross Reference portion of the map with the suffix -RC or in the Symbols By Value portion of the map with the prefix RC-. R is the label that means relocatable, and C is the label that means code address.

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.

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.

2.2.2 Processing Shareable Images

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.

For example, the program in Example 2-2 (in Section 2.2.1) can be implemented as a shareable image. (For information about creating a shareable image, see Chapter 4.) The shareable image can be included in the link operation as in the following example:

$ 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 Linkage Type 80 VMS_STL_STD Bound to section: 0008 8. "$LINKER RELOCATABLE_SYMBOL" Symbol Value 0000000000000001 1. Size associated with sym: 0000000000000000

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

2.2.2.1 Implicit Processing of Shareable Images

For VAX linking, when you specify a shareable image in a link operation, the linker not only resolves symbols from the shareable image you specify but it also resolves symbols from all shareable images that the shareable image has been linked against (that is, the shareable image's dependency list).

The I64 linker performs like the Alpha linker in that it does not automatically scan down a shareable image's dependency list to resolve symbols. Instead, on I64 an image's dependency list is in the dynamic segment. It appears in an analysis near the top of the file under the title Shareable Image List, as in the following example analysis of MY_MAIN.EXE:

$ 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. Section 2.2.3.1, Section 2.2.3.2, and Section 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.

For example, to create a library and insert the object module version of the program in Example 2-2 into the library, you could specify the following command:

$ LIBRARY/CREATE/INSERT MYMATH_LIB MY_MATH

The librarian includes the module in its module list and all of the global symbols defined in the module in its name table. To view the library's module list and name table, specify the LIBRARY command with the /LIST and /NAMES qualifiers, as in the following example:

$ LIBRARY/LIST/NAMES MYMATH_LIB Directory of ELF OBJECT library WORK:[PROGRAMS]MYMATH_LIB.OLB;1 on 3-NOV-2005 17:49:14 Creation date: 3-NOV-2005 17:48:57 Creator: Librarian I01-35 Revision date: 3-NOV-2005 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

You can specify the library in the link operation using the following command:

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

2.2.3.1 Identifying Library Files Using the /LIBRARY Qualifier

When the linker processes a library file identified by the /LIBRARY qualifier, the linker processes the library's name table and looks for the definitions of symbols referenced in previously processed input files.

Note that in order to resolve a reference to a symbol defined in a library, the linker must first process the module that references the symbol before it processes the library file. As such, while the order of object modules and shareable images is not usually important in a link operation, how you order library files can be important. (For more information about controlling the order in which the linker processes input files, see Section 2.3.)

Once the object module or shareable image is included from the library into the link operation, the linker processes all the symbol definitions in a shareable image, and symbol definitions and references in an object module. If you want the linker to selectively process object modules or shareable images that are included in the link operation from a library, you must append the Librarian utility's /SELECTIVE_SEARCH qualifier to the file specification of the object module or shareable image when you insert it into the library. Appending the linker's /SELECTIVE_SEARCH qualifier to a library file specification in a link operation is illegal. For more information about processing input files selectively, see Section 2.2.4.

Processing Object Module Libraries

When the linker finds a symbol in the name table of an object module library, it:

• Extracts from the library the object module that contains the definition and includes it in the link operation
• Processes the GSD of the object module extracted from the library, adding an entry to the linker's list of symbol definitions for every symbol defined in the object module, and adding entries to the linker's undefined symbol list for all the symbols referenced by the module (see Section 2.2.1)
• Continues to process the undefined symbol list until there are no definitions in the library for any outstanding references

When the linker finishes processing the library, it will have extracted all the modules that resolve references generated by modules that were previously extracted from the library.

Processing Shareable Image Libraries

When the linker finds a symbol in the name table of a shareable image library, it notes which shareable image contains the symbol and then looks for the shareable image to include it in the link operation. By default, the linker looks for the shareable image in the same device and directory as the library file

If the linker cannot find the shareable image in the device and directory of the library file, the linker looks for the shareable image in the directory pointed to by the logical name IA64$LIBRARY.

Once the linker locates the shareable image, it processes the shareable image as it does any other shareable image (see Section 2.2.2).

2.2.3.2 Including Specific Modules from a Library Using the /INCLUDE Qualifier

If the library file is specified with the /INCLUDE qualifier, the linker does not process the library's name table. Instead, the linker includes in the link operation modules from the library specified with the /INCLUDE qualifier and processes these modules as it would any other object module or shareable image.

If you append both the /LIBRARY qualifier and the /INCLUDE qualifier to a library file specification, the linker processes the library's name table to search for modules that contain needed definitions. When the linker finds an object module or shareable image in the library that contains a needed definition, it processes it as described in Section 2.2.3.1. In addition, the linker includes the modules specified with the /INCLUDE qualifier in the link operation and processes them as it would any other object module or shareable image.

2.2.3.3 Processing Default Libraries

In addition to the libraries you specify using the /LIBRARY qualifier or the /INCLUDE qualifier, the linker processes certain other libraries by default. The linker processes these default libraries in the following order:

1. Default user library files. You specify a default user library by associating the library with one of the linker's default logical names from the range LNK$LIBRARY, LNK$LIBRARY_1,... LNK$LIBRARY_999. If the /NOUSERLIBRARY qualifier is specified, the linker skips processing default user libraries. (For more information about defining a default user library, see the description of the /USERLIBRARY qualifier in the Linker command reference in Part 4.)
   If the default user library contains shareable images, the linker looks for the shareable image as described in Section 2.2.3.1.
2. Default system shareable image library file. The linker processes the default system shareable image library IMAGELIB.OLB by default unless you specify the /NOSYSSHR or the /NOSYSLIB qualifier.
   Note that when the linker needs to include a shareable image from IMAGELIB.OLB in a link operation, it always looks for the shareable images in IA64$LIBRARY. The linker does not look for the shareable image in the device and directory of IMAGELIB.OLB as it does for other shareable image libraries.
3. Default system object module library file. The linker processes the default system object library STARLET.OLB by default unless you specify the /NOSYSLIB qualifier.
   When the I64 linker processes STARLET.OLB by default, it also processes the shareable image (SYS$PUBLIC_VECTORS.EXE). This shareable image is needed to resolve references to system services.
   When STARLET is not processed by default (for example, when the /NOSYSLIB qualifier is specified), the linker does not process SYS$PUBLIC_VECTORS.EXE automatically, even if you explicitly specify STARLET.OLB in an options file.
   If you specify SYS$PUBLIC_VECTORS.EXE explicitly in an options file when it is already being processed by default, the linker displays the following warning:

   %ILINK-W-MULCLUOPT, cluster SYS$PUBLIC_VECTORS multiply defined in options file [filename]

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.

Processing input files selectively can reduce the amount of time a link operation takes and can conserve the linker's use of virtual memory. Note, however, that selective processing can also introduce dependencies on the ordering of input files in the LINK command.

For example, in the link operation in Section 2.2.2, 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.) 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.

If you append the /SELECTIVE_SEARCH qualifier to the shareable image file specification and all of the other input files are specified on the command line, the link will fail. In the following example, because the linker has no symbols on its undefined symbol list when it processes the shareable image file MY_MATH.EXE, it does not include any symbol definitions from the shareable image in its processing. When it subsequently processes the object module MY_MAIN.OBJ that references the symbol mysub , the linker cannot resolve the reference to the symbol. (For information about how to correct this link operation, see Section 2.3.1.)

$ 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. The following command creates the library MYMATH_LIB.OLB and inserts the file MY_MATH.OBJ into the library. (For more information about using the Librarian utility, see the HP OpenVMS Command Definition, Librarian, and Message Utilities Manual.)

$ LIBRARY/CREATE/INSERT MYMATH_LIB MY_MATH/SELECTIVE_SEARCH