GDB Cheatsheet

lldb Equivalents

Use this GDB reference while you build software engineering projects, review code, or refresh the syntax you reach for most.

Why You Need This

On macOS, lldb is the system debugger and gdb is not installed. On Linux, lldb ships with LLVM and is what Clang, Swift, and Rust tooling assume. The two share almost no command spelling, so a gdb reflex produces is not a known command.

lldb commands are noun verb with heavy aliasing. breakpoint set --name main is the real command, br s -n main is the same thing, and b main is a separate regex-based shorthand. Every alias below was checked against a running lldb.

lldb ./prog                # load
lldb -- ./prog -v in.csv   # everything after -- is the program's argv
lldb -p 1234               # attach by pid
lldb -n prog               # attach by process name
lldb -c core.4711 ./prog   # load a core
lldb -b -o "run" -o "bt" ./prog     # batch, like gdb --batch -ex

gdb flag	lldb flag
`--args prog a b`	`-- prog a b`, or `--file prog` then `settings set target.run-args`
`-ex CMD`	`-o CMD` (`--one-line`), repeatable and ordered
`-x FILE`	`-s FILE` (`--source`)
`--batch`	`-b` (`--batch`)
`-nx`	`-x` (`--no-lldbinit`)
`-p PID`	`-p PID`
`-c CORE`	`-c CORE`
`~/.gdbinit`	`~/.lldbinit`, plus `./.lldbinit` if enabled in settings

Breakpoints and Watchpoints

gdb	lldb
`break main`	`breakpoint set --name main` · `br s -n main` · `b main`
`break file.c:42`	`breakpoint set --file file.c --line 42` · `br s -f file.c -l 42`
`break *0x1000`	`breakpoint set --address 0x1000` · `br s -a 0x1000`
`break Ns::f`	`br s -M f` (method) or `br s -n Ns::f`
`break f if x == 0`	`br s -n f -c 'x == 0'`
`condition 1 x > 2`	`breakpoint modify -c 'x > 2' 1`
`ignore 1 10`	`breakpoint modify -i 10 1`
`tbreak f`	`br s -o true -n f` (`--one-shot`)
`rbreak ^http_`	`breakpoint set --func-regex ^http_` · `br s -r ^http_`
`catch throw`	`breakpoint set -E c++` (`--language-exception`)
`commands 1 ... end`	`breakpoint command add 1`
`info breakpoints`	`breakpoint list` · `br l`
`delete 1`	`breakpoint delete 1` · `br del 1`
`disable 1` / `enable 1`	`breakpoint disable 1` / `breakpoint enable 1`
`watch total`	`watchpoint set variable total` · `wa s v total`
`watch -l *p`	`watchpoint set expression -- p`
`rwatch v`	`watchpoint set variable -w read v`
`awatch v`	`watchpoint set variable -w read_write v`
`info watchpoints`	`watchpoint list`
`catch syscall`	no equivalent, lldb has no syscall catchpoint

Running, Stepping, Frames

gdb	lldb
`run`	`process launch` · `run` · `r`
`start`	`process launch --stop-at-entry` · `pro la -s`
`continue` / `c`	`process continue` · `continue` · `c`
`next` / `n`	`thread step-over` · `next` · `n`
`step` / `s`	`thread step-in` · `step` · `s`
`finish` / `fin`	`thread step-out` · `finish` · `fin`
`stepi` / `si`	`thread step-inst` · `si`
`nexti` / `ni`	`thread step-inst-over` · `ni`
`until 88`	`thread until 88`
`return 0`	`thread return 0`
`jump 92`	`thread jump --line 92`
`kill`	`process kill` · `kill`
`detach`	`process detach`
`attach 1234`	`process attach --pid 1234`
`bt`	`thread backtrace` · `bt`
`bt 5`	`bt 5`
`bt full`	no single equivalent, `bt` then `frame variable` per frame
`thread apply all bt`	`thread backtrace all` · `bt all`
`frame 2` / `f 2`	`frame select 2` · `f 2`
`up` / `down`	`up` / `down`
`info frame`	`frame info`
`info locals`	`frame variable --no-args` · `v -a` (bare `v` shows both)
`info args`	`frame variable --no-locals` · `v -l`
`info threads`	`thread list`
`thread 2`	`thread select 2` · `t 2`
`set scheduler-locking on`	no equivalent, lldb has no scheduler locking

Data, Memory, and Symbols

