Text User Interface (TUI) mode

The Text User Interface (TUI) mode is a graphical interface for GDB that runs in a terminal. UDB extends the interface with additional functionality. This page covers the most important topics for using TUI mode in UDB. Please refer to the GDB documentation for full details on GDB’s TUI mode.

TUI mode can be enabled with the tui enable command and disabled with the tui disable command, or toggled with the C-x a key sequence

Note

The notation C-x a means holding the Control key and typing x, then releasing the Control key and typing a.

Layouts

The default TUI layout is the src layout which shows the source code on the top of the screen and the command window on the bottom of the screen.

Note

The dashboard layout provides an IDE-like experience with multiple windows and is recommended for most debugging tasks.

Layouts can be activated directly with the layout command or cycled with the C-x 2 key sequence:

  • layout src: Shows the program’s source code.

  • layout asm: Shows the program’s assembly code.

  • layout regs: Shows the program’s registers and the source or assembly window.

  • layout split: Shows the source and assembly window.

  • layout locals: Shows the program’s local variables.

  • layout backtrace: Shows the program’s backtrace.

  • layout timeline: Shows the timeline of the current session.

  • layout threads: Shows the program’s threads.

  • layout breakpoints: Shows the breakpoints in the current session.

  • layout dashboard: Shows information about the source code, local variables, the backtrace and the timeline of the session.

  • layout dashboard-split: Same as layout dashboard, but both the source and assembly window.

Note

The following TUI windows and layouts are experimental and may be changed or removed without notice in future releases: locals, backtrace, timeline, threads, breakpoints, dashboard, dashboard-split.

Custom layouts can be defined with the tui new-layout command. See the TUI commands documentation.

Terminal output

Any terminal output that does not come directly from UDB can interfere with the user interface. When this happens, use the refresh command or type C-l to redraw the screen.

To avoid the need to use the refresh command, configure UDB so that the output from the program does not go to the terminal. Use one of these approaches:

  • Before launching the program, use the set args command to redirect the program output to a file, for example, set args > /dev/null.

  • Before launching the program, use the set inferior-tty command to give the program its own terminal, for example, set inferior-tty /dev/pts/2.

    Use this approach if you need to interact with your program’s input or monitor your program’s output, while it is being recorded.

  • In replay mode, use the set replay-standard-streams off command to disable the program output.

Window focus

Use the arrow keys to interact with the TUI window that has the focus.

By default, the command window has the focus, so that the Up and Down keys navigate the command history. This is different from GDB where by default, the source window has the focus.

After giving the focus to a window you can use the arrow keys, and the PageUp and PageDown keys, to scroll the content of the window.

  • Use the focus command to give the focus to a specific window, for example, focus src.

  • Use the C-x o key sequence to cycle the focus between all the windows.

Note

Regardless of which window has the focus, the C-n and C-p key bindings always navigate the command history.

Mouse

If your terminal supports mouse operations, the mouse wheel scrolls the window under the mouse pointer, except for the command window.

If your terminal does not appear to support mouse operations, it may need to be enabled. Please refer to your terminal’s documentation.

Text selection

Text selection does not work as normal while TUI mode is active because the mouse events are consumed directly by UDB.

Most terminal emulators let you override this behaviour by holding down a modifier key to access the terminal’s native selection and copying functionality. This is often the Shift key, but it could be other keys such as the Alt, Option or Fn keys. Please refer to your terminal emulator’s documentation.

Use the set tui mouse-events off command to disable mouse support. This re-enables text selection with the mouse.

Custom key bindings

You can define your own key bindings in the ~/.inputrc file. For example, to enable the dashboard layout with the C-x c key sequence:

$if gdb
  "\C-xc": "layout dashboard\n"
$endif

See the readline documentation for details on the file format.