Document revision date: 30 March 2001

## OpenVMS Linker Utility Manual

Previous | Contents | Index

The linker puts both the DATA and $CHAR_STRING_CONSTANTS program sections in the same image section because they both have the same settings of significant attributes. Within the image section, the linker organizes the program sections alphabetically, so the $CHAR_STRING_CONSTANTS program section appears before the DATA program section. The linker creates a separate image section for the $CODE program section.

The linker performs similar processing of the program sections in the default cluster. The Image Section Synopsis section of the map file lists the clusters the linker created and lists the image sections it created for each cluster. This section also describes the layout of the image in memory, including the base address of each image section. Example 3-6 illustrates an excerpt of the Image Section Synopsis section from the map file produced with the sample link. The listing includes clusters for contributions for the VAX C Run-Time Library.

Example 3-6 Image Section Information in a Map File

                                                 +------------------------+
                                                 ! Image Section Synopsis !
                                                 +------------------------+

       Cluster      Type Pages   Base Addr  Disk VBN PFC Protection and Paging      ...
       -------      ---- -----   ---------  -------- --- ---------------------

    MYSUB_CLUS         0     1    00000200        2   0  READ WRITE   COPY ON REF
                       0     1    00000400        3   0  READ ONLY

    VAXCRTL            3     4    00000000-R      0   0  READ ONLY
                       3     1    00000800-R      0   0  READ ONLY
                       4     1    00000A00-R      0   0  READ WRITE   COPY ON REF
                       3    17    00000C00-R      0   0  READ ONLY
                       3   142    00002E00-R      0   0  READ ONLY
                       4    21    00014A00-R      0   0  READ WRITE   COPY ON REF
                       4     1  P-00017400-R      0   0  READ WRITE   COPY ON REF
                       2     3    00017600-R      0   0  READ WRITE   FIXUP VECTORS

    LIBRTL             3   193    00000000-R      0   0  READ ONLY
                       4     8    00018200-R      0   0  READ WRITE   DEMAND ZERO

    MTHRTL             3   335    00000000-R      0   0  READ ONLY
                       2     1    00029E00-R      0   0  READ WRITE   FIXUP VECTORS

    DEFAULT_CLUSTER    0     1    00000600        4   0  READ WRITE   COPY ON REF
                       0     1    00000800        5   0  READ ONLY
                       0     1    00000A00        6   0  READ WRITE   FIXUP VECTORS
                     253    20    7FFFD800        0   0  READ WRITE   DEMAND ZERO

For more information about the image section synopsis section of a map file, see Section 5.2.3.

To find out which program sections the linker placed in each image section, look at the Program Section Synopsis section of the map file. This section lists all the program sections in each cluster and lists the contributions (the number of bytes) to each program section from each object module. By comparing the base-address of the program sections with the base-addresses of the image sections in the Image Section Synopsis section, you can tell in which image section the program sections appear. Example 3-7 is an excerpt from the Program Section Synopsis section of the map file produced by the sample link operation.

Example 3-7 Program Section Information in a Map File (VAX Example)

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

    Psect Name Module Name   Base     End      Length        Align      Attributes
    ---------- -----------   ----     ---      ------        -----      ----------

    $DATA                  00000200 00000203 00000004 (  4.) LONG 2 PIC,USR,CON...
               MYSUB       00000200 00000203 00000004 (  4.) LONG 2

    GLOBAL_DATA            00000204 00000207 00000004 (  4.) LONG 2 PIC,USR,OVR...
               MYSUB       00000204 00000207 00000004 (  4.) LONG 2
               MYTEST      00000204 00000207 00000004 (  4.) LONG 2

    $CODE                  00000400 0000040B 0000000C ( 12.) LONG 2 PIC,USR,CON...
               MYSUB       00000400 0000040B 0000000C ( 12.) LONG 2

    $CHAR_STRING_CONSTANTS 00000600 0000062D 0000002E ( 46.) LONG 2 PIC,USR,CON...
               MYTEST      00000600 00000623 00000024 ( 36.) LONG 2
               MYADD       00000624 0000062D 0000000A ( 10.) LONG 2

    $DATA                  00000630 00000637 00000008 (  8.) LONG 2 PIC,USR,CON...
               MYTEST      00000630 00000633 00000004 (  4.) LONG 2
               MYADD       00000634 00000637 00000004 (  4.) LONG 2

    $CODE                  00000800 00000858 00000059 ( 89.) LONG 2 PIC,USR,CON...
               MYTEST      00000800 0000083E 0000003F ( 63.) LONG 2
               MYADD       00000840 00000858 00000019 ( 25.) LONG 2
       .
       .
       .

