20. GDB Text User Interface

The GDB Text User Interface, TUI in short,
is a terminal interface which uses the curses library
to show the source file, the assembly output, the program registers
and GDB commands in separate text windows.
The TUI is available only when GDB is configured
with the --enable-tui configure option (see section B.3 configure options).

20.1 TUI overview

A curses (or TUI) mode in which it displays several text
windows on the terminal.

A standard mode which corresponds to the GDB configured without
the TUI.

In the TUI mode, GDB can display several text window
on the terminal:

command

This window is the GDB command window with the GDB
prompt and the GDB outputs. The GDB input is still
managed using readline but through the TUI. The command
window is always visible.

source

The source window shows the source file of the program. The current
line as well as active breakpoints are displayed in this window.
The current program position is shown with the `>' marker and
active breakpoints are shown with `*' markers.

assembly

The assembly window shows the disassembly output of the program.

register

This window shows the processor registers. It detects when
a register is changed and when this is the case, registers that have
changed are highlighted.

The source, assembly and register windows are attached to the thread
and the frame position. They are updated when the current thread
changes, when the frame changes or when the program counter changes.
These three windows are arranged by the TUI according to several
layouts. The layout defines which of these three windows are visible.
The following layouts are available:

20.2 TUI Key Bindings

The TUI installs several key bindings in the readline keymaps
(see section 25. Command Line Editing).
They allow to leave or enter in the TUI mode or they operate
directly on the TUI layout and windows. The following key bindings
are installed for both TUI mode and the GDB standard mode.

C-x C-a

C-x a

C-x A

Enter or leave the TUI mode. When the TUI mode is left,
the curses window management is left and GDB operates using
its standard mode writing on the terminal directly. When the TUI
mode is entered, the control is given back to the curses windows.
The screen is then refreshed.

C-x 1

Use a TUI layout with only one window. The layout will
either be `source' or `assembly'. When the TUI mode
is not active, it will switch to the TUI mode.

Think of this key binding as the Emacs C-x 1 binding.

C-x 2

Use a TUI layout with at least two windows. When the current
layout shows already two windows, a next layout with two windows is used.
When a new layout is chosen, one window will always be common to the
previous layout and the new one.

Think of it as the Emacs C-x 2 binding.

The following key bindings are handled only by the TUI mode:

PgUp

Scroll the active window one page up.

PgDn

Scroll the active window one page down.

Up

Scroll the active window one line up.

Down

Scroll the active window one line down.

Left

Scroll the active window one column left.

Right

Scroll the active window one column right.

C-L

Refresh the screen.

In the TUI mode, the arrow keys are used by the active window
for scrolling. This means they are not available for readline. It is
necessary to use other readline key bindings such as C-p, C-n,
C-b and C-f.

20.3 TUI specific commands

The TUI has specific commands to control the text windows.
These commands are always available, that is they do not depend on
the current terminal mode in which GDB runs. When GDB
is in the standard mode, using these commands will automatically switch
in the TUI mode.

layout next

Display the next layout.

layout prev

Display the previous layout.

layout src

Display the source window only.

layout asm

Display the assembly window only.

layout split

Display the source and assembly window.

layout regs

Display the register window together with the source or assembly window.

focus next | prev | src | asm | regs | split

Set the focus to the named window.
This command allows to change the active window so that scrolling keys
can be affected to another window.

refresh

Refresh the screen. This is similar to using C-L key.

update

Update the source window and the current execution point.

winheight name +count

winheight name -count

Change the height of the window name by count
lines. Positive counts increase the height, while negative counts
decrease it.