Debugging Tool Addr2line

addr2line

← Debugging Tools and Commands

GNU addr2line maps machine addresses to function names, source lines, and inline-call chains using the exact matching executable or DWARF artifact.

Property	Details
Supported OS	Windows, Linux, macOS.
Install	Install GNU Binutils or use the project pinned MinGW toolchain.
Verify	x86_64-w64-mingw32-addr2line --version
Primary output	See the workflow below.

When to use it

x86_64-w64-mingw32-addr2line is one of the most important tools in this workflow because it turns a sampled machine address into source context using the matching DWARF artifact.

GNU reference: https://sourceware.org/binutils/docs/binutils/addr2line.html

Common command

x86_64-w64-mingw32-addr2line \
  -a -f -i -C \
  -e /path/to/xemu-dwarf.exe \
  0x1402d3a7c 0x1402d50fa 0x1401865a1

Options:

Option	Meaning
-a	print the input address
-f	print function names
-i	show inline-call chain
-C	demangle C++ names
-e	exact executable/debug image to use

Read the output

Typical pattern:

0x1402d3a7c
some_function
path/to/source.c:123

With -i, additional function/file/line groups after the first location are inline parents. This is especially important under LTO/O2 where a hot instruction may physically live inside an inlined chain rather than a neat standalone function.

?? or line 0

Output such as:

??
??:0

usually means the tool cannot map that address using the supplied debug information. Common causes include:

• wrong executable/DWARF pair;
• stripped/missing debug information;
• incorrect address adjustment;
• address belongs to another module;
• optimizer emitted code without useful line attribution at that point.

Do not guess the source line when symbolization failed.

ASLR / RVA rule

A raw ETW instruction pointer may be a runtime virtual address after ASLR.

Safe model:

RVA = runtime IP - runtime image base
linked VA = preferred PE image base + RVA

Use the form expected by the selected symbolization method.

Do not subtract the preferred PE base directly from an ASLR runtime address. First establish the runtime image base recorded for that process instance.

For nearest-label maps, our retained tooling works in RVA space and explicitly verifies that the sampled IP belongs to the recorded xemu image range.

---

Boundaries and common mistakes

Establish whether an input is a runtime virtual address, image-relative virtual address, or linked virtual address before symbolizing it. For ASLR captures, use the runtime image base from that process instance.

??:0 is a failed attribution, not permission to guess. Check artifact pairing, address conversion, module ownership, and retained debug sections.

Evidence to retain

• Tool name and exact version.
• Source commit/tree and executable SHA-256.
• The complete command or saved profile used.
• Input artifact hashes and the explicitly selected time or address range.
• Raw output plus any derived report; do not retain only a screenshot or conclusion.
• Admission failures, warnings, dropped events, incomplete rows, or unsupported operations.

Official references

• GNU addr2line

Related xemu guides

• Debugging Tools and Commands
• Debugging Lag and Hot Paths
• Performance Methodology