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

tui enable

Activate TUI mode. The last active TUI window layout will be used if TUI mode has previously been used in the current debugging session, otherwise a default layout is used.

tui disable

Disable TUI mode, returning to the console interpreter.

info win

List and give the size of all displayed windows.

tui new-layout name window weight [window weight…]

Create a new TUI layout. The new layout will be named name, and can be accessed using the layout command (see below).

Each window parameter is either the name of a window to display, or a window description. The windows will be displayed from top to bottom in the order listed.

The names of the windows are the same as the ones given to the focus command (see below); additional, the status window can be specified. Note that, because it is of fixed height, the weight assigned to the status window is of no importance. It is conventional to use ‘0’ here.

A window description looks a bit like an invocation of tui new-layout, and is of the form {[-horizontal]window weight [window weight…]}.

This specifies a sub-layout. If -horizontal is given, the windows in this description will be arranged side-by-side, rather than top-to-bottom.

Each weight is an integer. It is the weight of this window relative to all the other windows in the layout. These numbers are used to calculate how much of the screen is given to each window.

For example:

(gdb) tui new-layout example src 1 regs 1 status 0 cmd 1

Here, the new layout is called ‘example’. It shows the source and register windows, followed by the status window, and then finally the command window. The non-status windows all have the same weight, so the terminal will be split into three roughly equal sections.

Here is a more complex example, showing a horizontal layout:

(gdb) tui new-layout example {-horizontal src 1 asm 1} 2 status 0 cmd 1

This will result in side-by-side source and assembly windows; with the status and command window being beneath these, filling the entire width of the terminal. Because they have weight 2, the source and assembly windows will be twice the height of the command window.

layout name

Changes which TUI windows are displayed. The name parameter controls which layout is shown. It can be either one of the built-in layout names, or the name of a layout defined by the user using tui new-layout.

The built-in layouts are as follows:

next

Display the next layout.

prev

Display the previous layout.

src

Display the source and command windows.

asm

Display the assembly and command windows.

split

Display the source, assembly, and command windows.

regs

When in src layout display the register, source, and command windows. When in asm or split layout display the register, assembler, and command windows.

focus name

Changes which TUI window is currently active for scrolling. The name parameter can be any of the following:

next

Make the next window active for scrolling.

prev

Make the previous window active for scrolling.

src

Make the source window active for scrolling.

asm

Make the assembly window active for scrolling.

regs

Make the register window active for scrolling.

cmd

Make the command window active for scrolling.

refresh

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

tui reg group

Changes the register group displayed in the tui register window to group. If the register window is not currently displayed this command will cause the register window to be displayed. The list of register groups, as well as their order is target specific. The following groups are available on most targets:

next

Repeatedly selecting this group will cause the display to cycle through all of the available register groups.

prev

Repeatedly selecting this group will cause the display to cycle through all of the available register groups in the reverse order to next.

general

Display the general registers.

float

Display the floating point registers.

system

Display the system registers.

vector

Display the vector registers.

all

Display all registers.

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. The name parameter can be one of src (the source window), cmd (the command window), asm (the disassembly window), or regs (the register display window).