blob: 0ecc602ca2c1ad4723098c9aeeb49d7921ea2a14 [file] [log] [blame]
This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo.
INFO-DIR-SECTION Software development
START-INFO-DIR-ENTRY
* Gdb: (gdb). The GNU debugger.
END-INFO-DIR-ENTRY
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
2010 2011, 2012 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.3 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 FSF's Back-Cover Text is: "You are free to copy and modify
this GNU Manual. Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom."
This file documents the GNU debugger GDB.
This is the Tenth Edition, of `Debugging with GDB: the GNU
Source-Level Debugger' for GDB (GDB) Version 7.5.
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
2010 2011, 2012 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.3 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 FSF's Back-Cover Text is: "You are free to copy and modify
this GNU Manual. Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom."

File: gdb.info, Node: objfile-gdb.py file, Next: dotdebug_gdb_scripts section, Up: Python Auto-loading
23.2.3.1 The `OBJFILE-gdb.py' file
..................................
When a new object file is read, GDB looks for a file named
`OBJFILE-gdb.py' (we call it SCRIPT-NAME below), where OBJFILE is the
object file's real name, formed by ensuring that the file name is
absolute, following all symlinks, and resolving `.' and `..'
components. If this file exists and is readable, GDB will evaluate it
as a Python script.
If this file does not exist, then GDB will look for SCRIPT-NAME file
in all of the directories as specified below.
Note that loading of this script file also requires accordingly
configured `auto-load safe-path' (*note Auto-loading safe path::).
`set auto-load scripts-directory [DIRECTORIES]'
Control GDB auto-loaded scripts location. Multiple directory
entries may be delimited by the host platform path separator in use
(`:' on Unix, `;' on MS-Windows and MS-DOS).
Each entry here needs to be covered also by the security setting
`set auto-load safe-path' (*note set auto-load safe-path::).
This variable defaults to `$debugdir:$datadir/auto-load'. The
default `set auto-load safe-path' value can be also overriden by
GDB configuration option `--with-auto-load-dir'.
Any reference to `$debugdir' will get replaced by
DEBUG-FILE-DIRECTORY value (*note Separate Debug Files::) and any
reference to `$datadir' will get replaced by DATA-DIRECTORY which
is determined at GDB startup (*note Data Files::). `$debugdir' and
`$datadir' must be placed as a directory component -- either alone
or delimited by `/' or `\' directory separators, depending on the
host platform.
The list of directories uses path separator (`:' on GNU and Unix
systems, `;' on MS-Windows and MS-DOS) to separate directories,
similarly to the `PATH' environment variable.
`show auto-load scripts-directory'
Show GDB auto-loaded scripts location.
GDB does not track which files it has already auto-loaded this way.
GDB will load the associated script every time the corresponding
OBJFILE is opened. So your `-gdb.py' file should be careful to avoid
errors if it is evaluated more than once.

File: gdb.info, Node: dotdebug_gdb_scripts section, Next: Which flavor to choose?, Prev: objfile-gdb.py file, Up: Python Auto-loading
23.2.3.2 The `.debug_gdb_scripts' section
.........................................
For systems using file formats like ELF and COFF, when GDB loads a new
object file it will look for a special section named
`.debug_gdb_scripts'. If this section exists, its contents is a list
of names of scripts to load.
GDB will look for each specified script file first in the current
directory and then along the source search path (*note Specifying
Source Directories: Source Path.), except that `$cdir' is not searched,
since the compilation directory is not relevant to scripts.
Entries can be placed in section `.debug_gdb_scripts' with, for
example, this GCC macro:
/* Note: The "MS" section flags are to remove duplicates. */
#define DEFINE_GDB_SCRIPT(script_name) \
asm("\
.pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\
.byte 1\n\
.asciz \"" script_name "\"\n\
.popsection \n\
");
Then one can reference the macro in a header or source file like this:
DEFINE_GDB_SCRIPT ("my-app-scripts.py")
The script name may include directories if desired.
Note that loading of this script file also requires accordingly
configured `auto-load safe-path' (*note Auto-loading safe path::).
If the macro is put in a header, any application or library using
this header will get a reference to the specified script.

File: gdb.info, Node: Which flavor to choose?, Prev: dotdebug_gdb_scripts section, Up: Python Auto-loading
23.2.3.3 Which flavor to choose?
................................
Given the multiple ways of auto-loading Python scripts, it might not
always be clear which one to choose. This section provides some
guidance.
Benefits of the `-gdb.py' way:
* Can be used with file formats that don't support multiple sections.
* Ease of finding scripts for public libraries.
Scripts specified in the `.debug_gdb_scripts' section are searched
for in the source search path. For publicly installed libraries,
e.g., `libstdc++', there typically isn't a source directory in
which to find the script.
* Doesn't require source code additions.
Benefits of the `.debug_gdb_scripts' way:
* Works with static linking.
Scripts for libraries done the `-gdb.py' way require an objfile to
trigger their loading. When an application is statically linked
the only objfile available is the executable, and it is cumbersome
to attach all the scripts from all the input libraries to the
executable's `-gdb.py' script.
* Works with classes that are entirely inlined.
Some classes can be entirely inlined, and thus there may not be an
associated shared library to attach a `-gdb.py' script to.
* Scripts needn't be copied out of the source tree.
In some circumstances, apps can be built out of large collections
of internal libraries, and the build infrastructure necessary to
install the `-gdb.py' scripts in a place where GDB can find them is
cumbersome. It may be easier to specify the scripts in the
`.debug_gdb_scripts' section as relative paths, and add a path to
the top of the source tree to the source search path.

File: gdb.info, Node: Python modules, Prev: Python Auto-loading, Up: Python
23.2.4 Python modules
---------------------
GDB comes with several modules to assist writing Python code.
* Menu:
* gdb.printing:: Building and registering pretty-printers.
* gdb.types:: Utilities for working with types.
* gdb.prompt:: Utilities for prompt value substitution.

File: gdb.info, Node: gdb.printing, Next: gdb.types, Up: Python modules
23.2.4.1 gdb.printing
.....................
This module provides a collection of utilities for working with
pretty-printers.
`PrettyPrinter (NAME, SUBPRINTERS=None)'
This class specifies the API that makes `info pretty-printer',
`enable pretty-printer' and `disable pretty-printer' work.
Pretty-printers should generally inherit from this class.
`SubPrettyPrinter (NAME)'
For printers that handle multiple types, this class specifies the
corresponding API for the subprinters.
`RegexpCollectionPrettyPrinter (NAME)'
Utility class for handling multiple printers, all recognized via
regular expressions. *Note Writing a Pretty-Printer::, for an
example.
`FlagEnumerationPrinter (NAME)'
A pretty-printer which handles printing of `enum' values. Unlike
GDB's built-in `enum' printing, this printer attempts to work
properly when there is some overlap between the enumeration
constants. NAME is the name of the printer and also the name of
the `enum' type to look up.
`register_pretty_printer (OBJ, PRINTER, REPLACE=False)'
Register PRINTER with the pretty-printer list of OBJ. If REPLACE
is `True' then any existing copy of the printer is replaced.
Otherwise a `RuntimeError' exception is raised if a printer with
the same name already exists.

File: gdb.info, Node: gdb.types, Next: gdb.prompt, Prev: gdb.printing, Up: Python modules
23.2.4.2 gdb.types
..................
This module provides a collection of utilities for working with
`gdb.Types' objects.
`get_basic_type (TYPE)'
Return TYPE with const and volatile qualifiers stripped, and with
typedefs and C++ references converted to the underlying type.
C++ example:
typedef const int const_int;
const_int foo (3);
const_int& foo_ref (foo);
int main () { return 0; }
Then in gdb:
(gdb) start
(gdb) python import gdb.types
(gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
(gdb) python print gdb.types.get_basic_type(foo_ref.type)
int
`has_field (TYPE, FIELD)'
Return `True' if TYPE, assumed to be a type with fields (e.g., a
structure or union), has field FIELD.
`make_enum_dict (ENUM_TYPE)'
Return a Python `dictionary' type produced from ENUM_TYPE.
`deep_items (TYPE)'
Returns a Python iterator similar to the standard
`gdb.Type.iteritems' method, except that the iterator returned by
`deep_items' will recursively traverse anonymous struct or union
fields. For example:
struct A
{
int a;
union {
int b0;
int b1;
};
};
Then in GDB:
(gdb) python import gdb.types
(gdb) python struct_a = gdb.lookup_type("struct A")
(gdb) python print struct_a.keys ()
{['a', '']}
(gdb) python print [k for k,v in gdb.types.deep_items(struct_a)]
{['a', 'b0', 'b1']}

File: gdb.info, Node: gdb.prompt, Prev: gdb.types, Up: Python modules
23.2.4.3 gdb.prompt
...................
This module provides a method for prompt value-substitution.
`substitute_prompt (STRING)'
Return STRING with escape sequences substituted by values. Some
escape sequences take arguments. You can specify arguments inside
"{}" immediately following the escape sequence.
The escape sequences you can pass to this function are:
`\\'
Substitute a backslash.
`\e'
Substitute an ESC character.
`\f'
Substitute the selected frame; an argument names a frame
parameter.
`\n'
Substitute a newline.
`\p'
Substitute a parameter's value; the argument names the
parameter.
`\r'
Substitute a carriage return.
`\t'
Substitute the selected thread; an argument names a thread
parameter.
`\v'
Substitute the version of GDB.
`\w'
Substitute the current working directory.
`\['
Begin a sequence of non-printing characters. These sequences
are typically used with the ESC character, and are not
counted in the string length. Example:
"\[\e[0;34m\](gdb)\[\e[0m\]" will return a blue-colored
"(gdb)" prompt where the length is five.
`\]'
End a sequence of non-printing characters.
For example:
substitute_prompt (``frame: \f,
print arguments: \p{print frame-arguments}'')
will return the string:
"frame: main, print arguments: scalars"

File: gdb.info, Node: Aliases, Prev: Python, Up: Extending GDB
23.3 Creating new spellings of existing commands
================================================
It is often useful to define alternate spellings of existing commands.
For example, if a new GDB command defined in Python has a long name to
type, it is handy to have an abbreviated version of it that involves
less typing.
GDB itself uses aliases. For example `s' is an alias of the `step'
command even though it is otherwise an ambiguous abbreviation of other
commands like `set' and `show'.
Aliases are also used to provide shortened or more common versions
of multi-word commands. For example, GDB provides the `tty' alias of
the `set inferior-tty' command.
You can define a new alias with the `alias' command.
`alias [-a] [--] ALIAS = COMMAND'
ALIAS specifies the name of the new alias. Each word of ALIAS must
consist of letters, numbers, dashes and underscores.
COMMAND specifies the name of an existing command that is being
aliased.
The `-a' option specifies that the new alias is an abbreviation of
the command. Abbreviations are not shown in command lists displayed by
the `help' command.
The `--' option specifies the end of options, and is useful when
ALIAS begins with a dash.
Here is a simple example showing how to make an abbreviation of a
command so that there is less to type. Suppose you were tired of
typing `disas', the current shortest unambiguous abbreviation of the
`disassemble' command and you wanted an even shorter version named `di'.
The following will accomplish this.
(gdb) alias -a di = disas
Note that aliases are different from user-defined commands. With a
user-defined command, you also need to write documentation for it with
the `document' command. An alias automatically picks up the
documentation of the existing command.
Here is an example where we make `elms' an abbreviation of
`elements' in the `set print elements' command. This is to show that
you can make an abbreviation of any part of a command.
(gdb) alias -a set print elms = set print elements
(gdb) alias -a show print elms = show print elements
(gdb) set p elms 20
(gdb) show p elms
Limit on string chars or array elements to print is 200.
Note that if you are defining an alias of a `set' command, and you
want to have an alias for the corresponding `show' command, then you
need to define the latter separately.
Unambiguously abbreviated commands are allowed in COMMAND and ALIAS,
just as they are normally.
(gdb) alias -a set pr elms = set p ele
Finally, here is an example showing the creation of a one word alias
for a more complex command. This creates alias `spe' of the command
`set print elements'.
(gdb) alias spe = set print elements
(gdb) spe 20

File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top
24 Command Interpreters
***********************
GDB supports multiple command interpreters, and some command
infrastructure to allow users or user interface writers to switch
between interpreters or run commands in other interpreters.
GDB currently supports two command interpreters, the console
interpreter (sometimes called the command-line interpreter or CLI) and
the machine interface interpreter (or GDB/MI). This manual describes
both of these interfaces in great detail.
By default, GDB will start with the console interpreter. However,
the user may choose to start GDB with another interpreter by specifying
the `-i' or `--interpreter' startup options. Defined interpreters
include:
`console'
The traditional console or command-line interpreter. This is the
most often used interpreter with GDB. With no interpreter
specified at runtime, GDB will use this interpreter.
`mi'
The newest GDB/MI interface (currently `mi2'). Used primarily by
programs wishing to use GDB as a backend for a debugger GUI or an
IDE. For more information, see *Note The GDB/MI Interface: GDB/MI.
`mi2'
The current GDB/MI interface.
`mi1'
The GDB/MI interface included in GDB 5.1, 5.2, and 5.3.
The interpreter being used by GDB may not be dynamically switched at
runtime. Although possible, this could lead to a very precarious
situation. Consider an IDE using GDB/MI. If a user enters the command
"interpreter-set console" in a console view, GDB would switch to using
the console interpreter, rendering the IDE inoperable!
Although you may only choose a single interpreter at startup, you
may execute commands in any interpreter from the current interpreter
using the appropriate command. If you are running the console
interpreter, simply use the `interpreter-exec' command:
interpreter-exec mi "-data-list-register-names"
GDB/MI has a similar command, although it is only available in
versions of GDB which support GDB/MI version 2 (or greater).

File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top
25 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) 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'. *Note TUI
Key Bindings: TUI Keys.

File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI
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. (*note Specifying a Debugging
Target: Targets.).
_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 (*note 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.

File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI
25.2 TUI Key Bindings
=====================
The TUI installs several key bindings in the readline keymaps (*note
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 (*note 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.

File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI
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'.

File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single Key Mode, Up: TUI
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 (*note The
GDB/MI Interface: GDB/MI.), 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.

File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI
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.

File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top
26 Using GDB under GNU Emacs
****************************
A special interface allows you to use GNU Emacs to view (and edit) the
source files for the program you are debugging with GDB.
To use this interface, use the command `M-x gdb' in Emacs. Give the
executable file you want to debug as an argument. This command starts
GDB as a subprocess of Emacs, with input and output through a newly
created Emacs buffer.
Running GDB under Emacs can be just like running GDB normally except
for two things:
* All "terminal" input and output goes through an Emacs buffer,
called the GUD buffer.
This applies both to GDB commands and their output, and to the
input and output done by the program you are debugging.
This is useful because it means that you can copy the text of
previous commands and input them again; you can even use parts of
the output in this way.
All the facilities of Emacs' Shell mode are available for
interacting with your program. In particular, you can send
signals the usual way--for example, `C-c C-c' for an interrupt,
`C-c C-z' for a stop.
* GDB displays source code through Emacs.
Each time GDB displays a stack frame, Emacs automatically finds the
source file for that frame and puts an arrow (`=>') at the left
margin of the current line. Emacs uses a separate buffer for
source display, and splits the screen to show both your GDB session
and the source.
Explicit GDB `list' or search commands still produce output as
usual, but you probably have no reason to use them from Emacs.
We call this "text command mode". Emacs 22.1, and later, also uses
a graphical mode, enabled by default, which provides further buffers
that can control the execution and describe the state of your program.
*Note GDB Graphical Interface: (Emacs)GDB Graphical Interface.
If you specify an absolute file name when prompted for the `M-x gdb'
argument, then Emacs sets your current working directory to where your
program resides. If you only specify the file name, then Emacs sets
your current working directory to the directory associated with the
previous buffer. In this case, GDB may find your program by searching
your environment's `PATH' variable, but on some operating systems it
might not find the source. So, although the GDB input and output
session proceeds normally, the auxiliary buffer does not display the
current source and line of execution.
The initial working directory of GDB is printed on the top line of
the GUD buffer and this serves as a default for the commands that
specify files for GDB to operate on. *Note Commands to Specify Files:
Files.
By default, `M-x gdb' calls the program called `gdb'. If you need
to call GDB by a different name (for example, if you keep several
configurations around, with different names) you can customize the
Emacs variable `gud-gdb-command-name' to run the one you want.
In the GUD buffer, you can use these special Emacs commands in
addition to the standard Shell mode commands:
`C-h m'
Describe the features of Emacs' GUD Mode.
`C-c C-s'
Execute to another source line, like the GDB `step' command; also
update the display window to show the current file and location.
`C-c C-n'
Execute to next source line in this function, skipping all function
calls, like the GDB `next' command. Then update the display window
to show the current file and location.
`C-c C-i'
Execute one instruction, like the GDB `stepi' command; update
display window accordingly.
`C-c C-f'
Execute until exit from the selected stack frame, like the GDB
`finish' command.
`C-c C-r'
Continue execution of your program, like the GDB `continue'
command.
`C-c <'
Go up the number of frames indicated by the numeric argument
(*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up'
command.
`C-c >'
Go down the number of frames indicated by the numeric argument,
like the GDB `down' command.
In any source file, the Emacs command `C-x <SPC>' (`gud-break')
tells GDB to set a breakpoint on the source line point is on.
In text command mode, if you type `M-x speedbar', Emacs displays a
separate frame which shows a backtrace when the GUD buffer is current.
Move point to any frame in the stack and type <RET> to make it become
the current frame and display the associated source in the source
buffer. Alternatively, click `Mouse-2' to make the selected frame
become the current one. In graphical mode, the speedbar displays watch
expressions.
If you accidentally delete the source-display buffer, an easy way to
get it back is to type the command `f' in the GDB buffer, to request a
frame display; when you run under Emacs, this recreates the source
buffer if necessary to show you the context of the current frame.
The source files displayed in Emacs are in ordinary Emacs buffers
which are visiting the source files in the usual way. You can edit the
files with these buffers if you wish; but keep in mind that GDB
communicates with Emacs in terms of line numbers. If you add or delete
lines from the text, the line numbers that GDB knows cease to
correspond properly with the code.
A more detailed description of Emacs' interaction with GDB is given
in the Emacs manual (*note Debuggers: (Emacs)Debuggers.).

File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top
27 The GDB/MI Interface
***********************
Function and Purpose
====================
GDB/MI is a line based machine oriented text interface to GDB and is
activated by specifying using the `--interpreter' command line option
(*note Mode Options::). It is specifically intended to support the
development of systems which use the debugger as just one small
component of a larger system.
This chapter is a specification of the GDB/MI interface. It is
written in the form of a reference manual.
Note that GDB/MI is still under construction, so some of the
features described below are incomplete and subject to change (*note
GDB/MI Development and Front Ends: GDB/MI Development and Front Ends.).
Notation and Terminology
========================
This chapter uses the following notation:
* `|' separates two alternatives.
* `[ SOMETHING ]' indicates that SOMETHING is optional: it may or
may not be given.
* `( GROUP )*' means that GROUP inside the parentheses may repeat
zero or more times.
* `( GROUP )+' means that GROUP inside the parentheses may repeat
one or more times.
* `"STRING"' means a literal STRING.
* Menu:
* GDB/MI General Design::
* GDB/MI Command Syntax::
* GDB/MI Compatibility with CLI::
* GDB/MI Development and Front Ends::
* GDB/MI Output Records::
* GDB/MI Simple Examples::
* GDB/MI Command Description Format::
* GDB/MI Breakpoint Commands::
* GDB/MI Program Context::
* GDB/MI Thread Commands::
* GDB/MI Ada Tasking Commands::
* GDB/MI Program Execution::
* GDB/MI Stack Manipulation::
* GDB/MI Variable Objects::
* GDB/MI Data Manipulation::
* GDB/MI Tracepoint Commands::
* GDB/MI Symbol Query::
* GDB/MI File Commands::
* GDB/MI Target Manipulation::
* GDB/MI File Transfer Commands::
* GDB/MI Miscellaneous Commands::

File: gdb.info, Node: GDB/MI General Design, Next: GDB/MI Command Syntax, Up: GDB/MI
27.1 GDB/MI General Design
==========================
Interaction of a GDB/MI frontend with GDB involves three
parts--commands sent to GDB, responses to those commands and
notifications. Each command results in exactly one response,
indicating either successful completion of the command, or an error.
For the commands that do not resume the target, the response contains
the requested information. For the commands that resume the target, the
response only indicates whether the target was successfully resumed.
Notifications is the mechanism for reporting changes in the state of the
target, or in GDB state, that cannot conveniently be associated with a
command and reported as part of that command response.
The important examples of notifications are:
* Exec notifications. These are used to report changes in target
state--when a target is resumed, or stopped. It would not be
feasible to include this information in response of resuming
commands, because one resume commands can result in multiple
events in different threads. Also, quite some time may pass
before any event happens in the target, while a frontend needs to
know whether the resuming command itself was successfully executed.
* Console output, and status notifications. Console output
notifications are used to report output of CLI commands, as well as
diagnostics for other commands. Status notifications are used to
report the progress of a long-running operation. Naturally,
including this information in command response would mean no
output is produced until the command is finished, which is
undesirable.
* General notifications. Commands may have various side effects on
the GDB or target state beyond their official purpose. For
example, a command may change the selected thread. Although such
changes can be included in command response, using notification
allows for more orthogonal frontend design.
There's no guarantee that whenever an MI command reports an error,
GDB or the target are in any specific state, and especially, the state
is not reverted to the state before the MI command was processed.
Therefore, whenever an MI command results in an error, we recommend
that the frontend refreshes all the information shown in the user
interface.
* Menu:
* Context management::
* Asynchronous and non-stop modes::
* Thread groups::

File: gdb.info, Node: Context management, Next: Asynchronous and non-stop modes, Up: GDB/MI General Design
27.1.1 Context management
-------------------------
In most cases when GDB accesses the target, this access is done in
context of a specific thread and frame (*note Frames::). Often, even
when accessing global data, the target requires that a thread be
specified. The CLI interface maintains the selected thread and frame,
and supplies them to target on each command. This is convenient,
because a command line user would not want to specify that information
explicitly on each command, and because user interacts with GDB via a
single terminal, so no confusion is possible as to what thread and
frame are the current ones.
In the case of MI, the concept of selected thread and frame is less
useful. First, a frontend can easily remember this information itself.
Second, a graphical frontend can have more than one window, each one
used for debugging a different thread, and the frontend might want to
access additional threads for internal purposes. This increases the
risk that by relying on implicitly selected thread, the frontend may be
operating on a wrong one. Therefore, each MI command should explicitly
specify which thread and frame to operate on. To make it possible,
each MI command accepts the `--thread' and `--frame' options, the value
to each is GDB identifier for thread and frame to operate on.
Usually, each top-level window in a frontend allows the user to
select a thread and a frame, and remembers the user selection for
further operations. However, in some cases GDB may suggest that the
current thread be changed. For example, when stopping on a breakpoint
it is reasonable to switch to the thread where breakpoint is hit. For
another example, if the user issues the CLI `thread' command via the
frontend, it is desirable to change the frontend's selected thread to
the one specified by user. GDB communicates the suggestion to change
current thread using the `=thread-selected' notification. No such
notification is available for the selected frame at the moment.
Note that historically, MI shares the selected thread with CLI, so
frontends used the `-thread-select' to execute commands in the right
context. However, getting this to work right is cumbersome. The
simplest way is for frontend to emit `-thread-select' command before
every command. This doubles the number of commands that need to be
sent. The alternative approach is to suppress `-thread-select' if the
selected thread in GDB is supposed to be identical to the thread the
frontend wants to operate on. However, getting this optimization right
can be tricky. In particular, if the frontend sends several commands
to GDB, and one of the commands changes the selected thread, then the
behaviour of subsequent commands will change. So, a frontend should
either wait for response from such problematic commands, or explicitly
add `-thread-select' for all subsequent commands. No frontend is known
to do this exactly right, so it is suggested to just always pass the
`--thread' and `--frame' options.

File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, Prev: Context management, Up: GDB/MI General Design
27.1.2 Asynchronous command execution and non-stop mode
-------------------------------------------------------
On some targets, GDB is capable of processing MI commands even while
the target is running. This is called "asynchronous command execution"
(*note Background Execution::). The frontend may specify a preferrence
for asynchronous execution using the `-gdb-set target-async 1' command,
which should be emitted before either running the executable or
attaching to the target. After the frontend has started the executable
or attached to the target, it can find if asynchronous execution is
enabled using the `-list-target-features' command.
Even if GDB can accept a command while target is running, many
commands that access the target do not work when the target is running.
Therefore, asynchronous command execution is most useful when combined
with non-stop mode (*note Non-Stop Mode::). Then, it is possible to
examine the state of one thread, while other threads are running.
When a given thread is running, MI commands that try to access the
target in the context of that thread may not work, or may work only on
some targets. In particular, commands that try to operate on thread's
stack will not work, on any target. Commands that read memory, or
modify breakpoints, may work or not work, depending on the target. Note
that even commands that operate on global state, such as `print',
`set', and breakpoint commands, still access the target in the context
of a specific thread, so frontend should try to find a stopped thread
and perform the operation on that thread (using the `--thread' option).
Which commands will work in the context of a running thread is
highly target dependent. However, the two commands `-exec-interrupt',
to stop a thread, and `-thread-info', to find the state of a thread,
will always work.

File: gdb.info, Node: Thread groups, Prev: Asynchronous and non-stop modes, Up: GDB/MI General Design
27.1.3 Thread groups
--------------------
GDB may be used to debug several processes at the same time. On some
platfroms, GDB may support debugging of several hardware systems, each
one having several cores with several different processes running on
each core. This section describes the MI mechanism to support such
debugging scenarios.
The key observation is that regardless of the structure of the
target, MI can have a global list of threads, because most commands that
accept the `--thread' option do not need to know what process that
thread belongs to. Therefore, it is not necessary to introduce neither
additional `--process' option, nor an notion of the current process in
the MI interface. The only strictly new feature that is required is
the ability to find how the threads are grouped into processes.
To allow the user to discover such grouping, and to support arbitrary
hierarchy of machines/cores/processes, MI introduces the concept of a
"thread group". Thread group is a collection of threads and other
thread groups. A thread group always has a string identifier, a type,
and may have additional attributes specific to the type. A new
command, `-list-thread-groups', returns the list of top-level thread
groups, which correspond to processes that GDB is debugging at the
moment. By passing an identifier of a thread group to the
`-list-thread-groups' command, it is possible to obtain the members of
specific thread group.
To allow the user to easily discover processes, and other objects, he
wishes to debug, a concept of "available thread group" is introduced.
Available thread group is an thread group that GDB is not debugging,
but that can be attached to, using the `-target-attach' command. The
list of available top-level thread groups can be obtained using
`-list-thread-groups --available'. In general, the content of a thread
group may be only retrieved only after attaching to that thread group.
Thread groups are related to inferiors (*note Inferiors and
Programs::). Each inferior corresponds to a thread group of a special
type `process', and some additional operations are permitted on such
thread groups.

File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Prev: GDB/MI General Design, Up: GDB/MI
27.2 GDB/MI Command Syntax
==========================
* Menu:
* GDB/MI Input Syntax::
* GDB/MI Output Syntax::

File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax
27.2.1 GDB/MI Input Syntax
--------------------------
`COMMAND ==>'
`CLI-COMMAND | MI-COMMAND'
`CLI-COMMAND ==>'
`[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB
CLI command.
`MI-COMMAND ==>'
`[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " "
PARAMETER )* NL'
`TOKEN ==>'
"any sequence of digits"
`OPTION ==>'
`"-" PARAMETER [ " " PARAMETER ]'
`PARAMETER ==>'
`NON-BLANK-SEQUENCE | C-STRING'
`OPERATION ==>'
_any of the operations described in this chapter_
`NON-BLANK-SEQUENCE ==>'
_anything, provided it doesn't contain special characters such as
"-", NL, """ and of course " "_
`C-STRING ==>'
`""" SEVEN-BIT-ISO-C-STRING-CONTENT """'
`NL ==>'
`CR | CR-LF'
Notes:
* The CLI commands are still handled by the MI interpreter; their
output is described below.
* The `TOKEN', when present, is passed back when the command
finishes.
* Some MI commands accept optional arguments as part of the parameter
list. Each option is identified by a leading `-' (dash) and may be
followed by an optional argument parameter. Options occur first
in the parameter list and can be delimited from normal parameters
using `--' (this is useful when some parameters begin with a dash).
Pragmatics:
* We want easy access to the existing CLI syntax (for debugging).
* We want it to be easy to spot a MI operation.

File: gdb.info, Node: GDB/MI Output Syntax, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax
27.2.2 GDB/MI Output Syntax
---------------------------
The output from GDB/MI consists of zero or more out-of-band records
followed, optionally, by a single result record. This result record is
for the most recent command. The sequence of output records is
terminated by `(gdb)'.
If an input command was prefixed with a `TOKEN' then the
corresponding output for that command will also be prefixed by that same
TOKEN.
`OUTPUT ==>'
`( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL'
`RESULT-RECORD ==>'
` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL'
`OUT-OF-BAND-RECORD ==>'
`ASYNC-RECORD | STREAM-RECORD'
`ASYNC-RECORD ==>'
`EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT'
`EXEC-ASYNC-OUTPUT ==>'
`[ TOKEN ] "*" ASYNC-OUTPUT'
`STATUS-ASYNC-OUTPUT ==>'
`[ TOKEN ] "+" ASYNC-OUTPUT'
`NOTIFY-ASYNC-OUTPUT ==>'
`[ TOKEN ] "=" ASYNC-OUTPUT'
`ASYNC-OUTPUT ==>'
`ASYNC-CLASS ( "," RESULT )* NL'
`RESULT-CLASS ==>'
`"done" | "running" | "connected" | "error" | "exit"'
`ASYNC-CLASS ==>'
`"stopped" | OTHERS' (where OTHERS will be added depending on the
needs--this is still in development).
`RESULT ==>'
` VARIABLE "=" VALUE'
`VARIABLE ==>'
` STRING '
`VALUE ==>'
` CONST | TUPLE | LIST '
`CONST ==>'
`C-STRING'
`TUPLE ==>'
` "{}" | "{" RESULT ( "," RESULT )* "}" '
`LIST ==>'
` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )*
"]" '
`STREAM-RECORD ==>'
`CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT'
`CONSOLE-STREAM-OUTPUT ==>'
`"~" C-STRING'
`TARGET-STREAM-OUTPUT ==>'
`"@" C-STRING'
`LOG-STREAM-OUTPUT ==>'
`"&" C-STRING'
`NL ==>'
`CR | CR-LF'
`TOKEN ==>'
_any sequence of digits_.
Notes:
* All output sequences end in a single line containing a period.
* The `TOKEN' is from the corresponding request. Note that for all
async output, while the token is allowed by the grammar and may be
output by future versions of GDB for select async output messages,
it is generally omitted. Frontends should treat all async output
as reporting general changes in the state of the target and there
should be no need to associate async output to any prior command.
* STATUS-ASYNC-OUTPUT contains on-going status information about the
progress of a slow operation. It can be discarded. All status
output is prefixed by `+'.
* EXEC-ASYNC-OUTPUT contains asynchronous state change on the target
(stopped, started, disappeared). All async output is prefixed by
`*'.
* NOTIFY-ASYNC-OUTPUT contains supplementary information that the
client should handle (e.g., a new breakpoint information). All
notify output is prefixed by `='.
* CONSOLE-STREAM-OUTPUT is output that should be displayed as is in
the console. It is the textual response to a CLI command. All
the console output is prefixed by `~'.
* TARGET-STREAM-OUTPUT is the output produced by the target program.
All the target output is prefixed by `@'.
* LOG-STREAM-OUTPUT is output text coming from GDB's internals, for
instance messages that should be displayed as part of an error
log. All the log output is prefixed by `&'.
* New GDB/MI commands should only output LISTS containing VALUES.
*Note GDB/MI Stream Records: GDB/MI Stream Records, for more details
about the various output records.

File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI
27.3 GDB/MI Compatibility with CLI
==================================
For the developers convenience CLI commands can be entered directly,
but there may be some unexpected behaviour. For example, commands that
query the user will behave as if the user replied yes, breakpoint
command lists are not executed and some CLI commands, such as `if',
`when' and `define', prompt for further input with `>', which is not
valid MI output.
This feature may be removed at some stage in the future and it is
recommended that front ends use the `-interpreter-exec' command (*note
-interpreter-exec::).

File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI
27.4 GDB/MI Development and Front Ends
======================================
The application which takes the MI output and presents the state of the
program being debugged to the user is called a "front end".
Although GDB/MI is still incomplete, it is currently being used by a
variety of front ends to GDB. This makes it difficult to introduce new
functionality without breaking existing usage. This section tries to
minimize the problems by describing how the protocol might change.
Some changes in MI need not break a carefully designed front end, and
for these the MI version will remain unchanged. The following is a
list of changes that may occur within one level, so front ends should
parse MI output in a way that can handle them:
* New MI commands may be added.
* New fields may be added to the output of any MI command.
* The range of values for fields with specified values, e.g.,
`in_scope' (*note -var-update::) may be extended.
If the changes are likely to break front ends, the MI version level
will be increased by one. This will allow the front end to parse the
output according to the MI version. Apart from mi0, new versions of
GDB will not support old versions of MI and it will be the
responsibility of the front end to work with the new one.
The best way to avoid unexpected changes in MI that might break your
front end is to make your project known to GDB developers and follow
development on <gdb@sourceware.org> and <gdb-patches@sourceware.org>.

File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI
27.5 GDB/MI Output Records
==========================
* Menu:
* GDB/MI Result Records::
* GDB/MI Stream Records::
* GDB/MI Async Records::
* GDB/MI Frame Information::
* GDB/MI Thread Information::
* GDB/MI Ada Exception Information::

File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records
27.5.1 GDB/MI Result Records
----------------------------
In addition to a number of out-of-band notifications, the response to a
GDB/MI command includes one of the following result indications:
`"^done" [ "," RESULTS ]'
The synchronous operation was successful, `RESULTS' are the return
values.
`"^running"'
This result record is equivalent to `^done'. Historically, it was
output instead of `^done' if the command has resumed the target.
This behaviour is maintained for backward compatibility, but all
frontends should treat `^done' and `^running' identically and rely
on the `*running' output record to determine which threads are
resumed.
`"^connected"'
GDB has connected to a remote target.
`"^error" "," C-STRING'
The operation failed. The `C-STRING' contains the corresponding
error message.
`"^exit"'
GDB has terminated.

File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Async Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records
27.5.2 GDB/MI Stream Records
----------------------------
GDB internally maintains a number of output streams: the console, the
target, and the log. The output intended for each of these streams is
funneled through the GDB/MI interface using "stream records".
Each stream record begins with a unique "prefix character" which
identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output
Syntax.). In addition to the prefix, each stream record contains a
`STRING-OUTPUT'. This is either raw text (with an implicit new line)
or a quoted C string (which does not contain an implicit newline).
`"~" STRING-OUTPUT'
The console output stream contains text that should be displayed
in the CLI console window. It contains the textual responses to
CLI commands.
`"@" STRING-OUTPUT'
The target output stream contains any textual output from the
running target. This is only present when GDB's event loop is
truly asynchronous, which is currently only the case for remote
targets.
`"&" STRING-OUTPUT'
The log stream contains debugging messages being produced by GDB's
internals.

File: gdb.info, Node: GDB/MI Async Records, Next: GDB/MI Frame Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records
27.5.3 GDB/MI Async Records
---------------------------
"Async" records are used to notify the GDB/MI client of additional
changes that have occurred. Those changes can either be a consequence
of GDB/MI commands (e.g., a breakpoint modified) or a result of target
activity (e.g., target stopped).
The following is the list of possible async records:
`*running,thread-id="THREAD"'
The target is now running. The THREAD field tells which specific
thread is now running, and can be `all' if all threads are
running. The frontend should assume that no interaction with a
running thread is possible after this notification is produced.
The frontend should not assume that this notification is output
only once for any command. GDB may emit this notification several
times, either for different threads, because it cannot resume all
threads together, or even for a single thread, if the thread must
be stepped though some code before letting it run freely.
`*stopped,reason="REASON",thread-id="ID",stopped-threads="STOPPED",core="CORE"'
The target has stopped. The REASON field can have one of the
following values:
`breakpoint-hit'
A breakpoint was reached.
`watchpoint-trigger'
A watchpoint was triggered.
`read-watchpoint-trigger'
A read watchpoint was triggered.
`access-watchpoint-trigger'
An access watchpoint was triggered.
`function-finished'
An -exec-finish or similar CLI command was accomplished.
`location-reached'
An -exec-until or similar CLI command was accomplished.
`watchpoint-scope'
A watchpoint has gone out of scope.
`end-stepping-range'
An -exec-next, -exec-next-instruction, -exec-step,
-exec-step-instruction or similar CLI command was
accomplished.
`exited-signalled'
The inferior exited because of a signal.
`exited'
The inferior exited.
`exited-normally'
The inferior exited normally.
`signal-received'
A signal was received by the inferior.
`solib-event'
The inferior has stopped due to a library being loaded or
unloaded. This can happen when `stop-on-solib-events' (*note
Files::) is set or when a `catch load' or `catch unload'
catchpoint is in use (*note Set Catchpoints::).
`fork'
The inferior has forked. This is reported when `catch fork'
(*note Set Catchpoints::) has been used.
`vfork'
The inferior has vforked. This is reported in when `catch
vfork' (*note Set Catchpoints::) has been used.
`syscall-entry'
The inferior entered a system call. This is reported when
`catch syscall' (*note Set Catchpoints::) has been used.
`syscall-entry'
The inferior returned from a system call. This is reported
when `catch syscall' (*note Set Catchpoints::) has been used.
`exec'
The inferior called `exec'. This is reported when `catch
exec' (*note Set Catchpoints::) has been used.
The ID field identifies the thread that directly caused the stop -
for example by hitting a breakpoint. Depending on whether all-stop
mode is in effect (*note All-Stop Mode::), GDB may either stop all
threads, or only the thread that directly triggered the stop. If
all threads are stopped, the STOPPED field will have the value of
`"all"'. Otherwise, the value of the STOPPED field will be a list
of thread identifiers. Presently, this list will always include a
single thread, but frontend should be prepared to see several
threads in the list. The CORE field reports the processor core on
which the stop event has happened. This field may be absent if
such information is not available.
`=thread-group-added,id="ID"'
`=thread-group-removed,id="ID"'
A thread group was either added or removed. The ID field contains
the GDB identifier of the thread group. When a thread group is
added, it generally might not be associated with a running
process. When a thread group is removed, its id becomes invalid
and cannot be used in any way.
`=thread-group-started,id="ID",pid="PID"'
A thread group became associated with a running program, either
because the program was just started or the thread group was
attached to a program. The ID field contains the GDB identifier
of the thread group. The PID field contains process identifier,
specific to the operating system.
`=thread-group-exited,id="ID"[,exit-code="CODE"]'
A thread group is no longer associated with a running program,
either because the program has exited, or because it was detached
from. The ID field contains the GDB identifier of the thread
group. CODE is the exit code of the inferior; it exists only when
the inferior exited with some code.
`=thread-created,id="ID",group-id="GID"'
`=thread-exited,id="ID",group-id="GID"'
A thread either was created, or has exited. The ID field contains
the GDB identifier of the thread. The GID field identifies the
thread group this thread belongs to.
`=thread-selected,id="ID"'
Informs that the selected thread was changed as result of the last
command. This notification is not emitted as result of
`-thread-select' command but is emitted whenever an MI command
that is not documented to change the selected thread actually
changes it. In particular, invoking, directly or indirectly (via
user-defined command), the CLI `thread' command, will generate
this notification.
We suggest that in response to this notification, front ends
highlight the selected thread and cause subsequent commands to
apply to that thread.
`=library-loaded,...'
Reports that a new library file was loaded by the program. This
notification has 4 fields--ID, TARGET-NAME, HOST-NAME, and
SYMBOLS-LOADED. The ID field is an opaque identifier of the
library. For remote debugging case, TARGET-NAME and HOST-NAME
fields give the name of the library file on the target, and on the
host respectively. For native debugging, both those fields have
the same value. The SYMBOLS-LOADED field is emitted only for
backward compatibility and should not be relied on to convey any
useful information. The THREAD-GROUP field, if present, specifies
the id of the thread group in whose context the library was
loaded. If the field is absent, it means the library was loaded
in the context of all present thread groups.
`=library-unloaded,...'
Reports that a library was unloaded by the program. This
notification has 3 fields--ID, TARGET-NAME and HOST-NAME with the
same meaning as for the `=library-loaded' notification. The
THREAD-GROUP field, if present, specifies the id of the thread
group in whose context the library was unloaded. If the field is
absent, it means the library was unloaded in the context of all
present thread groups.
`=breakpoint-created,bkpt={...}'
`=breakpoint-modified,bkpt={...}'
`=breakpoint-deleted,bkpt={...}'
Reports that a breakpoint was created, modified, or deleted,
respectively. Only user-visible breakpoints are reported to the MI
user.
The BKPT argument is of the same form as returned by the various
breakpoint commands; *Note GDB/MI Breakpoint Commands::.
Note that if a breakpoint is emitted in the result record of a
command, then it will not also be emitted in an async record.

File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records
27.5.4 GDB/MI Frame Information
-------------------------------
Response from many MI commands includes an information about stack
frame. This information is a tuple that may have the following fields:
`level'
The level of the stack frame. The innermost frame has the level of
zero. This field is always present.
`func'
The name of the function corresponding to the frame. This field
may be absent if GDB is unable to determine the function name.
`addr'
The code address for the frame. This field is always present.
`file'
The name of the source files that correspond to the frame's code
address. This field may be absent.
`line'
The source line corresponding to the frames' code address. This
field may be absent.
`from'
The name of the binary file (either executable or shared library)
the corresponds to the frame's code address. This field may be
absent.

File: gdb.info, Node: GDB/MI Thread Information, Next: GDB/MI Ada Exception Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records
27.5.5 GDB/MI Thread Information
--------------------------------
Whenever GDB has to report an information about a thread, it uses a
tuple with the following fields:
`id'
The numeric id assigned to the thread by GDB. This field is
always present.
`target-id'
Target-specific string identifying the thread. This field is
always present.
`details'
Additional information about the thread provided by the target.
It is supposed to be human-readable and not interpreted by the
frontend. This field is optional.
`state'
Either `stopped' or `running', depending on whether the thread is
presently running. This field is always present.
`core'
The value of this field is an integer number of the processor core
the thread was last seen on. This field is optional.

File: gdb.info, Node: GDB/MI Ada Exception Information, Prev: GDB/MI Thread Information, Up: GDB/MI Output Records
27.5.6 GDB/MI Ada Exception Information
---------------------------------------
Whenever a `*stopped' record is emitted because the program stopped
after hitting an exception catchpoint (*note Set Catchpoints::), GDB
provides the name of the exception that was raised via the
`exception-name' field.

File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI
27.6 Simple Examples of GDB/MI Interaction
==========================================
This subsection presents several simple examples of interaction using
the GDB/MI interface. In these examples, `->' means that the following
line is passed to GDB/MI as input, while `<-' means the output received
from GDB/MI.
Note the line breaks shown in the examples are here only for
readability, they don't appear in the real output.
Setting a Breakpoint
--------------------
Setting a breakpoint generates synchronous output which contains
detailed information of the breakpoint.
-> -break-insert main
<- ^done,bkpt={number="1",type="breakpoint",disp="keep",
enabled="y",addr="0x08048564",func="main",file="myprog.c",
fullname="/home/nickrob/myprog.c",line="68",times="0"}
<- (gdb)
Program Execution
-----------------
Program execution generates asynchronous records and MI gives the
reason that execution stopped.
-> -exec-run
<- ^running
<- (gdb)
<- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
frame={addr="0x08048564",func="main",
args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}],
file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"}
<- (gdb)
-> -exec-continue
<- ^running
<- (gdb)
<- *stopped,reason="exited-normally"
<- (gdb)
Quitting GDB
------------
Quitting GDB just prints the result class `^exit'.
-> (gdb)
<- -gdb-exit
<- ^exit
Please note that `^exit' is printed immediately, but it might take
some time for GDB to actually exit. During that time, GDB performs
necessary cleanups, including killing programs being debugged or
disconnecting from debug hardware, so the frontend should wait till GDB
exits and should only forcibly kill GDB if it fails to exit in
reasonable time.
A Bad Command
-------------
Here's what happens if you pass a non-existent command:
-> -rubbish
<- ^error,msg="Undefined MI command: rubbish"
<- (gdb)

File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI
27.7 GDB/MI Command Description Format
======================================
The remaining sections describe blocks of commands. Each block of
commands is laid out in a fashion similar to this section.
Motivation
----------
The motivation for this collection of commands.
Introduction
------------
A brief introduction to this collection of commands as a whole.
Commands
--------
For each command in the block, the following is described:
Synopsis
........
-command ARGS...
Result
......
GDB Command
...........
The corresponding GDB CLI command(s), if any.
Example
.......
Example(s) formatted for readability. Some of the described commands
have not been implemented yet and these are labeled N.A. (not
available).

File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Command Description Format, Up: GDB/MI
27.8 GDB/MI Breakpoint Commands
===============================
This section documents GDB/MI commands for manipulating breakpoints.
The `-break-after' Command
--------------------------
Synopsis
........
-break-after NUMBER COUNT
The breakpoint number NUMBER is not in effect until it has been hit
COUNT times. To see how this is reflected in the output of the
`-break-list' command, see the description of the `-break-list' command
below.
GDB Command
...........
The corresponding GDB command is `ignore'.
Example
.......
(gdb)
-break-insert main
^done,bkpt={number="1",type="breakpoint",disp="keep",
enabled="y",addr="0x000100d0",func="main",file="hello.c",
fullname="/home/foo/hello.c",line="5",times="0"}
(gdb)
-break-after 1 3
~
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",times="0",ignore="3"}]}
(gdb)
The `-break-commands' Command
-----------------------------
Synopsis
........
-break-commands NUMBER [ COMMAND1 ... COMMANDN ]
Specifies the CLI commands that should be executed when breakpoint
NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands.
If no command is specified, any previously-set commands are cleared.
*Note Break Commands::. Typical use of this functionality is tracing a
program, that is, printing of values of some variables whenever
breakpoint is hit and then continuing.
GDB Command
...........
The corresponding GDB command is `commands'.
Example
.......
(gdb)
-break-insert main
^done,bkpt={number="1",type="breakpoint",disp="keep",
enabled="y",addr="0x000100d0",func="main",file="hello.c",
fullname="/home/foo/hello.c",line="5",times="0"}
(gdb)
-break-commands 1 "print v" "continue"
^done
(gdb)
The `-break-condition' Command
------------------------------
Synopsis
........
-break-condition NUMBER EXPR
Breakpoint NUMBER will stop the program only if the condition in
EXPR is true. The condition becomes part of the `-break-list' output
(see the description of the `-break-list' command below).
GDB Command
...........
The corresponding GDB command is `condition'.
Example
.......
(gdb)
-break-condition 1 1
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",cond="1",times="0",ignore="3"}]}
(gdb)
The `-break-delete' Command
---------------------------
Synopsis
........
-break-delete ( BREAKPOINT )+
Delete the breakpoint(s) whose number(s) are specified in the
argument list. This is obviously reflected in the breakpoint list.
GDB Command
...........
The corresponding GDB command is `delete'.
Example
.......
(gdb)
-break-delete 1
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="0",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[]}
(gdb)
The `-break-disable' Command
----------------------------
Synopsis
........
-break-disable ( BREAKPOINT )+
Disable the named BREAKPOINT(s). The field `enabled' in the break
list is now set to `n' for the named BREAKPOINT(s).
GDB Command
...........
The corresponding GDB command is `disable'.
Example
.......
(gdb)
-break-disable 2
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",times="0"}]}
(gdb)
The `-break-enable' Command
---------------------------
Synopsis
........
-break-enable ( BREAKPOINT )+
Enable (previously disabled) BREAKPOINT(s).
GDB Command
...........
The corresponding GDB command is `enable'.
Example
.......
(gdb)
-break-enable 2
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",times="0"}]}
(gdb)
The `-break-info' Command
-------------------------
Synopsis
........
-break-info BREAKPOINT
Get information about a single breakpoint.
GDB Command
...........
The corresponding GDB command is `info break BREAKPOINT'.
Example
.......
N.A.
The `-break-insert' Command
---------------------------
Synopsis
........
-break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
[ -c CONDITION ] [ -i IGNORE-COUNT ]
[ -p THREAD-ID ] [ LOCATION ]
If specified, LOCATION, can be one of:
* function
* filename:linenum
* filename:function
* *address
The possible optional parameters of this command are:
`-t'
Insert a temporary breakpoint.
`-h'
Insert a hardware breakpoint.
`-f'
If LOCATION cannot be parsed (for example if it refers to unknown
files or functions), create a pending breakpoint. Without this
flag, GDB will report an error, and won't create a breakpoint, if
LOCATION cannot be parsed.
`-d'
Create a disabled breakpoint.
`-a'
Create a tracepoint. *Note Tracepoints::. When this parameter is
used together with `-h', a fast tracepoint is created.
`-c CONDITION'
Make the breakpoint conditional on CONDITION.
`-i IGNORE-COUNT'
Initialize the IGNORE-COUNT.
`-p THREAD-ID'
Restrict the breakpoint to the specified THREAD-ID.
Result
......
The result is in the form:
^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep",
enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME",
fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,]
times="TIMES"}
where NUMBER is the GDB number for this breakpoint, FUNCNAME is the
name of the function where the breakpoint was inserted, FILENAME is the
name of the source file which contains this function, LINENO is the
source line number within that file and TIMES the number of times that
the breakpoint has been hit (always 0 for -break-insert but may be
greater for -break-info or -break-list which use the same output).
Note: this format is open to change.
GDB Command
...........
The corresponding GDB commands are `break', `tbreak', `hbreak', and
`thbreak'.
Example
.......
(gdb)
-break-insert main
^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",
fullname="/home/foo/recursive2.c,line="4",times="0"}
(gdb)
-break-insert -t foo
^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",
fullname="/home/foo/recursive2.c,line="11",times="0"}
(gdb)
-break-list
^done,BreakpointTable={nr_rows="2",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x0001072c", func="main",file="recursive2.c",
fullname="/home/foo/recursive2.c,"line="4",times="0"},
bkpt={number="2",type="breakpoint",disp="del",enabled="y",
addr="0x00010774",func="foo",file="recursive2.c",
fullname="/home/foo/recursive2.c",line="11",times="0"}]}
(gdb)
The `-break-list' Command
-------------------------
Synopsis
........
-break-list
Displays the list of inserted breakpoints, showing the following
fields:
`Number'
number of the breakpoint
`Type'
type of the breakpoint: `breakpoint' or `watchpoint'
`Disposition'
should the breakpoint be deleted or disabled when it is hit: `keep'
or `nokeep'
`Enabled'
is the breakpoint enabled or no: `y' or `n'
`Address'
memory location at which the breakpoint is set
`What'
logical location of the breakpoint, expressed by function name,
file name, line number
`Times'
number of times the breakpoint has been hit
If there are no breakpoints or watchpoints, the `BreakpointTable'
`body' field is an empty list.
GDB Command
...........
The corresponding GDB command is `info break'.
Example
.......
(gdb)
-break-list
^done,BreakpointTable={nr_rows="2",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",line="5",times="0"},
bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
line="13",times="0"}]}
(gdb)
Here's an example of the result when there are no breakpoints:
(gdb)
-break-list
^done,BreakpointTable={nr_rows="0",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[]}
(gdb)
The `-break-passcount' Command
------------------------------
Synopsis
........
-break-passcount TRACEPOINT-NUMBER PASSCOUNT
Set the passcount for tracepoint TRACEPOINT-NUMBER to PASSCOUNT. If
the breakpoint referred to by TRACEPOINT-NUMBER is not a tracepoint,
error is emitted. This corresponds to CLI command `passcount'.
The `-break-watch' Command
--------------------------
Synopsis
........
-break-watch [ -a | -r ]
Create a watchpoint. With the `-a' option it will create an
"access" watchpoint, i.e., a watchpoint that triggers either on a read
from or on a write to the memory location. With the `-r' option, the
watchpoint created is a "read" watchpoint, i.e., it will trigger only
when the memory location is accessed for reading. Without either of
the options, the watchpoint created is a regular watchpoint, i.e., it
will trigger when the memory location is accessed for writing. *Note
Setting Watchpoints: Set Watchpoints.
Note that `-break-list' will report a single list of watchpoints and
breakpoints inserted.
GDB Command
...........
The corresponding GDB commands are `watch', `awatch', and `rwatch'.
Example
.......
Setting a watchpoint on a variable in the `main' function:
(gdb)
-break-watch x
^done,wpt={number="2",exp="x"}
(gdb)
-exec-continue
^running
(gdb)
*stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"},
value={old="-268439212",new="55"},
frame={func="main",args=[],file="recursive2.c",
fullname="/home/foo/bar/recursive2.c",line="5"}
(gdb)
Setting a watchpoint on a variable local to a function. GDB will
stop the program execution twice: first for the variable changing
value, then for the watchpoint going out of scope.
(gdb)
-break-watch C
^done,wpt={number="5",exp="C"}
(gdb)
-exec-continue
^running
(gdb)
*stopped,reason="watchpoint-trigger",
wpt={number="5",exp="C"},value={old="-276895068",new="3"},
frame={func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
(gdb)
-exec-continue
^running
(gdb)
*stopped,reason="watchpoint-scope",wpnum="5",
frame={func="callee3",args=[{name="strarg",
value="0x11940 \"A string argument.\""}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
(gdb)
Listing breakpoints and watchpoints, at different points in the
program execution. Note that once the watchpoint goes out of scope, it
is deleted.
(gdb)
-break-watch C
^done,wpt={number="2",exp="C"}
(gdb)
-break-list
^done,BreakpointTable={nr_rows="2",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"},
bkpt={number="2",type="watchpoint",disp="keep",
enabled="y",addr="",what="C",times="0"}]}
(gdb)
-exec-continue
^running
(gdb)
*stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"},
value={old="-276895068",new="3"},
frame={func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
(gdb)
-break-list
^done,BreakpointTable={nr_rows="2",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"},
bkpt={number="2",type="watchpoint",disp="keep",
enabled="y",addr="",what="C",times="-5"}]}
(gdb)
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="2",
frame={func="callee3",args=[{name="strarg",
value="0x11940 \"A string argument.\""}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
times="1"}]}
(gdb)

File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI
27.9 GDB/MI Program Context
============================
The `-exec-arguments' Command
-----------------------------
Synopsis
........
-exec-arguments ARGS
Set the inferior program arguments, to be used in the next
`-exec-run'.
GDB Command
...........
The corresponding GDB command is `set args'.
Example
.......
(gdb)
-exec-arguments -v word
^done
(gdb)
The `-environment-cd' Command
-----------------------------
Synopsis
........
-environment-cd PATHDIR
Set GDB's working directory.
GDB Command
...........
The corresponding GDB command is `cd'.
Example
.......
(gdb)
-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
^done
(gdb)
The `-environment-directory' Command
------------------------------------
Synopsis
........
-environment-directory [ -r ] [ PATHDIR ]+
Add directories PATHDIR to beginning of search path for source files.
If the `-r' option is used, the search path is reset to the default
search path. If directories PATHDIR are supplied in addition to the
`-r' option, the search path is first reset and then addition occurs as
normal. Multiple directories may be specified, separated by blanks.
Specifying multiple directories in a single command results in the
directories added to the beginning of the search path in the same order
they were presented in the command. If blanks are needed as part of a
directory name, double-quotes should be used around the name. In the
command output, the path will show up separated by the system
directory-separator character. The directory-separator character must
not be used in any directory name. If no directories are specified,
the current search path is displayed.
GDB Command
...........
The corresponding GDB command is `dir'.
Example
.......
(gdb)
-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
(gdb)
-environment-directory ""
^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
(gdb)
-environment-directory -r /home/jjohnstn/src/gdb /usr/src
^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
(gdb)
-environment-directory -r
^done,source-path="$cdir:$cwd"
(gdb)
The `-environment-path' Command
-------------------------------
Synopsis
........
-environment-path [ -r ] [ PATHDIR ]+
Add directories PATHDIR to beginning of search path for object files.
If the `-r' option is used, the search path is reset to the original
search path that existed at gdb start-up. If directories PATHDIR are
supplied in addition to the `-r' option, the search path is first reset
and then addition occurs as normal. Multiple directories may be
specified, separated by blanks. Specifying multiple directories in a
single command results in the directories added to the beginning of the
search path in the same order they were presented in the command. If
blanks are needed as part of a directory name, double-quotes should be
used around the name. In the command output, the path will show up
separated by the system directory-separator character. The
directory-separator character must not be used in any directory name.
If no directories are specified, the current path is displayed.
GDB Command
...........
The corresponding GDB command is `path'.
Example
.......
(gdb)
-environment-path
^done,path="/usr/bin"
(gdb)
-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
(gdb)
-environment-path -r /usr/local/bin
^done,path="/usr/local/bin:/usr/bin"
(gdb)
The `-environment-pwd' Command
------------------------------
Synopsis
........
-environment-pwd
Show the current working directory.
GDB Command
...........
The corresponding GDB command is `pwd'.
Example
.......
(gdb)
-environment-pwd
^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
(gdb)

