GDB Cheatsheet

TUI and Layouts

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

Turning It On

The TUI is a curses split screen: source or assembly above, the gdb prompt below. It needs a real terminal, so it fails under a pipe or the machine interface.

gdb -tui ./prog        # start in the TUI
gdb ./prog             # then type tui enable

(gdb) tui enable
(gdb) tui disable
(gdb) info win
        Name       Lines Columns Focus
        src           15      80 (has focus)
        status         1      80
        cmd            8      80

Command	Effect
`tui enable`	activate the TUI, restoring the last layout used
`tui disable`	back to the plain console
`Ctrl-x a`	toggle the TUI on and off, also `Ctrl-x Ctrl-a` and `Ctrl-x A`
`info win`	list visible windows, their sizes, and which has focus
`tui refresh` or `refresh`	redraw everything, same as `Ctrl-l`

tui disable does not lose anything. Toggling out to read a long bt and back with Ctrl-x a is the normal rhythm, since scrollback in the cmd window is small.

Layouts

(gdb) layout src      # source and command
(gdb) layout asm      # disassembly and command
(gdb) layout split    # source, disassembly, and command
(gdb) layout regs     # adds registers to whichever of the above is active
(gdb) layout next
(gdb) layout prev

Layout	Windows
`src`	source plus command
`asm`	assembly plus command
`split`	source, assembly, and command
`regs`	registers plus whatever `src`, `asm`, or `split` was showing
`next` / `prev`	cycle through the layouts, built-in and user-defined

Key	Effect
`Ctrl-x 1`	a one-window layout, source or assembly
`Ctrl-x 2`	a layout with at least two windows, cycling
`Ctrl-x o`	move focus to the next window
`Ctrl-x s`	toggle SingleKey mode
`Ctrl-l`	redraw

layout regs is a modifier, not a standalone layout. From src it shows registers plus source, from asm it shows registers plus disassembly, which is why the same command looks different depending on where you were.

(gdb) tui reg general      # which register group the regs window shows
(gdb) tui reg float
(gdb) tui reg vector
(gdb) tui reg next

Focus and Sizing

Only one window is active for scrolling at a time, and the arrow keys go to it. That is why the up arrow sometimes scrolls source instead of recalling a command.

(gdb) focus cmd        # arrows go back to command history
(gdb) focus src
(gdb) focus asm
(gdb) focus regs
(gdb) focus next
(gdb) winheight src +8
(gdb) winheight cmd -4
(gdb) tui window height src 20
(gdb) tui window width src +10

Command	Effect
`focus NAME`	make that window active for scrolling, `next` and `prev` also work
`winheight NAME +N` / `-N`	grow or shrink a window by N lines
`tui window height NAME +N`	the long form of `winheight`
`tui window width NAME +N`	horizontal resize, for side-by-side layouts
`Ctrl-x o`	rotate focus, the fast version

Windows must always fill the terminal, so a resize only works when a neighbor can give up or absorb the space. With focus src the arrow keys scroll source and the readline history is unreachable until you focus cmd or press Ctrl-x o.

The Redraw Gotcha

The TUI does not own the terminal exclusively. Anything the inferior writes to stdout or stderr lands on top of the curses windows and scrambles the display.

(gdb) refresh          # or Ctrl-l, repaint everything

Fixes in rough order of preference:

1. refresh or Ctrl-l after each burst of program output. 2. Redirect the program's output away from the terminal: run > /tmp/out 2>&1. 3. Run the inferior on a second terminal. Start tty in another window, note the device, then tty /dev/pts/5 in gdb before run. 4. Turn the TUI off while the noisy part runs, back on afterward.

(gdb) tty /dev/pts/5
(gdb) run

A resized terminal can also leave the layout stale. refresh fixes that, and if the screen is unrecoverable tui disable then tui enable rebuilds every window.

SingleKey Mode and Looks

Ctrl-x s binds bare letters to stepping commands, so you drive the debugger one keystroke at a time. Any other key drops you back to the prompt with that character already typed.

Key	Command	Key	Command
`c`	`continue`	`C`	`reverse-continue`
`n`	`next`	`N`	`reverse-next`
`s`	`step`	`S`	`reverse-step`
`o`	`nexti`, step Over	`O`	`reverse-nexti`
`i`	`stepi`, step Into	`I`	`reverse-stepi`
`f`	`finish`	`F`	`reverse-finish`
`u`	`up`	`d`	`down`
`v`	`info locals`	`w`	`where`
`r`	`run`	`q`	leave SingleKey mode

(gdb) set tui border-kind acs        # space, ascii, or acs
(gdb) set tui border-mode normal
(gdb) set tui active-border-mode bold-standout
(gdb) set tui compact-source on      # narrower line-number column
(gdb) set tui tab-width 4
(gdb) set tui mouse-events off       # let the terminal handle selection again

set tui mouse-events off is the one worth knowing. With mouse events on, gdb eats clicks and you cannot select text to copy out of the source window. Put the settings you like in ~/.gdbinit, along with tui enable if you always want it.