# Analysis and introspection options in linkers

### --trace-symbol=<sym>

Alias: -y sym

Print files which define or reference the specified non-local symbol. There are three types of definitions: definition in a relocatable object file, definition in a shared object, definition in a lazy object file/archive.

### --trace

Alias: -t

Print processed files: relocatable object files, shared objects, and extracted lazy object files/archive members. Note that unextracted lazy object files/archive members are not printed.

The GNU ld behavior is a bit strange. You need to specify -t twice to get both the archive name and the member name.

gold introduced --print-symbol-counts=<file> in 2008-06. The output includes the member count and extracted member count for each archive. I added --print-archive-stats=<file> to ld.lld to dump the archive information, but in a tab-separated format.

### --why-extract=<file>

Print why each archive member/lazy object file is extracted. I added the option to ld.lld 14. The output is in a tab-separated format.

It is easy to track a chain of references to one archive member:

ld64 has a similar option named -why_load.

## -Map=<file>

Print a link map to the file. To print to stdout, use -M.

The output includes output sections addresses, file offsets, input section to output section mapping, and symbol assignments.

GNU ld prints additional information: Archive member included to satisfy reference by file (symbol), Discarded input sections (similar to --print-gc-sections), Allocating common symbols, Memory Configuration (related to memory regions), and Linker script and memory map (similar to -t).

If the option value is a directory or a name with %, the map filename will be constructed from the output filename.

## Cross references

### --cref

Print a cross reference table. For each non-local defined or shared symbol, print the defined file on the first line and and referencing files in subsequent lines. The format is a bit wasteful because there are 50 bytes before the File column.

If -Map is specified, print along with the link map to the file. I find this behavior a bit unfortunate, because:

• the information is independent from other pieces of -Map
• both pieces of information has large amount of output. Merging them makes the link action slower if the user just needs one piece of information

mold recently added the option in an alternative format to --cref.

### -why_live sym

ld64 manpage says: Logs a chain of references to symbol_name. Only applicable with -dead_strip . It can help debug why something that you think should be dead strip removed is not removed.

This can usually be approximated by ld.lld --why-extract=-.