7    Object Files

This chapter provides details on how compiler-system object files are formatted and processed.

The chapter addresses the following topics:

• The components that make up the object file and the differences between the object-file format used by the Digital UNIX compiler system and the System V common object file format (COFF). (Section 7.1)

• The headers and sections of the object file. Detailed information is given on the logic followed by the assembler and linker in handling relocation entries. (Section 7.2)

• The formats of object files (OMAGIC, NMAGIC, and ZMAGIC). (Section 7.3)

• Information used by the dynamic loader in loading object files at run time. (Section 7.4)

• Archive files. (Section 7.5)

• The symbols defined by the linker. (Section 7.6)

7.1    Object File Overview

The assembler and the linker generate object files. The sections in the object files are ordered as shown in Figure 7-1. Sections that do not contain data are omitted, except for the file header, optional header, and section header, which are always present.

Object files also contain a symbol table, which is also divided into sections. Figure 7-1 shows all of the possible sections in a symbol table. The sections of the symbol table that appear in a final object file can vary:

• The optimization symbols table and auxiliary symbols table appear only when a debugging option is in effect (when the user specifies one of the -g1, -g2, or -g3 compilation options).

• When you specify the -x option (strip nonglobals) for the link-edit phase, the linker updates the procedure descriptor table and strips the following tables from the object file: line number table, local symbols table, optimization symbols table, auxiliary symbols table, local strings table, and relative file descriptor table.

• The linker strips the entire symbol table from the object file when the user specifies the -s option (strip) for the link-edit phase.

Any new assembler or linker designed to work with the compiler system should lay out the object file sections in the order shown in Figure 7-1. The linker can process object files that are ordered differently, but performance may be degraded.

Figure 7-1: Object File Format

The standard System V COFF (common object file format) differs from the Digital UNIX compiler system format in the following ways:

• The file header definition is based on the System V header file filehdr.h with the following modifications:

  • The symbol table file pointer and the number of symbol table entries now specify the file pointer and the size of the symbolic header, respectively.

  • All tables that specify symbolic information have their file pointers and number of entries in the symbolic header. See Chapter 8 for information about the symbolic header.

• The definition of the optional header has the same format as specified in the System V header file aouthdr.h, except the following fields have been added: bldrev, bss_start, gprmask, fprmask, and gp_value (see Table 7-4).

• The definition of the section header has the same format as the System V header file scnhdr.h, except the line number fields are used for global pointers (see Table 7-6).

The definition of the section relocation information is similar to UNIX 4.3 BSD, which has local relocation types. Section 7.2.5 provides information on differences between local and external relocation entries.

7.2    Object File Sections

The following sections describe the components of an object file. Headers are informational and provide the means for navigating the object file. Sections contain program instructions or data (or both).

7.2.1    File Header

The format of the file header is shown in Table 7-1. The file header and all of the fields described in this section are defined in filehdr.h.

Table 7-1: File Header Format

The magic number in the f_magic field in the file header specifies the target machine on which an object file can execute. Table 7-2 shows the octal values and mnemonics for the magic numbers.

Table 7-2: File Header Magic Numbers

The f_flags field in the file header describes the object file characteristics. Table 7-3 lists the flags and gives their hexadecimal values and their meanings. The table notes those flags that do not apply to compiler system object files.

Table 7-3: File Header Flags

Table Note:

1. Not used by compiler system object modules.

7.2.2    Optional Header

The linker and the assembler fill in the optional header, and the dynamic loader, or other program that loads the object module at run time, uses the information it contains, as described in Section 7.4.

Table 7-4 shows the format of the optional header (which is defined in the header file aouthdr.h).

Table 7-4: Optional Header Definitions

Table 7-5 shows the octal values of the magic field for the optional header; the header file aouthdr.h contains the macro definitions.

Table 7-5: Optional Header Magic Numbers

See Section 7.3 for information on the format of OMAGIC, NMAGIC, and ZMAGIC files.

7.2.3    Section Headers

Table 7-6 shows the format of the section header (which is defined in the header file scnhdr.h).

Table 7-6: Section Header Format

Table 7-7 shows the defined section names for the s_name field of the section header.

Table 7-7: Section Header Constants for Section Names

Table Notes:

1. These sections exist only in ZMAGIC-type files and are used during dynamic linking.

Table 7-8 shows the defined hexadecimal values for the s_flags field. (Those flags that are not used by compiler system object files are noted in the table.)

