# Link maps

Link maps are optionally generated by the linker. They provide the
following information on how the files were linked:

- Archive and object files that are accessed
- Common symbols that are allocated
- Linker script (if specified)
- Memory map of sections and symbols

## Link map in text format

A link map is generated as a text file that you specify on the command
line with the

`-Map <filename>` option (see [Map options](https://docs.qualcomm.com/doc/80-VB419-102/topic/use_the_linker.html#id14)).

### Example link map file

The following link map file was generated by linking the C program for
the AArch64 target architecture:

#include "stdio.h" int common_var;
    
    int main() {
       common_var = 1;
       printf("var = %d\\n", common_var);
       return 0;
    }
    Copy to clipboard

Note

This map file has been shortened for readability.

Archive member included because of file (symbol)
    /prj/llvm-arm/home/common/build_tools/gcc-fsf-glibc-aarch64-linux-gnu-4.9.0/ aarch64-linux- gnu/libc/usr/lib64/libc_nonshared.a(elf-init.oS)
    /prj/llvm-arm/home/common/build_tools/gcc-fsf-glibc-aarch64-linux-gnu-4.9.0/ aarch64-linux-gnu/libc/usr/lib/../lib64/crt1.o ( libc_csu_init)
    
    Allocating common symbols Common symbol size file
    
    common_var   0x4     /tmp/t-f3306e.o

    Linker Script and memory map
    LOAD /prj/llvm-arm/home/common/build_tools/gcc-fsf-glibc-aarch64-linux- gnu-4.9.0/aarch64- linux-gnu/libc/usr/lib/../lib64/crt1.o[]
    LOAD /prj/llvm-arm/home/common/build_tools/gcc-fsf-glibc-aarch64-linux- gnu-4.9.0/aarch64- linux-gnu/libc/usr/lib/../lib64/crti.o[]
    LOAD /prj/llvm-arm/home/common/build_tools/gcc-fsf-glibc-aarch64-linux- gnu-4.9.0/lib/gcc/ aarch64-linux-gnu/4.9.0/crtbegin.o[]
    LOAD /tmp/t-f3306e.o[]
    LOAD /prj/llvm-arm/home/common/build_tools/gcc-fsf-glibc-aarch64-linux- gnu-4.9.0/lib/gcc/ aarch64-linux-gnu/4.9.0/../../../../aarch64-linux-gnu/ lib/../lib64/libgcc_s.so[]
    START GROUP
    LOAD /prj/llvm-arm/home/common/build_tools/gcc-fsf-glibc-aarch64-linux- gnu-4.9.0/aarch64- linux-gnu/libc/lib64/libc.so.6[]
    LOAD /prj/llvm-arm/home/common/build_tools/gcc-fsf-glibc-aarch64-linux-gnu-4.9.0/aarch64- linux-gnu/libc/usr/lib64/libc_nonshared.a(elf-init.oS) []
    LOAD /prj/llvm-arm/home/common/build_tools/gcc-fsf-glibc-aarch64-linux-gnu-4.9.0/aarch64- linux-gnu/libc/lib/ld-linux-aarch64.so.1[]
    END GROUP
    SKIPPED /prj/llvm-arm/home/common/build_tools/gcc-fsf-glibc-aarch64-linux- gnu-4.9.0/lib/ gcc/aarch64-linux-gnu/4.9.0/../../../../aarch64-linux-gnu/lib/../lib64/ libgcc_s.so (ELF) LOAD /prj/llvm-arm/home/common/build_tools/gcc-fsf-glibc-aarch64-linux- gnu-4.9.0/lib/gcc/ aarch64-linux-gnu/4.9.0/crtend.o[]
    LOAD /prj/llvm-arm/home/common/build_tools/gcc-fsf-glibc-aarch64-linux- gnu-4.9.0/aarch64- linux-gnu/libc/usr/lib/../lib64/crtn.o[]
    
    Linker scripts used (including INCLUDE command)
    /sysroot/aarch64-linux-gnu/libc/usr/lib/../lib64/libc.so
    ...
    interp 0x238 0x1b # Offset: 0x238, LMA: 0x238 ...
    .text        0x460   0x21c   # Offset: 0x460, LMA: 0x460
    .text        0x460   0x48    /sysroot/aarch64-linux-gnu/libc/usr/lib/../lib64/crt1.o
                 0x468           .text
                 0x468           $x
                 0x468           _start
                 0x498           $d
    ...
    .text        0x5c0   0x48    /tmp/t-57e15d.o
                 0x5c0           $x.0
                   0x5c0         .text
                 0x5c0           main
    ...
    .shstrtab
    0x1288 0xf1
    .symtab
    0x1380 0x7f8
    Copy to clipboard

### Archive section

The archive section of a link map lists each archive file that was
accessed by the linker and the symbol reference that caused the archive
file to be accessed.

<archive_file> (<symbol_define_object_file>)
    <symbol_reference_object_file>
    
    (<symbol>)
    Copy to clipboard

Each entry in the archive section contains the following items:

- The full pathname of the archive file accessed by the linker
- The name of the archived object file that defines the symbol (in
parentheses)
- The full pathname of the object file that contains the symbol
reference
- The name of the referenced symbol (in parentheses)

#### Example

The libc\_csu\_init symbol is referenced in the crt1.o object file and
defined in \_elf-init.oS, which is stored in the libc\_nonshared.a archive file:

/sysroot/aarch64-linux-gnu/libc/usr/lib64/libc_nonshared.a(elf-init.oS)
    /sysroot/aarch64-linux-gnu/libc/usr/lib/../lib64/crt1.o (libc_csu_init)
    Copy to clipboard

### Common symbols section

The common symbols section of a link map lists the common symbols that
were allocated in memory by the linker.

> 
> 
> <symbol size archive_file> (<symbol_define_object_file>)
>     Copy to clipboard

Each entry in the common symbols section contains the following items:

- The name of the symbol
- The size of the memory area allocated for the symbol
- The full pathname of the archive file accessed by the linker
- The name of the archived object file that defines the symbol (in parentheses)

#### Example

The common\_var symbol has size of 0x4 and is defined in the t-57e15d.o
object file that was compiled as shown in [Example link map file](https://docs.qualcomm.com/doc/80-VB419-102/topic/link_maps.html#sec-example-link-map-file):

common_var 0x4 /tmp/t-57e15d.o 3
    Copy to clipboard

### Linker script section

The linker script section of a link map lists the complete linker script
that is specified for the link (see [Linker scripts](https://docs.qualcomm.com/doc/80-VB419-102/topic/linker_scripts.html)).

<linker_script_command>
    Copy to clipboard

Note

Linker scripts are optional. If a script is not specified on
the linker command line, the link map does not include a linker script.

#### Example

Following are the initial lines of a linker script section:

...
    
    LOAD /sysroot/aarch64-linux-gnu/libc/lib64/libc.so.6
    
    LOAD /sysroot/aarch64-linux-gnu/libc/usr/lib64/libc_nonshared.a(elf-init.oS)
    
    LOAD /sysroot/aarch64-linux-gnu/libc/lib/ld-linux-aarch64.so.1 END
    GROUP
    
    SKIPPED /sysroot/lib/gcc/aarch64-linux-gnu/4.9.0/../../../../aarch64-linux-gnu/ lib/../lib64/libgcc_s.so (ELF)
    
    LOAD /sysroot/lib/gcc/aarch64-linux-gnu/4.9.0/crtend.o
    
    LOAD /sysroot/aarch64-linux-gnu/libc/usr/lib/../lib64/crtn.o
    
    Linker scripts used (including INCLUDE command)
    
    /sysroot/aarch64-linux-gnu/libc/usr/lib/../lib64/libc.so
    Copy to clipboard

### Memory map section

The memory map section of a link map lists how symbols and assembly
language sections are assigned to memory in the output file.

<output_section addr size>
    
    <input_section addr size object_file symbol addr>
    
    ...
    
    ...
    Copy to clipboard

The section lists one or more output sections, and each output section
contains the following items:

- The output section, its start address, and section size
- Each input section that is mapped to the output section, including
its start address, section size, and full pathname of the object file
containing the section
- Each symbol defined in the input section, including its assigned
value

#### Example

The .text output section has the start address of 0x468 and size of
0x21c. Multiple input sections (named .text) are mapped to this output
section. Two sections are shown in this example. The first section has
the start address of 0x468 and size of 0x48. The second section has the
start address of 0x5c0 and size of 0x48. Following each section
descriptor is a list of the symbols in the section.

.text 0x468 0x21c
    .text 0x468 0x48 /sysroot/aarch64-linux-gnu/libc/usr/lib/..
    /lib64/crt1.o
    0x468 .text
    0x468 $x
    0x468 \_start
    0x498 $d
    ...
    .text 0x5c0 0x48 /tmp/t-57e15d.o 0x5c0 $x.0
    0x5c0 .text
    0x5c0 main
    ...
    Copy to clipboard

## Link map in YAML format

If you use the -MapStyle option ([Map options](https://docs.qualcomm.com/doc/80-VB419-102/topic/use_the_linker.html#id14)) to
specify YAML-style output for the map file, the linker generates a YAML
file instead of the text file that shows the memory map for the program.

To derive statistics from the YAML map file produced by the linker, use
the YAMLMapParser.py tool and include any of the options.

### Example YAML file

a.c
    
    int discardedcommon;
    
    int main() { foo(); return 0;} b.c int foo() { return 0; }
    
    clang -c 1.c 2.c -ffunction-sections -fdata-sections llvm-ar cr
    lib2.a 2.o
    
    ld.qcld 1.o lib2.a -MapStyle yaml -Map x.yaml --gc-sections -e main
    Copy to clipboard

### Options

- **-info=architecture**
    - Display the architecture.

- **list**
    - Redirect the output to a file.

- **–map**
    - Display the memory map of the images.

- **sizes**
    - List the code and data sizes for the objects in the image.

- **summarysizes**
    - List the code and data sizes of the image.

- **totals**
    - List the total size of all objects in the image.

- **unused**
    - List the sections eliminated from the image.

- **unusedsymbols**
    - List the symbols eliminated from the image.

- **–xref**
    - List the cross-references between input sections.

### Sections of a YAML file

- **Header**
    - Top-level information of the program that was built.

- **Version information**
    - Tools version information.

- **Archive records**
    - Archive files pulled in by the linker.

- **Inputs**
    - Inputs that were used.

- **InputInfo**
    - Inputs that were used and not used.

- **Linker script used**
    - Linker script file that was used.

- **BuildType**
    - Type of build.

- **OutputFile**
    - Name of the output file.

- **EntryAddress**
    - Entry address for the image built.

- **CommandLine**
    - Command line information on how the linker was called.

- **CommandLineDefaults**
    - Various defaults applied in the linker.

- **OutputSections**
    - All output sections.

- **DiscardedComdats**
    - COMDAT C++ section groups that were discarded.

- **DiscardedSections**
    - Sections that were discarded by garbage collection.

- **DiscardedCommonSymbols**
    - Common symbols that were discarded.

- **LoadRegions**
    - Segments that the program loader will loa.d

- **CrossReferences**
    - Cross-reference table for the program.

Last Published: May 10, 2024

[Previous Topic
Use the linker](https://docs.qualcomm.com/bundle/publicresource/80-VB419-102/topics/use_the_linker.md) [Next Topic
Linker scripts](https://docs.qualcomm.com/bundle/publicresource/80-VB419-102/topics/linker_scripts.md)