Subversion Repositories or1k

This is gdb.info, produced by makeinfo version 4.1 from ./gdb.texinfo.

INFO-DIR-SECTION Programming & development tools.

START-INFO-DIR-ENTRY

* Gdb: (gdb).                     The GNU debugger.

END-INFO-DIR-ENTRY

   This file documents the GNU debugger GDB.

   This is the Ninth Edition, December 2001, of `Debugging with GDB:

the GNU Source-Level Debugger' for GDB Version 5.3.

   Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,

1998,

1999, 2000, 2001, 2002 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.1 or

any later version published by the Free Software Foundation; with the

Invariant Sections being "Free Software" and "Free Software Needs Free

Documentation", with the Front-Cover Texts being "A GNU Manual," and

with the Back-Cover Texts as in (a) below.

   (a) The Free Software Foundation's Back-Cover Text is: "You have

freedom to copy and modify this GNU Manual, like GNU software.  Copies

published by the Free Software Foundation raise funds for GNU

development."

File: gdb.info,  Node: ST2000,  Next: Z8000,  Prev: Sparclite,  Up: Embedded Processors

Tandem ST2000

-------------

   GDB may be used with a Tandem ST2000 phone switch, running Tandem's

STDBUG protocol.

   To connect your ST2000 to the host system, see the manufacturer's

manual.  Once the ST2000 is physically attached, you can run:

     target st2000 DEV SPEED

to establish it as your debugging environment.  DEV is normally the

name of a serial device, such as `/dev/ttya', connected to the ST2000

via a serial line.  You can instead specify DEV as a TCP connection

(for example, to a serial line attached via a terminal concentrator)

using the syntax `HOSTNAME:PORTNUMBER'.

   The `load' and `attach' commands are _not_ defined for this target;

you must load your program into the ST2000 as you normally would for

standalone operation.  GDB reads debugging information (such as

symbols) from a separate, debugging version of the program available on

your host computer.

   These auxiliary GDB commands are available to help you with the

ST2000 environment:

`st2000 COMMAND'

     Send a COMMAND to the STDBUG monitor.  See the manufacturer's

     manual for available commands.

`connect'

     Connect the controlling terminal to the STDBUG command monitor.

     When you are done interacting with STDBUG, typing either of two

     character sequences gets you back to the GDB command prompt:

     `~.' (Return, followed by tilde and period) or `~'

     (Return, followed by tilde and control-D).

File: gdb.info,  Node: Z8000,  Prev: ST2000,  Up: Embedded Processors

Zilog Z8000

-----------

   When configured for debugging Zilog Z8000 targets, GDB includes a

Z8000 simulator.

   For the Z8000 family, `target sim' simulates either the Z8002 (the

unsegmented variant of the Z8000 architecture) or the Z8001 (the

segmented variant).  The simulator recognizes which architecture is

appropriate by inspecting the object code.

`target sim ARGS'

     Debug programs on a simulated CPU.  If the simulator supports setup

     options, specify them via ARGS.

After specifying this target, you can debug programs for the simulated

CPU in the same style as programs for your host computer; use the

`file' command to load a new program image, the `run' command to run

your program, and so on.

   As well as making available all the usual machine registers (*note

Registers: Registers.), the Z8000 simulator provides three additional

items of information as specially named registers:

`cycles'

     Counts clock-ticks in the simulator.

`insts'

     Counts instructions run in the simulator.

`time'

     Execution time in 60ths of a second.

   You can refer to these values in GDB expressions with the usual

conventions; for example, `b fputc if $cycles>5000' sets a conditional

breakpoint that suspends only after at least 5000 simulated clock ticks.

File: gdb.info,  Node: Architectures,  Prev: Embedded Processors,  Up: Configurations

Architectures

=============

   This section describes characteristics of architectures that affect

all uses of GDB with the architecture, both native and cross.

* Menu:

* A29K::

* Alpha::

* MIPS::

File: gdb.info,  Node: A29K,  Next: Alpha,  Up: Architectures

A29K

----

`set rstack_high_address ADDRESS'

     On AMD 29000 family processors, registers are saved in a separate

     "register stack".  There is no way for GDB to determine the extent

     of this stack.  Normally, GDB just assumes that the stack is

     "large enough".  This may result in GDB referencing memory

     locations that do not exist.  If necessary, you can get around

     this problem by specifying the ending address of the register

     stack with the `set rstack_high_address' command.  The argument

     should be an address, which you probably want to precede with `0x'

     to specify in hexadecimal.

`show rstack_high_address'

     Display the current limit of the register stack, on AMD 29000

     family processors.