Table 7-8: Format of s_flags Section Header Entry

Table Notes:

1. Not used by compiler system object modules.

2. These sections exist only in ZMAGIC type files and are used during dynamic linking.

The S_NRELOC_OVFL flag is used when the number of relocation entries in a section overflows the s_nreloc field of the section header. In this case, s_nreloc contains the value 0xffff and the s_flags field has the S_NRELOC_OVFL flag set; the value true is in the r_vaddr field of the first relocation entry for that section. That relocation entry has a type of R_ABS and all other fields are zero, causing it to be ignored under normal circumstances.

Note

For performance reasons, the linker uses the s_flags entry instead of s_name to determine the type of section. The linker does correctly fill in the s_name entry, however.

7.2.4    Section Data

Object files contain instructions and data. The instructions and data are stored in appropriate sections according to their use. Figure 7-2 shows the layout of section data in object files.

Figure 7-2: Organization of Section Data

The sections that are present in the section data and the ordering of the sections depends on the options that are in effect for a particular compilation.

The .conflict, .dynamic .dynstr, .dynsym, .got, .hash, .liblist, .msym, and .rel.dyn sections exist only in shared object files and are used during dynamic linking. These sections are described in more detail in Chapter 9. The following table describes the uses of the other sections:

Section Name	Use
.ucode	Intermediate code (if present, all other sections are excluded)
.bss	Block started by symbol
.data	Large data
.fini	Process termination text
.init	Initialization text
.lit4	4-byte literal pool
.lit8	8-byte literal pool
.lita	Literal address pool (only present in nonshared object files)
.pdata	Exception procedure table for pdata
.rconst	Read-only constants
.rdata	Read-only data
.sbss	Small block started by symbol
.sdata	Small data
.text	Machine instructions to be executed
.xdata	Exception scope table for xdata

The .text section contains the machine instructions that are to be executed; the .sdata, .lit4, .lit8, .rdata, .data, and .rconst sections contain initialized data; and the .bss and .sbss sections reserve space for uninitialized data that is created by the dynamic loader for the program before execution and filled with zeros. The only difference between .rdata and .rconst is that only .rdata can have dynamic relocations.

As indicated in Figure 7-2, the sections are grouped into segments:

• The text segment contains the .rdata (for nonshared object files), .fini, .init, .text, and .rconst sections in all files except shared object files, which contain additional sections. (The .rdata section can go in either the text or data segment, depending on the object file type.)

• The data segment contains the sections .got (for shared object files), .sdata, .lit4, .lit8, .lita (for nonshared object files), .rdata (for shared object files), and .data.

• The bss segment contains the .bss and .sbss sections.

A section is described by and referenced through the section header (see Section 7.2.3); the optional header (see Section 7.2.2) provides the same information for segments.

The linker references the data shown in Figure 7-2 as both sections and segments. It references the sections through the section header and the segments through the optional header. However, the dynamic loader, when loading the object file at run time, references the same data only by segment, through the optional header.

7.2.5    Section Relocation Information

Program instructions and data may contain addresses that must be adjusted when the object file is linked. Relocations locate the addresses within the section and indicate how they are to be adjusted.

7.2.5.1    Relocation Table Entry

Table 7-9 shows the format of an entry in the relocation table (defined in the header file reloc.h).

Table 7-9: Format of a Relocation Table Entry

The setting of r_extern and the contents of r_symndx vary for external and local relocation entries:

• For external relocation entries, r_extern is set to 1 and r_symndx is the index into external symbols. In this case, the value of the symbol is used as the value for relocation (see Figure 7-3).

• For local relocation entries, r_extern is set to 0, and r_symndx contains a constant that refers to a section (see Figure 7-4). In this case, the starting address of the section to which the constant refers is used as the value for relocation.

Table 7-10 gives the section numbers for r_symndx; the reloc.h file contains the macro definitions.

Table 7-10: Section Numbers for Local Relocation Entries

Table 7-11 shows valid symbolic entries for the r_type field (which is defined in the header file reloc.h).

Table 7-11: Relocation Types

Table 7-12 shows valid symbolic entries for the symbol index (r_symndx) field for the relocation type R_LITUSE.

Table 7-12: Literal Usage Types

7.2.5.2    Assembler and Linker Processing of Relocation Entries

Object modules with all external references defined have the same format as relocatable modules and are executable without relinking.