File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Ada Tasking Commands, Prev: GDB/MI Program Context, Up: GDB/MI
27.10 GDB/MI Thread Commands
============================
The `-thread-info' Command
--------------------------
Synopsis
........
-thread-info [ THREAD-ID ]
Reports information about either a specific thread, if the THREAD-ID
parameter is present, or about all threads. When printing information
about all threads, also reports the current thread.
GDB Command
...........
The `info thread' command prints the same information about all threads.
Result
......
The result is a list of threads. The following attributes are defined
for a given thread:
`current'
This field exists only for the current thread. It has the value
`*'.
`id'
The identifier that GDB uses to refer to the thread.
`target-id'
The identifier that the target uses to refer to the thread.
`details'
Extra information about the thread, in a target-specific format.
This field is optional.
`name'
The name of the thread. If the user specified a name using the
`thread name' command, then this name is given. Otherwise, if GDB
can extract the thread name from the target, then that name is
given. If GDB cannot find the thread name, then this field is
omitted.
`frame'
The stack frame currently executing in the thread.
`state'
The thread's state. The `state' field may have the following
values:
`stopped'
The thread is stopped. Frame information is available for
stopped threads.
`running'
The thread is running. There's no frame information for
running threads.
`core'
If GDB can find the CPU core on which this thread is running, then
this field is the core identifier. This field is optional.
Example
.......
-thread-info
^done,threads=[
{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",
args=[]},state="running"},
{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
frame={level="0",addr="0x0804891f",func="foo",
args=[{name="i",value="10"}],
file="/tmp/a.c",fullname="/tmp/a.c",line="158"},
state="running"}],
current-thread-id="1"
(gdb)
The `-thread-list-ids' Command
------------------------------
Synopsis
........
-thread-list-ids
Produces a list of the currently known GDB thread ids. At the end
of the list it also prints the total number of such threads.
This command is retained for historical reasons, the `-thread-info'
command should be used instead.
GDB Command
...........
Part of `info threads' supplies the same information.
Example
.......
(gdb)
-thread-list-ids
^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"},
current-thread-id="1",number-of-threads="3"
(gdb)
The `-thread-select' Command
----------------------------
Synopsis
........
-thread-select THREADNUM
Make THREADNUM the current thread. It prints the number of the new
current thread, and the topmost frame for that thread.
This command is deprecated in favor of explicitly using the
`--thread' option to each command.
GDB Command
...........
The corresponding GDB command is `thread'.
Example
.......
(gdb)
-exec-next
^running
(gdb)
*stopped,reason="end-stepping-range",thread-id="2",line="187",
file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
(gdb)
-thread-list-ids
^done,
thread-ids={thread-id="3",thread-id="2",thread-id="1"},
number-of-threads="3"
(gdb)
-thread-select 3
^done,new-thread-id="3",
frame={level="0",func="vprintf",
args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""},
{name="arg",value="0x2"}],file="vprintf.c",line="31"}
(gdb)

File: gdb.info, Node: GDB/MI Ada Tasking Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Thread Commands, Up: GDB/MI
27.11 GDB/MI Ada Tasking Commands
=================================
The `-ada-task-info' Command
----------------------------
Synopsis
........
-ada-task-info [ TASK-ID ]
Reports information about either a specific Ada task, if the TASK-ID
parameter is present, or about all Ada tasks.
GDB Command
...........
The `info tasks' command prints the same information about all Ada
tasks (*note Ada Tasks::).
Result
......
The result is a table of Ada tasks. The following columns are defined
for each Ada task:
`current'
This field exists only for the current thread. It has the value
`*'.
`id'
The identifier that GDB uses to refer to the Ada task.
`task-id'
The identifier that the target uses to refer to the Ada task.
`thread-id'
The identifier of the thread corresponding to the Ada task.
This field should always exist, as Ada tasks are always implemented
on top of a thread. But if GDB cannot find this corresponding
thread for any reason, the field is omitted.
`parent-id'
This field exists only when the task was created by another task.
In this case, it provides the ID of the parent task.
`priority'
The base priority of the task.
`state'
The current state of the task. For a detailed description of the
possible states, see *Note Ada Tasks::.
`name'
The name of the task.
Example
.......
-ada-task-info
^done,tasks={nr_rows="3",nr_cols="8",
hdr=[{width="1",alignment="-1",col_name="current",colhdr=""},
{width="3",alignment="1",col_name="id",colhdr="ID"},
{width="9",alignment="1",col_name="task-id",colhdr="TID"},
{width="4",alignment="1",col_name="thread-id",colhdr=""},
{width="4",alignment="1",col_name="parent-id",colhdr="P-ID"},
{width="3",alignment="1",col_name="priority",colhdr="Pri"},
{width="22",alignment="-1",col_name="state",colhdr="State"},
{width="1",alignment="2",col_name="name",colhdr="Name"}],
body=[{current="*",id="1",task-id=" 644010",thread-id="1",priority="48",
state="Child Termination Wait",name="main_task"}]}
(gdb)

