This is the mail archive of the
gdb-patches@sources.redhat.com
mailing list for the GDB project.
Re: [rfa:doco] inline gdbmi.texinfo and annotate.texinfo in gdb.texinfo
Date: Wed, 26 Mar 2003 17:47:01 -0500
From: Andrew Cagney <ac131313 at redhat dot com>
>
> I don't mind, but what's the reasons for merging gdbmi.texinfo?
A simple `I might as well integrate both at the same time'. The
separate gdbmi.texinfo file is a throw-back to before MI was contributed.
Fine with me, then.
Ok, thanks. I've actually committed the attached. It's identical to
except that this includes a missing Makefile.in update.
Andrew
Index: doc/ChangeLog
2003-03-27 Andrew Cagney <cagney at redhat dot com>
* gdb.texinfo (GDB/MI Variable Objects): Replace @include with
chapter body. Use @smallexample instead of @example.
(Annotations): Ditto.
* Makefile.in (GDB_DOC_SOURCE_INCLUDES): Remove gdbmi.texinfo and
annotate.texi.
Index: mi/ChangeLog
2003-03-27 Andrew Cagney <cagney at redhat dot com>
* gdbmi.texinfo: Delete file. Contents moved to
../doc/gdb.texinfo.
Index: doc/Makefile.in
===================================================================
RCS file: /cvs/src/src/gdb/doc/Makefile.in,v
retrieving revision 1.27
diff -u -r1.27 Makefile.in
--- doc/Makefile.in 18 Mar 2003 17:44:23 -0000 1.27
+++ doc/Makefile.in 27 Mar 2003 15:14:46 -0000
@@ -98,10 +98,8 @@
# Main GDB manual
GDB_DOC_SOURCE_INCLUDES = \
- $(srcdir)/annotate.texi \
$(srcdir)/fdl.texi \
$(srcdir)/gpl.texi \
- $(GDBMI_DIR)/gdbmi.texinfo \
$(READLINE_DIR)/rluser.texinfo \
$(READLINE_DIR)/inc-hist.texinfo
GDB_DOC_BUILD_INCLUDES = \
Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.153
diff -u -r1.153 gdb.texinfo
--- doc/gdb.texinfo 17 Mar 2003 14:46:35 -0000 1.153
+++ doc/gdb.texinfo 27 Mar 2003 15:14:52 -0000
@@ -14045,8 +14045,4544 @@
each value is printed in its own window.
@end ignore
- at include annotate.texi
- at include gdbmi.texinfo
+
+ at node GDB/MI
+ at chapter The @sc{gdb/mi} Interface
+
+ at unnumberedsec Function and Purpose
+
+ at cindex @sc{gdb/mi}, its purpose
+ at sc{gdb/mi} is a line based machine oriented text interface to @value{GDBN}. 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 @sc{gdb/mi} interface. It is written
+in the form of a reference manual.
+
+Note that @sc{gdb/mi} is still under construction, so some of the
+features described below are incomplete and subject to change.
+
+ at unnumberedsec Notation and Terminology
+
+ at cindex notational conventions, for @sc{gdb/mi}
+This chapter uses the following notation:
+
+ at itemize @bullet
+ at item
+ at code{|} separates two alternatives.
+
+ at item
+ at code{[ @var{something} ]} indicates that @var{something} is optional:
+it may or may not be given.
+
+ at item
+ at code{( @var{group} )*} means that @var{group} inside the parentheses
+may repeat zero or more times.
+
+ at item
+ at code{( @var{group} )+} means that @var{group} inside the parentheses
+may repeat one or more times.
+
+ at item
+ at code{"@var{string}"} means a literal @var{string}.
+ at end itemize
+
+ at ignore
+ at heading Dependencies
+ at end ignore
+
+ at heading Acknowledgments
+
+In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
+Elena Zannoni.
+
+ at 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::
+ at ignore
+* GDB/MI Kod Commands::
+* GDB/MI Memory Overlay Commands::
+* GDB/MI Signal Handling Commands::
+ at end ignore
+* GDB/MI Stack Manipulation::
+* GDB/MI Symbol Query::
+* GDB/MI Target Manipulation::
+* GDB/MI Thread Commands::
+* GDB/MI Tracepoint Commands::
+* GDB/MI Variable Objects::
+ at end menu
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Command Syntax
+ at section @sc{gdb/mi} Command Syntax
+
+ at menu
+* GDB/MI Input Syntax::
+* GDB/MI Output Syntax::
+* GDB/MI Simple Examples::
+ at end menu
+
+ at node GDB/MI Input Syntax
+ at subsection @sc{gdb/mi} Input Syntax
+
+ at cindex input syntax for @sc{gdb/mi}
+ at cindex @sc{gdb/mi}, input syntax
+ at table @code
+ at item @var{command} @expansion{}
+ at code{@var{cli-command} | @var{mi-command}}
+
+ at item @var{cli-command} @expansion{}
+ at code{[ @var{token} ] @var{cli-command} @var{nl}}, where
+ at var{cli-command} is any existing @value{GDBN} CLI command.
+
+ at item @var{mi-command} @expansion{}
+ at code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )*
+ at code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}}
+
+ at item @var{token} @expansion{}
+"any sequence of digits"
+
+ at item @var{option} @expansion{}
+ at code{"-" @var{parameter} [ " " @var{parameter} ]}
+
+ at item @var{parameter} @expansion{}
+ at code{@var{non-blank-sequence} | @var{c-string}}
+
+ at item @var{operation} @expansion{}
+ at emph{any of the operations described in this chapter}
+
+ at item @var{non-blank-sequence} @expansion{}
+ at emph{anything, provided it doesn't contain special characters such as
+"-", @var{nl}, """ and of course " "}
+
+ at item @var{c-string} @expansion{}
+ at code{""" @var{seven-bit-iso-c-string-content} """}
+
+ at item @var{nl} @expansion{}
+ at code{CR | CR-LF}
+ at end table
+
+ at noindent
+Notes:
+
+ at itemize @bullet
+ at item
+The CLI commands are still handled by the @sc{mi} interpreter; their
+output is described below.
+
+ at item
+The @code{ at var{token}}, when present, is passed back when the command
+finishes.
+
+ at item
+Some @sc{mi} commands accept optional arguments as part of the parameter
+list. Each option is identified by a leading @samp{-} (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
+ at samp{--} (this is useful when some parameters begin with a dash).
+ at end itemize
+
+Pragmatics:
+
+ at itemize @bullet
+ at item
+We want easy access to the existing CLI syntax (for debugging).
+
+ at item
+We want it to be easy to spot a @sc{mi} operation.
+ at end itemize
+
+ at node GDB/MI Output Syntax
+ at subsection @sc{gdb/mi} Output Syntax
+
+ at cindex output syntax of @sc{gdb/mi}
+ at cindex @sc{gdb/mi}, output syntax
+The output from @sc{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 @samp{(@value{GDBP})}.
+
+If an input command was prefixed with a @code{ at var{token}} then the
+corresponding output for that command will also be prefixed by that same
+ at var{token} dot
+
+ at table @code
+ at item @var{output} @expansion{}
+ at code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
+
+ at item @var{result-record} @expansion{}
+ at code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
+
+ at item @var{out-of-band-record} @expansion{}
+ at code{@var{async-record} | @var{stream-record}}
+
+ at item @var{async-record} @expansion{}
+ at code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
+
+ at item @var{exec-async-output} @expansion{}
+ at code{[ @var{token} ] "*" @var{async-output}}
+
+ at item @var{status-async-output} @expansion{}
+ at code{[ @var{token} ] "+" @var{async-output}}
+
+ at item @var{notify-async-output} @expansion{}
+ at code{[ @var{token} ] "=" @var{async-output}}
+
+ at item @var{async-output} @expansion{}
+ at code{@var{async-class} ( "," @var{result} )* @var{nl}}
+
+ at item @var{result-class} @expansion{}
+ at code{"done" | "running" | "connected" | "error" | "exit"}
+
+ at item @var{async-class} @expansion{}
+ at code{"stopped" | @var{others}} (where @var{others} will be added
+depending on the needs---this is still in development).
+
+ at item @var{result} @expansion{}
+ at code{ @var{variable} "=" @var{value}}
+
+ at item @var{variable} @expansion{}
+ at code{ @var{string} }
+
+ at item @var{value} @expansion{}
+ at code{ @var{const} | @var{tuple} | @var{list} }
+
+ at item @var{const} @expansion{}
+ at code{@var{c-string}}
+
+ at item @var{tuple} @expansion{}
+ at code{ "@{ at }" | "@{" @var{result} ( "," @var{result} )* "@}" }
+
+ at item @var{list} @expansion{}
+ at code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "["
+ at var{result} ( "," @var{result} )* "]" }
+
+ at item @var{stream-record} @expansion{}
+ at code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
+
+ at item @var{console-stream-output} @expansion{}
+ at code{"~" @var{c-string}}
+
+ at item @var{target-stream-output} @expansion{}
+ at code{"@@" @var{c-string}}
+
+ at item @var{log-stream-output} @expansion{}
+ at code{"&" @var{c-string}}
+
+ at item @var{nl} @expansion{}
+ at code{CR | CR-LF}
+
+ at item @var{token} @expansion{}
+ at emph{any sequence of digits}.
+ at end table
+
+ at noindent
+Notes:
+
+ at itemize @bullet
+ at item
+All output sequences end in a single line containing a period.
+
+ at item
+The @code{ at var{token}} is from the corresponding request. If an execution
+command is interrupted by the @samp{-exec-interrupt} command, the
+ at var{token} associated with the @samp{*stopped} message is the one of the
+original execution command, not the one of the interrupt command.
+
+ at item
+ at cindex status output in @sc{gdb/mi}
+ at var{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 @samp{+}.
+
+ at item
+ at cindex async output in @sc{gdb/mi}
+ at var{exec-async-output} contains asynchronous state change on the target
+(stopped, started, disappeared). All async output is prefixed by
+ at samp{*} dot
+
+ at item
+ at cindex notify output in @sc{gdb/mi}
+ at var{notify-async-output} contains supplementary information that the
+client should handle (e.g., a new breakpoint information). All notify
+output is prefixed by @samp{=}.
+
+ at item
+ at cindex console output in @sc{gdb/mi}
+ at var{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 @samp{~}.
+
+ at item
+ at cindex target output in @sc{gdb/mi}
+ at var{target-stream-output} is the output produced by the target program.
+All the target output is prefixed by @samp{@@}.
+
+ at item
+ at cindex log output in @sc{gdb/mi}
+ at var{log-stream-output} is output text coming from @value{GDBN}'s internals, for
+instance messages that should be displayed as part of an error log. All
+the log output is prefixed by @samp{&}.
+
+ at item
+ at cindex list output in @sc{gdb/mi}
+New @sc{gdb/mi} commands should only output @var{lists} containing
+ at var{values} dot
+
+
+ at end itemize
+
+ at xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
+details about the various output records.
+
+ at node GDB/MI Simple Examples
+ at subsection Simple Examples of @sc{gdb/mi} Interaction
+ at cindex @sc{gdb/mi}, simple examples
+
+This subsection presents several simple examples of interaction using
+the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
+following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
+the output received from @sc{gdb/mi}.
+
+ at subsubheading Target Stop
+ at c Ummm... There is no "-stop" command. This assumes async, no?
+Here's an example of stopping the inferior process:
+
+ at smallexample
+-> -stop
+<- (@value{GDBP})
+ at end smallexample
+
+ at noindent
+and later:
+
+ at smallexample
+<- *stop,reason="stop",address="0x123",source="a.c:123"
+<- (@value{GDBP})
+ at end smallexample
+
+ at subsubheading Simple CLI Command
+
+Here's an example of a simple CLI command being passed through
+ at sc{gdb/mi} and on to the CLI.
+
+ at smallexample
+-> print 1+2
+<- &"print 1+2\n"
+<- ~"$1 = 3\n"
+<- ^done
+<- (@value{GDBP})
+ at end smallexample
+
+ at subsubheading Command With Side Effects
+
+ at smallexample
+-> -symbol-file xyz.exe
+<- *breakpoint,nr="3",address="0x123",source="a.c:123"
+<- (@value{GDBP})
+ at end smallexample
+
+ at subsubheading A Bad Command
+
+Here's what happens if you pass a non-existent command:
+
+ at smallexample
+-> -rubbish
+<- ^error,msg="Undefined MI command: rubbish"
+<- (@value{GDBP})
+ at end smallexample
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Compatibility with CLI
+ at section @sc{gdb/mi} Compatibility with CLI
+
+ at cindex compatibility, @sc{gdb/mi} and CLI
+ at cindex @sc{gdb/mi}, compatibility with CLI
+To help users familiar with @value{GDBN}'s existing CLI interface, @sc{gdb/mi}
+accepts existing CLI commands. As specified by the syntax, such
+commands can be directly entered into the @sc{gdb/mi} interface and @value{GDBN} will
+respond.
+
+This mechanism is provided as an aid to developers of @sc{gdb/mi}
+clients and not as a reliable interface into the CLI. Since the command
+is being interpreteted in an environment that assumes @sc{gdb/mi}
+behaviour, the exact output of such commands is likely to end up being
+an un-supported hybrid of @sc{gdb/mi} and CLI output.
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Output Records
+ at section @sc{gdb/mi} Output Records
+
+ at menu
+* GDB/MI Result Records::
+* GDB/MI Stream Records::
+* GDB/MI Out-of-band Records::
+ at end menu
+
+ at node GDB/MI Result Records
+ at subsection @sc{gdb/mi} Result Records
+
+ at cindex result records in @sc{gdb/mi}
+ at cindex @sc{gdb/mi}, result records
+In addition to a number of out-of-band notifications, the response to a
+ at sc{gdb/mi} command includes one of the following result indications:
+
+ at table @code
+ at findex ^done
+ at item "^done" [ "," @var{results} ]
+The synchronous operation was successful, @code{ at var{results}} are the return
+values.
+
+ at item "^running"
+ at findex ^running
+ at c Is this one correct? Should it be an out-of-band notification?
+The asynchronous operation was successfully started. The target is
+running.
+
+ at item "^error" "," @var{c-string}
+ at findex ^error
+The operation failed. The @code{ at var{c-string}} contains the corresponding
+error message.
+ at end table
+
+ at node GDB/MI Stream Records
+ at subsection @sc{gdb/mi} Stream Records
+
+ at cindex @sc{gdb/mi}, stream records
+ at cindex stream records in @sc{gdb/mi}
+ at value{GDBN} 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 @sc{gdb/mi} interface using @dfn{stream records}.
+
+Each stream record begins with a unique @dfn{prefix character} which
+identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output
+Syntax}). In addition to the prefix, each stream record contains a
+ at code{@var{string-output}}. This is either raw text (with an implicit new
+line) or a quoted C string (which does not contain an implicit newline).
+
+ at table @code
+ at item "~" @var{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.
+
+ at item "@@" @var{string-output}
+The target output stream contains any textual output from the running
+target.
+
+ at item "&" @var{string-output}
+The log stream contains debugging messages being produced by @value{GDBN}'s
+internals.
+ at end table
+
+ at node GDB/MI Out-of-band Records
+ at subsection @sc{gdb/mi} Out-of-band Records
+
+ at cindex out-of-band records in @sc{gdb/mi}
+ at cindex @sc{gdb/mi}, out-of-band records
+ at dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of
+additional changes that have occurred. Those changes can either be a
+consequence of @sc{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.
+
+ at table @code
+ at item "*" "stop"
+ at end table
+
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Command Description Format
+ at section @sc{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.
+
+ at subheading Motivation
+
+The motivation for this collection of commands.
+
+ at subheading Introduction
+
+A brief introduction to this collection of commands as a whole.
+
+ at subheading Commands
+
+For each command in the block, the following is described:
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -command @var{args} at dots{}
+ at end smallexample
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} CLI command.
+
+ at subsubheading Result
+
+ at subsubheading Out-of-band
+
+ at subsubheading Notes
+
+ at subsubheading Example
+
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Breakpoint Table Commands
+ at section @sc{gdb/mi} Breakpoint table commands
+
+ at cindex breakpoint commands for @sc{gdb/mi}
+ at cindex @sc{gdb/mi}, breakpoint commands
+This section documents @sc{gdb/mi} commands for manipulating
+breakpoints.
+
+ at subheading The @code{-break-after} Command
+ at findex -break-after
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -break-after @var{number} @var{count}
+ at end smallexample
+
+The breakpoint number @var{number} is not in effect until it has been
+hit @var{count} times. To see how this is reflected in the output of
+the @samp{-break-list} command, see the description of the
+ at samp{-break-list} command below.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{ignore}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-break-insert main
+^done,bkpt= at {number="1",addr="0x000100d0",file="hello.c",line="5"@}
+(@value{GDBP})
+-break-after 1 3
+~
+^done
+(@value{GDBP})
+-break-list
+^done,BreakpointTable= at {nr_rows="1",nr_cols="6",
+hdr=[ at {width="3",alignment="-1",col_name="number",colhdr="Num"@},
+ at {width="14",alignment="-1",col_name="type",colhdr="Type"@},
+ at {width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
+ at {width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
+ at {width="10",alignment="-1",col_name="addr",colhdr="Address"@},
+ at {width="40",alignment="2",col_name="what",colhdr="What"@}],
+body=[bkpt= at {number="1",type="breakpoint",disp="keep",enabled="y",
+addr="0x000100d0",func="main",file="hello.c",line="5",times="0",
+ignore="3"@}] at }
+(@value{GDBP})
+ at end smallexample
+
+ at ignore
+ at subheading The @code{-break-catch} Command
+ at findex -break-catch
+
+ at subheading The @code{-break-commands} Command
+ at findex -break-commands
+ at end ignore
+
+
+ at subheading The @code{-break-condition} Command
+ at findex -break-condition
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -break-condition @var{number} @var{expr}
+ at end smallexample
+
+Breakpoint @var{number} will stop the program only if the condition in
+ at var{expr} is true. The condition becomes part of the
+ at samp{-break-list} output (see the description of the @samp{-break-list}
+command below).
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{condition}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-break-condition 1 1
+^done
+(@value{GDBP})
+-break-list
+^done,BreakpointTable= at {nr_rows="1",nr_cols="6",
+hdr=[ at {width="3",alignment="-1",col_name="number",colhdr="Num"@},
+ at {width="14",alignment="-1",col_name="type",colhdr="Type"@},
+ at {width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
+ at {width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
+ at {width="10",alignment="-1",col_name="addr",colhdr="Address"@},
+ at {width="40",alignment="2",col_name="what",colhdr="What"@}],
+body=[bkpt= at {number="1",type="breakpoint",disp="keep",enabled="y",
+addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",
+times="0",ignore="3"@}] at }
+(@value{GDBP})
+ at end smallexample
+
+ at subheading The @code{-break-delete} Command
+ at findex -break-delete
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -break-delete ( @var{breakpoint} )+
+ at end smallexample
+
+Delete the breakpoint(s) whose number(s) are specified in the argument
+list. This is obviously reflected in the breakpoint list.
+
+ at subsubheading @value{GDBN} command
+
+The corresponding @value{GDBN} command is @samp{delete}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-break-delete 1
+^done
+(@value{GDBP})
+-break-list
+^done,BreakpointTable= at {nr_rows="0",nr_cols="6",
+hdr=[ at {width="3",alignment="-1",col_name="number",colhdr="Num"@},
+ at {width="14",alignment="-1",col_name="type",colhdr="Type"@},
+ at {width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
+ at {width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
+ at {width="10",alignment="-1",col_name="addr",colhdr="Address"@},
+ at {width="40",alignment="2",col_name="what",colhdr="What"@}],
+body=[] at }
+(@value{GDBP})
+ at end smallexample
+
+ at subheading The @code{-break-disable} Command
+ at findex -break-disable
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -break-disable ( @var{breakpoint} )+
+ at end smallexample
+
+Disable the named @var{breakpoint}(s). The field @samp{enabled} in the
+break list is now set to @samp{n} for the named @var{breakpoint}(s).
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{disable}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-break-disable 2
+^done
+(@value{GDBP})
+-break-list
+^done,BreakpointTable= at {nr_rows="1",nr_cols="6",
+hdr=[ at {width="3",alignment="-1",col_name="number",colhdr="Num"@},
+ at {width="14",alignment="-1",col_name="type",colhdr="Type"@},
+ at {width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
+ at {width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
+ at {width="10",alignment="-1",col_name="addr",colhdr="Address"@},
+ at {width="40",alignment="2",col_name="what",colhdr="What"@}],
+body=[bkpt= at {number="2",type="breakpoint",disp="keep",enabled="n",
+addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}] at }
+(@value{GDBP})
+ at end smallexample
+
+ at subheading The @code{-break-enable} Command
+ at findex -break-enable
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -break-enable ( @var{breakpoint} )+
+ at end smallexample
+
+Enable (previously disabled) @var{breakpoint}(s).
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{enable}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-break-enable 2
+^done
+(@value{GDBP})
+-break-list
+^done,BreakpointTable= at {nr_rows="1",nr_cols="6",
+hdr=[ at {width="3",alignment="-1",col_name="number",colhdr="Num"@},
+ at {width="14",alignment="-1",col_name="type",colhdr="Type"@},
+ at {width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
+ at {width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
+ at {width="10",alignment="-1",col_name="addr",colhdr="Address"@},
+ at {width="40",alignment="2",col_name="what",colhdr="What"@}],
+body=[bkpt= at {number="2",type="breakpoint",disp="keep",enabled="y",
+addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}] at }
+(@value{GDBP})
+ at end smallexample
+
+ at subheading The @code{-break-info} Command
+ at findex -break-info
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -break-info @var{breakpoint}
+ at end smallexample
+
+ at c REDUNDANT???
+Get information about a single breakpoint.
+
+ at subsubheading @value{GDBN} command
+
+The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
+
+ at subsubheading Example
+N.A.
+
+ at subheading The @code{-break-insert} Command
+ at findex -break-insert
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -break-insert [ -t ] [ -h ] [ -r ]
+ [ -c @var{condition} ] [ -i @var{ignore-count} ]
+ [ -p @var{thread} ] [ @var{line} | @var{addr} ]
+ at end smallexample
+
+ at noindent
+If specified, @var{line}, can be one of:
+
+ at itemize @bullet
+ at item function
+ at c @item +offset
+ at c @item -offset
+ at c @item linenum
+ at item filename:linenum
+ at item filename:function
+ at item *address
+ at end itemize
+
+The possible optional parameters of this command are:
+
+ at table @samp
+ at item -t
+Insert a tempoary breakpoint.
+ at item -h
+Insert a hardware breakpoint.
+ at item -c @var{condition}
+Make the breakpoint conditional on @var{condition}.
+ at item -i @var{ignore-count}
+Initialize the @var{ignore-count}.
+ at item -r
+Insert a regular breakpoint in all the functions whose names match the
+given regular expression. Other flags are not applicable to regular
+expresson.
+ at end table
+
+ at subsubheading Result
+
+The result is in the form:
+
+ at smallexample
+ ^done,bkptno="@var{number}",func="@var{funcname}",
+ file="@var{filename}",line="@var{lineno}"
+ at end smallexample
+
+ at noindent
+where @var{number} is the @value{GDBN} number for this breakpoint, @var{funcname}
+is the name of the function where the breakpoint was inserted,
+ at var{filename} is the name of the source file which contains this
+function, and @var{lineno} is the source line number within that file.
+
+Note: this format is open to change.
+ at c An out-of-band breakpoint instead of part of the result?
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
+ at samp{hbreak}, @samp{thbreak}, and @samp{rbreak}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-break-insert main
+^done,bkpt= at {number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
+(@value{GDBP})
+-break-insert -t foo
+^done,bkpt= at {number="2",addr="0x00010774",file="recursive2.c",line="11"@}
+(@value{GDBP})
+-break-list
+^done,BreakpointTable= at {nr_rows="2",nr_cols="6",
+hdr=[ at {width="3",alignment="-1",col_name="number",colhdr="Num"@},
+ at {width="14",alignment="-1",col_name="type",colhdr="Type"@},
+ at {width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
+ at {width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
+ at {width="10",alignment="-1",col_name="addr",colhdr="Address"@},
+ at {width="40",alignment="2",col_name="what",colhdr="What"@}],
+body=[bkpt= at {number="1",type="breakpoint",disp="keep",enabled="y",
+addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@},
+bkpt= at {number="2",type="breakpoint",disp="del",enabled="y",
+addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}] at }
+(@value{GDBP})
+-break-insert -r foo.*
+~int foo(int, int);
+^done,bkpt= at {number="3",addr="0x00010774",file="recursive2.c",line="11"@}
+(@value{GDBP})
+ at end smallexample
+
+ at subheading The @code{-break-list} Command
+ at findex -break-list
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -break-list
+ at end smallexample
+
+Displays the list of inserted breakpoints, showing the following fields:
+
+ at table @samp
+ at item Number
+number of the breakpoint
+ at item Type
+type of the breakpoint: @samp{breakpoint} or @samp{watchpoint}
+ at item Disposition
+should the breakpoint be deleted or disabled when it is hit: @samp{keep}
+or @samp{nokeep}
+ at item Enabled
+is the breakpoint enabled or no: @samp{y} or @samp{n}
+ at item Address
+memory location at which the breakpoint is set
+ at item What
+logical location of the breakpoint, expressed by function name, file
+name, line number
+ at item Times
+number of times the breakpoint has been hit
+ at end table
+
+If there are no breakpoints or watchpoints, the @code{BreakpointTable}
+ at code{body} field is an empty list.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info break}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-break-list
+^done,BreakpointTable= at {nr_rows="2",nr_cols="6",
+hdr=[ at {width="3",alignment="-1",col_name="number",colhdr="Num"@},
+ at {width="14",alignment="-1",col_name="type",colhdr="Type"@},
+ at {width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
+ at {width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
+ at {width="10",alignment="-1",col_name="addr",colhdr="Address"@},
+ at {width="40",alignment="2",col_name="what",colhdr="What"@}],
+body=[bkpt= at {number="1",type="breakpoint",disp="keep",enabled="y",
+addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
+bkpt= at {number="2",type="breakpoint",disp="keep",enabled="y",
+addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}] at }
+(@value{GDBP})
+ at end smallexample
+
+Here's an example of the result when there are no breakpoints:
+
+ at smallexample
+(@value{GDBP})
+-break-list
+^done,BreakpointTable= at {nr_rows="0",nr_cols="6",
+hdr=[ at {width="3",alignment="-1",col_name="number",colhdr="Num"@},
+ at {width="14",alignment="-1",col_name="type",colhdr="Type"@},
+ at {width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
+ at {width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
+ at {width="10",alignment="-1",col_name="addr",colhdr="Address"@},
+ at {width="40",alignment="2",col_name="what",colhdr="What"@}],
+body=[] at }
+(@value{GDBP})
+ at end smallexample
+
+ at subheading The @code{-break-watch} Command
+ at findex -break-watch
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -break-watch [ -a | -r ]
+ at end smallexample
+
+Create a watchpoint. With the @samp{-a} option it will create an
+ at dfn{access} watchpoint, i.e. a watchpoint that triggers either on a
+read from or on a write to the memory location. With the @samp{-r}
+option, the watchpoint created is a @dfn{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.
+ at xref{Set Watchpoints, , Setting watchpoints}.
+
+Note that @samp{-break-list} will report a single list of watchpoints and
+breakpoints inserted.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and
+ at samp{rwatch} dot
+
+ at subsubheading Example
+
+Setting a watchpoint on a variable in the @code{main} function:
+
+ at smallexample
+(@value{GDBP})
+-break-watch x
+^done,wpt= at {number="2",exp="x"@}
+(@value{GDBP})
+-exec-continue
+^running
+^done,reason="watchpoint-trigger",wpt= at {number="2",exp="x"@},
+value= at {old="-268439212",new="55"@},
+frame= at {func="main",args=[],file="recursive2.c",line="5"@}
+(@value{GDBP})
+ at end smallexample
+
+Setting a watchpoint on a variable local to a function. @value{GDBN} will stop
+the program execution twice: first for the variable changing value, then
+for the watchpoint going out of scope.
+
+ at smallexample
+(@value{GDBP})
+-break-watch C
+^done,wpt= at {number="5",exp="C"@}
+(@value{GDBP})
+-exec-continue
+^running
+^done,reason="watchpoint-trigger",
+wpt= at {number="5",exp="C"@},value= at {old="-276895068",new="3"@},
+frame= at {func="callee4",args=[],
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
+(@value{GDBP})
+-exec-continue
+^running
+^done,reason="watchpoint-scope",wpnum="5",
+frame= at {func="callee3",args=[ at {name="strarg",
+value="0x11940 \"A string argument.\""@}],
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+(@value{GDBP})
+ at end smallexample
+
+Listing breakpoints and watchpoints, at different points in the program
+execution. Note that once the watchpoint goes out of scope, it is
+deleted.
+
+ at smallexample
+(@value{GDBP})
+-break-watch C
+^done,wpt= at {number="2",exp="C"@}
+(@value{GDBP})
+-break-list
+^done,BreakpointTable= at {nr_rows="2",nr_cols="6",
+hdr=[ at {width="3",alignment="-1",col_name="number",colhdr="Num"@},
+ at {width="14",alignment="-1",col_name="type",colhdr="Type"@},
+ at {width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
+ at {width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
+ at {width="10",alignment="-1",col_name="addr",colhdr="Address"@},
+ at {width="40",alignment="2",col_name="what",colhdr="What"@}],
+body=[bkpt= at {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= at {number="2",type="watchpoint",disp="keep",
+enabled="y",addr="",what="C",times="0"@}] at }
+(@value{GDBP})
+-exec-continue
+^running
+^done,reason="watchpoint-trigger",wpt= at {number="2",exp="C"@},
+value= at {old="-276895068",new="3"@},
+frame= at {func="callee4",args=[],
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
+(@value{GDBP})
+-break-list
+^done,BreakpointTable= at {nr_rows="2",nr_cols="6",
+hdr=[ at {width="3",alignment="-1",col_name="number",colhdr="Num"@},
+ at {width="14",alignment="-1",col_name="type",colhdr="Type"@},
+ at {width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
+ at {width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
+ at {width="10",alignment="-1",col_name="addr",colhdr="Address"@},
+ at {width="40",alignment="2",col_name="what",colhdr="What"@}],
+body=[bkpt= at {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= at {number="2",type="watchpoint",disp="keep",
+enabled="y",addr="",what="C",times="-5"@}] at }
+(@value{GDBP})
+-exec-continue
+^running
+^done,reason="watchpoint-scope",wpnum="2",
+frame= at {func="callee3",args=[ at {name="strarg",
+value="0x11940 \"A string argument.\""@}],
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+(@value{GDBP})
+-break-list
+^done,BreakpointTable= at {nr_rows="1",nr_cols="6",
+hdr=[ at {width="3",alignment="-1",col_name="number",colhdr="Num"@},
+ at {width="14",alignment="-1",col_name="type",colhdr="Type"@},
+ at {width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
+ at {width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
+ at {width="10",alignment="-1",col_name="addr",colhdr="Address"@},
+ at {width="40",alignment="2",col_name="what",colhdr="What"@}],
+body=[bkpt= at {number="1",type="breakpoint",disp="keep",enabled="y",
+addr="0x00010734",func="callee4",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}] at }
+(@value{GDBP})
+ at end smallexample
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Data Manipulation
+ at section @sc{gdb/mi} Data Manipulation
+
+ at cindex data manipulation, in @sc{gdb/mi}
+ at cindex @sc{gdb/mi}, data manipulation
+This section describes the @sc{gdb/mi} commands that manipulate data:
+examine memory and registers, evaluate expressions, etc.
+
+ at c REMOVED FROM THE INTERFACE.
+ at c @subheading -data-assign
+ at c Change the value of a program variable. Plenty of side effects.
+ at c @subsubheading GDB command
+ at c set variable
+ at c @subsubheading Example
+ at c N.A.
+
+ at subheading The @code{-data-disassemble} Command
+ at findex -data-disassemble
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -data-disassemble
+ [ -s @var{start-addr} -e @var{end-addr} ]
+ | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
+ -- @var{mode}
+ at end smallexample
+
+ at noindent
+Where:
+
+ at table @samp
+ at item @var{start-addr}
+is the beginning address (or @code{$pc})
+ at item @var{end-addr}
+is the end address
+ at item @var{filename}
+is the name of the file to disassemble
+ at item @var{linenum}
+is the line number to disassemble around
+ at item @var{lines}
+is the the number of disassembly lines to be produced. If it is -1,
+the whole function will be disassembled, in case no @var{end-addr} is
+specified. If @var{end-addr} is specified as a non-zero value, and
+ at var{lines} is lower than the number of disassembly lines between
+ at var{start-addr} and @var{end-addr}, only @var{lines} lines are
+displayed; if @var{lines} is higher than the number of lines between
+ at var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
+are displayed.
+ at item @var{mode}
+is either 0 (meaning only disassembly) or 1 (meaning mixed source and
+disassembly).
+ at end table
+
+ at subsubheading Result
+
+The output for each instruction is composed of four fields:
+
+ at itemize @bullet
+ at item Address
+ at item Func-name
+ at item Offset
+ at item Instruction
+ at end itemize
+
+Note that whatever included in the instruction field, is not manipulated
+directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format.
+
+ at subsubheading @value{GDBN} Command
+
+There's no direct mapping from this command to the CLI.
+
+ at subsubheading Example
+
+Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
+
+ at smallexample
+(@value{GDBP})
+-data-disassemble -s $pc -e "$pc + 20" -- 0
+^done,
+asm_insns=[
+ at {address="0x000107c0",func-name="main",offset="4",
+inst="mov 2, %o0"@},
+ at {address="0x000107c4",func-name="main",offset="8",
+inst="sethi %hi(0x11800), %o2"@},
+ at {address="0x000107c8",func-name="main",offset="12",
+inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
+ at {address="0x000107cc",func-name="main",offset="16",
+inst="sethi %hi(0x11800), %o2"@},
+ at {address="0x000107d0",func-name="main",offset="20",
+inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}]
+(@value{GDBP})
+ at end smallexample
+
+Disassemble the whole @code{main} function. Line 32 is part of
+ at code{main} dot
+
+ at smallexample
+-data-disassemble -f basics.c -l 32 -- 0
+^done,asm_insns=[
+ at {address="0x000107bc",func-name="main",offset="0",
+inst="save %sp, -112, %sp"@},
+ at {address="0x000107c0",func-name="main",offset="4",
+inst="mov 2, %o0"@},
+ at {address="0x000107c4",func-name="main",offset="8",
+inst="sethi %hi(0x11800), %o2"@},
+[ at dots{}]
+ at {address="0x0001081c",func-name="main",offset="96",inst="ret "@},
+ at {address="0x00010820",func-name="main",offset="100",inst="restore "@}]
+(@value{GDBP})
+ at end smallexample
+
+Disassemble 3 instructions from the start of @code{main}:
+
+ at smallexample
+(@value{GDBP})
+-data-disassemble -f basics.c -l 32 -n 3 -- 0
+^done,asm_insns=[
+ at {address="0x000107bc",func-name="main",offset="0",
+inst="save %sp, -112, %sp"@},
+ at {address="0x000107c0",func-name="main",offset="4",
+inst="mov 2, %o0"@},
+ at {address="0x000107c4",func-name="main",offset="8",
+inst="sethi %hi(0x11800), %o2"@}]
+(@value{GDBP})
+ at end smallexample
+
+Disassemble 3 instructions from the start of @code{main} in mixed mode:
+
+ at smallexample
+(@value{GDBP})
+-data-disassemble -f basics.c -l 32 -n 3 -- 1
+^done,asm_insns=[
+src_and_asm_line= at {line="31",
+file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
+ testsuite/gdb.mi/basics.c",line_asm_insn=[
+ at {address="0x000107bc",func-name="main",offset="0",
+inst="save %sp, -112, %sp"@}] at },
+src_and_asm_line= at {line="32",
+file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
+ testsuite/gdb.mi/basics.c",line_asm_insn=[
+ at {address="0x000107c0",func-name="main",offset="4",
+inst="mov 2, %o0"@},
+ at {address="0x000107c4",func-name="main",offset="8",
+inst="sethi %hi(0x11800), %o2"@}] at }]
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-data-evaluate-expression} Command
+ at findex -data-evaluate-expression
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -data-evaluate-expression @var{expr}
+ at end smallexample
+
+Evaluate @var{expr} as an expression. The expression could contain an
+inferior function call. The function call will execute synchronously.
+If the expression contains spaces, it must be enclosed in double quotes.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
+ at samp{call} dot In @code{gdbtk} only, there's a corresponding
+ at samp{gdb_eval} command.
+
+ at subsubheading Example
+
+In the following example, the numbers that precede the commands are the
+ at dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
+Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
+output.
+
+ at smallexample
+211-data-evaluate-expression A
+211^done,value="1"
+(@value{GDBP})
+311-data-evaluate-expression &A
+311^done,value="0xefffeb7c"
+(@value{GDBP})
+411-data-evaluate-expression A+3
+411^done,value="4"
+(@value{GDBP})
+511-data-evaluate-expression "A + 3"
+511^done,value="4"
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-data-list-changed-registers} Command
+ at findex -data-list-changed-registers
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -data-list-changed-registers
+ at end smallexample
+
+Display a list of the registers that have changed.
+
+ at subsubheading @value{GDBN} Command
+
+ at value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
+has the corresponding command @samp{gdb_changed_register_list}.
+
+ at subsubheading Example
+
+On a PPC MBX board:
+
+ at smallexample
+(@value{GDBP})
+-exec-continue
+^running
+
+(@value{GDBP})
+*stopped,reason="breakpoint-hit",bkptno="1",frame= at {func="main",
+args=[],file="try.c",line="5"@}
+(@value{GDBP})
+-data-list-changed-registers
+^done,changed-registers=["0","1","2","4","5","6","7","8","9",
+"10","11","13","14","15","16","17","18","19","20","21","22","23",
+"24","25","26","27","28","30","31","64","65","66","67","69"]
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-data-list-register-names} Command
+ at findex -data-list-register-names
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -data-list-register-names [ ( @var{regno} )+ ]
+ at end smallexample
+
+Show a list of register names for the current target. If no arguments
+are given, it shows a list of the names of all the registers. If
+integer numbers are given as arguments, it will print a list of the
+names of the registers corresponding to the arguments. To ensure
+consistency between a register name and its number, the output list may
+include empty register names.
+
+ at subsubheading @value{GDBN} Command
+
+ at value{GDBN} does not have a command which corresponds to
+ at samp{-data-list-register-names} dot In @code{gdbtk} there is a
+corresponding command @samp{gdb_regnames}.
+
+ at subsubheading Example
+
+For the PPC MBX board:
+ at smallexample
+(@value{GDBP})
+-data-list-register-names
+^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
+"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
+"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
+"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
+"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
+"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
+"", "pc","ps","cr","lr","ctr","xer"]
+(@value{GDBP})
+-data-list-register-names 1 2 3
+^done,register-names=["r1","r2","r3"]
+(@value{GDBP})
+ at end smallexample
+
+ at subheading The @code{-data-list-register-values} Command
+ at findex -data-list-register-values
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -data-list-register-values @var{fmt} [ ( @var{regno} )*]
+ at end smallexample
+
+Display the registers' contents. @var{fmt} is the format according to
+which the registers' contents are to be returned, followed by an optional
+list of numbers specifying the registers to display. A missing list of
+numbers indicates that the contents of all the registers must be returned.
+
+Allowed formats for @var{fmt} are:
+
+ at table @code
+ at item x
+Hexadecimal
+ at item o
+Octal
+ at item t
+Binary
+ at item d
+Decimal
+ at item r
+Raw
+ at item N
+Natural
+ at end table
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
+all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
+
+ at subsubheading Example
+
+For a PPC MBX board (note: line breaks are for readability only, they
+don't appear in the actual output):
+
+ at smallexample
+(@value{GDBP})
+-data-list-register-values r 64 65
+^done,register-values=[ at {number="64",value="0xfe00a300"@},
+ at {number="65",value="0x00029002"@}]
+(@value{GDBP})
+-data-list-register-values x
+^done,register-values=[ at {number="0",value="0xfe0043c8"@},
+ at {number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
+ at {number="3",value="0x0"@},@{number="4",value="0xa"@},
+ at {number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
+ at {number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
+ at {number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
+ at {number="11",value="0x1"@},@{number="12",value="0x0"@},
+ at {number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
+ at {number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
+ at {number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
+ at {number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
+ at {number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
+ at {number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
+ at {number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
+ at {number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
+ at {number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
+ at {number="31",value="0x0"@},@{number="32",value="0x0"@},
+ at {number="33",value="0x0"@},@{number="34",value="0x0"@},
+ at {number="35",value="0x0"@},@{number="36",value="0x0"@},
+ at {number="37",value="0x0"@},@{number="38",value="0x0"@},
+ at {number="39",value="0x0"@},@{number="40",value="0x0"@},
+ at {number="41",value="0x0"@},@{number="42",value="0x0"@},
+ at {number="43",value="0x0"@},@{number="44",value="0x0"@},
+ at {number="45",value="0x0"@},@{number="46",value="0x0"@},
+ at {number="47",value="0x0"@},@{number="48",value="0x0"@},
+ at {number="49",value="0x0"@},@{number="50",value="0x0"@},
+ at {number="51",value="0x0"@},@{number="52",value="0x0"@},
+ at {number="53",value="0x0"@},@{number="54",value="0x0"@},
+ at {number="55",value="0x0"@},@{number="56",value="0x0"@},
+ at {number="57",value="0x0"@},@{number="58",value="0x0"@},
+ at {number="59",value="0x0"@},@{number="60",value="0x0"@},
+ at {number="61",value="0x0"@},@{number="62",value="0x0"@},
+ at {number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
+ at {number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
+ at {number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
+ at {number="69",value="0x20002b03"@}]
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-data-read-memory} Command
+ at findex -data-read-memory
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -data-read-memory [ -o @var{byte-offset} ]
+ @var{address} @var{word-format} @var{word-size}
+ @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
+ at end smallexample
+
+ at noindent
+where:
+
+ at table @samp
+ at item @var{address}
+An expression specifying the address of the first memory word to be
+read. Complex expressions containing embedded white space should be
+quoted using the C convention.
+
+ at item @var{word-format}
+The format to be used to print the memory words. The notation is the
+same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
+,Output formats}).
+
+ at item @var{word-size}
+The size of each memory word in bytes.
+
+ at item @var{nr-rows}
+The number of rows in the output table.
+
+ at item @var{nr-cols}
+The number of columns in the output table.
+
+ at item @var{aschar}
+If present, indicates that each row should include an @sc{ascii} dump. The
+value of @var{aschar} is used as a padding character when a byte is not a
+member of the printable @sc{ascii} character set (printable @sc{ascii}
+characters are those whose code is between 32 and 126, inclusively).
+
+ at item @var{byte-offset}
+An offset to add to the @var{address} before fetching memory.
+ at end table
+
+This command displays memory contents as a table of @var{nr-rows} by
+ at var{nr-cols} words, each word being @var{word-size} bytes. In total,
+ at code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
+(returned as @samp{total-bytes}). Should less than the requested number
+of bytes be returned by the target, the missing words are identified
+using @samp{N/A}. The number of bytes read from the target is returned
+in @samp{nr-bytes} and the starting address used to read memory in
+ at samp{addr} dot
+
+The address of the next/previous row or page is available in
+ at samp{next-row} and @samp{prev-row}, @samp{next-page} and
+ at samp{prev-page} dot
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
+ at samp{gdb_get_mem} memory read command.
+
+ at subsubheading Example
+
+Read six bytes of memory starting at @code{bytes+6} but then offset by
+ at code{-6} bytes. Format as three rows of two columns. One byte per
+word. Display each word in hex.
+
+ at smallexample
+(@value{GDBP})
+9-data-read-memory -o -6 -- bytes+6 x 1 3 2
+9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
+next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
+prev-page="0x0000138a",memory=[
+ at {addr="0x00001390",data=["0x00","0x01"] at },
+ at {addr="0x00001392",data=["0x02","0x03"] at },
+ at {addr="0x00001394",data=["0x04","0x05"] at }]
+(@value{GDBP})
+ at end smallexample
+
+Read two bytes of memory starting at address @code{shorts + 64} and
+display as a single word formatted in decimal.
+
+ at smallexample
+(@value{GDBP})
+5-data-read-memory shorts+64 d 2 1 1
+5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
+next-row="0x00001512",prev-row="0x0000150e",
+next-page="0x00001512",prev-page="0x0000150e",memory=[
+ at {addr="0x00001510",data=["128"] at }]
+(@value{GDBP})
+ at end smallexample
+
+Read thirty two bytes of memory starting at @code{bytes+16} and format
+as eight rows of four columns. Include a string encoding with @samp{x}
+used as the non-printable character.
+
+ at smallexample
+(@value{GDBP})
+4-data-read-memory bytes+16 x 1 8 4 x
+4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
+next-row="0x000013c0",prev-row="0x0000139c",
+next-page="0x000013c0",prev-page="0x00001380",memory=[
+ at {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@},
+ at {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@},
+ at {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@},
+ at {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@},
+ at {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@},
+ at {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@},
+ at {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@},
+ at {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}]
+(@value{GDBP})
+ at end smallexample
+
+ at subheading The @code{-display-delete} Command
+ at findex -display-delete
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -display-delete @var{number}
+ at end smallexample
+
+Delete the display @var{number}.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{delete display}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-display-disable} Command
+ at findex -display-disable
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -display-disable @var{number}
+ at end smallexample
+
+Disable display @var{number}.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{disable display}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-display-enable} Command
+ at findex -display-enable
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -display-enable @var{number}
+ at end smallexample
+
+Enable display @var{number}.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{enable display}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-display-insert} Command
+ at findex -display-insert
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -display-insert @var{expression}
+ at end smallexample
+
+Display @var{expression} every time the program stops.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{display}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-display-list} Command
+ at findex -display-list
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -display-list
+ at end smallexample
+
+List the displays. Do not show the current values.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info display}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-environment-cd} Command
+ at findex -environment-cd
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -environment-cd @var{pathdir}
+ at end smallexample
+
+Set @value{GDBN}'s working directory.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{cd}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
+^done
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-environment-directory} Command
+ at findex -environment-directory
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -environment-directory [ -r ] [ @var{pathdir} ]+
+ at end smallexample
+
+Add directories @var{pathdir} to beginning of search path for source files.
+If the @samp{-r} option is used, the search path is reset to the default
+search path. If directories @var{pathdir} are supplied in addition to the
+ at samp{-r} option, the search path is first reset and then addition
+occurs as normal.
+Multiple directories may be specified, separated by blanks. Specifying
+multiple directories in a single command
+results in the directories added to the beginning of the
+search path in the same order they were presented in the command.
+If blanks are needed as
+part of a directory name, double-quotes should be used around
+the name. In the command output, the path will show up separated
+by the system directory-separator character. The directory-seperator
+character must not be used
+in any directory name.
+If no directories are specified, the current search path is displayed.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{dir}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
+^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
+(@value{GDBP})
+-environment-directory ""
+^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
+(@value{GDBP})
+-environment-directory -r /home/jjohnstn/src/gdb /usr/src
+^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
+(@value{GDBP})
+-environment-directory -r
+^done,source-path="$cdir:$cwd"
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-environment-path} Command
+ at findex -environment-path
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -environment-path [ -r ] [ @var{pathdir} ]+
+ at end smallexample
+
+Add directories @var{pathdir} to beginning of search path for object files.
+If the @samp{-r} option is used, the search path is reset to the original
+search path that existed at gdb start-up. If directories @var{pathdir} are
+supplied in addition to the
+ at samp{-r} option, the search path is first reset and then addition
+occurs as normal.
+Multiple directories may be specified, separated by blanks. Specifying
+multiple directories in a single command
+results in the directories added to the beginning of the
+search path in the same order they were presented in the command.
+If blanks are needed as
+part of a directory name, double-quotes should be used around
+the name. In the command output, the path will show up separated
+by the system directory-separator character. The directory-seperator
+character must not be used
+in any directory name.
+If no directories are specified, the current path is displayed.
+
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{path}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-environment-path
+^done,path="/usr/bin"
+(@value{GDBP})
+-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
+^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
+(@value{GDBP})
+-environment-path -r /usr/local/bin
+^done,path="/usr/local/bin:/usr/bin"
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-environment-pwd} Command
+ at findex -environment-pwd
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -environment-pwd
+ at end smallexample
+
+Show the current working directory.
+
+ at subsubheading @value{GDBN} command
+
+The corresponding @value{GDBN} command is @samp{pwd}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-environment-pwd
+^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
+(@value{GDBP})
+ at end smallexample
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Program Control
+ at section @sc{gdb/mi} Program control
+
+ at subsubheading Program termination
+
+As a result of execution, the inferior program can run to completion, if
+it doesn't encounter any breakpoints. In this case the output will
+include an exit code, if the program has exited exceptionally.
+
+ at subsubheading Examples
+
+ at noindent
+Program exited normally:
+
+ at smallexample
+(@value{GDBP})
+-exec-run
+^running
+(@value{GDBP})
+x = 55
+*stopped,reason="exited-normally"
+(@value{GDBP})
+ at end smallexample
+
+ at noindent
+Program exited exceptionally:
+
+ at smallexample
+(@value{GDBP})
+-exec-run
+^running
+(@value{GDBP})
+x = 55
+*stopped,reason="exited",exit-code="01"
+(@value{GDBP})
+ at end smallexample
+
+Another way the program can terminate is if it receives a signal such as
+ at code{SIGINT} dot In this case, @sc{gdb/mi} displays this:
+
+ at smallexample
+(@value{GDBP})
+*stopped,reason="exited-signalled",signal-name="SIGINT",
+signal-meaning="Interrupt"
+ at end smallexample
+
+
+ at subheading The @code{-exec-abort} Command
+ at findex -exec-abort
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -exec-abort
+ at end smallexample
+
+Kill the inferior running program.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{kill}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-exec-arguments} Command
+ at findex -exec-arguments
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -exec-arguments @var{args}
+ at end smallexample
+
+Set the inferior program arguments, to be used in the next
+ at samp{-exec-run} dot
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{set args}.
+
+ at subsubheading Example
+
+ at c FIXME!
+Don't have one around.
+
+
+ at subheading The @code{-exec-continue} Command
+ at findex -exec-continue
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -exec-continue
+ at end smallexample
+
+Asynchronous command. Resumes the execution of the inferior program
+until a breakpoint is encountered, or until the inferior exits.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} corresponding is @samp{continue}.
+
+ at subsubheading Example
+
+ at smallexample
+-exec-continue
+^running
+(@value{GDBP})
+@@Hello world
+*stopped,reason="breakpoint-hit",bkptno="2",frame= at {func="foo",args=[],
+file="hello.c",line="13"@}
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-exec-finish} Command
+ at findex -exec-finish
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -exec-finish
+ at end smallexample
+
+Asynchronous command. Resumes the execution of the inferior program
+until the current function is exited. Displays the results returned by
+the function.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{finish}.
+
+ at subsubheading Example
+
+Function returning @code{void}.
+
+ at smallexample
+-exec-finish
+^running
+(@value{GDBP})
+@@hello from foo
+*stopped,reason="function-finished",frame= at {func="main",args=[],
+file="hello.c",line="7"@}
+(@value{GDBP})
+ at end smallexample
+
+Function returning other than @code{void}. The name of the internal
+ at value{GDBN} variable storing the result is printed, together with the
+value itself.
+
+ at smallexample
+-exec-finish
+^running
+(@value{GDBP})
+*stopped,reason="function-finished",frame= at {addr="0x000107b0",func="foo",
+args=[ at {name="a",value="1"],@{name="b",value="9"@} at },
+file="recursive2.c",line="14"@},
+gdb-result-var="$1",return-value="0"
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-exec-interrupt} Command
+ at findex -exec-interrupt
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -exec-interrupt
+ at end smallexample
+
+Asynchronous command. Interrupts the background execution of the target.
+Note how the token associated with the stop message is the one for the
+execution command that has been interrupted. The token for the interrupt
+itself only appears in the @samp{^done} output. If the user is trying to
+interrupt a non-running program, an error message will be printed.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{interrupt}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+111-exec-continue
+111^running
+
+(@value{GDBP})
+222-exec-interrupt
+222^done
+(@value{GDBP})
+111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
+frame= at {addr="0x00010140",func="foo",args=[],file="try.c",line="13"@}
+(@value{GDBP})
+
+(@value{GDBP})
+-exec-interrupt
+^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-exec-next} Command
+ at findex -exec-next
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -exec-next
+ at end smallexample
+
+Asynchronous command. Resumes execution of the inferior program, stopping
+when the beginning of the next source line is reached.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{next}.
+
+ at subsubheading Example
+
+ at smallexample
+-exec-next
+^running
+(@value{GDBP})
+*stopped,reason="end-stepping-range",line="8",file="hello.c"
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-exec-next-instruction} Command
+ at findex -exec-next-instruction
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -exec-next-instruction
+ at end smallexample
+
+Asynchronous command. Executes one machine instruction. If the
+instruction is a function call continues until the function returns. If
+the program stops at an instruction in the middle of a source line, the
+address will be printed as well.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{nexti}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-exec-next-instruction
+^running
+
+(@value{GDBP})
+*stopped,reason="end-stepping-range",
+addr="0x000100d4",line="5",file="hello.c"
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-exec-return} Command
+ at findex -exec-return
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -exec-return
+ at end smallexample
+
+Makes current function return immediately. Doesn't execute the inferior.
+Displays the new current frame.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{return}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+200-break-insert callee4
+200^done,bkpt= at {number="1",addr="0x00010734",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
+(@value{GDBP})
+000-exec-run
+000^running
+(@value{GDBP})
+000*stopped,reason="breakpoint-hit",bkptno="1",
+frame= at {func="callee4",args=[],
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
+(@value{GDBP})
+205-break-delete
+205^done
+(@value{GDBP})
+111-exec-return
+111^done,frame= at {level="0",func="callee3",
+args=[ at {name="strarg",
+value="0x11940 \"A string argument.\""@}],
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-exec-run} Command
+ at findex -exec-run
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -exec-run
+ at end smallexample
+
+Asynchronous command. Starts execution of the inferior from the
+beginning. The inferior executes until either a breakpoint is
+encountered or the program exits.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{run}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-break-insert main
+^done,bkpt= at {number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
+(@value{GDBP})
+-exec-run
+^running
+(@value{GDBP})
+*stopped,reason="breakpoint-hit",bkptno="1",
+frame= at {func="main",args=[],file="recursive2.c",line="4"@}
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-exec-show-arguments} Command
+ at findex -exec-show-arguments
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -exec-show-arguments
+ at end smallexample
+
+Print the arguments of the program.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{show args}.
+
+ at subsubheading Example
+N.A.
+
+ at c @subheading -exec-signal
+
+ at subheading The @code{-exec-step} Command
+ at findex -exec-step
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -exec-step
+ at end smallexample
+
+Asynchronous command. Resumes execution of the inferior program, stopping
+when the beginning of the next source line is reached, if the next
+source line is not a function call. If it is, stop at the first
+instruction of the called function.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{step}.
+
+ at subsubheading Example
+
+Stepping into a function:
+
+ at smallexample
+-exec-step
+^running
+(@value{GDBP})
+*stopped,reason="end-stepping-range",
+frame= at {func="foo",args=[ at {name="a",value="10"@},
+ at {name="b",value="0"@}],file="recursive2.c",line="11"@}
+(@value{GDBP})
+ at end smallexample
+
+Regular stepping:
+
+ at smallexample
+-exec-step
+^running
+(@value{GDBP})
+*stopped,reason="end-stepping-range",line="14",file="recursive2.c"
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-exec-step-instruction} Command
+ at findex -exec-step-instruction
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -exec-step-instruction
+ at end smallexample
+
+Asynchronous command. Resumes the inferior which executes one machine
+instruction. The output, once @value{GDBN} has stopped, will vary depending on
+whether we have stopped in the middle of a source line or not. In the
+former case, the address at which the program stopped will be printed as
+well.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{stepi}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-exec-step-instruction
+^running
+
+(@value{GDBP})
+*stopped,reason="end-stepping-range",
+frame= at {func="foo",args=[],file="try.c",line="10"@}
+(@value{GDBP})
+-exec-step-instruction
+^running
+
+(@value{GDBP})
+*stopped,reason="end-stepping-range",
+frame= at {addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@}
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-exec-until} Command
+ at findex -exec-until
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -exec-until [ @var{location} ]
+ at end smallexample
+
+Asynchronous command. Executes the inferior until the @var{location}
+specified in the argument is reached. If there is no argument, the inferior
+executes until a source line greater than the current one is reached.
+The reason for stopping in this case will be @samp{location-reached}.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{until}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-exec-until recursive2.c:6
+^running
+(@value{GDBP})
+x = 55
+*stopped,reason="location-reached",frame= at {func="main",args=[],
+file="recursive2.c",line="6"@}
+(@value{GDBP})
+ at end smallexample
+
+ at ignore
+ at subheading -file-clear
+Is this going away????
+ at end ignore
+
+
+ at subheading The @code{-file-exec-and-symbols} Command
+ at findex -file-exec-and-symbols
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -file-exec-and-symbols @var{file}
+ at end smallexample
+
+Specify the executable file to be debugged. This file is the one from
+which the symbol table is also read. If no file is specified, the
+command clears the executable and symbol information. If breakpoints
+are set when using this command with no arguments, @value{GDBN} will produce
+error messages. Otherwise, no output is produced, except a completion
+notification.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{file}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
+^done
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-file-exec-file} Command
+ at findex -file-exec-file
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -file-exec-file @var{file}
+ at end smallexample
+
+Specify the executable file to be debugged. Unlike
+ at samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
+from this file. If used without argument, @value{GDBN} clears the information
+about the executable file. No output is produced, except a completion
+notification.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{exec-file}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
+^done
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-file-list-exec-sections} Command
+ at findex -file-list-exec-sections
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -file-list-exec-sections
+ at end smallexample
+
+List the sections of the current executable file.
+
+ at subsubheading @value{GDBN} Command
+
+The @value{GDBN} command @samp{info file} shows, among the rest, the same
+information as this command. @code{gdbtk} has a corresponding command
+ at samp{gdb_load_info} dot
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-file-list-exec-source-files} Command
+ at findex -file-list-exec-source-files
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -file-list-exec-source-files
+ at end smallexample
+
+List the source files for the current executable.
+
+ at subsubheading @value{GDBN} Command
+
+There's no @value{GDBN} command which directly corresponds to this one.
+ at code{gdbtk} has an analogous command @samp{gdb_listfiles}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-file-list-shared-libraries} Command
+ at findex -file-list-shared-libraries
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -file-list-shared-libraries
+ at end smallexample
+
+List the shared libraries in the program.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info shared}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-file-list-symbol-files} Command
+ at findex -file-list-symbol-files
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -file-list-symbol-files
+ at end smallexample
+
+List symbol files.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info file} (part of it).
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-file-symbol-file} Command
+ at findex -file-symbol-file
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -file-symbol-file @var{file}
+ at end smallexample
+
+Read symbol table info from the specified @var{file} argument. When
+used without arguments, clears @value{GDBN}'s symbol table info. No output is
+produced, except for a completion notification.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{symbol-file}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
+^done
+(@value{GDBP})
+ at end smallexample
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Miscellaneous Commands
+ at section Miscellaneous @value{GDBN} commands in @sc{gdb/mi}
+
+ at c @subheading -gdb-complete
+
+ at subheading The @code{-gdb-exit} Command
+ at findex -gdb-exit
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -gdb-exit
+ at end smallexample
+
+Exit @value{GDBN} immediately.
+
+ at subsubheading @value{GDBN} Command
+
+Approximately corresponds to @samp{quit}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-gdb-exit
+ at end smallexample
+
+ at subheading The @code{-gdb-set} Command
+ at findex -gdb-set
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -gdb-set
+ at end smallexample
+
+Set an internal @value{GDBN} variable.
+ at c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{set}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-gdb-set $foo=3
+^done
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-gdb-show} Command
+ at findex -gdb-show
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -gdb-show
+ at end smallexample
+
+Show the current value of a @value{GDBN} variable.
+
+ at subsubheading @value{GDBN} command
+
+The corresponding @value{GDBN} command is @samp{show}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-gdb-show annotate
+^done,value="0"
+(@value{GDBP})
+ at end smallexample
+
+ at c @subheading -gdb-source
+
+
+ at subheading The @code{-gdb-version} Command
+ at findex -gdb-version
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -gdb-version
+ at end smallexample
+
+Show version information for @value{GDBN}. Used mostly in testing.
+
+ at subsubheading @value{GDBN} Command
+
+There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this
+information when you start an interactive session.
+
+ at subsubheading Example
+
+ at c This example modifies the actual output from GDB to avoid overfull
+ at c box in TeX.
+ at smallexample
+(@value{GDBP})
+-gdb-version
+~GNU gdb 5.2.1
+~Copyright 2000 Free Software Foundation, Inc.
+~GDB is free software, covered by the GNU General Public License, and
+~you are welcome to change it and/or distribute copies of it under
+~ certain conditions.
+~Type "show copying" to see the conditions.
+~There is absolutely no warranty for GDB. Type "show warranty" for
+~ details.
+~This GDB was configured as
+ "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
+^done
+(@value{GDBP})
+ at end smallexample
+
+ at subheading The @code{-interpreter-exec} Command
+ at findex -interpreter-exec
+
+ at subheading Synopsis
+
+ at smallexample
+-interpreter-exec @var{interpreter} @var{command}
+ at end smallexample
+
+Execute the specified @var{command} in the given @var{interpreter}.
+
+ at subheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{interpreter-exec}.
+
+ at subheading Example
+
+ at smallexample
+(@value{GDBP})
+-interpreter-exec console "break main"
+&"During symbol reading, couldn't parse type; debugger out of date?.\n"
+&"During symbol reading, bad structure-type format.\n"
+~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
+^done
+(@value{GDBP})
+ at end smallexample
+
+ at ignore
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Kod Commands
+ at section @sc{gdb/mi} Kod Commands
+
+The Kod commands are not implemented.
+
+ at c @subheading -kod-info
+
+ at c @subheading -kod-list
+
+ at c @subheading -kod-list-object-types
+
+ at c @subheading -kod-show
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Memory Overlay Commands
+ at section @sc{gdb/mi} Memory Overlay Commands
+
+The memory overlay commands are not implemented.
+
+ at c @subheading -overlay-auto
+
+ at c @subheading -overlay-list-mapping-state
+
+ at c @subheading -overlay-list-overlays
+
+ at c @subheading -overlay-map
+
+ at c @subheading -overlay-off
+
+ at c @subheading -overlay-on
+
+ at c @subheading -overlay-unmap
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Signal Handling Commands
+ at section @sc{gdb/mi} Signal Handling Commands
+
+Signal handling commands are not implemented.
+
+ at c @subheading -signal-handle
+
+ at c @subheading -signal-list-handle-actions
+
+ at c @subheading -signal-list-signal-types
+ at end ignore
+
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Stack Manipulation
+ at section @sc{gdb/mi} Stack Manipulation Commands
+
+
+ at subheading The @code{-stack-info-frame} Command
+ at findex -stack-info-frame
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -stack-info-frame
+ at end smallexample
+
+Get info on the current frame.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
+(without arguments).
+
+ at subsubheading Example
+N.A.
+
+ at subheading The @code{-stack-info-depth} Command
+ at findex -stack-info-depth
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -stack-info-depth [ @var{max-depth} ]
+ at end smallexample
+
+Return the depth of the stack. If the integer argument @var{max-depth}
+is specified, do not count beyond @var{max-depth} frames.
+
+ at subsubheading @value{GDBN} Command
+
+There's no equivalent @value{GDBN} command.
+
+ at subsubheading Example
+
+For a stack with frame levels 0 through 11:
+
+ at smallexample
+(@value{GDBP})
+-stack-info-depth
+^done,depth="12"
+(@value{GDBP})
+-stack-info-depth 4
+^done,depth="4"
+(@value{GDBP})
+-stack-info-depth 12
+^done,depth="12"
+(@value{GDBP})
+-stack-info-depth 11
+^done,depth="11"
+(@value{GDBP})
+-stack-info-depth 13
+^done,depth="12"
+(@value{GDBP})
+ at end smallexample
+
+ at subheading The @code{-stack-list-arguments} Command
+ at findex -stack-list-arguments
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -stack-list-arguments @var{show-values}
+ [ @var{low-frame} @var{high-frame} ]
+ at end smallexample
+
+Display a list of the arguments for the frames between @var{low-frame}
+and @var{high-frame} (inclusive). If @var{low-frame} and
+ at var{high-frame} are not provided, list the arguments for the whole call
+stack.
+
+The @var{show-values} argument must have a value of 0 or 1. A value of
+0 means that only the names of the arguments are listed, a value of 1
+means that both names and values of the arguments are printed.
+
+ at subsubheading @value{GDBN} Command
+
+ at value{GDBN} does not have an equivalent command. @code{gdbtk} has a
+ at samp{gdb_get_args} command which partially overlaps with the
+functionality of @samp{-stack-list-arguments}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-stack-list-frames
+^done,
+stack=[
+frame= at {level="0",addr="0x00010734",func="callee4",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
+frame= at {level="1",addr="0x0001076c",func="callee3",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
+frame= at {level="2",addr="0x0001078c",func="callee2",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
+frame= at {level="3",addr="0x000107b4",func="callee1",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
+frame= at {level="4",addr="0x000107e0",func="main",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
+(@value{GDBP})
+-stack-list-arguments 0
+^done,
+stack-args=[
+frame= at {level="0",args=[] at },
+frame= at {level="1",args=[name="strarg"] at },
+frame= at {level="2",args=[name="intarg",name="strarg"] at },
+frame= at {level="3",args=[name="intarg",name="strarg",name="fltarg"] at },
+frame= at {level="4",args=[] at }]
+(@value{GDBP})
+-stack-list-arguments 1
+^done,
+stack-args=[
+frame= at {level="0",args=[] at },
+frame= at {level="1",
+ args=[ at {name="strarg",value="0x11940 \"A string argument.\""@}] at },
+frame= at {level="2",args=[
+ at {name="intarg",value="2"@},
+ at {name="strarg",value="0x11940 \"A string argument.\""@}] at },
+ at {frame=@{level="3",args=[
+ at {name="intarg",value="2"@},
+ at {name="strarg",value="0x11940 \"A string argument.\""@},
+ at {name="fltarg",value="3.5"@}] at },
+frame= at {level="4",args=[] at }]
+(@value{GDBP})
+-stack-list-arguments 0 2 2
+^done,stack-args=[frame= at {level="2",args=[name="intarg",name="strarg"] at }]
+(@value{GDBP})
+-stack-list-arguments 1 2 2
+^done,stack-args=[frame= at {level="2",
+args=[ at {name="intarg",value="2"@},
+ at {name="strarg",value="0x11940 \"A string argument.\""@}] at }]
+(@value{GDBP})
+ at end smallexample
+
+ at c @subheading -stack-list-exception-handlers
+
+
+ at subheading The @code{-stack-list-frames} Command
+ at findex -stack-list-frames
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -stack-list-frames [ @var{low-frame} @var{high-frame} ]
+ at end smallexample
+
+List the frames currently on the stack. For each frame it displays the
+following info:
+
+ at table @samp
+ at item @var{level}
+The frame number, 0 being the topmost frame, i.e. the innermost function.
+ at item @var{addr}
+The @code{$pc} value for that frame.
+ at item @var{func}
+Function name.
+ at item @var{file}
+File name of the source file where the function lives.
+ at item @var{line}
+Line number corresponding to the @code{$pc}.
+ at end table
+
+If invoked without arguments, this command prints a backtrace for the
+whole stack. If given two integer arguments, it shows the frames whose
+levels are between the two arguments (inclusive). If the two arguments
+are equal, it shows the single frame at the corresponding level.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
+
+ at subsubheading Example
+
+Full stack backtrace:
+
+ at smallexample
+(@value{GDBP})
+-stack-list-frames
+^done,stack=
+[frame= at {level="0",addr="0x0001076c",func="foo",
+ file="recursive2.c",line="11"@},
+frame= at {level="1",addr="0x000107a4",func="foo",
+ file="recursive2.c",line="14"@},
+frame= at {level="2",addr="0x000107a4",func="foo",
+ file="recursive2.c",line="14"@},
+frame= at {level="3",addr="0x000107a4",func="foo",
+ file="recursive2.c",line="14"@},
+frame= at {level="4",addr="0x000107a4",func="foo",
+ file="recursive2.c",line="14"@},
+frame= at {level="5",addr="0x000107a4",func="foo",
+ file="recursive2.c",line="14"@},
+frame= at {level="6",addr="0x000107a4",func="foo",
+ file="recursive2.c",line="14"@},
+frame= at {level="7",addr="0x000107a4",func="foo",
+ file="recursive2.c",line="14"@},
+frame= at {level="8",addr="0x000107a4",func="foo",
+ file="recursive2.c",line="14"@},
+frame= at {level="9",addr="0x000107a4",func="foo",
+ file="recursive2.c",line="14"@},
+frame= at {level="10",addr="0x000107a4",func="foo",
+ file="recursive2.c",line="14"@},
+frame= at {level="11",addr="0x00010738",func="main",
+ file="recursive2.c",line="4"@}]
+(@value{GDBP})
+ at end smallexample
+
+Show frames between @var{low_frame} and @var{high_frame}:
+
+ at smallexample
+(@value{GDBP})
+-stack-list-frames 3 5
+^done,stack=
+[frame= at {level="3",addr="0x000107a4",func="foo",
+ file="recursive2.c",line="14"@},
+frame= at {level="4",addr="0x000107a4",func="foo",
+ file="recursive2.c",line="14"@},
+frame= at {level="5",addr="0x000107a4",func="foo",
+ file="recursive2.c",line="14"@}]
+(@value{GDBP})
+ at end smallexample
+
+Show a single frame:
+
+ at smallexample
+(@value{GDBP})
+-stack-list-frames 3 3
+^done,stack=
+[frame= at {level="3",addr="0x000107a4",func="foo",
+ file="recursive2.c",line="14"@}]
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-stack-list-locals} Command
+ at findex -stack-list-locals
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -stack-list-locals @var{print-values}
+ at end smallexample
+
+Display the local variable names for the current frame. With an
+argument of 0 prints only the names of the variables, with argument of 1
+prints also their values.
+
+ at subsubheading @value{GDBN} Command
+
+ at samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-stack-list-locals 0
+^done,locals=[name="A",name="B",name="C"]
+(@value{GDBP})
+-stack-list-locals 1
+^done,locals=[ at {name="A",value="1"@},@{name="B",value="2"@},
+ @{name="C",value="3"@}]
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-stack-select-frame} Command
+ at findex -stack-select-frame
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -stack-select-frame @var{framenum}
+ at end smallexample
+
+Change the current frame. Select a different frame @var{framenum} on
+the stack.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
+ at samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-stack-select-frame 2
+^done
+(@value{GDBP})
+ at end smallexample
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Symbol Query
+ at section @sc{gdb/mi} Symbol Query Commands
+
+
+ at subheading The @code{-symbol-info-address} Command
+ at findex -symbol-info-address
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -symbol-info-address @var{symbol}
+ at end smallexample
+
+Describe where @var{symbol} is stored.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info address}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-symbol-info-file} Command
+ at findex -symbol-info-file
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -symbol-info-file
+ at end smallexample
+
+Show the file for the symbol.
+
+ at subsubheading @value{GDBN} Command
+
+There's no equivalent @value{GDBN} command. @code{gdbtk} has
+ at samp{gdb_find_file} dot
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-symbol-info-function} Command
+ at findex -symbol-info-function
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -symbol-info-function
+ at end smallexample
+
+Show which function the symbol lives in.
+
+ at subsubheading @value{GDBN} Command
+
+ at samp{gdb_get_function} in @code{gdbtk}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-symbol-info-line} Command
+ at findex -symbol-info-line
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -symbol-info-line
+ at end smallexample
+
+Show the core addresses of the code for a source line.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} comamnd is @samp{info line}.
+ at code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-symbol-info-symbol} Command
+ at findex -symbol-info-symbol
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -symbol-info-symbol @var{addr}
+ at end smallexample
+
+Describe what symbol is at location @var{addr}.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info symbol}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-symbol-list-functions} Command
+ at findex -symbol-list-functions
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -symbol-list-functions
+ at end smallexample
+
+List the functions in the executable.
+
+ at subsubheading @value{GDBN} Command
+
+ at samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
+ at samp{gdb_search} in @code{gdbtk}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-symbol-list-types} Command
+ at findex -symbol-list-types
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -symbol-list-types
+ at end smallexample
+
+List all the type names.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding commands are @samp{info types} in @value{GDBN},
+ at samp{gdb_search} in @code{gdbtk}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-symbol-list-variables} Command
+ at findex -symbol-list-variables
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -symbol-list-variables
+ at end smallexample
+
+List all the global and static variable names.
+
+ at subsubheading @value{GDBN} Command
+
+ at samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-symbol-locate} Command
+ at findex -symbol-locate
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -symbol-locate
+ at end smallexample
+
+ at subsubheading @value{GDBN} Command
+
+ at samp{gdb_loc} in @code{gdbtk}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-symbol-type} Command
+ at findex -symbol-type
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -symbol-type @var{variable}
+ at end smallexample
+
+Show type of @var{variable}.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
+ at samp{gdb_obj_variable} dot
+
+ at subsubheading Example
+N.A.
+
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Target Manipulation
+ at section @sc{gdb/mi} Target Manipulation Commands
+
+
+ at subheading The @code{-target-attach} Command
+ at findex -target-attach
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -target-attach @var{pid} | @var{file}
+ at end smallexample
+
+Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
+
+ at subsubheading @value{GDBN} command
+
+The corresponding @value{GDBN} command is @samp{attach}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-target-compare-sections} Command
+ at findex -target-compare-sections
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -target-compare-sections [ @var{section} ]
+ at end smallexample
+
+Compare data of section @var{section} on target to the exec file.
+Without the argument, all sections are compared.
+
+ at subsubheading @value{GDBN} Command
+
+The @value{GDBN} equivalent is @samp{compare-sections}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-target-detach} Command
+ at findex -target-detach
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -target-detach
+ at end smallexample
+
+Disconnect from the remote target. There's no output.
+
+ at subsubheading @value{GDBN} command
+
+The corresponding @value{GDBN} command is @samp{detach}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-target-detach
+^done
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-target-download} Command
+ at findex -target-download
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -target-download
+ at end smallexample
+
+Loads the executable onto the remote target.
+It prints out an update message every half second, which includes the fields:
+
+ at table @samp
+ at item section
+The name of the section.
+ at item section-sent
+The size of what has been sent so far for that section.
+ at item section-size
+The size of the section.
+ at item total-sent
+The total size of what was sent so far (the current and the previous sections).
+ at item total-size
+The size of the overall executable to download.
+ at end table
+
+ at noindent
+Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
+ at sc{gdb/mi} Output Syntax}).
+
+In addition, it prints the name and size of the sections, as they are
+downloaded. These messages include the following fields:
+
+ at table @samp
+ at item section
+The name of the section.
+ at item section-size
+The size of the section.
+ at item total-size
+The size of the overall executable to download.
+ at end table
+
+ at noindent
+At the end, a summary is printed.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{load}.
+
+ at subsubheading Example
+
+Note: each status message appears on a single line. Here the messages
+have been broken down so that they can fit onto a page.
+
+ at smallexample
+(@value{GDBP})
+-target-download
++download,@{section=".text",section-size="6668",total-size="9880"@}
++download,@{section=".text",section-sent="512",section-size="6668",
+total-sent="512",total-size="9880"@}
++download,@{section=".text",section-sent="1024",section-size="6668",
+total-sent="1024",total-size="9880"@}
++download,@{section=".text",section-sent="1536",section-size="6668",
+total-sent="1536",total-size="9880"@}
++download,@{section=".text",section-sent="2048",section-size="6668",
+total-sent="2048",total-size="9880"@}
++download,@{section=".text",section-sent="2560",section-size="6668",
+total-sent="2560",total-size="9880"@}
++download,@{section=".text",section-sent="3072",section-size="6668",
+total-sent="3072",total-size="9880"@}
++download,@{section=".text",section-sent="3584",section-size="6668",
+total-sent="3584",total-size="9880"@}
++download,@{section=".text",section-sent="4096",section-size="6668",
+total-sent="4096",total-size="9880"@}
++download,@{section=".text",section-sent="4608",section-size="6668",
+total-sent="4608",total-size="9880"@}
++download,@{section=".text",section-sent="5120",section-size="6668",
+total-sent="5120",total-size="9880"@}
++download,@{section=".text",section-sent="5632",section-size="6668",
+total-sent="5632",total-size="9880"@}
++download,@{section=".text",section-sent="6144",section-size="6668",
+total-sent="6144",total-size="9880"@}
++download,@{section=".text",section-sent="6656",section-size="6668",
+total-sent="6656",total-size="9880"@}
++download,@{section=".init",section-size="28",total-size="9880"@}
++download,@{section=".fini",section-size="28",total-size="9880"@}
++download,@{section=".data",section-size="3156",total-size="9880"@}
++download,@{section=".data",section-sent="512",section-size="3156",
+total-sent="7236",total-size="9880"@}
++download,@{section=".data",section-sent="1024",section-size="3156",
+total-sent="7748",total-size="9880"@}
++download,@{section=".data",section-sent="1536",section-size="3156",
+total-sent="8260",total-size="9880"@}
++download,@{section=".data",section-sent="2048",section-size="3156",
+total-sent="8772",total-size="9880"@}
++download,@{section=".data",section-sent="2560",section-size="3156",
+total-sent="9284",total-size="9880"@}
++download,@{section=".data",section-sent="3072",section-size="3156",
+total-sent="9796",total-size="9880"@}
+^done,address="0x10004",load-size="9880",transfer-rate="6586",
+write-rate="429"
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-target-exec-status} Command
+ at findex -target-exec-status
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -target-exec-status
+ at end smallexample
+
+Provide information on the state of the target (whether it is running or
+not, for instance).
+
+ at subsubheading @value{GDBN} Command
+
+There's no equivalent @value{GDBN} command.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-target-list-available-targets} Command
+ at findex -target-list-available-targets
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -target-list-available-targets
+ at end smallexample
+
+List the possible targets to connect to.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{help target}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-target-list-current-targets} Command
+ at findex -target-list-current-targets
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -target-list-current-targets
+ at end smallexample
+
+Describe the current target.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding information is printed by @samp{info file} (among
+other things).
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-target-list-parameters} Command
+ at findex -target-list-parameters
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -target-list-parameters
+ at end smallexample
+
+ at c ????
+
+ at subsubheading @value{GDBN} Command
+
+No equivalent.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-target-select} Command
+ at findex -target-select
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -target-select @var{type} @var{parameters @dots{}}
+ at end smallexample
+
+Connect @value{GDBN} to the remote target. This command takes two args:
+
+ at table @samp
+ at item @var{type}
+The type of target, for instance @samp{async}, @samp{remote}, etc.
+ at item @var{parameters}
+Device names, host names and the like. @xref{Target Commands, ,
+Commands for managing targets}, for more details.
+ at end table
+
+The output is a connection notification, followed by the address at
+which the target program is, in the following form:
+
+ at smallexample
+^connected,addr="@var{address}",func="@var{function name}",
+ args=[ at var{arg list}]
+ at end smallexample
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{target}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-target-select async /dev/ttya
+^connected,addr="0xfe00a300",func="??",args=[]
+(@value{GDBP})
+ at end smallexample
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Thread Commands
+ at section @sc{gdb/mi} Thread Commands
+
+
+ at subheading The @code{-thread-info} Command
+ at findex -thread-info
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -thread-info
+ at end smallexample
+
+ at subsubheading @value{GDBN} command
+
+No equivalent.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-thread-list-all-threads} Command
+ at findex -thread-list-all-threads
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -thread-list-all-threads
+ at end smallexample
+
+ at subsubheading @value{GDBN} Command
+
+The equivalent @value{GDBN} command is @samp{info threads}.
+
+ at subsubheading Example
+N.A.
+
+
+ at subheading The @code{-thread-list-ids} Command
+ at findex -thread-list-ids
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -thread-list-ids
+ at end smallexample
+
+Produces a list of the currently known @value{GDBN} thread ids. At the
+end of the list it also prints the total number of such threads.
+
+ at subsubheading @value{GDBN} Command
+
+Part of @samp{info threads} supplies the same information.
+
+ at subsubheading Example
+
+No threads present, besides the main process:
+
+ at smallexample
+(@value{GDBP})
+-thread-list-ids
+^done,thread-ids= at {@},number-of-threads="0"
+(@value{GDBP})
+ at end smallexample
+
+
+Several threads:
+
+ at smallexample
+(@value{GDBP})
+-thread-list-ids
+^done,thread-ids= at {thread-id="3",thread-id="2",thread-id="1"@},
+number-of-threads="3"
+(@value{GDBP})
+ at end smallexample
+
+
+ at subheading The @code{-thread-select} Command
+ at findex -thread-select
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -thread-select @var{threadnum}
+ at end smallexample
+
+Make @var{threadnum} the current thread. It prints the number of the new
+current thread, and the topmost frame for that thread.
+
+ at subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{thread}.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-exec-next
+^running
+(@value{GDBP})
+*stopped,reason="end-stepping-range",thread-id="2",line="187",
+file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
+(@value{GDBP})
+-thread-list-ids
+^done,
+thread-ids= at {thread-id="3",thread-id="2",thread-id="1"@},
+number-of-threads="3"
+(@value{GDBP})
+-thread-select 3
+^done,new-thread-id="3",
+frame= at {level="0",func="vprintf",
+args=[ at {name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
+ at {name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
+(@value{GDBP})
+ at end smallexample
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Tracepoint Commands
+ at section @sc{gdb/mi} Tracepoint Commands
+
+The tracepoint commands are not yet implemented.
+
+ at c @subheading -trace-actions
+
+ at c @subheading -trace-delete
+
+ at c @subheading -trace-disable
+
+ at c @subheading -trace-dump
+
+ at c @subheading -trace-enable
+
+ at c @subheading -trace-exists
+
+ at c @subheading -trace-find
+
+ at c @subheading -trace-frame-number
+
+ at c @subheading -trace-info
+
+ at c @subheading -trace-insert
+
+ at c @subheading -trace-list
+
+ at c @subheading -trace-pass-count
+
+ at c @subheading -trace-save
+
+ at c @subheading -trace-start
+
+ at c @subheading -trace-stop
+
+
+ at c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ at node GDB/MI Variable Objects
+ at section @sc{gdb/mi} Variable Objects
+
+
+ at subheading Motivation for Variable Objects in @sc{gdb/mi}
+
+For the implementation of a variable debugger window (locals, watched
+expressions, etc.), we are proposing the adaptation of the existing code
+used by @code{Insight}.
+
+The two main reasons for that are:
+
+ at enumerate 1
+ at item
+It has been proven in practice (it is already on its second generation).
+
+ at item
+It will shorten development time (needless to say how important it is
+now).
+ at end enumerate
+
+The original interface was designed to be used by Tcl code, so it was
+slightly changed so it could be used through @sc{gdb/mi}. This section
+describes the @sc{gdb/mi} operations that will be available and gives some
+hints about their use.
+
+ at emph{Note}: In addition to the set of operations described here, we
+expect the @sc{gui} implementation of a variable window to require, at
+least, the following operations:
+
+ at itemize @bullet
+ at item @code{-gdb-show} @code{output-radix}
+ at item @code{-stack-list-arguments}
+ at item @code{-stack-list-locals}
+ at item @code{-stack-select-frame}
+ at end itemize
+
+ at subheading Introduction to Variable Objects in @sc{gdb/mi}
+
+ at cindex variable objects in @sc{gdb/mi}
+The basic idea behind variable objects is the creation of a named object
+to represent a variable, an expression, a memory location or even a CPU
+register. For each object created, a set of operations is available for
+examining or changing its properties.
+
+Furthermore, complex data types, such as C structures, are represented
+in a tree format. For instance, the @code{struct} type variable is the
+root and the children will represent the struct members. If a child
+is itself of a complex type, it will also have children of its own.
+Appropriate language differences are handled for C, C at t{++} and Java.
+
+When returning the actual values of the objects, this facility allows
+for the individual selection of the display format used in the result
+creation. It can be chosen among: binary, decimal, hexadecimal, octal
+and natural. Natural refers to a default format automatically
+chosen based on the variable type (like decimal for an @code{int}, hex
+for pointers, etc.).
+
+The following is the complete set of @sc{gdb/mi} operations defined to
+access this functionality:
+
+ at multitable @columnfractions .4 .6
+ at item @strong{Operation}
+ at tab @strong{Description}
+
+ at item @code{-var-create}
+ at tab create a variable object
+ at item @code{-var-delete}
+ at tab delete the variable object and its children
+ at item @code{-var-set-format}
+ at tab set the display format of this variable
+ at item @code{-var-show-format}
+ at tab show the display format of this variable
+ at item @code{-var-info-num-children}
+ at tab tells how many children this object has
+ at item @code{-var-list-children}
+ at tab return a list of the object's children
+ at item @code{-var-info-type}
+ at tab show the type of this variable object
+ at item @code{-var-info-expression}
+ at tab print what this variable object represents
+ at item @code{-var-show-attributes}
+ at tab is this variable editable? does it exist here?
+ at item @code{-var-evaluate-expression}
+ at tab get the value of this variable
+ at item @code{-var-assign}
+ at tab set the value of this variable
+ at item @code{-var-update}
+ at tab update the variable and its children
+ at end multitable
+
+In the next subsection we describe each operation in detail and suggest
+how it can be used.
+
+ at subheading Description And Use of Operations on Variable Objects
+
+ at subheading The @code{-var-create} Command
+ at findex -var-create
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -var-create @{ at var{name} | "-"@}
+ @{ at var{frame-addr} | "*"@} @var{expression}
+ at end smallexample
+
+This operation creates a variable object, which allows the monitoring of
+a variable, the result of an expression, a memory cell or a CPU
+register.
+
+The @var{name} parameter is the string by which the object can be
+referenced. It must be unique. If @samp{-} is specified, the varobj
+system will generate a string ``varNNNNNN'' automatically. It will be
+unique provided that one does not specify @var{name} on that format.
+The command fails if a duplicate name is found.
+
+The frame under which the expression should be evaluated can be
+specified by @var{frame-addr}. A @samp{*} indicates that the current
+frame should be used.
+
+ at var{expression} is any expression valid on the current language set (must not
+begin with a @samp{*}), or one of the following:
+
+ at itemize @bullet
+ at item
+ at samp{*@var{addr}}, where @var{addr} is the address of a memory cell
+
+ at item
+ at samp{*@var{addr}- at var{addr}} --- a memory address range (TBD)
+
+ at item
+ at samp{$@var{regname}} --- a CPU register name
+ at end itemize
+
+ at subsubheading Result
+
+This operation returns the name, number of children and the type of the
+object created. Type is returned as a string as the ones generated by
+the @value{GDBN} CLI:
+
+ at smallexample
+ name="@var{name}",numchild="N",type="@var{type}"
+ at end smallexample
+
+
+ at subheading The @code{-var-delete} Command
+ at findex -var-delete
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -var-delete @var{name}
+ at end smallexample
+
+Deletes a previously created variable object and all of its children.
+
+Returns an error if the object @var{name} is not found.
+
+
+ at subheading The @code{-var-set-format} Command
+ at findex -var-set-format
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -var-set-format @var{name} @var{format-spec}
+ at end smallexample
+
+Sets the output format for the value of the object @var{name} to be
+ at var{format-spec} dot
+
+The syntax for the @var{format-spec} is as follows:
+
+ at smallexample
+ @var{format-spec} @expansion{}
+ @{binary | decimal | hexadecimal | octal | natural at }
+ at end smallexample
+
+
+ at subheading The @code{-var-show-format} Command
+ at findex -var-show-format
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -var-show-format @var{name}
+ at end smallexample
+
+Returns the format used to display the value of the object @var{name}.
+
+ at smallexample
+ @var{format} @expansion{}
+ @var{format-spec}
+ at end smallexample
+
+
+ at subheading The @code{-var-info-num-children} Command
+ at findex -var-info-num-children
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -var-info-num-children @var{name}
+ at end smallexample
+
+Returns the number of children of a variable object @var{name}:
+
+ at smallexample
+ numchild= at var{n}
+ at end smallexample
+
+
+ at subheading The @code{-var-list-children} Command
+ at findex -var-list-children
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -var-list-children @var{name}
+ at end smallexample
+
+Returns a list of the children of the specified variable object:
+
+ at smallexample
+ numchild= at var{n},children=[ at {name=@var{name},
+ numchild= at var{n},type= at var{type}@},@r{(repeats N times)}]
+ at end smallexample
+
+
+ at subheading The @code{-var-info-type} Command
+ at findex -var-info-type
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -var-info-type @var{name}
+ at end smallexample
+
+Returns the type of the specified variable @var{name}. The type is
+returned as a string in the same format as it is output by the
+ at value{GDBN} CLI:
+
+ at smallexample
+ type= at var{typename}
+ at end smallexample
+
+
+ at subheading The @code{-var-info-expression} Command
+ at findex -var-info-expression
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -var-info-expression @var{name}
+ at end smallexample
+
+Returns what is represented by the variable object @var{name}:
+
+ at smallexample
+ lang= at var{lang-spec},exp= at var{expression}
+ at end smallexample
+
+ at noindent
+where @var{lang-spec} is @code{ at {"C" | "C++" | "Java"@}}.
+
+ at subheading The @code{-var-show-attributes} Command
+ at findex -var-show-attributes
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -var-show-attributes @var{name}
+ at end smallexample
+
+List attributes of the specified variable object @var{name}:
+
+ at smallexample
+ status= at var{attr} [ ( ,@var{attr} )* ]
+ at end smallexample
+
+ at noindent
+where @var{attr} is @code{ at { @{ editable | noneditable @} | TBD @}}.
+
+ at subheading The @code{-var-evaluate-expression} Command
+ at findex -var-evaluate-expression
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -var-evaluate-expression @var{name}
+ at end smallexample
+
+Evaluates the expression that is represented by the specified variable
+object and returns its value as a string in the current format specified
+for the object:
+
+ at smallexample
+ value= at var{value}
+ at end smallexample
+
+Note that one must invoke @code{-var-list-children} for a variable
+before the value of a child variable can be evaluated.
+
+ at subheading The @code{-var-assign} Command
+ at findex -var-assign
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -var-assign @var{name} @var{expression}
+ at end smallexample
+
+Assigns the value of @var{expression} to the variable object specified
+by @var{name}. The object must be @samp{editable}. If the variable's
+value is altered by the assign, the variable will show up in any
+subsequent @code{-var-update} list.
+
+ at subsubheading Example
+
+ at smallexample
+(@value{GDBP})
+-var-assign var1 3
+^done,value="3"
+(@value{GDBP})
+-var-update *
+^done,changelist=[ at {name="var1",in_scope="true",type_changed="false"@}]
+(@value{GDBP})
+ at end smallexample
+
+ at subheading The @code{-var-update} Command
+ at findex -var-update
+
+ at subsubheading Synopsis
+
+ at smallexample
+ -var-update @{ at var{name} | "*"@}
+ at end smallexample
+
+Update the value of the variable object @var{name} by evaluating its
+expression after fetching all the new values from memory or registers.
+A @samp{*} causes all existing variable objects to be updated.
+
+
+ at node Annotations
+ at chapter @value{GDBN} Annotations
+
+This chapter describes annotations in @value{GDBN}. Annotations are
+designed to interface @value{GDBN} to graphical user interfaces or
+other similar programs which want to interact with @value{GDBN} at a
+relatively high level.
+
+ at ignore
+This is Edition @value{EDITION}, @value{DATE}.
+ at end ignore
+
+ at menu
+* Annotations Overview:: What annotations are; the general syntax.
+* Server Prefix:: Issuing a command without affecting user state.
+* Value Annotations:: Values are marked as such.
+* Frame Annotations:: Stack frames are annotated.
+* Displays:: @value{GDBN} can be told to display something periodically.
+* Prompting:: Annotations marking @value{GDBN}'s need for input.
+* Errors:: Annotations for error messages.
+* Breakpoint Info:: Information on breakpoints.
+* Invalidation:: Some annotations describe things now invalid.
+* Annotations for Running::
+ Whether the program is running, how it stopped, etc.
+* Source Annotations:: Annotations describing source code.
+* TODO:: Annotations which might be added in the future.
+ at end menu
+
+ at node Annotations Overview
+ at section What is an Annotation?
+ at cindex annotations
+
+To produce annotations, start @value{GDBN} with the @code{--annotate=2} option.
+
+Annotations start with a newline character, two @samp{control-z}
+characters, and the name of the annotation. If there is no additional
+information associated with this annotation, the name of the annotation
+is followed immediately by a newline. If there is additional
+information, the name of the annotation is followed by a space, the
+additional information, and a newline. The additional information
+cannot contain newline characters.
+
+Any output not beginning with a newline and two @samp{control-z}
+characters denotes literal output from @value{GDBN}. Currently there is
+no need for @value{GDBN} to output a newline followed by two
+ at samp{control-z} characters, but if there was such a need, the
+annotations could be extended with an @samp{escape} annotation which
+means those three characters as output.
+
+A simple example of starting up @value{GDBN} with annotations is:
+
+ at smallexample
+$ gdb --annotate=2
+GNU GDB 5.0
+Copyright 2000 Free Software Foundation, Inc.
+GDB is free software, covered by the GNU General Public License,
+and you are welcome to change it and/or distribute copies of it
+under certain conditions.
+Type "show copying" to see the conditions.
+There is absolutely no warranty for GDB. Type "show warranty"
+for details.
+This GDB was configured as "sparc-sun-sunos4.1.3"
+
+^Z^Zpre-prompt
+(gdb)
+^Z^Zprompt
+quit
+
+^Z^Zpost-prompt
+$
+ at end smallexample
+
+Here @samp{quit} is input to @value{GDBN}; the rest is output from
+ at value{GDBN} dot The three lines beginning @samp{^Z^Z} (where @samp{^Z}
+denotes a @samp{control-z} character) are annotations; the rest is
+output from @value{GDBN}.
+
+ at node Server Prefix
+ at section The Server Prefix
+ at cindex server prefix for annotations
+
+To issue a command to @value{GDBN} without affecting certain aspects of
+the state which is seen by users, prefix it with @samp{server }. This
+means that this command will not affect the command history, nor will it
+affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
+pressed on a line by itself.
+
+The server prefix does not affect the recording of values into the value
+history; to print a value without recording it into the value history,
+use the @code{output} command instead of the @code{print} command.
+
+ at node Value Annotations
+ at section Values
+
+ at cindex annotations for values
+When a value is printed in various contexts, @value{GDBN} uses
+annotations to delimit the value from the surrounding text.
+
+ at findex value-history-begin
+ at findex value-history-value
+ at findex value-history-end
+If a value is printed using @code{print} and added to the value history,
+the annotation looks like
+
+ at smallexample
+^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
+ at var{history-string}
+^Z^Zvalue-history-value
+ at var{the-value}
+^Z^Zvalue-history-end
+ at end smallexample
+
+ at noindent
+where @var{history-number} is the number it is getting in the value
+history, @var{history-string} is a string, such as @samp{$5 = }, which
+introduces the value to the user, @var{the-value} is the output
+corresponding to the value itself, and @var{value-flags} is @samp{*} for
+a value which can be dereferenced and @samp{-} for a value which cannot.
+
+ at findex value-begin
+ at findex value-end
+If the value is not added to the value history (it is an invalid float
+or it is printed with the @code{output} command), the annotation is similar:
+
+ at smallexample
+^Z^Zvalue-begin @var{value-flags}
+ at var{the-value}
+^Z^Zvalue-end
+ at end smallexample
+
+ at findex arg-begin
+ at findex arg-name-end
+ at findex arg-value
+ at findex arg-end
+When @value{GDBN} prints an argument to a function (for example, in the output
+from the @code{backtrace} command), it annotates it as follows:
+
+ at smallexample
+^Z^Zarg-begin
+ at var{argument-name}
+^Z^Zarg-name-end
+ at var{separator-string}
+^Z^Zarg-value @var{value-flags}
+ at var{the-value}
+^Z^Zarg-end
+ at end smallexample
+
+ at noindent
+where @var{argument-name} is the name of the argument,
+ at var{separator-string} is text which separates the name from the value
+for the user's benefit (such as @samp{=}), and @var{value-flags} and
+ at var{the-value} have the same meanings as in a
+ at code{value-history-begin} annotation.
+
+ at findex field-begin
+ at findex field-name-end
+ at findex field-value
+ at findex field-end
+When printing a structure, @value{GDBN} annotates it as follows:
+
+ at smallexample
+^Z^Zfield-begin @var{value-flags}
+ at var{field-name}
+^Z^Zfield-name-end
+ at var{separator-string}
+^Z^Zfield-value
+ at var{the-value}
+^Z^Zfield-end
+ at end smallexample
+
+ at noindent
+where @var{field-name} is the name of the field, @var{separator-string}
+is text which separates the name from the value for the user's benefit
+(such as @samp{=}), and @var{value-flags} and @var{the-value} have the
+same meanings as in a @code{value-history-begin} annotation.
+
+When printing an array, @value{GDBN} annotates it as follows:
+
+ at smallexample
+^Z^Zarray-section-begin @var{array-index} @var{value-flags}
+ at end smallexample
+
+ at noindent
+where @var{array-index} is the index of the first element being
+annotated and @var{value-flags} has the same meaning as in a
+ at code{value-history-begin} annotation. This is followed by any number
+of elements, where is element can be either a single element:
+
+ at findex elt
+ at smallexample
+ at samp{,} @var{whitespace} ; @r{omitted for the first element}
+ at var{the-value}
+^Z^Zelt
+ at end smallexample
+
+or a repeated element
+
+ at findex elt-rep
+ at findex elt-rep-end
+ at smallexample
+ at samp{,} @var{whitespace} ; @r{omitted for the first element}
+ at var{the-value}
+^Z^Zelt-rep @var{number-of-repetitions}
+ at var{repetition-string}
+^Z^Zelt-rep-end
+ at end smallexample
+
+In both cases, @var{the-value} is the output for the value of the
+element and @var{whitespace} can contain spaces, tabs, and newlines. In
+the repeated case, @var{number-of-repetitions} is the number of
+consecutive array elements which contain that value, and
+ at var{repetition-string} is a string which is designed to convey to the
+user that repetition is being depicted.
+
+ at findex array-section-end
+Once all the array elements have been output, the array annotation is
+ended with
+
+ at smallexample
+^Z^Zarray-section-end
+ at end smallexample
+
+ at node Frame Annotations
+ at section Frames
+
+ at cindex annotations for frames
+Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies
+to frames printed when @value{GDBN} stops, output from commands such as
+ at code{backtrace} or @code{up}, etc.
+
+ at findex frame-begin
+The frame annotation begins with
+
+ at smallexample
+^Z^Zframe-begin @var{level} @var{address}
+ at var{level-string}
+ at end smallexample
+
+ at noindent
+where @var{level} is the number of the frame (0 is the innermost frame,
+and other frames have positive numbers), @var{address} is the address of
+the code executing in that frame, and @var{level-string} is a string
+designed to convey the level to the user. @var{address} is in the form
+ at samp{0x} followed by one or more lowercase hex digits (note that this
+does not depend on the language). The frame ends with
+
+ at findex frame-end
+ at smallexample
+^Z^Zframe-end
+ at end smallexample
+
+Between these annotations is the main body of the frame, which can
+consist of
+
+ at itemize @bullet
+ at item
+ at findex function-call
+ at smallexample
+^Z^Zfunction-call
+ at var{function-call-string}
+ at end smallexample
+
+where @var{function-call-string} is text designed to convey to the user
+that this frame is associated with a function call made by @value{GDBN} to a
+function in the program being debugged.
+
+ at item
+ at findex signal-handler-caller
+ at smallexample
+^Z^Zsignal-handler-caller
+ at var{signal-handler-caller-string}
+ at end smallexample
+
+where @var{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).
+
+ at item
+A normal frame.
+
+ at findex frame-address
+ at findex frame-address-end
+This can optionally (depending on whether this is thought of as
+interesting information for the user to see) begin with
+
+ at smallexample
+^Z^Zframe-address
+ at var{address}
+^Z^Zframe-address-end
+ at var{separator-string}
+ at end smallexample
+
+where @var{address} is the address executing in the frame (the same
+address as in the @code{frame-begin} annotation, but printed in a form
+which is intended for user consumption---in particular, the syntax varies
+depending on the language), and @var{separator-string} is a string
+intended to separate this address from what follows for the user's
+benefit.
+
+ at findex frame-function-name
+ at findex frame-args
+Then comes
+
+ at smallexample
+^Z^Zframe-function-name
+ at var{function-name}
+^Z^Zframe-args
+ at var{arguments}
+ at end smallexample
+
+where @var{function-name} is the name of the function executing in the
+frame, or @samp{??} if not known, and @var{arguments} are the arguments
+to the frame, with parentheses around them (each argument is annotated
+individually as well, @pxref{Value Annotations}).
+
+ at findex frame-source-begin
+ at findex frame-source-file
+ at findex frame-source-file-end
+ at findex frame-source-line
+ at findex frame-source-end
+If source information is available, a reference to it is then printed:
+
+ at smallexample
+^Z^Zframe-source-begin
+ at var{source-intro-string}
+^Z^Zframe-source-file
+ at var{filename}
+^Z^Zframe-source-file-end
+:
+^Z^Zframe-source-line
+ at var{line-number}
+^Z^Zframe-source-end
+ at end smallexample
+
+where @var{source-intro-string} separates for the user's benefit the
+reference from the text which precedes it, @var{filename} is the name of
+the source file, and @var{line-number} is the line number within that
+file (the first line is line 1).
+
+ at findex frame-where
+If @value{GDBN} 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
+
+ at smallexample
+^Z^Zframe-where
+ at var{information}
+ at end smallexample
+
+Then, if source is to actually be displayed for this frame (for example,
+this is not true for output from the @code{backtrace} command), then a
+ at code{source} annotation (@pxref{Source Annotations}) is displayed. Unlike
+most annotations, this is output instead of the normal text which would be
+output, not in addition.
+ at end itemize
+
+ at node Displays
+ at section Displays
+
+ at findex display-begin
+ at findex display-number-end
+ at findex display-format
+ at findex display-expression
+ at findex display-expression-end
+ at findex display-value
+ at findex display-end
+ at cindex annotations for display
+When @value{GDBN} is told to display something using the @code{display} command,
+the results of the display are annotated:
+
+ at smallexample
+^Z^Zdisplay-begin
+ at var{number}
+^Z^Zdisplay-number-end
+ at var{number-separator}
+^Z^Zdisplay-format
+ at var{format}
+^Z^Zdisplay-expression
+ at var{expression}
+^Z^Zdisplay-expression-end
+ at var{expression-separator}
+^Z^Zdisplay-value
+ at var{value}
+^Z^Zdisplay-end
+ at end smallexample
+
+ at noindent
+where @var{number} is the number of the display, @var{number-separator}
+is intended to separate the number from what follows for the user,
+ at var{format} includes information such as the size, format, or other
+information about how the value is being displayed, @var{expression} is
+the expression being displayed, @var{expression-separator} is intended
+to separate the expression from the text that follows for the user,
+and @var{value} is the actual value being displayed.
+
+ at node Prompting
+ at section Annotation for @value{GDBN} Input
+
+ at cindex annotations for prompts
+When @value{GDBN} 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 @dfn{input type}. Each
+input type has three annotations: a @code{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 @code{post-}
+annotation which denotes the end of any echo which may (or may not) be
+associated with the input. For example, the @code{prompt} input type
+features the following annotations:
+
+ at smallexample
+^Z^Zpre-prompt
+^Z^Zprompt
+^Z^Zpost-prompt
+ at end smallexample
+
+The input types are
+
+ at table @code
+ at findex pre-prompt
+ at findex prompt
+ at findex post-prompt
+ at item prompt
+When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
+
+ at findex pre-commands
+ at findex commands
+ at findex post-commands
+ at item commands
+When @value{GDBN} prompts for a set of commands, like in the @code{commands}
+command. The annotations are repeated for each command which is input.
+
+ at findex pre-overload-choice
+ at findex overload-choice
+ at findex post-overload-choice
+ at item overload-choice
+When @value{GDBN} wants the user to select between various overloaded functions.
+
+ at findex pre-query
+ at findex query
+ at findex post-query
+ at item query
+When @value{GDBN} wants the user to confirm a potentially dangerous operation.
+
+ at findex pre-prompt-for-continue
+ at findex prompt-for-continue
+ at findex post-prompt-for-continue
+ at item prompt-for-continue
+When @value{GDBN} is asking the user to press return to continue. Note: Don't
+expect this to work well; instead use @code{set height 0} to disable
+prompting. This is because the counting of lines is buggy in the
+presence of annotations.
+ at end table
+
+ at node Errors
+ at section Errors
+ at cindex annotations for errors, warnings and interrupts
+
+ at findex quit
+ at smallexample
+^Z^Zquit
+ at end smallexample
+
+This annotation occurs right before @value{GDBN} responds to an interrupt.
+
+ at findex error
+ at smallexample
+^Z^Zerror
+ at end smallexample
+
+This annotation occurs right before @value{GDBN} responds to an error.
+
+Quit and error annotations indicate that any annotations which @value{GDBN} was
+in the middle of may end abruptly. For example, if a
+ at code{value-history-begin} annotation is followed by a @code{error}, one
+cannot expect to receive the matching @code{value-history-end}. One
+cannot expect not to receive it either, however; an error annotation
+does not necessarily mean that @value{GDBN} is immediately returning all the way
+to the top level.
+
+ at findex error-begin
+A quit or error annotation may be preceded by
+
+ at smallexample
+^Z^Zerror-begin
+ at end smallexample
+
+Any output between that and the quit or error annotation is the error
+message.
+
+Warning messages are not yet annotated.
+ at c If we want to change that, need to fix warning(), type_error(),
+ at c range_error(), and possibly other places.
+
+ at node Breakpoint Info
+ at section Information on Breakpoints
+
+ at cindex annotations for breakpoints
+The output from the @code{info breakpoints} command is annotated as follows:
+
+ at findex breakpoints-headers
+ at findex breakpoints-table
+ at smallexample
+^Z^Zbreakpoints-headers
+ at var{header-entry}
+^Z^Zbreakpoints-table
+ at end smallexample
+
+ at noindent
+where @var{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:
+
+ at findex record
+ at findex field
+ at smallexample
+^Z^Zrecord
+^Z^Zfield 0
+ at var{number}
+^Z^Zfield 1
+ at var{type}
+^Z^Zfield 2
+ at var{disposition}
+^Z^Zfield 3
+ at var{enable}
+^Z^Zfield 4
+ at var{address}
+^Z^Zfield 5
+ at var{what}
+^Z^Zfield 6
+ at var{frame}
+^Z^Zfield 7
+ at var{condition}
+^Z^Zfield 8
+ at var{ignore-count}
+^Z^Zfield 9
+ at var{commands}
+ at end smallexample
+
+Note that @var{address} is intended for user consumption---the syntax
+varies depending on the language.
+
+The output ends with
+
+ at findex breakpoints-table-end
+ at smallexample
+^Z^Zbreakpoints-table-end
+ at end smallexample
+
+ at node Invalidation
+ at section Invalidation Notices
+
+ at cindex annotations for invalidation messages
+The following annotations say that certain pieces of state may have
+changed.
+
+ at table @code
+ at findex frames-invalid
+ at item ^Z^Zframes-invalid
+
+The frames (for example, output from the @code{backtrace} command) may
+have changed.
+
+ at findex breakpoints-invalid
+ at item ^Z^Zbreakpoints-invalid
+
+The breakpoints may have changed. For example, the user just added or
+deleted a breakpoint.
+ at end table
+
+ at node Annotations for Running
+ at section Running the Program
+ at cindex annotations for running programs
+
+ at findex starting
+ at findex stopping
+When the program starts executing due to a @value{GDBN} command such as
+ at code{step} or @code{continue},
+
+ at smallexample
+^Z^Zstarting
+ at end smallexample
+
+is output. When the program stops,
+
+ at smallexample
+^Z^Zstopped
+ at end smallexample
+
+is output. Before the @code{stopped} annotation, a variety of
+annotations describe how the program stopped.
+
+ at table @code
+ at findex exited
+ at item ^Z^Zexited @var{exit-status}
+The program exited, and @var{exit-status} is the exit status (zero for
+successful exit, otherwise nonzero).
+
+ at findex signalled
+ at findex signal-name
+ at findex signal-name-end
+ at findex signal-string
+ at findex signal-string-end
+ at item ^Z^Zsignalled
+The program exited with a signal. After the @code{^Z^Zsignalled}, the
+annotation continues:
+
+ at smallexample
+ at var{intro-text}
+^Z^Zsignal-name
+ at var{name}
+^Z^Zsignal-name-end
+ at var{middle-text}
+^Z^Zsignal-string
+ at var{string}
+^Z^Zsignal-string-end
+ at var{end-text}
+ at end smallexample
+
+ at noindent
+where @var{name} is the name of the signal, such as @code{SIGILL} or
+ at code{SIGSEGV}, and @var{string} is the explanation of the signal, such
+as @code{Illegal Instruction} or @code{Segmentation fault}.
+ at var{intro-text}, @var{middle-text}, and @var{end-text} are for the
+user's benefit and have no particular format.
+
+ at findex signal
+ at item ^Z^Zsignal
+The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
+just saying that the program received the signal, not that it was
+terminated with it.
+
+ at findex breakpoint
+ at item ^Z^Zbreakpoint @var{number}
+The program hit breakpoint number @var{number}.
+
+ at findex watchpoint
+ at item ^Z^Zwatchpoint @var{number}
+The program hit watchpoint number @var{number}.
+ at end table
+
+ at node Source Annotations
+ at section Displaying Source
+ at cindex annotations for source display
+
+ at findex source
+The following annotation is used instead of displaying source code:
+
+ at smallexample
+^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
+ at end smallexample
+
+where @var{filename} is an absolute file name indicating which source
+file, @var{line} is the line number within that file (where 1 is the
+first line in the file), @var{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),
+ at var{middle} is @samp{middle} if @var{addr} is in the middle of the
+line, or @samp{beg} if @var{addr} is at the beginning of the line, and
+ at var{addr} is the address in the target program associated with the
+source which is being displayed. @var{addr} is in the form @samp{0x}
+followed by one or more lowercase hex digits (note that this does not
+depend on the language).
+
+ at node TODO
+ at section Annotations We Might Want in the Future
+
+ at format
+ - 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.
+ at end format
@node GDB Bugs
@chapter Reporting Bugs in @value{GDBN}