Local relocation entries must be used for symbols that are defined, and external relocation entries are used only for undefined symbols. Figure 7-3 gives an overview of the relocation table entry for an undefined external symbol.

Figure 7-3: Relocation Table Entry for Undefined External Symbols

The assembler creates a relocation table entry for an undefined external symbol as follows:

1. Sets r_vaddr to point to the item to be relocated.

2. Places a constant to be added to the value for relocation at the address for the item to be relocated (r_vaddr).

3. Sets r_symndx to the index of the external symbols entry that contains the symbol value (which is used as the value for relocation).

4. Sets r_type to the constant for the type of relocation types. Table 7-11 shows the valid constants for the relocation type.

5. Sets r_extern to 1.

Note

The assembler always sets the value of the undefined external symbols entry to 0. It may assign a constant value to be added to the relocated value at the address where the location is to be done. For relocation types other than R_HINT, the linker flags this as an error if the width of the constant is less than a full quadword and an overflow occurs after relocation.

When the linker determines that an external symbol is defined, it changes the relocation table entry for the symbol to a local relocation entry. Figure 7-4 gives an overview of the new entry.

Figure 7-4: Relocation Table Entry for a Local Relocation Entry

To change this entry from an external relocation entry to a local relocation entry, the linker performs the following steps:

1. Picks up the constant from the address to be relocated (r_vaddr).

2. If the width of the constant is less than 64 bits, sign-extends the constant to 64 bits.

3. Adds the value for relocation (the value of the symbol) to the constant and places it back in the address to be relocated.

4. Sets r_symndx to the section number that contains the external symbol.

5. Sets r_extern to 0.

The following examples show the use of external relocation entries:

• Example 1: 64-Bit Reference -- R_REFQUAD

  This example shows assembly statements that set the value at location b to the global data value y.

      .globl y
      .data
  b:  .quad y # R_REFQUAD relocation type at address b for
              # symbol y
  

  In processing this statement, the assembler generates a relocation entry of type R_REFQUAD for the address b and the symbol y. After determining the address for the symbol y, the linker adds the 64-bit address of y to the 64-bit value at location b and places the sum in location b.

  The linker handles 32-bit addresses (R_REFLONG) in the same manner, except it checks for overflow after determining the relocation value.

• Example 2: 21-Bit Branch -- R_BRADDR

  This example shows assembly statements that call routine x from location c.

      .text
  x:  #routine x
      ...
  c:  bsr x # R_BRADDR relocation type at address c for symbol x
  

  In processing these statements, the assembler generates a relocation entry of type R_BRADDR for the address and the symbol x. After determining the address for the routine, the linker subtracts the address c+4 to form the displacement to the routine. Then, the linker adds this result (sign-extended and multiplied by 4) to the 21 low-order bits of the instruction at address c, and after checking for overflow, places the result (divided by 4) back into the 21 low-order bits at address c.

  R_BRADDR relocation entries are produced for the assembler's br (branch) and bsr (branch subroutine) instructions.

  If the entry is a local relocation type, the target of the branch instruction is assembled in the instruction at the address to be relocated. Otherwise, the instruction's displacement field contains a signed offset from the external symbol.

• Example 3: 32-bit GP-Relative Reference -- R_GPREL32

  This example shows assembly language statements that set the value at location a to the offset from the global pointer to the global data value z.

      .globl z
      .data
  a:  .gprel32 z # R_GPREL32 relocation type at address a for
                 # symbol z
  

  In processing this statement, the assembler generates a relocation entry of type R_GPREL32 for the address a and the symbol z. After determining the address for the symbol z, the linker adds the 64-bit displacement of z from the the global pointer to the signed 32-bit value at location a, and places the sum in location a. The linker checks for overflow when performing the above operation.

• Example 4: Literal Address Reference -- R_LITERAL

  This example shows an assembly language statement that loads the address of the symbol y into register 22.

      lda $22, y
  

  In processing this statement, the assembler generates the following code:

      .lita
  x:  .quad y # R_REFQUAD relocation type at address x for
              # symbol y
  
   
  
      .text
  h:  ldq $22, n($gp) # R_LITERAL relocation type at address h
                      # for symbol x
  

  The assembler uses the difference between the address for the symbol x and the value of the global pointer as the value of the displacement (n) for the instruction. The linker gets the value of the global pointer used by the assembler from gp_value in the optional header (see Table 7-4).

