1 @c \input texinfo @c -*-texinfo-*-
2 @c @c %**start of header
3 @c @setfilename gdbmi.info
4 @c @settitle GDB/MI Machine Interface
5 @c @setchapternewpage off
9 @c This file documents GDB/MI, a Machine Interface to GDB.
11 @c Copyright 2000, 2001 Free Software Foundation, Inc.
12 @c Contributed by Cygnus Solutions.
14 @c Permission is granted to copy, distribute and/or modify this document
15 @c under the terms of the GNU Free Documentation License, Version 1.1 or
16 @c any later version published by the Free Software Foundation; with the
17 @c Invariant Sections being ``The GDB/MI Interface'' and ``GGDB/MI
18 @c Command Syntax'', with the Front-Cover texts being ``A GNU Manual,''
19 @c and with the Back-Cover Texts as in (a) below.
21 @c (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
22 @c this GNU Manual, like GNU software. Copies published by the Free
23 @c Software Foundation raise funds for GNU development.''
26 @c @c This title page illustrates only one of the
27 @c @c two methods of forming a title page.
31 @c @subtitle Version 0.3
33 @c @author Andrew Cagney, Fernando Nasser and Elena Zannoni
35 @c @c The following two commands
36 @c @c start the copyright page.
38 @c @vskip 0pt plus 1filll
40 @c Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.
42 @c Permission is granted to copy, distribute and/or modify this document
43 @c under the terms of the GNU Free Documentation License, Version 1.1 or
44 @c any later version published by the Free Software Foundation; with the
45 @c Invariant Sections being ``The GDB/MI Interface'' and ``GGDB/MI
46 @c Command Syntax'', with the Front-Cover texts being ``A GNU Manual,''
47 @c and with the Back-Cover Texts as in (a) below.
49 @c (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
50 @c this GNU Manual, like GNU software. Copies published by the Free
51 @c Software Foundation raise funds for GNU development.''
54 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
56 @chapter The @sc{gdb/mi} Interface
58 @unnumberedsec Function and Purpose
60 @cindex @sc{gdb/mi}, its purpose
61 @sc{gdb/mi} is a line based machine oriented text interface to @value{GDBN}. It is
62 specifically intended to support the development of systems which use
63 the debugger as just one small component of a larger system.
65 This chapter is a specification of the @sc{gdb/mi} interface. It is written
66 in the form of a reference manual.
68 Note that @sc{gdb/mi} is still under construction, so some of the
69 features described below are incomplete and subject to change.
71 @unnumberedsec Notation and Terminology
73 @cindex notational conventions, for @sc{gdb/mi}
74 This chapter uses the following notation:
78 @code{|} separates two alternatives.
81 @code{[ @var{something} ]} indicates that @var{something} is optional:
82 it may or may not be given.
85 @code{( @var{group} )*} means that @var{group} inside the parentheses
86 may repeat zero or more times.
89 @code{( @var{group} )+} means that @var{group} inside the parentheses
90 may repeat one or more times.
93 @code{"@var{string}"} means a literal @var{string}.
100 @heading Acknowledgments
102 In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
106 * GDB/MI Command Syntax::
107 * GDB/MI Compatibility with CLI::
108 * GDB/MI Output Records::
109 * GDB/MI Command Description Format::
110 * GDB/MI Breakpoint Table Commands::
111 * GDB/MI Data Manipulation::
112 * GDB/MI Program Control::
113 * GDB/MI Miscellaneous Commands::
114 * GDB/MI Stack Manipulation::
115 * GDB/MI Symbol Query::
116 * GDB/MI Target Manipulation::
117 * GDB/MI Thread Commands::
118 * GDB/MI Tracepoint Commands::
119 * GDB/MI Variable Objects::
122 @c When these are implemented, they should be moved to be between Misc and
123 @c Stack Manipulation in the above menu. They are now outside the menu
124 @c because makeinfo 3.12 barfs if it sees @ignore or @comments in the
127 * GDB/MI Kod Commands::
128 * GDB/MI Memory Overlay Commands::
129 * GDB/MI Signal Handling Commands::
132 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
133 @node GDB/MI Command Syntax
134 @section @sc{gdb/mi} Command Syntax
137 * GDB/MI Input Syntax::
138 * GDB/MI Output Syntax::
139 * GDB/MI Simple Examples::
142 @node GDB/MI Input Syntax
143 @subsection @sc{gdb/mi} Input Syntax
145 @cindex input syntax for @sc{gdb/mi}
146 @cindex @sc{gdb/mi}, input syntax
148 @item @var{command} @expansion{}
149 @code{@var{cli-command} | @var{mi-command}}
151 @item @var{cli-command} @expansion{}
152 @code{[ @var{token} ] @var{cli-command} @var{nl}}, where
153 @var{cli-command} is any existing @value{GDBN} CLI command.
155 @item @var{mi-command} @expansion{}
156 @code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )*
157 @code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}}
159 @item @var{token} @expansion{}
160 "any sequence of digits"
162 @item @var{option} @expansion{}
163 @code{"-" @var{parameter} [ " " @var{parameter} ]}
165 @item @var{parameter} @expansion{}
166 @code{@var{non-blank-sequence} | @var{c-string}}
168 @item @var{operation} @expansion{}
169 @emph{any of the operations described in this chapter}
171 @item @var{non-blank-sequence} @expansion{}
172 @emph{anything, provided it doesn't contain special characters such as
173 "-", @var{nl}, """ and of course " "}
175 @item @var{c-string} @expansion{}
176 @code{""" @var{seven-bit-iso-c-string-content} """}
178 @item @var{nl} @expansion{}
187 The CLI commands are still handled by the @sc{mi} interpreter; their
188 output is described below.
191 The @code{@var{token}}, when present, is passed back when the command
195 Some @sc{mi} commands accept optional arguments as part of the parameter
196 list. Each option is identified by a leading @samp{-} (dash) and may be
197 followed by an optional argument parameter. Options occur first in the
198 parameter list and can be delimited from normal parameters using
199 @samp{--} (this is useful when some parameters begin with a dash).
206 We want easy access to the existing CLI syntax (for debugging).
209 We want it to be easy to spot a @sc{mi} operation.
212 @node GDB/MI Output Syntax
213 @subsection @sc{gdb/mi} Output Syntax
215 @cindex output syntax of @sc{gdb/mi}
216 @cindex @sc{gdb/mi}, output syntax
217 The output from @sc{gdb/mi} consists of zero or more out-of-band records
218 followed, optionally, by a single result record. This result record
219 is for the most recent command. The sequence of output records is
220 terminated by @samp{(@value{GDBP})}.
222 If an input command was prefixed with a @code{@var{token}} then the
223 corresponding output for that command will also be prefixed by that same
227 @item @var{output} @expansion{}
228 @code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
230 @item @var{result-record} @expansion{}
231 @code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
233 @item @var{out-of-band-record} @expansion{}
234 @code{@var{async-record} | @var{stream-record}}
236 @item @var{async-record} @expansion{}
237 @code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
239 @item @var{exec-async-output} @expansion{}
240 @code{[ @var{token} ] "*" @var{async-output}}
242 @item @var{status-async-output} @expansion{}
243 @code{[ @var{token} ] "+" @var{async-output}}
245 @item @var{notify-async-output} @expansion{}
246 @code{[ @var{token} ] "=" @var{async-output}}
248 @item @var{async-output} @expansion{}
249 @code{@var{async-class} ( "," @var{result} )* @var{nl}}
251 @item @var{result-class} @expansion{}
252 @code{"done" | "running" | "connected" | "error" | "exit"}
254 @item @var{async-class} @expansion{}
255 @code{"stopped" | @var{others}} (where @var{others} will be added
256 depending on the needs---this is still in development).
258 @item @var{result} @expansion{}
259 @code{ @var{variable} "=" @var{value}}
261 @item @var{variable} @expansion{}
262 @code{ @var{string} }
264 @item @var{value} @expansion{}
265 @code{ @var{const} | @var{tuple} | @var{list} }
267 @item @var{const} @expansion{}
268 @code{@var{c-string}}
270 @item @var{tuple} @expansion{}
271 @code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" }
273 @item @var{list} @expansion{}
274 @code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "["
275 @var{result} ( "," @var{result} )* "]" }
277 @item @var{stream-record} @expansion{}
278 @code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
280 @item @var{console-stream-output} @expansion{}
281 @code{"~" @var{c-string}}
283 @item @var{target-stream-output} @expansion{}
284 @code{"@@" @var{c-string}}
286 @item @var{log-stream-output} @expansion{}
287 @code{"&" @var{c-string}}
289 @item @var{nl} @expansion{}
292 @item @var{token} @expansion{}
293 @emph{any sequence of digits}.
297 In addition, the following are still being developed:
301 This action is currently undefined.
309 All output sequences end in a single line containing a period.
312 The @code{@var{token}} is from the corresponding request. If an execution
313 command is interrupted by the @samp{-exec-interrupt} command, the
314 @var{token} associated with the @samp{*stopped} message is the one of the
315 original execution command, not the one of the interrupt command.
318 @cindex status output in @sc{gdb/mi}
319 @var{status-async-output} contains on-going status information about the
320 progress of a slow operation. It can be discarded. All status output is
321 prefixed by @samp{+}.
324 @cindex async output in @sc{gdb/mi}
325 @var{exec-async-output} contains asynchronous state change on the target
326 (stopped, started, disappeared). All async output is prefixed by
330 @cindex notify output in @sc{gdb/mi}
331 @var{notify-async-output} contains supplementary information that the
332 client should handle (e.g., a new breakpoint information). All notify
333 output is prefixed by @samp{=}.
336 @cindex console output in @sc{gdb/mi}
337 @var{console-stream-output} is output that should be displayed as is in the
338 console. It is the textual response to a CLI command. All the console
339 output is prefixed by @samp{~}.
342 @cindex target output in @sc{gdb/mi}
343 @var{target-stream-output} is the output produced by the target program.
344 All the target output is prefixed by @samp{@@}.
347 @cindex log output in @sc{gdb/mi}
348 @var{log-stream-output} is output text coming from @value{GDBN}'s internals, for
349 instance messages that should be displayed as part of an error log. All
350 the log output is prefixed by @samp{&}.
353 @cindex list output in @sc{gdb/mi}
354 New @sc{gdb/mi} commands should only output @var{lists} containing
360 @xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
361 details about the various output records.
363 @node GDB/MI Simple Examples
364 @subsection Simple Examples of @sc{gdb/mi} Interaction
365 @cindex @sc{gdb/mi}, simple examples
367 This subsection presents several simple examples of interaction using
368 the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
369 following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
370 the output received from @sc{gdb/mi}.
372 @subsubheading Target Stop
374 Here's an example of stopping the inferior process:
385 <- *stop,reason="stop",address="0x123",source="a.c:123"
389 @subsubheading Simple CLI Command
391 Here's an example of a simple CLI command being passed through
392 @sc{gdb/mi} and on to the CLI.
400 @subsubheading Command With Side Effects
403 -> -symbol-file xyz.exe
404 <- *breakpoint,nr="3",address="0x123",source="a.c:123"
408 @subsubheading A Bad Command
410 Here's what happens if you pass a non-existent command:
414 <- error,"Rubbish not found"
418 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
419 @node GDB/MI Compatibility with CLI
420 @section @sc{gdb/mi} Compatibility with CLI
422 @cindex compatibility, @sc{gdb/mi} and CLI
423 @cindex @sc{gdb/mi}, compatibility with CLI
424 To help users familiar with @value{GDBN}'s existing CLI interface, @sc{gdb/mi}
425 accepts existing CLI commands. As specified by the syntax, such
426 commands can be directly entered into the @sc{gdb/mi} interface and @value{GDBN} will
429 This mechanism is provided as an aid to developers of @sc{gdb/mi}
430 clients and not as a reliable interface into the CLI. Since the command
431 is being interpreteted in an environment that assumes @sc{gdb/mi}
432 behaviour, the exact output of such commands is likely to end up being
433 an un-supported hybrid of @sc{gdb/mi} and CLI output.
435 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
436 @node GDB/MI Output Records
437 @section @sc{gdb/mi} Output Records
440 * GDB/MI Result Records::
441 * GDB/MI Stream Records::
442 * GDB/MI Out-of-band Records::
445 @node GDB/MI Result Records
446 @subsection @sc{gdb/mi} Result Records
448 @cindex result records in @sc{gdb/mi}
449 @cindex @sc{gdb/mi}, result records
450 In addition to a number of out-of-band notifications, the response to a
451 @sc{gdb/mi} command includes one of the following result indications:
455 @item "^done" [ "," @var{results} ]
456 The synchronous operation was successful, @code{@var{results}} are the return
461 @c Is this one correct? Should it be an out-of-band notification?
462 The asynchronous operation was successfully started. The target is
465 @item "^error" "," @var{c-string}
467 The operation failed. The @code{@var{c-string}} contains the corresponding
471 @node GDB/MI Stream Records
472 @subsection @sc{gdb/mi} Stream Records
474 @cindex @sc{gdb/mi}, stream records
475 @cindex stream records in @sc{gdb/mi}
476 @value{GDBN} internally maintains a number of output streams: the console, the
477 target, and the log. The output intended for each of these streams is
478 funneled through the @sc{gdb/mi} interface using @dfn{stream records}.
480 Each stream record begins with a unique @dfn{prefix character} which
481 identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output
482 Syntax}). In addition to the prefix, each stream record contains a
483 @code{@var{string-output}}. This is either raw text (with an implicit new
484 line) or a quoted C string (which does not contain an implicit newline).
487 @item "~" @var{string-output}
488 The console output stream contains text that should be displayed in the
489 CLI console window. It contains the textual responses to CLI commands.
491 @item "@@" @var{string-output}
492 The target output stream contains any textual output from the running
495 @item "&" @var{string-output}
496 The log stream contains debugging messages being produced by @value{GDBN}'s
500 @node GDB/MI Out-of-band Records
501 @subsection @sc{gdb/mi} Out-of-band Records
503 @cindex out-of-band records in @sc{gdb/mi}
504 @cindex @sc{gdb/mi}, out-of-band records
505 @dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of
506 additional changes that have occurred. Those changes can either be a
507 consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
508 target activity (e.g., target stopped).
510 The following is a preliminary list of possible out-of-band records.
517 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
518 @node GDB/MI Command Description Format
519 @section @sc{gdb/mi} Command Description Format
521 The remaining sections describe blocks of commands. Each block of
522 commands is laid out in a fashion similar to this section.
524 Note the the line breaks shown in the examples are here only for
525 readability. They don't appear in the real output.
526 Also note that the commands with a non-available example (N.A.@:) are
529 @subheading Motivation
531 The motivation for this collection of commands.
533 @subheading Introduction
535 A brief introduction to this collection of commands as a whole.
539 For each command in the block, the following is described:
541 @subsubheading Synopsis
544 -command @var{args}@dots{}
547 @subsubheading @value{GDBN} Command
549 The corresponding @value{GDBN} CLI command.
551 @subsubheading Result
553 @subsubheading Out-of-band
557 @subsubheading Example
560 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
561 @node GDB/MI Breakpoint Table Commands
562 @section @sc{gdb/mi} Breakpoint table commands
564 @cindex breakpoint commands for @sc{gdb/mi}
565 @cindex @sc{gdb/mi}, breakpoint commands
566 This section documents @sc{gdb/mi} commands for manipulating
569 @subheading The @code{-break-after} Command
572 @subsubheading Synopsis
575 -break-after @var{number} @var{count}
578 The breakpoint number @var{number} is not in effect until it has been
579 hit @var{count} times. To see how this is reflected in the output of
580 the @samp{-break-list} command, see the description of the
581 @samp{-break-list} command below.
583 @subsubheading @value{GDBN} Command
585 The corresponding @value{GDBN} command is @samp{ignore}.
587 @subsubheading Example
592 ^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@}
599 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
600 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
601 addr="0x000100d0",func="main",file="hello.c",line="5",times="0",
607 @subheading The @code{-break-catch} Command
610 @subheading The @code{-break-commands} Command
611 @findex -break-commands
615 @subheading The @code{-break-condition} Command
616 @findex -break-condition
618 @subsubheading Synopsis
621 -break-condition @var{number} @var{expr}
624 Breakpoint @var{number} will stop the program only if the condition in
625 @var{expr} is true. The condition becomes part of the
626 @samp{-break-list} output (see the description of the @samp{-break-list}
629 @subsubheading @value{GDBN} Command
631 The corresponding @value{GDBN} command is @samp{condition}.
633 @subsubheading Example
641 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
642 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
643 addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",
644 times="0",ignore="3"@}@}
648 @subheading The @code{-break-delete} Command
649 @findex -break-delete
651 @subsubheading Synopsis
654 -break-delete ( @var{breakpoint} )+
657 Delete the breakpoint(s) whose number(s) are specified in the argument
658 list. This is obviously reflected in the breakpoint list.
660 @subsubheading @value{GDBN} command
662 The corresponding @value{GDBN} command is @samp{delete}.
664 @subsubheading Example
672 ^done,BreakpointTable=@{@}
676 @subheading The @code{-break-disable} Command
677 @findex -break-disable
679 @subsubheading Synopsis
682 -break-disable ( @var{breakpoint} )+
685 Disable the named @var{breakpoint}(s). The field @samp{enabled} in the
686 break list is now set to @samp{n} for the named @var{breakpoint}(s).
688 @subsubheading @value{GDBN} Command
690 The corresponding @value{GDBN} command is @samp{disable}.
692 @subsubheading Example
700 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
701 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
702 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@}
706 @subheading The @code{-break-enable} Command
707 @findex -break-enable
709 @subsubheading Synopsis
712 -break-enable ( @var{breakpoint} )+
715 Enable (previously disabled) @var{breakpoint}(s).
717 @subsubheading @value{GDBN} Command
719 The corresponding @value{GDBN} command is @samp{enable}.
721 @subsubheading Example
729 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
730 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
731 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@}
735 @subheading The @code{-break-info} Command
738 @subsubheading Synopsis
741 -break-info @var{breakpoint}
745 Get information about a single breakpoint.
747 @subsubheading @value{GDBN} command
749 The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
751 @subsubheading Example
754 @subheading The @code{-break-insert} Command
755 @findex -break-insert
757 @subsubheading Synopsis
760 -break-insert [ -t ] [ -h ] [ -r ]
761 [ -c @var{condition} ] [ -i @var{ignore-count} ]
762 [ -p @var{thread} ] [ @var{line} | @var{addr} ]
766 If specified, @var{line}, can be one of:
773 @item filename:linenum
774 @item filename:function
778 The possible optional parameters of this command are:
782 Insert a tempoary breakpoint.
784 Insert a hardware breakpoint.
785 @item -c @var{condition}
786 Make the breakpoint conditional on @var{condition}.
787 @item -i @var{ignore-count}
788 Initialize the @var{ignore-count}.
790 Insert a regular breakpoint in all the functions whose names match the
791 given regular expression. Other flags are not applicable to regular
795 @subsubheading Result
797 The result is in the form:
800 ^done,bkptno="@var{number}",func="@var{funcname}",
801 file="@var{filename}",line="@var{lineno}"
805 where @var{number} is the @value{GDBN} number for this breakpoint, @var{funcname}
806 is the name of the function where the breakpoint was inserted,
807 @var{filename} is the name of the source file which contains this
808 function, and @var{lineno} is the source line number within that file.
810 Note: this format is open to change.
811 @c An out-of-band breakpoint instead of part of the result?
813 @subsubheading @value{GDBN} Command
815 The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
816 @samp{hbreak}, @samp{thbreak}, and @samp{rbreak}.
818 @subsubheading Example
823 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
826 ^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@}
829 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
830 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
831 addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@},
832 bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
833 addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}@}
835 -break-insert -r foo.*
837 ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@}
841 @subheading The @code{-break-list} Command
844 @subsubheading Synopsis
850 Displays the list of inserted breakpoints, showing the following fields:
854 number of the breakpoint
856 type of the breakpoint: @samp{breakpoint} or @samp{watchpoint}
858 should the breakpoint be deleted or disabled when it is hit: @samp{keep}
861 is the breakpoint enabled or no: @samp{y} or @samp{n}
863 memory location at which the breakpoint is set
865 logical location of the breakpoint, expressed by function name, file
868 number of times the breakpoint has been hit
871 If there are no breakpoints or watchpoints, the @code{BreakpointTable}
872 field is an empty list.
874 @subsubheading @value{GDBN} Command
876 The corresponding @value{GDBN} command is @samp{info break}.
878 @subsubheading Example
883 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
884 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
885 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
886 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
887 addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}@}
891 Here's an example of the result when there are no breakpoints:
896 ^done,BreakpointTable=@{@}
900 @subheading The @code{-break-watch} Command
903 @subsubheading Synopsis
906 -break-watch [ -a | -r ]
909 Create a watchpoint. With the @samp{-a} option it will create an
910 @dfn{access} watchpoint, i.e. a watchpoint that triggers either on a
911 read from or on a write to the memory location. With the @samp{-r}
912 option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will
913 trigger only when the memory location is accessed for reading. Without
914 either of the options, the watchpoint created is a regular watchpoint,
915 i.e. it will trigger when the memory location is accessed for writing.
916 @xref{Set Watchpoints, , Setting watchpoints}.
918 Note that @samp{-break-list} will report a single list of watchpoints and
919 breakpoints inserted.
921 @subsubheading @value{GDBN} Command
923 The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and
926 @subsubheading Example
928 Setting a watchpoint on a variable in the @code{main} function:
933 ^done,wpt=@{number="2",exp="x"@}
937 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
938 value=@{old="-268439212",new="55"@},
939 frame=@{func="main",args=[],file="recursive2.c",line="5"@}
943 Setting a watchpoint on a variable local to a function. @value{GDBN} will stop
944 the program execution twice: first for the variable changing value, then
945 for the watchpoint going out of scope.
950 ^done,wpt=@{number="5",exp="C"@}
954 ^done,reason="watchpoint-trigger",
955 wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
956 frame=@{func="callee4",args=[],
957 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
961 ^done,reason="watchpoint-scope",wpnum="5",
962 frame=@{func="callee3",args=[@{name="strarg",
963 value="0x11940 \"A string argument.\""@}],
964 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
968 Listing breakpoints and watchpoints, at different points in the program
969 execution. Note that once the watchpoint goes out of scope, it is
975 ^done,wpt=@{number="2",exp="C"@}
978 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
979 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
980 addr="0x00010734",func="callee4",
981 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
982 bkpt=@{number="2",type="watchpoint",disp="keep",
983 enabled="y",addr="",what="C",times="0"@}@}
987 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
988 value=@{old="-276895068",new="3"@},
989 frame=@{func="callee4",args=[],
990 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
993 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
994 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
995 addr="0x00010734",func="callee4",
996 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
997 bkpt=@{number="2",type="watchpoint",disp="keep",
998 enabled="y",addr="",what="C",times="-5"@}@}
1002 ^done,reason="watchpoint-scope",wpnum="2",
1003 frame=@{func="callee3",args=[@{name="strarg",
1004 value="0x11940 \"A string argument.\""@}],
1005 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1008 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
1009 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
1010 addr="0x00010734",func="callee4",
1011 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}@}
1015 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1016 @node GDB/MI Data Manipulation
1017 @section @sc{gdb/mi} Data Manipulation
1019 @cindex data manipulation, in @sc{gdb/mi}
1020 @cindex @sc{gdb/mi}, data manipulation
1021 This section describes the @sc{gdb/mi} commands that manipulate data:
1022 examine memory and registers, evaluate expressions, etc.
1024 @c REMOVED FROM THE INTERFACE.
1025 @c @subheading -data-assign
1026 @c Change the value of a program variable. Plenty of side effects.
1027 @c @subsubheading GDB command
1029 @c @subsubheading Example
1032 @subheading The @code{-data-disassemble} Command
1033 @findex -data-disassemble
1035 @subsubheading Synopsis
1039 [ -s @var{start-addr} -e @var{end-addr} ]
1040 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
1048 @item @var{start-addr}
1049 is the beginning address (or @code{$pc})
1050 @item @var{end-addr}
1052 @item @var{filename}
1053 is the name of the file to disassemble
1055 is the line number to disassemble around
1057 is the the number of disassembly lines to be produced. If it is -1,
1058 the whole function will be disassembled, in case no @var{end-addr} is
1059 specified. If @var{end-addr} is specified as a non-zero value, and
1060 @var{lines} is lower than the number of disassembly lines between
1061 @var{start-addr} and @var{end-addr}, only @var{lines} lines are
1062 displayed; if @var{lines} is higher than the number of lines between
1063 @var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
1066 is either 0 (meaning only disassembly) or 1 (meaning mixed source and
1070 @subsubheading Result
1072 The output for each instruction is composed of four fields:
1081 Note that whatever included in the instruction field, is not manipulated
1082 directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format.
1084 @subsubheading @value{GDBN} Command
1086 There's no direct mapping from this command to the CLI.
1088 @subsubheading Example
1090 Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
1094 -data-disassemble -s $pc -e "$pc + 20" -- 0
1097 @{address="0x000107c0",func-name="main",offset="4",
1098 inst="mov 2, %o0"@},
1099 @{address="0x000107c4",func-name="main",offset="8",
1100 inst="sethi %hi(0x11800), %o2"@},
1101 @{address="0x000107c8",func-name="main",offset="12",
1102 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
1103 @{address="0x000107cc",func-name="main",offset="16",
1104 inst="sethi %hi(0x11800), %o2"@},
1105 @{address="0x000107d0",func-name="main",offset="20",
1106 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}]
1110 Disassemble the whole @code{main} function. Line 32 is part of
1114 -data-disassemble -f basics.c -l 32 -- 0
1116 @{address="0x000107bc",func-name="main",offset="0",
1117 inst="save %sp, -112, %sp"@},
1118 @{address="0x000107c0",func-name="main",offset="4",
1119 inst="mov 2, %o0"@},
1120 @{address="0x000107c4",func-name="main",offset="8",
1121 inst="sethi %hi(0x11800), %o2"@},
1123 @{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
1124 @{address="0x00010820",func-name="main",offset="100",inst="restore "@}]
1128 Disassemble 3 instructions from the start of @code{main}:
1132 -data-disassemble -f basics.c -l 32 -n 3 -- 0
1134 @{address="0x000107bc",func-name="main",offset="0",
1135 inst="save %sp, -112, %sp"@},
1136 @{address="0x000107c0",func-name="main",offset="4",
1137 inst="mov 2, %o0"@},
1138 @{address="0x000107c4",func-name="main",offset="8",
1139 inst="sethi %hi(0x11800), %o2"@}]
1143 Disassemble 3 instructions from the start of @code{main} in mixed mode:
1147 -data-disassemble -f basics.c -l 32 -n 3 -- 1
1149 src_and_asm_line=@{line="31",
1150 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1151 testsuite/gdb.mi/basics.c",line_asm_insn=[
1152 @{address="0x000107bc",func-name="main",offset="0",
1153 inst="save %sp, -112, %sp"@}]@},
1154 src_and_asm_line=@{line="32",
1155 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1156 testsuite/gdb.mi/basics.c",line_asm_insn=[
1157 @{address="0x000107c0",func-name="main",offset="4",
1158 inst="mov 2, %o0"@},
1159 @{address="0x000107c4",func-name="main",offset="8",
1160 inst="sethi %hi(0x11800), %o2"@}]@}]
1165 @subheading The @code{-data-evaluate-expression} Command
1166 @findex -data-evaluate-expression
1168 @subsubheading Synopsis
1171 -data-evaluate-expression @var{expr}
1174 Evaluate @var{expr} as an expression. The expression could contain an
1175 inferior function call. The function call will execute synchronously.
1176 If the expression contains spaces, it must be enclosed in double quotes.
1178 @subsubheading @value{GDBN} Command
1180 The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
1181 @samp{call}. In @code{gdbtk} only, there's a corresponding
1182 @samp{gdb_eval} command.
1184 @subsubheading Example
1186 In the following example, the numbers that precede the commands are the
1187 @dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
1188 Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
1192 211-data-evaluate-expression A
1195 311-data-evaluate-expression &A
1196 311^done,value="0xefffeb7c"
1198 411-data-evaluate-expression A+3
1201 511-data-evaluate-expression "A + 3"
1207 @subheading The @code{-data-list-changed-registers} Command
1208 @findex -data-list-changed-registers
1210 @subsubheading Synopsis
1213 -data-list-changed-registers
1216 Display a list of the registers that have changed.
1218 @subsubheading @value{GDBN} Command
1220 @value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
1221 has the corresponding command @samp{gdb_changed_register_list}.
1223 @subsubheading Example
1233 *stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
1234 args=[],file="try.c",line="5"@}
1236 -data-list-changed-registers
1237 ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
1238 "10","11","13","14","15","16","17","18","19","20","21","22","23",
1239 "24","25","26","27","28","30","31","64","65","66","67","69"]
1244 @subheading The @code{-data-list-register-names} Command
1245 @findex -data-list-register-names
1247 @subsubheading Synopsis
1250 -data-list-register-names [ ( @var{regno} )+ ]
1253 Show a list of register names for the current target. If no arguments
1254 are given, it shows a list of the names of all the registers. If
1255 integer numbers are given as arguments, it will print a list of the
1256 names of the registers corresponding to the arguments. To ensure
1257 consistency between a register name and its number, the output list may
1258 include empty register names.
1260 @subsubheading @value{GDBN} Command
1262 @value{GDBN} does not have a command which corresponds to
1263 @samp{-data-list-register-names}. In @code{gdbtk} there is a
1264 corresponding command @samp{gdb_regnames}.
1266 @subsubheading Example
1268 For the PPC MBX board:
1271 -data-list-register-names
1272 ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
1273 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
1274 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
1275 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
1276 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
1277 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
1278 "", "pc","ps","cr","lr","ctr","xer"]
1280 -data-list-register-names 1 2 3
1281 ^done,register-names=["r1","r2","r3"]
1285 @subheading The @code{-data-list-register-values} Command
1286 @findex -data-list-register-values
1288 @subsubheading Synopsis
1291 -data-list-register-values @var{fmt} [ ( @var{regno} )*]
1294 Display the registers' contents. @var{fmt} is the format according to
1295 which the registers' contents are to be returned, followed by an optional
1296 list of numbers specifying the registers to display. A missing list of
1297 numbers indicates that the contents of all the registers must be returned.
1299 Allowed formats for @var{fmt} are:
1316 @subsubheading @value{GDBN} Command
1318 The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
1319 all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
1321 @subsubheading Example
1323 For a PPC MBX board (note: line breaks are for readability only, they
1324 don't appear in the actual output):
1328 -data-list-register-values r 64 65
1329 ^done,register-values=[@{number="64",value="0xfe00a300"@},
1330 @{number="65",value="0x00029002"@}]
1332 -data-list-register-values x
1333 ^done,register-values=[@{number="0",value="0xfe0043c8"@},
1334 @{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
1335 @{number="3",value="0x0"@},@{number="4",value="0xa"@},
1336 @{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
1337 @{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
1338 @{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
1339 @{number="11",value="0x1"@},@{number="12",value="0x0"@},
1340 @{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
1341 @{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
1342 @{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
1343 @{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
1344 @{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
1345 @{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
1346 @{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
1347 @{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
1348 @{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
1349 @{number="31",value="0x0"@},@{number="32",value="0x0"@},
1350 @{number="33",value="0x0"@},@{number="34",value="0x0"@},
1351 @{number="35",value="0x0"@},@{number="36",value="0x0"@},
1352 @{number="37",value="0x0"@},@{number="38",value="0x0"@},
1353 @{number="39",value="0x0"@},@{number="40",value="0x0"@},
1354 @{number="41",value="0x0"@},@{number="42",value="0x0"@},
1355 @{number="43",value="0x0"@},@{number="44",value="0x0"@},
1356 @{number="45",value="0x0"@},@{number="46",value="0x0"@},
1357 @{number="47",value="0x0"@},@{number="48",value="0x0"@},
1358 @{number="49",value="0x0"@},@{number="50",value="0x0"@},
1359 @{number="51",value="0x0"@},@{number="52",value="0x0"@},
1360 @{number="53",value="0x0"@},@{number="54",value="0x0"@},
1361 @{number="55",value="0x0"@},@{number="56",value="0x0"@},
1362 @{number="57",value="0x0"@},@{number="58",value="0x0"@},
1363 @{number="59",value="0x0"@},@{number="60",value="0x0"@},
1364 @{number="61",value="0x0"@},@{number="62",value="0x0"@},
1365 @{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
1366 @{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
1367 @{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
1368 @{number="69",value="0x20002b03"@}]
1373 @subheading The @code{-data-read-memory} Command
1374 @findex -data-read-memory
1376 @subsubheading Synopsis
1379 -data-read-memory [ -o @var{byte-offset} ]
1380 @var{address} @var{word-format} @var{word-size}
1381 @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
1389 An expression specifying the address of the first memory word to be
1390 read. Complex expressions containing embedded white space should be
1391 quoted using the C convention.
1393 @item @var{word-format}
1394 The format to be used to print the memory words. The notation is the
1395 same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
1398 @item @var{word-size}
1399 The size of each memory word in bytes.
1402 The number of rows in the output table.
1405 The number of columns in the output table.
1408 If present, indicates that each row should include an @sc{ascii} dump. The
1409 value of @var{aschar} is used as a padding character when a byte is not a
1410 member of the printable @sc{ascii} character set (printable @sc{ascii}
1411 characters are those whose code is between 32 and 126, inclusively).
1413 @item @var{byte-offset}
1414 An offset to add to the @var{address} before fetching memory.
1417 This command displays memory contents as a table of @var{nr-rows} by
1418 @var{nr-cols} words, each word being @var{word-size} bytes. In total,
1419 @code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
1420 (returned as @samp{total-bytes}). Should less then the requested number
1421 of bytes be returned by the target, the missing words are identified
1422 using @samp{N/A}. The number of bytes read from the target is returned
1423 in @samp{nr-bytes} and the starting address used to read memory in
1426 The address of the next/previous row or page is available in
1427 @samp{next-row} and @samp{prev-row}, @samp{next-page} and
1430 @subsubheading @value{GDBN} Command
1432 The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
1433 @samp{gdb_get_mem} memory read command.
1435 @subsubheading Example
1437 Read six bytes of memory starting at @code{bytes+6} but then offset by
1438 @code{-6} bytes. Format as three rows of two columns. One byte per
1439 word. Display each word in hex.
1443 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
1444 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
1445 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
1446 prev-page="0x0000138a",memory=@{
1447 @{addr="0x00001390",data=@{"0x00","0x01"@}@},
1448 @{addr="0x00001392",data=@{"0x02","0x03"@}@},
1449 @{addr="0x00001394",data=@{"0x04","0x05"@}@}@}
1453 Read two bytes of memory starting at address @code{shorts + 64} and
1454 display as a single word formatted in decimal.
1458 5-data-read-memory shorts+64 d 2 1 1
1459 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
1460 next-row="0x00001512",prev-row="0x0000150e",
1461 next-page="0x00001512",prev-page="0x0000150e",memory=@{
1462 @{addr="0x00001510",data=@{"128"@}@}@}
1466 Read thirty two bytes of memory starting at @code{bytes+16} and format
1467 as eight rows of four columns. Include a string encoding with @samp{x}
1468 used as the non-printable character.
1472 4-data-read-memory bytes+16 x 1 8 4 x
1473 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
1474 next-row="0x000013c0",prev-row="0x0000139c",
1475 next-page="0x000013c0",prev-page="0x00001380",memory=@{
1476 @{addr="0x000013a0",data=@{"0x10","0x11","0x12","0x13"@},ascii="xxxx"@},
1477 @{addr="0x000013a4",data=@{"0x14","0x15","0x16","0x17"@},ascii="xxxx"@},
1478 @{addr="0x000013a8",data=@{"0x18","0x19","0x1a","0x1b"@},ascii="xxxx"@},
1479 @{addr="0x000013ac",data=@{"0x1c","0x1d","0x1e","0x1f"@},ascii="xxxx"@},
1480 @{addr="0x000013b0",data=@{"0x20","0x21","0x22","0x23"@},ascii=" !\"#"@},
1481 @{addr="0x000013b4",data=@{"0x24","0x25","0x26","0x27"@},ascii="$%&'"@},
1482 @{addr="0x000013b8",data=@{"0x28","0x29","0x2a","0x2b"@},ascii="()*+"@},
1483 @{addr="0x000013bc",data=@{"0x2c","0x2d","0x2e","0x2f"@},ascii=",-./"@}@}
1487 @subheading The @code{-display-delete} Command
1488 @findex -display-delete
1490 @subsubheading Synopsis
1493 -display-delete @var{number}
1496 Delete the display @var{number}.
1498 @subsubheading @value{GDBN} Command
1500 The corresponding @value{GDBN} command is @samp{delete display}.
1502 @subsubheading Example
1506 @subheading The @code{-display-disable} Command
1507 @findex -display-disable
1509 @subsubheading Synopsis
1512 -display-disable @var{number}
1515 Disable display @var{number}.
1517 @subsubheading @value{GDBN} Command
1519 The corresponding @value{GDBN} command is @samp{disable display}.
1521 @subsubheading Example
1525 @subheading The @code{-display-enable} Command
1526 @findex -display-enable
1528 @subsubheading Synopsis
1531 -display-enable @var{number}
1534 Enable display @var{number}.
1536 @subsubheading @value{GDBN} Command
1538 The corresponding @value{GDBN} command is @samp{enable display}.
1540 @subsubheading Example
1544 @subheading The @code{-display-insert} Command
1545 @findex -display-insert
1547 @subsubheading Synopsis
1550 -display-insert @var{expression}
1553 Display @var{expression} every time the program stops.
1555 @subsubheading @value{GDBN} Command
1557 The corresponding @value{GDBN} command is @samp{display}.
1559 @subsubheading Example
1563 @subheading The @code{-display-list} Command
1564 @findex -display-list
1566 @subsubheading Synopsis
1572 List the displays. Do not show the current values.
1574 @subsubheading @value{GDBN} Command
1576 The corresponding @value{GDBN} command is @samp{info display}.
1578 @subsubheading Example
1582 @subheading The @code{-environment-cd} Command
1583 @findex -environment-cd
1585 @subsubheading Synopsis
1588 -environment-cd @var{pathdir}
1591 Set @value{GDBN}'s working directory.
1593 @subsubheading @value{GDBN} Command
1595 The corresponding @value{GDBN} command is @samp{cd}.
1597 @subsubheading Example
1601 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1607 @subheading The @code{-environment-directory} Command
1608 @findex -environment-directory
1610 @subsubheading Synopsis
1613 -environment-directory @var{pathdir}
1616 Add directory @var{pathdir} to beginning of search path for source files.
1618 @subsubheading @value{GDBN} Command
1620 The corresponding @value{GDBN} command is @samp{dir}.
1622 @subsubheading Example
1626 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1632 @subheading The @code{-environment-path} Command
1633 @findex -environment-path
1635 @subsubheading Synopsis
1638 -environment-path ( @var{pathdir} )+
1641 Add directories @var{pathdir} to beginning of search path for object files.
1643 @subsubheading @value{GDBN} Command
1645 The corresponding @value{GDBN} command is @samp{path}.
1647 @subsubheading Example
1651 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb
1657 @subheading The @code{-environment-pwd} Command
1658 @findex -environment-pwd
1660 @subsubheading Synopsis
1666 Show the current working directory.
1668 @subsubheading @value{GDBN} command
1670 The corresponding @value{GDBN} command is @samp{pwd}.
1672 @subsubheading Example
1677 ~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb.
1682 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1683 @node GDB/MI Program Control
1684 @section @sc{gdb/mi} Program control
1686 @subsubheading Program termination
1688 As a result of execution, the inferior program can run to completion, if
1689 it doesn't encounter any breakpoints. In this case the output will
1690 include an exit code, if the program has exited exceptionally.
1692 @subsubheading Examples
1695 Program exited normally:
1703 *stopped,reason="exited-normally"
1708 Program exited exceptionally:
1716 *stopped,reason="exited",exit-code="01"
1720 Another way the program can terminate is if it receives a signal such as
1721 @code{SIGINT}. In this case, @sc{gdb/mi} displays this:
1725 *stopped,reason="exited-signalled",signal-name="SIGINT",
1726 signal-meaning="Interrupt"
1730 @subheading The @code{-exec-abort} Command
1733 @subsubheading Synopsis
1739 Kill the inferior running program.
1741 @subsubheading @value{GDBN} Command
1743 The corresponding @value{GDBN} command is @samp{kill}.
1745 @subsubheading Example
1749 @subheading The @code{-exec-arguments} Command
1750 @findex -exec-arguments
1752 @subsubheading Synopsis
1755 -exec-arguments @var{args}
1758 Set the inferior program arguments, to be used in the next
1761 @subsubheading @value{GDBN} Command
1763 The corresponding @value{GDBN} command is @samp{set args}.
1765 @subsubheading Example
1768 Don't have one around.
1771 @subheading The @code{-exec-continue} Command
1772 @findex -exec-continue
1774 @subsubheading Synopsis
1780 Asynchronous command. Resumes the execution of the inferior program
1781 until a breakpoint is encountered, or until the inferior exits.
1783 @subsubheading @value{GDBN} Command
1785 The corresponding @value{GDBN} corresponding is @samp{continue}.
1787 @subsubheading Example
1794 *stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
1795 file="hello.c",line="13"@}
1800 @subheading The @code{-exec-finish} Command
1801 @findex -exec-finish
1803 @subsubheading Synopsis
1809 Asynchronous command. Resumes the execution of the inferior program
1810 until the current function is exited. Displays the results returned by
1813 @subsubheading @value{GDBN} Command
1815 The corresponding @value{GDBN} command is @samp{finish}.
1817 @subsubheading Example
1819 Function returning @code{void}.
1826 *stopped,reason="function-finished",frame=@{func="main",args=[],
1827 file="hello.c",line="7"@}
1831 Function returning other than @code{void}. The name of the internal
1832 @value{GDBN} variable storing the result is printed, together with the
1839 *stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
1840 args=[@{name="a",value="1"],@{name="b",value="9"@}@},
1841 file="recursive2.c",line="14"@},
1842 gdb-result-var="$1",return-value="0"
1847 @subheading The @code{-exec-interrupt} Command
1848 @findex -exec-interrupt
1850 @subsubheading Synopsis
1856 Asynchronous command. Interrupts the background execution of the target.
1857 Note how the token associated with the stop message is the one for the
1858 execution command that has been interrupted. The token for the interrupt
1859 itself only appears in the @samp{^done} output. If the user is trying to
1860 interrupt a non-running program, an error message will be printed.
1862 @subsubheading @value{GDBN} Command
1864 The corresponding @value{GDBN} command is @samp{interrupt}.
1866 @subsubheading Example
1877 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
1878 frame=@{addr="0x00010140",func="foo",args=@{@},file="try.c",line="13"@}
1883 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
1888 @subheading The @code{-exec-next} Command
1891 @subsubheading Synopsis
1897 Asynchronous command. Resumes execution of the inferior program, stopping
1898 when the beginning of the next source line is reached.
1900 @subsubheading @value{GDBN} Command
1902 The corresponding @value{GDBN} command is @samp{next}.
1904 @subsubheading Example
1910 *stopped,reason="end-stepping-range",line="8",file="hello.c"
1915 @subheading The @code{-exec-next-instruction} Command
1916 @findex -exec-next-instruction
1918 @subsubheading Synopsis
1921 -exec-next-instruction
1924 Asynchronous command. Executes one machine instruction. If the
1925 instruction is a function call continues until the function returns. If
1926 the program stops at an instruction in the middle of a source line, the
1927 address will be printed as well.
1929 @subsubheading @value{GDBN} Command
1931 The corresponding @value{GDBN} command is @samp{nexti}.
1933 @subsubheading Example
1937 -exec-next-instruction
1941 *stopped,reason="end-stepping-range",
1942 addr="0x000100d4",line="5",file="hello.c"
1947 @subheading The @code{-exec-return} Command
1948 @findex -exec-return
1950 @subsubheading Synopsis
1956 Makes current function return immediately. Doesn't execute the inferior.
1957 Displays the new current frame.
1959 @subsubheading @value{GDBN} Command
1961 The corresponding @value{GDBN} command is @samp{return}.
1963 @subsubheading Example
1967 200-break-insert callee4
1968 200^done,bkpt=@{number="1",addr="0x00010734",
1969 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1974 000*stopped,reason="breakpoint-hit",bkptno="1",
1975 frame=@{func="callee4",args=[],
1976 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1982 111^done,frame=@{level="0 ",func="callee3",
1983 args=[@{name="strarg",
1984 value="0x11940 \"A string argument.\""@}],
1985 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1990 @subheading The @code{-exec-run} Command
1993 @subsubheading Synopsis
1999 Asynchronous command. Starts execution of the inferior from the
2000 beginning. The inferior executes until either a breakpoint is
2001 encountered or the program exits.
2003 @subsubheading @value{GDBN} Command
2005 The corresponding @value{GDBN} command is @samp{run}.
2007 @subsubheading Example
2012 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
2017 *stopped,reason="breakpoint-hit",bkptno="1",
2018 frame=@{func="main",args=[],file="recursive2.c",line="4"@}
2023 @subheading The @code{-exec-show-arguments} Command
2024 @findex -exec-show-arguments
2026 @subsubheading Synopsis
2029 -exec-show-arguments
2032 Print the arguments of the program.
2034 @subsubheading @value{GDBN} Command
2036 The corresponding @value{GDBN} command is @samp{show args}.
2038 @subsubheading Example
2041 @c @subheading -exec-signal
2043 @subheading The @code{-exec-step} Command
2046 @subsubheading Synopsis
2052 Asynchronous command. Resumes execution of the inferior program, stopping
2053 when the beginning of the next source line is reached, if the next
2054 source line is not a function call. If it is, stop at the first
2055 instruction of the called function.
2057 @subsubheading @value{GDBN} Command
2059 The corresponding @value{GDBN} command is @samp{step}.
2061 @subsubheading Example
2063 Stepping into a function:
2069 *stopped,reason="end-stepping-range",
2070 frame=@{func="foo",args=[@{name="a",value="10"@},
2071 @{name="b",value="0"@}],file="recursive2.c",line="11"@}
2081 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
2086 @subheading The @code{-exec-step-instruction} Command
2087 @findex -exec-step-instruction
2089 @subsubheading Synopsis
2092 -exec-step-instruction
2095 Asynchronous command. Resumes the inferior which executes one machine
2096 instruction. The output, once @value{GDBN} has stopped, will vary depending on
2097 whether we have stopped in the middle of a source line or not. In the
2098 former case, the address at which the program stopped will be printed as
2101 @subsubheading @value{GDBN} Command
2103 The corresponding @value{GDBN} command is @samp{stepi}.
2105 @subsubheading Example
2109 -exec-step-instruction
2113 *stopped,reason="end-stepping-range",
2114 frame=@{func="foo",args=[],file="try.c",line="10"@}
2116 -exec-step-instruction
2120 *stopped,reason="end-stepping-range",
2121 frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@}
2126 @subheading The @code{-exec-until} Command
2129 @subsubheading Synopsis
2132 -exec-until [ @var{location} ]
2135 Asynchronous command. Executes the inferior until the @var{location}
2136 specified in the argument is reached. If there is no argument, the inferior
2137 executes until a source line greater than the current one is reached.
2138 The reason for stopping in this case will be @samp{location-reached}.
2140 @subsubheading @value{GDBN} Command
2142 The corresponding @value{GDBN} command is @samp{until}.
2144 @subsubheading Example
2148 -exec-until recursive2.c:6
2152 *stopped,reason="location-reached",frame=@{func="main",args=[],
2153 file="recursive2.c",line="6"@}
2158 @subheading -file-clear
2159 Is this going away????
2163 @subheading The @code{-file-exec-and-symbols} Command
2164 @findex -file-exec-and-symbols
2166 @subsubheading Synopsis
2169 -file-exec-and-symbols @var{file}
2172 Specify the executable file to be debugged. This file is the one from
2173 which the symbol table is also read. If no file is specified, the
2174 command clears the executable and symbol information. If breakpoints
2175 are set when using this command with no arguments, @value{GDBN} will produce
2176 error messages. Otherwise, no output is produced, except a completion
2179 @subsubheading @value{GDBN} Command
2181 The corresponding @value{GDBN} command is @samp{file}.
2183 @subsubheading Example
2187 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2193 @subheading The @code{-file-exec-file} Command
2194 @findex -file-exec-file
2196 @subsubheading Synopsis
2199 -file-exec-file @var{file}
2202 Specify the executable file to be debugged. Unlike
2203 @samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
2204 from this file. If used without argument, @value{GDBN} clears the information
2205 about the executable file. No output is produced, except a completion
2208 @subsubheading @value{GDBN} Command
2210 The corresponding @value{GDBN} command is @samp{exec-file}.
2212 @subsubheading Example
2216 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2222 @subheading The @code{-file-list-exec-sections} Command
2223 @findex -file-list-exec-sections
2225 @subsubheading Synopsis
2228 -file-list-exec-sections
2231 List the sections of the current executable file.
2233 @subsubheading @value{GDBN} Command
2235 The @value{GDBN} command @samp{info file} shows, among the rest, the same
2236 information as this command. @code{gdbtk} has a corresponding command
2237 @samp{gdb_load_info}.
2239 @subsubheading Example
2243 @subheading The @code{-file-list-exec-source-files} Command
2244 @findex -file-list-exec-source-files
2246 @subsubheading Synopsis
2249 -file-list-exec-source-files
2252 List the source files for the current executable.
2254 @subsubheading @value{GDBN} Command
2256 There's no @value{GDBN} command which directly corresponds to this one.
2257 @code{gdbtk} has an analogous command @samp{gdb_listfiles}.
2259 @subsubheading Example
2263 @subheading The @code{-file-list-shared-libraries} Command
2264 @findex -file-list-shared-libraries
2266 @subsubheading Synopsis
2269 -file-list-shared-libraries
2272 List the shared libraries in the program.
2274 @subsubheading @value{GDBN} Command
2276 The corresponding @value{GDBN} command is @samp{info shared}.
2278 @subsubheading Example
2282 @subheading The @code{-file-list-symbol-files} Command
2283 @findex -file-list-symbol-files
2285 @subsubheading Synopsis
2288 -file-list-symbol-files
2293 @subsubheading @value{GDBN} Command
2295 The corresponding @value{GDBN} command is @samp{info file} (part of it).
2297 @subsubheading Example
2301 @subheading The @code{-file-symbol-file} Command
2302 @findex -file-symbol-file
2304 @subsubheading Synopsis
2307 -file-symbol-file @var{file}
2310 Read symbol table info from the specified @var{file} argument. When
2311 used without arguments, clears @value{GDBN}'s symbol table info. No output is
2312 produced, except for a completion notification.
2314 @subsubheading @value{GDBN} Command
2316 The corresponding @value{GDBN} command is @samp{symbol-file}.
2318 @subsubheading Example
2322 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2327 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2328 @node GDB/MI Miscellaneous Commands
2329 @section Miscellaneous @value{GDBN} commands in @sc{gdb/mi}
2331 @c @subheading -gdb-complete
2333 @subheading The @code{-gdb-exit} Command
2336 @subsubheading Synopsis
2342 Exit @value{GDBN} immediately.
2344 @subsubheading @value{GDBN} Command
2346 Approximately corresponds to @samp{quit}.
2348 @subsubheading Example
2355 @subheading The @code{-gdb-set} Command
2358 @subsubheading Synopsis
2364 Set an internal @value{GDBN} variable.
2365 @c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
2367 @subsubheading @value{GDBN} Command
2369 The corresponding @value{GDBN} command is @samp{set}.
2371 @subsubheading Example
2381 @subheading The @code{-gdb-show} Command
2384 @subsubheading Synopsis
2390 Show the current value of a @value{GDBN} variable.
2392 @subsubheading @value{GDBN} command
2394 The corresponding @value{GDBN} command is @samp{show}.
2396 @subsubheading Example
2405 @c @subheading -gdb-source
2408 @subheading The @code{-gdb-version} Command
2409 @findex -gdb-version
2411 @subsubheading Synopsis
2417 Show version information for @value{GDBN}. Used mostly in testing.
2419 @subsubheading @value{GDBN} Command
2421 There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this
2422 information when you start an interactive session.
2424 @subsubheading Example
2426 @c This example modifies the actual output from GDB to avoid overfull
2432 ~Copyright 2000 Free Software Foundation, Inc.
2433 ~GDB is free software, covered by the GNU General Public License, and
2434 ~you are welcome to change it and/or distribute copies of it under
2435 ~ certain conditions.
2436 ~Type "show copying" to see the conditions.
2437 ~There is absolutely no warranty for GDB. Type "show warranty" for
2439 ~This GDB was configured as
2440 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
2446 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2447 @node GDB/MI Kod Commands
2448 @section @sc{gdb/mi} Kod Commands
2450 The Kod commands are not implemented.
2452 @c @subheading -kod-info
2454 @c @subheading -kod-list
2456 @c @subheading -kod-list-object-types
2458 @c @subheading -kod-show
2460 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2461 @node GDB/MI Memory Overlay Commands
2462 @section @sc{gdb/mi} Memory Overlay Commands
2464 The memory overlay commands are not implemented.
2466 @c @subheading -overlay-auto
2468 @c @subheading -overlay-list-mapping-state
2470 @c @subheading -overlay-list-overlays
2472 @c @subheading -overlay-map
2474 @c @subheading -overlay-off
2476 @c @subheading -overlay-on
2478 @c @subheading -overlay-unmap
2480 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2481 @node GDB/MI Signal Handling Commands
2482 @section @sc{gdb/mi} Signal Handling Commands
2484 Signal handling commands are not implemented.
2486 @c @subheading -signal-handle
2488 @c @subheading -signal-list-handle-actions
2490 @c @subheading -signal-list-signal-types
2494 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2495 @node GDB/MI Stack Manipulation
2496 @section Stack manipulation commands in @sc{gdb/mi}
2499 @subheading The @code{-stack-info-frame} Command
2500 @findex -stack-info-frame
2502 @subsubheading Synopsis
2508 Get info on the current frame.
2510 @subsubheading @value{GDBN} Command
2512 The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
2513 (without arguments).
2515 @subsubheading Example
2518 @subheading The @code{-stack-info-depth} Command
2519 @findex -stack-info-depth
2521 @subsubheading Synopsis
2524 -stack-info-depth [ @var{max-depth} ]
2527 Return the depth of the stack. If the integer argument @var{max-depth}
2528 is specified, do not count beyond @var{max-depth} frames.
2530 @subsubheading @value{GDBN} Command
2532 There's no equivalent @value{GDBN} command.
2534 @subsubheading Example
2536 For a stack with frame levels 0 through 11:
2546 -stack-info-depth 12
2549 -stack-info-depth 11
2552 -stack-info-depth 13
2557 @subheading The @code{-stack-list-arguments} Command
2558 @findex -stack-list-arguments
2560 @subsubheading Synopsis
2563 -stack-list-arguments @var{show-values}
2564 [ @var{low-frame} @var{high-frame} ]
2567 Display a list of the arguments for the frames between @var{low-frame}
2568 and @var{high-frame} (inclusive). If @var{low-frame} and
2569 @var{high-frame} are not provided, list the arguments for the whole call
2572 The @var{show-values} argument must have a value of 0 or 1. A value of
2573 0 means that only the names of the arguments are listed, a value of 1
2574 means that both names and values of the arguments are printed.
2576 @subsubheading @value{GDBN} Command
2578 @value{GDBN} does not have an equivalent command. @code{gdbtk} has a
2579 @samp{gdb_get_args} command which partially overlaps with the
2580 functionality of @samp{-stack-list-arguments}.
2582 @subsubheading Example
2589 frame=@{level="0 ",addr="0x00010734",func="callee4",
2590 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
2591 frame=@{level="1 ",addr="0x0001076c",func="callee3",
2592 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
2593 frame=@{level="2 ",addr="0x0001078c",func="callee2",
2594 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
2595 frame=@{level="3 ",addr="0x000107b4",func="callee1",
2596 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
2597 frame=@{level="4 ",addr="0x000107e0",func="main",
2598 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}@}
2600 -stack-list-arguments 0
2603 frame=@{level="0",args=@{@}@},
2604 frame=@{level="1",args=@{name="strarg"@}@},
2605 frame=@{level="2",args=@{name="intarg",name="strarg"@}@},
2606 frame=@{level="3",args=@{name="intarg",name="strarg",name="fltarg"@}@},
2607 frame=@{level="4",args=@{@}@}@}
2609 -stack-list-arguments 1
2612 frame=@{level="0",args=@{@}@},
2614 args=@{@{name="strarg",value="0x11940 \"A string argument.\""@}@}@},
2615 frame=@{level="2",args=@{
2616 @{name="intarg",value="2"@},
2617 @{name="strarg",value="0x11940 \"A string argument.\""@}@}@},
2618 @{frame=@{level="3",args=@{
2619 @{name="intarg",value="2"@},
2620 @{name="strarg",value="0x11940 \"A string argument.\""@},
2621 @{name="fltarg",value="3.5"@}@}@},
2622 frame=@{level="4",args=@{@}@}@}
2624 -stack-list-arguments 0 2 2
2625 ^done,stack-args=@{frame=@{level="2",args=@{name="intarg",name="strarg"@}@}@}
2627 -stack-list-arguments 1 2 2
2628 ^done,stack-args=@{frame=@{level="2",
2629 args=@{@{name="intarg",value="2"@},
2630 @{name="strarg",value="0x11940 \"A string argument.\""@}@}@}@}
2634 @c @subheading -stack-list-exception-handlers
2637 @subheading The @code{-stack-list-frames} Command
2638 @findex -stack-list-frames
2640 @subsubheading Synopsis
2643 -stack-list-frames [ @var{low-frame} @var{high-frame} ]
2646 List the frames currently on the stack. For each frame it displays the
2651 The frame number, 0 being the topmost frame, i.e. the innermost function.
2653 The @code{$pc} value for that frame.
2657 File name of the source file where the function lives.
2659 Line number corresponding to the @code{$pc}.
2662 If invoked without arguments, this command prints a backtrace for the
2663 whole stack. If given two integer arguments, it shows the frames whose
2664 levels are between the two arguments (inclusive). If the two arguments
2665 are equal, it shows the single frame at the corresponding level.
2667 @subsubheading @value{GDBN} Command
2669 The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
2671 @subsubheading Example
2673 Full stack backtrace:
2679 @{frame=@{level="0 ",addr="0x0001076c",func="foo",
2680 file="recursive2.c",line="11"@},
2681 frame=@{level="1 ",addr="0x000107a4",func="foo",
2682 file="recursive2.c",line="14"@},
2683 frame=@{level="2 ",addr="0x000107a4",func="foo",
2684 file="recursive2.c",line="14"@},
2685 frame=@{level="3 ",addr="0x000107a4",func="foo",
2686 file="recursive2.c",line="14"@},
2687 frame=@{level="4 ",addr="0x000107a4",func="foo",
2688 file="recursive2.c",line="14"@},
2689 frame=@{level="5 ",addr="0x000107a4",func="foo",
2690 file="recursive2.c",line="14"@},
2691 frame=@{level="6 ",addr="0x000107a4",func="foo",
2692 file="recursive2.c",line="14"@},
2693 frame=@{level="7 ",addr="0x000107a4",func="foo",
2694 file="recursive2.c",line="14"@},
2695 frame=@{level="8 ",addr="0x000107a4",func="foo",
2696 file="recursive2.c",line="14"@},
2697 frame=@{level="9 ",addr="0x000107a4",func="foo",
2698 file="recursive2.c",line="14"@},
2699 frame=@{level="10",addr="0x000107a4",func="foo",
2700 file="recursive2.c",line="14"@},
2701 frame=@{level="11",addr="0x00010738",func="main",
2702 file="recursive2.c",line="4"@}@}
2706 Show frames between @var{low_frame} and @var{high_frame}:
2710 -stack-list-frames 3 5
2712 @{frame=@{level="3 ",addr="0x000107a4",func="foo",
2713 file="recursive2.c",line="14"@},
2714 frame=@{level="4 ",addr="0x000107a4",func="foo",
2715 file="recursive2.c",line="14"@},
2716 frame=@{level="5 ",addr="0x000107a4",func="foo",
2717 file="recursive2.c",line="14"@}@}
2721 Show a single frame:
2725 -stack-list-frames 3 3
2727 @{frame=@{level="3 ",addr="0x000107a4",func="foo",
2728 file="recursive2.c",line="14"@}@}
2733 @subheading The @code{-stack-list-locals} Command
2734 @findex -stack-list-locals
2736 @subsubheading Synopsis
2739 -stack-list-locals @var{print-values}
2742 Display the local variable names for the current frame. With an
2743 argument of 0 prints only the names of the variables, with argument of 1
2744 prints also their values.
2746 @subsubheading @value{GDBN} Command
2748 @samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
2750 @subsubheading Example
2754 -stack-list-locals 0
2755 ^done,locals=@{name="A",name="B",name="C"@}
2757 -stack-list-locals 1
2758 ^done,locals=@{@{name="A",value="1"@},@{name="B",value="2"@},
2759 @{name="C",value="3"@}@}
2764 @subheading The @code{-stack-select-frame} Command
2765 @findex -stack-select-frame
2767 @subsubheading Synopsis
2770 -stack-select-frame @var{framenum}
2773 Change the current frame. Select a different frame @var{framenum} on
2776 @subsubheading @value{GDBN} Command
2778 The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
2779 @samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
2781 @subsubheading Example
2785 -stack-select-frame 2
2790 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2791 @node GDB/MI Symbol Query
2792 @section @sc{gdb/mi} Symbol Query Commands
2795 @subheading The @code{-symbol-info-address} Command
2796 @findex -symbol-info-address
2798 @subsubheading Synopsis
2801 -symbol-info-address @var{symbol}
2804 Describe where @var{symbol} is stored.
2806 @subsubheading @value{GDBN} Command
2808 The corresponding @value{GDBN} command is @samp{info address}.
2810 @subsubheading Example
2814 @subheading The @code{-symbol-info-file} Command
2815 @findex -symbol-info-file
2817 @subsubheading Synopsis
2823 Show the file for the symbol.
2825 @subsubheading @value{GDBN} Command
2827 There's no equivalent @value{GDBN} command. @code{gdbtk} has
2828 @samp{gdb_find_file}.
2830 @subsubheading Example
2834 @subheading The @code{-symbol-info-function} Command
2835 @findex -symbol-info-function
2837 @subsubheading Synopsis
2840 -symbol-info-function
2843 Show which function the symbol lives in.
2845 @subsubheading @value{GDBN} Command
2847 @samp{gdb_get_function} in @code{gdbtk}.
2849 @subsubheading Example
2853 @subheading The @code{-symbol-info-line} Command
2854 @findex -symbol-info-line
2856 @subsubheading Synopsis
2862 Show the core addresses of the code for a source line.
2864 @subsubheading @value{GDBN} Command
2866 The corresponding @value{GDBN} comamnd is @samp{info line}.
2867 @code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
2869 @subsubheading Example
2873 @subheading The @code{-symbol-info-symbol} Command
2874 @findex -symbol-info-symbol
2876 @subsubheading Synopsis
2879 -symbol-info-symbol @var{addr}
2882 Describe what symbol is at location @var{addr}.
2884 @subsubheading @value{GDBN} Command
2886 The corresponding @value{GDBN} command is @samp{info symbol}.
2888 @subsubheading Example
2892 @subheading The @code{-symbol-list-functions} Command
2893 @findex -symbol-list-functions
2895 @subsubheading Synopsis
2898 -symbol-list-functions
2901 List the functions in the executable.
2903 @subsubheading @value{GDBN} Command
2905 @samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
2906 @samp{gdb_search} in @code{gdbtk}.
2908 @subsubheading Example
2912 @subheading The @code{-symbol-list-types} Command
2913 @findex -symbol-list-types
2915 @subsubheading Synopsis
2921 List all the type names.
2923 @subsubheading @value{GDBN} Command
2925 The corresponding commands are @samp{info types} in @value{GDBN},
2926 @samp{gdb_search} in @code{gdbtk}.
2928 @subsubheading Example
2932 @subheading The @code{-symbol-list-variables} Command
2933 @findex -symbol-list-variables
2935 @subsubheading Synopsis
2938 -symbol-list-variables
2941 List all the global and static variable names.
2943 @subsubheading @value{GDBN} Command
2945 @samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
2947 @subsubheading Example
2951 @subheading The @code{-symbol-locate} Command
2952 @findex -symbol-locate
2954 @subsubheading Synopsis
2960 @subsubheading @value{GDBN} Command
2962 @samp{gdb_loc} in @code{gdbtk}.
2964 @subsubheading Example
2968 @subheading The @code{-symbol-type} Command
2969 @findex -symbol-type
2971 @subsubheading Synopsis
2974 -symbol-type @var{variable}
2977 Show type of @var{variable}.
2979 @subsubheading @value{GDBN} Command
2981 The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
2982 @samp{gdb_obj_variable}.
2984 @subsubheading Example
2988 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2989 @node GDB/MI Target Manipulation
2990 @section @sc{gdb/mi} Target Manipulation Commands
2993 @subheading The @code{-target-attach} Command
2994 @findex -target-attach
2996 @subsubheading Synopsis
2999 -target-attach @var{pid} | @var{file}
3002 Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
3004 @subsubheading @value{GDBN} command
3006 The corresponding @value{GDBN} command is @samp{attach}.
3008 @subsubheading Example
3012 @subheading The @code{-target-compare-sections} Command
3013 @findex -target-compare-sections
3015 @subsubheading Synopsis
3018 -target-compare-sections [ @var{section} ]
3021 Compare data of section @var{section} on target to the exec file.
3022 Without the argument, all sections are compared.
3024 @subsubheading @value{GDBN} Command
3026 The @value{GDBN} equivalent is @samp{compare-sections}.
3028 @subsubheading Example
3032 @subheading The @code{-target-detach} Command
3033 @findex -target-detach
3035 @subsubheading Synopsis
3041 Disconnect from the remote target. There's no output.
3043 @subsubheading @value{GDBN} command
3045 The corresponding @value{GDBN} command is @samp{detach}.
3047 @subsubheading Example
3057 @subheading The @code{-target-download} Command
3058 @findex -target-download
3060 @subsubheading Synopsis
3066 Loads the executable onto the remote target.
3067 It prints out an update message every half second, which includes the fields:
3071 The name of the section.
3073 The size of what has been sent so far for that section.
3075 The size of the section.
3077 The total size of what was sent so far (the current and the previous sections).
3079 The size of the overall executable to download.
3083 Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
3084 @sc{gdb/mi} Output Syntax}).
3086 In addition, it prints the name and size of the sections, as they are
3087 downloaded. These messages include the following fields:
3091 The name of the section.
3093 The size of the section.
3095 The size of the overall executable to download.
3099 At the end, a summary is printed.
3101 @subsubheading @value{GDBN} Command
3103 The corresponding @value{GDBN} command is @samp{load}.
3105 @subsubheading Example
3107 Note: each status message appears on a single line. Here the messages
3108 have been broken down so that they can fit onto a page.
3113 +download,@{section=".text",section-size="6668",total-size="9880"@}
3114 +download,@{section=".text",section-sent="512",section-size="6668",
3115 total-sent="512",total-size="9880"@}
3116 +download,@{section=".text",section-sent="1024",section-size="6668",
3117 total-sent="1024",total-size="9880"@}
3118 +download,@{section=".text",section-sent="1536",section-size="6668",
3119 total-sent="1536",total-size="9880"@}
3120 +download,@{section=".text",section-sent="2048",section-size="6668",
3121 total-sent="2048",total-size="9880"@}
3122 +download,@{section=".text",section-sent="2560",section-size="6668",
3123 total-sent="2560",total-size="9880"@}
3124 +download,@{section=".text",section-sent="3072",section-size="6668",
3125 total-sent="3072",total-size="9880"@}
3126 +download,@{section=".text",section-sent="3584",section-size="6668",
3127 total-sent="3584",total-size="9880"@}
3128 +download,@{section=".text",section-sent="4096",section-size="6668",
3129 total-sent="4096",total-size="9880"@}
3130 +download,@{section=".text",section-sent="4608",section-size="6668",
3131 total-sent="4608",total-size="9880"@}
3132 +download,@{section=".text",section-sent="5120",section-size="6668",
3133 total-sent="5120",total-size="9880"@}
3134 +download,@{section=".text",section-sent="5632",section-size="6668",
3135 total-sent="5632",total-size="9880"@}
3136 +download,@{section=".text",section-sent="6144",section-size="6668",
3137 total-sent="6144",total-size="9880"@}
3138 +download,@{section=".text",section-sent="6656",section-size="6668",
3139 total-sent="6656",total-size="9880"@}
3140 +download,@{section=".init",section-size="28",total-size="9880"@}
3141 +download,@{section=".fini",section-size="28",total-size="9880"@}
3142 +download,@{section=".data",section-size="3156",total-size="9880"@}
3143 +download,@{section=".data",section-sent="512",section-size="3156",
3144 total-sent="7236",total-size="9880"@}
3145 +download,@{section=".data",section-sent="1024",section-size="3156",
3146 total-sent="7748",total-size="9880"@}
3147 +download,@{section=".data",section-sent="1536",section-size="3156",
3148 total-sent="8260",total-size="9880"@}
3149 +download,@{section=".data",section-sent="2048",section-size="3156",
3150 total-sent="8772",total-size="9880"@}
3151 +download,@{section=".data",section-sent="2560",section-size="3156",
3152 total-sent="9284",total-size="9880"@}
3153 +download,@{section=".data",section-sent="3072",section-size="3156",
3154 total-sent="9796",total-size="9880"@}
3155 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
3161 @subheading The @code{-target-exec-status} Command
3162 @findex -target-exec-status
3164 @subsubheading Synopsis
3170 Provide information on the state of the target (whether it is running or
3173 @subsubheading @value{GDBN} Command
3175 There's no equivalent @value{GDBN} command.
3177 @subsubheading Example
3181 @subheading The @code{-target-list-available-targets} Command
3182 @findex -target-list-available-targets
3184 @subsubheading Synopsis
3187 -target-list-available-targets
3190 List the possible targets to connect to.
3192 @subsubheading @value{GDBN} Command
3194 The corresponding @value{GDBN} command is @samp{help target}.
3196 @subsubheading Example
3200 @subheading The @code{-target-list-current-targets} Command
3201 @findex -target-list-current-targets
3203 @subsubheading Synopsis
3206 -target-list-current-targets
3209 Describe the current target.
3211 @subsubheading @value{GDBN} Command
3213 The corresponding information is printed by @samp{info file} (among
3216 @subsubheading Example
3220 @subheading The @code{-target-list-parameters} Command
3221 @findex -target-list-parameters
3223 @subsubheading Synopsis
3226 -target-list-parameters
3231 @subsubheading @value{GDBN} Command
3235 @subsubheading Example
3239 @subheading The @code{-target-select} Command
3240 @findex -target-select
3242 @subsubheading Synopsis
3245 -target-select @var{type} @var{parameters @dots{}}
3248 Connect @value{GDBN} to the remote target. This command takes two args:
3252 The type of target, for instance @samp{async}, @samp{remote}, etc.
3253 @item @var{parameters}
3254 Device names, host names and the like. @xref{Target Commands, ,
3255 Commands for managing targets}, for more details.
3258 The output is a connection notification, followed by the address at
3259 which the target program is, in the following form:
3262 ^connected,addr="@var{address}",func="@var{function name}",
3263 args=@{@var{arg list}@}
3266 @subsubheading @value{GDBN} Command
3268 The corresponding @value{GDBN} command is @samp{target}.
3270 @subsubheading Example
3274 -target-select async /dev/ttya
3275 ^connected,addr="0xfe00a300",func="??",args=@{@}
3279 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3280 @node GDB/MI Thread Commands
3281 @section @sc{gdb/mi} Thread Commands
3284 @subheading The @code{-thread-info} Command
3285 @findex -thread-info
3287 @subsubheading Synopsis
3293 @subsubheading @value{GDBN} command
3297 @subsubheading Example
3301 @subheading The @code{-thread-list-all-threads} Command
3302 @findex -thread-list-all-threads
3304 @subsubheading Synopsis
3307 -thread-list-all-threads
3310 @subsubheading @value{GDBN} Command
3312 The equivalent @value{GDBN} command is @samp{info threads}.
3314 @subsubheading Example
3318 @subheading The @code{-thread-list-ids} Command
3319 @findex -thread-list-ids
3321 @subsubheading Synopsis
3327 Produces a list of the currently known @value{GDBN} thread ids. At the
3328 end of the list it also prints the total number of such threads.
3330 @subsubheading @value{GDBN} Command
3332 Part of @samp{info threads} supplies the same information.
3334 @subsubheading Example
3336 No threads present, besides the main process:
3341 ^done,thread-ids=@{@},number-of-threads="0"
3351 ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3352 number-of-threads="3"
3357 @subheading The @code{-thread-select} Command
3358 @findex -thread-select
3360 @subsubheading Synopsis
3363 -thread-select @var{threadnum}
3366 Make @var{threadnum} the current thread. It prints the number of the new
3367 current thread, and the topmost frame for that thread.
3369 @subsubheading @value{GDBN} Command
3371 The corresponding @value{GDBN} command is @samp{thread}.
3373 @subsubheading Example
3380 *stopped,reason="end-stepping-range",thread-id="2",line="187",
3381 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
3385 thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3386 number-of-threads="3"
3389 ^done,new-thread-id="3",
3390 frame=@{level="0 ",func="vprintf",
3391 args=@{@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
3392 @{name="arg",value="0x2"@}@},file="vprintf.c",line="31"@}
3396 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3397 @node GDB/MI Tracepoint Commands
3398 @section @sc{gdb/mi} Tracepoint Commands
3400 The tracepoint commands are not yet implemented.
3402 @c @subheading -trace-actions
3404 @c @subheading -trace-delete
3406 @c @subheading -trace-disable
3408 @c @subheading -trace-dump
3410 @c @subheading -trace-enable
3412 @c @subheading -trace-exists
3414 @c @subheading -trace-find
3416 @c @subheading -trace-frame-number
3418 @c @subheading -trace-info
3420 @c @subheading -trace-insert
3422 @c @subheading -trace-list
3424 @c @subheading -trace-pass-count
3426 @c @subheading -trace-save
3428 @c @subheading -trace-start
3430 @c @subheading -trace-stop
3433 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3434 @node GDB/MI Variable Objects
3435 @section @sc{gdb/mi} Variable Objects
3438 @subheading Motivation for Variable Objects in @sc{gdb/mi}
3440 For the implementation of a variable debugger window (locals, watched
3441 expressions, etc.), we are proposing the adaptation of the existing code
3442 used by @code{Insight}.
3444 The two main reasons for that are:
3448 It has been proven in practice (it is already on its second generation).
3451 It will shorten development time (needless to say how important it is
3455 The original interface was designed to be used by Tcl code, so it was
3456 slightly changed so it could be used through @sc{gdb/mi}. This section
3457 describes the @sc{gdb/mi} operations that will be available and gives some
3458 hints about their use.
3460 @emph{Note}: In addition to the set of operations described here, we
3461 expect the @sc{gui} implementation of a variable window to require, at
3462 least, the following operations:
3465 @item @code{-gdb-show} @code{output-radix}
3466 @item @code{-stack-list-arguments}
3467 @item @code{-stack-list-locals}
3468 @item @code{-stack-select-frame}
3471 @subheading Introduction to Variable Objects in @sc{gdb/mi}
3473 @cindex variable objects in @sc{gdb/mi}
3474 The basic idea behind variable objects is the creation of a named object
3475 to represent a variable, an expression, a memory location or even a CPU
3476 register. For each object created, a set of operations is available for
3477 examining or changing its properties.
3479 Furthermore, complex data types, such as C structures, are represented
3480 in a tree format. For instance, the @code{struct} type variable is the
3481 root and the children will represent the struct members. If a child
3482 is itself of a complex type, it will also have children of its own.
3483 Appropriate language differences are handled for C, C@t{++} and Java.
3485 When returning the actual values of the objects, this facility allows
3486 for the individual selection of the display format used in the result
3487 creation. It can be chosen among: binary, decimal, hexadecimal, octal
3488 and natural. Natural refers to a default format automatically
3489 chosen based on the variable type (like decimal for an @code{int}, hex
3490 for pointers, etc.).
3492 The following is the complete set of @sc{gdb/mi} operations defined to
3493 access this functionality:
3495 @multitable @columnfractions .4 .6
3496 @item @strong{Operation}
3497 @tab @strong{Description}
3499 @item @code{-var-create}
3500 @tab create a variable object
3501 @item @code{-var-delete}
3502 @tab delete the variable object and its children
3503 @item @code{-var-set-format}
3504 @tab set the display format of this variable
3505 @item @code{-var-show-format}
3506 @tab show the display format of this variable
3507 @item @code{-var-info-num-children}
3508 @tab tells how many children this object has
3509 @item @code{-var-list-children}
3510 @tab return a list of the object's children
3511 @item @code{-var-info-type}
3512 @tab show the type of this variable object
3513 @item @code{-var-info-expression}
3514 @tab print what this variable object represents
3515 @item @code{-var-show-attributes}
3516 @tab is this variable editable? does it exist here?
3517 @item @code{-var-evaluate-expression}
3518 @tab get the value of this variable
3519 @item @code{-var-assign}
3520 @tab set the value of this variable
3521 @item @code{-var-update}
3522 @tab update the variable and its children
3525 In the next subsection we describe each operation in detail and suggest
3528 @subheading Description And Use of Operations on Variable Objects
3530 @subheading The @code{-var-create} Command
3533 @subsubheading Synopsis
3536 -var-create @{@var{name} | "-"@}
3537 @{@var{frame-addr} | "*"@} @var{expression}
3540 This operation creates a variable object, which allows the monitoring of
3541 a variable, the result of an expression, a memory cell or a CPU
3544 The @var{name} parameter is the string by which the object can be
3545 referenced. It must be unique. If @samp{-} is specified, the varobj
3546 system will generate a string ``varNNNNNN'' automatically. It will be
3547 unique provided that one does not specify @var{name} on that format.
3548 The command fails if a duplicate name is found.
3550 The frame under which the expression should be evaluated can be
3551 specified by @var{frame-addr}. A @samp{*} indicates that the current
3552 frame should be used.
3554 @var{expression} is any expression valid on the current language set (must not
3555 begin with a @samp{*}), or one of the following:
3559 @samp{*@var{addr}}, where @var{addr} is the address of a memory cell
3562 @samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
3565 @samp{$@var{regname}} --- a CPU register name
3568 @subsubheading Result
3570 This operation returns the name, number of children and the type of the
3571 object created. Type is returned as a string as the ones generated by
3572 the @value{GDBN} CLI:
3575 name="@var{name}",numchild="N",type="@var{type}"
3579 @subheading The @code{-var-delete} Command
3582 @subsubheading Synopsis
3585 -var-delete @var{name}
3588 Deletes a previously created variable object and all of its children.
3590 Returns an error if the object @var{name} is not found.
3593 @subheading The @code{-var-set-format} Command
3594 @findex -var-set-format
3596 @subsubheading Synopsis
3599 -var-set-format @var{name} @var{format-spec}
3602 Sets the output format for the value of the object @var{name} to be
3605 The syntax for the @var{format-spec} is as follows:
3608 @var{format-spec} @expansion{}
3609 @{binary | decimal | hexadecimal | octal | natural@}
3613 @subheading The @code{-var-show-format} Command
3614 @findex -var-show-format
3616 @subsubheading Synopsis
3619 -var-show-format @var{name}
3622 Returns the format used to display the value of the object @var{name}.
3625 @var{format} @expansion{}
3630 @subheading The @code{-var-info-num-children} Command
3631 @findex -var-info-num-children
3633 @subsubheading Synopsis
3636 -var-info-num-children @var{name}
3639 Returns the number of children of a variable object @var{name}:
3646 @subheading The @code{-var-list-children} Command
3647 @findex -var-list-children
3649 @subsubheading Synopsis
3652 -var-list-children @var{name}
3655 Returns a list of the children of the specified variable object:
3658 numchild=@var{n},children=@{@{name=@var{name},
3659 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}@}
3663 @subheading The @code{-var-info-type} Command
3664 @findex -var-info-type
3666 @subsubheading Synopsis
3669 -var-info-type @var{name}
3672 Returns the type of the specified variable @var{name}. The type is
3673 returned as a string in the same format as it is output by the
3681 @subheading The @code{-var-info-expression} Command
3682 @findex -var-info-expression
3684 @subsubheading Synopsis
3687 -var-info-expression @var{name}
3690 Returns what is represented by the variable object @var{name}:
3693 lang=@var{lang-spec},exp=@var{expression}
3697 where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
3699 @subheading The @code{-var-show-attributes} Command
3700 @findex -var-show-attributes
3702 @subsubheading Synopsis
3705 -var-show-attributes @var{name}
3708 List attributes of the specified variable object @var{name}:
3711 status=@var{attr} [ ( ,@var{attr} )* ]
3715 where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
3717 @subheading The @code{-var-evaluate-expression} Command
3718 @findex -var-evaluate-expression
3720 @subsubheading Synopsis
3723 -var-evaluate-expression @var{name}
3726 Evaluates the expression that is represented by the specified variable
3727 object and returns its value as a string in the current format specified
3734 @subheading The @code{-var-assign} Command
3737 @subsubheading Synopsis
3740 -var-assign @var{name} @var{expression}
3743 Assigns the value of @var{expression} to the variable object specified
3744 by @var{name}. The object must be @samp{editable}.
3746 @subheading The @code{-var-update} Command
3749 @subsubheading Synopsis
3752 -var-update @{@var{name} | "*"@}
3755 Update the value of the variable object @var{name} by evaluating its
3756 expression after fetching all the new values from memory or registers.
3757 A @samp{*} causes all existing variable objects to be updated.
3760 @c change-log-default-name: "ChangeLog-mi"