HP OpenVMS Systems Documentation

HP OpenVMS Linker Utility Manual

You can force the linker to allocate disk blocks for demand-zero segments by specifying the /NODEMAND_ZERO qualifier. The linker initializes the segment data with zeros and writes the segment data into the image file. Note that the linker still sorts the sections with the NOMOD attribute into separate segments.

To control which sections are placed in demand-zero segments, you must reset the NOMOD attribute of the section by using the PSECT_ATTR= option. The NOMOD attribute cannot be set by the programmer in source code or with linker options, but it can be cleared with PSECT_ATTR=psect-name,MOD.

If you set the EXE or VEC attributes for a section for which the compiler has set the NOMOD attribute, the linker issues a warning and sets the section attributes back to NOEXE and NOVEC. The linker creates a read-only demand-zero segment for a segment with the NOWRT attribute. See Part 4 for more information.

To request trailing zero compression, you have to use the PER_PAGE keyword for the /DEMAND_ZERO qualifier.

The DZRO_MIN= and the ISD_MAX= options are not supported on I64 systems. The linker ignores these options and produces informational messages. For further explanation of these options, see Part 4.

3.4.5 Creating ELF Sections in the Image File

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

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 a modification timestamp 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 writes global symbols into the image file under the following conditions:

• When you request a shareable image. (If you want to ship a shareable image that cannot be linked against, use /NOGST to exclude the global symbol from the shareable image file.)
• When you request a debug version of the image.

The Table 3-10 indicates where global symbol definitions are written during a link operation that uses the debugging qualifiers:

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.

3.4.6 Writing the Main Output Files

To complete the image creation the generated data has to be written to the image file. The linker prepares all the necessary ELF header tables, which are updated, when writing segments and ELF sections. The linker writes the headers, and sections, that is the contents of the linker buffers in the following order:

1. Temporary ELF header, temporary segment header table
2. All segments to the image file.
3. The traceback sections to the image or debug symbol file, unless /NOTRACEB specified in the LINK command.
4. The debug sections to the image or debug symbol file, in case /DEBUG was specified in the LINK command.
5. The remaining sections of the map to the map file, if requested in the LINK command. (These sections include all requested sections except the Object Module Synopsis, which it already wrote, and the Link Run Statistics, which it cannot write until the linking operation finishes.)
6. The global symbol table to the image file, and also to another separate file, if requested in the LINK command.
7. The supporting ELF sections to the image file.
8. The ELF section header table to the image file.
9. The updated ELF header and segment header table.
10. The link statistics to the map file, if requested in the LINK command.

This chapter describes how to create shareable images on OpenVMS I64 systems and how to declare universal symbols in shareable images.

4.1 Overview of Creating Shareable Images on I64 Systems

To create a shareable image, specify the /SHAREABLE qualifier on the LINK command line. You can specify as input files in the link operation any of the types of input files accepted by the linker, as described in Chapter 1.

Note, however, to enable other modules to reference symbols in the shareable image, you must declare them as universal symbols. You must declare universal symbols at link time using linker options. The linker lists all universal symbols in the global symbol table (GST) of the shareable image. For I64 images the GST is implemented as a set of symbols in the ELF symbol table (SYMTAB) in the shareable image. The linker processes the GST of a shareable image specified as an input file in a link operation during symbol resolution. (For more information about symbol resolution, see Chapter 2.)

For I64 linking, you declare universal symbols by listing the symbols in a SYMBOL_VECTOR= option statement in a linker options file. You do not need to create a transfer vector to create an upwardly compatible shareable image, as you do with OpenVMS VAX shareable images. The symbol vector can provide upward compatibility. For more information about this topic, see Section 4.2.

The linker supports qualifiers and options that control various aspects of shareable image creation. Table 4-1 lists these qualifiers and options. (For more information about linker qualifiers and options, see Part 4.)

To illustrate how to declare universal symbols, consider the programs in the following examples. Example 4-1 shows a shareable image test module; Example 4-2 shows the shareable image.

#include <stdio.h>

#pragma extern_model save
#pragma extern_model common_block
extern int my_data;
#pragma extern_model restore

extern int my_symbol;
extern int mysub( int, int );

main()
{
  int num1, num2, result;

  num1 = 7;
  num2 = 4;

  result = mysub( num1, num2 );
  printf("Result= %d\n", result);
  printf("Data implemented as overlaid psect= %d\n", my_data);
  printf("Global reference data is= %d\n", my_symbol);
}

#pragma extern_model save
#pragma extern_model common_block
int my_data = 5;
#pragma extern_model restore

int my_symbol = 10;

int add_data = -1;
int sub_data = -1;
int mul_data = -1;
int div_data = -1;


int myadd( int value_1, int value_2 )
{
  add_data = value_1 + value_2;
  return add_data;
}
int mysub( int value_1, int value_2 )
{
  sub_data = value_1 - value_2;
  return sub_data;
}
int mymul( int value_1, int value_2 )
{
  mul_data = value_1 * value_2;
  return mul_data;
}
int mydiv( int value_1, int value_2 )
{
  div_data = value_1 / value_2;
  return div_data;
}

