This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.
|
This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.
|
|
|
INFO-DIR-SECTION Programming & development tools.
|
INFO-DIR-SECTION Programming & development tools.
|
START-INFO-DIR-ENTRY
|
START-INFO-DIR-ENTRY
|
* Gdb: (gdb). The GNU debugger.
|
* Gdb: (gdb). The GNU debugger.
|
END-INFO-DIR-ENTRY
|
END-INFO-DIR-ENTRY
|
|
|
This file documents the GNU debugger GDB.
|
This file documents the GNU debugger GDB.
|
|
|
This is the Ninth Edition, April 2001, of `Debugging with GDB: the
|
This is the Ninth Edition, April 2001, of `Debugging with GDB: the
|
GNU Source-Level Debugger' for GDB Version 20010707.
|
GNU Source-Level Debugger' for GDB Version 20010707.
|
|
|
Copyright (C)
|
Copyright (C)
|
1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
|
1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
|
Free Software Foundation, Inc.
|
Free Software Foundation, Inc.
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.1 or
|
under the terms of the GNU Free Documentation License, Version 1.1 or
|
any later version published by the Free Software Foundation; with the
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being "A Sample GDB Session" and "Free Software",
|
Invariant Sections being "A Sample GDB Session" and "Free Software",
|
with the Front-Cover texts being "A GNU Manual," and with the
|
with the Front-Cover texts being "A GNU Manual," and with the
|
Back-Cover Texts as in (a) below.
|
Back-Cover Texts as in (a) below.
|
|
|
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
|
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
|
modify this GNU Manual, like GNU software. Copies published by the Free
|
modify this GNU Manual, like GNU software. Copies published by the Free
|
Software Foundation raise funds for GNU development."
|
Software Foundation raise funds for GNU development."
|
|
|
|
|
File: gdb.info, Node: Define, Next: Hooks, Up: Sequences
|
File: gdb.info, Node: Define, Next: Hooks, Up: Sequences
|
|
|
User-defined commands
|
User-defined commands
|
=====================
|
=====================
|
|
|
A "user-defined command" is a sequence of GDB commands to which you
|
A "user-defined command" is a sequence of GDB commands to which you
|
assign a new name as a command. This is done with the `define'
|
assign a new name as a command. This is done with the `define'
|
command. User commands may accept up to 10 arguments separated by
|
command. User commands may accept up to 10 arguments separated by
|
whitespace. Arguments are accessed within the user command via
|
whitespace. Arguments are accessed within the user command via
|
$ARG0...$ARG9. A trivial example:
|
$ARG0...$ARG9. A trivial example:
|
|
|
define adder
|
define adder
|
print $arg0 + $arg1 + $arg2
|
print $arg0 + $arg1 + $arg2
|
|
|
To execute the command use:
|
To execute the command use:
|
|
|
adder 1 2 3
|
adder 1 2 3
|
|
|
This defines the command `adder', which prints the sum of its three
|
This defines the command `adder', which prints the sum of its three
|
arguments. Note the arguments are text substitutions, so they may
|
arguments. Note the arguments are text substitutions, so they may
|
reference variables, use complex expressions, or even perform inferior
|
reference variables, use complex expressions, or even perform inferior
|
functions calls.
|
functions calls.
|
|
|
`define COMMANDNAME'
|
`define COMMANDNAME'
|
Define a command named COMMANDNAME. If there is already a command
|
Define a command named COMMANDNAME. If there is already a command
|
by that name, you are asked to confirm that you want to redefine
|
by that name, you are asked to confirm that you want to redefine
|
it.
|
it.
|
|
|
The definition of the command is made up of other GDB command
|
The definition of the command is made up of other GDB command
|
lines, which are given following the `define' command. The end of
|
lines, which are given following the `define' command. The end of
|
these commands is marked by a line containing `end'.
|
these commands is marked by a line containing `end'.
|
|
|
`if'
|
`if'
|
Takes a single argument, which is an expression to evaluate. It
|
Takes a single argument, which is an expression to evaluate. It
|
is followed by a series of commands that are executed only if the
|
is followed by a series of commands that are executed only if the
|
expression is true (nonzero). There can then optionally be a line
|
expression is true (nonzero). There can then optionally be a line
|
`else', followed by a series of commands that are only executed if
|
`else', followed by a series of commands that are only executed if
|
the expression was false. The end of the list is marked by a line
|
the expression was false. The end of the list is marked by a line
|
containing `end'.
|
containing `end'.
|
|
|
`while'
|
`while'
|
The syntax is similar to `if': the command takes a single argument,
|
The syntax is similar to `if': the command takes a single argument,
|
which is an expression to evaluate, and must be followed by the
|
which is an expression to evaluate, and must be followed by the
|
commands to execute, one per line, terminated by an `end'. The
|
commands to execute, one per line, terminated by an `end'. The
|
commands are executed repeatedly as long as the expression
|
commands are executed repeatedly as long as the expression
|
evaluates to true.
|
evaluates to true.
|
|
|
`document COMMANDNAME'
|
`document COMMANDNAME'
|
Document the user-defined command COMMANDNAME, so that it can be
|
Document the user-defined command COMMANDNAME, so that it can be
|
accessed by `help'. The command COMMANDNAME must already be
|
accessed by `help'. The command COMMANDNAME must already be
|
defined. This command reads lines of documentation just as
|
defined. This command reads lines of documentation just as
|
`define' reads the lines of the command definition, ending with
|
`define' reads the lines of the command definition, ending with
|
`end'. After the `document' command is finished, `help' on command
|
`end'. After the `document' command is finished, `help' on command
|
COMMANDNAME displays the documentation you have written.
|
COMMANDNAME displays the documentation you have written.
|
|
|
You may use the `document' command again to change the
|
You may use the `document' command again to change the
|
documentation of a command. Redefining the command with `define'
|
documentation of a command. Redefining the command with `define'
|
does not change the documentation.
|
does not change the documentation.
|
|
|
`help user-defined'
|
`help user-defined'
|
List all user-defined commands, with the first line of the
|
List all user-defined commands, with the first line of the
|
documentation (if any) for each.
|
documentation (if any) for each.
|
|
|
`show user'
|
`show user'
|
`show user COMMANDNAME'
|
`show user COMMANDNAME'
|
Display the GDB commands used to define COMMANDNAME (but not its
|
Display the GDB commands used to define COMMANDNAME (but not its
|
documentation). If no COMMANDNAME is given, display the
|
documentation). If no COMMANDNAME is given, display the
|
definitions for all user-defined commands.
|
definitions for all user-defined commands.
|
|
|
When user-defined commands are executed, the commands of the
|
When user-defined commands are executed, the commands of the
|
definition are not printed. An error in any command stops execution of
|
definition are not printed. An error in any command stops execution of
|
the user-defined command.
|
the user-defined command.
|
|
|
If used interactively, commands that would ask for confirmation
|
If used interactively, commands that would ask for confirmation
|
proceed without asking when used inside a user-defined command. Many
|
proceed without asking when used inside a user-defined command. Many
|
GDB commands that normally print messages to say what they are doing
|
GDB commands that normally print messages to say what they are doing
|
omit the messages when used in a user-defined command.
|
omit the messages when used in a user-defined command.
|
|
|
|
|
File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences
|
File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences
|
|
|
User-defined command hooks
|
User-defined command hooks
|
==========================
|
==========================
|
|
|
You may define "hooks", which are a special kind of user-defined
|
You may define "hooks", which are a special kind of user-defined
|
command. Whenever you run the command `foo', if the user-defined
|
command. Whenever you run the command `foo', if the user-defined
|
command `hook-foo' exists, it is executed (with no arguments) before
|
command `hook-foo' exists, it is executed (with no arguments) before
|
that command.
|
that command.
|
|
|
A hook may also be defined which is run after the command you
|
A hook may also be defined which is run after the command you
|
executed. Whenever you run the command `foo', if the user-defined
|
executed. Whenever you run the command `foo', if the user-defined
|
command `hookpost-foo' exists, it is executed (with no arguments) after
|
command `hookpost-foo' exists, it is executed (with no arguments) after
|
that command. Post-execution hooks may exist simultaneously with
|
that command. Post-execution hooks may exist simultaneously with
|
pre-execution hooks, for the same command.
|
pre-execution hooks, for the same command.
|
|
|
It is valid for a hook to call the command which it hooks. If this
|
It is valid for a hook to call the command which it hooks. If this
|
occurs, the hook is not re-executed, thereby avoiding infinte recursion.
|
occurs, the hook is not re-executed, thereby avoiding infinte recursion.
|
|
|
In addition, a pseudo-command, `stop' exists. Defining
|
In addition, a pseudo-command, `stop' exists. Defining
|
(`hook-stop') makes the associated commands execute every time
|
(`hook-stop') makes the associated commands execute every time
|
execution stops in your program: before breakpoint commands are run,
|
execution stops in your program: before breakpoint commands are run,
|
displays are printed, or the stack frame is printed.
|
displays are printed, or the stack frame is printed.
|
|
|
For example, to ignore `SIGALRM' signals while single-stepping, but
|
For example, to ignore `SIGALRM' signals while single-stepping, but
|
treat them normally during normal execution, you could define:
|
treat them normally during normal execution, you could define:
|
|
|
define hook-stop
|
define hook-stop
|
handle SIGALRM nopass
|
handle SIGALRM nopass
|
end
|
end
|
|
|
define hook-run
|
define hook-run
|
handle SIGALRM pass
|
handle SIGALRM pass
|
end
|
end
|
|
|
define hook-continue
|
define hook-continue
|
handle SIGLARM pass
|
handle SIGLARM pass
|
end
|
end
|
|
|
As a further example, to hook at the begining and end of the `echo'
|
As a further example, to hook at the begining and end of the `echo'
|
command, and to add extra text to the beginning and end of the message,
|
command, and to add extra text to the beginning and end of the message,
|
you could define:
|
you could define:
|
|
|
define hook-echo
|
define hook-echo
|
echo <<<---
|
echo <<<---
|
end
|
end
|
|
|
define hookpost-echo
|
define hookpost-echo
|
echo --->>>\n
|
echo --->>>\n
|
end
|
end
|
|
|
(gdb) echo Hello World
|
(gdb) echo Hello World
|
<<<---Hello World--->>>
|
<<<---Hello World--->>>
|
(gdb)
|
(gdb)
|
|
|
You can define a hook for any single-word command in GDB, but not
|
You can define a hook for any single-word command in GDB, but not
|
for command aliases; you should define a hook for the basic command
|
for command aliases; you should define a hook for the basic command
|
name, e.g. `backtrace' rather than `bt'. If an error occurs during
|
name, e.g. `backtrace' rather than `bt'. If an error occurs during
|
the execution of your hook, execution of GDB commands stops and GDB
|
the execution of your hook, execution of GDB commands stops and GDB
|
issues a prompt (before the command that you actually typed had a
|
issues a prompt (before the command that you actually typed had a
|
chance to run).
|
chance to run).
|
|
|
If you try to define a hook which does not match any known command,
|
If you try to define a hook which does not match any known command,
|
you get a warning from the `define' command.
|
you get a warning from the `define' command.
|
|
|
|
|
File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences
|
File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences
|
|
|
Command files
|
Command files
|
=============
|
=============
|
|
|
A command file for GDB is a file of lines that are GDB commands.
|
A command file for GDB is a file of lines that are GDB commands.
|
Comments (lines starting with `#') may also be included. An empty line
|
Comments (lines starting with `#') may also be included. An empty line
|
in a command file does nothing; it does not mean to repeat the last
|
in a command file does nothing; it does not mean to repeat the last
|
command, as it would from the terminal.
|
command, as it would from the terminal.
|
|
|
When you start GDB, it automatically executes commands from its
|
When you start GDB, it automatically executes commands from its
|
"init files". These are files named `.gdbinit' on Unix and `gdb.ini'
|
"init files". These are files named `.gdbinit' on Unix and `gdb.ini'
|
on DOS/Windows. During startup, GDB does the following:
|
on DOS/Windows. During startup, GDB does the following:
|
|
|
1. Reads the init file (if any) in your home directory(1).
|
1. Reads the init file (if any) in your home directory(1).
|
|
|
2. Processes command line options and operands.
|
2. Processes command line options and operands.
|
|
|
3. Reads the init file (if any) in the current working directory.
|
3. Reads the init file (if any) in the current working directory.
|
|
|
4. Reads command files specified by the `-x' option.
|
4. Reads command files specified by the `-x' option.
|
|
|
The init file in your home directory can set options (such as `set
|
The init file in your home directory can set options (such as `set
|
complaints') that affect subsequent processing of command line options
|
complaints') that affect subsequent processing of command line options
|
and operands. Init files are not executed if you use the `-nx' option
|
and operands. Init files are not executed if you use the `-nx' option
|
(*note Choosing modes: Mode Options.).
|
(*note Choosing modes: Mode Options.).
|
|
|
On some configurations of GDB, the init file is known by a different
|
On some configurations of GDB, the init file is known by a different
|
name (these are typically environments where a specialized form of GDB
|
name (these are typically environments where a specialized form of GDB
|
may need to coexist with other forms, hence a different name for the
|
may need to coexist with other forms, hence a different name for the
|
specialized version's init file). These are the environments with
|
specialized version's init file). These are the environments with
|
special init file names:
|
special init file names:
|
|
|
* VxWorks (Wind River Systems real-time OS): `.vxgdbinit'
|
* VxWorks (Wind River Systems real-time OS): `.vxgdbinit'
|
|
|
* OS68K (Enea Data Systems real-time OS): `.os68gdbinit'
|
* OS68K (Enea Data Systems real-time OS): `.os68gdbinit'
|
|
|
* ES-1800 (Ericsson Telecom AB M68000 emulator): `.esgdbinit'
|
* ES-1800 (Ericsson Telecom AB M68000 emulator): `.esgdbinit'
|
|
|
You can also request the execution of a command file with the
|
You can also request the execution of a command file with the
|
`source' command:
|
`source' command:
|
|
|
`source FILENAME'
|
`source FILENAME'
|
Execute the command file FILENAME.
|
Execute the command file FILENAME.
|
|
|
The lines in a command file are executed sequentially. They are not
|
The lines in a command file are executed sequentially. They are not
|
printed as they are executed. An error in any command terminates
|
printed as they are executed. An error in any command terminates
|
execution of the command file.
|
execution of the command file.
|
|
|
Commands that would ask for confirmation if used interactively
|
Commands that would ask for confirmation if used interactively
|
proceed without asking when used in a command file. Many GDB commands
|
proceed without asking when used in a command file. Many GDB commands
|
that normally print messages to say what they are doing omit the
|
that normally print messages to say what they are doing omit the
|
messages when called from command files.
|
messages when called from command files.
|
|
|
---------- Footnotes ----------
|
---------- Footnotes ----------
|
|
|
(1) On DOS/Windows systems, the home directory is the one pointed to
|
(1) On DOS/Windows systems, the home directory is the one pointed to
|
by the `HOME' environment variable.
|
by the `HOME' environment variable.
|
|
|
|
|
File: gdb.info, Node: Output, Prev: Command Files, Up: Sequences
|
File: gdb.info, Node: Output, Prev: Command Files, Up: Sequences
|
|
|
Commands for controlled output
|
Commands for controlled output
|
==============================
|
==============================
|
|
|
During the execution of a command file or a user-defined command,
|
During the execution of a command file or a user-defined command,
|
normal GDB output is suppressed; the only output that appears is what is
|
normal GDB output is suppressed; the only output that appears is what is
|
explicitly printed by the commands in the definition. This section
|
explicitly printed by the commands in the definition. This section
|
describes three commands useful for generating exactly the output you
|
describes three commands useful for generating exactly the output you
|
want.
|
want.
|
|
|
`echo TEXT'
|
`echo TEXT'
|
Print TEXT. Nonprinting characters can be included in TEXT using
|
Print TEXT. Nonprinting characters can be included in TEXT using
|
C escape sequences, such as `\n' to print a newline. *No newline
|
C escape sequences, such as `\n' to print a newline. *No newline
|
is printed unless you specify one.* In addition to the standard C
|
is printed unless you specify one.* In addition to the standard C
|
escape sequences, a backslash followed by a space stands for a
|
escape sequences, a backslash followed by a space stands for a
|
space. This is useful for displaying a string with spaces at the
|
space. This is useful for displaying a string with spaces at the
|
beginning or the end, since leading and trailing spaces are
|
beginning or the end, since leading and trailing spaces are
|
otherwise trimmed from all arguments. To print ` and foo = ', use
|
otherwise trimmed from all arguments. To print ` and foo = ', use
|
the command `echo \ and foo = \ '.
|
the command `echo \ and foo = \ '.
|
|
|
A backslash at the end of TEXT can be used, as in C, to continue
|
A backslash at the end of TEXT can be used, as in C, to continue
|
the command onto subsequent lines. For example,
|
the command onto subsequent lines. For example,
|
|
|
echo This is some text\n\
|
echo This is some text\n\
|
which is continued\n\
|
which is continued\n\
|
onto several lines.\n
|
onto several lines.\n
|
|
|
produces the same output as
|
produces the same output as
|
|
|
echo This is some text\n
|
echo This is some text\n
|
echo which is continued\n
|
echo which is continued\n
|
echo onto several lines.\n
|
echo onto several lines.\n
|
|
|
`output EXPRESSION'
|
`output EXPRESSION'
|
Print the value of EXPRESSION and nothing but that value: no
|
Print the value of EXPRESSION and nothing but that value: no
|
newlines, no `$NN = '. The value is not entered in the value
|
newlines, no `$NN = '. The value is not entered in the value
|
history either. *Note Expressions: Expressions, for more
|
history either. *Note Expressions: Expressions, for more
|
information on expressions.
|
information on expressions.
|
|
|
`output/FMT EXPRESSION'
|
`output/FMT EXPRESSION'
|
Print the value of EXPRESSION in format FMT. You can use the same
|
Print the value of EXPRESSION in format FMT. You can use the same
|
formats as for `print'. *Note Output formats: Output Formats, for
|
formats as for `print'. *Note Output formats: Output Formats, for
|
more information.
|
more information.
|
|
|
`printf STRING, EXPRESSIONS...'
|
`printf STRING, EXPRESSIONS...'
|
Print the values of the EXPRESSIONS under the control of STRING.
|
Print the values of the EXPRESSIONS under the control of STRING.
|
The EXPRESSIONS are separated by commas and may be either numbers
|
The EXPRESSIONS are separated by commas and may be either numbers
|
or pointers. Their values are printed as specified by STRING,
|
or pointers. Their values are printed as specified by STRING,
|
exactly as if your program were to execute the C subroutine
|
exactly as if your program were to execute the C subroutine
|
|
|
printf (STRING, EXPRESSIONS...);
|
printf (STRING, EXPRESSIONS...);
|
|
|
For example, you can print two values in hex like this:
|
For example, you can print two values in hex like this:
|
|
|
printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
|
printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
|
|
|
The only backslash-escape sequences that you can use in the format
|
The only backslash-escape sequences that you can use in the format
|
string are the simple ones that consist of backslash followed by a
|
string are the simple ones that consist of backslash followed by a
|
letter.
|
letter.
|
|
|
|
|
File: gdb.info, Node: Emacs, Next: Annotations, Prev: Sequences, Up: Top
|
File: gdb.info, Node: Emacs, Next: Annotations, Prev: Sequences, Up: Top
|
|
|
Using GDB under GNU Emacs
|
Using GDB under GNU Emacs
|
*************************
|
*************************
|
|
|
A special interface allows you to use GNU Emacs to view (and edit)
|
A special interface allows you to use GNU Emacs to view (and edit)
|
the source files for the program you are debugging with GDB.
|
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
|
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
|
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
|
GDB as a subprocess of Emacs, with input and output through a newly
|
created Emacs buffer.
|
created Emacs buffer.
|
|
|
Using GDB under Emacs is just like using GDB normally except for two
|
Using GDB under Emacs is just like using GDB normally except for two
|
things:
|
things:
|
|
|
* All "terminal" input and output goes through the Emacs buffer.
|
* All "terminal" input and output goes through the Emacs buffer.
|
|
|
This applies both to GDB commands and their output, and to the input
|
This applies both to GDB commands and their output, and to the input
|
and output done by the program you are debugging.
|
and output done by the program you are debugging.
|
|
|
This is useful because it means that you can copy the text of
|
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
|
previous commands and input them again; you can even use parts of the
|
output in this way.
|
output in this way.
|
|
|
All the facilities of Emacs' Shell mode are available for interacting
|
All the facilities of Emacs' Shell mode are available for interacting
|
with your program. In particular, you can send signals the usual
|
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.
|
way--for example, `C-c C-c' for an interrupt, `C-c C-z' for a stop.
|
|
|
* GDB displays source code through Emacs.
|
* GDB displays source code through Emacs.
|
|
|
Each time GDB displays a stack frame, Emacs automatically finds the
|
Each time GDB displays a stack frame, Emacs automatically finds the
|
source file for that frame and puts an arrow (`=>') at the left margin
|
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,
|
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.
|
and splits the screen to show both your GDB session and the source.
|
|
|
Explicit GDB `list' or search commands still produce output as
|
Explicit GDB `list' or search commands still produce output as
|
usual, but you probably have no reason to use them from Emacs.
|
usual, but you probably have no reason to use them from Emacs.
|
|
|
_Warning:_ If the directory where your program resides is not your
|
_Warning:_ If the directory where your program resides is not your
|
current directory, it can be easy to confuse Emacs about the
|
current directory, it can be easy to confuse Emacs about the
|
location of the source files, in which case the auxiliary display
|
location of the source files, in which case the auxiliary display
|
buffer does not appear to show your source. GDB can find programs
|
buffer does not appear to show your source. GDB can find programs
|
by searching your environment's `PATH' variable, so the GDB input
|
by searching your environment's `PATH' variable, so the GDB input
|
and output session proceeds normally; but Emacs does not get
|
and output session proceeds normally; but Emacs does not get
|
enough information back from GDB to locate the source files in
|
enough information back from GDB to locate the source files in
|
this situation. To avoid this problem, either start GDB mode from
|
this situation. To avoid this problem, either start GDB mode from
|
the directory where your program resides, or specify an absolute
|
the directory where your program resides, or specify an absolute
|
file name when prompted for the `M-x gdb' argument.
|
file name when prompted for the `M-x gdb' argument.
|
|
|
A similar confusion can result if you use the GDB `file' command to
|
A similar confusion can result if you use the GDB `file' command to
|
switch to debugging a program in some other location, from an
|
switch to debugging a program in some other location, from an
|
existing GDB buffer in Emacs.
|
existing GDB buffer in Emacs.
|
|
|
By default, `M-x gdb' calls the program called `gdb'. If you need
|
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
|
to call GDB by a different name (for example, if you keep several
|
configurations around, with different names) you can set the Emacs
|
configurations around, with different names) you can set the Emacs
|
variable `gdb-command-name'; for example,
|
variable `gdb-command-name'; for example,
|
|
|
(setq gdb-command-name "mygdb")
|
(setq gdb-command-name "mygdb")
|
|
|
(preceded by `M-:' or `ESC :', or typed in the `*scratch*' buffer, or
|
(preceded by `M-:' or `ESC :', or typed in the `*scratch*' buffer, or
|
in your `.emacs' file) makes Emacs call the program named "`mygdb'"
|
in your `.emacs' file) makes Emacs call the program named "`mygdb'"
|
instead.
|
instead.
|
|
|
In the GDB I/O buffer, you can use these special Emacs commands in
|
In the GDB I/O buffer, you can use these special Emacs commands in
|
addition to the standard Shell mode commands:
|
addition to the standard Shell mode commands:
|
|
|
`C-h m'
|
`C-h m'
|
Describe the features of Emacs' GDB Mode.
|
Describe the features of Emacs' GDB Mode.
|
|
|
`M-s'
|
`M-s'
|
Execute to another source line, like the GDB `step' command; also
|
Execute to another source line, like the GDB `step' command; also
|
update the display window to show the current file and location.
|
update the display window to show the current file and location.
|
|
|
`M-n'
|
`M-n'
|
Execute to next source line in this function, skipping all function
|
Execute to next source line in this function, skipping all function
|
calls, like the GDB `next' command. Then update the display window
|
calls, like the GDB `next' command. Then update the display window
|
to show the current file and location.
|
to show the current file and location.
|
|
|
`M-i'
|
`M-i'
|
Execute one instruction, like the GDB `stepi' command; update
|
Execute one instruction, like the GDB `stepi' command; update
|
display window accordingly.
|
display window accordingly.
|
|
|
`M-x gdb-nexti'
|
`M-x gdb-nexti'
|
Execute to next instruction, using the GDB `nexti' command; update
|
Execute to next instruction, using the GDB `nexti' command; update
|
display window accordingly.
|
display window accordingly.
|
|
|
`C-c C-f'
|
`C-c C-f'
|
Execute until exit from the selected stack frame, like the GDB
|
Execute until exit from the selected stack frame, like the GDB
|
`finish' command.
|
`finish' command.
|
|
|
`M-c'
|
`M-c'
|
Continue execution of your program, like the GDB `continue'
|
Continue execution of your program, like the GDB `continue'
|
command.
|
command.
|
|
|
_Warning:_ In Emacs v19, this command is `C-c C-p'.
|
_Warning:_ In Emacs v19, this command is `C-c C-p'.
|
|
|
`M-u'
|
`M-u'
|
Go up the number of frames indicated by the numeric argument
|
Go up the number of frames indicated by the numeric argument
|
(*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up'
|
(*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up'
|
command.
|
command.
|
|
|
_Warning:_ In Emacs v19, this command is `C-c C-u'.
|
_Warning:_ In Emacs v19, this command is `C-c C-u'.
|
|
|
`M-d'
|
`M-d'
|
Go down the number of frames indicated by the numeric argument,
|
Go down the number of frames indicated by the numeric argument,
|
like the GDB `down' command.
|
like the GDB `down' command.
|
|
|
_Warning:_ In Emacs v19, this command is `C-c C-d'.
|
_Warning:_ In Emacs v19, this command is `C-c C-d'.
|
|
|
`C-x &'
|
`C-x &'
|
Read the number where the cursor is positioned, and insert it at
|
Read the number where the cursor is positioned, and insert it at
|
the end of the GDB I/O buffer. For example, if you wish to
|
the end of the GDB I/O buffer. For example, if you wish to
|
disassemble code around an address that was displayed earlier,
|
disassemble code around an address that was displayed earlier,
|
type `disassemble'; then move the cursor to the address display,
|
type `disassemble'; then move the cursor to the address display,
|
and pick up the argument for `disassemble' by typing `C-x &'.
|
and pick up the argument for `disassemble' by typing `C-x &'.
|
|
|
You can customize this further by defining elements of the list
|
You can customize this further by defining elements of the list
|
`gdb-print-command'; once it is defined, you can format or
|
`gdb-print-command'; once it is defined, you can format or
|
otherwise process numbers picked up by `C-x &' before they are
|
otherwise process numbers picked up by `C-x &' before they are
|
inserted. A numeric argument to `C-x &' indicates that you wish
|
inserted. A numeric argument to `C-x &' indicates that you wish
|
special formatting, and also acts as an index to pick an element
|
special formatting, and also acts as an index to pick an element
|
of the list. If the list element is a string, the number to be
|
of the list. If the list element is a string, the number to be
|
inserted is formatted using the Emacs function `format'; otherwise
|
inserted is formatted using the Emacs function `format'; otherwise
|
the number is passed as an argument to the corresponding list
|
the number is passed as an argument to the corresponding list
|
element.
|
element.
|
|
|
In any source file, the Emacs command `C-x SPC' (`gdb-break') tells
|
In any source file, the Emacs command `C-x SPC' (`gdb-break') tells
|
GDB to set a breakpoint on the source line point is on.
|
GDB to set a breakpoint on the source line point is on.
|
|
|
If you accidentally delete the source-display buffer, an easy way to
|
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
|
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
|
frame display; when you run under Emacs, this recreates the source
|
buffer if necessary to show you the context of the current frame.
|
buffer if necessary to show you the context of the current frame.
|
|
|
The source files displayed in Emacs are in ordinary Emacs buffers
|
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
|
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
|
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
|
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
|
lines from the text, the line numbers that GDB knows cease to
|
correspond properly with the code.
|
correspond properly with the code.
|
|
|
|
|
File: gdb.info, Node: Annotations, Next: GDB/MI, Prev: Emacs, Up: Top
|
File: gdb.info, Node: Annotations, Next: GDB/MI, Prev: Emacs, Up: Top
|
|
|
GDB Annotations
|
GDB Annotations
|
***************
|
***************
|
|
|
This chapter describes annotations in GDB. Annotations are designed
|
This chapter describes annotations in GDB. Annotations are designed
|
to interface GDB to graphical user interfaces or other similar programs
|
to interface GDB to graphical user interfaces or other similar programs
|
which want to interact with GDB at a relatively high level.
|
which want to interact with GDB at a relatively high level.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Annotations Overview:: What annotations are; the general syntax.
|
* Annotations Overview:: What annotations are; the general syntax.
|
* Server Prefix:: Issuing a command without affecting user state.
|
* Server Prefix:: Issuing a command without affecting user state.
|
* Value Annotations:: Values are marked as such.
|
* Value Annotations:: Values are marked as such.
|
* Frame Annotations:: Stack frames are annotated.
|
* Frame Annotations:: Stack frames are annotated.
|
* Displays:: GDB can be told to display something periodically.
|
* Displays:: GDB can be told to display something periodically.
|
* Prompting:: Annotations marking GDB's need for input.
|
* Prompting:: Annotations marking GDB's need for input.
|
* Errors:: Annotations for error messages.
|
* Errors:: Annotations for error messages.
|
* Breakpoint Info:: Information on breakpoints.
|
* Breakpoint Info:: Information on breakpoints.
|
* Invalidation:: Some annotations describe things now invalid.
|
* Invalidation:: Some annotations describe things now invalid.
|
* Annotations for Running::
|
* Annotations for Running::
|
Whether the program is running, how it stopped, etc.
|
Whether the program is running, how it stopped, etc.
|
* Source Annotations:: Annotations describing source code.
|
* Source Annotations:: Annotations describing source code.
|
* TODO:: Annotations which might be added in the future.
|
* TODO:: Annotations which might be added in the future.
|
|
|
|
|
File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations
|
File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations
|
|
|
What is an Annotation?
|
What is an Annotation?
|
======================
|
======================
|
|
|
To produce annotations, start GDB with the `--annotate=2' option.
|
To produce annotations, start GDB with the `--annotate=2' option.
|
|
|
Annotations start with a newline character, two `control-z'
|
Annotations start with a newline character, two `control-z'
|
characters, and the name of the annotation. If there is no additional
|
characters, and the name of the annotation. If there is no additional
|
information associated with this annotation, the name of the annotation
|
information associated with this annotation, the name of the annotation
|
is followed immediately by a newline. If there is additional
|
is followed immediately by a newline. If there is additional
|
information, the name of the annotation is followed by a space, the
|
information, the name of the annotation is followed by a space, the
|
additional information, and a newline. The additional information
|
additional information, and a newline. The additional information
|
cannot contain newline characters.
|
cannot contain newline characters.
|
|
|
Any output not beginning with a newline and two `control-z'
|
Any output not beginning with a newline and two `control-z'
|
characters denotes literal output from GDB. Currently there is no need
|
characters denotes literal output from GDB. Currently there is no need
|
for GDB to output a newline followed by two `control-z' characters, but
|
for GDB to output a newline followed by two `control-z' characters, but
|
if there was such a need, the annotations could be extended with an
|
if there was such a need, the annotations could be extended with an
|
`escape' annotation which means those three characters as output.
|
`escape' annotation which means those three characters as output.
|
|
|
A simple example of starting up GDB with annotations is:
|
A simple example of starting up GDB with annotations is:
|
|
|
$ gdb --annotate=2
|
$ gdb --annotate=2
|
GNU GDB 5.0
|
GNU GDB 5.0
|
Copyright 2000 Free Software Foundation, Inc.
|
Copyright 2000 Free Software Foundation, Inc.
|
GDB is free software, covered by the GNU General Public License,
|
GDB is free software, covered by the GNU General Public License,
|
and you are welcome to change it and/or distribute copies of it
|
and you are welcome to change it and/or distribute copies of it
|
under certain conditions.
|
under certain conditions.
|
Type "show copying" to see the conditions.
|
Type "show copying" to see the conditions.
|
There is absolutely no warranty for GDB. Type "show warranty"
|
There is absolutely no warranty for GDB. Type "show warranty"
|
for details.
|
for details.
|
This GDB was configured as "sparc-sun-sunos4.1.3"
|
This GDB was configured as "sparc-sun-sunos4.1.3"
|
|
|
^Z^Zpre-prompt
|
^Z^Zpre-prompt
|
(gdb)
|
(gdb)
|
^Z^Zprompt
|
^Z^Zprompt
|
quit
|
quit
|
|
|
^Z^Zpost-prompt
|
^Z^Zpost-prompt
|
$
|
$
|
|
|
Here `quit' is input to GDB; the rest is output from GDB. The three
|
Here `quit' is input to GDB; the rest is output from GDB. The three
|
lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are
|
lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are
|
annotations; the rest is output from GDB.
|
annotations; the rest is output from GDB.
|
|
|
|
|
File: gdb.info, Node: Server Prefix, Next: Value Annotations, Prev: Annotations Overview, Up: Annotations
|
File: gdb.info, Node: Server Prefix, Next: Value Annotations, Prev: Annotations Overview, Up: Annotations
|
|
|
The Server Prefix
|
The Server Prefix
|
=================
|
=================
|
|
|
To issue a command to GDB without affecting certain aspects of the
|
To issue a command to GDB without affecting certain aspects of the
|
state which is seen by users, prefix it with `server '. This means
|
state which is seen by users, prefix it with `server '. This means
|
that this command will not affect the command history, nor will it
|
that this command will not affect the command history, nor will it
|
affect GDB's notion of which command to repeat if is pressed on a
|
affect GDB's notion of which command to repeat if is pressed on a
|
line by itself.
|
line by itself.
|
|
|
The server prefix does not affect the recording of values into the
|
The server prefix does not affect the recording of values into the
|
value history; to print a value without recording it into the value
|
value history; to print a value without recording it into the value
|
history, use the `output' command instead of the `print' command.
|
history, use the `output' command instead of the `print' command.
|
|
|
|
|
File: gdb.info, Node: Value Annotations, Next: Frame Annotations, Prev: Server Prefix, Up: Annotations
|
File: gdb.info, Node: Value Annotations, Next: Frame Annotations, Prev: Server Prefix, Up: Annotations
|
|
|
Values
|
Values
|
======
|
======
|
|
|
When a value is printed in various contexts, GDB uses annotations to
|
When a value is printed in various contexts, GDB uses annotations to
|
delimit the value from the surrounding text.
|
delimit the value from the surrounding text.
|
|
|
If a value is printed using `print' and added to the value history,
|
If a value is printed using `print' and added to the value history,
|
the annotation looks like
|
the annotation looks like
|
|
|
^Z^Zvalue-history-begin HISTORY-NUMBER VALUE-FLAGS
|
^Z^Zvalue-history-begin HISTORY-NUMBER VALUE-FLAGS
|
HISTORY-STRING
|
HISTORY-STRING
|
^Z^Zvalue-history-value
|
^Z^Zvalue-history-value
|
THE-VALUE
|
THE-VALUE
|
^Z^Zvalue-history-end
|
^Z^Zvalue-history-end
|
|
|
where HISTORY-NUMBER is the number it is getting in the value history,
|
where HISTORY-NUMBER is the number it is getting in the value history,
|
HISTORY-STRING is a string, such as `$5 = ', which introduces the value
|
HISTORY-STRING is a string, such as `$5 = ', which introduces the value
|
to the user, THE-VALUE is the output corresponding to the value itself,
|
to the user, THE-VALUE is the output corresponding to the value itself,
|
and VALUE-FLAGS is `*' for a value which can be dereferenced and `-'
|
and VALUE-FLAGS is `*' for a value which can be dereferenced and `-'
|
for a value which cannot.
|
for a value which cannot.
|
|
|
If the value is not added to the value history (it is an invalid
|
If the value is not added to the value history (it is an invalid
|
float or it is printed with the `output' command), the annotation is
|
float or it is printed with the `output' command), the annotation is
|
similar:
|
similar:
|
|
|
^Z^Zvalue-begin VALUE-FLAGS
|
^Z^Zvalue-begin VALUE-FLAGS
|
THE-VALUE
|
THE-VALUE
|
^Z^Zvalue-end
|
^Z^Zvalue-end
|
|
|
When GDB prints an argument to a function (for example, in the output
|
When GDB prints an argument to a function (for example, in the output
|
from the `backtrace' command), it annotates it as follows:
|
from the `backtrace' command), it annotates it as follows:
|
|
|
^Z^Zarg-begin
|
^Z^Zarg-begin
|
ARGUMENT-NAME
|
ARGUMENT-NAME
|
^Z^Zarg-name-end
|
^Z^Zarg-name-end
|
SEPARATOR-STRING
|
SEPARATOR-STRING
|
^Z^Zarg-value VALUE-FLAGS
|
^Z^Zarg-value VALUE-FLAGS
|
THE-VALUE
|
THE-VALUE
|
^Z^Zarg-end
|
^Z^Zarg-end
|
|
|
where ARGUMENT-NAME is the name of the argument, SEPARATOR-STRING is
|
where ARGUMENT-NAME is the name of the argument, SEPARATOR-STRING is
|
text which separates the name from the value for the user's benefit
|
text which separates the name from the value for the user's benefit
|
(such as `='), and VALUE-FLAGS and THE-VALUE have the same meanings as
|
(such as `='), and VALUE-FLAGS and THE-VALUE have the same meanings as
|
in a `value-history-begin' annotation.
|
in a `value-history-begin' annotation.
|
|
|
When printing a structure, GDB annotates it as follows:
|
When printing a structure, GDB annotates it as follows:
|
|
|
^Z^Zfield-begin VALUE-FLAGS
|
^Z^Zfield-begin VALUE-FLAGS
|
FIELD-NAME
|
FIELD-NAME
|
^Z^Zfield-name-end
|
^Z^Zfield-name-end
|
SEPARATOR-STRING
|
SEPARATOR-STRING
|
^Z^Zfield-value
|
^Z^Zfield-value
|
THE-VALUE
|
THE-VALUE
|
^Z^Zfield-end
|
^Z^Zfield-end
|
|
|
where FIELD-NAME is the name of the field, SEPARATOR-STRING is text
|
where FIELD-NAME is the name of the field, SEPARATOR-STRING is text
|
which separates the name from the value for the user's benefit (such as
|
which separates the name from the value for the user's benefit (such as
|
`='), and VALUE-FLAGS and THE-VALUE have the same meanings as in a
|
`='), and VALUE-FLAGS and THE-VALUE have the same meanings as in a
|
`value-history-begin' annotation.
|
`value-history-begin' annotation.
|
|
|
When printing an array, GDB annotates it as follows:
|
When printing an array, GDB annotates it as follows:
|
|
|
^Z^Zarray-section-begin ARRAY-INDEX VALUE-FLAGS
|
^Z^Zarray-section-begin ARRAY-INDEX VALUE-FLAGS
|
|
|
where ARRAY-INDEX is the index of the first element being annotated and
|
where ARRAY-INDEX is the index of the first element being annotated and
|
VALUE-FLAGS has the same meaning as in a `value-history-begin'
|
VALUE-FLAGS has the same meaning as in a `value-history-begin'
|
annotation. This is followed by any number of elements, where is
|
annotation. This is followed by any number of elements, where is
|
element can be either a single element:
|
element can be either a single element:
|
|
|
`,' WHITESPACE ; omitted for the first element
|
`,' WHITESPACE ; omitted for the first element
|
THE-VALUE
|
THE-VALUE
|
^Z^Zelt
|
^Z^Zelt
|
|
|
or a repeated element
|
or a repeated element
|
|
|
`,' WHITESPACE ; omitted for the first element
|
`,' WHITESPACE ; omitted for the first element
|
THE-VALUE
|
THE-VALUE
|
^Z^Zelt-rep NUMBER-OF-REPITITIONS
|
^Z^Zelt-rep NUMBER-OF-REPITITIONS
|
REPETITION-STRING
|
REPETITION-STRING
|
^Z^Zelt-rep-end
|
^Z^Zelt-rep-end
|
|
|
In both cases, THE-VALUE is the output for the value of the element
|
In both cases, THE-VALUE is the output for the value of the element
|
and WHITESPACE can contain spaces, tabs, and newlines. In the repeated
|
and WHITESPACE can contain spaces, tabs, and newlines. In the repeated
|
case, NUMBER-OF-REPITITONS is the number of consecutive array elements
|
case, NUMBER-OF-REPITITONS is the number of consecutive array elements
|
which contain that value, and REPETITION-STRING is a string which is
|
which contain that value, and REPETITION-STRING is a string which is
|
designed to convey to the user that repitition is being depicted.
|
designed to convey to the user that repitition is being depicted.
|
|
|
Once all the array elements have been output, the array annotation is
|
Once all the array elements have been output, the array annotation is
|
ended with
|
ended with
|
|
|
^Z^Zarray-section-end
|
^Z^Zarray-section-end
|
|
|
|
|
File: gdb.info, Node: Frame Annotations, Next: Displays, Prev: Value Annotations, Up: Annotations
|
File: gdb.info, Node: Frame Annotations, Next: Displays, Prev: Value Annotations, Up: Annotations
|
|
|
Frames
|
Frames
|
======
|
======
|
|
|
Whenever GDB prints a frame, it annotates it. For example, this
|
Whenever GDB prints a frame, it annotates it. For example, this
|
applies to frames printed when GDB stops, output from commands such as
|
applies to frames printed when GDB stops, output from commands such as
|
`backtrace' or `up', etc.
|
`backtrace' or `up', etc.
|
|
|
The frame annotation begins with
|
The frame annotation begins with
|
|
|
^Z^Zframe-begin LEVEL ADDRESS
|
^Z^Zframe-begin LEVEL ADDRESS
|
LEVEL-STRING
|
LEVEL-STRING
|
|
|
where LEVEL is the number of the frame (0 is the innermost frame, and
|
where LEVEL is the number of the frame (0 is the innermost frame, and
|
other frames have positive numbers), ADDRESS is the address of the code
|
other frames have positive numbers), ADDRESS is the address of the code
|
executing in that frame, and LEVEL-STRING is a string designed to
|
executing in that frame, and LEVEL-STRING is a string designed to
|
convey the level to the user. ADDRESS is in the form `0x' followed by
|
convey the level to the user. ADDRESS is in the form `0x' followed by
|
one or more lowercase hex digits (note that this does not depend on the
|
one or more lowercase hex digits (note that this does not depend on the
|
language). The frame ends with
|
language). The frame ends with
|
|
|
^Z^Zframe-end
|
^Z^Zframe-end
|
|
|
Between these annotations is the main body of the frame, which can
|
Between these annotations is the main body of the frame, which can
|
consist of
|
consist of
|
|
|
* ^Z^Zfunction-call
|
* ^Z^Zfunction-call
|
FUNCTION-CALL-STRING
|
FUNCTION-CALL-STRING
|
|
|
where FUNCTION-CALL-STRING is text designed to convey to the user
|
where FUNCTION-CALL-STRING is text designed to convey to the user
|
that this frame is associated with a function call made by GDB to a
|
that this frame is associated with a function call made by GDB to a
|
function in the program being debugged.
|
function in the program being debugged.
|
|
|
* ^Z^Zsignal-handler-caller
|
* ^Z^Zsignal-handler-caller
|
SIGNAL-HANDLER-CALLER-STRING
|
SIGNAL-HANDLER-CALLER-STRING
|
|
|
where SIGNAL-HANDLER-CALLER-STRING is text designed to convey to
|
where SIGNAL-HANDLER-CALLER-STRING is text designed to convey to
|
the user that this frame is associated with whatever mechanism is
|
the user that this frame is associated with whatever mechanism is
|
used by this operating system to call a signal handler (it is the
|
used by this operating system to call a signal handler (it is the
|
frame which calls the signal handler, not the frame for the signal
|
frame which calls the signal handler, not the frame for the signal
|
handler itself).
|
handler itself).
|
|
|
* A normal frame.
|
* A normal frame.
|
|
|
This can optionally (depending on whether this is thought of as
|
This can optionally (depending on whether this is thought of as
|
interesting information for the user to see) begin with
|
interesting information for the user to see) begin with
|
|
|
^Z^Zframe-address
|
^Z^Zframe-address
|
ADDRESS
|
ADDRESS
|
^Z^Zframe-address-end
|
^Z^Zframe-address-end
|
SEPARATOR-STRING
|
SEPARATOR-STRING
|
|
|
where ADDRESS is the address executing in the frame (the same
|
where ADDRESS is the address executing in the frame (the same
|
address as in the `frame-begin' annotation, but printed in a form
|
address as in the `frame-begin' annotation, but printed in a form
|
which is intended for user consumption--in particular, the syntax
|
which is intended for user consumption--in particular, the syntax
|
varies depending on the language), and SEPARATOR-STRING is a string
|
varies depending on the language), and SEPARATOR-STRING is a string
|
intended to separate this address from what follows for the user's
|
intended to separate this address from what follows for the user's
|
benefit.
|
benefit.
|
|
|
Then comes
|
Then comes
|
|
|
^Z^Zframe-function-name
|
^Z^Zframe-function-name
|
FUNCTION-NAME
|
FUNCTION-NAME
|
^Z^Zframe-args
|
^Z^Zframe-args
|
ARGUMENTS
|
ARGUMENTS
|
|
|
where FUNCTION-NAME is the name of the function executing in the
|
where FUNCTION-NAME is the name of the function executing in the
|
frame, or `??' if not known, and ARGUMENTS are the arguments to
|
frame, or `??' if not known, and ARGUMENTS are the arguments to
|
the frame, with parentheses around them (each argument is annotated
|
the frame, with parentheses around them (each argument is annotated
|
individually as well, *note Value Annotations::).
|
individually as well, *note Value Annotations::).
|
|
|
If source information is available, a reference to it is then
|
If source information is available, a reference to it is then
|
printed:
|
printed:
|
|
|
^Z^Zframe-source-begin
|
^Z^Zframe-source-begin
|
SOURCE-INTRO-STRING
|
SOURCE-INTRO-STRING
|
^Z^Zframe-source-file
|
^Z^Zframe-source-file
|
FILENAME
|
FILENAME
|
^Z^Zframe-source-file-end
|
^Z^Zframe-source-file-end
|
:
|
:
|
^Z^Zframe-source-line
|
^Z^Zframe-source-line
|
LINE-NUMBER
|
LINE-NUMBER
|
^Z^Zframe-source-end
|
^Z^Zframe-source-end
|
|
|
where SOURCE-INTRO-STRING separates for the user's benefit the
|
where SOURCE-INTRO-STRING separates for the user's benefit the
|
reference from the text which precedes it, FILENAME is the name of
|
reference from the text which precedes it, FILENAME is the name of
|
the source file, and LINE-NUMBER is the line number within that
|
the source file, and LINE-NUMBER is the line number within that
|
file (the first line is line 1).
|
file (the first line is line 1).
|
|
|
If GDB prints some information about where the frame is from (which
|
If GDB prints some information about where the frame is from (which
|
library, which load segment, etc.; currently only done on the
|
library, which load segment, etc.; currently only done on the
|
RS/6000), it is annotated with
|
RS/6000), it is annotated with
|
|
|
^Z^Zframe-where
|
^Z^Zframe-where
|
INFORMATION
|
INFORMATION
|
|
|
Then, if source is to actually be displayed for this frame (for
|
Then, if source is to actually be displayed for this frame (for
|
example, this is not true for output from the `backtrace'
|
example, this is not true for output from the `backtrace'
|
command), then a `source' annotation (*note Source Annotations::)
|
command), then a `source' annotation (*note Source Annotations::)
|
is displayed. Unlike most annotations, this is output instead of
|
is displayed. Unlike most annotations, this is output instead of
|
the normal text which would be output, not in addition.
|
the normal text which would be output, not in addition.
|
|
|
|
|
File: gdb.info, Node: Displays, Next: Prompting, Prev: Frame Annotations, Up: Annotations
|
File: gdb.info, Node: Displays, Next: Prompting, Prev: Frame Annotations, Up: Annotations
|
|
|
Displays
|
Displays
|
========
|
========
|
|
|
When GDB is told to display something using the `display' command,
|
When GDB is told to display something using the `display' command,
|
the results of the display are annotated:
|
the results of the display are annotated:
|
|
|
^Z^Zdisplay-begin
|
^Z^Zdisplay-begin
|
NUMBER
|
NUMBER
|
^Z^Zdisplay-number-end
|
^Z^Zdisplay-number-end
|
NUMBER-SEPARATOR
|
NUMBER-SEPARATOR
|
^Z^Zdisplay-format
|
^Z^Zdisplay-format
|
FORMAT
|
FORMAT
|
^Z^Zdisplay-expression
|
^Z^Zdisplay-expression
|
EXPRESSION
|
EXPRESSION
|
^Z^Zdisplay-expression-end
|
^Z^Zdisplay-expression-end
|
EXPRESSION-SEPARATOR
|
EXPRESSION-SEPARATOR
|
^Z^Zdisplay-value
|
^Z^Zdisplay-value
|
VALUE
|
VALUE
|
^Z^Zdisplay-end
|
^Z^Zdisplay-end
|
|
|
where NUMBER is the number of the display, NUMBER-SEPARATOR is intended
|
where NUMBER is the number of the display, NUMBER-SEPARATOR is intended
|
to separate the number from what follows for the user, FORMAT includes
|
to separate the number from what follows for the user, FORMAT includes
|
information such as the size, format, or other information about how
|
information such as the size, format, or other information about how
|
the value is being displayed, EXPRESSION is the expression being
|
the value is being displayed, EXPRESSION is the expression being
|
displayed, EXPRESSION-SEPARATOR is intended to separate the expression
|
displayed, EXPRESSION-SEPARATOR is intended to separate the expression
|
from the text that follows for the user, and VALUE is the actual value
|
from the text that follows for the user, and VALUE is the actual value
|
being displayed.
|
being displayed.
|
|
|
|
|
File: gdb.info, Node: Prompting, Next: Errors, Prev: Displays, Up: Annotations
|
File: gdb.info, Node: Prompting, Next: Errors, Prev: Displays, Up: Annotations
|
|
|
Annotation for GDB Input
|
Annotation for GDB Input
|
========================
|
========================
|
|
|
When GDB prompts for input, it annotates this fact so it is possible
|
When GDB prompts for input, it annotates this fact so it is possible
|
to know when to send output, when the output from a given command is
|
to know when to send output, when the output from a given command is
|
over, etc.
|
over, etc.
|
|
|
Different kinds of input each have a different "input type". Each
|
Different kinds of input each have a different "input type". Each
|
input type has three annotations: a `pre-' annotation, which denotes
|
input type has three annotations: a `pre-' annotation, which denotes
|
the beginning of any prompt which is being output, a plain annotation,
|
the beginning of any prompt which is being output, a plain annotation,
|
which denotes the end of the prompt, and then a `post-' annotation
|
which denotes the end of the prompt, and then a `post-' annotation
|
which denotes the end of any echo which may (or may not) be associated
|
which denotes the end of any echo which may (or may not) be associated
|
with the input. For example, the `prompt' input type features the
|
with the input. For example, the `prompt' input type features the
|
following annotations:
|
following annotations:
|
|
|
^Z^Zpre-prompt
|
^Z^Zpre-prompt
|
^Z^Zprompt
|
^Z^Zprompt
|
^Z^Zpost-prompt
|
^Z^Zpost-prompt
|
|
|
The input types are
|
The input types are
|
|
|
`prompt'
|
`prompt'
|
When GDB is prompting for a command (the main GDB prompt).
|
When GDB is prompting for a command (the main GDB prompt).
|
|
|
`commands'
|
`commands'
|
When GDB prompts for a set of commands, like in the `commands'
|
When GDB prompts for a set of commands, like in the `commands'
|
command. The annotations are repeated for each command which is
|
command. The annotations are repeated for each command which is
|
input.
|
input.
|
|
|
`overload-choice'
|
`overload-choice'
|
When GDB wants the user to select between various overloaded
|
When GDB wants the user to select between various overloaded
|
functions.
|
functions.
|
|
|
`query'
|
`query'
|
When GDB wants the user to confirm a potentially dangerous
|
When GDB wants the user to confirm a potentially dangerous
|
operation.
|
operation.
|
|
|
`prompt-for-continue'
|
`prompt-for-continue'
|
When GDB is asking the user to press return to continue. Note:
|
When GDB is asking the user to press return to continue. Note:
|
Don't expect this to work well; instead use `set height 0' to
|
Don't expect this to work well; instead use `set height 0' to
|
disable prompting. This is because the counting of lines is buggy
|
disable prompting. This is because the counting of lines is buggy
|
in the presence of annotations.
|
in the presence of annotations.
|
|
|
|
|
File: gdb.info, Node: Errors, Next: Breakpoint Info, Prev: Prompting, Up: Annotations
|
File: gdb.info, Node: Errors, Next: Breakpoint Info, Prev: Prompting, Up: Annotations
|
|
|
Errors
|
Errors
|
======
|
======
|
|
|
^Z^Zquit
|
^Z^Zquit
|
|
|
This annotation occurs right before GDB responds to an interrupt.
|
This annotation occurs right before GDB responds to an interrupt.
|
|
|
^Z^Zerror
|
^Z^Zerror
|
|
|
This annotation occurs right before GDB responds to an error.
|
This annotation occurs right before GDB responds to an error.
|
|
|
Quit and error annotations indicate that any annotations which GDB
|
Quit and error annotations indicate that any annotations which GDB
|
was in the middle of may end abruptly. For example, if a
|
was in the middle of may end abruptly. For example, if a
|
`value-history-begin' annotation is followed by a `error', one cannot
|
`value-history-begin' annotation is followed by a `error', one cannot
|
expect to receive the matching `value-history-end'. One cannot expect
|
expect to receive the matching `value-history-end'. One cannot expect
|
not to receive it either, however; an error annotation does not
|
not to receive it either, however; an error annotation does not
|
necessarily mean that GDB is immediately returning all the way to the
|
necessarily mean that GDB is immediately returning all the way to the
|
top level.
|
top level.
|
|
|
A quit or error annotation may be preceded by
|
A quit or error annotation may be preceded by
|
|
|
^Z^Zerror-begin
|
^Z^Zerror-begin
|
|
|
Any output between that and the quit or error annotation is the error
|
Any output between that and the quit or error annotation is the error
|
message.
|
message.
|
|
|
Warning messages are not yet annotated.
|
Warning messages are not yet annotated.
|
|
|
|
|
File: gdb.info, Node: Breakpoint Info, Next: Invalidation, Prev: Errors, Up: Annotations
|
File: gdb.info, Node: Breakpoint Info, Next: Invalidation, Prev: Errors, Up: Annotations
|
|
|
Information on Breakpoints
|
Information on Breakpoints
|
==========================
|
==========================
|
|
|
The output from the `info breakpoints' command is annotated as
|
The output from the `info breakpoints' command is annotated as
|
follows:
|
follows:
|
|
|
^Z^Zbreakpoints-headers
|
^Z^Zbreakpoints-headers
|
HEADER-ENTRY
|
HEADER-ENTRY
|
^Z^Zbreakpoints-table
|
^Z^Zbreakpoints-table
|
|
|
where HEADER-ENTRY has the same syntax as an entry (see below) but
|
where HEADER-ENTRY has the same syntax as an entry (see below) but
|
instead of containing data, it contains strings which are intended to
|
instead of containing data, it contains strings which are intended to
|
convey the meaning of each field to the user. This is followed by any
|
convey the meaning of each field to the user. This is followed by any
|
number of entries. If a field does not apply for this entry, it is
|
number of entries. If a field does not apply for this entry, it is
|
omitted. Fields may contain trailing whitespace. Each entry consists
|
omitted. Fields may contain trailing whitespace. Each entry consists
|
of:
|
of:
|
|
|
^Z^Zrecord
|
^Z^Zrecord
|
^Z^Zfield 0
|
^Z^Zfield 0
|
NUMBER
|
NUMBER
|
^Z^Zfield 1
|
^Z^Zfield 1
|
TYPE
|
TYPE
|
^Z^Zfield 2
|
^Z^Zfield 2
|
DISPOSITION
|
DISPOSITION
|
^Z^Zfield 3
|
^Z^Zfield 3
|
ENABLE
|
ENABLE
|
^Z^Zfield 4
|
^Z^Zfield 4
|
ADDRESS
|
ADDRESS
|
^Z^Zfield 5
|
^Z^Zfield 5
|
WHAT
|
WHAT
|
^Z^Zfield 6
|
^Z^Zfield 6
|
FRAME
|
FRAME
|
^Z^Zfield 7
|
^Z^Zfield 7
|
CONDITION
|
CONDITION
|
^Z^Zfield 8
|
^Z^Zfield 8
|
IGNORE-COUNT
|
IGNORE-COUNT
|
^Z^Zfield 9
|
^Z^Zfield 9
|
COMMANDS
|
COMMANDS
|
|
|
Note that ADDRESS is intended for user consumption--the syntax
|
Note that ADDRESS is intended for user consumption--the syntax
|
varies depending on the language.
|
varies depending on the language.
|
|
|
The output ends with
|
The output ends with
|
|
|
^Z^Zbreakpoints-table-end
|
^Z^Zbreakpoints-table-end
|
|
|
|
|
File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Breakpoint Info, Up: Annotations
|
File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Breakpoint Info, Up: Annotations
|
|
|
Invalidation Notices
|
Invalidation Notices
|
====================
|
====================
|
|
|
The following annotations say that certain pieces of state may have
|
The following annotations say that certain pieces of state may have
|
changed.
|
changed.
|
|
|
`^Z^Zframes-invalid'
|
`^Z^Zframes-invalid'
|
The frames (for example, output from the `backtrace' command) may
|
The frames (for example, output from the `backtrace' command) may
|
have changed.
|
have changed.
|
|
|
`^Z^Zbreakpoints-invalid'
|
`^Z^Zbreakpoints-invalid'
|
The breakpoints may have changed. For example, the user just
|
The breakpoints may have changed. For example, the user just
|
added or deleted a breakpoint.
|
added or deleted a breakpoint.
|
|
|
|
|
File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations
|
File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations
|
|
|
Running the Program
|
Running the Program
|
===================
|
===================
|
|
|
When the program starts executing due to a GDB command such as
|
When the program starts executing due to a GDB command such as
|
`step' or `continue',
|
`step' or `continue',
|
|
|
^Z^Zstarting
|
^Z^Zstarting
|
|
|
is output. When the program stops,
|
is output. When the program stops,
|
|
|
^Z^Zstopped
|
^Z^Zstopped
|
|
|
is output. Before the `stopped' annotation, a variety of
|
is output. Before the `stopped' annotation, a variety of
|
annotations describe how the program stopped.
|
annotations describe how the program stopped.
|
|
|
`^Z^Zexited EXIT-STATUS'
|
`^Z^Zexited EXIT-STATUS'
|
The program exited, and EXIT-STATUS is the exit status (zero for
|
The program exited, and EXIT-STATUS is the exit status (zero for
|
successful exit, otherwise nonzero).
|
successful exit, otherwise nonzero).
|
|
|
`^Z^Zsignalled'
|
`^Z^Zsignalled'
|
The program exited with a signal. After the `^Z^Zsignalled', the
|
The program exited with a signal. After the `^Z^Zsignalled', the
|
annotation continues:
|
annotation continues:
|
|
|
INTRO-TEXT
|
INTRO-TEXT
|
^Z^Zsignal-name
|
^Z^Zsignal-name
|
NAME
|
NAME
|
^Z^Zsignal-name-end
|
^Z^Zsignal-name-end
|
MIDDLE-TEXT
|
MIDDLE-TEXT
|
^Z^Zsignal-string
|
^Z^Zsignal-string
|
STRING
|
STRING
|
^Z^Zsignal-string-end
|
^Z^Zsignal-string-end
|
END-TEXT
|
END-TEXT
|
|
|
where NAME is the name of the signal, such as `SIGILL' or
|
where NAME is the name of the signal, such as `SIGILL' or
|
`SIGSEGV', and STRING is the explanation of the signal, such as
|
`SIGSEGV', and STRING is the explanation of the signal, such as
|
`Illegal Instruction' or `Segmentation fault'. INTRO-TEXT,
|
`Illegal Instruction' or `Segmentation fault'. INTRO-TEXT,
|
MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
|
MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
|
particular format.
|
particular format.
|
|
|
`^Z^Zsignal'
|
`^Z^Zsignal'
|
The syntax of this annotation is just like `signalled', but GDB is
|
The syntax of this annotation is just like `signalled', but GDB is
|
just saying that the program received the signal, not that it was
|
just saying that the program received the signal, not that it was
|
terminated with it.
|
terminated with it.
|
|
|
`^Z^Zbreakpoint NUMBER'
|
`^Z^Zbreakpoint NUMBER'
|
The program hit breakpoint number NUMBER.
|
The program hit breakpoint number NUMBER.
|
|
|
`^Z^Zwatchpoint NUMBER'
|
`^Z^Zwatchpoint NUMBER'
|
The program hit watchpoint number NUMBER.
|
The program hit watchpoint number NUMBER.
|
|
|
|
|
File: gdb.info, Node: Source Annotations, Next: TODO, Prev: Annotations for Running, Up: Annotations
|
File: gdb.info, Node: Source Annotations, Next: TODO, Prev: Annotations for Running, Up: Annotations
|
|
|
Displaying Source
|
Displaying Source
|
=================
|
=================
|
|
|
The following annotation is used instead of displaying source code:
|
The following annotation is used instead of displaying source code:
|
|
|
^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
|
^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
|
|
|
where FILENAME is an absolute file name indicating which source
|
where FILENAME is an absolute file name indicating which source
|
file, LINE is the line number within that file (where 1 is the first
|
file, LINE is the line number within that file (where 1 is the first
|
line in the file), CHARACTER is the character position within the file
|
line in the file), CHARACTER is the character position within the file
|
(where 0 is the first character in the file) (for most debug formats
|
(where 0 is the first character in the file) (for most debug formats
|
this will necessarily point to the beginning of a line), MIDDLE is
|
this will necessarily point to the beginning of a line), MIDDLE is
|
`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at
|
`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at
|
the beginning of the line, and ADDR is the address in the target
|
the beginning of the line, and ADDR is the address in the target
|
program associated with the source which is being displayed. ADDR is
|
program associated with the source which is being displayed. ADDR is
|
in the form `0x' followed by one or more lowercase hex digits (note
|
in the form `0x' followed by one or more lowercase hex digits (note
|
that this does not depend on the language).
|
that this does not depend on the language).
|
|
|
|
|
File: gdb.info, Node: TODO, Prev: Source Annotations, Up: Annotations
|
File: gdb.info, Node: TODO, Prev: Source Annotations, Up: Annotations
|
|
|
Annotations We Might Want in the Future
|
Annotations We Might Want in the Future
|
=======================================
|
=======================================
|
|
|
- target-invalid
|
- target-invalid
|
the target might have changed (registers, heap contents, or
|
the target might have changed (registers, heap contents, or
|
execution status). For performance, we might eventually want
|
execution status). For performance, we might eventually want
|
to hit `registers-invalid' and `all-registers-invalid' with
|
to hit `registers-invalid' and `all-registers-invalid' with
|
greater precision
|
greater precision
|
|
|
- systematic annotation for set/show parameters (including
|
- systematic annotation for set/show parameters (including
|
invalidation notices).
|
invalidation notices).
|
|
|
- similarly, `info' returns a list of candidates for invalidation
|
- similarly, `info' returns a list of candidates for invalidation
|
notices.
|
notices.
|
|
|
|
|
File: gdb.info, Node: GDB/MI, Next: GDB Bugs, Prev: Annotations, Up: Top
|
File: gdb.info, Node: GDB/MI, Next: GDB Bugs, Prev: Annotations, Up: Top
|
|
|
The GDB/MI Interface
|
The GDB/MI Interface
|
********************
|
********************
|
|
|
Function and Purpose
|
Function and Purpose
|
====================
|
====================
|
|
|
GDB/MI is a line based machine oriented text interface to GDB. It is
|
GDB/MI is a line based machine oriented text interface to GDB. It is
|
specifically intended to support the development of systems which use
|
specifically intended to support the development of systems which use
|
the debugger as just one small component of a larger system.
|
the debugger as just one small component of a larger system.
|
|
|
This chapter is a specification of the GDB/MI interface. It is
|
This chapter is a specification of the GDB/MI interface. It is
|
written in the form of a reference manual.
|
written in the form of a reference manual.
|
|
|
Note that GDB/MI is still under construction, so some of the
|
Note that GDB/MI is still under construction, so some of the
|
features described below are incomplete and subject to change.
|
features described below are incomplete and subject to change.
|
|
|
Notation and Terminology
|
Notation and Terminology
|
========================
|
========================
|
|
|
This chapter uses the following notation:
|
This chapter uses the following notation:
|
|
|
* `|' separates two alternatives.
|
* `|' separates two alternatives.
|
|
|
* `[ SOMETHING ]' indicates that SOMETHING is optional: it may or
|
* `[ SOMETHING ]' indicates that SOMETHING is optional: it may or
|
may not be given.
|
may not be given.
|
|
|
* `( GROUP )*' means that GROUP inside the parentheses may repeat
|
* `( GROUP )*' means that GROUP inside the parentheses may repeat
|
zero or more times.
|
zero or more times.
|
|
|
* `( GROUP )+' means that GROUP inside the parentheses may repeat
|
* `( GROUP )+' means that GROUP inside the parentheses may repeat
|
one or more times.
|
one or more times.
|
|
|
* `"STRING"' means a literal STRING.
|
* `"STRING"' means a literal STRING.
|
|
|
Acknowledgments
|
Acknowledgments
|
===============
|
===============
|
|
|
In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
|
In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
|
Elena Zannoni.
|
Elena Zannoni.
|
|
|
* Menu:
|
* Menu:
|
|
|
* GDB/MI Command Syntax::
|
* GDB/MI Command Syntax::
|
* GDB/MI Compatibility with CLI::
|
* GDB/MI Compatibility with CLI::
|
* GDB/MI Output Records::
|
* GDB/MI Output Records::
|
* GDB/MI Command Description Format::
|
* GDB/MI Command Description Format::
|
* GDB/MI Breakpoint Table Commands::
|
* GDB/MI Breakpoint Table Commands::
|
* GDB/MI Data Manipulation::
|
* GDB/MI Data Manipulation::
|
* GDB/MI Program Control::
|
* GDB/MI Program Control::
|
* GDB/MI Miscellaneous Commands::
|
* GDB/MI Miscellaneous Commands::
|
* GDB/MI Stack Manipulation::
|
* GDB/MI Stack Manipulation::
|
* GDB/MI Symbol Query::
|
* GDB/MI Symbol Query::
|
* GDB/MI Target Manipulation::
|
* GDB/MI Target Manipulation::
|
* GDB/MI Thread Commands::
|
* GDB/MI Thread Commands::
|
* GDB/MI Tracepoint Commands::
|
* GDB/MI Tracepoint Commands::
|
* GDB/MI Variable Objects::
|
* GDB/MI Variable Objects::
|
|
|
|
|
File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Up: GDB/MI
|
|
|
GDB/MI Command Syntax
|
GDB/MI Command Syntax
|
=====================
|
=====================
|
|
|
* Menu:
|
* Menu:
|
|
|
* GDB/MI Input Syntax::
|
* GDB/MI Input Syntax::
|
* GDB/MI Output Syntax::
|
* GDB/MI Output Syntax::
|
* GDB/MI Simple Examples::
|
* GDB/MI Simple Examples::
|
|
|
|
|
File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax
|
File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax
|
|
|
GDB/MI Input Syntax
|
GDB/MI Input Syntax
|
-------------------
|
-------------------
|
|
|
`COMMAND ==>'
|
`COMMAND ==>'
|
`CLI-COMMAND | MI-COMMAND'
|
`CLI-COMMAND | MI-COMMAND'
|
|
|
`CLI-COMMAND ==>'
|
`CLI-COMMAND ==>'
|
`[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB
|
`[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB
|
CLI command.
|
CLI command.
|
|
|
`MI-COMMAND ==>'
|
`MI-COMMAND ==>'
|
`[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " "
|
`[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " "
|
PARAMETER )* NL'
|
PARAMETER )* NL'
|
|
|
`TOKEN ==>'
|
`TOKEN ==>'
|
"any sequence of digits"
|
"any sequence of digits"
|
|
|
`OPTION ==>'
|
`OPTION ==>'
|
`"-" PARAMETER [ " " PARAMETER ]'
|
`"-" PARAMETER [ " " PARAMETER ]'
|
|
|
`PARAMETER ==>'
|
`PARAMETER ==>'
|
`NON-BLANK-SEQUENCE | C-STRING'
|
`NON-BLANK-SEQUENCE | C-STRING'
|
|
|
`OPERATION ==>'
|
`OPERATION ==>'
|
_any of the operations described in this chapter_
|
_any of the operations described in this chapter_
|
|
|
`NON-BLANK-SEQUENCE ==>'
|
`NON-BLANK-SEQUENCE ==>'
|
_anything, provided it doesn't contain special characters such as
|
_anything, provided it doesn't contain special characters such as
|
"-", NL, """ and of course " "_
|
"-", NL, """ and of course " "_
|
|
|
`C-STRING ==>'
|
`C-STRING ==>'
|
`""" SEVEN-BIT-ISO-C-STRING-CONTENT """'
|
`""" SEVEN-BIT-ISO-C-STRING-CONTENT """'
|
|
|
`NL ==>'
|
`NL ==>'
|
`CR | CR-LF'
|
`CR | CR-LF'
|
|
|
Notes:
|
Notes:
|
|
|
* The CLI commands are still handled by the MI interpreter; their
|
* The CLI commands are still handled by the MI interpreter; their
|
output is described below.
|
output is described below.
|
|
|
* The `TOKEN', when present, is passed back when the command
|
* The `TOKEN', when present, is passed back when the command
|
finishes.
|
finishes.
|
|
|
* Some MI commands accept optional arguments as part of the parameter
|
* Some MI commands accept optional arguments as part of the parameter
|
list. Each option is identified by a leading `-' (dash) and may be
|
list. Each option is identified by a leading `-' (dash) and may be
|
followed by an optional argument parameter. Options occur first
|
followed by an optional argument parameter. Options occur first
|
in the parameter list and can be delimited from normal parameters
|
in the parameter list and can be delimited from normal parameters
|
using `--' (this is useful when some parameters begin with a dash).
|
using `--' (this is useful when some parameters begin with a dash).
|
|
|
Pragmatics:
|
Pragmatics:
|
|
|
* We want easy access to the existing CLI syntax (for debugging).
|
* We want easy access to the existing CLI syntax (for debugging).
|
|
|
* We want it to be easy to spot a MI operation.
|
* We want it to be easy to spot a MI operation.
|
|
|
|
|
File: gdb.info, Node: GDB/MI Output Syntax, Next: GDB/MI Simple Examples, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax
|
File: gdb.info, Node: GDB/MI Output Syntax, Next: GDB/MI Simple Examples, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax
|
|
|
GDB/MI Output Syntax
|
GDB/MI Output Syntax
|
--------------------
|
--------------------
|
|
|
The output from GDB/MI consists of zero or more out-of-band records
|
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
|
followed, optionally, by a single result record. This result record is
|
for the most recent command. The sequence of output records is
|
for the most recent command. The sequence of output records is
|
terminated by `(gdb)'.
|
terminated by `(gdb)'.
|
|
|
If an input command was prefixed with a `TOKEN' then the
|
If an input command was prefixed with a `TOKEN' then the
|
corresponding output for that command will also be prefixed by that same
|
corresponding output for that command will also be prefixed by that same
|
TOKEN.
|
TOKEN.
|
|
|
`OUTPUT ==>'
|
`OUTPUT ==>'
|
`( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL'
|
`( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL'
|
|
|
`RESULT-RECORD ==>'
|
`RESULT-RECORD ==>'
|
` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL'
|
` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL'
|
|
|
`OUT-OF-BAND-RECORD ==>'
|
`OUT-OF-BAND-RECORD ==>'
|
`ASYNC-RECORD | STREAM-RECORD'
|
`ASYNC-RECORD | STREAM-RECORD'
|
|
|
`ASYNC-RECORD ==>'
|
`ASYNC-RECORD ==>'
|
`EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT'
|
`EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT'
|
|
|
`EXEC-ASYNC-OUTPUT ==>'
|
`EXEC-ASYNC-OUTPUT ==>'
|
`[ TOKEN ] "*" ASYNC-OUTPUT'
|
`[ TOKEN ] "*" ASYNC-OUTPUT'
|
|
|
`STATUS-ASYNC-OUTPUT ==>'
|
`STATUS-ASYNC-OUTPUT ==>'
|
`[ TOKEN ] "+" ASYNC-OUTPUT'
|
`[ TOKEN ] "+" ASYNC-OUTPUT'
|
|
|
`NOTIFY-ASYNC-OUTPUT ==>'
|
`NOTIFY-ASYNC-OUTPUT ==>'
|
`[ TOKEN ] "=" ASYNC-OUTPUT'
|
`[ TOKEN ] "=" ASYNC-OUTPUT'
|
|
|
`ASYNC-OUTPUT ==>'
|
`ASYNC-OUTPUT ==>'
|
`ASYNC-CLASS ( "," RESULT )* NL'
|
`ASYNC-CLASS ( "," RESULT )* NL'
|
|
|
`RESULT-CLASS ==>'
|
`RESULT-CLASS ==>'
|
`"done" | "running" | "connected" | "error" | "exit"'
|
`"done" | "running" | "connected" | "error" | "exit"'
|
|
|
`ASYNC-CLASS ==>'
|
`ASYNC-CLASS ==>'
|
`"stopped" | OTHERS' (where OTHERS will be added depending on the
|
`"stopped" | OTHERS' (where OTHERS will be added depending on the
|
needs--this is still in development).
|
needs--this is still in development).
|
|
|
`RESULT ==>'
|
`RESULT ==>'
|
` VARIABLE "=" VALUE'
|
` VARIABLE "=" VALUE'
|
|
|
`VARIABLE ==>'
|
`VARIABLE ==>'
|
` STRING '
|
` STRING '
|
|
|
`VALUE ==>'
|
`VALUE ==>'
|
` CONST | TUPLE | LIST '
|
` CONST | TUPLE | LIST '
|
|
|
`CONST ==>'
|
`CONST ==>'
|
`C-STRING'
|
`C-STRING'
|
|
|
`TUPLE ==>'
|
`TUPLE ==>'
|
` "{}" | "{" RESULT ( "," RESULT )* "}" '
|
` "{}" | "{" RESULT ( "," RESULT )* "}" '
|
|
|
`LIST ==>'
|
`LIST ==>'
|
` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )*
|
` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )*
|
"]" '
|
"]" '
|
|
|
`STREAM-RECORD ==>'
|
`STREAM-RECORD ==>'
|
`CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT'
|
`CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT'
|
|
|
`CONSOLE-STREAM-OUTPUT ==>'
|
`CONSOLE-STREAM-OUTPUT ==>'
|
`"~" C-STRING'
|
`"~" C-STRING'
|
|
|
`TARGET-STREAM-OUTPUT ==>'
|
`TARGET-STREAM-OUTPUT ==>'
|
`"@" C-STRING'
|
`"@" C-STRING'
|
|
|
`LOG-STREAM-OUTPUT ==>'
|
`LOG-STREAM-OUTPUT ==>'
|
`"&" C-STRING'
|
`"&" C-STRING'
|
|
|
`NL ==>'
|
`NL ==>'
|
`CR | CR-LF'
|
`CR | CR-LF'
|
|
|
`TOKEN ==>'
|
`TOKEN ==>'
|
_any sequence of digits_.
|
_any sequence of digits_.
|
|
|
Notes:
|
Notes:
|
|
|
* All output sequences end in a single line containing a period.
|
* All output sequences end in a single line containing a period.
|
|
|
* The `TOKEN' is from the corresponding request. If an execution
|
* The `TOKEN' is from the corresponding request. If an execution
|
command is interrupted by the `-exec-interrupt' command, the TOKEN
|
command is interrupted by the `-exec-interrupt' command, the TOKEN
|
associated with the `*stopped' message is the one of the original
|
associated with the `*stopped' message is the one of the original
|
execution command, not the one of the interrupt command.
|
execution command, not the one of the interrupt command.
|
|
|
* STATUS-ASYNC-OUTPUT contains on-going status information about the
|
* STATUS-ASYNC-OUTPUT contains on-going status information about the
|
progress of a slow operation. It can be discarded. All status
|
progress of a slow operation. It can be discarded. All status
|
output is prefixed by `+'.
|
output is prefixed by `+'.
|
|
|
* EXEC-ASYNC-OUTPUT contains asynchronous state change on the target
|
* EXEC-ASYNC-OUTPUT contains asynchronous state change on the target
|
(stopped, started, disappeared). All async output is prefixed by
|
(stopped, started, disappeared). All async output is prefixed by
|
`*'.
|
`*'.
|
|
|
* NOTIFY-ASYNC-OUTPUT contains supplementary information that the
|
* NOTIFY-ASYNC-OUTPUT contains supplementary information that the
|
client should handle (e.g., a new breakpoint information). All
|
client should handle (e.g., a new breakpoint information). All
|
notify output is prefixed by `='.
|
notify output is prefixed by `='.
|
|
|
* CONSOLE-STREAM-OUTPUT is output that should be displayed as is in
|
* 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. It is the textual response to a CLI command. All
|
the console output is prefixed by `~'.
|
the console output is prefixed by `~'.
|
|
|
* TARGET-STREAM-OUTPUT is the output produced by the target program.
|
* TARGET-STREAM-OUTPUT is the output produced by the target program.
|
All the target output is prefixed by `@'.
|
All the target output is prefixed by `@'.
|
|
|
* LOG-STREAM-OUTPUT is output text coming from GDB's internals, for
|
* LOG-STREAM-OUTPUT is output text coming from GDB's internals, for
|
instance messages that should be displayed as part of an error
|
instance messages that should be displayed as part of an error
|
log. All the log output is prefixed by `&'.
|
log. All the log output is prefixed by `&'.
|
|
|
* New GDB/MI commands should only output LISTS containing VALUES.
|
* New GDB/MI commands should only output LISTS containing VALUES.
|
|
|
|
|
*Note GDB/MI Stream Records: GDB/MI Stream Records, for more details
|
*Note GDB/MI Stream Records: GDB/MI Stream Records, for more details
|
about the various output records.
|
about the various output records.
|
|
|
|
|
File: gdb.info, Node: GDB/MI Simple Examples, Prev: GDB/MI Output Syntax, Up: GDB/MI Command Syntax
|
File: gdb.info, Node: GDB/MI Simple Examples, Prev: GDB/MI Output Syntax, Up: GDB/MI Command Syntax
|
|
|
Simple Examples of GDB/MI Interaction
|
Simple Examples of GDB/MI Interaction
|
-------------------------------------
|
-------------------------------------
|
|
|
This subsection presents several simple examples of interaction using
|
This subsection presents several simple examples of interaction using
|
the GDB/MI interface. In these examples, `->' means that the following
|
the GDB/MI interface. In these examples, `->' means that the following
|
line is passed to GDB/MI as input, while `<-' means the output received
|
line is passed to GDB/MI as input, while `<-' means the output received
|
from GDB/MI.
|
from GDB/MI.
|
|
|
Target Stop
|
Target Stop
|
...........
|
...........
|
|
|
Here's an example of stopping the inferior process:
|
Here's an example of stopping the inferior process:
|
|
|
-> -stop
|
-> -stop
|
<- (gdb)
|
<- (gdb)
|
|
|
and later:
|
and later:
|
|
|
<- *stop,reason="stop",address="0x123",source="a.c:123"
|
<- *stop,reason="stop",address="0x123",source="a.c:123"
|
<- (gdb)
|
<- (gdb)
|
|
|
Simple CLI Command
|
Simple CLI Command
|
..................
|
..................
|
|
|
Here's an example of a simple CLI command being passed through
|
Here's an example of a simple CLI command being passed through
|
GDB/MI and on to the CLI.
|
GDB/MI and on to the CLI.
|
|
|
-> print 1+2
|
-> print 1+2
|
<- ~3\n
|
<- ~3\n
|
<- (gdb)
|
<- (gdb)
|
|
|
Command With Side Effects
|
Command With Side Effects
|
.........................
|
.........................
|
|
|
-> -symbol-file xyz.exe
|
-> -symbol-file xyz.exe
|
<- *breakpoint,nr="3",address="0x123",source="a.c:123"
|
<- *breakpoint,nr="3",address="0x123",source="a.c:123"
|
<- (gdb)
|
<- (gdb)
|
|
|
A Bad Command
|
A Bad Command
|
.............
|
.............
|
|
|
Here's what happens if you pass a non-existent command:
|
Here's what happens if you pass a non-existent command:
|
|
|
-> -rubbish
|
-> -rubbish
|
<- error,"Rubbish not found"
|
<- error,"Rubbish not found"
|
<- (gdb)
|
<- (gdb)
|
|
|
|
|
File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Output Records, Prev: GDB/MI Command Syntax, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Output Records, Prev: GDB/MI Command Syntax, Up: GDB/MI
|
|
|
GDB/MI Compatibility with CLI
|
GDB/MI Compatibility with CLI
|
=============================
|
=============================
|
|
|
To help users familiar with GDB's existing CLI interface, GDB/MI
|
To help users familiar with GDB's existing CLI interface, GDB/MI
|
accepts existing CLI commands. As specified by the syntax, such
|
accepts existing CLI commands. As specified by the syntax, such
|
commands can be directly entered into the GDB/MI interface and GDB will
|
commands can be directly entered into the GDB/MI interface and GDB will
|
respond.
|
respond.
|
|
|
This mechanism is provided as an aid to developers of GDB/MI clients
|
This mechanism is provided as an aid to developers of GDB/MI clients
|
and not as a reliable interface into the CLI. Since the command is
|
and not as a reliable interface into the CLI. Since the command is
|
being interpreteted in an environment that assumes GDB/MI behaviour,
|
being interpreteted in an environment that assumes GDB/MI behaviour,
|
the exact output of such commands is likely to end up being an
|
the exact output of such commands is likely to end up being an
|
un-supported hybrid of GDB/MI and CLI output.
|
un-supported hybrid of GDB/MI and CLI output.
|
|
|
|
|
File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Command Description Format, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Command Description Format, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI
|
|
|
GDB/MI Output Records
|
GDB/MI Output Records
|
=====================
|
=====================
|
|
|
* Menu:
|
* Menu:
|
|
|
* GDB/MI Result Records::
|
* GDB/MI Result Records::
|
* GDB/MI Stream Records::
|
* GDB/MI Stream Records::
|
* GDB/MI Out-of-band Records::
|
* GDB/MI Out-of-band Records::
|
|
|
|
|
File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records
|
File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records
|
|
|
GDB/MI Result Records
|
GDB/MI Result Records
|
---------------------
|
---------------------
|
|
|
In addition to a number of out-of-band notifications, the response
|
In addition to a number of out-of-band notifications, the response
|
to a GDB/MI command includes one of the following result indications:
|
to a GDB/MI command includes one of the following result indications:
|
|
|
`"^done" [ "," RESULTS ]'
|
`"^done" [ "," RESULTS ]'
|
The synchronous operation was successful, `RESULTS' are the return
|
The synchronous operation was successful, `RESULTS' are the return
|
values.
|
values.
|
|
|
`"^running"'
|
`"^running"'
|
The asynchronous operation was successfully started. The target is
|
The asynchronous operation was successfully started. The target is
|
running.
|
running.
|
|
|
`"^error" "," C-STRING'
|
`"^error" "," C-STRING'
|
The operation failed. The `C-STRING' contains the corresponding
|
The operation failed. The `C-STRING' contains the corresponding
|
error message.
|
error message.
|
|
|
|
|
File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Out-of-band Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records
|
File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Out-of-band Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records
|
|
|
GDB/MI Stream Records
|
GDB/MI Stream Records
|
---------------------
|
---------------------
|
|
|
GDB internally maintains a number of output streams: the console, the
|
GDB internally maintains a number of output streams: the console, the
|
target, and the log. The output intended for each of these streams is
|
target, and the log. The output intended for each of these streams is
|
funneled through the GDB/MI interface using "stream records".
|
funneled through the GDB/MI interface using "stream records".
|
|
|
Each stream record begins with a unique "prefix character" which
|
Each stream record begins with a unique "prefix character" which
|
identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output
|
identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output
|
Syntax.). In addition to the prefix, each stream record contains a
|
Syntax.). In addition to the prefix, each stream record contains a
|
`STRING-OUTPUT'. This is either raw text (with an implicit new line)
|
`STRING-OUTPUT'. This is either raw text (with an implicit new line)
|
or a quoted C string (which does not contain an implicit newline).
|
or a quoted C string (which does not contain an implicit newline).
|
|
|
`"~" STRING-OUTPUT'
|
`"~" STRING-OUTPUT'
|
The console output stream contains text that should be displayed
|
The console output stream contains text that should be displayed
|
in the CLI console window. It contains the textual responses to
|
in the CLI console window. It contains the textual responses to
|
CLI commands.
|
CLI commands.
|
|
|
`"@" STRING-OUTPUT'
|
`"@" STRING-OUTPUT'
|
The target output stream contains any textual output from the
|
The target output stream contains any textual output from the
|
running target.
|
running target.
|
|
|
`"&" STRING-OUTPUT'
|
`"&" STRING-OUTPUT'
|
The log stream contains debugging messages being produced by GDB's
|
The log stream contains debugging messages being produced by GDB's
|
internals.
|
internals.
|
|
|
|
|
File: gdb.info, Node: GDB/MI Out-of-band Records, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records
|
File: gdb.info, Node: GDB/MI Out-of-band Records, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records
|
|
|
GDB/MI Out-of-band Records
|
GDB/MI Out-of-band Records
|
--------------------------
|
--------------------------
|
|
|
"Out-of-band" records are used to notify the GDB/MI client of
|
"Out-of-band" records are used to notify the GDB/MI client of
|
additional changes that have occurred. Those changes can either be a
|
additional changes that have occurred. Those changes can either be a
|
consequence of GDB/MI (e.g., a breakpoint modified) or a result of
|
consequence of GDB/MI (e.g., a breakpoint modified) or a result of
|
target activity (e.g., target stopped).
|
target activity (e.g., target stopped).
|
|
|
The following is a preliminary list of possible out-of-band records.
|
The following is a preliminary list of possible out-of-band records.
|
|
|
`"*" "stop"'
|
`"*" "stop"'
|
|
|
File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Table Commands, Prev: GDB/MI Output Records, Up: GDB/MI
|
File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Table Commands, Prev: GDB/MI Output Records, Up: GDB/MI
|
|
|
GDB/MI Command Description Format
|
GDB/MI Command Description Format
|
=================================
|
=================================
|
|
|
The remaining sections describe blocks of commands. Each block of
|
The remaining sections describe blocks of commands. Each block of
|
commands is laid out in a fashion similar to this section.
|
commands is laid out in a fashion similar to this section.
|
|
|
Note the the line breaks shown in the examples are here only for
|
Note the the line breaks shown in the examples are here only for
|
readability. They don't appear in the real output. Also note that the
|
readability. They don't appear in the real output. Also note that the
|
commands with a non-available example (N.A.) are not yet implemented.
|
commands with a non-available example (N.A.) are not yet implemented.
|
|
|
Motivation
|
Motivation
|
----------
|
----------
|
|
|
The motivation for this collection of commands.
|
The motivation for this collection of commands.
|
|
|
Introduction
|
Introduction
|
------------
|
------------
|
|
|
A brief introduction to this collection of commands as a whole.
|
A brief introduction to this collection of commands as a whole.
|
|
|
Commands
|
Commands
|
--------
|
--------
|
|
|
For each command in the block, the following is described:
|
For each command in the block, the following is described:
|
|
|
Synopsis
|
Synopsis
|
........
|
........
|
|
|
-command ARGS...
|
-command ARGS...
|
|
|
GDB Command
|
GDB Command
|
...........
|
...........
|
|
|
The corresponding GDB CLI command.
|
The corresponding GDB CLI command.
|
|
|
Result
|
Result
|
......
|
......
|
|
|
Out-of-band
|
Out-of-band
|
...........
|
...........
|
|
|
Notes
|
Notes
|
.....
|
.....
|
|
|
Example
|
Example
|
.......
|
.......
|
|
|
|
|