GDB Purpose Walk agents through GDB sessions from first launch to advanced workflows: crash diagnosis, reverse debugging, remote debugging, and multi-thread inspection. Triggers "My program segfaults / crashes — how do I debug it?" "How do I set a breakpoint on condition X?" "How do I inspect memory / variables in GDB?" "How do I debug a remote embedded target?" "GDB shows ?? frames / no source" "How do I replay a bug deterministically?" (record/replay) Workflow 1. Prerequisite: compile with debug info Always compile with -g (GCC/Clang). Use -Og or -O0 for most debuggable code. gcc -g -Og -o prog main.c For release builds: use -g -O2 and keep the binary with symbols (strip separately with objcopy ). 2. Start GDB gdb ./prog
load binary
gdb ./prog core
load with core dump
gdb -p 12345
attach to running process
gdb --args ./prog arg1 arg2
pass arguments
gdb -batch -ex 'run' -ex 'bt' ./prog
non-interactive (CI)
- Essential commands Command Shortcut Effect run [args] r Start the program continue c Resume after break next n Step over (source line) step s Step into nexti ni Step over (instruction) stepi si Step into (instruction) finish Run to end of current function until N Run to line N return [val] Force return from function quit q Exit GDB
- Breakpoints and watchpoints break main # break at function break file.c:42 # break at line break 0x400abc # break at address break foo if x > 10 # conditional break tbreak foo # temporary breakpoint (fires once) rbreak ^mylib_. # regex breakpoint on all matching functions watch x # watchpoint: break when x changes watch (int)0x601060 # watch memory address rwatch x # break when x is read awatch x # break on read or write info breakpoints # list all breakpoints delete 3 # delete breakpoint 3 disable 3 # disable without deleting enable 3
- Inspect state print x # print variable print/x x # print in hex print *ptr # dereference pointer print arr[0]@10 # print 10 elements of array display x # auto-print x on every stop undisplay 1 info locals # all local variables info args # function arguments info registers # all CPU registers info registers rip rsp rbp # specific registers x/10wx 0x7fff0000 # examine 10 words at address x/s 0x400abc # examine as string x/i $rip # examine current instruction backtrace # call stack (bt) bt full # bt + local vars frame 2 # switch to frame 2 up / down # move up/down the stack
- Multi-thread debugging info threads # list threads thread 3 # switch to thread 3 thread apply all bt # backtrace all threads thread apply all bt full # full bt all threads set scheduler-locking on # pause other threads while stepping
- Reverse debugging (record/replay) Record requires target record-full or target record-btrace (Intel PT):
Software record (slow but universal)
record # start recording run
... trigger the bug ...
reverse-continue # go back to last break reverse-next # step backwards reverse-step reverse-finish
Intel Processor Trace (fast, hardware)
target record-btrace pt run
view instruction history
record instruction-history 8. Remote debugging with gdbserver On target: gdbserver :1234 ./prog
Or attach:
gdbserver :1234 --attach 5678 On host: gdb ./prog ( gdb ) target remote 192.168 .1.10:1234 ( gdb ) break main ( gdb ) continue For cross-compilation: use aarch64-linux-gnu-gdb on the host. 9. Common problems Symptom Cause Fix No symbol table Binary not compiled with -g Recompile with -g ?? frames in backtrace Missing debug info or stack corruption Install debuginfo package; check for stack smash Cannot access memory at address Null dereference / freed memory Check pointer before deref; use ASan SIGABRT in backtrace abort() or assertion failure Go up frames to find the assertion GDB hangs on run Binary waiting for input Redirect stdin: run < /dev/null Breakpoint in wrong place Optimiser moved code Compile with -Og ; or use nexti 10. GDB init file (~/.gdbinit) set history save on set history size 1000 set print pretty on set print array on set print array-indexes on set pagination off set confirm off For a command cheatsheet, see references/cheatsheet.md . For pretty-printers and Python scripting, see references/scripting.md .