For more information about the program synopsis section of a map file, see Section 5.2.4.

### 3.3.4 Allocating Memory for Image Sections

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

The linker aligns image sections on CPU-specific page boundaries. Within an image section, the linker assigns to each program section a virtual address relative to the base address of the image section.

Concatenated Program Sections

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

Overlaid Program Sections

If the program sections have the overlaid (OVR) attribute set, the linker uses the same start address for the program sections so that they occupy the same virtual memory (that is, the program sections overlay each other). For overlaid program sections, the linker allocates enough space to accommodate the largest of all the program 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 final contents of the program section are determined by the last contributing module. Therefore, the order in which you specify the input modules is important.

Assigning Virtual Addresses

The linker keeps track of free (available) virtual addresses by maintaining a free virtual memory list. For each cluster, the linker determines the number of pages required, searches the list beginning at the lowest virtual address for a contiguous number of pages large enough to contain the cluster, allocates those addresses to the cluster, then removes those addresses from the list.

The linker allocates virtual memory to the first cluster beginning at a page size boundary for executable images in the P0 region of the user's virtual address space, unless the cluster is based, in which case it allocates virtual memory beginning at the specified address. For VAX linking, the default is 512 (200 hexadecimal). However, you can specify the page size using the /BPAGE qualifier. (For information about the /BPAGE qualifier, see Part 2.)

On its first pass through the cluster list, the linker allocates virtual addresses to any based user clusters or based shareable image clusters on the cluster list, removing the allocated addresses from the free virtual memory list as it proceeds. On its second pass, it repeats this procedure for nonbased user clusters. (Remember that nonbased shareable image clusters will have memory allocated for them at run time.)

Because the linker processes clusters in the order of their appearance on the cluster list, the virtual address space of the final image will generally contain contiguous image sections of consecutive clusters on the basis of their order in the cluster list. The presence of based clusters, however, may prevent such an outcome, and for this reason they are not recommended.

After allocating memory for a cluster, the linker relocates its contents by performing the following processing:

1. Relocating each image section. The linker adds the starting virtual address of the cluster to the relative offset of the image section from the cluster base and places the result in the appropriate field of the image section descriptor (ISD).
2. Relocating each program section in the image section. The linker adds the newly calculated starting virtual address of the image section to the relative offset of the program section from the base of the image section.
3. Relocating each global symbol in the program section. The linker adds the newly calculated program section virtual address to the relative offset of the global symbols from the base of the program section.

### 3.3.5 Image Section Attributes

When it creates image sections, the linker assigns attributes to the image section based on the attributes of the program sections it contains. The image section attributes describe certain characteristics of the portion of memory they represent, for example, the protection characteristics. For example, an image section that contains program sections with the writability attribute also has the writability attribute set. Table 3_2 and Table 3-3 include the image section attributes associated with an image section that contains program sections with a particular set of attributes. Table 3-5 lists all the image section attributes. Image section attributes, like program section attributes, are Boolean values that are either on or off.