gdb	lldb
`print x` / `p x`	`expression x` · `p x` (`print` is `dwim-print`)
`p/x x`	`p/x x` · `expression -f hex -- x`
`p *ap@5`	`parray 5 ap`, the `@` syntax does not exist
`p arr[2]@3`	`parray 3 &arr[2]`
`ptype struct config`	`type lookup config` · `image lookup -t config`
`whatis x`	`expression -T -- x`, or read the type in `p` output
`set var x = 5`	`expression x = 5` · `expr x = 5`
`call f(1)`	`expression f(1)` · `p f(1)`
`display x`	`target stop-hook add -o "p x"`
`set print pretty on`	on by default, tune with `type summary add`
`x/16xb buf`	`x/16xb buf` · `memory read -f x -s 1 -c 16 buf`
`x/5xw &arr`	`x/5xw &arr`, and `x/5xw arr` is an error on an array, see below
`x/5i $pc`	`x/5i $pc` · `disassemble -s $pc -c 5`
`find &a, +100, 0xdead`	`memory find -e 0xdead -- &a &a+100`
`info registers` / `i r`	`register read` · `re r`
`info all-registers`	`register read --all`
`p $rsp`	`p $rsp`, `register read sp` also works
`set var $rax = 0`	`register write rax 0`
`disassemble`	`disassemble --frame` · `di -f`
`disassemble /s f`	`disassemble -m -n f` (`--mixed`)
`disassemble /r f`	`disassemble -b -n f` (`--bytes`)
`info symbol 0x1000`	`image lookup --address 0x1000` · `im loo -a 0x1000`
`info line f`	`image lookup -F f` or `source info -f file.c`
`info functions ^http_`	`image lookup -r -n ^http_`
`info sharedlibrary`	`image list` · `target modules list`
`info proc mappings`	`memory region ADDR`, one region at a time
`gcore out.core`	`process save-core out.core`
`set sysroot /tmp/root`	`platform select -S /tmp/root remote-linux`, plus `target.exec-search-paths`
`set solib-search-path A`	`settings set target.exec-search-paths A`
`set substitute-path A B`	`settings set target.source-map A B`

Settings, Scripting, and the UI

gdb	lldb
`set confirm off`	`settings set auto-confirm true`
`set pagination off`	no equivalent setting, lldb does not page command output
`set disassembly-flavor intel`	`settings set target.x86-disassembly-flavor intel`
`set follow-fork-mode child`	`settings set target.process.follow-fork-mode child`
`set stop-on-solib-events 1`	`settings set target.process.stop-on-sharedlibrary-events true`
`set print elements 0`	`settings set target.max-string-summary-length 4096`
`show CONFIG`	`settings show CONFIG`
`define NAME ... end`	`command alias NAME ...` for one command
a multi-line `define`	`command script add -f mod.fn NAME`
`python print(1)`	`script print(1)`
`python-interactive`	`script` with no argument
`source f.py`	`command script import f.py`
`gdb.execute("bt")`	`lldb.debugger.HandleCommand("bt")`
`gdb.parse_and_eval("x")`	`frame.EvaluateExpression("x")` in the SB API
`shell ls`	`platform shell ls`
`tui enable`	`gui`
`apropos WORD`	`apropos WORD`
`help break`	`help breakpoint set`
`quit` / `q`	`quit` · `q`

Differences That Bite

x needs an address, not an array. In lldb an array expression is not convertible to an address, so take it explicitly.

(lldb) x/5xw arr
error: invalid start address expression.
error: address expression "arr" resulted in a value whose type can't be
converted to an address: int[5]
(lldb) x/5xw &arr
0x100008000: 0x00000003 0x00000001 0x00000004 0x00000001

-b stops at the first error. In batch mode, one failing -o command aborts every command after it, so an out-of-scope variable silently truncates your script. gdb --batch keeps going.

No @ artificial arrays. p *ap@5 is a syntax error. Use parray 5 ap.

No syscall catchpoints and no scheduler locking. apropos syscall and apropos scheduler both come back empty. There is no substitute, and for single-thread stepping the closest thing is thread step-over with the other threads left running.

print is not expression. In current lldb, print and p are dwim-print, which tries a frame-variable lookup before evaluating an expression. It is faster and usually identical, but expression is what takes the full option set.

gdb on macOS

gdb still builds on macOS through Homebrew, but it cannot control a process without being granted debugging rights, so it needs a signed certificate with the com.apple.security.cs.debugger entitlement, or sudo. Symptoms of an unsigned gdb are:

Unable to find Mach task port for process-id 1234:
  (os/kern) failure (0x5). (please check gdb is codesigned)

The steps are creating a self-signed code-signing certificate in Keychain Access, trusting it for code signing, then codesign -s <cert> --entitlements gdb.xml $(which gdb) with an entitlements plist granting com.apple.security.cs.debugger, and a reboot or a taskgated restart. gdb also lags behind Apple's arm64 platform support, so on Apple silicon lldb is the practical choice and this table is the translation layer. On Linux both work fully, and the choice is only preference.