File: gdb.info,  Node: Alpha,  Next: MIPS,  Prev: A29K,  Up: Architectures

Alpha

-----

   See the following section.

File: gdb.info,  Node: MIPS,  Prev: Alpha,  Up: Architectures

MIPS

----

   Alpha- and MIPS-based computers use an unusual stack frame, which

sometimes requires GDB to search backward in the object code to find

the beginning of a function.

   To improve response time (especially for embedded applications, where

GDB may be restricted to a slow serial line for this search) you may

want to limit the size of this search, using one of these commands:

`set heuristic-fence-post LIMIT'

     Restrict GDB to examining at most LIMIT bytes in its search for

     the beginning of a function.  A value of 0 (the default) means

     there is no limit.  However, except for 0, the larger the limit

     the more bytes `heuristic-fence-post' must search and therefore

     the longer it takes to run.

`show heuristic-fence-post'

     Display the current limit.

These commands are available _only_ when GDB is configured for

debugging programs on Alpha or MIPS processors.

File: gdb.info,  Node: Controlling GDB,  Next: Sequences,  Prev: Configurations,  Up: Top

Controlling GDB

***************

   You can alter the way GDB interacts with you by using the `set'

command.  For commands controlling how GDB displays data, see *Note

Print settings: Print Settings.  Other settings are described here.

* Menu:

* Prompt::                      Prompt

* Editing::                     Command editing

* History::                     Command history

* Screen Size::                 Screen size

* Numbers::                     Numbers

* Messages/Warnings::           Optional warnings and messages

* Debugging Output::            Optional messages about internal happenings

File: gdb.info,  Node: Prompt,  Next: Editing,  Up: Controlling GDB

Prompt

======

   GDB indicates its readiness to read a command by printing a string

called the "prompt".  This string is normally `(gdb)'.  You can change

the prompt string with the `set prompt' command.  For instance, when

debugging GDB with GDB, it is useful to change the prompt in one of the

GDB sessions so that you can always tell which one you are talking to.

   _Note:_  `set prompt' does not add a space for you after the prompt

you set.  This allows you to set a prompt which ends in a space or a

prompt that does not.

`set prompt NEWPROMPT'

     Directs GDB to use NEWPROMPT as its prompt string henceforth.

`show prompt'

     Prints a line of the form: `Gdb's prompt is: YOUR-PROMPT'

File: gdb.info,  Node: Editing,  Next: History,  Prev: Prompt,  Up: Controlling GDB

Command editing

===============

   GDB reads its input commands via the "readline" interface.  This GNU

library provides consistent behavior for programs which provide a

command line interface to the user.  Advantages are GNU Emacs-style or

"vi"-style inline editing of commands, `csh'-like history substitution,

and a storage and recall of command history across debugging sessions.

   You may control the behavior of command line editing in GDB with the

command `set'.

`set editing'

`set editing on'

     Enable command line editing (enabled by default).

`set editing off'

     Disable command line editing.

`show editing'

     Show whether command line editing is enabled.

File: gdb.info,  Node: History,  Next: Screen Size,  Prev: Editing,  Up: Controlling GDB

Command history

===============

   GDB can keep track of the commands you type during your debugging

sessions, so that you can be certain of precisely what happened.  Use

these commands to manage the GDB command history facility.