• Example 5: Literal Usage Reference -- R_LITUSE

  This example shows an assembly language statement that loads the 32-bit value stored at address y into register 22.

      ldl $22, y
  

  In processing this statement, the assembler generates the following code:

      .lita
  x:  .quad y # R_REFQUAD relocation type at address x for
              # symbol y
  
   
  
      .text
  h:  ldq $at, n($gp) # R_LITERAL relocation type at address h
                      # for symbol x
  i:  ldl $22, 0($at) # R_LITUSE relocation type at address i;
                      # r_symndx == R_LU_BASE
  

  The assembler uses the difference between the address for the symbol x and the value of the global pointer as the value of the displacement (n) for the ldq instruction. The linker gets the value of the global pointer used by the assembler from gp_value in the optional header (see Table 7-4).

• Example 6: GP Displacement Reference -- R_GPDISP

  This example shows an assembly language statement that reloads the value of the global pointer after a call to procedure x.

      # call to procedure x returns here with return address in ra
      ldgp $gp, 0(ra)
  

  In processing this statement, the assembler generates the following code:

  j:  lda $at, <gp_disp>[0:15](ra) # R_GPDISP relocation type
                                   # at address j;
                                   # r_symndx contains byte offset
                                   # from address j to address k
  k:  ldah $gp, <gp_disp>[16:31]($at)
  

  The assembler determines the 32-bit displacement from the address of the ldgp instruction to the global pointer and stores it into the offset fields of the lda and ldah instructions. The linker gets the value of the global pointer used by the assembler from gp_value in the optional header (see Table 7-4).

• Example 7: JSR Hint -- R_HINT

  This example shows an assembly language statement that makes an indirect jump through register 24 and specifies to the branch-prediction logic that the target of the jsr instruction is the address of the symbol x.

      # get address of procedure to call into register 24
  m:  jsr ra, ($24), x # R_HINT relocation type at address m
                       # for symbol x
  

  In processing this statement, the assembler generates a relocation entry of type R_HINT for the address m and the symbol x.

7.3    Object-File Formats (OMAGIC, NMAGIC, ZMAGIC)

The linker creates files with the following object-file formats:

• Impure format (OMAGIC)

• Shared text format (NMAGIC)

• Demand paged format (ZMAGIC)

To understand the descriptions of these formats, you should be familiar with the format and contents of the text, data, and bss segments as described in Section 7.2.4.

The following constraints are imposed on the address at which an object can be loaded and the boundaries of its segments:

• Segments must not overlap.

• Space should be reserved for the stack, which starts just below the base of the text segment and grows through lower addresses; that is, the value of each subsequent address is less than that of the previous address.

• For ZMAGIC and NMAGIC files, the default text segment address is 0x120000000, with the data segment starting at 0x140000000.

• For OMAGIC files, the default text segment address is 0x10000000, with the data segment following the text segment.

The operating system can dictate additional constraints.

7.3.1    Impure Format (OMAGIC) Files

An OMAGIC file has the format shown in Figure 7-5.

Figure 7-5: Layout of OMAGIC Files in Virtual Memory

The OMAGIC format has the following characteristics:

• Each section follows the other in virtual address space aligned on a 16-byte boundary.

• The sections are not blocked.

• Text and data segments can be placed anywhere in the virtual address space using the linker's -T and -D options.

• The addresses specified for the segments must be rounded to 16-byte boundaries.

7.3.2    Shared Text (NMAGIC) Files

An NMAGIC file has the format shown in Figure 7-6.

Figure 7-6: Layout of NMAGIC Files in Virtual Memory

An NMAGIC file has the following characteristics:

• The virtual address of the .data section is on a pagesize boundary.

• The sections are not blocked.

• Each section follows the other in virtual address space aligned on a 16-byte boundary.

• Only the start of the text and data segments, using the linker's -T and -D options, can be specified for a shared text format file; the start of the text and data segments must be a multiple of the page size.

7.3.3    Demand Paged (ZMAGIC) Files

A ZMAGIC file is a demand paged file. Figure 7-7 shows the format of a ZMAGIC file as it appears in virtual memory and on disk.

Figure 7-7: Layout of ZMAGIC Files

A ZMAGIC file has the following characteristics:

• The text segment and the data segment are blocked, with pagesize as the blocking factor. Blocking reduces the complexity of paging in the files.

