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.
1258 @subsubheading @value{GDBN} Command
1260 @value{GDBN} does not have a command which corresponds to
1261 @samp{-data-list-register-names}. In @code{gdbtk} there is a
1262 corresponding command @samp{gdb_regnames}.
1264 @subsubheading Example
1266 For the PPC MBX board:
1269 -data-list-register-names
1270 ^done,register-names=@{"r0","r1","r2","r3","r4","r5","r6","r7",
1271 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
1272 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
1273 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
1274 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
1275 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
1276 "pc","ps","cr","lr","ctr","xer"@}
1278 -data-list-register-names 1 2 3
1279 ^done,register-names=@{"r1","r2","r3"@}
1283 @subheading The @code{-data-list-register-values} Command
1284 @findex -data-list-register-values
1286 @subsubheading Synopsis
1289 -data-list-register-values @var{fmt} [ ( @var{regno} )*]
1292 Display the registers' contents. @var{fmt} is the format according to
1293 which the registers' contents are to be returned, followed by an optional
1294 list of numbers specifying the registers to display. A missing list of
1295 numbers indicates that the contents of all the registers must be returned.
1297 Allowed formats for @var{fmt} are:
1314 @subsubheading @value{GDBN} Command
1316 The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
1317 all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
1319 @subsubheading Example
1321 For a PPC MBX board (note: line breaks are for readability only, they
1322 don't appear in the actual output):
1326 -data-list-register-values r 64 65
1327 ^done,register-values=@{@{number="64",value="0xfe00a300"@},
1328 @{number="65",value="0x00029002"@}@}
1330 -data-list-register-values x
1331 ^done,register-values=@{@{number="0",value="0xfe0043c8"@},
1332 @{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
1333 @{number="3",value="0x0"@},@{number="4",value="0xa"@},
1334 @{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
1335 @{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
1336 @{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
1337 @{number="11",value="0x1"@},@{number="12",value="0x0"@},
1338 @{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
1339 @{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
1340 @{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
1341 @{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
1342 @{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
1343 @{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
1344 @{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
1345 @{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
1346 @{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
1347 @{number="31",value="0x0"@},@{number="32",value="0x0"@},
1348 @{number="33",value="0x0"@},@{number="34",value="0x0"@},
1349 @{number="35",value="0x0"@},@{number="36",value="0x0"@},
1350 @{number="37",value="0x0"@},@{number="38",value="0x0"@},
1351 @{number="39",value="0x0"@},@{number="40",value="0x0"@},
1352 @{number="41",value="0x0"@},@{number="42",value="0x0"@},
1353 @{number="43",value="0x0"@},@{number="44",value="0x0"@},
1354 @{number="45",value="0x0"@},@{number="46",value="0x0"@},
1355 @{number="47",value="0x0"@},@{number="48",value="0x0"@},
1356 @{number="49",value="0x0"@},@{number="50",value="0x0"@},
1357 @{number="51",value="0x0"@},@{number="52",value="0x0"@},
1358 @{number="53",value="0x0"@},@{number="54",value="0x0"@},
1359 @{number="55",value="0x0"@},@{number="56",value="0x0"@},
1360 @{number="57",value="0x0"@},@{number="58",value="0x0"@},
1361 @{number="59",value="0x0"@},@{number="60",value="0x0"@},
1362 @{number="61",value="0x0"@},@{number="62",value="0x0"@},
1363 @{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
1364 @{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
1365 @{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
1366 @{number="69",value="0x20002b03"@}@}
1371 @subheading The @code{-data-read-memory} Command
1372 @findex -data-read-memory
1374 @subsubheading Synopsis
1377 -data-read-memory [ -o @var{byte-offset} ]
1378 @var{address} @var{word-format} @var{word-size}
1379 @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
1387 An expression specifying the address of the first memory word to be
1388 read. Complex expressions containing embedded white space should be
1389 quoted using the C convention.
1391 @item @var{word-format}
1392 The format to be used to print the memory words. The notation is the
1393 same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
1396 @item @var{word-size}
1397 The size of each memory word in bytes.
1400 The number of rows in the output table.
1403 The number of columns in the output table.
1406 If present, indicates that each row should include an @sc{ascii} dump. The
1407 value of @var{aschar} is used as a padding character when a byte is not a
1408 member of the printable @sc{ascii} character set (printable @sc{ascii}
1409 characters are those whose code is between 32 and 126, inclusively).
1411 @item @var{byte-offset}
1412 An offset to add to the @var{address} before fetching memory.
1415 This command displays memory contents as a table of @var{nr-rows} by
1416 @var{nr-cols} words, each word being @var{word-size} bytes. In total,
1417 @code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
1418 (returned as @samp{total-bytes}). Should less then the requested number
1419 of bytes be returned by the target, the missing words are identified
1420 using @samp{N/A}. The number of bytes read from the target is returned
1421 in @samp{nr-bytes} and the starting address used to read memory in
1424 The address of the next/previous row or page is available in
1425 @samp{next-row} and @samp{prev-row}, @samp{next-page} and
1428 @subsubheading @value{GDBN} Command
1430 The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
1431 @samp{gdb_get_mem} memory read command.
1433 @subsubheading Example
1435 Read six bytes of memory starting at @code{bytes+6} but then offset by
1436 @code{-6} bytes. Format as three rows of two columns. One byte per
1437 word. Display each word in hex.
1441 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
1442 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
1443 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
1444 prev-page="0x0000138a",memory=@{
1445 @{addr="0x00001390",data=@{"0x00","0x01"@}@},
1446 @{addr="0x00001392",data=@{"0x02","0x03"@}@},
1447 @{addr="0x00001394",data=@{"0x04","0x05"@}@}@}
1451 Read two bytes of memory starting at address @code{shorts + 64} and
1452 display as a single word formatted in decimal.
1456 5-data-read-memory shorts+64 d 2 1 1
1457 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
1458 next-row="0x00001512",prev-row="0x0000150e",
1459 next-page="0x00001512",prev-page="0x0000150e",memory=@{
1460 @{addr="0x00001510",data=@{"128"@}@}@}
1464 Read thirty two bytes of memory starting at @code{bytes+16} and format
1465 as eight rows of four columns. Include a string encoding with @samp{x}
1466 used as the non-printable character.
1470 4-data-read-memory bytes+16 x 1 8 4 x
1471 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
1472 next-row="0x000013c0",prev-row="0x0000139c",
1473 next-page="0x000013c0",prev-page="0x00001380",memory=@{
1474 @{addr="0x000013a0",data=@{"0x10","0x11","0x12","0x13"@},ascii="xxxx"@},
1475 @{addr="0x000013a4",data=@{"0x14","0x15","0x16","0x17"@},ascii="xxxx"@},
1476 @{addr="0x000013a8",data=@{"0x18","0x19","0x1a","0x1b"@},ascii="xxxx"@},
1477 @{addr="0x000013ac",data=@{"0x1c","0x1d","0x1e","0x1f"@},ascii="xxxx"@},
1478 @{addr="0x000013b0",data=@{"0x20","0x21","0x22","0x23"@},ascii=" !\"#"@},
1479 @{addr="0x000013b4",data=@{"0x24","0x25","0x26","0x27"@},ascii="$%&'"@},
1480 @{addr="0x000013b8",data=@{"0x28","0x29","0x2a","0x2b"@},ascii="()*+"@},
1481 @{addr="0x000013bc",data=@{"0x2c","0x2d","0x2e","0x2f"@},ascii=",-./"@}@}
1485 @subheading The @code{-display-delete} Command
1486 @findex -display-delete
1488 @subsubheading Synopsis
1491 -display-delete @var{number}
1494 Delete the display @var{number}.
1496 @subsubheading @value{GDBN} Command
1498 The corresponding @value{GDBN} command is @samp{delete display}.
1500 @subsubheading Example
1504 @subheading The @code{-display-disable} Command
1505 @findex -display-disable
1507 @subsubheading Synopsis
1510 -display-disable @var{number}
1513 Disable display @var{number}.
1515 @subsubheading @value{GDBN} Command
1517 The corresponding @value{GDBN} command is @samp{disable display}.
1519 @subsubheading Example
1523 @subheading The @code{-display-enable} Command
1524 @findex -display-enable
1526 @subsubheading Synopsis
1529 -display-enable @var{number}
1532 Enable display @var{number}.
1534 @subsubheading @value{GDBN} Command
1536 The corresponding @value{GDBN} command is @samp{enable display}.
1538 @subsubheading Example
1542 @subheading The @code{-display-insert} Command
1543 @findex -display-insert
1545 @subsubheading Synopsis
1548 -display-insert @var{expression}
1551 Display @var{expression} every time the program stops.
1553 @subsubheading @value{GDBN} Command
1555 The corresponding @value{GDBN} command is @samp{display}.
1557 @subsubheading Example
1561 @subheading The @code{-display-list} Command
1562 @findex -display-list
1564 @subsubheading Synopsis
1570 List the displays. Do not show the current values.
1572 @subsubheading @value{GDBN} Command
1574 The corresponding @value{GDBN} command is @samp{info display}.
1576 @subsubheading Example
1580 @subheading The @code{-environment-cd} Command
1581 @findex -environment-cd
1583 @subsubheading Synopsis
1586 -environment-cd @var{pathdir}
1589 Set @value{GDBN}'s working directory.
1591 @subsubheading @value{GDBN} Command
1593 The corresponding @value{GDBN} command is @samp{cd}.
1595 @subsubheading Example
1599 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1605 @subheading The @code{-environment-directory} Command
1606 @findex -environment-directory
1608 @subsubheading Synopsis
1611 -environment-directory @var{pathdir}
1614 Add directory @var{pathdir} to beginning of search path for source files.
1616 @subsubheading @value{GDBN} Command
1618 The corresponding @value{GDBN} command is @samp{dir}.
1620 @subsubheading Example
1624 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1630 @subheading The @code{-environment-path} Command
1631 @findex -environment-path
1633 @subsubheading Synopsis
1636 -environment-path ( @var{pathdir} )+
1639 Add directories @var{pathdir} to beginning of search path for object files.
1641 @subsubheading @value{GDBN} Command
1643 The corresponding @value{GDBN} command is @samp{path}.
1645 @subsubheading Example
1649 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb
1655 @subheading The @code{-environment-pwd} Command
1656 @findex -environment-pwd
1658 @subsubheading Synopsis
1664 Show the current working directory.
1666 @subsubheading @value{GDBN} command
1668 The corresponding @value{GDBN} command is @samp{pwd}.
1670 @subsubheading Example
1675 ~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb.
1680 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1681 @node GDB/MI Program Control
1682 @section @sc{gdb/mi} Program control
1684 @subsubheading Program termination
1686 As a result of execution, the inferior program can run to completion, if
1687 it doesn't encounter any breakpoints. In this case the output will
1688 include an exit code, if the program has exited exceptionally.
1690 @subsubheading Examples
1693 Program exited normally:
1701 *stopped,reason="exited-normally"
1706 Program exited exceptionally:
1714 *stopped,reason="exited",exit-code="01"
1718 Another way the program can terminate is if it receives a signal such as
1719 @code{SIGINT}. In this case, @sc{gdb/mi} displays this:
1723 *stopped,reason="exited-signalled",signal-name="SIGINT",
1724 signal-meaning="Interrupt"
1728 @subheading The @code{-exec-abort} Command
1731 @subsubheading Synopsis
1737 Kill the inferior running program.
1739 @subsubheading @value{GDBN} Command
1741 The corresponding @value{GDBN} command is @samp{kill}.
1743 @subsubheading Example
1747 @subheading The @code{-exec-arguments} Command
1748 @findex -exec-arguments
1750 @subsubheading Synopsis
1753 -exec-arguments @var{args}
1756 Set the inferior program arguments, to be used in the next
1759 @subsubheading @value{GDBN} Command
1761 The corresponding @value{GDBN} command is @samp{set args}.
1763 @subsubheading Example
1766 Don't have one around.
1769 @subheading The @code{-exec-continue} Command
1770 @findex -exec-continue
1772 @subsubheading Synopsis
1778 Asynchronous command. Resumes the execution of the inferior program
1779 until a breakpoint is encountered, or until the inferior exits.
1781 @subsubheading @value{GDBN} Command
1783 The corresponding @value{GDBN} corresponding is @samp{continue}.
1785 @subsubheading Example
1792 *stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=@{@},
1793 file="hello.c",line="13"@}
1798 @subheading The @code{-exec-finish} Command
1799 @findex -exec-finish
1801 @subsubheading Synopsis
1807 Asynchronous command. Resumes the execution of the inferior program
1808 until the current function is exited. Displays the results returned by
1811 @subsubheading @value{GDBN} Command
1813 The corresponding @value{GDBN} command is @samp{finish}.
1815 @subsubheading Example
1817 Function returning @code{void}.
1824 *stopped,reason="function-finished",frame=@{func="main",args=@{@},
1825 file="hello.c",line="7"@}
1829 Function returning other than @code{void}. The name of the internal
1830 @value{GDBN} variable storing the result is printed, together with the
1837 *stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
1838 args=@{@{name="a",value="1"@},@{name="b",value="9"@}@},
1839 file="recursive2.c",line="14"@},
1840 gdb-result-var="$1",return-value="0"
1845 @subheading The @code{-exec-interrupt} Command
1846 @findex -exec-interrupt
1848 @subsubheading Synopsis
1854 Asynchronous command. Interrupts the background execution of the target.
1855 Note how the token associated with the stop message is the one for the
1856 execution command that has been interrupted. The token for the interrupt
1857 itself only appears in the @samp{^done} output. If the user is trying to
1858 interrupt a non-running program, an error message will be printed.
1860 @subsubheading @value{GDBN} Command
1862 The corresponding @value{GDBN} command is @samp{interrupt}.
1864 @subsubheading Example
1875 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
1876 frame=@{addr="0x00010140",func="foo",args=@{@},file="try.c",line="13"@}
1881 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
1886 @subheading The @code{-exec-next} Command
1889 @subsubheading Synopsis
1895 Asynchronous command. Resumes execution of the inferior program, stopping
1896 when the beginning of the next source line is reached.
1898 @subsubheading @value{GDBN} Command
1900 The corresponding @value{GDBN} command is @samp{next}.
1902 @subsubheading Example
1908 *stopped,reason="end-stepping-range",line="8",file="hello.c"
1913 @subheading The @code{-exec-next-instruction} Command
1914 @findex -exec-next-instruction
1916 @subsubheading Synopsis
1919 -exec-next-instruction
1922 Asynchronous command. Executes one machine instruction. If the
1923 instruction is a function call continues until the function returns. If
1924 the program stops at an instruction in the middle of a source line, the
1925 address will be printed as well.
1927 @subsubheading @value{GDBN} Command
1929 The corresponding @value{GDBN} command is @samp{nexti}.
1931 @subsubheading Example
1935 -exec-next-instruction
1939 *stopped,reason="end-stepping-range",
1940 addr="0x000100d4",line="5",file="hello.c"
1945 @subheading The @code{-exec-return} Command
1946 @findex -exec-return
1948 @subsubheading Synopsis
1954 Makes current function return immediately. Doesn't execute the inferior.
1955 Displays the new current frame.
1957 @subsubheading @value{GDBN} Command
1959 The corresponding @value{GDBN} command is @samp{return}.
1961 @subsubheading Example
1965 200-break-insert callee4
1966 200^done,bkpt=@{number="1",addr="0x00010734",
1967 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1972 000*stopped,reason="breakpoint-hit",bkptno="1",
1973 frame=@{func="callee4",args=@{@},
1974 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1980 111^done,frame=@{level="0 ",func="callee3",
1981 args=@{@{name="strarg",
1982 value="0x11940 \"A string argument.\""@}@},
1983 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1988 @subheading The @code{-exec-run} Command
1991 @subsubheading Synopsis
1997 Asynchronous command. Starts execution of the inferior from the
1998 beginning. The inferior executes until either a breakpoint is
1999 encountered or the program exits.
2001 @subsubheading @value{GDBN} Command
2003 The corresponding @value{GDBN} command is @samp{run}.
2005 @subsubheading Example
2010 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
2015 *stopped,reason="breakpoint-hit",bkptno="1",
2016 frame=@{func="main",args=@{@},file="recursive2.c",line="4"@}
2021 @subheading The @code{-exec-show-arguments} Command
2022 @findex -exec-show-arguments
2024 @subsubheading Synopsis
2027 -exec-show-arguments
2030 Print the arguments of the program.
2032 @subsubheading @value{GDBN} Command
2034 The corresponding @value{GDBN} command is @samp{show args}.
2036 @subsubheading Example
2039 @c @subheading -exec-signal
2041 @subheading The @code{-exec-step} Command
2044 @subsubheading Synopsis
2050 Asynchronous command. Resumes execution of the inferior program, stopping
2051 when the beginning of the next source line is reached, if the next
2052 source line is not a function call. If it is, stop at the first
2053 instruction of the called function.
2055 @subsubheading @value{GDBN} Command
2057 The corresponding @value{GDBN} command is @samp{step}.
2059 @subsubheading Example
2061 Stepping into a function:
2067 *stopped,reason="end-stepping-range",
2068 frame=@{func="foo",args=@{@{name="a",value="10"@},
2069 @{name="b",value="0"@}@},file="recursive2.c",line="11"@}
2079 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
2084 @subheading The @code{-exec-step-instruction} Command
2085 @findex -exec-step-instruction
2087 @subsubheading Synopsis
2090 -exec-step-instruction
2093 Asynchronous command. Resumes the inferior which executes one machine
2094 instruction. The output, once @value{GDBN} has stopped, will vary depending on
2095 whether we have stopped in the middle of a source line or not. In the
2096 former case, the address at which the program stopped will be printed as
2099 @subsubheading @value{GDBN} Command
2101 The corresponding @value{GDBN} command is @samp{stepi}.
2103 @subsubheading Example
2107 -exec-step-instruction
2111 *stopped,reason="end-stepping-range",
2112 frame=@{func="foo",args=@{@},file="try.c",line="10"@}
2114 -exec-step-instruction
2118 *stopped,reason="end-stepping-range",
2119 frame=@{addr="0x000100f4",func="foo",args=@{@},file="try.c",line="10"@}
2124 @subheading The @code{-exec-until} Command
2127 @subsubheading Synopsis
2130 -exec-until [ @var{location} ]
2133 Asynchronous command. Executes the inferior until the @var{location}
2134 specified in the argument is reached. If there is no argument, the inferior
2135 executes until a source line greater than the current one is reached.
2136 The reason for stopping in this case will be @samp{location-reached}.
2138 @subsubheading @value{GDBN} Command
2140 The corresponding @value{GDBN} command is @samp{until}.
2142 @subsubheading Example
2146 -exec-until recursive2.c:6
2150 *stopped,reason="location-reached",frame=@{func="main",args=@{@},
2151 file="recursive2.c",line="6"@}
2156 @subheading -file-clear
2157 Is this going away????
2161 @subheading The @code{-file-exec-and-symbols} Command
2162 @findex -file-exec-and-symbols
2164 @subsubheading Synopsis
2167 -file-exec-and-symbols @var{file}
2170 Specify the executable file to be debugged. This file is the one from
2171 which the symbol table is also read. If no file is specified, the
2172 command clears the executable and symbol information. If breakpoints
2173 are set when using this command with no arguments, @value{GDBN} will produce
2174 error messages. Otherwise, no output is produced, except a completion
2177 @subsubheading @value{GDBN} Command
2179 The corresponding @value{GDBN} command is @samp{file}.
2181 @subsubheading Example
2185 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2191 @subheading The @code{-file-exec-file} Command
2192 @findex -file-exec-file
2194 @subsubheading Synopsis
2197 -file-exec-file @var{file}
2200 Specify the executable file to be debugged. Unlike
2201 @samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
2202 from this file. If used without argument, @value{GDBN} clears the information
2203 about the executable file. No output is produced, except a completion
2206 @subsubheading @value{GDBN} Command
2208 The corresponding @value{GDBN} command is @samp{exec-file}.
2210 @subsubheading Example
2214 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2220 @subheading The @code{-file-list-exec-sections} Command
2221 @findex -file-list-exec-sections
2223 @subsubheading Synopsis
2226 -file-list-exec-sections
2229 List the sections of the current executable file.
2231 @subsubheading @value{GDBN} Command
2233 The @value{GDBN} command @samp{info file} shows, among the rest, the same
2234 information as this command. @code{gdbtk} has a corresponding command
2235 @samp{gdb_load_info}.
2237 @subsubheading Example
2241 @subheading The @code{-file-list-exec-source-files} Command
2242 @findex -file-list-exec-source-files
2244 @subsubheading Synopsis
2247 -file-list-exec-source-files
2250 List the source files for the current executable.
2252 @subsubheading @value{GDBN} Command
2254 There's no @value{GDBN} command which directly corresponds to this one.
2255 @code{gdbtk} has an analogous command @samp{gdb_listfiles}.
2257 @subsubheading Example
2261 @subheading The @code{-file-list-shared-libraries} Command
2262 @findex -file-list-shared-libraries
2264 @subsubheading Synopsis
2267 -file-list-shared-libraries
2270 List the shared libraries in the program.
2272 @subsubheading @value{GDBN} Command
2274 The corresponding @value{GDBN} command is @samp{info shared}.
2276 @subsubheading Example
2280 @subheading The @code{-file-list-symbol-files} Command
2281 @findex -file-list-symbol-files
2283 @subsubheading Synopsis
2286 -file-list-symbol-files
2291 @subsubheading @value{GDBN} Command
2293 The corresponding @value{GDBN} command is @samp{info file} (part of it).
2295 @subsubheading Example
2299 @subheading The @code{-file-symbol-file} Command
2300 @findex -file-symbol-file
2302 @subsubheading Synopsis
2305 -file-symbol-file @var{file}
2308 Read symbol table info from the specified @var{file} argument. When
2309 used without arguments, clears @value{GDBN}'s symbol table info. No output is
2310 produced, except for a completion notification.
2312 @subsubheading @value{GDBN} Command
2314 The corresponding @value{GDBN} command is @samp{symbol-file}.
2316 @subsubheading Example
2320 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2325 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2326 @node GDB/MI Miscellaneous Commands
2327 @section Miscellaneous @value{GDBN} commands in @sc{gdb/mi}
2329 @c @subheading -gdb-complete
2331 @subheading The @code{-gdb-exit} Command
2334 @subsubheading Synopsis
2340 Exit @value{GDBN} immediately.
2342 @subsubheading @value{GDBN} Command
2344 Approximately corresponds to @samp{quit}.
2346 @subsubheading Example
2353 @subheading The @code{-gdb-set} Command
2356 @subsubheading Synopsis
2362 Set an internal @value{GDBN} variable.
2363 @c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
2365 @subsubheading @value{GDBN} Command
2367 The corresponding @value{GDBN} command is @samp{set}.
2369 @subsubheading Example
2379 @subheading The @code{-gdb-show} Command
2382 @subsubheading Synopsis
2388 Show the current value of a @value{GDBN} variable.
2390 @subsubheading @value{GDBN} command
2392 The corresponding @value{GDBN} command is @samp{show}.
2394 @subsubheading Example
2403 @c @subheading -gdb-source
2406 @subheading The @code{-gdb-version} Command
2407 @findex -gdb-version
2409 @subsubheading Synopsis
2415 Show version information for @value{GDBN}. Used mostly in testing.
2417 @subsubheading @value{GDBN} Command
2419 There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this
2420 information when you start an interactive session.
2422 @subsubheading Example
2424 @c This example modifies the actual output from GDB to avoid overfull
2430 ~Copyright 2000 Free Software Foundation, Inc.
2431 ~GDB is free software, covered by the GNU General Public License, and
2432 ~you are welcome to change it and/or distribute copies of it under
2433 ~ certain conditions.
2434 ~Type "show copying" to see the conditions.
2435 ~There is absolutely no warranty for GDB. Type "show warranty" for
2437 ~This GDB was configured as
2438 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
2444 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2445 @node GDB/MI Kod Commands
2446 @section @sc{gdb/mi} Kod Commands
2448 The Kod commands are not implemented.
2450 @c @subheading -kod-info
2452 @c @subheading -kod-list
2454 @c @subheading -kod-list-object-types
2456 @c @subheading -kod-show
2458 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2459 @node GDB/MI Memory Overlay Commands
2460 @section @sc{gdb/mi} Memory Overlay Commands
2462 The memory overlay commands are not implemented.
2464 @c @subheading -overlay-auto
2466 @c @subheading -overlay-list-mapping-state
2468 @c @subheading -overlay-list-overlays
2470 @c @subheading -overlay-map
2472 @c @subheading -overlay-off
2474 @c @subheading -overlay-on
2476 @c @subheading -overlay-unmap
2478 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2479 @node GDB/MI Signal Handling Commands
2480 @section @sc{gdb/mi} Signal Handling Commands
2482 Signal handling commands are not implemented.
2484 @c @subheading -signal-handle
2486 @c @subheading -signal-list-handle-actions
2488 @c @subheading -signal-list-signal-types
2492 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2493 @node GDB/MI Stack Manipulation
2494 @section Stack manipulation commands in @sc{gdb/mi}
2497 @subheading The @code{-stack-info-frame} Command
2498 @findex -stack-info-frame
2500 @subsubheading Synopsis
2506 Get info on the current frame.
2508 @subsubheading @value{GDBN} Command
2510 The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
2511 (without arguments).
2513 @subsubheading Example
2516 @subheading The @code{-stack-info-depth} Command
2517 @findex -stack-info-depth
2519 @subsubheading Synopsis
2522 -stack-info-depth [ @var{max-depth} ]
2525 Return the depth of the stack. If the integer argument @var{max-depth}
2526 is specified, do not count beyond @var{max-depth} frames.
2528 @subsubheading @value{GDBN} Command
2530 There's no equivalent @value{GDBN} command.
2532 @subsubheading Example
2534 For a stack with frame levels 0 through 11:
2544 -stack-info-depth 12
2547 -stack-info-depth 11
2550 -stack-info-depth 13
2555 @subheading The @code{-stack-list-arguments} Command
2556 @findex -stack-list-arguments
2558 @subsubheading Synopsis
2561 -stack-list-arguments @var{show-values}
2562 [ @var{low-frame} @var{high-frame} ]
2565 Display a list of the arguments for the frames between @var{low-frame}
2566 and @var{high-frame} (inclusive). If @var{low-frame} and
2567 @var{high-frame} are not provided, list the arguments for the whole call
2570 The @var{show-values} argument must have a value of 0 or 1. A value of
2571 0 means that only the names of the arguments are listed, a value of 1
2572 means that both names and values of the arguments are printed.
2574 @subsubheading @value{GDBN} Command
2576 @value{GDBN} does not have an equivalent command. @code{gdbtk} has a
2577 @samp{gdb_get_args} command which partially overlaps with the
2578 functionality of @samp{-stack-list-arguments}.
2580 @subsubheading Example
2587 frame=@{level="0 ",addr="0x00010734",func="callee4",
2588 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
2589 frame=@{level="1 ",addr="0x0001076c",func="callee3",
2590 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
2591 frame=@{level="2 ",addr="0x0001078c",func="callee2",
2592 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
2593 frame=@{level="3 ",addr="0x000107b4",func="callee1",
2594 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
2595 frame=@{level="4 ",addr="0x000107e0",func="main",
2596 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}@}
2598 -stack-list-arguments 0
2601 frame=@{level="0",args=@{@}@},
2602 frame=@{level="1",args=@{name="strarg"@}@},
2603 frame=@{level="2",args=@{name="intarg",name="strarg"@}@},
2604 frame=@{level="3",args=@{name="intarg",name="strarg",name="fltarg"@}@},
2605 frame=@{level="4",args=@{@}@}@}
2607 -stack-list-arguments 1
2610 frame=@{level="0",args=@{@}@},
2612 args=@{@{name="strarg",value="0x11940 \"A string argument.\""@}@}@},
2613 frame=@{level="2",args=@{
2614 @{name="intarg",value="2"@},
2615 @{name="strarg",value="0x11940 \"A string argument.\""@}@}@},
2616 @{frame=@{level="3",args=@{
2617 @{name="intarg",value="2"@},
2618 @{name="strarg",value="0x11940 \"A string argument.\""@},
2619 @{name="fltarg",value="3.5"@}@}@},
2620 frame=@{level="4",args=@{@}@}@}
2622 -stack-list-arguments 0 2 2
2623 ^done,stack-args=@{frame=@{level="2",args=@{name="intarg",name="strarg"@}@}@}
2625 -stack-list-arguments 1 2 2
2626 ^done,stack-args=@{frame=@{level="2",
2627 args=@{@{name="intarg",value="2"@},
2628 @{name="strarg",value="0x11940 \"A string argument.\""@}@}@}@}
2632 @c @subheading -stack-list-exception-handlers
2635 @subheading The @code{-stack-list-frames} Command
2636 @findex -stack-list-frames
2638 @subsubheading Synopsis
2641 -stack-list-frames [ @var{low-frame} @var{high-frame} ]
2644 List the frames currently on the stack. For each frame it displays the
2649 The frame number, 0 being the topmost frame, i.e. the innermost function.
2651 The @code{$pc} value for that frame.
2655 File name of the source file where the function lives.
2657 Line number corresponding to the @code{$pc}.
2660 If invoked without arguments, this command prints a backtrace for the
2661 whole stack. If given two integer arguments, it shows the frames whose
2662 levels are between the two arguments (inclusive). If the two arguments
2663 are equal, it shows the single frame at the corresponding level.
2665 @subsubheading @value{GDBN} Command
2667 The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
2669 @subsubheading Example
2671 Full stack backtrace:
2677 @{frame=@{level="0 ",addr="0x0001076c",func="foo",
2678 file="recursive2.c",line="11"@},
2679 frame=@{level="1 ",addr="0x000107a4",func="foo",
2680 file="recursive2.c",line="14"@},
2681 frame=@{level="2 ",addr="0x000107a4",func="foo",
2682 file="recursive2.c",line="14"@},
2683 frame=@{level="3 ",addr="0x000107a4",func="foo",
2684 file="recursive2.c",line="14"@},
2685 frame=@{level="4 ",addr="0x000107a4",func="foo",
2686 file="recursive2.c",line="14"@},
2687 frame=@{level="5 ",addr="0x000107a4",func="foo",
2688 file="recursive2.c",line="14"@},
2689 frame=@{level="6 ",addr="0x000107a4",func="foo",
2690 file="recursive2.c",line="14"@},
2691 frame=@{level="7 ",addr="0x000107a4",func="foo",
2692 file="recursive2.c",line="14"@},
2693 frame=@{level="8 ",addr="0x000107a4",func="foo",
2694 file="recursive2.c",line="14"@},
2695 frame=@{level="9 ",addr="0x000107a4",func="foo",
2696 file="recursive2.c",line="14"@},
2697 frame=@{level="10",addr="0x000107a4",func="foo",
2698 file="recursive2.c",line="14"@},
2699 frame=@{level="11",addr="0x00010738",func="main",
2700 file="recursive2.c",line="4"@}@}
2704 Show frames between @var{low_frame} and @var{high_frame}:
2708 -stack-list-frames 3 5
2710 @{frame=@{level="3 ",addr="0x000107a4",func="foo",
2711 file="recursive2.c",line="14"@},
2712 frame=@{level="4 ",addr="0x000107a4",func="foo",
2713 file="recursive2.c",line="14"@},
2714 frame=@{level="5 ",addr="0x000107a4",func="foo",
2715 file="recursive2.c",line="14"@}@}
2719 Show a single frame:
2723 -stack-list-frames 3 3
2725 @{frame=@{level="3 ",addr="0x000107a4",func="foo",
2726 file="recursive2.c",line="14"@}@}
2731 @subheading The @code{-stack-list-locals} Command
2732 @findex -stack-list-locals
2734 @subsubheading Synopsis
2737 -stack-list-locals @var{print-values}
2740 Display the local variable names for the current frame. With an
2741 argument of 0 prints only the names of the variables, with argument of 1
2742 prints also their values.
2744 @subsubheading @value{GDBN} Command
2746 @samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
2748 @subsubheading Example
2752 -stack-list-locals 0
2753 ^done,locals=@{name="A",name="B",name="C"@}
2755 -stack-list-locals 1
2756 ^done,locals=@{@{name="A",value="1"@},@{name="B",value="2"@},
2757 @{name="C",value="3"@}@}
2762 @subheading The @code{-stack-select-frame} Command
2763 @findex -stack-select-frame
2765 @subsubheading Synopsis
2768 -stack-select-frame @var{framenum}
2771 Change the current frame. Select a different frame @var{framenum} on
2774 @subsubheading @value{GDBN} Command
2776 The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
2777 @samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
2779 @subsubheading Example
2783 -stack-select-frame 2
2788 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2789 @node GDB/MI Symbol Query
2790 @section @sc{gdb/mi} Symbol Query Commands
2793 @subheading The @code{-symbol-info-address} Command
2794 @findex -symbol-info-address
2796 @subsubheading Synopsis
2799 -symbol-info-address @var{symbol}
2802 Describe where @var{symbol} is stored.
2804 @subsubheading @value{GDBN} Command
2806 The corresponding @value{GDBN} command is @samp{info address}.
2808 @subsubheading Example
2812 @subheading The @code{-symbol-info-file} Command
2813 @findex -symbol-info-file
2815 @subsubheading Synopsis
2821 Show the file for the symbol.
2823 @subsubheading @value{GDBN} Command
2825 There's no equivalent @value{GDBN} command. @code{gdbtk} has
2826 @samp{gdb_find_file}.
2828 @subsubheading Example
2832 @subheading The @code{-symbol-info-function} Command
2833 @findex -symbol-info-function
2835 @subsubheading Synopsis
2838 -symbol-info-function
2841 Show which function the symbol lives in.
2843 @subsubheading @value{GDBN} Command
2845 @samp{gdb_get_function} in @code{gdbtk}.
2847 @subsubheading Example
2851 @subheading The @code{-symbol-info-line} Command
2852 @findex -symbol-info-line
2854 @subsubheading Synopsis
2860 Show the core addresses of the code for a source line.
2862 @subsubheading @value{GDBN} Command
2864 The corresponding @value{GDBN} comamnd is @samp{info line}.
2865 @code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
2867 @subsubheading Example
2871 @subheading The @code{-symbol-info-symbol} Command
2872 @findex -symbol-info-symbol
2874 @subsubheading Synopsis
2877 -symbol-info-symbol @var{addr}
2880 Describe what symbol is at location @var{addr}.
2882 @subsubheading @value{GDBN} Command
2884 The corresponding @value{GDBN} command is @samp{info symbol}.
2886 @subsubheading Example
2890 @subheading The @code{-symbol-list-functions} Command
2891 @findex -symbol-list-functions
2893 @subsubheading Synopsis
2896 -symbol-list-functions
2899 List the functions in the executable.
2901 @subsubheading @value{GDBN} Command
2903 @samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
2904 @samp{gdb_search} in @code{gdbtk}.
2906 @subsubheading Example
2910 @subheading The @code{-symbol-list-types} Command
2911 @findex -symbol-list-types
2913 @subsubheading Synopsis
2919 List all the type names.
2921 @subsubheading @value{GDBN} Command
2923 The corresponding commands are @samp{info types} in @value{GDBN},
2924 @samp{gdb_search} in @code{gdbtk}.
2926 @subsubheading Example
2930 @subheading The @code{-symbol-list-variables} Command
2931 @findex -symbol-list-variables
2933 @subsubheading Synopsis
2936 -symbol-list-variables
2939 List all the global and static variable names.
2941 @subsubheading @value{GDBN} Command
2943 @samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
2945 @subsubheading Example
2949 @subheading The @code{-symbol-locate} Command
2950 @findex -symbol-locate
2952 @subsubheading Synopsis
2958 @subsubheading @value{GDBN} Command
2960 @samp{gdb_loc} in @code{gdbtk}.
2962 @subsubheading Example
2966 @subheading The @code{-symbol-type} Command
2967 @findex -symbol-type
2969 @subsubheading Synopsis
2972 -symbol-type @var{variable}
2975 Show type of @var{variable}.
2977 @subsubheading @value{GDBN} Command
2979 The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
2980 @samp{gdb_obj_variable}.
2982 @subsubheading Example
2986 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2987 @node GDB/MI Target Manipulation
2988 @section @sc{gdb/mi} Target Manipulation Commands
2991 @subheading The @code{-target-attach} Command
2992 @findex -target-attach
2994 @subsubheading Synopsis
2997 -target-attach @var{pid} | @var{file}
3000 Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
3002 @subsubheading @value{GDBN} command
3004 The corresponding @value{GDBN} command is @samp{attach}.
3006 @subsubheading Example
3010 @subheading The @code{-target-compare-sections} Command
3011 @findex -target-compare-sections
3013 @subsubheading Synopsis
3016 -target-compare-sections [ @var{section} ]
3019 Compare data of section @var{section} on target to the exec file.
3020 Without the argument, all sections are compared.
3022 @subsubheading @value{GDBN} Command
3024 The @value{GDBN} equivalent is @samp{compare-sections}.
3026 @subsubheading Example
3030 @subheading The @code{-target-detach} Command
3031 @findex -target-detach
3033 @subsubheading Synopsis
3039 Disconnect from the remote target. There's no output.
3041 @subsubheading @value{GDBN} command
3043 The corresponding @value{GDBN} command is @samp{detach}.
3045 @subsubheading Example
3055 @subheading The @code{-target-download} Command
3056 @findex -target-download
3058 @subsubheading Synopsis
3064 Loads the executable onto the remote target.
3065 It prints out an update message every half second, which includes the fields:
3069 The name of the section.
3071 The size of what has been sent so far for that section.
3073 The size of the section.
3075 The total size of what was sent so far (the current and the previous sections).
3077 The size of the overall executable to download.
3081 Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
3082 @sc{gdb/mi} Output Syntax}).
3084 In addition, it prints the name and size of the sections, as they are
3085 downloaded. These messages include the following fields:
3089 The name of the section.
3091 The size of the section.
3093 The size of the overall executable to download.
3097 At the end, a summary is printed.
3099 @subsubheading @value{GDBN} Command
3101 The corresponding @value{GDBN} command is @samp{load}.
3103 @subsubheading Example
3105 Note: each status message appears on a single line. Here the messages
3106 have been broken down so that they can fit onto a page.
3111 +download,@{section=".text",section-size="6668",total-size="9880"@}
3112 +download,@{section=".text",section-sent="512",section-size="6668",
3113 total-sent="512",total-size="9880"@}
3114 +download,@{section=".text",section-sent="1024",section-size="6668",
3115 total-sent="1024",total-size="9880"@}
3116 +download,@{section=".text",section-sent="1536",section-size="6668",
3117 total-sent="1536",total-size="9880"@}
3118 +download,@{section=".text",section-sent="2048",section-size="6668",
3119 total-sent="2048",total-size="9880"@}
3120 +download,@{section=".text",section-sent="2560",section-size="6668",
3121 total-sent="2560",total-size="9880"@}
3122 +download,@{section=".text",section-sent="3072",section-size="6668",
3123 total-sent="3072",total-size="9880"@}
3124 +download,@{section=".text",section-sent="3584",section-size="6668",
3125 total-sent="3584",total-size="9880"@}
3126 +download,@{section=".text",section-sent="4096",section-size="6668",
3127 total-sent="4096",total-size="9880"@}
3128 +download,@{section=".text",section-sent="4608",section-size="6668",
3129 total-sent="4608",total-size="9880"@}
3130 +download,@{section=".text",section-sent="5120",section-size="6668",
3131 total-sent="5120",total-size="9880"@}
3132 +download,@{section=".text",section-sent="5632",section-size="6668",
3133 total-sent="5632",total-size="9880"@}
3134 +download,@{section=".text",section-sent="6144",section-size="6668",
3135 total-sent="6144",total-size="9880"@}
3136 +download,@{section=".text",section-sent="6656",section-size="6668",
3137 total-sent="6656",total-size="9880"@}
3138 +download,@{section=".init",section-size="28",total-size="9880"@}
3139 +download,@{section=".fini",section-size="28",total-size="9880"@}
3140 +download,@{section=".data",section-size="3156",total-size="9880"@}
3141 +download,@{section=".data",section-sent="512",section-size="3156",
3142 total-sent="7236",total-size="9880"@}
3143 +download,@{section=".data",section-sent="1024",section-size="3156",
3144 total-sent="7748",total-size="9880"@}
3145 +download,@{section=".data",section-sent="1536",section-size="3156",
3146 total-sent="8260",total-size="9880"@}
3147 +download,@{section=".data",section-sent="2048",section-size="3156",
3148 total-sent="8772",total-size="9880"@}
3149 +download,@{section=".data",section-sent="2560",section-size="3156",
3150 total-sent="9284",total-size="9880"@}
3151 +download,@{section=".data",section-sent="3072",section-size="3156",
3152 total-sent="9796",total-size="9880"@}
3153 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
3159 @subheading The @code{-target-exec-status} Command
3160 @findex -target-exec-status
3162 @subsubheading Synopsis
3168 Provide information on the state of the target (whether it is running or
3171 @subsubheading @value{GDBN} Command
3173 There's no equivalent @value{GDBN} command.
3175 @subsubheading Example
3179 @subheading The @code{-target-list-available-targets} Command
3180 @findex -target-list-available-targets
3182 @subsubheading Synopsis
3185 -target-list-available-targets
3188 List the possible targets to connect to.
3190 @subsubheading @value{GDBN} Command
3192 The corresponding @value{GDBN} command is @samp{help target}.
3194 @subsubheading Example
3198 @subheading The @code{-target-list-current-targets} Command
3199 @findex -target-list-current-targets
3201 @subsubheading Synopsis
3204 -target-list-current-targets
3207 Describe the current target.
3209 @subsubheading @value{GDBN} Command
3211 The corresponding information is printed by @samp{info file} (among
3214 @subsubheading Example
3218 @subheading The @code{-target-list-parameters} Command
3219 @findex -target-list-parameters
3221 @subsubheading Synopsis
3224 -target-list-parameters
3229 @subsubheading @value{GDBN} Command
3233 @subsubheading Example
3237 @subheading The @code{-target-select} Command
3238 @findex -target-select
3240 @subsubheading Synopsis
3243 -target-select @var{type} @var{parameters @dots{}}
3246 Connect @value{GDBN} to the remote target. This command takes two args:
3250 The type of target, for instance @samp{async}, @samp{remote}, etc.
3251 @item @var{parameters}
3252 Device names, host names and the like. @xref{Target Commands, ,
3253 Commands for managing targets}, for more details.
3256 The output is a connection notification, followed by the address at
3257 which the target program is, in the following form:
3260 ^connected,addr="@var{address}",func="@var{function name}",
3261 args=@{@var{arg list}@}
3264 @subsubheading @value{GDBN} Command
3266 The corresponding @value{GDBN} command is @samp{target}.
3268 @subsubheading Example
3272 -target-select async /dev/ttya
3273 ^connected,addr="0xfe00a300",func="??",args=@{@}
3277 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3278 @node GDB/MI Thread Commands
3279 @section @sc{gdb/mi} Thread Commands
3282 @subheading The @code{-thread-info} Command
3283 @findex -thread-info
3285 @subsubheading Synopsis
3291 @subsubheading @value{GDBN} command
3295 @subsubheading Example
3299 @subheading The @code{-thread-list-all-threads} Command
3300 @findex -thread-list-all-threads
3302 @subsubheading Synopsis
3305 -thread-list-all-threads
3308 @subsubheading @value{GDBN} Command
3310 The equivalent @value{GDBN} command is @samp{info threads}.
3312 @subsubheading Example
3316 @subheading The @code{-thread-list-ids} Command
3317 @findex -thread-list-ids
3319 @subsubheading Synopsis
3325 Produces a list of the currently known @value{GDBN} thread ids. At the
3326 end of the list it also prints the total number of such threads.
3328 @subsubheading @value{GDBN} Command
3330 Part of @samp{info threads} supplies the same information.
3332 @subsubheading Example
3334 No threads present, besides the main process:
3339 ^done,thread-ids=@{@},number-of-threads="0"
3349 ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3350 number-of-threads="3"
3355 @subheading The @code{-thread-select} Command
3356 @findex -thread-select
3358 @subsubheading Synopsis
3361 -thread-select @var{threadnum}
3364 Make @var{threadnum} the current thread. It prints the number of the new
3365 current thread, and the topmost frame for that thread.
3367 @subsubheading @value{GDBN} Command
3369 The corresponding @value{GDBN} command is @samp{thread}.
3371 @subsubheading Example
3378 *stopped,reason="end-stepping-range",thread-id="2",line="187",
3379 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
3383 thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3384 number-of-threads="3"
3387 ^done,new-thread-id="3",
3388 frame=@{level="0 ",func="vprintf",
3389 args=@{@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
3390 @{name="arg",value="0x2"@}@},file="vprintf.c",line="31"@}
3394 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3395 @node GDB/MI Tracepoint Commands
3396 @section @sc{gdb/mi} Tracepoint Commands
3398 The tracepoint commands are not yet implemented.
3400 @c @subheading -trace-actions
3402 @c @subheading -trace-delete
3404 @c @subheading -trace-disable
3406 @c @subheading -trace-dump
3408 @c @subheading -trace-enable
3410 @c @subheading -trace-exists
3412 @c @subheading -trace-find
3414 @c @subheading -trace-frame-number
3416 @c @subheading -trace-info
3418 @c @subheading -trace-insert
3420 @c @subheading -trace-list
3422 @c @subheading -trace-pass-count
3424 @c @subheading -trace-save
3426 @c @subheading -trace-start
3428 @c @subheading -trace-stop
3431 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3432 @node GDB/MI Variable Objects
3433 @section @sc{gdb/mi} Variable Objects
3436 @subheading Motivation for Variable Objects in @sc{gdb/mi}
3438 For the implementation of a variable debugger window (locals, watched
3439 expressions, etc.), we are proposing the adaptation of the existing code
3440 used by @code{Insight}.
3442 The two main reasons for that are:
3446 It has been proven in practice (it is already on its second generation).
3449 It will shorten development time (needless to say how important it is
3453 The original interface was designed to be used by Tcl code, so it was
3454 slightly changed so it could be used through @sc{gdb/mi}. This section
3455 describes the @sc{gdb/mi} operations that will be available and gives some
3456 hints about their use.
3458 @emph{Note}: In addition to the set of operations described here, we
3459 expect the @sc{gui} implementation of a variable window to require, at
3460 least, the following operations:
3463 @item @code{-gdb-show} @code{output-radix}
3464 @item @code{-stack-list-arguments}
3465 @item @code{-stack-list-locals}
3466 @item @code{-stack-select-frame}
3469 @subheading Introduction to Variable Objects in @sc{gdb/mi}
3471 @cindex variable objects in @sc{gdb/mi}
3472 The basic idea behind variable objects is the creation of a named object
3473 to represent a variable, an expression, a memory location or even a CPU
3474 register. For each object created, a set of operations is available for
3475 examining or changing its properties.
3477 Furthermore, complex data types, such as C structures, are represented
3478 in a tree format. For instance, the @code{struct} type variable is the
3479 root and the children will represent the struct members. If a child
3480 is itself of a complex type, it will also have children of its own.
3481 Appropriate language differences are handled for C, C@t{++} and Java.
3483 When returning the actual values of the objects, this facility allows
3484 for the individual selection of the display format used in the result
3485 creation. It can be chosen among: binary, decimal, hexadecimal, octal
3486 and natural. Natural refers to a default format automatically
3487 chosen based on the variable type (like decimal for an @code{int}, hex
3488 for pointers, etc.).
3490 The following is the complete set of @sc{gdb/mi} operations defined to
3491 access this functionality:
3493 @multitable @columnfractions .4 .6
3494 @item @strong{Operation}
3495 @tab @strong{Description}
3497 @item @code{-var-create}
3498 @tab create a variable object
3499 @item @code{-var-delete}
3500 @tab delete the variable object and its children
3501 @item @code{-var-set-format}
3502 @tab set the display format of this variable
3503 @item @code{-var-show-format}
3504 @tab show the display format of this variable
3505 @item @code{-var-info-num-children}
3506 @tab tells how many children this object has
3507 @item @code{-var-list-children}
3508 @tab return a list of the object's children
3509 @item @code{-var-info-type}
3510 @tab show the type of this variable object
3511 @item @code{-var-info-expression}
3512 @tab print what this variable object represents
3513 @item @code{-var-show-attributes}
3514 @tab is this variable editable? does it exist here?
3515 @item @code{-var-evaluate-expression}
3516 @tab get the value of this variable
3517 @item @code{-var-assign}
3518 @tab set the value of this variable
3519 @item @code{-var-update}
3520 @tab update the variable and its children
3523 In the next subsection we describe each operation in detail and suggest
3526 @subheading Description And Use of Operations on Variable Objects
3528 @subheading The @code{-var-create} Command
3531 @subsubheading Synopsis
3534 -var-create @{@var{name} | "-"@}
3535 @{@var{frame-addr} | "*"@} @var{expression}
3538 This operation creates a variable object, which allows the monitoring of
3539 a variable, the result of an expression, a memory cell or a CPU
3542 The @var{name} parameter is the string by which the object can be
3543 referenced. It must be unique. If @samp{-} is specified, the varobj
3544 system will generate a string ``varNNNNNN'' automatically. It will be
3545 unique provided that one does not specify @var{name} on that format.
3546 The command fails if a duplicate name is found.
3548 The frame under which the expression should be evaluated can be
3549 specified by @var{frame-addr}. A @samp{*} indicates that the current
3550 frame should be used.
3552 @var{expression} is any expression valid on the current language set (must not
3553 begin with a @samp{*}), or one of the following:
3557 @samp{*@var{addr}}, where @var{addr} is the address of a memory cell
3560 @samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
3563 @samp{$@var{regname}} --- a CPU register name
3566 @subsubheading Result
3568 This operation returns the name, number of children and the type of the
3569 object created. Type is returned as a string as the ones generated by
3570 the @value{GDBN} CLI:
3573 name="@var{name}",numchild="N",type="@var{type}"
3577 @subheading The @code{-var-delete} Command
3580 @subsubheading Synopsis
3583 -var-delete @var{name}
3586 Deletes a previously created variable object and all of its children.
3588 Returns an error if the object @var{name} is not found.
3591 @subheading The @code{-var-set-format} Command
3592 @findex -var-set-format
3594 @subsubheading Synopsis
3597 -var-set-format @var{name} @var{format-spec}
3600 Sets the output format for the value of the object @var{name} to be
3603 The syntax for the @var{format-spec} is as follows:
3606 @var{format-spec} @expansion{}
3607 @{binary | decimal | hexadecimal | octal | natural@}
3611 @subheading The @code{-var-show-format} Command
3612 @findex -var-show-format
3614 @subsubheading Synopsis
3617 -var-show-format @var{name}
3620 Returns the format used to display the value of the object @var{name}.
3623 @var{format} @expansion{}
3628 @subheading The @code{-var-info-num-children} Command
3629 @findex -var-info-num-children
3631 @subsubheading Synopsis
3634 -var-info-num-children @var{name}
3637 Returns the number of children of a variable object @var{name}:
3644 @subheading The @code{-var-list-children} Command
3645 @findex -var-list-children
3647 @subsubheading Synopsis
3650 -var-list-children @var{name}
3653 Returns a list of the children of the specified variable object:
3656 numchild=@var{n},children=@{@{name=@var{name},
3657 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}@}
3661 @subheading The @code{-var-info-type} Command
3662 @findex -var-info-type
3664 @subsubheading Synopsis
3667 -var-info-type @var{name}
3670 Returns the type of the specified variable @var{name}. The type is
3671 returned as a string in the same format as it is output by the
3679 @subheading The @code{-var-info-expression} Command
3680 @findex -var-info-expression
3682 @subsubheading Synopsis
3685 -var-info-expression @var{name}
3688 Returns what is represented by the variable object @var{name}:
3691 lang=@var{lang-spec},exp=@var{expression}
3695 where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
3697 @subheading The @code{-var-show-attributes} Command
3698 @findex -var-show-attributes
3700 @subsubheading Synopsis
3703 -var-show-attributes @var{name}
3706 List attributes of the specified variable object @var{name}:
3709 status=@var{attr} [ ( ,@var{attr} )* ]
3713 where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
3715 @subheading The @code{-var-evaluate-expression} Command
3716 @findex -var-evaluate-expression
3718 @subsubheading Synopsis
3721 -var-evaluate-expression @var{name}
3724 Evaluates the expression that is represented by the specified variable
3725 object and returns its value as a string in the current format specified
3732 @subheading The @code{-var-assign} Command
3735 @subsubheading Synopsis
3738 -var-assign @var{name} @var{expression}
3741 Assigns the value of @var{expression} to the variable object specified
3742 by @var{name}. The object must be @samp{editable}.
3744 @subheading The @code{-var-update} Command
3747 @subsubheading Synopsis
3750 -var-update @{@var{name} | "*"@}
3753 Update the value of the variable object @var{name} by evaluating its
3754 expression after fetching all the new values from memory or registers.
3755 A @samp{*} causes all existing variable objects to be updated.
3758 @c change-log-default-name: "ChangeLog-mi"