Debugging with GDB: TUI

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 25. GDB Text User Interface

> 25.1 TUI Overview |  | TUI overview
> 25.2 TUI Key Bindings |  | TUI key bindings
> 25.3 TUI Single Key Mode |  | TUI single key mode
> 25.4 TUI-specific Commands |  | TUI-specific commands
> 25.5 TUI Configuration Variables |  | TUI configuration variables

The GDB Text User Interface (TUI) 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 mode is supported only on platforms where a suitable version of the `curses` library is available.

The TUI mode is enabled by default when you invoke GDB as ``gdb -tui'`. You can also switch in and out of TUI mode while GDB runs by using various TUI commands and key bindings, such as `C-x C-a`. See section TUI Key Bindings.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 25.1 TUI Overview

In TUI mode, GDB can display several text windows:

command
  This window is the GDB command window with the GDB prompt and the GDB output. The GDB input is still managed using readline.

source
  The source window shows the source file of the program. The current line and active breakpoints are displayed in this window.

assembly
  The assembly window shows the disassembly output of the program.

register
  This window shows the processor registers. Registers are highlighted when their values change.

The source and assembly windows show the current program position by highlighting the current line and marking it with a ``>'` marker. Breakpoints are indicated with two markers. The first marker indicates the breakpoint type:

`B`
  Breakpoint which was hit at least once.

`b`
  Breakpoint which was never hit.

`H`
  Hardware breakpoint which was hit at least once.

`h`
  Hardware breakpoint which was never hit.

The second marker indicates whether the breakpoint is enabled or not:

`+`
  Breakpoint is enabled.

`-`
  Breakpoint is disabled.

The source, assembly and register windows are updated when the current thread changes, when the frame changes, or when the program counter changes.

These windows are not all visible at the same time. The command window is always visible. The others can be arranged in several layouts:

- source only,

- assembly only,

- source and assembly,

- source and registers, or

- assembly and registers.

A status line above the command window shows the following information:

target
  Indicates the current GDB target. (see section Specifying a Debugging Target).

process
  Gives the current process or thread number. When no process is being debugged, this field is set to `No process`.

function
  Gives the current function name for the selected frame. The name is demangled if demangling is turned on (see section 10.8 Print Settings). When there is no symbol corresponding to the current program counter, the string `??` is displayed.

line
  Indicates the current line number for the selected frame. When the current line number is not known, the string `??` is displayed.

pc
  Indicates the current program counter address.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 25.2 TUI Key Bindings

The TUI installs several key bindings in the readline keymaps (see section 32. Command Line Editing). 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 leaving the TUI mode, the curses window management stops and GDB operates using its standard mode, writing on the terminal directly. When reentering the TUI mode, 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 already has two windows, the 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.

`C-x o`
  Change the active window. The TUI associates several key bindings (like scrolling and arrow keys) with the active window. This command gives the focus to the next TUI window.

  Think of it as the Emacs `C-x o` binding.

`C-x s`
  Switch in and out of the TUI SingleKey mode that binds single keys to GDB commands (see section 25.3 TUI Single Key Mode).

The following key bindings only work in 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.

Because the arrow keys scroll the active window in the TUI mode, they are not available for their normal use by readline unless the command window has the focus. When another window is active, you must use other readline key bindings such as `C-p`, `C-n`, `C-b` and `C-f` to control the command window.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 25.3 TUI Single Key Mode

The TUI also provides a SingleKey mode, which binds several frequently used GDB commands to single keys. Type `C-x s` to switch into this mode, where the following key bindings are used:

`c`
  continue

`d`
  down

`f`
  finish

`n`
  next

`q`
  exit the SingleKey mode.

`r`
  run

`s`
  step

`u`
  up

`v`
  info locals

`w`
  where

Other keys temporarily switch to the GDB command prompt. The key that was pressed is inserted in the editing buffer so that it is possible to type most GDB commands without interaction with the TUI SingleKey mode. Once the command is entered the TUI SingleKey mode is restored. The only way to permanently leave this mode is by typing `q` or `C-x s`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 25.4 TUI-specific Commands

The TUI has specific commands to control the text windows. These commands are always available, even when GDB is not in the TUI mode. When GDB is in the standard mode, most of these commands will automatically switch to the TUI mode.

Note that if GDB's `stdout` is not connected to a terminal, or GDB has been started with the machine interface interpreter (see section The GDB/MI Interface), most of these commands will fail with an error, because it would not be possible or desirable to enable curses window management.

`info win`
  List and give the size of all displayed windows.

`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`
  Make the next window active for scrolling.

`focus prev`
  Make the previous window active for scrolling.

`focus src`
  Make the source window active for scrolling.

`focus asm`
  Make the assembly window active for scrolling.

`focus regs`
  Make the register window active for scrolling.

`focus cmd`
  Make the command window active for scrolling.

`refresh`
  Refresh the screen. This is similar to typing `C-L`.

`tui reg float`
  Show the floating point registers in the register window.

`tui reg general`
  Show the general registers in the register window.

`tui reg next`
  Show the next register group. The list of register groups as well as their order is target specific. The predefined register groups are the following: `general`, `float`, `system`, `vector`, `all`, `save`, `restore`.

`tui reg system`
  Show the system registers in the register window.

`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.

`tabset nchars`
  Set the width of tab stops to be nchars characters.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 25.5 TUI Configuration Variables

Several configuration variables control the appearance of TUI windows.

`set tui border-kind kind`
  Select the border appearance for the source, assembly and register windows. The possible values are the following:
  `space`
    Use a space character to draw the border.

  `ascii`
    Use ASCII characters ``+'`, ``-'` and ``|'` to draw the border.

  `acs`
    Use the Alternate Character Set to draw the border. The border is drawn using character line graphics if the terminal supports them.

`set tui border-mode mode`
`set tui active-border-mode mode`
  Select the display attributes for the borders of the inactive windows or the active window. The mode can be one of the following:
  `normal`
    Use normal attributes to display the border.

  `standout`
    Use standout mode.

  `reverse`
    Use reverse video mode.

  `half`
    Use half bright mode.

  `half-standout`
    Use half bright and standout mode.

  `bold`
    Use extra bright or bold mode.

  `bold-standout`
    Use extra bright or bold and standout mode.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 17 2014 using texi2html