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.cFor 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)3. 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 |
4. 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 35. 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 stack6. 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 stepping7. 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-history8. Remote debugging with gdbserver
On target:
gdbserver :1234 ./prog
# Or attach:
gdbserver :1234 --attach 5678On host:
gdb ./prog
(gdb) target remote 192.168.1.10:1234
(gdb) break main
(gdb) continueFor 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 offFor a command cheatsheet, see references/cheatsheet.md. For pretty-printers and Python scripting, see references/scripting.md.
Related skills
- Use
skills/debuggers/core-dumpsfor loading core files - Use
skills/debuggers/lldbfor LLDB-based workflows - Use
skills/runtimes/sanitizersto catch bugs before needing the debugger - Use
skills/compilers/gccfor-gflag details