`set history filename FNAME'

     Set the name of the GDB command history file to FNAME.  This is

     the file where GDB reads an initial command history list, and

     where it writes the command history from this session when it

     exits.  You can access this list through history expansion or

     through the history command editing characters listed below.  This

     file defaults to the value of the environment variable

     `GDBHISTFILE', or to `./.gdb_history' (`./_gdb_history' on MS-DOS)

     if this variable is not set.

`set history save'

`set history save on'

     Record command history in a file, whose name may be specified with

     the `set history filename' command.  By default, this option is

     disabled.

`set history save off'

     Stop recording command history in a file.

`set history size SIZE'

     Set the number of commands which GDB keeps in its history list.

     This defaults to the value of the environment variable `HISTSIZE',

     or to 256 if this variable is not set.

   History expansion assigns special meaning to the character `!'.

   Since `!' is also the logical not operator in C, history expansion

is off by default. If you decide to enable history expansion with the

`set history expansion on' command, you may sometimes need to follow

`!' (when it is used as logical not, in an expression) with a space or

a tab to prevent it from being expanded.  The readline history

facilities do not attempt substitution on the strings `!=' and `!(',

even when history expansion is enabled.

   The commands to control history expansion are:

`set history expansion on'

`set history expansion'

     Enable history expansion.  History expansion is off by default.

`set history expansion off'

     Disable history expansion.

     The readline code comes with more complete documentation of

     editing and history expansion features.  Users unfamiliar with GNU

     Emacs or `vi' may wish to read it.

`show history'

`show history filename'

`show history save'

`show history size'

`show history expansion'

     These commands display the state of the GDB history parameters.

     `show history' by itself displays all four states.

`show commands'

     Display the last ten commands in the command history.

`show commands N'

     Print ten commands centered on command number N.

`show commands +'

     Print ten commands just after the commands last printed.

File: gdb.info,  Node: Screen Size,  Next: Numbers,  Prev: History,  Up: Controlling GDB

Screen size

===========

   Certain commands to GDB may produce large amounts of information

output to the screen.  To help you read all of it, GDB pauses and asks

you for input at the end of each page of output.  Type  when you

want to continue the output, or `q' to discard the remaining output.

Also, the screen width setting determines when to wrap lines of output.

Depending on what is being printed, GDB tries to break the line at a

readable place, rather than simply letting it overflow onto the

following line.

   Normally GDB knows the size of the screen from the terminal driver

software.  For example, on Unix GDB uses the termcap data base together

with the value of the `TERM' environment variable and the `stty rows'

and `stty cols' settings.  If this is not correct, you can override it

with the `set height' and `set width' commands:

`set height LPP'

`show height'

`set width CPL'

`show width'

     These `set' commands specify a screen height of LPP lines and a

     screen width of CPL characters.  The associated `show' commands

     display the current settings.

     If you specify a height of zero lines, GDB does not pause during

     output no matter how long the output is.  This is useful if output

     is to a file or to an editor buffer.

     Likewise, you can specify `set width 0' to prevent GDB from

     wrapping its output.

File: gdb.info,  Node: Numbers,  Next: Messages/Warnings,  Prev: Screen Size,  Up: Controlling GDB

Numbers

=======

   You can always enter numbers in octal, decimal, or hexadecimal in

GDB by the usual conventions: octal numbers begin with `0', decimal

numbers end with `.', and hexadecimal numbers begin with `0x'.  Numbers

that begin with none of these are, by default, entered in base 10;

likewise, the default display for numbers--when no particular format is

specified--is base 10.  You can change the default base for both input

and output with the `set radix' command.

`set input-radix BASE'

     Set the default base for numeric input.  Supported choices for

     BASE are decimal 8, 10, or 16.  BASE must itself be specified

     either unambiguously or using the current default radix; for

     example, any of

          set radix 012

          set radix 10.

          set radix 0xa

     sets the base to decimal.  On the other hand, `set radix 10'

     leaves the radix unchanged no matter what it was.

`set output-radix BASE'

     Set the default base for numeric display.  Supported choices for

     BASE are decimal 8, 10, or 16.  BASE must itself be specified

     either unambiguously or using the current default radix.

`show input-radix'

     Display the current default base for numeric input.

`show output-radix'

     Display the current default base for numeric display.

File: gdb.info,  Node: Messages/Warnings,  Next: Debugging Output,  Prev: Numbers,  Up: Controlling GDB

Optional warnings and messages

==============================

   By default, GDB is silent about its inner workings.  If you are

running on a slow machine, you may want to use the `set verbose'

command.  This makes GDB tell you when it does a lengthy internal

operation, so you will not think it has crashed.

   Currently, the messages controlled by `set verbose' are those which

announce that the symbol table for a source file is being read; see

`symbol-file' in *Note Commands to specify files: Files.

`set verbose on'

     Enables GDB output of certain informational messages.

`set verbose off'

     Disables GDB output of certain informational messages.

`show verbose'

     Displays whether `set verbose' is on or off.

   By default, if GDB encounters bugs in the symbol table of an object

file, it is silent; but if you are debugging a compiler, you may find

this information useful (*note Errors reading symbol files: Symbol

Errors.).

`set complaints LIMIT'

     Permits GDB to output LIMIT complaints about each type of unusual

     symbols before becoming silent about the problem.  Set LIMIT to

     zero to suppress all complaints; set it to a large number to

     prevent complaints from being suppressed.

`show complaints'

     Displays how many symbol complaints GDB is permitted to produce.

   By default, GDB is cautious, and asks what sometimes seems to be a

lot of stupid questions to confirm certain commands.  For example, if

you try to run a program which is already running:

     (gdb) run

     The program being debugged has been started already.

     Start it from the beginning? (y or n)

   If you are willing to unflinchingly face the consequences of your own

commands, you can disable this "feature":

`set confirm off'

     Disables confirmation requests.

`set confirm on'

     Enables confirmation requests (the default).

`show confirm'

     Displays state of confirmation requests.

File: gdb.info,  Node: Debugging Output,  Prev: Messages/Warnings,  Up: Controlling GDB

Optional messages about internal happenings

===========================================

`set debug arch'

     Turns on or off display of gdbarch debugging info. The default is

     off

`show debug arch'

     Displays the current state of displaying gdbarch debugging info.

`set debug event'

     Turns on or off display of GDB event debugging info. The default

     is off.

`show debug event'

     Displays the current state of displaying GDB event debugging info.

`set debug expression'

     Turns on or off display of GDB expression debugging info. The

     default is off.

`show debug expression'

     Displays the current state of displaying GDB expression debugging

     info.

`set debug overload'

     Turns on or off display of GDB C++ overload debugging info. This

     includes info such as ranking of functions, etc. The default is

     off.

`show debug overload'

     Displays the current state of displaying GDB C++ overload

     debugging info.

`set debug remote'

     Turns on or off display of reports on all packets sent back and

     forth across the serial line to the remote machine.  The info is

     printed on the GDB standard output stream. The default is off.

`show debug remote'

     Displays the state of display of remote packets.

`set debug serial'

     Turns on or off display of GDB serial debugging info. The default

     is off.

`show debug serial'

     Displays the current state of displaying GDB serial debugging info.

`set debug target'

     Turns on or off display of GDB target debugging info. This info

     includes what is going on at the target level of GDB, as it

     happens. The default is off.

`show debug target'

     Displays the current state of displaying GDB target debugging info.

`set debug varobj'

     Turns on or off display of GDB variable object debugging info. The

     default is off.

`show debug varobj'

     Displays the current state of displaying GDB variable object

     debugging info.

File: gdb.info,  Node: Sequences,  Next: TUI,  Prev: Controlling GDB,  Up: Top

Canned Sequences of Commands

****************************

   Aside from breakpoint commands (*note Breakpoint command lists:

Break Commands.), GDB provides two ways to store sequences of commands

for execution as a unit: user-defined commands and command files.

* Menu:

* Define::                      User-defined commands

* Hooks::                       User-defined command hooks

* Command Files::               Command files

* Output::                      Commands for controlled output

File: gdb.info,  Node: Define,  Next: Hooks,  Up: Sequences

User-defined commands

=====================

   A "user-defined command" is a sequence of GDB commands to which you

assign a new name as a command.  This is done with the `define'

command.  User commands may accept up to 10 arguments separated by

whitespace.  Arguments are accessed within the user command via

$ARG0...$ARG9.  A trivial example:

     define adder

       print $arg0 + $arg1 + $arg2

To execute the command use:

     adder 1 2 3

This defines the command `adder', which prints the sum of its three

arguments.  Note the arguments are text substitutions, so they may

reference variables, use complex expressions, or even perform inferior

functions calls.

`define COMMANDNAME'

     Define a command named COMMANDNAME.  If there is already a command

     by that name, you are asked to confirm that you want to redefine

     it.

     The definition of the command is made up of other GDB command

     lines, which are given following the `define' command.  The end of

     these commands is marked by a line containing `end'.

`if'

     Takes a single argument, which is an expression to evaluate.  It

     is followed by a series of commands that are executed only if the

     expression is true (nonzero).  There can then optionally be a line

     `else', followed by a series of commands that are only executed if

     the expression was false.  The end of the list is marked by a line

     containing `end'.

`while'

     The syntax is similar to `if': the command takes a single argument,

     which is an expression to evaluate, and must be followed by the

     commands to execute, one per line, terminated by an `end'.  The

     commands are executed repeatedly as long as the expression

     evaluates to true.

`document COMMANDNAME'

     Document the user-defined command COMMANDNAME, so that it can be

     accessed by `help'.  The command COMMANDNAME must already be

     defined.  This command reads lines of documentation just as

     `define' reads the lines of the command definition, ending with

     `end'.  After the `document' command is finished, `help' on command

     COMMANDNAME displays the documentation you have written.

     You may use the `document' command again to change the

     documentation of a command.  Redefining the command with `define'

     does not change the documentation.

`help user-defined'

     List all user-defined commands, with the first line of the

     documentation (if any) for each.

`show user'

`show user COMMANDNAME'

     Display the GDB commands used to define COMMANDNAME (but not its

     documentation).  If no COMMANDNAME is given, display the

     definitions for all user-defined commands.

`show max-user-call-depth'

`set max-user-call-depth'

     The value of `max-user-call-depth' controls how many recursion

     levels are allowed in user-defined commands before GDB suspects an

     infinite recursion and aborts the command.

   When user-defined commands are executed, the commands of the

definition are not printed.  An error in any command stops execution of

the user-defined command.

   If used interactively, commands that would ask for confirmation

proceed without asking when used inside a user-defined command.  Many

GDB commands that normally print messages to say what they are doing

omit the messages when used in a user-defined command.

File: gdb.info,  Node: Hooks,  Next: Command Files,  Prev: Define,  Up: Sequences

User-defined command hooks

==========================

   You may define "hooks", which are a special kind of user-defined

command.  Whenever you run the command `foo', if the user-defined

command `hook-foo' exists, it is executed (with no arguments) before

that command.

   A hook may also be defined which is run after the command you

executed.  Whenever you run the command `foo', if the user-defined

command `hookpost-foo' exists, it is executed (with no arguments) after

that command.  Post-execution hooks may exist simultaneously with

pre-execution hooks, for the same command.

   It is valid for a hook to call the command which it hooks.  If this

occurs, the hook is not re-executed, thereby avoiding infinte recursion.

   In addition, a pseudo-command, `stop' exists.  Defining

(`hook-stop') makes the associated commands execute every time

execution stops in your program: before breakpoint commands are run,

displays are printed, or the stack frame is printed.

   For example, to ignore `SIGALRM' signals while single-stepping, but

treat them normally during normal execution, you could define:

     define hook-stop

     handle SIGALRM nopass

     end

     define hook-run

     handle SIGALRM pass

     end

     define hook-continue

     handle SIGLARM pass

     end

   As a further example, to hook at the begining and end of the `echo'

command, and to add extra text to the beginning and end of the message,

you could define:

     define hook-echo

     echo <<<---

     end

     define hookpost-echo

     echo --->>>\n

     end

     (gdb) echo Hello World

     <<<---Hello World--->>>

     (gdb)

   You can define a hook for any single-word command in GDB, but not

for command aliases; you should define a hook for the basic command

name, e.g.  `backtrace' rather than `bt'.  If an error occurs during

the execution of your hook, execution of GDB commands stops and GDB

issues a prompt (before the command that you actually typed had a

chance to run).

   If you try to define a hook which does not match any known command,

you get a warning from the `define' command.

File: gdb.info,  Node: Command Files,  Next: Output,  Prev: Hooks,  Up: Sequences

Command files

=============

   A command file for GDB is a file of lines that are GDB commands.

Comments (lines starting with `#') may also be included.  An empty line

in a command file does nothing; it does not mean to repeat the last

command, as it would from the terminal.

   When you start GDB, it automatically executes commands from its

"init files", normally called `.gdbinit'(1).  During startup, GDB does

the following:

  1. Reads the init file (if any) in your home directory(2).

  2. Processes command line options and operands.

  3. Reads the init file (if any) in the current working directory.

  4. Reads command files specified by the `-x' option.

   The init file in your home directory can set options (such as `set

complaints') that affect subsequent processing of command line options

and operands.  Init files are not executed if you use the `-nx' option

(*note Choosing modes: Mode Options.).

   On some configurations of GDB, the init file is known by a different

name (these are typically environments where a specialized form of GDB

may need to coexist with other forms, hence a different name for the

specialized version's init file).  These are the environments with

special init file names:

   * VxWorks (Wind River Systems real-time OS): `.vxgdbinit'

   * OS68K (Enea Data Systems real-time OS): `.os68gdbinit'

   * ES-1800 (Ericsson Telecom AB M68000 emulator): `.esgdbinit'

   You can also request the execution of a command file with the

`source' command:

`source FILENAME'

     Execute the command file FILENAME.

   The lines in a command file are executed sequentially.  They are not

printed as they are executed.  An error in any command terminates

execution of the command file and control is returned to the console.

   Commands that would ask for confirmation if used interactively

proceed without asking when used in a command file.  Many GDB commands

that normally print messages to say what they are doing omit the

messages when called from command files.

   GDB also accepts command input from standard input.  In this mode,

normal output goes to standard output and error output goes to standard

error.  Errors in a command file supplied on standard input do not

terminate execution of the command file -- execution continues with the

next command.

     gdb < cmds > log 2>&1

   (The syntax above will vary depending on the shell used.) This

example will execute commands from the file `cmds'. All output and

errors would be directed to `log'.

   ---------- Footnotes ----------

   (1) The DJGPP port of GDB uses the name `gdb.ini' instead, due to the

limitations of file names imposed by DOS filesystems.

   (2) On DOS/Windows systems, the home directory is the one pointed to

by the `HOME' environment variable.

File: gdb.info,  Node: Output,  Prev: Command Files,  Up: Sequences

Commands for controlled output

==============================

   During the execution of a command file or a user-defined command,

normal GDB output is suppressed; the only output that appears is what is

explicitly printed by the commands in the definition.  This section

describes three commands useful for generating exactly the output you

want.

`echo TEXT'

     Print TEXT.  Nonprinting characters can be included in TEXT using

     C escape sequences, such as `\n' to print a newline.  *No newline

     is printed unless you specify one.* In addition to the standard C

     escape sequences, a backslash followed by a space stands for a

     space.  This is useful for displaying a string with spaces at the

     beginning or the end, since leading and trailing spaces are

     otherwise trimmed from all arguments.  To print ` and foo = ', use

     the command `echo \ and foo = \ '.

     A backslash at the end of TEXT can be used, as in C, to continue

     the command onto subsequent lines.  For example,

          echo This is some text\n\

          which is continued\n\

          onto several lines.\n

     produces the same output as

          echo This is some text\n

          echo which is continued\n

          echo onto several lines.\n

`output EXPRESSION'

     Print the value of EXPRESSION and nothing but that value: no

     newlines, no `$NN = '.  The value is not entered in the value

     history either.  *Note Expressions: Expressions, for more

     information on expressions.

`output/FMT EXPRESSION'

     Print the value of EXPRESSION in format FMT.  You can use the same

     formats as for `print'.  *Note Output formats: Output Formats, for

     more information.

`printf STRING, EXPRESSIONS...'

     Print the values of the EXPRESSIONS under the control of STRING.

     The EXPRESSIONS are separated by commas and may be either numbers

     or pointers.  Their values are printed as specified by STRING,

     exactly as if your program were to execute the C subroutine

          printf (STRING, EXPRESSIONS...);

     For example, you can print two values in hex like this:

          printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo

     The only backslash-escape sequences that you can use in the format

     string are the simple ones that consist of backslash followed by a

     letter.

File: gdb.info,  Node: TUI,  Next: Emacs,  Prev: Sequences,  Up: Top

GDB Text User Interface

***********************

* Menu:

* TUI Overview::                TUI overview

* TUI Keys::                    TUI key bindings

* TUI Single Key Mode::         TUI single key mode

* TUI Commands::                TUI specific commands

* TUI Configuration::           TUI configuration variables

   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 (*note Configure Options::).

File: gdb.info,  Node: TUI Overview,  Next: TUI Keys,  Up: TUI

TUI overview

============

   The TUI has two display modes that can be switched while GDB runs:

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

_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 and assembly windows show the current program position by

highlighting the current line and marking them with the `>' marker.

Breakpoints are also indicated with two markers.  A first one 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 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:

   * source

   * assembly

   * source and assembly

   * source and registers

   * assembly and registers

   On top of the command window a status line gives various information

concerning the current process begin debugged.  The status line is

updated when the information it shows changes.  The following fields

are displayed:

_target_

     Indicates the current gdb target (*note Specifying a Debugging

     Target: Targets.).

_process_

     Gives information about 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 (*note Print Settings::).