• The size of the sum of the file header, optional header, and headers from each of the sections is rounded to 16 bytes and included in blocking of the text segment. See Table 7-1, Table 7-4, and Table 7-6, respectively, for details on the headers.

• The text segment starts by default at 0x120000000.

• Only the start of the text and data segments, using the linker's -T and -D options can be specified for a demand paged format file and must be a multiple of the page size.

7.3.4    Ucode Objects

A ucode object contains only a file header, the ucode section header, the ucode section, and all of the symbolic information. A ucode section never appears in a machine-code object file.

7.4    Loading Object Files

The linker produces object files with their sections in a fixed order similar to the order that was used in UNIX system object files that existed prior to the implementation of the common object file format (COFF). Figure 7-1 shows the ordering of the sections, and Section 7.2 contains information on how the sections are formatted.

The sections are grouped into segments, which are described in the optional header. To load an object file for execution, the dynamic loader needs only the magic number in the file header and the optional header to load an object file for execution.

The starting addresses and sizes of the segments for all types of object files are specified similarly, and the segments are loaded in the same manner.

After reading in the file header and the optional header, the dynamic loader must examine the file magic number to determine if the program can be loaded. Then, the dynamic loader loads the text and data segments.

The starting offset in the file for the text segment is given by the following macro in the header file a.out.h:

N_TXTOFF (f,a)

where f is the file header structure and a is the option header structure for the object file to be loaded.

The tsize field in the optional header (Table 7-4) contains the size of the text segment and text_start contains the address at which it is to be loaded. The starting offset of the data segment follows the text segment. The dsize field in the section header (Table 7-6) contains the size of the data segment; data_start contains the address at which it is to be loaded.

The dynamic loader must fill the .bss section with zeros. The bss_start field in the optional header specifies the starting address; bsize specifies the number of bytes to be filled with zeros. In ZMAGIC files, the linker adjusts bsize to account for the zero-filled area it created in the data segment that is part of of the .sbss or .bss sections.

If the object file itself does not load the global pointer register, it must be set to the gp_value field in the optional header (Table 7-4).

The other fields in the optional header are gprmask and fprmask, whose bits show the registers used in the .text, .init, and .fini sections. They can be used by the operating system, if desired, to avoid save register relocations when a context-switch operation occurs.

7.5    Archive Files

The linker can link object files in archives created by the archiver. The archiver and the format of the archives are based on the System V portable archive format. To improve performance, the format of the archives symbol table was changed to a hash table, not a linear list.

The archive hash table is accessed through the ranhashinit() and ranlookup() library routines in libmld.a, which are documented in ranhash(3). The archive format definition is in the header file ar.h.

7.6    Linker Defined Symbols

Certain symbols are reserved and their values are defined by the linker. A user program can reference these symbols, but cannot define them; an error is generated if a user program attempts to define one of these symbols. Table 7-13 lists the names and values of these symbols; the header file sym.h contains their preprocessor macro definitions.

Table 7-13: Linker Defined Symbols

Table Notes:

1. Compiler system only.

2. Not defined with -std.

3. No symbol entry. Not defined in sym.h.

The dynamic linker also reserves and defines certain symbols; see Chapter 9 for more information.

The first three symbols in Table 7-13 (_ETEXT, _EDATA, and _END) come from the standard UNIX system linker. The remaining symbols are compiler-system specific.

The linker symbol _COBOL_MAIN is set to the symbol value of the first external symbol with the cobol_main bit set. COBOL objects use this symbol to determine the main routine.

The following symbols relate to the run-time procedure table:

• _PROCEDURE_TABLE

• _PROCEDURE_TABLE_SIZE

• _PROCEDURE_STRING_TABLE

The run-time procedure table is used by the exception systems in languages that have exception-handling capabilities built into them. Its description is found in the header file sym.h. The table is a subset of the procedure descriptor table portion of the symbol table with one additional field, exception_info.

When the procedure table entry is for an external procedure and an external symbol table exists, the linker fills in exception_info with the address of the external table. Otherwise, it fills in exception_info with zeros.

The name of the run-time procedure table is the procedure name concatenated with the string _exception_info (that is, the default value of the preprocessor macro EXCEPTION_SUFFIX, as defined in the header file excpt.h).

The run-time procedure table provides enough information to allow a program to unwind its stack. It is typically used by the routines in libexc.a. The comments in the header file excpt.h describe the routines in that library.