diff options
Diffstat (limited to 'gdb/doc/gdb.texinfo')
| -rw-r--r-- | gdb/doc/gdb.texinfo | 4540 |
1 files changed, 4538 insertions, 2 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 8c38e877353..5c4eb95e6b3 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -14045,8 +14045,4544 @@ environment. Users of this environment can use a new command, each value is printed in its own window. @end ignore -@include annotate.texi -@include gdbmi.texinfo + +@node GDB/MI +@chapter The @sc{gdb/mi} Interface + +@unnumberedsec Function and Purpose + +@cindex @sc{gdb/mi}, its purpose +@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. + +@unnumberedsec Notation and Terminology + +@cindex notational conventions, for @sc{gdb/mi} +This chapter uses the following notation: + +@itemize @bullet +@item +@code{|} separates two alternatives. + +@item +@code{[ @var{something} ]} indicates that @var{something} is optional: +it may or may not be given. + +@item +@code{( @var{group} )*} means that @var{group} inside the parentheses +may repeat zero or more times. + +@item +@code{( @var{group} )+} means that @var{group} inside the parentheses +may repeat one or more times. + +@item +@code{"@var{string}"} means a literal @var{string}. +@end itemize + +@ignore +@heading Dependencies +@end ignore + +@heading Acknowledgments + +In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and +Elena Zannoni. + +@menu +* GDB/MI Command Syntax:: +* GDB/MI Compatibility with CLI:: +* GDB/MI Output Records:: +* GDB/MI Command Description Format:: +* GDB/MI Breakpoint Table Commands:: +* GDB/MI Data Manipulation:: +* GDB/MI Program Control:: +* GDB/MI Miscellaneous Commands:: +@ignore +* GDB/MI Kod Commands:: +* GDB/MI Memory Overlay Commands:: +* GDB/MI Signal Handling Commands:: +@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:: +@end menu + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Command Syntax +@section @sc{gdb/mi} Command Syntax + +@menu +* GDB/MI Input Syntax:: +* GDB/MI Output Syntax:: +* GDB/MI Simple Examples:: +@end menu + +@node GDB/MI Input Syntax +@subsection @sc{gdb/mi} Input Syntax + +@cindex input syntax for @sc{gdb/mi} +@cindex @sc{gdb/mi}, input syntax +@table @code +@item @var{command} @expansion{} +@code{@var{cli-command} | @var{mi-command}} + +@item @var{cli-command} @expansion{} +@code{[ @var{token} ] @var{cli-command} @var{nl}}, where +@var{cli-command} is any existing @value{GDBN} CLI command. + +@item @var{mi-command} @expansion{} +@code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )* +@code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}} + +@item @var{token} @expansion{} +"any sequence of digits" + +@item @var{option} @expansion{} +@code{"-" @var{parameter} [ " " @var{parameter} ]} + +@item @var{parameter} @expansion{} +@code{@var{non-blank-sequence} | @var{c-string}} + +@item @var{operation} @expansion{} +@emph{any of the operations described in this chapter} + +@item @var{non-blank-sequence} @expansion{} +@emph{anything, provided it doesn't contain special characters such as +"-", @var{nl}, """ and of course " "} + +@item @var{c-string} @expansion{} +@code{""" @var{seven-bit-iso-c-string-content} """} + +@item @var{nl} @expansion{} +@code{CR | CR-LF} +@end table + +@noindent +Notes: + +@itemize @bullet +@item +The CLI commands are still handled by the @sc{mi} interpreter; their +output is described below. + +@item +The @code{@var{token}}, when present, is passed back when the command +finishes. + +@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 +@samp{--} (this is useful when some parameters begin with a dash). +@end itemize + +Pragmatics: + +@itemize @bullet +@item +We want easy access to the existing CLI syntax (for debugging). + +@item +We want it to be easy to spot a @sc{mi} operation. +@end itemize + +@node GDB/MI Output Syntax +@subsection @sc{gdb/mi} Output Syntax + +@cindex output syntax of @sc{gdb/mi} +@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{@var{token}} then the +corresponding output for that command will also be prefixed by that same +@var{token}. + +@table @code +@item @var{output} @expansion{} +@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}} + +@item @var{result-record} @expansion{} +@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}} + +@item @var{out-of-band-record} @expansion{} +@code{@var{async-record} | @var{stream-record}} + +@item @var{async-record} @expansion{} +@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}} + +@item @var{exec-async-output} @expansion{} +@code{[ @var{token} ] "*" @var{async-output}} + +@item @var{status-async-output} @expansion{} +@code{[ @var{token} ] "+" @var{async-output}} + +@item @var{notify-async-output} @expansion{} +@code{[ @var{token} ] "=" @var{async-output}} + +@item @var{async-output} @expansion{} +@code{@var{async-class} ( "," @var{result} )* @var{nl}} + +@item @var{result-class} @expansion{} +@code{"done" | "running" | "connected" | "error" | "exit"} + +@item @var{async-class} @expansion{} +@code{"stopped" | @var{others}} (where @var{others} will be added +depending on the needs---this is still in development). + +@item @var{result} @expansion{} +@code{ @var{variable} "=" @var{value}} + +@item @var{variable} @expansion{} +@code{ @var{string} } + +@item @var{value} @expansion{} +@code{ @var{const} | @var{tuple} | @var{list} } + +@item @var{const} @expansion{} +@code{@var{c-string}} + +@item @var{tuple} @expansion{} +@code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" } + +@item @var{list} @expansion{} +@code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "[" +@var{result} ( "," @var{result} )* "]" } + +@item @var{stream-record} @expansion{} +@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}} + +@item @var{console-stream-output} @expansion{} +@code{"~" @var{c-string}} + +@item @var{target-stream-output} @expansion{} +@code{"@@" @var{c-string}} + +@item @var{log-stream-output} @expansion{} +@code{"&" @var{c-string}} + +@item @var{nl} @expansion{} +@code{CR | CR-LF} + +@item @var{token} @expansion{} +@emph{any sequence of digits}. +@end table + +@noindent +Notes: + +@itemize @bullet +@item +All output sequences end in a single line containing a period. + +@item +The @code{@var{token}} is from the corresponding request. If an execution +command is interrupted by the @samp{-exec-interrupt} command, the +@var{token} associated with the @samp{*stopped} message is the one of the +original execution command, not the one of the interrupt command. + +@item +@cindex status output in @sc{gdb/mi} +@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{+}. + +@item +@cindex async output in @sc{gdb/mi} +@var{exec-async-output} contains asynchronous state change on the target +(stopped, started, disappeared). All async output is prefixed by +@samp{*}. + +@item +@cindex notify output in @sc{gdb/mi} +@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{=}. + +@item +@cindex console output in @sc{gdb/mi} +@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{~}. + +@item +@cindex target output in @sc{gdb/mi} +@var{target-stream-output} is the output produced by the target program. +All the target output is prefixed by @samp{@@}. + +@item +@cindex log output in @sc{gdb/mi} +@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{&}. + +@item +@cindex list output in @sc{gdb/mi} +New @sc{gdb/mi} commands should only output @var{lists} containing +@var{values}. + + +@end itemize + +@xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more +details about the various output records. + +@node GDB/MI Simple Examples +@subsection Simple Examples of @sc{gdb/mi} Interaction +@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}. + +@subsubheading Target Stop +@c Ummm... There is no "-stop" command. This assumes async, no? +Here's an example of stopping the inferior process: + +@smallexample +-> -stop +<- (@value{GDBP}) +@end smallexample + +@noindent +and later: + +@smallexample +<- *stop,reason="stop",address="0x123",source="a.c:123" +<- (@value{GDBP}) +@end smallexample + +@subsubheading Simple CLI Command + +Here's an example of a simple CLI command being passed through +@sc{gdb/mi} and on to the CLI. + +@smallexample +-> print 1+2 +<- &"print 1+2\n" +<- ~"$1 = 3\n" +<- ^done +<- (@value{GDBP}) +@end smallexample + +@subsubheading Command With Side Effects + +@smallexample +-> -symbol-file xyz.exe +<- *breakpoint,nr="3",address="0x123",source="a.c:123" +<- (@value{GDBP}) +@end smallexample + +@subsubheading A Bad Command + +Here's what happens if you pass a non-existent command: + +@smallexample +-> -rubbish +<- ^error,msg="Undefined MI command: rubbish" +<- (@value{GDBP}) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Compatibility with CLI +@section @sc{gdb/mi} Compatibility with CLI + +@cindex compatibility, @sc{gdb/mi} and CLI +@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. + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Output Records +@section @sc{gdb/mi} Output Records + +@menu +* GDB/MI Result Records:: +* GDB/MI Stream Records:: +* GDB/MI Out-of-band Records:: +@end menu + +@node GDB/MI Result Records +@subsection @sc{gdb/mi} Result Records + +@cindex result records in @sc{gdb/mi} +@cindex @sc{gdb/mi}, result records +In addition to a number of out-of-band notifications, the response to a +@sc{gdb/mi} command includes one of the following result indications: + +@table @code +@findex ^done +@item "^done" [ "," @var{results} ] +The synchronous operation was successful, @code{@var{results}} are the return +values. + +@item "^running" +@findex ^running +@c Is this one correct? Should it be an out-of-band notification? +The asynchronous operation was successfully started. The target is +running. + +@item "^error" "," @var{c-string} +@findex ^error +The operation failed. The @code{@var{c-string}} contains the corresponding +error message. +@end table + +@node GDB/MI Stream Records +@subsection @sc{gdb/mi} Stream Records + +@cindex @sc{gdb/mi}, stream records +@cindex stream records in @sc{gdb/mi} +@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 +@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). + +@table @code +@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. + +@item "@@" @var{string-output} +The target output stream contains any textual output from the running +target. + +@item "&" @var{string-output} +The log stream contains debugging messages being produced by @value{GDBN}'s +internals. +@end table + +@node GDB/MI Out-of-band Records +@subsection @sc{gdb/mi} Out-of-band Records + +@cindex out-of-band records in @sc{gdb/mi} +@cindex @sc{gdb/mi}, out-of-band records +@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. + +@table @code +@item "*" "stop" +@end table + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Command Description Format +@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. + +@subheading Motivation + +The motivation for this collection of commands. + +@subheading Introduction + +A brief introduction to this collection of commands as a whole. + +@subheading Commands + +For each command in the block, the following is described: + +@subsubheading Synopsis + +@smallexample + -command @var{args}@dots{} +@end smallexample + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} CLI command. + +@subsubheading Result + +@subsubheading Out-of-band + +@subsubheading Notes + +@subsubheading Example + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Breakpoint Table Commands +@section @sc{gdb/mi} Breakpoint table commands + +@cindex breakpoint commands for @sc{gdb/mi} +@cindex @sc{gdb/mi}, breakpoint commands +This section documents @sc{gdb/mi} commands for manipulating +breakpoints. + +@subheading The @code{-break-after} Command +@findex -break-after + +@subsubheading Synopsis + +@smallexample + -break-after @var{number} @var{count} +@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 +@samp{-break-list} command below. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{ignore}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-break-insert main +^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@} +(@value{GDBP}) +-break-after 1 3 +~ +^done +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x000100d0",func="main",file="hello.c",line="5",times="0", +ignore="3"@}]@} +(@value{GDBP}) +@end smallexample + +@ignore +@subheading The @code{-break-catch} Command +@findex -break-catch + +@subheading The @code{-break-commands} Command +@findex -break-commands +@end ignore + + +@subheading The @code{-break-condition} Command +@findex -break-condition + +@subsubheading Synopsis + +@smallexample + -break-condition @var{number} @var{expr} +@end smallexample + +Breakpoint @var{number} will stop the program only if the condition in +@var{expr} is true. The condition becomes part of the +@samp{-break-list} output (see the description of the @samp{-break-list} +command below). + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{condition}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-break-condition 1 1 +^done +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x000100d0",func="main",file="hello.c",line="5",cond="1", +times="0",ignore="3"@}]@} +(@value{GDBP}) +@end smallexample + +@subheading The @code{-break-delete} Command +@findex -break-delete + +@subsubheading Synopsis + +@smallexample + -break-delete ( @var{breakpoint} )+ +@end smallexample + +Delete the breakpoint(s) whose number(s) are specified in the argument +list. This is obviously reflected in the breakpoint list. + +@subsubheading @value{GDBN} command + +The corresponding @value{GDBN} command is @samp{delete}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-break-delete 1 +^done +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="0",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[]@} +(@value{GDBP}) +@end smallexample + +@subheading The @code{-break-disable} Command +@findex -break-disable + +@subsubheading Synopsis + +@smallexample + -break-disable ( @var{breakpoint} )+ +@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). + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{disable}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-break-disable 2 +^done +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n", +addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@} +(@value{GDBP}) +@end smallexample + +@subheading The @code{-break-enable} Command +@findex -break-enable + +@subsubheading Synopsis + +@smallexample + -break-enable ( @var{breakpoint} )+ +@end smallexample + +Enable (previously disabled) @var{breakpoint}(s). + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{enable}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-break-enable 2 +^done +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", +addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@} +(@value{GDBP}) +@end smallexample + +@subheading The @code{-break-info} Command +@findex -break-info + +@subsubheading Synopsis + +@smallexample + -break-info @var{breakpoint} +@end smallexample + +@c REDUNDANT??? +Get information about a single breakpoint. + +@subsubheading @value{GDBN} command + +The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}. + +@subsubheading Example +N.A. + +@subheading The @code{-break-insert} Command +@findex -break-insert + +@subsubheading Synopsis + +@smallexample + -break-insert [ -t ] [ -h ] [ -r ] + [ -c @var{condition} ] [ -i @var{ignore-count} ] + [ -p @var{thread} ] [ @var{line} | @var{addr} ] +@end smallexample + +@noindent +If specified, @var{line}, can be one of: + +@itemize @bullet +@item function +@c @item +offset +@c @item -offset +@c @item linenum +@item filename:linenum +@item filename:function +@item *address +@end itemize + +The possible optional parameters of this command are: + +@table @samp +@item -t +Insert a tempoary breakpoint. +@item -h +Insert a hardware breakpoint. +@item -c @var{condition} +Make the breakpoint conditional on @var{condition}. +@item -i @var{ignore-count} +Initialize the @var{ignore-count}. +@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. +@end table + +@subsubheading Result + +The result is in the form: + +@smallexample + ^done,bkptno="@var{number}",func="@var{funcname}", + file="@var{filename}",line="@var{lineno}" +@end smallexample + +@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, +@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. +@c An out-of-band breakpoint instead of part of the result? + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak}, +@samp{hbreak}, @samp{thbreak}, and @samp{rbreak}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-break-insert main +^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} +(@value{GDBP}) +-break-insert -t foo +^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@} +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="2",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@}, +bkpt=@{number="2",type="breakpoint",disp="del",enabled="y", +addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}]@} +(@value{GDBP}) +-break-insert -r foo.* +~int foo(int, int); +^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@} +(@value{GDBP}) +@end smallexample + +@subheading The @code{-break-list} Command +@findex -break-list + +@subsubheading Synopsis + +@smallexample + -break-list +@end smallexample + +Displays the list of inserted breakpoints, showing the following fields: + +@table @samp +@item Number +number of the breakpoint +@item Type +type of the breakpoint: @samp{breakpoint} or @samp{watchpoint} +@item Disposition +should the breakpoint be deleted or disabled when it is hit: @samp{keep} +or @samp{nokeep} +@item Enabled +is the breakpoint enabled or no: @samp{y} or @samp{n} +@item Address +memory location at which the breakpoint is set +@item What +logical location of the breakpoint, expressed by function name, file +name, line number +@item Times +number of times the breakpoint has been hit +@end table + +If there are no breakpoints or watchpoints, the @code{BreakpointTable} +@code{body} field is an empty list. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info break}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="2",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}, +bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", +addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}]@} +(@value{GDBP}) +@end smallexample + +Here's an example of the result when there are no breakpoints: + +@smallexample +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="0",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[]@} +(@value{GDBP}) +@end smallexample + +@subheading The @code{-break-watch} Command +@findex -break-watch + +@subsubheading Synopsis + +@smallexample + -break-watch [ -a | -r ] +@end smallexample + +Create a watchpoint. With the @samp{-a} option it will create an +@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. +@xref{Set Watchpoints, , Setting watchpoints}. + +Note that @samp{-break-list} will report a single list of watchpoints and +breakpoints inserted. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and +@samp{rwatch}. + +@subsubheading Example + +Setting a watchpoint on a variable in the @code{main} function: + +@smallexample +(@value{GDBP}) +-break-watch x +^done,wpt=@{number="2",exp="x"@} +(@value{GDBP}) +-exec-continue +^running +^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@}, +value=@{old="-268439212",new="55"@}, +frame=@{func="main",args=[],file="recursive2.c",line="5"@} +(@value{GDBP}) +@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. + +@smallexample +(@value{GDBP}) +-break-watch C +^done,wpt=@{number="5",exp="C"@} +(@value{GDBP}) +-exec-continue +^running +^done,reason="watchpoint-trigger", +wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@}, +frame=@{func="callee4",args=[], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@} +(@value{GDBP}) +-exec-continue +^running +^done,reason="watchpoint-scope",wpnum="5", +frame=@{func="callee3",args=[@{name="strarg", +value="0x11940 \"A string argument.\""@}], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} +(@value{GDBP}) +@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. + +@smallexample +(@value{GDBP}) +-break-watch C +^done,wpt=@{number="2",exp="C"@} +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="2",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x00010734",func="callee4", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}, +bkpt=@{number="2",type="watchpoint",disp="keep", +enabled="y",addr="",what="C",times="0"@}]@} +(@value{GDBP}) +-exec-continue +^running +^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@}, +value=@{old="-276895068",new="3"@}, +frame=@{func="callee4",args=[], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@} +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="2",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x00010734",func="callee4", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}, +bkpt=@{number="2",type="watchpoint",disp="keep", +enabled="y",addr="",what="C",times="-5"@}]@} +(@value{GDBP}) +-exec-continue +^running +^done,reason="watchpoint-scope",wpnum="2", +frame=@{func="callee3",args=[@{name="strarg", +value="0x11940 \"A string argument.\""@}], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} +(@value{GDBP}) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x00010734",func="callee4", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}]@} +(@value{GDBP}) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Data Manipulation +@section @sc{gdb/mi} Data Manipulation + +@cindex data manipulation, in @sc{gdb/mi} +@cindex @sc{gdb/mi}, data manipulation +This section describes the @sc{gdb/mi} commands that manipulate data: +examine memory and registers, evaluate expressions, etc. + +@c REMOVED FROM THE INTERFACE. +@c @subheading -data-assign +@c Change the value of a program variable. Plenty of side effects. +@c @subsubheading GDB command +@c set variable +@c @subsubheading Example +@c N.A. + +@subheading The @code{-data-disassemble} Command +@findex -data-disassemble + +@subsubheading Synopsis + +@smallexample + -data-disassemble + [ -s @var{start-addr} -e @var{end-addr} ] + | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ] + -- @var{mode} +@end smallexample + +@noindent +Where: + +@table @samp +@item @var{start-addr} +is the beginning address (or @code{$pc}) +@item @var{end-addr} +is the end address +@item @var{filename} +is the name of the file to disassemble +@item @var{linenum} +is the line number to disassemble around +@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 +@var{lines} is lower than the number of disassembly lines between +@var{start-addr} and @var{end-addr}, only @var{lines} lines are +displayed; if @var{lines} is higher than the number of lines between +@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr} +are displayed. +@item @var{mode} +is either 0 (meaning only disassembly) or 1 (meaning mixed source and +disassembly). +@end table + +@subsubheading Result + +The output for each instruction is composed of four fields: + +@itemize @bullet +@item Address +@item Func-name +@item Offset +@item Instruction +@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. + +@subsubheading @value{GDBN} Command + +There's no direct mapping from this command to the CLI. + +@subsubheading Example + +Disassemble from the current value of @code{$pc} to @code{$pc + 20}: + +@smallexample +(@value{GDBP}) +-data-disassemble -s $pc -e "$pc + 20" -- 0 +^done, +asm_insns=[ +@{address="0x000107c0",func-name="main",offset="4", +inst="mov 2, %o0"@}, +@{address="0x000107c4",func-name="main",offset="8", +inst="sethi %hi(0x11800), %o2"@}, +@{address="0x000107c8",func-name="main",offset="12", +inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@}, +@{address="0x000107cc",func-name="main",offset="16", +inst="sethi %hi(0x11800), %o2"@}, +@{address="0x000107d0",func-name="main",offset="20", +inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}] +(@value{GDBP}) +@end smallexample + +Disassemble the whole @code{main} function. Line 32 is part of +@code{main}. + +@smallexample +-data-disassemble -f basics.c -l 32 -- 0 +^done,asm_insns=[ +@{address="0x000107bc",func-name="main",offset="0", +inst="save %sp, -112, %sp"@}, +@{address="0x000107c0",func-name="main",offset="4", +inst="mov 2, %o0"@}, +@{address="0x000107c4",func-name="main",offset="8", +inst="sethi %hi(0x11800), %o2"@}, +[@dots{}] +@{address="0x0001081c",func-name="main",offset="96",inst="ret "@}, +@{address="0x00010820",func-name="main",offset="100",inst="restore "@}] +(@value{GDBP}) +@end smallexample + +Disassemble 3 instructions from the start of @code{main}: + +@smallexample +(@value{GDBP}) +-data-disassemble -f basics.c -l 32 -n 3 -- 0 +^done,asm_insns=[ +@{address="0x000107bc",func-name="main",offset="0", +inst="save %sp, -112, %sp"@}, +@{address="0x000107c0",func-name="main",offset="4", +inst="mov 2, %o0"@}, +@{address="0x000107c4",func-name="main",offset="8", +inst="sethi %hi(0x11800), %o2"@}] +(@value{GDBP}) +@end smallexample + +Disassemble 3 instructions from the start of @code{main} in mixed mode: + +@smallexample +(@value{GDBP}) +-data-disassemble -f basics.c -l 32 -n 3 -- 1 +^done,asm_insns=[ +src_and_asm_line=@{line="31", +file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ + testsuite/gdb.mi/basics.c",line_asm_insn=[ +@{address="0x000107bc",func-name="main",offset="0", +inst="save %sp, -112, %sp"@}]@}, +src_and_asm_line=@{line="32", +file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ + testsuite/gdb.mi/basics.c",line_asm_insn=[ +@{address="0x000107c0",func-name="main",offset="4", +inst="mov 2, %o0"@}, +@{address="0x000107c4",func-name="main",offset="8", +inst="sethi %hi(0x11800), %o2"@}]@}] +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-data-evaluate-expression} Command +@findex -data-evaluate-expression + +@subsubheading Synopsis + +@smallexample + -data-evaluate-expression @var{expr} +@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. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and +@samp{call}. In @code{gdbtk} only, there's a corresponding +@samp{gdb_eval} command. + +@subsubheading Example + +In the following example, the numbers that precede the commands are the +@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. + +@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}) +@end smallexample + + +@subheading The @code{-data-list-changed-registers} Command +@findex -data-list-changed-registers + +@subsubheading Synopsis + +@smallexample + -data-list-changed-registers +@end smallexample + +Display a list of the registers that have changed. + +@subsubheading @value{GDBN} Command + +@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk} +has the corresponding command @samp{gdb_changed_register_list}. + +@subsubheading Example + +On a PPC MBX board: + +@smallexample +(@value{GDBP}) +-exec-continue +^running + +(@value{GDBP}) +*stopped,reason="breakpoint-hit",bkptno="1",frame=@{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}) +@end smallexample + + +@subheading The @code{-data-list-register-names} Command +@findex -data-list-register-names + +@subsubheading Synopsis + +@smallexample + -data-list-register-names [ ( @var{regno} )+ ] +@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. + +@subsubheading @value{GDBN} Command + +@value{GDBN} does not have a command which corresponds to +@samp{-data-list-register-names}. In @code{gdbtk} there is a +corresponding command @samp{gdb_regnames}. + +@subsubheading Example + +For the PPC MBX board: +@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}) +@end smallexample + +@subheading The @code{-data-list-register-values} Command +@findex -data-list-register-values + +@subsubheading Synopsis + +@smallexample + -data-list-register-values @var{fmt} [ ( @var{regno} )*] +@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: + +@table @code +@item x +Hexadecimal +@item o +Octal +@item t +Binary +@item d +Decimal +@item r +Raw +@item N +Natural +@end table + +@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}. + +@subsubheading Example + +For a PPC MBX board (note: line breaks are for readability only, they +don't appear in the actual output): + +@smallexample +(@value{GDBP}) +-data-list-register-values r 64 65 +^done,register-values=[@{number="64",value="0xfe00a300"@}, +@{number="65",value="0x00029002"@}] +(@value{GDBP}) +-data-list-register-values x +^done,register-values=[@{number="0",value="0xfe0043c8"@}, +@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@}, +@{number="3",value="0x0"@},@{number="4",value="0xa"@}, +@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@}, +@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@}, +@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@}, +@{number="11",value="0x1"@},@{number="12",value="0x0"@}, +@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@}, +@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@}, +@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@}, +@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@}, +@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@}, +@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@}, +@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@}, +@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@}, +@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@}, +@{number="31",value="0x0"@},@{number="32",value="0x0"@}, +@{number="33",value="0x0"@},@{number="34",value="0x0"@}, +@{number="35",value="0x0"@},@{number="36",value="0x0"@}, +@{number="37",value="0x0"@},@{number="38",value="0x0"@}, +@{number="39",value="0x0"@},@{number="40",value="0x0"@}, +@{number="41",value="0x0"@},@{number="42",value="0x0"@}, +@{number="43",value="0x0"@},@{number="44",value="0x0"@}, +@{number="45",value="0x0"@},@{number="46",value="0x0"@}, +@{number="47",value="0x0"@},@{number="48",value="0x0"@}, +@{number="49",value="0x0"@},@{number="50",value="0x0"@}, +@{number="51",value="0x0"@},@{number="52",value="0x0"@}, +@{number="53",value="0x0"@},@{number="54",value="0x0"@}, +@{number="55",value="0x0"@},@{number="56",value="0x0"@}, +@{number="57",value="0x0"@},@{number="58",value="0x0"@}, +@{number="59",value="0x0"@},@{number="60",value="0x0"@}, +@{number="61",value="0x0"@},@{number="62",value="0x0"@}, +@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@}, +@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@}, +@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@}, +@{number="69",value="0x20002b03"@}] +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-data-read-memory} Command +@findex -data-read-memory + +@subsubheading Synopsis + +@smallexample + -data-read-memory [ -o @var{byte-offset} ] + @var{address} @var{word-format} @var{word-size} + @var{nr-rows} @var{nr-cols} [ @var{aschar} ] +@end smallexample + +@noindent +where: + +@table @samp +@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. + +@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}). + +@item @var{word-size} +The size of each memory word in bytes. + +@item @var{nr-rows} +The number of rows in the output table. + +@item @var{nr-cols} +The number of columns in the output table. + +@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). + +@item @var{byte-offset} +An offset to add to the @var{address} before fetching memory. +@end table + +This command displays memory contents as a table of @var{nr-rows} by +@var{nr-cols} words, each word being @var{word-size} bytes. In total, +@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 +@samp{addr}. + +The address of the next/previous row or page is available in +@samp{next-row} and @samp{prev-row}, @samp{next-page} and +@samp{prev-page}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has +@samp{gdb_get_mem} memory read command. + +@subsubheading Example + +Read six bytes of memory starting at @code{bytes+6} but then offset by +@code{-6} bytes. Format as three rows of two columns. One byte per +word. Display each word in hex. + +@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=[ +@{addr="0x00001390",data=["0x00","0x01"]@}, +@{addr="0x00001392",data=["0x02","0x03"]@}, +@{addr="0x00001394",data=["0x04","0x05"]@}] +(@value{GDBP}) +@end smallexample + +Read two bytes of memory starting at address @code{shorts + 64} and +display as a single word formatted in decimal. + +@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=[ +@{addr="0x00001510",data=["128"]@}] +(@value{GDBP}) +@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. + +@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=[ +@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@}, +@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@}, +@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@}, +@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@}, +@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@}, +@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@}, +@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@}, +@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}] +(@value{GDBP}) +@end smallexample + +@subheading The @code{-display-delete} Command +@findex -display-delete + +@subsubheading Synopsis + +@smallexample + -display-delete @var{number} +@end smallexample + +Delete the display @var{number}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{delete display}. + +@subsubheading Example +N.A. + + +@subheading The @code{-display-disable} Command +@findex -display-disable + +@subsubheading Synopsis + +@smallexample + -display-disable @var{number} +@end smallexample + +Disable display @var{number}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{disable display}. + +@subsubheading Example +N.A. + + +@subheading The @code{-display-enable} Command +@findex -display-enable + +@subsubheading Synopsis + +@smallexample + -display-enable @var{number} +@end smallexample + +Enable display @var{number}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{enable display}. + +@subsubheading Example +N.A. + + +@subheading The @code{-display-insert} Command +@findex -display-insert + +@subsubheading Synopsis + +@smallexample + -display-insert @var{expression} +@end smallexample + +Display @var{expression} every time the program stops. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{display}. + +@subsubheading Example +N.A. + + +@subheading The @code{-display-list} Command +@findex -display-list + +@subsubheading Synopsis + +@smallexample + -display-list +@end smallexample + +List the displays. Do not show the current values. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info display}. + +@subsubheading Example +N.A. + + +@subheading The @code{-environment-cd} Command +@findex -environment-cd + +@subsubheading Synopsis + +@smallexample + -environment-cd @var{pathdir} +@end smallexample + +Set @value{GDBN}'s working directory. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{cd}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb +^done +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-environment-directory} Command +@findex -environment-directory + +@subsubheading Synopsis + +@smallexample + -environment-directory [ -r ] [ @var{pathdir} ]+ +@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 +@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. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{dir}. + +@subsubheading Example + +@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}) +@end smallexample + + +@subheading The @code{-environment-path} Command +@findex -environment-path + +@subsubheading Synopsis + +@smallexample + -environment-path [ -r ] [ @var{pathdir} ]+ +@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 +@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. + + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{path}. + +@subsubheading Example + +@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}) +@end smallexample + + +@subheading The @code{-environment-pwd} Command +@findex -environment-pwd + +@subsubheading Synopsis + +@smallexample + -environment-pwd +@end smallexample + +Show the current working directory. + +@subsubheading @value{GDBN} command + +The corresponding @value{GDBN} command is @samp{pwd}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-environment-pwd +^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" +(@value{GDBP}) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Program Control +@section @sc{gdb/mi} Program control + +@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. + +@subsubheading Examples + +@noindent +Program exited normally: + +@smallexample +(@value{GDBP}) +-exec-run +^running +(@value{GDBP}) +x = 55 +*stopped,reason="exited-normally" +(@value{GDBP}) +@end smallexample + +@noindent +Program exited exceptionally: + +@smallexample +(@value{GDBP}) +-exec-run +^running +(@value{GDBP}) +x = 55 +*stopped,reason="exited",exit-code="01" +(@value{GDBP}) +@end smallexample + +Another way the program can terminate is if it receives a signal such as +@code{SIGINT}. In this case, @sc{gdb/mi} displays this: + +@smallexample +(@value{GDBP}) +*stopped,reason="exited-signalled",signal-name="SIGINT", +signal-meaning="Interrupt" +@end smallexample + + +@subheading The @code{-exec-abort} Command +@findex -exec-abort + +@subsubheading Synopsis + +@smallexample + -exec-abort +@end smallexample + +Kill the inferior running program. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{kill}. + +@subsubheading Example +N.A. + + +@subheading The @code{-exec-arguments} Command +@findex -exec-arguments + +@subsubheading Synopsis + +@smallexample + -exec-arguments @var{args} +@end smallexample + +Set the inferior program arguments, to be used in the next +@samp{-exec-run}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{set args}. + +@subsubheading Example + +@c FIXME! +Don't have one around. + + +@subheading The @code{-exec-continue} Command +@findex -exec-continue + +@subsubheading Synopsis + +@smallexample + -exec-continue +@end smallexample + +Asynchronous command. Resumes the execution of the inferior program +until a breakpoint is encountered, or until the inferior exits. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} corresponding is @samp{continue}. + +@subsubheading Example + +@smallexample +-exec-continue +^running +(@value{GDBP}) +@@Hello world +*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[], +file="hello.c",line="13"@} +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-finish} Command +@findex -exec-finish + +@subsubheading Synopsis + +@smallexample + -exec-finish +@end smallexample + +Asynchronous command. Resumes the execution of the inferior program +until the current function is exited. Displays the results returned by +the function. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{finish}. + +@subsubheading Example + +Function returning @code{void}. + +@smallexample +-exec-finish +^running +(@value{GDBP}) +@@hello from foo +*stopped,reason="function-finished",frame=@{func="main",args=[], +file="hello.c",line="7"@} +(@value{GDBP}) +@end smallexample + +Function returning other than @code{void}. The name of the internal +@value{GDBN} variable storing the result is printed, together with the +value itself. + +@smallexample +-exec-finish +^running +(@value{GDBP}) +*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo", +args=[@{name="a",value="1"],@{name="b",value="9"@}@}, +file="recursive2.c",line="14"@}, +gdb-result-var="$1",return-value="0" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-interrupt} Command +@findex -exec-interrupt + +@subsubheading Synopsis + +@smallexample + -exec-interrupt +@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. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{interrupt}. + +@subsubheading Example + +@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=@{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}) +@end smallexample + + +@subheading The @code{-exec-next} Command +@findex -exec-next + +@subsubheading Synopsis + +@smallexample + -exec-next +@end smallexample + +Asynchronous command. Resumes execution of the inferior program, stopping +when the beginning of the next source line is reached. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{next}. + +@subsubheading Example + +@smallexample +-exec-next +^running +(@value{GDBP}) +*stopped,reason="end-stepping-range",line="8",file="hello.c" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-next-instruction} Command +@findex -exec-next-instruction + +@subsubheading Synopsis + +@smallexample + -exec-next-instruction +@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. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{nexti}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-exec-next-instruction +^running + +(@value{GDBP}) +*stopped,reason="end-stepping-range", +addr="0x000100d4",line="5",file="hello.c" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-return} Command +@findex -exec-return + +@subsubheading Synopsis + +@smallexample + -exec-return +@end smallexample + +Makes current function return immediately. Doesn't execute the inferior. +Displays the new current frame. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{return}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +200-break-insert callee4 +200^done,bkpt=@{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=@{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=@{level="0",func="callee3", +args=[@{name="strarg", +value="0x11940 \"A string argument.\""@}], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-run} Command +@findex -exec-run + +@subsubheading Synopsis + +@smallexample + -exec-run +@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. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{run}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-break-insert main +^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} +(@value{GDBP}) +-exec-run +^running +(@value{GDBP}) +*stopped,reason="breakpoint-hit",bkptno="1", +frame=@{func="main",args=[],file="recursive2.c",line="4"@} +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-show-arguments} Command +@findex -exec-show-arguments + +@subsubheading Synopsis + +@smallexample + -exec-show-arguments +@end smallexample + +Print the arguments of the program. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{show args}. + +@subsubheading Example +N.A. + +@c @subheading -exec-signal + +@subheading The @code{-exec-step} Command +@findex -exec-step + +@subsubheading Synopsis + +@smallexample + -exec-step +@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. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{step}. + +@subsubheading Example + +Stepping into a function: + +@smallexample +-exec-step +^running +(@value{GDBP}) +*stopped,reason="end-stepping-range", +frame=@{func="foo",args=[@{name="a",value="10"@}, +@{name="b",value="0"@}],file="recursive2.c",line="11"@} +(@value{GDBP}) +@end smallexample + +Regular stepping: + +@smallexample +-exec-step +^running +(@value{GDBP}) +*stopped,reason="end-stepping-range",line="14",file="recursive2.c" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-step-instruction} Command +@findex -exec-step-instruction + +@subsubheading Synopsis + +@smallexample + -exec-step-instruction +@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. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{stepi}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-exec-step-instruction +^running + +(@value{GDBP}) +*stopped,reason="end-stepping-range", +frame=@{func="foo",args=[],file="try.c",line="10"@} +(@value{GDBP}) +-exec-step-instruction +^running + +(@value{GDBP}) +*stopped,reason="end-stepping-range", +frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@} +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-exec-until} Command +@findex -exec-until + +@subsubheading Synopsis + +@smallexample + -exec-until [ @var{location} ] +@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}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{until}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-exec-until recursive2.c:6 +^running +(@value{GDBP}) +x = 55 +*stopped,reason="location-reached",frame=@{func="main",args=[], +file="recursive2.c",line="6"@} +(@value{GDBP}) +@end smallexample + +@ignore +@subheading -file-clear +Is this going away???? +@end ignore + + +@subheading The @code{-file-exec-and-symbols} Command +@findex -file-exec-and-symbols + +@subsubheading Synopsis + +@smallexample + -file-exec-and-symbols @var{file} +@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. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{file}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx +^done +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-file-exec-file} Command +@findex -file-exec-file + +@subsubheading Synopsis + +@smallexample + -file-exec-file @var{file} +@end smallexample + +Specify the executable file to be debugged. Unlike +@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. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{exec-file}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx +^done +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-file-list-exec-sections} Command +@findex -file-list-exec-sections + +@subsubheading Synopsis + +@smallexample + -file-list-exec-sections +@end smallexample + +List the sections of the current executable file. + +@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 +@samp{gdb_load_info}. + +@subsubheading Example +N.A. + + +@subheading The @code{-file-list-exec-source-files} Command +@findex -file-list-exec-source-files + +@subsubheading Synopsis + +@smallexample + -file-list-exec-source-files +@end smallexample + +List the source files for the current executable. + +@subsubheading @value{GDBN} Command + +There's no @value{GDBN} command which directly corresponds to this one. +@code{gdbtk} has an analogous command @samp{gdb_listfiles}. + +@subsubheading Example +N.A. + + +@subheading The @code{-file-list-shared-libraries} Command +@findex -file-list-shared-libraries + +@subsubheading Synopsis + +@smallexample + -file-list-shared-libraries +@end smallexample + +List the shared libraries in the program. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info shared}. + +@subsubheading Example +N.A. + + +@subheading The @code{-file-list-symbol-files} Command +@findex -file-list-symbol-files + +@subsubheading Synopsis + +@smallexample + -file-list-symbol-files +@end smallexample + +List symbol files. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info file} (part of it). + +@subsubheading Example +N.A. + + +@subheading The @code{-file-symbol-file} Command +@findex -file-symbol-file + +@subsubheading Synopsis + +@smallexample + -file-symbol-file @var{file} +@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. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{symbol-file}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx +^done +(@value{GDBP}) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Miscellaneous Commands +@section Miscellaneous @value{GDBN} commands in @sc{gdb/mi} + +@c @subheading -gdb-complete + +@subheading The @code{-gdb-exit} Command +@findex -gdb-exit + +@subsubheading Synopsis + +@smallexample + -gdb-exit +@end smallexample + +Exit @value{GDBN} immediately. + +@subsubheading @value{GDBN} Command + +Approximately corresponds to @samp{quit}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-gdb-exit +@end smallexample + +@subheading The @code{-gdb-set} Command +@findex -gdb-set + +@subsubheading Synopsis + +@smallexample + -gdb-set +@end smallexample + +Set an internal @value{GDBN} variable. +@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ????? + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{set}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-gdb-set $foo=3 +^done +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-gdb-show} Command +@findex -gdb-show + +@subsubheading Synopsis + +@smallexample + -gdb-show +@end smallexample + +Show the current value of a @value{GDBN} variable. + +@subsubheading @value{GDBN} command + +The corresponding @value{GDBN} command is @samp{show}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-gdb-show annotate +^done,value="0" +(@value{GDBP}) +@end smallexample + +@c @subheading -gdb-source + + +@subheading The @code{-gdb-version} Command +@findex -gdb-version + +@subsubheading Synopsis + +@smallexample + -gdb-version +@end smallexample + +Show version information for @value{GDBN}. Used mostly in testing. + +@subsubheading @value{GDBN} Command + +There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this +information when you start an interactive session. + +@subsubheading Example + +@c This example modifies the actual output from GDB to avoid overfull +@c box in TeX. +@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}) +@end smallexample + +@subheading The @code{-interpreter-exec} Command +@findex -interpreter-exec + +@subheading Synopsis + +@smallexample +-interpreter-exec @var{interpreter} @var{command} +@end smallexample + +Execute the specified @var{command} in the given @var{interpreter}. + +@subheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{interpreter-exec}. + +@subheading Example + +@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}) +@end smallexample + +@ignore +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Kod Commands +@section @sc{gdb/mi} Kod Commands + +The Kod commands are not implemented. + +@c @subheading -kod-info + +@c @subheading -kod-list + +@c @subheading -kod-list-object-types + +@c @subheading -kod-show + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Memory Overlay Commands +@section @sc{gdb/mi} Memory Overlay Commands + +The memory overlay commands are not implemented. + +@c @subheading -overlay-auto + +@c @subheading -overlay-list-mapping-state + +@c @subheading -overlay-list-overlays + +@c @subheading -overlay-map + +@c @subheading -overlay-off + +@c @subheading -overlay-on + +@c @subheading -overlay-unmap + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Signal Handling Commands +@section @sc{gdb/mi} Signal Handling Commands + +Signal handling commands are not implemented. + +@c @subheading -signal-handle + +@c @subheading -signal-list-handle-actions + +@c @subheading -signal-list-signal-types +@end ignore + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Stack Manipulation +@section @sc{gdb/mi} Stack Manipulation Commands + + +@subheading The @code{-stack-info-frame} Command +@findex -stack-info-frame + +@subsubheading Synopsis + +@smallexample + -stack-info-frame +@end smallexample + +Get info on the current frame. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame} +(without arguments). + +@subsubheading Example +N.A. + +@subheading The @code{-stack-info-depth} Command +@findex -stack-info-depth + +@subsubheading Synopsis + +@smallexample + -stack-info-depth [ @var{max-depth} ] +@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. + +@subsubheading @value{GDBN} Command + +There's no equivalent @value{GDBN} command. + +@subsubheading Example + +For a stack with frame levels 0 through 11: + +@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}) +@end smallexample + +@subheading The @code{-stack-list-arguments} Command +@findex -stack-list-arguments + +@subsubheading Synopsis + +@smallexample + -stack-list-arguments @var{show-values} + [ @var{low-frame} @var{high-frame} ] +@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 +@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. + +@subsubheading @value{GDBN} Command + +@value{GDBN} does not have an equivalent command. @code{gdbtk} has a +@samp{gdb_get_args} command which partially overlaps with the +functionality of @samp{-stack-list-arguments}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-stack-list-frames +^done, +stack=[ +frame=@{level="0",addr="0x00010734",func="callee4", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}, +frame=@{level="1",addr="0x0001076c",func="callee3", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}, +frame=@{level="2",addr="0x0001078c",func="callee2", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@}, +frame=@{level="3",addr="0x000107b4",func="callee1", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@}, +frame=@{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=@{level="0",args=[]@}, +frame=@{level="1",args=[name="strarg"]@}, +frame=@{level="2",args=[name="intarg",name="strarg"]@}, +frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@}, +frame=@{level="4",args=[]@}] +(@value{GDBP}) +-stack-list-arguments 1 +^done, +stack-args=[ +frame=@{level="0",args=[]@}, +frame=@{level="1", + args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, +frame=@{level="2",args=[ +@{name="intarg",value="2"@}, +@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, +@{frame=@{level="3",args=[ +@{name="intarg",value="2"@}, +@{name="strarg",value="0x11940 \"A string argument.\""@}, +@{name="fltarg",value="3.5"@}]@}, +frame=@{level="4",args=[]@}] +(@value{GDBP}) +-stack-list-arguments 0 2 2 +^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}] +(@value{GDBP}) +-stack-list-arguments 1 2 2 +^done,stack-args=[frame=@{level="2", +args=[@{name="intarg",value="2"@}, +@{name="strarg",value="0x11940 \"A string argument.\""@}]@}] +(@value{GDBP}) +@end smallexample + +@c @subheading -stack-list-exception-handlers + + +@subheading The @code{-stack-list-frames} Command +@findex -stack-list-frames + +@subsubheading Synopsis + +@smallexample + -stack-list-frames [ @var{low-frame} @var{high-frame} ] +@end smallexample + +List the frames currently on the stack. For each frame it displays the +following info: + +@table @samp +@item @var{level} +The frame number, 0 being the topmost frame, i.e. the innermost function. +@item @var{addr} +The @code{$pc} value for that frame. +@item @var{func} +Function name. +@item @var{file} +File name of the source file where the function lives. +@item @var{line} +Line number corresponding to the @code{$pc}. +@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. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}. + +@subsubheading Example + +Full stack backtrace: + +@smallexample +(@value{GDBP}) +-stack-list-frames +^done,stack= +[frame=@{level="0",addr="0x0001076c",func="foo", + file="recursive2.c",line="11"@}, +frame=@{level="1",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="2",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="3",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="4",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="5",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="6",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="7",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="8",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="9",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="10",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="11",addr="0x00010738",func="main", + file="recursive2.c",line="4"@}] +(@value{GDBP}) +@end smallexample + +Show frames between @var{low_frame} and @var{high_frame}: + +@smallexample +(@value{GDBP}) +-stack-list-frames 3 5 +^done,stack= +[frame=@{level="3",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="4",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}, +frame=@{level="5",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}] +(@value{GDBP}) +@end smallexample + +Show a single frame: + +@smallexample +(@value{GDBP}) +-stack-list-frames 3 3 +^done,stack= +[frame=@{level="3",addr="0x000107a4",func="foo", + file="recursive2.c",line="14"@}] +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-stack-list-locals} Command +@findex -stack-list-locals + +@subsubheading Synopsis + +@smallexample + -stack-list-locals @var{print-values} +@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. + +@subsubheading @value{GDBN} Command + +@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-stack-list-locals 0 +^done,locals=[name="A",name="B",name="C"] +(@value{GDBP}) +-stack-list-locals 1 +^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@}, + @{name="C",value="3"@}] +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-stack-select-frame} Command +@findex -stack-select-frame + +@subsubheading Synopsis + +@smallexample + -stack-select-frame @var{framenum} +@end smallexample + +Change the current frame. Select a different frame @var{framenum} on +the stack. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{frame}, @samp{up}, +@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-stack-select-frame 2 +^done +(@value{GDBP}) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Symbol Query +@section @sc{gdb/mi} Symbol Query Commands + + +@subheading The @code{-symbol-info-address} Command +@findex -symbol-info-address + +@subsubheading Synopsis + +@smallexample + -symbol-info-address @var{symbol} +@end smallexample + +Describe where @var{symbol} is stored. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info address}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-info-file} Command +@findex -symbol-info-file + +@subsubheading Synopsis + +@smallexample + -symbol-info-file +@end smallexample + +Show the file for the symbol. + +@subsubheading @value{GDBN} Command + +There's no equivalent @value{GDBN} command. @code{gdbtk} has +@samp{gdb_find_file}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-info-function} Command +@findex -symbol-info-function + +@subsubheading Synopsis + +@smallexample + -symbol-info-function +@end smallexample + +Show which function the symbol lives in. + +@subsubheading @value{GDBN} Command + +@samp{gdb_get_function} in @code{gdbtk}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-info-line} Command +@findex -symbol-info-line + +@subsubheading Synopsis + +@smallexample + -symbol-info-line +@end smallexample + +Show the core addresses of the code for a source line. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} comamnd is @samp{info line}. +@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-info-symbol} Command +@findex -symbol-info-symbol + +@subsubheading Synopsis + +@smallexample + -symbol-info-symbol @var{addr} +@end smallexample + +Describe what symbol is at location @var{addr}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info symbol}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-list-functions} Command +@findex -symbol-list-functions + +@subsubheading Synopsis + +@smallexample + -symbol-list-functions +@end smallexample + +List the functions in the executable. + +@subsubheading @value{GDBN} Command + +@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and +@samp{gdb_search} in @code{gdbtk}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-list-types} Command +@findex -symbol-list-types + +@subsubheading Synopsis + +@smallexample + -symbol-list-types +@end smallexample + +List all the type names. + +@subsubheading @value{GDBN} Command + +The corresponding commands are @samp{info types} in @value{GDBN}, +@samp{gdb_search} in @code{gdbtk}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-list-variables} Command +@findex -symbol-list-variables + +@subsubheading Synopsis + +@smallexample + -symbol-list-variables +@end smallexample + +List all the global and static variable names. + +@subsubheading @value{GDBN} Command + +@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-locate} Command +@findex -symbol-locate + +@subsubheading Synopsis + +@smallexample + -symbol-locate +@end smallexample + +@subsubheading @value{GDBN} Command + +@samp{gdb_loc} in @code{gdbtk}. + +@subsubheading Example +N.A. + + +@subheading The @code{-symbol-type} Command +@findex -symbol-type + +@subsubheading Synopsis + +@smallexample + -symbol-type @var{variable} +@end smallexample + +Show type of @var{variable}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has +@samp{gdb_obj_variable}. + +@subsubheading Example +N.A. + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Target Manipulation +@section @sc{gdb/mi} Target Manipulation Commands + + +@subheading The @code{-target-attach} Command +@findex -target-attach + +@subsubheading Synopsis + +@smallexample + -target-attach @var{pid} | @var{file} +@end smallexample + +Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}. + +@subsubheading @value{GDBN} command + +The corresponding @value{GDBN} command is @samp{attach}. + +@subsubheading Example +N.A. + + +@subheading The @code{-target-compare-sections} Command +@findex -target-compare-sections + +@subsubheading Synopsis + +@smallexample + -target-compare-sections [ @var{section} ] +@end smallexample + +Compare data of section @var{section} on target to the exec file. +Without the argument, all sections are compared. + +@subsubheading @value{GDBN} Command + +The @value{GDBN} equivalent is @samp{compare-sections}. + +@subsubheading Example +N.A. + + +@subheading The @code{-target-detach} Command +@findex -target-detach + +@subsubheading Synopsis + +@smallexample + -target-detach +@end smallexample + +Disconnect from the remote target. There's no output. + +@subsubheading @value{GDBN} command + +The corresponding @value{GDBN} command is @samp{detach}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-target-detach +^done +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-target-download} Command +@findex -target-download + +@subsubheading Synopsis + +@smallexample + -target-download +@end smallexample + +Loads the executable onto the remote target. +It prints out an update message every half second, which includes the fields: + +@table @samp +@item section +The name of the section. +@item section-sent +The size of what has been sent so far for that section. +@item section-size +The size of the section. +@item total-sent +The total size of what was sent so far (the current and the previous sections). +@item total-size +The size of the overall executable to download. +@end table + +@noindent +Each message is sent as status record (@pxref{GDB/MI Output Syntax, , +@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: + +@table @samp +@item section +The name of the section. +@item section-size +The size of the section. +@item total-size +The size of the overall executable to download. +@end table + +@noindent +At the end, a summary is printed. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{load}. + +@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. + +@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}) +@end smallexample + + +@subheading The @code{-target-exec-status} Command +@findex -target-exec-status + +@subsubheading Synopsis + +@smallexample + -target-exec-status +@end smallexample + +Provide information on the state of the target (whether it is running or +not, for instance). + +@subsubheading @value{GDBN} Command + +There's no equivalent @value{GDBN} command. + +@subsubheading Example +N.A. + + +@subheading The @code{-target-list-available-targets} Command +@findex -target-list-available-targets + +@subsubheading Synopsis + +@smallexample + -target-list-available-targets +@end smallexample + +List the possible targets to connect to. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{help target}. + +@subsubheading Example +N.A. + + +@subheading The @code{-target-list-current-targets} Command +@findex -target-list-current-targets + +@subsubheading Synopsis + +@smallexample + -target-list-current-targets +@end smallexample + +Describe the current target. + +@subsubheading @value{GDBN} Command + +The corresponding information is printed by @samp{info file} (among +other things). + +@subsubheading Example +N.A. + + +@subheading The @code{-target-list-parameters} Command +@findex -target-list-parameters + +@subsubheading Synopsis + +@smallexample + -target-list-parameters +@end smallexample + +@c ???? + +@subsubheading @value{GDBN} Command + +No equivalent. + +@subsubheading Example +N.A. + + +@subheading The @code{-target-select} Command +@findex -target-select + +@subsubheading Synopsis + +@smallexample + -target-select @var{type} @var{parameters @dots{}} +@end smallexample + +Connect @value{GDBN} to the remote target. This command takes two args: + +@table @samp +@item @var{type} +The type of target, for instance @samp{async}, @samp{remote}, etc. +@item @var{parameters} +Device names, host names and the like. @xref{Target Commands, , +Commands for managing targets}, for more details. +@end table + +The output is a connection notification, followed by the address at +which the target program is, in the following form: + +@smallexample +^connected,addr="@var{address}",func="@var{function name}", + args=[@var{arg list}] +@end smallexample + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{target}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-target-select async /dev/ttya +^connected,addr="0xfe00a300",func="??",args=[] +(@value{GDBP}) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Thread Commands +@section @sc{gdb/mi} Thread Commands + + +@subheading The @code{-thread-info} Command +@findex -thread-info + +@subsubheading Synopsis + +@smallexample + -thread-info +@end smallexample + +@subsubheading @value{GDBN} command + +No equivalent. + +@subsubheading Example +N.A. + + +@subheading The @code{-thread-list-all-threads} Command +@findex -thread-list-all-threads + +@subsubheading Synopsis + +@smallexample + -thread-list-all-threads +@end smallexample + +@subsubheading @value{GDBN} Command + +The equivalent @value{GDBN} command is @samp{info threads}. + +@subsubheading Example +N.A. + + +@subheading The @code{-thread-list-ids} Command +@findex -thread-list-ids + +@subsubheading Synopsis + +@smallexample + -thread-list-ids +@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. + +@subsubheading @value{GDBN} Command + +Part of @samp{info threads} supplies the same information. + +@subsubheading Example + +No threads present, besides the main process: + +@smallexample +(@value{GDBP}) +-thread-list-ids +^done,thread-ids=@{@},number-of-threads="0" +(@value{GDBP}) +@end smallexample + + +Several threads: + +@smallexample +(@value{GDBP}) +-thread-list-ids +^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, +number-of-threads="3" +(@value{GDBP}) +@end smallexample + + +@subheading The @code{-thread-select} Command +@findex -thread-select + +@subsubheading Synopsis + +@smallexample + -thread-select @var{threadnum} +@end smallexample + +Make @var{threadnum} the current thread. It prints the number of the new +current thread, and the topmost frame for that thread. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{thread}. + +@subsubheading Example + +@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=@{thread-id="3",thread-id="2",thread-id="1"@}, +number-of-threads="3" +(@value{GDBP}) +-thread-select 3 +^done,new-thread-id="3", +frame=@{level="0",func="vprintf", +args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@}, +@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@} +(@value{GDBP}) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Tracepoint Commands +@section @sc{gdb/mi} Tracepoint Commands + +The tracepoint commands are not yet implemented. + +@c @subheading -trace-actions + +@c @subheading -trace-delete + +@c @subheading -trace-disable + +@c @subheading -trace-dump + +@c @subheading -trace-enable + +@c @subheading -trace-exists + +@c @subheading -trace-find + +@c @subheading -trace-frame-number + +@c @subheading -trace-info + +@c @subheading -trace-insert + +@c @subheading -trace-list + +@c @subheading -trace-pass-count + +@c @subheading -trace-save + +@c @subheading -trace-start + +@c @subheading -trace-stop + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Variable Objects +@section @sc{gdb/mi} Variable Objects + + +@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: + +@enumerate 1 +@item +It has been proven in practice (it is already on its second generation). + +@item +It will shorten development time (needless to say how important it is +now). +@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. + +@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: + +@itemize @bullet +@item @code{-gdb-show} @code{output-radix} +@item @code{-stack-list-arguments} +@item @code{-stack-list-locals} +@item @code{-stack-select-frame} +@end itemize + +@subheading Introduction to Variable Objects in @sc{gdb/mi} + +@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@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: + +@multitable @columnfractions .4 .6 +@item @strong{Operation} +@tab @strong{Description} + +@item @code{-var-create} +@tab create a variable object +@item @code{-var-delete} +@tab delete the variable object and its children +@item @code{-var-set-format} +@tab set the display format of this variable +@item @code{-var-show-format} +@tab show the display format of this variable +@item @code{-var-info-num-children} +@tab tells how many children this object has +@item @code{-var-list-children} +@tab return a list of the object's children +@item @code{-var-info-type} +@tab show the type of this variable object +@item @code{-var-info-expression} +@tab print what this variable object represents +@item @code{-var-show-attributes} +@tab is this variable editable? does it exist here? +@item @code{-var-evaluate-expression} +@tab get the value of this variable +@item @code{-var-assign} +@tab set the value of this variable +@item @code{-var-update} +@tab update the variable and its children +@end multitable + +In the next subsection we describe each operation in detail and suggest +how it can be used. + +@subheading Description And Use of Operations on Variable Objects + +@subheading The @code{-var-create} Command +@findex -var-create + +@subsubheading Synopsis + +@smallexample + -var-create @{@var{name} | "-"@} + @{@var{frame-addr} | "*"@} @var{expression} +@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. + +@var{expression} is any expression valid on the current language set (must not +begin with a @samp{*}), or one of the following: + +@itemize @bullet +@item +@samp{*@var{addr}}, where @var{addr} is the address of a memory cell + +@item +@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD) + +@item +@samp{$@var{regname}} --- a CPU register name +@end itemize + +@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: + +@smallexample + name="@var{name}",numchild="N",type="@var{type}" +@end smallexample + + +@subheading The @code{-var-delete} Command +@findex -var-delete + +@subsubheading Synopsis + +@smallexample + -var-delete @var{name} +@end smallexample + +Deletes a previously created variable object and all of its children. + +Returns an error if the object @var{name} is not found. + + +@subheading The @code{-var-set-format} Command +@findex -var-set-format + +@subsubheading Synopsis + +@smallexample + -var-set-format @var{name} @var{format-spec} +@end smallexample + +Sets the output format for the value of the object @var{name} to be +@var{format-spec}. + +The syntax for the @var{format-spec} is as follows: + +@smallexample + @var{format-spec} @expansion{} + @{binary | decimal | hexadecimal | octal | natural@} +@end smallexample + + +@subheading The @code{-var-show-format} Command +@findex -var-show-format + +@subsubheading Synopsis + +@smallexample + -var-show-format @var{name} +@end smallexample + +Returns the format used to display the value of the object @var{name}. + +@smallexample + @var{format} @expansion{} + @var{format-spec} +@end smallexample + + +@subheading The @code{-var-info-num-children} Command +@findex -var-info-num-children + +@subsubheading Synopsis + +@smallexample + -var-info-num-children @var{name} +@end smallexample + +Returns the number of children of a variable object @var{name}: + +@smallexample + numchild=@var{n} +@end smallexample + + +@subheading The @code{-var-list-children} Command +@findex -var-list-children + +@subsubheading Synopsis + +@smallexample + -var-list-children @var{name} +@end smallexample + +Returns a list of the children of the specified variable object: + +@smallexample + numchild=@var{n},children=[@{name=@var{name}, + numchild=@var{n},type=@var{type}@},@r{(repeats N times)}] +@end smallexample + + +@subheading The @code{-var-info-type} Command +@findex -var-info-type + +@subsubheading Synopsis + +@smallexample + -var-info-type @var{name} +@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 +@value{GDBN} CLI: + +@smallexample + type=@var{typename} +@end smallexample + + +@subheading The @code{-var-info-expression} Command +@findex -var-info-expression + +@subsubheading Synopsis + +@smallexample + -var-info-expression @var{name} +@end smallexample + +Returns what is represented by the variable object @var{name}: + +@smallexample + lang=@var{lang-spec},exp=@var{expression} +@end smallexample + +@noindent +where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}. + +@subheading The @code{-var-show-attributes} Command +@findex -var-show-attributes + +@subsubheading Synopsis + +@smallexample + -var-show-attributes @var{name} +@end smallexample + +List attributes of the specified variable object @var{name}: + +@smallexample + status=@var{attr} [ ( ,@var{attr} )* ] +@end smallexample + +@noindent +where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}. + +@subheading The @code{-var-evaluate-expression} Command +@findex -var-evaluate-expression + +@subsubheading Synopsis + +@smallexample + -var-evaluate-expression @var{name} +@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: + +@smallexample + value=@var{value} +@end smallexample + +Note that one must invoke @code{-var-list-children} for a variable +before the value of a child variable can be evaluated. + +@subheading The @code{-var-assign} Command +@findex -var-assign + +@subsubheading Synopsis + +@smallexample + -var-assign @var{name} @var{expression} +@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. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-var-assign var1 3 +^done,value="3" +(@value{GDBP}) +-var-update * +^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}] +(@value{GDBP}) +@end smallexample + +@subheading The @code{-var-update} Command +@findex -var-update + +@subsubheading Synopsis + +@smallexample + -var-update @{@var{name} | "*"@} +@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. + + +@node Annotations +@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. + +@ignore +This is Edition @value{EDITION}, @value{DATE}. +@end ignore + +@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. +@end menu + +@node Annotations Overview +@section What is an Annotation? +@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 +@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: + +@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 +$ +@end smallexample + +Here @samp{quit} is input to @value{GDBN}; the rest is output from +@value{GDBN}. 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}. + +@node Server Prefix +@section The Server Prefix +@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. + +@node Value Annotations +@section Values + +@cindex annotations for values +When a value is printed in various contexts, @value{GDBN} uses +annotations to delimit the value from the surrounding text. + +@findex value-history-begin +@findex value-history-value +@findex value-history-end +If a value is printed using @code{print} and added to the value history, +the annotation looks like + +@smallexample +^Z^Zvalue-history-begin @var{history-number} @var{value-flags} +@var{history-string} +^Z^Zvalue-history-value +@var{the-value} +^Z^Zvalue-history-end +@end smallexample + +@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. + +@findex value-begin +@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: + +@smallexample +^Z^Zvalue-begin @var{value-flags} +@var{the-value} +^Z^Zvalue-end +@end smallexample + +@findex arg-begin +@findex arg-name-end +@findex arg-value +@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: + +@smallexample +^Z^Zarg-begin +@var{argument-name} +^Z^Zarg-name-end +@var{separator-string} +^Z^Zarg-value @var{value-flags} +@var{the-value} +^Z^Zarg-end +@end smallexample + +@noindent +where @var{argument-name} is the name of the argument, +@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. + +@findex field-begin +@findex field-name-end +@findex field-value +@findex field-end +When printing a structure, @value{GDBN} annotates it as follows: + +@smallexample +^Z^Zfield-begin @var{value-flags} +@var{field-name} +^Z^Zfield-name-end +@var{separator-string} +^Z^Zfield-value +@var{the-value} +^Z^Zfield-end +@end smallexample + +@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: + +@smallexample +^Z^Zarray-section-begin @var{array-index} @var{value-flags} +@end smallexample + +@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 +@code{value-history-begin} annotation. This is followed by any number +of elements, where is element can be either a single element: + +@findex elt +@smallexample +@samp{,} @var{whitespace} ; @r{omitted for the first element} +@var{the-value} +^Z^Zelt +@end smallexample + +or a repeated element + +@findex elt-rep +@findex elt-rep-end +@smallexample +@samp{,} @var{whitespace} ; @r{omitted for the first element} +@var{the-value} +^Z^Zelt-rep @var{number-of-repetitions} +@var{repetition-string} +^Z^Zelt-rep-end +@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 +@var{repetition-string} is a string which is designed to convey to the +user that repetition is being depicted. + +@findex array-section-end +Once all the array elements have been output, the array annotation is +ended with + +@smallexample +^Z^Zarray-section-end +@end smallexample + +@node Frame Annotations +@section Frames + +@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 +@code{backtrace} or @code{up}, etc. + +@findex frame-begin +The frame annotation begins with + +@smallexample +^Z^Zframe-begin @var{level} @var{address} +@var{level-string} +@end smallexample + +@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 +@samp{0x} followed by one or more lowercase hex digits (note that this +does not depend on the language). The frame ends with + +@findex frame-end +@smallexample +^Z^Zframe-end +@end smallexample + +Between these annotations is the main body of the frame, which can +consist of + +@itemize @bullet +@item +@findex function-call +@smallexample +^Z^Zfunction-call +@var{function-call-string} +@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. + +@item +@findex signal-handler-caller +@smallexample +^Z^Zsignal-handler-caller +@var{signal-handler-caller-string} +@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). + +@item +A normal frame. + +@findex frame-address +@findex frame-address-end +This can optionally (depending on whether this is thought of as +interesting information for the user to see) begin with + +@smallexample +^Z^Zframe-address +@var{address} +^Z^Zframe-address-end +@var{separator-string} +@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. + +@findex frame-function-name +@findex frame-args +Then comes + +@smallexample +^Z^Zframe-function-name +@var{function-name} +^Z^Zframe-args +@var{arguments} +@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}). + +@findex frame-source-begin +@findex frame-source-file +@findex frame-source-file-end +@findex frame-source-line +@findex frame-source-end +If source information is available, a reference to it is then printed: + +@smallexample +^Z^Zframe-source-begin +@var{source-intro-string} +^Z^Zframe-source-file +@var{filename} +^Z^Zframe-source-file-end +: +^Z^Zframe-source-line +@var{line-number} +^Z^Zframe-source-end +@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). + +@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 + +@smallexample +^Z^Zframe-where +@var{information} +@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 +@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. +@end itemize + +@node Displays +@section Displays + +@findex display-begin +@findex display-number-end +@findex display-format +@findex display-expression +@findex display-expression-end +@findex display-value +@findex display-end +@cindex annotations for display +When @value{GDBN} is told to display something using the @code{display} command, +the results of the display are annotated: + +@smallexample +^Z^Zdisplay-begin +@var{number} +^Z^Zdisplay-number-end +@var{number-separator} +^Z^Zdisplay-format +@var{format} +^Z^Zdisplay-expression +@var{expression} +^Z^Zdisplay-expression-end +@var{expression-separator} +^Z^Zdisplay-value +@var{value} +^Z^Zdisplay-end +@end smallexample + +@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, +@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. + +@node Prompting +@section Annotation for @value{GDBN} Input + +@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: + +@smallexample +^Z^Zpre-prompt +^Z^Zprompt +^Z^Zpost-prompt +@end smallexample + +The input types are + +@table @code +@findex pre-prompt +@findex prompt +@findex post-prompt +@item prompt +When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt). + +@findex pre-commands +@findex commands +@findex post-commands +@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. + +@findex pre-overload-choice +@findex overload-choice +@findex post-overload-choice +@item overload-choice +When @value{GDBN} wants the user to select between various overloaded functions. + +@findex pre-query +@findex query +@findex post-query +@item query +When @value{GDBN} wants the user to confirm a potentially dangerous operation. + +@findex pre-prompt-for-continue +@findex prompt-for-continue +@findex post-prompt-for-continue +@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. +@end table + +@node Errors +@section Errors +@cindex annotations for errors, warnings and interrupts + +@findex quit +@smallexample +^Z^Zquit +@end smallexample + +This annotation occurs right before @value{GDBN} responds to an interrupt. + +@findex error +@smallexample +^Z^Zerror +@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 +@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. + +@findex error-begin +A quit or error annotation may be preceded by + +@smallexample +^Z^Zerror-begin +@end smallexample + +Any output between that and the quit or error annotation is the error +message. + +Warning messages are not yet annotated. +@c If we want to change that, need to fix warning(), type_error(), +@c range_error(), and possibly other places. + +@node Breakpoint Info +@section Information on Breakpoints + +@cindex annotations for breakpoints +The output from the @code{info breakpoints} command is annotated as follows: + +@findex breakpoints-headers +@findex breakpoints-table +@smallexample +^Z^Zbreakpoints-headers +@var{header-entry} +^Z^Zbreakpoints-table +@end smallexample + +@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: + +@findex record +@findex field +@smallexample +^Z^Zrecord +^Z^Zfield 0 +@var{number} +^Z^Zfield 1 +@var{type} +^Z^Zfield 2 +@var{disposition} +^Z^Zfield 3 +@var{enable} +^Z^Zfield 4 +@var{address} +^Z^Zfield 5 +@var{what} +^Z^Zfield 6 +@var{frame} +^Z^Zfield 7 +@var{condition} +^Z^Zfield 8 +@var{ignore-count} +^Z^Zfield 9 +@var{commands} +@end smallexample + +Note that @var{address} is intended for user consumption---the syntax +varies depending on the language. + +The output ends with + +@findex breakpoints-table-end +@smallexample +^Z^Zbreakpoints-table-end +@end smallexample + +@node Invalidation +@section Invalidation Notices + +@cindex annotations for invalidation messages +The following annotations say that certain pieces of state may have +changed. + +@table @code +@findex frames-invalid +@item ^Z^Zframes-invalid + +The frames (for example, output from the @code{backtrace} command) may +have changed. + +@findex breakpoints-invalid +@item ^Z^Zbreakpoints-invalid + +The breakpoints may have changed. For example, the user just added or +deleted a breakpoint. +@end table + +@node Annotations for Running +@section Running the Program +@cindex annotations for running programs + +@findex starting +@findex stopping +When the program starts executing due to a @value{GDBN} command such as +@code{step} or @code{continue}, + +@smallexample +^Z^Zstarting +@end smallexample + +is output. When the program stops, + +@smallexample +^Z^Zstopped +@end smallexample + +is output. Before the @code{stopped} annotation, a variety of +annotations describe how the program stopped. + +@table @code +@findex exited +@item ^Z^Zexited @var{exit-status} +The program exited, and @var{exit-status} is the exit status (zero for +successful exit, otherwise nonzero). + +@findex signalled +@findex signal-name +@findex signal-name-end +@findex signal-string +@findex signal-string-end +@item ^Z^Zsignalled +The program exited with a signal. After the @code{^Z^Zsignalled}, the +annotation continues: + +@smallexample +@var{intro-text} +^Z^Zsignal-name +@var{name} +^Z^Zsignal-name-end +@var{middle-text} +^Z^Zsignal-string +@var{string} +^Z^Zsignal-string-end +@var{end-text} +@end smallexample + +@noindent +where @var{name} is the name of the signal, such as @code{SIGILL} or +@code{SIGSEGV}, and @var{string} is the explanation of the signal, such +as @code{Illegal Instruction} or @code{Segmentation fault}. +@var{intro-text}, @var{middle-text}, and @var{end-text} are for the +user's benefit and have no particular format. + +@findex signal +@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. + +@findex breakpoint +@item ^Z^Zbreakpoint @var{number} +The program hit breakpoint number @var{number}. + +@findex watchpoint +@item ^Z^Zwatchpoint @var{number} +The program hit watchpoint number @var{number}. +@end table + +@node Source Annotations +@section Displaying Source +@cindex annotations for source display + +@findex source +The following annotation is used instead of displaying source code: + +@smallexample +^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr} +@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), +@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 +@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). + +@node TODO +@section Annotations We Might Want in the Future + +@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. +@end format @node GDB Bugs @chapter Reporting Bugs in @value{GDBN} |