Subversion Repositories or1k_old

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

INFO-DIR-SECTION Programming & development tools.
START-INFO-DIR-ENTRY
* Gdb: (gdb).                     The GNU debugger.
END-INFO-DIR-ENTRY

   This file documents the GNU debugger GDB.

   This is the Ninth Edition, December 2001, of `Debugging with GDB:
the GNU Source-Level Debugger' for GDB Version 5.3.

   Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
1998,
1999, 2000, 2001, 2002 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software" and "Free Software Needs Free
Documentation", with the Front-Cover Texts being "A GNU Manual," and
with the Back-Cover Texts as in (a) below.

   (a) The Free Software Foundation's Back-Cover Text is: "You have
freedom to copy and modify this GNU Manual, like GNU software.  Copies
published by the Free Software Foundation raise funds for GNU
development."


File: gdb.info,  Node: Value Annotations,  Next: Frame Annotations,  Prev: Server Prefix,  Up: Annotations

Values
======

   When a value is printed in various contexts, GDB uses annotations to
delimit the value from the surrounding text.

   If a value is printed using `print' and added to the value history,
the annotation looks like

     ^Z^Zvalue-history-begin HISTORY-NUMBER VALUE-FLAGS
     HISTORY-STRING
     ^Z^Zvalue-history-value
     THE-VALUE
     ^Z^Zvalue-history-end

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
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 `-'
for a value which cannot.

   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
similar:

     ^Z^Zvalue-begin VALUE-FLAGS
     THE-VALUE
     ^Z^Zvalue-end

   When GDB prints an argument to a function (for example, in the output
from the `backtrace' command), it annotates it as follows:

     ^Z^Zarg-begin
     ARGUMENT-NAME
     ^Z^Zarg-name-end
     SEPARATOR-STRING
     ^Z^Zarg-value VALUE-FLAGS
     THE-VALUE
     ^Z^Zarg-end

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
(such as `='), and VALUE-FLAGS and THE-VALUE have the same meanings as
in a `value-history-begin' annotation.

   When printing a structure, GDB annotates it as follows:

     ^Z^Zfield-begin VALUE-FLAGS
     FIELD-NAME
     ^Z^Zfield-name-end
     SEPARATOR-STRING
     ^Z^Zfield-value
     THE-VALUE
     ^Z^Zfield-end

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
`='), and VALUE-FLAGS and THE-VALUE have the same meanings as in a
`value-history-begin' annotation.

   When printing an array, GDB annotates it as follows:

     ^Z^Zarray-section-begin ARRAY-INDEX VALUE-FLAGS

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'
annotation.  This is followed by any number of elements, where is
element can be either a single element:

     `,' WHITESPACE         ; omitted for the first element
     THE-VALUE
     ^Z^Zelt

   or a repeated element

     `,' WHITESPACE         ; omitted for the first element
     THE-VALUE
     ^Z^Zelt-rep NUMBER-OF-REPITITIONS
     REPETITION-STRING
     ^Z^Zelt-rep-end

   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
case, NUMBER-OF-REPITITONS is the number of consecutive array elements
which contain that value, and REPETITION-STRING is a string which is
designed to convey to the user that repitition is being depicted.

   Once all the array elements have been output, the array annotation is
ended with

     ^Z^Zarray-section-end


File: gdb.info,  Node: Frame Annotations,  Next: Displays,  Prev: Value Annotations,  Up: Annotations

Frames
======

   Whenever GDB prints a frame, it annotates it.  For example, this
applies to frames printed when GDB stops, output from commands such as
`backtrace' or `up', etc.

   The frame annotation begins with

     ^Z^Zframe-begin LEVEL ADDRESS
     LEVEL-STRING

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
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
one or more lowercase hex digits (note that this does not depend on the
language).  The frame ends with

     ^Z^Zframe-end

   Between these annotations is the main body of the frame, which can
consist of

   *      ^Z^Zfunction-call
          FUNCTION-CALL-STRING

     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
     function in the program being debugged.

   *      ^Z^Zsignal-handler-caller
          SIGNAL-HANDLER-CALLER-STRING

     where SIGNAL-HANDLER-CALLER-STRING is text designed to convey to
     the user that this frame is associated with whatever mechanism is
     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
     handler itself).

   * A normal frame.

     This can optionally (depending on whether this is thought of as
     interesting information for the user to see) begin with

          ^Z^Zframe-address
          ADDRESS
          ^Z^Zframe-address-end
          SEPARATOR-STRING

     where ADDRESS is the address executing in the frame (the same
     address as in the `frame-begin' annotation, but printed in a form
     which is intended for user consumption--in particular, the syntax
     varies depending on the language), and SEPARATOR-STRING is a string
     intended to separate this address from what follows for the user's
     benefit.

     Then comes

          ^Z^Zframe-function-name
          FUNCTION-NAME
          ^Z^Zframe-args
          ARGUMENTS

     where FUNCTION-NAME is the name of the function executing in the
     frame, or `??' if not known, and ARGUMENTS are the arguments to
     the frame, with parentheses around them (each argument is annotated
     individually as well, *note Value Annotations::).

     If source information is available, a reference to it is then
     printed:

          ^Z^Zframe-source-begin
          SOURCE-INTRO-STRING
          ^Z^Zframe-source-file
          FILENAME
          ^Z^Zframe-source-file-end
          :
          ^Z^Zframe-source-line
          LINE-NUMBER
          ^Z^Zframe-source-end

     where SOURCE-INTRO-STRING separates for the user's benefit the
     reference from the text which precedes it, FILENAME is the name of
     the source file, and LINE-NUMBER is the line number within that
     file (the first line is line 1).

     If GDB prints some information about where the frame is from (which
     library, which load segment, etc.; currently only done on the
     RS/6000), it is annotated with

          ^Z^Zframe-where
          INFORMATION

     Then, if source is to actually be displayed for this frame (for
     example, this is not true for output from the `backtrace'
     command), then a `source' annotation (*note Source Annotations::)
     is displayed.  Unlike most annotations, this is output instead of
     the normal text which would be output, not in addition.


File: gdb.info,  Node: Displays,  Next: Prompting,  Prev: Frame Annotations,  Up: Annotations

Displays
========

   When GDB is told to display something using the `display' command,
the results of the display are annotated:

     ^Z^Zdisplay-begin
     NUMBER
     ^Z^Zdisplay-number-end
     NUMBER-SEPARATOR
     ^Z^Zdisplay-format
     FORMAT
     ^Z^Zdisplay-expression
     EXPRESSION
     ^Z^Zdisplay-expression-end
     EXPRESSION-SEPARATOR
     ^Z^Zdisplay-value
     VALUE
     ^Z^Zdisplay-end

where NUMBER is the number of the display, NUMBER-SEPARATOR is intended
to separate the number from what follows for the user, FORMAT includes
information such as the size, format, or other information about how
the value is being displayed, EXPRESSION is the expression being
displayed, EXPRESSION-SEPARATOR is intended to separate the expression
from the text that follows for the user, and VALUE is the actual value
being displayed.


File: gdb.info,  Node: Prompting,  Next: Errors,  Prev: Displays,  Up: Annotations

Annotation for GDB Input
========================

   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
over, etc.

   Different kinds of input each have a different "input type".  Each
input type has three annotations: a `pre-' annotation, which denotes
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 any echo which may (or may not) be associated
with the input.  For example, the `prompt' input type features the
following annotations:

     ^Z^Zpre-prompt
     ^Z^Zprompt
     ^Z^Zpost-prompt

   The input types are

`prompt'
     When GDB is prompting for a command (the main GDB prompt).

`commands'
     When GDB prompts for a set of commands, like in the `commands'
     command.  The annotations are repeated for each command which is
     input.

`overload-choice'
     When GDB wants the user to select between various overloaded
     functions.

`query'
     When GDB wants the user to confirm a potentially dangerous
     operation.

`prompt-for-continue'
     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
     disable prompting.  This is because the counting of lines is buggy
     in the presence of annotations.


File: gdb.info,  Node: Errors,  Next: Breakpoint Info,  Prev: Prompting,  Up: Annotations

Errors
======

     ^Z^Zquit

   This annotation occurs right before GDB responds to an interrupt.

     ^Z^Zerror

   This annotation occurs right before GDB responds to an error.

   Quit and error annotations indicate that any annotations which GDB
was in the middle of may end abruptly.  For example, if a
`value-history-begin' annotation is followed by a `error', one cannot
expect to receive the matching `value-history-end'.  One cannot expect
not to receive it either, however; an error annotation does not
necessarily mean that GDB is immediately returning all the way to the
top level.

   A quit or error annotation may be preceded by

     ^Z^Zerror-begin

   Any output between that and the quit or error annotation is the error
message.

   Warning messages are not yet annotated.


File: gdb.info,  Node: Breakpoint Info,  Next: Invalidation,  Prev: Errors,  Up: Annotations

Information on Breakpoints
==========================

   The output from the `info breakpoints' command is annotated as
follows:

     ^Z^Zbreakpoints-headers
     HEADER-ENTRY
     ^Z^Zbreakpoints-table

where HEADER-ENTRY has the same syntax as an entry (see below) but
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
number of entries.  If a field does not apply for this entry, it is
omitted.  Fields may contain trailing whitespace.  Each entry consists
of:

     ^Z^Zrecord
     ^Z^Zfield 0
     NUMBER
     ^Z^Zfield 1
     TYPE
     ^Z^Zfield 2
     DISPOSITION
     ^Z^Zfield 3
     ENABLE
     ^Z^Zfield 4
     ADDRESS
     ^Z^Zfield 5
     WHAT
     ^Z^Zfield 6
     FRAME
     ^Z^Zfield 7
     CONDITION
     ^Z^Zfield 8
     IGNORE-COUNT
     ^Z^Zfield 9
     COMMANDS

   Note that ADDRESS is intended for user consumption--the syntax
varies depending on the language.

   The output ends with

     ^Z^Zbreakpoints-table-end


File: gdb.info,  Node: Invalidation,  Next: Annotations for Running,  Prev: Breakpoint Info,  Up: Annotations

Invalidation Notices
====================

   The following annotations say that certain pieces of state may have
changed.

`^Z^Zframes-invalid'
     The frames (for example, output from the `backtrace' command) may
     have changed.

`^Z^Zbreakpoints-invalid'
     The breakpoints may have changed.  For example, the user just
     added or deleted a breakpoint.


File: gdb.info,  Node: Annotations for Running,  Next: Source Annotations,  Prev: Invalidation,  Up: Annotations

Running the Program
===================

   When the program starts executing due to a GDB command such as
`step' or `continue',

     ^Z^Zstarting

   is output.  When the program stops,

     ^Z^Zstopped

   is output.  Before the `stopped' annotation, a variety of
annotations describe how the program stopped.

`^Z^Zexited EXIT-STATUS'
     The program exited, and EXIT-STATUS is the exit status (zero for
     successful exit, otherwise nonzero).

`^Z^Zsignalled'
     The program exited with a signal.  After the `^Z^Zsignalled', the
     annotation continues:

          INTRO-TEXT
          ^Z^Zsignal-name
          NAME
          ^Z^Zsignal-name-end
          MIDDLE-TEXT
          ^Z^Zsignal-string
          STRING
          ^Z^Zsignal-string-end
          END-TEXT

     where NAME is the name of the signal, such as `SIGILL' or
     `SIGSEGV', and STRING is the explanation of the signal, such as
     `Illegal Instruction' or `Segmentation fault'.  INTRO-TEXT,
     MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
     particular format.

`^Z^Zsignal'
     The syntax of this annotation is just like `signalled', but GDB is
     just saying that the program received the signal, not that it was
     terminated with it.

`^Z^Zbreakpoint NUMBER'
     The program hit breakpoint number NUMBER.

`^Z^Zwatchpoint NUMBER'
     The program hit watchpoint number NUMBER.


File: gdb.info,  Node: Source Annotations,  Next: TODO,  Prev: Annotations for Running,  Up: Annotations

Displaying Source
=================

   The following annotation is used instead of displaying source code:

     ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR

   where FILENAME is an absolute file name indicating which source
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
(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
`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
program associated with the source which is being displayed.  ADDR is
in the form `0x' followed by one or more lowercase hex digits (note
that this does not depend on the language).


File: gdb.info,  Node: TODO,  Prev: Source Annotations,  Up: Annotations

Annotations We Might Want in the Future
=======================================

    - target-invalid
      the target might have changed (registers, heap contents, or
      execution status).  For performance, we might eventually want
      to hit `registers-invalid' and `all-registers-invalid' with
      greater precision

    - systematic annotation for set/show parameters (including
      invalidation notices).

    - similarly, `info' returns a list of candidates for invalidation
      notices.


File: gdb.info,  Node: GDB/MI,  Next: GDB Bugs,  Prev: Annotations,  Up: Top

The GDB/MI Interface
********************

Function and Purpose
====================

   GDB/MI is a line based machine oriented text interface to GDB.  It is
specifically intended to support the development of systems which use
the debugger as just one small component of a larger system.

   This chapter is a specification of the GDB/MI interface.  It is
written in the form of a reference manual.

   Note that GDB/MI is still under construction, so some of the
features described below are incomplete and subject to change.

Notation and Terminology
========================

   This chapter uses the following notation:

   * `|' separates two alternatives.

   * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or
     may not be given.

   * `( GROUP )*' means that GROUP inside the parentheses may repeat
     zero or more times.

   * `( GROUP )+' means that GROUP inside the parentheses may repeat
     one or more times.

   * `"STRING"' means a literal STRING.

Acknowledgments
===============

   In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
Elena Zannoni.

* Menu:

* GDB/MI Command Syntax::
* GDB/MI Compatibility with CLI::
* GDB/MI Output Records::
* GDB/MI Command Description Format::
* GDB/MI Breakpoint Table Commands::
* GDB/MI Data Manipulation::
* GDB/MI Program Control::
* GDB/MI Miscellaneous Commands::
* GDB/MI Stack Manipulation::
* GDB/MI Symbol Query::
* GDB/MI Target Manipulation::
* GDB/MI Thread Commands::
* GDB/MI Tracepoint Commands::
* GDB/MI Variable Objects::


File: gdb.info,  Node: GDB/MI Command Syntax,  Next: GDB/MI Compatibility with CLI,  Up: GDB/MI

GDB/MI Command Syntax
=====================

* Menu:

* GDB/MI Input Syntax::
* GDB/MI Output Syntax::
* GDB/MI Simple Examples::


File: gdb.info,  Node: GDB/MI Input Syntax,  Next: GDB/MI Output Syntax,  Up: GDB/MI Command Syntax

GDB/MI Input Syntax
-------------------

`COMMAND ==>'
     `CLI-COMMAND | MI-COMMAND'

`CLI-COMMAND ==>'
     `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB
     CLI command.

`MI-COMMAND ==>'
     `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " "
     PARAMETER )* NL'

`TOKEN ==>'
     "any sequence of digits"

`OPTION ==>'
     `"-" PARAMETER [ " " PARAMETER ]'

`PARAMETER ==>'
     `NON-BLANK-SEQUENCE | C-STRING'

`OPERATION ==>'
     _any of the operations described in this chapter_

`NON-BLANK-SEQUENCE ==>'
     _anything, provided it doesn't contain special characters such as
     "-", NL, """ and of course " "_

`C-STRING ==>'
     `""" SEVEN-BIT-ISO-C-STRING-CONTENT """'

`NL ==>'
     `CR | CR-LF'

Notes:

   * The CLI commands are still handled by the MI interpreter; their
     output is described below.

   * The `TOKEN', when present, is passed back when the command
     finishes.

   * Some MI commands accept optional arguments as part of the parameter
     list.  Each option is identified by a leading `-' (dash) and may be
     followed by an optional argument parameter.  Options occur first
     in the parameter list and can be delimited from normal parameters
     using `--' (this is useful when some parameters begin with a dash).

   Pragmatics:

   * We want easy access to the existing CLI syntax (for debugging).

   * We want it to be easy to spot a MI operation.


File: gdb.info,  Node: GDB/MI Output Syntax,  Next: GDB/MI Simple Examples,  Prev: GDB/MI Input Syntax,  Up: GDB/MI Command Syntax

GDB/MI Output Syntax
--------------------

   The output from GDB/MI consists of zero or more out-of-band records
followed, optionally, by a single result record.  This result record is
for the most recent command.  The sequence of output records is
terminated by `(gdb)'.

   If an input command was prefixed with a `TOKEN' then the
corresponding output for that command will also be prefixed by that same
TOKEN.

`OUTPUT ==>'
     `( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL'

`RESULT-RECORD ==>'
     ` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL'

`OUT-OF-BAND-RECORD ==>'
     `ASYNC-RECORD | STREAM-RECORD'

`ASYNC-RECORD ==>'
     `EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT'

`EXEC-ASYNC-OUTPUT ==>'
     `[ TOKEN ] "*" ASYNC-OUTPUT'

`STATUS-ASYNC-OUTPUT ==>'
     `[ TOKEN ] "+" ASYNC-OUTPUT'

`NOTIFY-ASYNC-OUTPUT ==>'
     `[ TOKEN ] "=" ASYNC-OUTPUT'

`ASYNC-OUTPUT ==>'
     `ASYNC-CLASS ( "," RESULT )* NL'

`RESULT-CLASS ==>'
     `"done" | "running" | "connected" | "error" | "exit"'

`ASYNC-CLASS ==>'
     `"stopped" | OTHERS' (where OTHERS will be added depending on the
     needs--this is still in development).

`RESULT ==>'
     ` VARIABLE "=" VALUE'

`VARIABLE ==>'
     ` STRING '

`VALUE ==>'
     ` CONST | TUPLE | LIST '

`CONST ==>'
     `C-STRING'

`TUPLE ==>'
     ` "{}" | "{" RESULT ( "," RESULT )* "}" '

`LIST ==>'
     ` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )*
     "]" '

`STREAM-RECORD ==>'
     `CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT'

`CONSOLE-STREAM-OUTPUT ==>'
     `"~" C-STRING'

`TARGET-STREAM-OUTPUT ==>'
     `"@" C-STRING'

`LOG-STREAM-OUTPUT ==>'
     `"&" C-STRING'

`NL ==>'
     `CR | CR-LF'

`TOKEN ==>'
     _any sequence of digits_.

Notes:

   * All output sequences end in a single line containing a period.

   * The `TOKEN' is from the corresponding request.  If an execution
     command is interrupted by the `-exec-interrupt' command, the TOKEN
     associated with the `*stopped' message is the one of the original
     execution command, not the one of the interrupt command.

   * STATUS-ASYNC-OUTPUT contains on-going status information about the
     progress of a slow operation.  It can be discarded.  All status
     output is prefixed by `+'.

   * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target
     (stopped, started, disappeared).  All async output is prefixed by
     `*'.

   * NOTIFY-ASYNC-OUTPUT contains supplementary information that the
     client should handle (e.g., a new breakpoint information).  All
     notify output is prefixed by `='.

   * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in
     the console.  It is the textual response to a CLI command.  All
     the console output is prefixed by `~'.

   * TARGET-STREAM-OUTPUT is the output produced by the target program.
     All the target output is prefixed by `@'.

   * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for
     instance messages that should be displayed as part of an error
     log.  All the log output is prefixed by `&'.

   * New GDB/MI commands should only output LISTS containing VALUES.


   *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details
about the various output records.


File: gdb.info,  Node: GDB/MI Simple Examples,  Prev: GDB/MI Output Syntax,  Up: GDB/MI Command Syntax

Simple Examples of GDB/MI Interaction
-------------------------------------

   This subsection presents several simple examples of interaction using
the GDB/MI interface.  In these examples, `->' means that the following
line is passed to GDB/MI as input, while `<-' means the output received
from GDB/MI.

Target Stop
...........

   Here's an example of stopping the inferior process:

     -> -stop
     <- (gdb)

and later:

     <- *stop,reason="stop",address="0x123",source="a.c:123"
     <- (gdb)

Simple CLI Command
..................

   Here's an example of a simple CLI command being passed through
GDB/MI and on to the CLI.

     -> print 1+2
     <- &"print 1+2\n"
     <- ~"$1 = 3\n"
     <- ^done
     <- (gdb)

Command With Side Effects
.........................

     -> -symbol-file xyz.exe
     <- *breakpoint,nr="3",address="0x123",source="a.c:123"
     <- (gdb)

A Bad Command
.............

   Here's what happens if you pass a non-existent command:

     -> -rubbish
     <- ^error,msg="Undefined MI command: rubbish"
     <- (gdb)


File: gdb.info,  Node: GDB/MI Compatibility with CLI,  Next: GDB/MI Output Records,  Prev: GDB/MI Command Syntax,  Up: GDB/MI

GDB/MI Compatibility with CLI
=============================

   To help users familiar with GDB's existing CLI interface, GDB/MI
accepts existing CLI commands.  As specified by the syntax, such
commands can be directly entered into the GDB/MI interface and GDB will
respond.

   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
being interpreteted in an environment that assumes GDB/MI behaviour,
the exact output of such commands is likely to end up being an
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

GDB/MI Output Records
=====================

* Menu:

* GDB/MI Result Records::
* GDB/MI Stream 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

GDB/MI Result Records
---------------------

   In addition to a number of out-of-band notifications, the response
to a GDB/MI command includes one of the following result indications:

`"^done" [ "," RESULTS ]'
     The synchronous operation was successful, `RESULTS' are the return
     values.

`"^running"'
     The asynchronous operation was successfully started.  The target is
     running.

`"^error" "," C-STRING'
     The operation failed.  The `C-STRING' contains the corresponding
     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

GDB/MI Stream Records
---------------------

   GDB internally maintains a number of output streams: the console, the
target, and the log.  The output intended for each of these streams is
funneled through the GDB/MI interface using "stream records".

   Each stream record begins with a unique "prefix character" which
identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output
Syntax.).  In addition to the prefix, each stream record contains a
`STRING-OUTPUT'.  This is either raw text (with an implicit new line)
or a quoted C string (which does not contain an implicit newline).

`"~" STRING-OUTPUT'
     The console output stream contains text that should be displayed
     in the CLI console window.  It contains the textual responses to
     CLI commands.

`"@" STRING-OUTPUT'
     The target output stream contains any textual output from the
     running target.

`"&" STRING-OUTPUT'
     The log stream contains debugging messages being produced by GDB's
     internals.


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

   "Out-of-band" records are used to notify the GDB/MI client of
additional changes that have occurred.  Those changes can either be a
consequence of GDB/MI (e.g., a breakpoint modified) or a result of
target activity (e.g., target stopped).

   The following is a preliminary list of possible out-of-band records.

`"*" "stop"'

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

   The remaining sections describe blocks of commands.  Each block of
commands is laid out in a fashion similar to this section.

   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
commands with a non-available example (N.A.) are not yet implemented.

Motivation
----------

   The motivation for this collection of commands.

Introduction
------------

   A brief introduction to this collection of commands as a whole.

Commands
--------

   For each command in the block, the following is described:

Synopsis
........

      -command ARGS...

GDB Command
...........

   The corresponding GDB CLI command.

Result
......

Out-of-band
...........

Notes
.....

Example
.......


File: gdb.info,  Node: GDB/MI Breakpoint Table Commands,  Next: GDB/MI Data Manipulation,  Prev: GDB/MI Command Description Format,  Up: GDB/MI

GDB/MI Breakpoint table commands
================================

   This section documents GDB/MI commands for manipulating breakpoints.

The `-break-after' Command
--------------------------

Synopsis
........

      -break-after NUMBER COUNT

   The breakpoint number NUMBER is not in effect until it has been hit
COUNT times.  To see how this is reflected in the output of the
`-break-list' command, see the description of the `-break-list' command
below.

GDB Command
...........

   The corresponding GDB command is `ignore'.

Example
.......

     (gdb)
     -break-insert main
     ^done,bkpt={number="1",addr="0x000100d0",file="hello.c",line="5"}
     (gdb)
     -break-after 1 3
     ~
     ^done
     (gdb)
     -break-list
     ^done,BreakpointTable={nr_rows="1",nr_cols="6",
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
     {width="40",alignment="2",col_name="what",colhdr="What"}],
     body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
     addr="0x000100d0",func="main",file="hello.c",line="5",times="0",
     ignore="3"}]}
     (gdb)

The `-break-condition' Command
------------------------------

Synopsis
........

      -break-condition NUMBER EXPR

   Breakpoint NUMBER will stop the program only if the condition in
EXPR is true.  The condition becomes part of the `-break-list' output
(see the description of the `-break-list' command below).

GDB Command
...........

   The corresponding GDB command is `condition'.

Example
.......

     (gdb)
     -break-condition 1 1
     ^done
     (gdb)
     -break-list
     ^done,BreakpointTable={nr_rows="1",nr_cols="6",
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
     {width="40",alignment="2",col_name="what",colhdr="What"}],
     body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
     addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",
     times="0",ignore="3"}]}
     (gdb)

The `-break-delete' Command
---------------------------

Synopsis
........

      -break-delete ( BREAKPOINT )+

   Delete the breakpoint(s) whose number(s) are specified in the
argument list.  This is obviously reflected in the breakpoint list.

GDB command
...........

   The corresponding GDB command is `delete'.

Example
.......

     (gdb)
     -break-delete 1
     ^done
     (gdb)
     -break-list
     ^done,BreakpointTable={nr_rows="0",nr_cols="6",
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
     {width="40",alignment="2",col_name="what",colhdr="What"}],
     body=[]}
     (gdb)

The `-break-disable' Command
----------------------------

Synopsis
........

      -break-disable ( BREAKPOINT )+

   Disable the named BREAKPOINT(s).  The field `enabled' in the break
list is now set to `n' for the named BREAKPOINT(s).

GDB Command
...........

   The corresponding GDB command is `disable'.

Example
.......

     (gdb)
     -break-disable 2
     ^done
     (gdb)
     -break-list
     ^done,BreakpointTable={nr_rows="1",nr_cols="6",
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
     {width="40",alignment="2",col_name="what",colhdr="What"}],
     body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n",
     addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}]}
     (gdb)

The `-break-enable' Command
---------------------------

Synopsis
........

      -break-enable ( BREAKPOINT )+

   Enable (previously disabled) BREAKPOINT(s).

GDB Command
...........

   The corresponding GDB command is `enable'.

Example
.......

     (gdb)
     -break-enable 2
     ^done
     (gdb)
     -break-list
     ^done,BreakpointTable={nr_rows="1",nr_cols="6",
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
     {width="40",alignment="2",col_name="what",colhdr="What"}],
     body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
     addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}]}
     (gdb)

The `-break-info' Command
-------------------------

Synopsis
........

      -break-info BREAKPOINT

   Get information about a single breakpoint.

GDB command
...........

   The corresponding GDB command is `info break BREAKPOINT'.

Example
.......

   N.A.

The `-break-insert' Command
---------------------------

Synopsis
........

      -break-insert [ -t ] [ -h ] [ -r ]
         [ -c CONDITION ] [ -i IGNORE-COUNT ]
         [ -p THREAD ] [ LINE | ADDR ]

If specified, LINE, can be one of:

   * function

   * filename:linenum

   * filename:function

   * *address

   The possible optional parameters of this command are:

`-t'
     Insert a tempoary breakpoint.

`-h'
     Insert a hardware breakpoint.

`-c CONDITION'
     Make the breakpoint conditional on CONDITION.

`-i IGNORE-COUNT'
     Initialize the IGNORE-COUNT.

`-r'
     Insert a regular breakpoint in all the functions whose names match
     the given regular expression.  Other flags are not applicable to
     regular expresson.

Result
......

   The result is in the form:

      ^done,bkptno="NUMBER",func="FUNCNAME",
       file="FILENAME",line="LINENO"

where NUMBER is the GDB number for this breakpoint, FUNCNAME is the
name of the function where the breakpoint was inserted, FILENAME is the
name of the source file which contains this function, and LINENO is the
source line number within that file.

   Note: this format is open to change.

GDB Command
...........

   The corresponding GDB commands are `break', `tbreak', `hbreak',
`thbreak', and `rbreak'.

Example
.......

     (gdb)
     -break-insert main
     ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
     (gdb)
     -break-insert -t foo
     ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",line="11"}
     (gdb)
     -break-list
     ^done,BreakpointTable={nr_rows="2",nr_cols="6",
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
     {width="40",alignment="2",col_name="what",colhdr="What"}],
     body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
     addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"},
     bkpt={number="2",type="breakpoint",disp="del",enabled="y",
     addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"}]}
     (gdb)
     -break-insert -r foo.*
     ~int foo(int, int);
     ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c",line="11"}
     (gdb)

The `-break-list' Command
-------------------------

Synopsis
........

      -break-list

   Displays the list of inserted breakpoints, showing the following
fields:

`Number'
     number of the breakpoint

`Type'
     type of the breakpoint: `breakpoint' or `watchpoint'

`Disposition'
     should the breakpoint be deleted or disabled when it is hit: `keep'
     or `nokeep'

`Enabled'
     is the breakpoint enabled or no: `y' or `n'

`Address'
     memory location at which the breakpoint is set

`What'
     logical location of the breakpoint, expressed by function name,
     file name, line number

`Times'
     number of times the breakpoint has been hit

   If there are no breakpoints or watchpoints, the `BreakpointTable'
`body' field is an empty list.

GDB Command
...........

   The corresponding GDB command is `info break'.

Example
.......

     (gdb)
     -break-list
     ^done,BreakpointTable={nr_rows="2",nr_cols="6",
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
     {width="40",alignment="2",col_name="what",colhdr="What"}],
     body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
     addr="0x000100d0",func="main",file="hello.c",line="5",times="0"},
     bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
     addr="0x00010114",func="foo",file="hello.c",line="13",times="0"}]}
     (gdb)

   Here's an example of the result when there are no breakpoints:

     (gdb)
     -break-list
     ^done,BreakpointTable={nr_rows="0",nr_cols="6",
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
     {width="40",alignment="2",col_name="what",colhdr="What"}],
     body=[]}
     (gdb)

The `-break-watch' Command
--------------------------

Synopsis
........

      -break-watch [ -a | -r ]

   Create a watchpoint.  With the `-a' option it will create an
"access" watchpoint, i.e. a watchpoint that triggers either on a read
from or on a write to the memory location.  With the `-r' option, the
watchpoint created is a "read" watchpoint, i.e. it will trigger only
when the memory location is accessed for reading.  Without either of
the options, the watchpoint created is a regular watchpoint, i.e. it
will trigger when the memory location is accessed for writing.  *Note
Setting watchpoints: Set Watchpoints.

   Note that `-break-list' will report a single list of watchpoints and
breakpoints inserted.

GDB Command
...........

   The corresponding GDB commands are `watch', `awatch', and `rwatch'.

Example
.......

   Setting a watchpoint on a variable in the `main' function:

     (gdb)
     -break-watch x
     ^done,wpt={number="2",exp="x"}
     (gdb)
     -exec-continue
     ^running
     ^done,reason="watchpoint-trigger",wpt={number="2",exp="x"},
     value={old="-268439212",new="55"},
     frame={func="main",args=[],file="recursive2.c",line="5"}
     (gdb)

   Setting a watchpoint on a variable local to a function.  GDB will
stop the program execution twice: first for the variable changing
value, then for the watchpoint going out of scope.

     (gdb)
     -break-watch C
     ^done,wpt={number="5",exp="C"}
     (gdb)
     -exec-continue
     ^running
     ^done,reason="watchpoint-trigger",
     wpt={number="5",exp="C"},value={old="-276895068",new="3"},
     frame={func="callee4",args=[],
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
     (gdb)
     -exec-continue
     ^running
     ^done,reason="watchpoint-scope",wpnum="5",
     frame={func="callee3",args=[{name="strarg",
     value="0x11940 \"A string argument.\""}],
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
     (gdb)

   Listing breakpoints and watchpoints, at different points in the
program execution.  Note that once the watchpoint goes out of scope, it
is deleted.

     (gdb)
     -break-watch C
     ^done,wpt={number="2",exp="C"}
     (gdb)
     -break-list
     ^done,BreakpointTable={nr_rows="2",nr_cols="6",
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
     {width="40",alignment="2",col_name="what",colhdr="What"}],
     body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
     addr="0x00010734",func="callee4",
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"},
     bkpt={number="2",type="watchpoint",disp="keep",
     enabled="y",addr="",what="C",times="0"}]}
     (gdb)
     -exec-continue
     ^running
     ^done,reason="watchpoint-trigger",wpt={number="2",exp="C"},
     value={old="-276895068",new="3"},
     frame={func="callee4",args=[],
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
     (gdb)
     -break-list
     ^done,BreakpointTable={nr_rows="2",nr_cols="6",
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
     {width="40",alignment="2",col_name="what",colhdr="What"}],
     body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
     addr="0x00010734",func="callee4",
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"},
     bkpt={number="2",type="watchpoint",disp="keep",
     enabled="y",addr="",what="C",times="-5"}]}
     (gdb)
     -exec-continue
     ^running
     ^done,reason="watchpoint-scope",wpnum="2",
     frame={func="callee3",args=[{name="strarg",
     value="0x11940 \"A string argument.\""}],
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
     (gdb)
     -break-list
     ^done,BreakpointTable={nr_rows="1",nr_cols="6",
     hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
     {width="14",alignment="-1",col_name="type",colhdr="Type"},
     {width="4",alignment="-1",col_name="disp",colhdr="Disp"},
     {width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
     {width="10",alignment="-1",col_name="addr",colhdr="Address"},
     {width="40",alignment="2",col_name="what",colhdr="What"}],
     body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
     addr="0x00010734",func="callee4",
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}]}
     (gdb)