Table 3-5 Image Section Attributes
Attribute | Symbol | Function
--- | --- | ---
Global | [E]ISD$M_GBL | GBL is set when the ISD came from a shareable image. On both VAX and Alpha systems, the first ISD of a shareable image is included in the base image for use by the image activator. For VAX linking, if the shareable image is based, all of its ISDs are included in the image being linked.
Copy On Reference | [E]ISD$M_CRF | CRF is set whenever the psect attributes are WRT and not SHR. CRF is also set by the linker whenever it creates fix-ups to the section (which require the image activator to write to it).
Demand Zero | [E]ISD$M_DZRO | Demand zero is set for VAX linking for executable images if: The section was never written to with a TIR (Text and Information Relocation) command. The section resulted from compression of empty pages from an existing section. Demand zero is set for Alpha executable and Alpha shareable images if the user has not specified /NODEMAND_ZERO and if: The section was never written to with an ETIR command. The program sections in the section have the NOMOD bit set. DZRO is always set for stack ISDs on both VAX images and Alpha images.
Executability | [E]ISD$M_EXE | The EXE attribute is inherited from the program section.
Write | [E]ISD$M_WRT | The WRT attribute is inherited from the program section. WRT is also set by the linker if fix-ups are made to the section. When this is done, the linker also generates a change protection fix-up so that the image activator can change the protection back to NOWRT after the fix-up is applied.
Match Control | ISD$M_MATCHCTL | This is used only for VAX images. It is not an attribute. MATCHCTL is a 3-bit field inside the flags field. It contains the match control bits. For Alpha images, this information is contained in a completely separate field.
Last Cluster | [E]ISD$M_LASTCLU | LASTCLU is set only for sections in executable images. LASTCLU indicates that an image section was generated off of the last cluster (which was not a shareable image cluster) in the cluster list. If FIXUPVEC is set, LASTCLU is clear.
Initial Code | [E]ISD$M_INITALCODE | This attribute is reserved by Compaq.
Based | [E]ISD$M_BASED | BASED indicates that the section is based. This is set when BASE= is specified in the options file. This attribute may also be set if based shareable images are encountered during linking. This attribute is present but not used for Alpha linking.
Fix-Up Vectors | [E]ISD$M_FIXUPVEC | FIXUPVEC marks the section that contains the image activator fix-ups. This section is created by the linker. The attribute cannot be set by the user.
Resident | [E]ISD$M_RESIDENT | This attribute is reserved by Compaq.
Vectored | [E]ISD$M_VECTOR | VECTOR indicates a vectored section, either a message section or a privileged library vector.
Protected | [E]ISD$M_PROTECT | Protect indicates that a section is protected. The linker sets the PROTECT attribute whenever VECTOR is set. PROTECT is also set if the /PROTECT qualifier is used, or if the cluster that the section is spawned from came after a PROTECT=YES option (and before a PROTECT=NO option).

The linker uses type designations instead of image section attributes to propagate the SHR and PIC program section attributes. The linker assigns the type designation [E]ISD$K_NORMAL for image sections in executable images. Image sections in shareable images can be any of the following types:

Image Section Type | Attribute Settings
--- | ---
Share fixed ([E]ISD$K_SHRFXD) | SHR,NOPIC
Private fixed ([E]ISD$K_PRVFXD) | NOSHR,NOPIC
Share position-independent ([E]ISD$K_SHRPIC) | SHR,PIC
Private position-independent ([E]ISD$K_PRVPIC) | NOSHR,PIC

The Image Section Synopsis section of a map file lists the attributes of each image section created in the Protection and Paging column. See Example 3-6 for an illustration. You can also get a listing of all the image sections created by the linker by using the ANALYZE/IMAGE utility. The output generated by this utility includes a list of all the image sections that make up the image, with their attributes. An excerpt from the analysis of the image file MYTEST.EXE is shown in Example 3-8.

Example 3-8 Image Section Descriptions in an ANALYZE/IMAGE Display

     Image Section Descriptors (ISD)

      1)(1)  image section descriptor (16 bytes)
        (2) page count: 1
        (3) base virtual address: %X'00000200' (P0 space)
        (4) page fault cluster size: default
        (5) IS flags:
        (0)  ISD$V_GBL        0
        (1)  ISD$V_CRF        1
        (2)  ISD$V_DZRO       0
        (3)  ISD$V_WRT        1
        (7)  ISD$V_LASTCLU    0
        (8)  ISD$V_INITALCODE 0
        (9)  ISD$V_BASED      0
        (10) ISD$V_FIXUPVEC   0
        (11) ISD$V_RESIDENT   0
        (17) ISD$V_VECTOR     0
        (18) ISD$V_PROTECT    0
        (6) section type: ISD$K_NORMAL
        (7) base VBN: 2
                            .
                            .
                            .
      9)  image section descriptor (31 bytes)
       page count: 193
       base virtual address: %X'00000000' (P0 space)
       page fault cluster size: default
       IS flags:
        (0)  ISD$V_GBL        1
        (1)  ISD$V_CRF        0
        (2)  ISD$V_DZRO       0
        (3)  ISD$V_WRT        0
        (7)  ISD$V_LASTCLU    0
        (8)  ISD$V_INITALCODE 0
        (9)  ISD$V_BASED      0
        (10) ISD$V_FIXUPVEC   0
        (11) ISD$V_RESIDENT   0
        (17) ISD$V_VECTOR     0
        (18) ISD$V_PROTECT    0
       section type: ISD$K_SHRPIC
       base VBN: 0
      (8) global section major id: %X'01', minor id: %X'00000E'
      (9) match control: ISD$K_MATLEQ
      (10) global section name: "LIBRTL_001"

The items in the following list correspond to the numbers in Example 3-8:

