The debugger commands that matter for C++, side by side for gdb and lldb. Sources: GDB manual, LLDB docs (GDB-to-LLDB command map), libstdc++ pretty-printers, rr-project.org — checked 2026-10-31 · pairs with tooling
Rebuild with a sanitizer first (tooling): a sanitizer report
names the bad access and its allocation and free stacks. Open a debugger once
you know what went wrong, for logic bugs, or when all you have is a core
dump. Every command below was run with gdb 16.3 (Linux, gcc:16 image) and
LLDB 22 (macOS); the transcripts are trimmed.
Build for debugging: -g always (release builds too; strip into a separate
file if size matters), -Og or -O0 when you need to step, since optimized
code shows variables as <optimized out> and jumps between lines.
-gsplit-dwarf writes debug info to .dwo files and speeds up linking large
projects. On macOS the debug info lives in a .dSYM bundle next to the
binary: copy the binary without it and file:line breakpoints don't resolve.
On macOS, use lldb: gdb has no native Apple Silicon support (its Darwin
port is x86 only, and Homebrew builds the arm64 gdb for an x86-64 target),
and on Intel Macs it needs codesigning.
| Task | gdb | lldb |
|---|---|---|
| Start with arguments | gdb --args ./app a b |
lldb -- ./app a b |
| Break on a function | break Widget::id |
b Widget::id |
| Break at a line, conditionally | break app.cpp:20 if i == 5 |
br set -f app.cpp -l 20 -c 'i == 5' |
| One template instantiation | break scale<double> |
br set -n 'scale<double>' |
| Every instantiation (regex) | rbreak ^scale< |
br set -r '^scale<' |
| One-shot breakpoint | tbreak check |
br set -n check -o true |
| Stop when an exception is thrown | catch throw |
br set -E c++ |
| … when it's caught | catch catch |
br set -E c++ -w false -h true |
| Stop when a variable changes | watch total |
watchpoint set variable total |
| … only past a value | watch total if total > 150 |
watchpoint modify -c 'total > 150' 1 |
| Backtrace, all threads | bt, thread apply all bt |
bt, bt all |
| Select a frame | frame 2, up, down |
frame select 2, up, down |
| Run to the end of this function | finish |
finish |
| Locals | info locals |
frame variable (v) |
| Print, with and without formatters | p v, p/r v |
p v, v --raw v |
| Attach | gdb -p PID |
lldb -p PID |
| Attach when it starts | — | process attach -n app --waitfor |
| Open a core file | gdb ./app core |
lldb -c core ./app |
| Write a core of the live process | gcore app.core |
process save-core app.core |
| Text UI | tui enable, layout split |
gui |
More in LLDB's GDB-to-LLDB command map.
A template has one function per instantiation. break scale<double> stops in
one; rbreak ^scale< (gdb) or br set -r '^scale<' (lldb) sets a location in
each and prints the instantiations it matched. A plain break scale also sets
one location per instantiation or overload (gdb: scale. (2 locations)).
catch throw / br set -E c++ stop inside __cxa_throw, before the stack
unwinds — the backtrace still shows who threw. Select the thrower's frame to
see its locals:
Catchpoint 2 (exception thrown), 0x0000fffff7cb2f3c in __cxa_throw () from libstdc++.so.6
(gdb) bt
#0 0x0000fffff7cb2f3c in __cxa_throw () from libstdc++.so.6
#1 0x0000000000401c54 in check (i=7) at dbg.cpp:13
#2 0x0000000000401df4 in main () at dbg.cpp:22
gdb takes a regex for the type: catch throw std::runtime_error. LLDB 22 has
no type filter for C++ exceptions; stop on every throw and read the backtrace.
In lldb, -h true alone stops on the throw and the catch
(__cxa_begin_catch); add -w false to stop only where it's caught.
Watchpoints stop on the write that changes a value — the fastest way to
find who corrupts a field. They're hardware-backed and few (LLDB reports 4 on
Apple arm64). A watch on a local ends when it goes out of scope; gdb's
watch -l v[1] watches the address instead of the expression.
Both debuggers show standard containers as their elements, not their
internals, and gdb evaluates v[1] and m.size() through libstdc++'s
xmethods:
(gdb) p v
$2 = std::vector of length 3, capacity 3 = {1, 2, 3}
(gdb) p m
$3 = std::map with 2 elements = {["a"] = 1, ["b"] = 2}
- gdb uses the Python pretty-printers that ship with libstdc++. They load
automatically from a
libstdc++.so.*-gdb.pyscript next to the library — if that library isn't under gdb's auto-load safe path (a GCC installed under/usr/local, as in thegcc:16image), gdb prints a warning at startup and you get_M_impland_M_startinstead. Addadd-auto-load-safe-path <dir>to your gdbinit.info pretty-printerlists what loaded;p/rprints the raw object. - lldb has built-in formatters for libc++ and libstdc++ (both checked on
macOS, Clang 22 and GCC 15 binaries).
v --rawturns them off. - Stepping:
stepintov[i]lands in library code. LLDB skips functions matchingtarget.process.thread.step-avoid-regexp(default^std::). libstdc++'s gdb script addsskipentries forstd::move,std::forward, smart-pointer accessors and containerbegin/size/operator[](since GCC 15, PR118260; present in 15.2 and 16, absent in 14;info skiplists them). Add your own withskip -gfi '/usr/include/c++/*/bits/*'.
gdb -p PID or lldb -p PID stops a running process; detach lets it
continue. On Linux, the Yama security module may forbid attaching to a process
that isn't your child — see kernel.yama.ptrace_scope in the
Yama docs.
gdb reads ~/.config/gdb/gdbinit (or ~/.gdbinit); lldb reads ~/.lldbinit.
Good first lines: set print pretty on and add-auto-load-safe-path <dir>
for gdb, command alias bfl breakpoint set -f %1 -l %2 style aliases for
lldb. A project-local .gdbinit runs only if its directory is on the
auto-load safe path, and lldb ignores ./.lldbinit unless
settings set target.load-cwd-lldbinit true — both warn instead, because the
file can run arbitrary commands.
Text UI: gdb's tui enable (or Ctrl-x a) shows source above the command
line; layout split adds disassembly. lldb's gui is a curses view of source,
threads and variables.
A core dump is the process's memory at the crash, so you can debug it later:
$ ulimit -c unlimited # allow core files in this shell
$ ./app # Segmentation fault (core dumped)
$ gdb ./app core # or: coredumpctl gdb (systemd)
(gdb) btWhere the file goes depends on /proc/sys/kernel/core_pattern (core in the
gcc:16 image; systemd distros pipe it to coredumpctl). Pretty-printers work
on cores too. gcore (gdb) and process save-core (lldb) write a core of a
live process without killing it — handy for a hung service. On macOS a crash
left no core here even with ulimit -c unlimited; process save-core worked.
Sanitizers turn core dumps off on 64-bit targets (disable_coredump=1); to
get one from an ASan failure, run with
ASAN_OPTIONS=disable_coredump=0:abort_on_error=1.
Keep the exact binary and its debug symbols for every build you ship, or the dump is unreadable.
rr records a run and replays it deterministically
under gdb, including backwards: rr record ./app, then rr replay and
watch -l x + reverse-continue to find the last write. It needs Linux and
CPU performance counters (recent x86 and some ARM CPUs), so it doesn't run in
most containers or under Docker on macOS — not verified here.
Captures a stack trace in-process — useful for logging where an unexpected error came from in production:
#include <stacktrace>
#include <print>
void on_fatal_error() {
std::println(stderr, "{}", std::stacktrace::current());
}Linking with libstdc++ depends on the version: GCC 13 needs
-lstdc++_libbacktrace; GCC 14 and later use -lstdc++exp. Support also
depends on how the toolchain was built, so check with a compile-and-link
test in your build, not by testing that <stacktrace> exists. (libc++ and MSVC
STL linking not covered here yet.)
- GDB manual: catchpoints · pretty-printing · auto-load safe path · skipping functions · TUI · core files
- LLDB: GDB-to-LLDB command map · variable formatting
- rr · rr README
- std::stacktrace
- Tooling · Valgrind · Performance tooling