You must use the extern common model to make the HP C for OpenVMS I64 compiler implement the symbol my_data as an overlaid section. The default model on HP C is relaxed/refdef. (For more information on the extern models and how they are enabled with pragmas or command qualifiers, see the HP C User's Guide for OpenVMS Systems.)

For I64 linking, you declare universal symbols by listing them in a SYMBOL_VECTOR= option. For each symbol listed in the SYMBOL_VECTOR= option, the linker creates an entry in the shareable image's symbol vector and creates an entry for the symbol in the shareable image's GST. When the shareable image is included in a subsequent link operation, the linker processes the symbols listed in its GST.

To enable images that linked against a shareable image to run with various versions of the shareable image, you must specify the identification numbers of the image. By default, the linker assigns a unique identification number to each version of a shareable image. At run time, if the ID of the shareable image as it is listed in the executable image does not match the ID of the shareable image the image activator finds to activate, the activation will abort. For information about using the GSMATCH= option to specify ID numbers, see the description of the GSMATCH= option in Part 4.

To implement Example 4-2 as an I64 shareable image, you must declare the universal symbols in the image by using the following LINK command:

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

You must identify the type of symbol vector entry you want to create by specifying a keyword. The linker allows you to create symbol vector entries for procedures, data (relocatable or constant), and for global data implemented as an overlaid section.

A symbol vector entry is a quadword that contains information about the symbol that can be used in subsequent fixups of images that are linked against the shareable image. The contents of the quadword depends on what the symbol represents. If the symbol represents a procedure (=PROCEDURE), the symbol vector entry contains the address of the function descriptor (FD). If the symbol represents a data (=DATA), the symbol vector entry contains the address of the data location. If the symbol represents a data constant (=DATA), the symbol vector entry contains the actual value of the constant. If the symbol represents a section (=PSECT) the symbol vector entry contains the address of the location of the section.

The linker fills in the symbol vector with values and addresses. The address calculations are based on the assumption that the shareable image will be mapped at the default start address of 10000 (hexadecimal). This is done despite the fact that the linker can not know where the image will be in memory, at run time. The linker also adds relocation information for the image activator to adjust the address values based on the actual start address of the shareable image, at activation time. This way, at run time, the symbol vector contains the actual code or data addresses.

When you create the shareable image (by linking it specifying the /SHAREABLE qualifier), the value of a universal symbol listed in the GST is the zero-based index in the quadword array, representing its entry in the symbol vector (expressed as the index z in Figure 4-1).

When you include this shareable image in a subsequent link operation, the linker leaves the address of the data, the address function descriptor of the external routine, or the address of the section empty in the linker-created short data. The linker creates a fixup for the executable image that references the symbol from the shareable image. The fixup includes the symbol's index in the symbol vector of the shareable image.

The following example illustrates how to link the object module MY_MAIN.OBJ with the shareable image MY_MATH.EXE.

$ LINK MY_MAIN, SYS$INPUT/OPT
MY_MATH/SHAREABLE
[Ctrl/Z]

At run time, when the image activator maps the shareable image into memory, it calculates the actual locations of the routines and relocatable data within the image and stores these values in its symbol vector. The image activator then fixes up the references to these symbols in the executable image. For a symbol representing constant data, the constant from the symbol vector is copied into the executable image. For a symbol representing relocatable data, the address of the data from the symbol vector is copied into the executable image. For a symbol representing a procedure the contents of the FD pointed to by the address in the symbol vector, the code address and the global pointer, is copied into the executable image. When the executable image makes a call to the procedure, shown as the branch (br.few) instruction sequence in Figure 4-1, control is transferred directly to the location of the procedure within the shareable image.

Figure 4-1 Accessing Universal Symbols Specified Using the SYMBOL_VECTOR = Option

Note that the images are being activated by the image activator with all relocations applied, pointing out a single fixup. That is, m and n are the virtual addresses after the image relocations are applied and gp is the relocated global pointer value.

Note also that, unlike VAX linking, global symbols implemented as overlaid sections are not universal by default. Instead, you control which of these symbols is a universal symbol by including it in the SYMBOL_VECTOR= option, specifying the PSECT keyword. The example declares the section my_data as a universal symbol.

4.2.1 Symbol Definitions Point to Shareable Image Sections

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

For example, the HP 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 HP C User's Guide for OpenVMS Systems.)

If the linker detects this condition, it issues the following error:

%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 HP C User's Guide for OpenVMS Systems.

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 linker maintains separate name spaces for global symbol names and section names. As described in Chapter 2, the section names are not used to resolve an undefined symbol. Because of the different name spaces, it is possible to specify an identical name in a symbol vector option when exporting a global symbol and a section. This depends on the main module's extern model and which entry in the symbol vector resolves or overlays a reference from the main module.

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

Use the GSMATCH mechanism to record any changes you make. GSMATCH handles the changes as follows:

• Major changes or incompatible changes, different orders of existing symbol vector entries, or deletion of entries most likely will result in a mismatch of the major ID number.
• Minor changes or compatible changes, or addition of new entries should result in a match of the major ID number but in a mismatch of the minor ID number.

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 Part 4.