File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Ada Tasking Commands, Up: GDB/MI
27.12 GDB/MI Program Execution
==============================
These are the asynchronous commands which generate the out-of-band
record `*stopped'. Currently GDB only really executes asynchronously
with remote targets and this interaction is mimicked in other cases.
The `-exec-continue' Command
----------------------------
Synopsis
........
-exec-continue [--reverse] [--all|--thread-group N]
Resumes the execution of the inferior program, which will continue
to execute until it reaches a debugger stop event. If the `--reverse'
option is specified, execution resumes in reverse until it reaches a
stop event. Stop events may include
* breakpoints or watchpoints
* signals or exceptions
* the end of the process (or its beginning under `--reverse')
* the end or beginning of a replay log if one is being used.
In all-stop mode (*note All-Stop Mode::), may resume only one
thread, or all threads, depending on the value of the
`scheduler-locking' variable. If `--all' is specified, all threads (in
all inferiors) will be resumed. The `--all' option is ignored in
all-stop mode. If the `--thread-group' options is specified, then all
threads in that thread group are resumed.
GDB Command
...........
The corresponding GDB corresponding is `continue'.
Example
.......
-exec-continue
^running
(gdb)
@Hello world
*stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={
func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c",
line="13"}
(gdb)
The `-exec-finish' Command
--------------------------
Synopsis
........
-exec-finish [--reverse]
Resumes the execution of the inferior program until the current
function is exited. Displays the results returned by the function. If
the `--reverse' option is specified, resumes the reverse execution of
the inferior program until the point where current function was called.
GDB Command
...........
The corresponding GDB command is `finish'.
Example
.......
Function returning `void'.
-exec-finish
^running
(gdb)
@hello from foo
*stopped,reason="function-finished",frame={func="main",args=[],
file="hello.c",fullname="/home/foo/bar/hello.c",line="7"}
(gdb)
Function returning other than `void'. The name of the internal GDB
variable storing the result is printed, together with the value itself.
-exec-finish
^running
(gdb)
*stopped,reason="function-finished",frame={addr="0x000107b0",func="foo",
args=[{name="a",value="1"],{name="b",value="9"}},
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
gdb-result-var="$1",return-value="0"
(gdb)
The `-exec-interrupt' Command
-----------------------------
Synopsis
........
-exec-interrupt [--all|--thread-group N]
Interrupts the background execution of the target. Note how the
token associated with the stop message is the one for the execution
command that has been interrupted. The token for the interrupt itself
only appears in the `^done' output. If the user is trying to interrupt
a non-running program, an error message will be printed.
Note that when asynchronous execution is enabled, this command is
asynchronous just like other execution commands. That is, first the
`^done' response will be printed, and the target stop will be reported
after that using the `*stopped' notification.
In non-stop mode, only the context thread is interrupted by default.
All threads (in all inferiors) will be interrupted if the `--all'
option is specified. If the `--thread-group' option is specified, all
threads in that group will be interrupted.
GDB Command
...........
The corresponding GDB command is `interrupt'.
Example
.......
(gdb)
111-exec-continue
111^running
(gdb)
222-exec-interrupt
222^done
(gdb)
111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
frame={addr="0x00010140",func="foo",args=[],file="try.c",
fullname="/home/foo/bar/try.c",line="13"}
(gdb)
(gdb)
-exec-interrupt
^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
(gdb)
The `-exec-jump' Command
------------------------
Synopsis
........
-exec-jump LOCATION
Resumes execution of the inferior program at the location specified
by parameter. *Note Specify Location::, for a description of the
different forms of LOCATION.
GDB Command
...........
The corresponding GDB command is `jump'.
Example
.......
-exec-jump foo.c:10
*running,thread-id="all"
^running
The `-exec-next' Command
------------------------
Synopsis
........
-exec-next [--reverse]
Resumes execution of the inferior program, stopping when the
beginning of the next source line is reached.
If the `--reverse' option is specified, resumes reverse execution of
the inferior program, stopping at the beginning of the previous source
line. If you issue this command on the first line of a function, it
will take you back to the caller of that function, to the source line
where the function was called.
GDB Command
...........
The corresponding GDB command is `next'.
Example
.......
-exec-next
^running
(gdb)
*stopped,reason="end-stepping-range",line="8",file="hello.c"
(gdb)
The `-exec-next-instruction' Command
------------------------------------
Synopsis
........
-exec-next-instruction [--reverse]
Executes one machine instruction. If the instruction is a function
call, continues until the function returns. If the program stops at an
instruction in the middle of a source line, the address will be printed
as well.
If the `--reverse' option is specified, resumes reverse execution of
the inferior program, stopping at the previous instruction. If the
previously executed instruction was a return from another function, it
will continue to execute in reverse until the call to that function
(from the current stack frame) is reached.
GDB Command
...........
The corresponding GDB command is `nexti'.
Example
.......
(gdb)
-exec-next-instruction
^running
(gdb)
*stopped,reason="end-stepping-range",
addr="0x000100d4",line="5",file="hello.c"
(gdb)
The `-exec-return' Command
--------------------------
Synopsis
........
-exec-return
Makes current function return immediately. Doesn't execute the
inferior. Displays the new current frame.
GDB Command
...........
The corresponding GDB command is `return'.
Example
.......
(gdb)
200-break-insert callee4
200^done,bkpt={number="1",addr="0x00010734",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
(gdb)
000-exec-run
000^running
(gdb)
000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
frame={func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
(gdb)
205-break-delete
205^done
(gdb)
111-exec-return
111^done,frame={level="0",func="callee3",
args=[{name="strarg",
value="0x11940 \"A string argument.\""}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
(gdb)
The `-exec-run' Command
-----------------------
Synopsis
........
-exec-run [--all | --thread-group N]
Starts execution of the inferior from the beginning. The inferior
executes until either a breakpoint is encountered or the program exits.
In the latter case the output will include an exit code, if the
program has exited exceptionally.
When no option is specified, the current inferior is started. If the
`--thread-group' option is specified, it should refer to a thread group
of type `process', and that thread group will be started. If the
`--all' option is specified, then all inferiors will be started.
GDB Command
...........
The corresponding GDB command is `run'.
Examples
........
(gdb)
-break-insert main
^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
(gdb)
-exec-run
^running
(gdb)
*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
frame={func="main",args=[],file="recursive2.c",
fullname="/home/foo/bar/recursive2.c",line="4"}
(gdb)
Program exited normally:
(gdb)
-exec-run
^running
(gdb)
x = 55
*stopped,reason="exited-normally"
(gdb)
Program exited exceptionally:
(gdb)
-exec-run
^running
(gdb)
x = 55
*stopped,reason="exited",exit-code="01"
(gdb)
Another way the program can terminate is if it receives a signal
such as `SIGINT'. In this case, GDB/MI displays this:
(gdb)
*stopped,reason="exited-signalled",signal-name="SIGINT",
signal-meaning="Interrupt"
The `-exec-step' Command
------------------------
Synopsis
........
-exec-step [--reverse]
Resumes execution of the inferior program, stopping when the
beginning of the next source line is reached, if the next source line
is not a function call. If it is, stop at the first instruction of the
called function. If the `--reverse' option is specified, resumes
reverse execution of the inferior program, stopping at the beginning of
the previously executed source line.
GDB Command
...........
The corresponding GDB command is `step'.
Example
.......
Stepping into a function:
-exec-step
^running
(gdb)
*stopped,reason="end-stepping-range",
frame={func="foo",args=[{name="a",value="10"},
{name="b",value="0"}],file="recursive2.c",
fullname="/home/foo/bar/recursive2.c",line="11"}
(gdb)
Regular stepping:
-exec-step
^running
(gdb)
*stopped,reason="end-stepping-range",line="14",file="recursive2.c"
(gdb)
The `-exec-step-instruction' Command
------------------------------------
Synopsis
........
-exec-step-instruction [--reverse]
Resumes the inferior which executes one machine instruction. If the
`--reverse' option is specified, resumes reverse execution of the
inferior program, stopping at the previously executed instruction. The
output, once GDB has stopped, will vary depending on whether we have
stopped in the middle of a source line or not. In the former case, the
address at which the program stopped will be printed as well.
GDB Command
...........
The corresponding GDB command is `stepi'.
Example
.......
(gdb)
-exec-step-instruction
^running
(gdb)
*stopped,reason="end-stepping-range",
frame={func="foo",args=[],file="try.c",
fullname="/home/foo/bar/try.c",line="10"}
(gdb)
-exec-step-instruction
^running
(gdb)
*stopped,reason="end-stepping-range",
frame={addr="0x000100f4",func="foo",args=[],file="try.c",
fullname="/home/foo/bar/try.c",line="10"}
(gdb)
The `-exec-until' Command
-------------------------
Synopsis
........
-exec-until [ LOCATION ]
Executes the inferior until the LOCATION specified in the argument
is reached. If there is no argument, the inferior executes until a
source line greater than the current one is reached. The reason for
stopping in this case will be `location-reached'.
GDB Command
...........
The corresponding GDB command is `until'.
Example
.......
(gdb)
-exec-until recursive2.c:6
^running
(gdb)
x = 55
*stopped,reason="location-reached",frame={func="main",args=[],
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"}
(gdb)

File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI
27.13 GDB/MI Stack Manipulation Commands
========================================
The `-stack-info-frame' Command
-------------------------------
Synopsis
........
-stack-info-frame
Get info on the selected frame.
GDB Command
...........
The corresponding GDB command is `info frame' or `frame' (without
arguments).
Example
.......
(gdb)
-stack-info-frame
^done,frame={level="1",addr="0x0001076c",func="callee3",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}
(gdb)
The `-stack-info-depth' Command
-------------------------------
Synopsis
........
-stack-info-depth [ MAX-DEPTH ]
Return the depth of the stack. If the integer argument MAX-DEPTH is
specified, do not count beyond MAX-DEPTH frames.
GDB Command
...........
There's no equivalent GDB command.
Example
.......
For a stack with frame levels 0 through 11:
(gdb)
-stack-info-depth
^done,depth="12"
(gdb)
-stack-info-depth 4
^done,depth="4"
(gdb)
-stack-info-depth 12
^done,depth="12"
(gdb)
-stack-info-depth 11
^done,depth="11"
(gdb)
-stack-info-depth 13
^done,depth="12"
(gdb)
The `-stack-list-arguments' Command
-----------------------------------
Synopsis
........
-stack-list-arguments PRINT-VALUES
[ LOW-FRAME HIGH-FRAME ]
Display a list of the arguments for the frames between LOW-FRAME and
HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided,
list the arguments for the whole call stack. If the two arguments are
equal, show the single frame at the corresponding level. It is an
error if LOW-FRAME is larger than the actual number of frames. On the
other hand, HIGH-FRAME may be larger than the actual number of frames,
in which case only existing frames will be returned.
If PRINT-VALUES is 0 or `--no-values', print only the names of the
variables; if it is 1 or `--all-values', print also their values; and
if it is 2 or `--simple-values', print the name, type and value for
simple data types, and the name and type for arrays, structures and
unions.
Use of this command to obtain arguments in a single frame is
deprecated in favor of the `-stack-list-variables' command.
GDB Command
...........
GDB does not have an equivalent command. `gdbtk' has a `gdb_get_args'
command which partially overlaps with the functionality of
`-stack-list-arguments'.
Example
.......
(gdb)
-stack-list-frames
^done,
stack=[
frame={level="0",addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"},
frame={level="1",addr="0x0001076c",func="callee3",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"},
frame={level="2",addr="0x0001078c",func="callee2",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"},
frame={level="3",addr="0x000107b4",func="callee1",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"},
frame={level="4",addr="0x000107e0",func="main",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}]
(gdb)
-stack-list-arguments 0
^done,
stack-args=[
frame={level="0",args=[]},
frame={level="1",args=[name="strarg"]},
frame={level="2",args=[name="intarg",name="strarg"]},
frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]},
frame={level="4",args=[]}]
(gdb)
-stack-list-arguments 1
^done,
stack-args=[
frame={level="0",args=[]},
frame={level="1",
args=[{name="strarg",value="0x11940 \"A string argument.\""}]},
frame={level="2",args=[
{name="intarg",value="2"},
{name="strarg",value="0x11940 \"A string argument.\""}]},
{frame={level="3",args=[
{name="intarg",value="2"},
{name="strarg",value="0x11940 \"A string argument.\""},
{name="fltarg",value="3.5"}]},
frame={level="4",args=[]}]
(gdb)
-stack-list-arguments 0 2 2
^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}]
(gdb)
-stack-list-arguments 1 2 2
^done,stack-args=[frame={level="2",
args=[{name="intarg",value="2"},
{name="strarg",value="0x11940 \"A string argument.\""}]}]
(gdb)
The `-stack-list-frames' Command
--------------------------------
Synopsis
........
-stack-list-frames [ LOW-FRAME HIGH-FRAME ]
List the frames currently on the stack. For each frame it displays
the following info:
`LEVEL'
The frame number, 0 being the topmost frame, i.e., the innermost
function.
`ADDR'
The `$pc' value for that frame.
`FUNC'
Function name.
`FILE'
File name of the source file where the function lives.
`FULLNAME'
The full file name of the source file where the function lives.
`LINE'
Line number corresponding to the `$pc'.
`FROM'
The shared library where this function is defined. This is only
given if the frame's function is not known.
If invoked without arguments, this command prints a backtrace for the
whole stack. If given two integer arguments, it shows the frames whose
levels are between the two arguments (inclusive). If the two arguments
are equal, it shows the single frame at the corresponding level. It is
an error if LOW-FRAME is larger than the actual number of frames. On
the other hand, HIGH-FRAME may be larger than the actual number of
frames, in which case only existing frames will be returned.
GDB Command
...........
The corresponding GDB commands are `backtrace' and `where'.
Example
.......
Full stack backtrace:
(gdb)
-stack-list-frames
^done,stack=
[frame={level="0",addr="0x0001076c",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"},
frame={level="1",addr="0x000107a4",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
frame={level="2",addr="0x000107a4",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
frame={level="3",addr="0x000107a4",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
frame={level="4",addr="0x000107a4",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
frame={level="5",addr="0x000107a4",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
frame={level="6",addr="0x000107a4",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
frame={level="7",addr="0x000107a4",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
frame={level="8",addr="0x000107a4",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
frame={level="9",addr="0x000107a4",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
frame={level="10",addr="0x000107a4",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
frame={level="11",addr="0x00010738",func="main",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}]
(gdb)
Show frames between LOW_FRAME and HIGH_FRAME:
(gdb)
-stack-list-frames 3 5
^done,stack=
[frame={level="3",addr="0x000107a4",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
frame={level="4",addr="0x000107a4",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"},
frame={level="5",addr="0x000107a4",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
(gdb)
Show a single frame:
(gdb)
-stack-list-frames 3 3
^done,stack=
[frame={level="3",addr="0x000107a4",func="foo",
file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}]
(gdb)
The `-stack-list-locals' Command
--------------------------------
Synopsis
........
-stack-list-locals PRINT-VALUES
Display the local variable names for the selected frame. If
PRINT-VALUES is 0 or `--no-values', print only the names of the
variables; if it is 1 or `--all-values', print also their values; and
if it is 2 or `--simple-values', print the name, type and value for
simple data types, and the name and type for arrays, structures and
unions. In this last case, a frontend can immediately display the
value of simple data types and create variable objects for other data
types when the user wishes to explore their values in more detail.
This command is deprecated in favor of the `-stack-list-variables'
command.
GDB Command
...........
`info locals' in GDB, `gdb_get_locals' in `gdbtk'.
Example
.......
(gdb)
-stack-list-locals 0
^done,locals=[name="A",name="B",name="C"]
(gdb)
-stack-list-locals --all-values
^done,locals=[{name="A",value="1"},{name="B",value="2"},
{name="C",value="{1, 2, 3}"}]
-stack-list-locals --simple-values
^done,locals=[{name="A",type="int",value="1"},
{name="B",type="int",value="2"},{name="C",type="int [3]"}]
(gdb)
The `-stack-list-variables' Command
-----------------------------------
Synopsis
........
-stack-list-variables PRINT-VALUES
Display the names of local variables and function arguments for the
selected frame. If PRINT-VALUES is 0 or `--no-values', print only the
names of the variables; if it is 1 or `--all-values', print also their
values; and if it is 2 or `--simple-values', print the name, type and
value for simple data types, and the name and type for arrays,
structures and unions.
Example
.......
(gdb)
-stack-list-variables --thread 1 --frame 0 --all-values
^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}]
(gdb)
The `-stack-select-frame' Command
---------------------------------
Synopsis
........
-stack-select-frame FRAMENUM
Change the selected frame. Select a different frame FRAMENUM on the
stack.
This command in deprecated in favor of passing the `--frame' option
to every command.
GDB Command
...........
The corresponding GDB commands are `frame', `up', `down',
`select-frame', `up-silent', and `down-silent'.
Example
.......
(gdb)
-stack-select-frame 2
^done
(gdb)

File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI
27.14 GDB/MI Variable Objects
=============================
Introduction to Variable Objects
--------------------------------
Variable objects are "object-oriented" MI interface for examining and