1. The size of the image section descriptor.
2. The size of the image section, expressed in pages. For Alpha images, the value is expressed in bytes.
3. The start address assigned to the image section by the linker. Note that this address is an offset from the beginning of the image, which is assumed to start at virtual address zero. (The linker always inserts an empty page at the beginning of every executable image.) Note also that the linker does not assign a start address for image sections representing shareable images because this information cannot be determined until run time, when the shareable image is loaded into memory by the image activator.
4. The number of pagelets that should be mapped in when the initial page fault occurs. You can set this value by using the CLUSTER= option.
5. The settings of image section attributes. Table 3-5 lists these attributes.
6. The type of image section, based on the combination of image section attributes.
7. The virtual block in the image file at which the image section begins.
8. Image sections that represent shareable images include the global section identification number, which specifies the identification number of the shareable image.
9. Image sections that represent shareable images also include a match control field that identifies the match control algorithm the image activator should apply to the global image section identification number when it activates the shareable image this ISD describes.
10. Image sections that represent shareable images include the global section name field, which is the name of the shareable image. The "_001"" is appended to the name by the linker to indicate which ISD in the image this represents.

### 3.3.6 Controlling Image Section Creation

You can control how the linker combines program sections into image sections in the following ways:

- By modifying the attributes of program sections
- By putting object modules into named clusters
- By using the SOLITARY attribute

#### 3.3.6.1 Modifying Program Section Attributes

The linker combines program sections in the same cluster into the same image section if they have the same settings for the significant program section attributes. To force the linker to put the program sections into different image sections, change the attributes of one of the program sections by using the PSECT_ATTR= option.

For example, in the sample link operation, the DATA program section and the $CHAR_STRING_CONSTANTS program section are combined into the same image section. If you want the $CHAR_STRING_CONSTANTS program section to appear in a different image section, change one of the significant attributes. For example, in the following link of the sample programs, the writability attribute is set to NOWRT. (For Alpha linking, you do not need to explicitly specify the C Run-Time Library in the link operation because it resides in the default system shareable image library [IMAGELIB.OLB], which the linker processes by default.)

    $ LINK/MAP/FULL MYTEST,MYADD,SYS$INPUT/OPT
    CLUSTER=MYSUB_CLUS,,,MYSUB
    PSECT_ATTR=$CHAR_STRING_CONSTANTS,NOWRT
    SYS$LIBRARY:VAXCRTL/SHARE
    [Ctrl/Z]

Example 3-9 presents an excerpt from the Image Section Synopsis section of the map file produced by this link.

Example 3-9 Image Section Synopsis of Second Link

       Cluster    Type Pages Base Addr Disk VBN PFC Protection and Paging...
       -------    ---- ----- --------- -------- --- ---------------------
                    .
                    .
                    .
    DEFAULT_CLUSTER 0    1    00000600      4    0  READ ONLY
                    0    1    00000800      0    0  READ WRITE   DEMAND ZERO
                    0    1    00000A00      5    0  READ ONLY
                    0    1    00000C00      6    0  READ WRITE   FIXUP VECTORS
                  253   20    7FFFD800      0    0  READ WRITE   DEMAND ZERO
                    .
                    .
                    .

Note that the default cluster contains one additional image section, a read-only image section beginning at virtual address 0x00000600, than the default cluster in the original link, illustrated in Section 3.3.1.

#### 3.3.6.2 Manipulating Cluster Creation

In general, the linker creates image sections on a per-cluster basis; that is, only program sections within a particular cluster can contribute to image section creation. (The linker can collect program sections with the global attribute from all clusters into a single image section.) To ensure that a program section appears in a particular image section, put the program section in a specific cluster.

For example, in the sample link operation illustrated in Example 3-5, the linker puts all the program sections in the object module MYSUB.OBJ in the cluster named MYSUB_CLUS because the CLUSTER= option is specified. If you wanted to group all of the program sections that contain code from all the other clusters into the MYSUB_CLUS cluster, you could specify the COLLECT= option, as in the following example. (By convention, VAX language processors put the code they generate into program sections named $CODE. Program section naming conventions are architecture specific.)

    $ LINK/MAP/FULL MYTEST, MYADD, SYS$INPUT/OPT
    CLUSTER=MYSUB_CLUS,,,MYSUB
    COLLECT=MYSUB_CLUS,$CODE
    SYS$LIBRARY:VAXCRTL/SHARE
    [Ctrl/Z]

Previous | Next | Contents | Index

| privacy and legal statement |
4548PRO_007.HTML