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"@}@}@},
1155 src_and_asm_line=@{line="32",
1156 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1157 testsuite/gdb.mi/basics.c",line_asm_insn=@{
1158 @{address="0x000107c0",func-name="main",offset="4",
1159 inst="mov 2, %o0"@},
1160 @{address="0x000107c4",func-name="main",offset="8",
1161 inst="sethi %hi(0x11800), %o2"@}@}@}@}
1166 @subheading The @code{-data-evaluate-expression} Command
1167 @findex -data-evaluate-expression
1169 @subsubheading Synopsis
1172 -data-evaluate-expression @var{expr}
1175 Evaluate @var{expr} as an expression. The expression could contain an
1176 inferior function call. The function call will execute synchronously.
1177 If the expression contains spaces, it must be enclosed in double quotes.
1179 @subsubheading @value{GDBN} Command
1181 The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
1182 @samp{call}. In @code{gdbtk} only, there's a corresponding
1183 @samp{gdb_eval} command.
1185 @subsubheading Example
1187 In the following example, the numbers that precede the commands are the
1188 @dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
1189 Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
1193 211-data-evaluate-expression A
1196 311-data-evaluate-expression &A
1197 311^done,value="0xefffeb7c"
1199 411-data-evaluate-expression A+3
1202 511-data-evaluate-expression "A + 3"
1208 @subheading The @code{-data-list-changed-registers} Command
1209 @findex -data-list-changed-registers
1211 @subsubheading Synopsis
1214 -data-list-changed-registers
1217 Display a list of the registers that have changed.
1219 @subsubheading @value{GDBN} Command
1221 @value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
1222 has the corresponding command @samp{gdb_changed_register_list}.
1224 @subsubheading Example
1234 *stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
1235 args=@{@},file="try.c",line="5"@}
1237 -data-list-changed-registers
1238 ^done,changed-registers=@{"0","1","2","4","5","6","7","8","9",
1239 "10","11","13","14","15","16","17","18","19","20","21","22","23",
1240 "24","25","26","27","28","30","31","64","65","66","67","69"@}
1245 @subheading The @code{-data-list-register-names} Command
1246 @findex -data-list-register-names
1248 @subsubheading Synopsis
1251 -data-list-register-names [ ( @var{regno} )+ ]
1254 Show a list of register names for the current target. If no arguments
1255 are given, it shows a list of the names of all the registers. If
1256 integer numbers are given as arguments, it will print a list of the
1257 names of the registers corresponding to the arguments.
1259 @subsubheading @value{GDBN} Command
1261 @value{GDBN} does not have a command which corresponds to
1262 @samp{-data-list-register-names}. In @code{gdbtk} there is a
1263 corresponding command @samp{gdb_regnames}.
1265 @subsubheading Example
1267 For the PPC MBX board:
1270 -data-list-register-names
1271 ^done,register-names=@{"r0","r1","r2","r3","r4","r5","r6","r7",
1272 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
1273 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
1274 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
1275 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
1276 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
1277 "pc","ps","cr","lr","ctr","xer"@}
1279 -data-list-register-names 1 2 3
1280 ^done,register-names=@{"r1","r2","r3"@}
1284 @subheading The @code{-data-list-register-values} Command
1285 @findex -data-list-register-values
1287 @subsubheading Synopsis
1290 -data-list-register-values @var{fmt} [ ( @var{regno} )*]
1293 Display the registers' contents. @var{fmt} is the format according to
1294 which the registers' contents are to be returned, followed by an optional
1295 list of numbers specifying the registers to display. A missing list of
1296 numbers indicates that the contents of all the registers must be returned.
1298 Allowed formats for @var{fmt} are:
1315 @subsubheading @value{GDBN} Command
1317 The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
1318 all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
1320 @subsubheading Example
1322 For a PPC MBX board (note: line breaks are for readability only, they
1323 don't appear in the actual output):
1327 -data-list-register-values r 64 65
1328 ^done,register-values=@{@{number="64",value="0xfe00a300"@},
1329 @{number="65",value="0x00029002"@}@}
1331 -data-list-register-values x
1332 ^done,register-values=@{@{number="0",value="0xfe0043c8"@},
1333 @{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
1334 @{number="3",value="0x0"@},@{number="4",value="0xa"@},
1335 @{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
1336 @{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
1337 @{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
1338 @{number="11",value="0x1"@},@{number="12",value="0x0"@},
1339 @{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
1340 @{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
1341 @{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
1342 @{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
1343 @{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
1344 @{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
1345 @{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
1346 @{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
1347 @{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
1348 @{number="31",value="0x0"@},@{number="32",value="0x0"@},
1349 @{number="33",value="0x0"@},@{number="34",value="0x0"@},
1350 @{number="35",value="0x0"@},@{number="36",value="0x0"@},
1351 @{number="37",value="0x0"@},@{number="38",value="0x0"@},
1352 @{number="39",value="0x0"@},@{number="40",value="0x0"@},
1353 @{number="41",value="0x0"@},@{number="42",value="0x0"@},
1354 @{number="43",value="0x0"@},@{number="44",value="0x0"@},
1355 @{number="45",value="0x0"@},@{number="46",value="0x0"@},
1356 @{number="47",value="0x0"@},@{number="48",value="0x0"@},
1357 @{number="49",value="0x0"@},@{number="50",value="0x0"@},
1358 @{number="51",value="0x0"@},@{number="52",value="0x0"@},
1359 @{number="53",value="0x0"@},@{number="54",value="0x0"@},
1360 @{number="55",value="0x0"@},@{number="56",value="0x0"@},
1361 @{number="57",value="0x0"@},@{number="58",value="0x0"@},
1362 @{number="59",value="0x0"@},@{number="60",value="0x0"@},
1363 @{number="61",value="0x0"@},@{number="62",value="0x0"@},
1364 @{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
1365 @{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
1366 @{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
1367 @{number="69",value="0x20002b03"@}@}
1372 @subheading The @code{-data-read-memory} Command
1373 @findex -data-read-memory
1375 @subsubheading Synopsis
1378 -data-read-memory [ -o @var{byte-offset} ]
1379 @var{address} @var{word-format} @var{word-size}
1380 @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
1388 An expression specifying the address of the first memory word to be
1389 read. Complex expressions containing embedded white space should be
1390 quoted using the C convention.
1392 @item @var{word-format}
1393 The format to be used to print the memory words. The notation is the
1394 same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
1397 @item @var{word-size}
1398 The size of each memory word in bytes.
1401 The number of rows in the output table.
1404 The number of columns in the output table.
1407 If present, indicates that each row should include an @sc{ascii} dump. The
1408 value of @var{aschar} is used as a padding character when a byte is not a
1409 member of the printable @sc{ascii} character set (printable @sc{ascii}
1410 characters are those whose code is between 32 and 126, inclusively).
1412 @item @var{byte-offset}
1413 An offset to add to the @var{address} before fetching memory.
1416 This command displays memory contents as a table of @var{nr-rows} by
1417 @var{nr-cols} words, each word being @var{word-size} bytes. In total,
1418 @code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
1419 (returned as @samp{total-bytes}). Should less then the requested number
1420 of bytes be returned by the target, the missing words are identified
1421 using @samp{N/A}. The number of bytes read from the target is returned
1422 in @samp{nr-bytes} and the starting address used to read memory in
1425 The address of the next/previous row or page is available in
1426 @samp{next-row} and @samp{prev-row}, @samp{next-page} and
1429 @subsubheading @value{GDBN} Command
1431 The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
1432 @samp{gdb_get_mem} memory read command.
1434 @subsubheading Example
1436 Read six bytes of memory starting at @code{bytes+6} but then offset by
1437 @code{-6} bytes. Format as three rows of two columns. One byte per
1438 word. Display each word in hex.
1442 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
1443 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
1444 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
1445 prev-page="0x0000138a",memory=@{
1446 @{addr="0x00001390",data=@{"0x00","0x01"@}@},
1447 @{addr="0x00001392",data=@{"0x02","0x03"@}@},
1448 @{addr="0x00001394",data=@{"0x04","0x05"@}@}@}
1452 Read two bytes of memory starting at address @code{shorts + 64} and
1453 display as a single word formatted in decimal.
1457 5-data-read-memory shorts+64 d 2 1 1
1458 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
1459 next-row="0x00001512",prev-row="0x0000150e",
1460 next-page="0x00001512",prev-page="0x0000150e",memory=@{
1461 @{addr="0x00001510",data=@{"128"@}@}@}
1465 Read thirty two bytes of memory starting at @code{bytes+16} and format
1466 as eight rows of four columns. Include a string encoding with @samp{x}
1467 used as the non-printable character.
1471 4-data-read-memory bytes+16 x 1 8 4 x
1472 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
1473 next-row="0x000013c0",prev-row="0x0000139c",
1474 next-page="0x000013c0",prev-page="0x00001380",memory=@{
1475 @{addr="0x000013a0",data=@{"0x10","0x11","0x12","0x13"@},ascii="xxxx"@},
1476 @{addr="0x000013a4",data=@{"0x14","0x15","0x16","0x17"@},ascii="xxxx"@},
1477 @{addr="0x000013a8",data=@{"0x18","0x19","0x1a","0x1b"@},ascii="xxxx"@},
1478 @{addr="0x000013ac",data=@{"0x1c","0x1d","0x1e","0x1f"@},ascii="xxxx"@},
1479 @{addr="0x000013b0",data=@{"0x20","0x21","0x22","0x23"@},ascii=" !\"#"@},
1480 @{addr="0x000013b4",data=@{"0x24","0x25","0x26","0x27"@},ascii="$%&'"@},
1481 @{addr="0x000013b8",data=@{"0x28","0x29","0x2a","0x2b"@},ascii="()*+"@},
1482 @{addr="0x000013bc",data=@{"0x2c","0x2d","0x2e","0x2f"@},ascii=",-./"@}@}
1486 @subheading The @code{-display-delete} Command
1487 @findex -display-delete
1489 @subsubheading Synopsis
1492 -display-delete @var{number}
1495 Delete the display @var{number}.
1497 @subsubheading @value{GDBN} Command
1499 The corresponding @value{GDBN} command is @samp{delete display}.
1501 @subsubheading Example
1505 @subheading The @code{-display-disable} Command
1506 @findex -display-disable
1508 @subsubheading Synopsis
1511 -display-disable @var{number}
1514 Disable display @var{number}.
1516 @subsubheading @value{GDBN} Command
1518 The corresponding @value{GDBN} command is @samp{disable display}.
1520 @subsubheading Example
1524 @subheading The @code{-display-enable} Command
1525 @findex -display-enable
1527 @subsubheading Synopsis
1530 -display-enable @var{number}
1533 Enable display @var{number}.
1535 @subsubheading @value{GDBN} Command
1537 The corresponding @value{GDBN} command is @samp{enable display}.
1539 @subsubheading Example
1543 @subheading The @code{-display-insert} Command
1544 @findex -display-insert
1546 @subsubheading Synopsis
1549 -display-insert @var{expression}
1552 Display @var{expression} every time the program stops.
1554 @subsubheading @value{GDBN} Command
1556 The corresponding @value{GDBN} command is @samp{display}.
1558 @subsubheading Example
1562 @subheading The @code{-display-list} Command
1563 @findex -display-list
1565 @subsubheading Synopsis
1571 List the displays. Do not show the current values.
1573 @subsubheading @value{GDBN} Command
1575 The corresponding @value{GDBN} command is @samp{info display}.
1577 @subsubheading Example
1581 @subheading The @code{-environment-cd} Command
1582 @findex -environment-cd
1584 @subsubheading Synopsis
1587 -environment-cd @var{pathdir}
1590 Set @value{GDBN}'s working directory.
1592 @subsubheading @value{GDBN} Command
1594 The corresponding @value{GDBN} command is @samp{cd}.
1596 @subsubheading Example
1600 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1606 @subheading The @code{-environment-directory} Command
1607 @findex -environment-directory
1609 @subsubheading Synopsis
1612 -environment-directory @var{pathdir}
1615 Add directory @var{pathdir} to beginning of search path for source files.
1617 @subsubheading @value{GDBN} Command
1619 The corresponding @value{GDBN} command is @samp{dir}.
1621 @subsubheading Example
1625 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1631 @subheading The @code{-environment-path} Command
1632 @findex -environment-path
1634 @subsubheading Synopsis
1637 -environment-path ( @var{pathdir} )+
1640 Add directories @var{pathdir} to beginning of search path for object files.
1642 @subsubheading @value{GDBN} Command
1644 The corresponding @value{GDBN} command is @samp{path}.
1646 @subsubheading Example
1650 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb
1656 @subheading The @code{-environment-pwd} Command
1657 @findex -environment-pwd
1659 @subsubheading Synopsis
1665 Show the current working directory.
1667 @subsubheading @value{GDBN} command
1669 The corresponding @value{GDBN} command is @samp{pwd}.
1671 @subsubheading Example
1676 ~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb.
1681 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1682 @node GDB/MI Program Control
1683 @section @sc{gdb/mi} Program control
1685 @subsubheading Program termination
1687 As a result of execution, the inferior program can run to completion, if
1688 it doesn't encounter any breakpoints. In this case the output will
1689 include an exit code, if the program has exited exceptionally.
1691 @subsubheading Examples
1694 Program exited normally:
1702 *stopped,reason="exited-normally"
1707 Program exited exceptionally:
1715 *stopped,reason="exited",exit-code="01"
1719 Another way the program can terminate is if it receives a signal such as
1720 @code{SIGINT}. In this case, @sc{gdb/mi} displays this:
1724 *stopped,reason="exited-signalled",signal-name="SIGINT",
1725 signal-meaning="Interrupt"
1729 @subheading The @code{-exec-abort} Command
1732 @subsubheading Synopsis
1738 Kill the inferior running program.
1740 @subsubheading @value{GDBN} Command
1742 The corresponding @value{GDBN} command is @samp{kill}.
1744 @subsubheading Example
1748 @subheading The @code{-exec-arguments} Command
1749 @findex -exec-arguments
1751 @subsubheading Synopsis
1754 -exec-arguments @var{args}
1757 Set the inferior program arguments, to be used in the next
1760 @subsubheading @value{GDBN} Command
1762 The corresponding @value{GDBN} command is @samp{set args}.
1764 @subsubheading Example
1767 Don't have one around.
1770 @subheading The @code{-exec-continue} Command
1771 @findex -exec-continue
1773 @subsubheading Synopsis
1779 Asynchronous command. Resumes the execution of the inferior program
1780 until a breakpoint is encountered, or until the inferior exits.
1782 @subsubheading @value{GDBN} Command
1784 The corresponding @value{GDBN} corresponding is @samp{continue}.
1786 @subsubheading Example
1793 *stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=@{@},
1794 file="hello.c",line="13"@}
1799 @subheading The @code{-exec-finish} Command
1800 @findex -exec-finish
1802 @subsubheading Synopsis
1808 Asynchronous command. Resumes the execution of the inferior program
1809 until the current function is exited. Displays the results returned by
1812 @subsubheading @value{GDBN} Command
1814 The corresponding @value{GDBN} command is @samp{finish}.
1816 @subsubheading Example
1818 Function returning @code{void}.
1825 *stopped,reason="function-finished",frame=@{func="main",args=@{@},
1826 file="hello.c",line="7"@}
1830 Function returning other than @code{void}. The name of the internal
1831 @value{GDBN} variable storing the result is printed, together with the
1838 *stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
1839 args=@{@{name="a",value="1"@},@{name="b",value="9"@}@},
1840 file="recursive2.c",line="14"@},
1841 gdb-result-var="$1",return-value="0"
1846 @subheading The @code{-exec-interrupt} Command
1847 @findex -exec-interrupt
1849 @subsubheading Synopsis
1855 Asynchronous command. Interrupts the background execution of the target.
1856 Note how the token associated with the stop message is the one for the
1857 execution command that has been interrupted. The token for the interrupt
1858 itself only appears in the @samp{^done} output. If the user is trying to
1859 interrupt a non-running program, an error message will be printed.
1861 @subsubheading @value{GDBN} Command
1863 The corresponding @value{GDBN} command is @samp{interrupt}.
1865 @subsubheading Example
1876 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
1877 frame=@{addr="0x00010140",func="foo",args=@{@},file="try.c",line="13"@}
1882 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
1887 @subheading The @code{-exec-next} Command
1890 @subsubheading Synopsis
1896 Asynchronous command. Resumes execution of the inferior program, stopping
1897 when the beginning of the next source line is reached.
1899 @subsubheading @value{GDBN} Command
1901 The corresponding @value{GDBN} command is @samp{next}.
1903 @subsubheading Example
1909 *stopped,reason="end-stepping-range",line="8",file="hello.c"
1914 @subheading The @code{-exec-next-instruction} Command
1915 @findex -exec-next-instruction
1917 @subsubheading Synopsis
1920 -exec-next-instruction
1923 Asynchronous command. Executes one machine instruction. If the
1924 instruction is a function call continues until the function returns. If
1925 the program stops at an instruction in the middle of a source line, the
1926 address will be printed as well.
1928 @subsubheading @value{GDBN} Command
1930 The corresponding @value{GDBN} command is @samp{nexti}.
1932 @subsubheading Example
1936 -exec-next-instruction
1940 *stopped,reason="end-stepping-range",
1941 addr="0x000100d4",line="5",file="hello.c"
1946 @subheading The @code{-exec-return} Command
1947 @findex -exec-return
1949 @subsubheading Synopsis
1955 Makes current function return immediately. Doesn't execute the inferior.
1956 Displays the new current frame.
1958 @subsubheading @value{GDBN} Command
1960 The corresponding @value{GDBN} command is @samp{return}.
1962 @subsubheading Example
1966 200-break-insert callee4
1967 200^done,bkpt=@{number="1",addr="0x00010734",
1968 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1973 000*stopped,reason="breakpoint-hit",bkptno="1",
1974 frame=@{func="callee4",args=@{@},
1975 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1981 111^done,frame=@{level="0 ",func="callee3",
1982 args=@{@{name="strarg",
1983 value="0x11940 \"A string argument.\""@}@},
1984 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1989 @subheading The @code{-exec-run} Command
1992 @subsubheading Synopsis
1998 Asynchronous command. Starts execution of the inferior from the
1999 beginning. The inferior executes until either a breakpoint is
2000 encountered or the program exits.
2002 @subsubheading @value{GDBN} Command
2004 The corresponding @value{GDBN} command is @samp{run}.
2006 @subsubheading Example
2011 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
2016 *stopped,reason="breakpoint-hit",bkptno="1",
2017 frame=@{func="main",args=@{@},file="recursive2.c",line="4"@}
2022 @subheading The @code{-exec-show-arguments} Command
2023 @findex -exec-show-arguments
2025 @subsubheading Synopsis
2028 -exec-show-arguments
2031 Print the arguments of the program.
2033 @subsubheading @value{GDBN} Command
2035 The corresponding @value{GDBN} command is @samp{show args}.
2037 @subsubheading Example
2040 @c @subheading -exec-signal
2042 @subheading The @code{-exec-step} Command
2045 @subsubheading Synopsis
2051 Asynchronous command. Resumes execution of the inferior program, stopping
2052 when the beginning of the next source line is reached, if the next
2053 source line is not a function call. If it is, stop at the first
2054 instruction of the called function.
2056 @subsubheading @value{GDBN} Command
2058 The corresponding @value{GDBN} command is @samp{step}.
2060 @subsubheading Example
2062 Stepping into a function:
2068 *stopped,reason="end-stepping-range",
2069 frame=@{func="foo",args=@{@{name="a",value="10"@},
2070 @{name="b",value="0"@}@},file="recursive2.c",line="11"@}
2080 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
2085 @subheading The @code{-exec-step-instruction} Command
2086 @findex -exec-step-instruction
2088 @subsubheading Synopsis
2091 -exec-step-instruction
2094 Asynchronous command. Resumes the inferior which executes one machine
2095 instruction. The output, once @value{GDBN} has stopped, will vary depending on
2096 whether we have stopped in the middle of a source line or not. In the
2097 former case, the address at which the program stopped will be printed as
2100 @subsubheading @value{GDBN} Command
2102 The corresponding @value{GDBN} command is @samp{stepi}.
2104 @subsubheading Example
2108 -exec-step-instruction
2112 *stopped,reason="end-stepping-range",
2113 frame=@{func="foo",args=@{@},file="try.c",line="10"@}
2115 -exec-step-instruction
2119 *stopped,reason="end-stepping-range",
2120 frame=@{addr="0x000100f4",func="foo",args=@{@},file="try.c",line="10"@}
2125 @subheading The @code{-exec-until} Command
2128 @subsubheading Synopsis
2131 -exec-until [ @var{location} ]
2134 Asynchronous command. Executes the inferior until the @var{location}
2135 specified in the argument is reached. If there is no argument, the inferior
2136 executes until a source line greater than the current one is reached.
2137 The reason for stopping in this case will be @samp{location-reached}.
2139 @subsubheading @value{GDBN} Command
2141 The corresponding @value{GDBN} command is @samp{until}.
2143 @subsubheading Example
2147 -exec-until recursive2.c:6
2151 *stopped,reason="location-reached",frame=@{func="main",args=@{@},
2152 file="recursive2.c",line="6"@}
2157 @subheading -file-clear
2158 Is this going away????
2162 @subheading The @code{-file-exec-and-symbols} Command
2163 @findex -file-exec-and-symbols
2165 @subsubheading Synopsis
2168 -file-exec-and-symbols @var{file}
2171 Specify the executable file to be debugged. This file is the one from
2172 which the symbol table is also read. If no file is specified, the
2173 command clears the executable and symbol information. If breakpoints
2174 are set when using this command with no arguments, @value{GDBN} will produce
2175 error messages. Otherwise, no output is produced, except a completion
2178 @subsubheading @value{GDBN} Command
2180 The corresponding @value{GDBN} command is @samp{file}.
2182 @subsubheading Example
2186 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2192 @subheading The @code{-file-exec-file} Command
2193 @findex -file-exec-file
2195 @subsubheading Synopsis
2198 -file-exec-file @var{file}
2201 Specify the executable file to be debugged. Unlike
2202 @samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
2203 from this file. If used without argument, @value{GDBN} clears the information
2204 about the executable file. No output is produced, except a completion
2207 @subsubheading @value{GDBN} Command
2209 The corresponding @value{GDBN} command is @samp{exec-file}.
2211 @subsubheading Example
2215 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2221 @subheading The @code{-file-list-exec-sections} Command
2222 @findex -file-list-exec-sections
2224 @subsubheading Synopsis
2227 -file-list-exec-sections
2230 List the sections of the current executable file.
2232 @subsubheading @value{GDBN} Command
2234 The @value{GDBN} command @samp{info file} shows, among the rest, the same
2235 information as this command. @code{gdbtk} has a corresponding command
2236 @samp{gdb_load_info}.
2238 @subsubheading Example
2242 @subheading The @code{-file-list-exec-source-files} Command
2243 @findex -file-list-exec-source-files
2245 @subsubheading Synopsis
2248 -file-list-exec-source-files
2251 List the source files for the current executable.
2253 @subsubheading @value{GDBN} Command
2255 There's no @value{GDBN} command which directly corresponds to this one.
2256 @code{gdbtk} has an analogous command @samp{gdb_listfiles}.
2258 @subsubheading Example
2262 @subheading The @code{-file-list-shared-libraries} Command
2263 @findex -file-list-shared-libraries
2265 @subsubheading Synopsis
2268 -file-list-shared-libraries
2271 List the shared libraries in the program.
2273 @subsubheading @value{GDBN} Command
2275 The corresponding @value{GDBN} command is @samp{info shared}.
2277 @subsubheading Example
2281 @subheading The @code{-file-list-symbol-files} Command
2282 @findex -file-list-symbol-files
2284 @subsubheading Synopsis
2287 -file-list-symbol-files
2292 @subsubheading @value{GDBN} Command
2294 The corresponding @value{GDBN} command is @samp{info file} (part of it).
2296 @subsubheading Example
2300 @subheading The @code{-file-symbol-file} Command
2301 @findex -file-symbol-file
2303 @subsubheading Synopsis
2306 -file-symbol-file @var{file}
2309 Read symbol table info from the specified @var{file} argument. When
2310 used without arguments, clears @value{GDBN}'s symbol table info. No output is
2311 produced, except for a completion notification.
2313 @subsubheading @value{GDBN} Command
2315 The corresponding @value{GDBN} command is @samp{symbol-file}.
2317 @subsubheading Example
2321 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2326 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2327 @node GDB/MI Miscellaneous Commands
2328 @section Miscellaneous @value{GDBN} commands in @sc{gdb/mi}
2330 @c @subheading -gdb-complete
2332 @subheading The @code{-gdb-exit} Command
2335 @subsubheading Synopsis
2341 Exit @value{GDBN} immediately.
2343 @subsubheading @value{GDBN} Command
2345 Approximately corresponds to @samp{quit}.
2347 @subsubheading Example
2354 @subheading The @code{-gdb-set} Command
2357 @subsubheading Synopsis
2363 Set an internal @value{GDBN} variable.
2364 @c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
2366 @subsubheading @value{GDBN} Command
2368 The corresponding @value{GDBN} command is @samp{set}.
2370 @subsubheading Example
2380 @subheading The @code{-gdb-show} Command
2383 @subsubheading Synopsis
2389 Show the current value of a @value{GDBN} variable.
2391 @subsubheading @value{GDBN} command
2393 The corresponding @value{GDBN} command is @samp{show}.
2395 @subsubheading Example
2404 @c @subheading -gdb-source
2407 @subheading The @code{-gdb-version} Command
2408 @findex -gdb-version
2410 @subsubheading Synopsis
2416 Show version information for @value{GDBN}. Used mostly in testing.
2418 @subsubheading @value{GDBN} Command
2420 There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this
2421 information when you start an interactive session.
2423 @subsubheading Example
2425 @c This example modifies the actual output from GDB to avoid overfull
2431 ~Copyright 2000 Free Software Foundation, Inc.
2432 ~GDB is free software, covered by the GNU General Public License, and
2433 ~you are welcome to change it and/or distribute copies of it under
2434 ~ certain conditions.
2435 ~Type "show copying" to see the conditions.
2436 ~There is absolutely no warranty for GDB. Type "show warranty" for
2438 ~This GDB was configured as
2439 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
2445 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2446 @node GDB/MI Kod Commands
2447 @section @sc{gdb/mi} Kod Commands
2449 The Kod commands are not implemented.
2451 @c @subheading -kod-info
2453 @c @subheading -kod-list
2455 @c @subheading -kod-list-object-types
2457 @c @subheading -kod-show
2459 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2460 @node GDB/MI Memory Overlay Commands
2461 @section @sc{gdb/mi} Memory Overlay Commands
2463 The memory overlay commands are not implemented.
2465 @c @subheading -overlay-auto
2467 @c @subheading -overlay-list-mapping-state
2469 @c @subheading -overlay-list-overlays
2471 @c @subheading -overlay-map
2473 @c @subheading -overlay-off
2475 @c @subheading -overlay-on
2477 @c @subheading -overlay-unmap
2479 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2480 @node GDB/MI Signal Handling Commands
2481 @section @sc{gdb/mi} Signal Handling Commands
2483 Signal handling commands are not implemented.
2485 @c @subheading -signal-handle
2487 @c @subheading -signal-list-handle-actions
2489 @c @subheading -signal-list-signal-types
2493 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2494 @node GDB/MI Stack Manipulation
2495 @section Stack manipulation commands in @sc{gdb/mi}
2498 @subheading The @code{-stack-info-frame} Command
2499 @findex -stack-info-frame
2501 @subsubheading Synopsis
2507 Get info on the current frame.
2509 @subsubheading @value{GDBN} Command
2511 The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
2512 (without arguments).
2514 @subsubheading Example
2517 @subheading The @code{-stack-info-depth} Command
2518 @findex -stack-info-depth
2520 @subsubheading Synopsis
2523 -stack-info-depth [ @var{max-depth} ]
2526 Return the depth of the stack. If the integer argument @var{max-depth}
2527 is specified, do not count beyond @var{max-depth} frames.
2529 @subsubheading @value{GDBN} Command
2531 There's no equivalent @value{GDBN} command.
2533 @subsubheading Example
2535 For a stack with frame levels 0 through 11:
2545 -stack-info-depth 12
2548 -stack-info-depth 11
2551 -stack-info-depth 13
2556 @subheading The @code{-stack-list-arguments} Command
2557 @findex -stack-list-arguments
2559 @subsubheading Synopsis
2562 -stack-list-arguments @var{show-values}
2563 [ @var{low-frame} @var{high-frame} ]
2566 Display a list of the arguments for the frames between @var{low-frame}
2567 and @var{high-frame} (inclusive). If @var{low-frame} and
2568 @var{high-frame} are not provided, list the arguments for the whole call
2571 The @var{show-values} argument must have a value of 0 or 1. A value of
2572 0 means that only the names of the arguments are listed, a value of 1
2573 means that both names and values of the arguments are printed.
2575 @subsubheading @value{GDBN} Command
2577 @value{GDBN} does not have an equivalent command. @code{gdbtk} has a
2578 @samp{gdb_get_args} command which partially overlaps with the
2579 functionality of @samp{-stack-list-arguments}.
2581 @subsubheading Example
2588 frame=@{level="0 ",addr="0x00010734",func="callee4",
2589 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
2590 frame=@{level="1 ",addr="0x0001076c",func="callee3",
2591 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
2592 frame=@{level="2 ",addr="0x0001078c",func="callee2",
2593 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
2594 frame=@{level="3 ",addr="0x000107b4",func="callee1",
2595 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
2596 frame=@{level="4 ",addr="0x000107e0",func="main",
2597 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}@}
2599 -stack-list-arguments 0
2602 frame=@{level="0",args=@{@}@},
2603 frame=@{level="1",args=@{name="strarg"@}@},
2604 frame=@{level="2",args=@{name="intarg",name="strarg"@}@},
2605 frame=@{level="3",args=@{name="intarg",name="strarg",name="fltarg"@}@},
2606 frame=@{level="4",args=@{@}@}@}
2608 -stack-list-arguments 1
2611 frame=@{level="0",args=@{@}@},
2613 args=@{@{name="strarg",value="0x11940 \"A string argument.\""@}@}@},
2614 frame=@{level="2",args=@{
2615 @{name="intarg",value="2"@},
2616 @{name="strarg",value="0x11940 \"A string argument.\""@}@}@},
2617 @{frame=@{level="3",args=@{
2618 @{name="intarg",value="2"@},
2619 @{name="strarg",value="0x11940 \"A string argument.\""@},
2620 @{name="fltarg",value="3.5"@}@}@},
2621 frame=@{level="4",args=@{@}@}@}
2623 -stack-list-arguments 0 2 2
2624 ^done,stack-args=@{frame=@{level="2",args=@{name="intarg",name="strarg"@}@}@}
2626 -stack-list-arguments 1 2 2
2627 ^done,stack-args=@{frame=@{level="2",
2628 args=@{@{name="intarg",value="2"@},
2629 @{name="strarg",value="0x11940 \"A string argument.\""@}@}@}@}
2633 @c @subheading -stack-list-exception-handlers
2636 @subheading The @code{-stack-list-frames} Command
2637 @findex -stack-list-frames
2639 @subsubheading Synopsis
2642 -stack-list-frames [ @var{low-frame} @var{high-frame} ]
2645 List the frames currently on the stack. For each frame it displays the
2650 The frame number, 0 being the topmost frame, i.e. the innermost function.
2652 The @code{$pc} value for that frame.
2656 File name of the source file where the function lives.
2658 Line number corresponding to the @code{$pc}.
2661 If invoked without arguments, this command prints a backtrace for the
2662 whole stack. If given two integer arguments, it shows the frames whose
2663 levels are between the two arguments (inclusive). If the two arguments
2664 are equal, it shows the single frame at the corresponding level.
2666 @subsubheading @value{GDBN} Command
2668 The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
2670 @subsubheading Example
2672 Full stack backtrace:
2678 @{frame=@{level="0 ",addr="0x0001076c",func="foo",
2679 file="recursive2.c",line="11"@},
2680 frame=@{level="1 ",addr="0x000107a4",func="foo",
2681 file="recursive2.c",line="14"@},
2682 frame=@{level="2 ",addr="0x000107a4",func="foo",
2683 file="recursive2.c",line="14"@},
2684 frame=@{level="3 ",addr="0x000107a4",func="foo",
2685 file="recursive2.c",line="14"@},
2686 frame=@{level="4 ",addr="0x000107a4",func="foo",
2687 file="recursive2.c",line="14"@},
2688 frame=@{level="5 ",addr="0x000107a4",func="foo",
2689 file="recursive2.c",line="14"@},
2690 frame=@{level="6 ",addr="0x000107a4",func="foo",
2691 file="recursive2.c",line="14"@},
2692 frame=@{level="7 ",addr="0x000107a4",func="foo",
2693 file="recursive2.c",line="14"@},
2694 frame=@{level="8 ",addr="0x000107a4",func="foo",
2695 file="recursive2.c",line="14"@},
2696 frame=@{level="9 ",addr="0x000107a4",func="foo",
2697 file="recursive2.c",line="14"@},
2698 frame=@{level="10",addr="0x000107a4",func="foo",
2699 file="recursive2.c",line="14"@},
2700 frame=@{level="11",addr="0x00010738",func="main",
2701 file="recursive2.c",line="4"@}@}
2705 Show frames between @var{low_frame} and @var{high_frame}:
2709 -stack-list-frames 3 5
2711 @{frame=@{level="3 ",addr="0x000107a4",func="foo",
2712 file="recursive2.c",line="14"@},
2713 frame=@{level="4 ",addr="0x000107a4",func="foo",
2714 file="recursive2.c",line="14"@},
2715 frame=@{level="5 ",addr="0x000107a4",func="foo",
2716 file="recursive2.c",line="14"@}@}
2720 Show a single frame:
2724 -stack-list-frames 3 3
2726 @{frame=@{level="3 ",addr="0x000107a4",func="foo",
2727 file="recursive2.c",line="14"@}@}
2732 @subheading The @code{-stack-list-locals} Command
2733 @findex -stack-list-locals
2735 @subsubheading Synopsis
2738 -stack-list-locals @var{print-values}
2741 Display the local variable names for the current frame. With an
2742 argument of 0 prints only the names of the variables, with argument of 1
2743 prints also their values.
2745 @subsubheading @value{GDBN} Command
2747 @samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
2749 @subsubheading Example
2753 -stack-list-locals 0
2754 ^done,locals=@{name="A",name="B",name="C"@}
2756 -stack-list-locals 1
2757 ^done,locals=@{@{name="A",value="1"@},@{name="B",value="2"@},
2758 @{name="C",value="3"@}@}
2763 @subheading The @code{-stack-select-frame} Command
2764 @findex -stack-select-frame
2766 @subsubheading Synopsis
2769 -stack-select-frame @var{framenum}
2772 Change the current frame. Select a different frame @var{framenum} on
2775 @subsubheading @value{GDBN} Command
2777 The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
2778 @samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
2780 @subsubheading Example
2784 -stack-select-frame 2
2789 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2790 @node GDB/MI Symbol Query
2791 @section @sc{gdb/mi} Symbol Query Commands
2794 @subheading The @code{-symbol-info-address} Command
2795 @findex -symbol-info-address
2797 @subsubheading Synopsis
2800 -symbol-info-address @var{symbol}
2803 Describe where @var{symbol} is stored.
2805 @subsubheading @value{GDBN} Command
2807 The corresponding @value{GDBN} command is @samp{info address}.
2809 @subsubheading Example
2813 @subheading The @code{-symbol-info-file} Command
2814 @findex -symbol-info-file
2816 @subsubheading Synopsis
2822 Show the file for the symbol.
2824 @subsubheading @value{GDBN} Command
2826 There's no equivalent @value{GDBN} command. @code{gdbtk} has
2827 @samp{gdb_find_file}.
2829 @subsubheading Example
2833 @subheading The @code{-symbol-info-function} Command
2834 @findex -symbol-info-function
2836 @subsubheading Synopsis
2839 -symbol-info-function
2842 Show which function the symbol lives in.
2844 @subsubheading @value{GDBN} Command
2846 @samp{gdb_get_function} in @code{gdbtk}.
2848 @subsubheading Example
2852 @subheading The @code{-symbol-info-line} Command
2853 @findex -symbol-info-line
2855 @subsubheading Synopsis
2861 Show the core addresses of the code for a source line.
2863 @subsubheading @value{GDBN} Command
2865 The corresponding @value{GDBN} comamnd is @samp{info line}.
2866 @code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
2868 @subsubheading Example
2872 @subheading The @code{-symbol-info-symbol} Command
2873 @findex -symbol-info-symbol
2875 @subsubheading Synopsis
2878 -symbol-info-symbol @var{addr}
2881 Describe what symbol is at location @var{addr}.
2883 @subsubheading @value{GDBN} Command
2885 The corresponding @value{GDBN} command is @samp{info symbol}.
2887 @subsubheading Example
2891 @subheading The @code{-symbol-list-functions} Command
2892 @findex -symbol-list-functions
2894 @subsubheading Synopsis
2897 -symbol-list-functions
2900 List the functions in the executable.
2902 @subsubheading @value{GDBN} Command
2904 @samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
2905 @samp{gdb_search} in @code{gdbtk}.
2907 @subsubheading Example
2911 @subheading The @code{-symbol-list-types} Command
2912 @findex -symbol-list-types
2914 @subsubheading Synopsis
2920 List all the type names.
2922 @subsubheading @value{GDBN} Command
2924 The corresponding commands are @samp{info types} in @value{GDBN},
2925 @samp{gdb_search} in @code{gdbtk}.
2927 @subsubheading Example
2931 @subheading The @code{-symbol-list-variables} Command
2932 @findex -symbol-list-variables
2934 @subsubheading Synopsis
2937 -symbol-list-variables
2940 List all the global and static variable names.
2942 @subsubheading @value{GDBN} Command
2944 @samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
2946 @subsubheading Example
2950 @subheading The @code{-symbol-locate} Command
2951 @findex -symbol-locate
2953 @subsubheading Synopsis
2959 @subsubheading @value{GDBN} Command
2961 @samp{gdb_loc} in @code{gdbtk}.
2963 @subsubheading Example
2967 @subheading The @code{-symbol-type} Command
2968 @findex -symbol-type
2970 @subsubheading Synopsis
2973 -symbol-type @var{variable}
2976 Show type of @var{variable}.
2978 @subsubheading @value{GDBN} Command
2980 The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
2981 @samp{gdb_obj_variable}.
2983 @subsubheading Example
2987 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2988 @node GDB/MI Target Manipulation
2989 @section @sc{gdb/mi} Target Manipulation Commands
2992 @subheading The @code{-target-attach} Command
2993 @findex -target-attach
2995 @subsubheading Synopsis
2998 -target-attach @var{pid} | @var{file}
3001 Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
3003 @subsubheading @value{GDBN} command
3005 The corresponding @value{GDBN} command is @samp{attach}.
3007 @subsubheading Example
3011 @subheading The @code{-target-compare-sections} Command
3012 @findex -target-compare-sections
3014 @subsubheading Synopsis
3017 -target-compare-sections [ @var{section} ]
3020 Compare data of section @var{section} on target to the exec file.
3021 Without the argument, all sections are compared.
3023 @subsubheading @value{GDBN} Command
3025 The @value{GDBN} equivalent is @samp{compare-sections}.
3027 @subsubheading Example
3031 @subheading The @code{-target-detach} Command
3032 @findex -target-detach
3034 @subsubheading Synopsis
3040 Disconnect from the remote target. There's no output.
3042 @subsubheading @value{GDBN} command
3044 The corresponding @value{GDBN} command is @samp{detach}.
3046 @subsubheading Example
3056 @subheading The @code{-target-download} Command
3057 @findex -target-download
3059 @subsubheading Synopsis
3065 Loads the executable onto the remote target.
3066 It prints out an update message every half second, which includes the fields:
3070 The name of the section.
3072 The size of what has been sent so far for that section.
3074 The size of the section.
3076 The total size of what was sent so far (the current and the previous sections).
3078 The size of the overall executable to download.
3082 Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
3083 @sc{gdb/mi} Output Syntax}).
3085 In addition, it prints the name and size of the sections, as they are
3086 downloaded. These messages include the following fields:
3090 The name of the section.
3092 The size of the section.
3094 The size of the overall executable to download.
3098 At the end, a summary is printed.
3100 @subsubheading @value{GDBN} Command
3102 The corresponding @value{GDBN} command is @samp{load}.
3104 @subsubheading Example
3106 Note: each status message appears on a single line. Here the messages
3107 have been broken down so that they can fit onto a page.
3112 +download,@{section=".text",section-size="6668",total-size="9880"@}
3113 +download,@{section=".text",section-sent="512",section-size="6668",
3114 total-sent="512",total-size="9880"@}
3115 +download,@{section=".text",section-sent="1024",section-size="6668",
3116 total-sent="1024",total-size="9880"@}
3117 +download,@{section=".text",section-sent="1536",section-size="6668",
3118 total-sent="1536",total-size="9880"@}
3119 +download,@{section=".text",section-sent="2048",section-size="6668",
3120 total-sent="2048",total-size="9880"@}
3121 +download,@{section=".text",section-sent="2560",section-size="6668",
3122 total-sent="2560",total-size="9880"@}
3123 +download,@{section=".text",section-sent="3072",section-size="6668",
3124 total-sent="3072",total-size="9880"@}
3125 +download,@{section=".text",section-sent="3584",section-size="6668",
3126 total-sent="3584",total-size="9880"@}
3127 +download,@{section=".text",section-sent="4096",section-size="6668",
3128 total-sent="4096",total-size="9880"@}
3129 +download,@{section=".text",section-sent="4608",section-size="6668",
3130 total-sent="4608",total-size="9880"@}
3131 +download,@{section=".text",section-sent="5120",section-size="6668",
3132 total-sent="5120",total-size="9880"@}
3133 +download,@{section=".text",section-sent="5632",section-size="6668",
3134 total-sent="5632",total-size="9880"@}
3135 +download,@{section=".text",section-sent="6144",section-size="6668",
3136 total-sent="6144",total-size="9880"@}
3137 +download,@{section=".text",section-sent="6656",section-size="6668",
3138 total-sent="6656",total-size="9880"@}
3139 +download,@{section=".init",section-size="28",total-size="9880"@}
3140 +download,@{section=".fini",section-size="28",total-size="9880"@}
3141 +download,@{section=".data",section-size="3156",total-size="9880"@}
3142 +download,@{section=".data",section-sent="512",section-size="3156",
3143 total-sent="7236",total-size="9880"@}
3144 +download,@{section=".data",section-sent="1024",section-size="3156",
3145 total-sent="7748",total-size="9880"@}
3146 +download,@{section=".data",section-sent="1536",section-size="3156",
3147 total-sent="8260",total-size="9880"@}
3148 +download,@{section=".data",section-sent="2048",section-size="3156",
3149 total-sent="8772",total-size="9880"@}
3150 +download,@{section=".data",section-sent="2560",section-size="3156",
3151 total-sent="9284",total-size="9880"@}
3152 +download,@{section=".data",section-sent="3072",section-size="3156",
3153 total-sent="9796",total-size="9880"@}
3154 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
3160 @subheading The @code{-target-exec-status} Command
3161 @findex -target-exec-status
3163 @subsubheading Synopsis
3169 Provide information on the state of the target (whether it is running or
3172 @subsubheading @value{GDBN} Command
3174 There's no equivalent @value{GDBN} command.
3176 @subsubheading Example
3180 @subheading The @code{-target-list-available-targets} Command
3181 @findex -target-list-available-targets
3183 @subsubheading Synopsis
3186 -target-list-available-targets
3189 List the possible targets to connect to.
3191 @subsubheading @value{GDBN} Command
3193 The corresponding @value{GDBN} command is @samp{help target}.
3195 @subsubheading Example
3199 @subheading The @code{-target-list-current-targets} Command
3200 @findex -target-list-current-targets
3202 @subsubheading Synopsis
3205 -target-list-current-targets
3208 Describe the current target.
3210 @subsubheading @value{GDBN} Command
3212 The corresponding information is printed by @samp{info file} (among
3215 @subsubheading Example
3219 @subheading The @code{-target-list-parameters} Command
3220 @findex -target-list-parameters
3222 @subsubheading Synopsis
3225 -target-list-parameters
3230 @subsubheading @value{GDBN} Command
3234 @subsubheading Example
3238 @subheading The @code{-target-select} Command
3239 @findex -target-select
3241 @subsubheading Synopsis
3244 -target-select @var{type} @var{parameters @dots{}}
3247 Connect @value{GDBN} to the remote target. This command takes two args:
3251 The type of target, for instance @samp{async}, @samp{remote}, etc.
3252 @item @var{parameters}
3253 Device names, host names and the like. @xref{Target Commands, ,
3254 Commands for managing targets}, for more details.
3257 The output is a connection notification, followed by the address at
3258 which the target program is, in the following form:
3261 ^connected,addr="@var{address}",func="@var{function name}",
3262 args=@{@var{arg list}@}
3265 @subsubheading @value{GDBN} Command
3267 The corresponding @value{GDBN} command is @samp{target}.
3269 @subsubheading Example
3273 -target-select async /dev/ttya
3274 ^connected,addr="0xfe00a300",func="??",args=@{@}
3278 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3279 @node GDB/MI Thread Commands
3280 @section @sc{gdb/mi} Thread Commands
3283 @subheading The @code{-thread-info} Command
3284 @findex -thread-info
3286 @subsubheading Synopsis
3292 @subsubheading @value{GDBN} command
3296 @subsubheading Example
3300 @subheading The @code{-thread-list-all-threads} Command
3301 @findex -thread-list-all-threads
3303 @subsubheading Synopsis
3306 -thread-list-all-threads
3309 @subsubheading @value{GDBN} Command
3311 The equivalent @value{GDBN} command is @samp{info threads}.
3313 @subsubheading Example
3317 @subheading The @code{-thread-list-ids} Command
3318 @findex -thread-list-ids
3320 @subsubheading Synopsis
3326 Produces a list of the currently known @value{GDBN} thread ids. At the
3327 end of the list it also prints the total number of such threads.
3329 @subsubheading @value{GDBN} Command
3331 Part of @samp{info threads} supplies the same information.
3333 @subsubheading Example
3335 No threads present, besides the main process:
3340 ^done,thread-ids=@{@},number-of-threads="0"
3350 ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3351 number-of-threads="3"
3356 @subheading The @code{-thread-select} Command
3357 @findex -thread-select
3359 @subsubheading Synopsis
3362 -thread-select @var{threadnum}
3365 Make @var{threadnum} the current thread. It prints the number of the new
3366 current thread, and the topmost frame for that thread.
3368 @subsubheading @value{GDBN} Command
3370 The corresponding @value{GDBN} command is @samp{thread}.
3372 @subsubheading Example
3379 *stopped,reason="end-stepping-range",thread-id="2",line="187",
3380 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
3384 thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3385 number-of-threads="3"
3388 ^done,new-thread-id="3",
3389 frame=@{level="0 ",func="vprintf",
3390 args=@{@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
3391 @{name="arg",value="0x2"@}@},file="vprintf.c",line="31"@}
3395 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3396 @node GDB/MI Tracepoint Commands
3397 @section @sc{gdb/mi} Tracepoint Commands
3399 The tracepoint commands are not yet implemented.
3401 @c @subheading -trace-actions
3403 @c @subheading -trace-delete
3405 @c @subheading -trace-disable
3407 @c @subheading -trace-dump
3409 @c @subheading -trace-enable
3411 @c @subheading -trace-exists
3413 @c @subheading -trace-find
3415 @c @subheading -trace-frame-number
3417 @c @subheading -trace-info
3419 @c @subheading -trace-insert
3421 @c @subheading -trace-list
3423 @c @subheading -trace-pass-count
3425 @c @subheading -trace-save
3427 @c @subheading -trace-start
3429 @c @subheading -trace-stop
3432 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3433 @node GDB/MI Variable Objects
3434 @section @sc{gdb/mi} Variable Objects
3437 @subheading Motivation for Variable Objects in @sc{gdb/mi}
3439 For the implementation of a variable debugger window (locals, watched
3440 expressions, etc.), we are proposing the adaptation of the existing code
3441 used by @code{Insight}.
3443 The two main reasons for that are:
3447 It has been proven in practice (it is already on its second generation).
3450 It will shorten development time (needless to say how important it is
3454 The original interface was designed to be used by Tcl code, so it was
3455 slightly changed so it could be used through @sc{gdb/mi}. This section
3456 describes the @sc{gdb/mi} operations that will be available and gives some
3457 hints about their use.
3459 @emph{Note}: In addition to the set of operations described here, we
3460 expect the @sc{gui} implementation of a variable window to require, at
3461 least, the following operations:
3464 @item @code{-gdb-show} @code{output-radix}
3465 @item @code{-stack-list-arguments}
3466 @item @code{-stack-list-locals}
3467 @item @code{-stack-select-frame}
3470 @subheading Introduction to Variable Objects in @sc{gdb/mi}
3472 @cindex variable objects in @sc{gdb/mi}
3473 The basic idea behind variable objects is the creation of a named object
3474 to represent a variable, an expression, a memory location or even a CPU
3475 register. For each object created, a set of operations is available for
3476 examining or changing its properties.
3478 Furthermore, complex data types, such as C structures, are represented
3479 in a tree format. For instance, the @code{struct} type variable is the
3480 root and the children will represent the struct members. If a child
3481 is itself of a complex type, it will also have children of its own.
3482 Appropriate language differences are handled for C, C@t{++} and Java.
3484 When returning the actual values of the objects, this facility allows
3485 for the individual selection of the display format used in the result
3486 creation. It can be chosen among: binary, decimal, hexadecimal, octal
3487 and natural. Natural refers to a default format automatically
3488 chosen based on the variable type (like decimal for an @code{int}, hex
3489 for pointers, etc.).
3491 The following is the complete set of @sc{gdb/mi} operations defined to
3492 access this functionality:
3494 @multitable @columnfractions .4 .6
3495 @item @strong{Operation}
3496 @tab @strong{Description}
3498 @item @code{-var-create}
3499 @tab create a variable object
3500 @item @code{-var-delete}
3501 @tab delete the variable object and its children
3502 @item @code{-var-set-format}
3503 @tab set the display format of this variable
3504 @item @code{-var-show-format}
3505 @tab show the display format of this variable
3506 @item @code{-var-info-num-children}
3507 @tab tells how many children this object has
3508 @item @code{-var-list-children}
3509 @tab return a list of the object's children
3510 @item @code{-var-info-type}
3511 @tab show the type of this variable object
3512 @item @code{-var-info-expression}
3513 @tab print what this variable object represents
3514 @item @code{-var-show-attributes}
3515 @tab is this variable editable? does it exist here?
3516 @item @code{-var-evaluate-expression}
3517 @tab get the value of this variable
3518 @item @code{-var-assign}
3519 @tab set the value of this variable
3520 @item @code{-var-update}
3521 @tab update the variable and its children
3524 In the next subsection we describe each operation in detail and suggest
3527 @subheading Description And Use of Operations on Variable Objects
3529 @subheading The @code{-var-create} Command
3532 @subsubheading Synopsis
3535 -var-create @{@var{name} | "-"@}
3536 @{@var{frame-addr} | "*"@} @var{expression}
3539 This operation creates a variable object, which allows the monitoring of
3540 a variable, the result of an expression, a memory cell or a CPU
3543 The @var{name} parameter is the string by which the object can be
3544 referenced. It must be unique. If @samp{-} is specified, the varobj
3545 system will generate a string ``varNNNNNN'' automatically. It will be
3546 unique provided that one does not specify @var{name} on that format.
3547 The command fails if a duplicate name is found.
3549 The frame under which the expression should be evaluated can be
3550 specified by @var{frame-addr}. A @samp{*} indicates that the current
3551 frame should be used.
3553 @var{expression} is any expression valid on the current language set (must not
3554 begin with a @samp{*}), or one of the following:
3558 @samp{*@var{addr}}, where @var{addr} is the address of a memory cell
3561 @samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
3564 @samp{$@var{regname}} --- a CPU register name
3567 @subsubheading Result
3569 This operation returns the name, number of children and the type of the
3570 object created. Type is returned as a string as the ones generated by
3571 the @value{GDBN} CLI:
3574 name="@var{name}",numchild="N",type="@var{type}"
3578 @subheading The @code{-var-delete} Command
3581 @subsubheading Synopsis
3584 -var-delete @var{name}
3587 Deletes a previously created variable object and all of its children.
3589 Returns an error if the object @var{name} is not found.
3592 @subheading The @code{-var-set-format} Command
3593 @findex -var-set-format
3595 @subsubheading Synopsis
3598 -var-set-format @var{name} @var{format-spec}
3601 Sets the output format for the value of the object @var{name} to be
3604 The syntax for the @var{format-spec} is as follows:
3607 @var{format-spec} @expansion{}
3608 @{binary | decimal | hexadecimal | octal | natural@}
3612 @subheading The @code{-var-show-format} Command
3613 @findex -var-show-format
3615 @subsubheading Synopsis
3618 -var-show-format @var{name}
3621 Returns the format used to display the value of the object @var{name}.
3624 @var{format} @expansion{}
3629 @subheading The @code{-var-info-num-children} Command
3630 @findex -var-info-num-children
3632 @subsubheading Synopsis
3635 -var-info-num-children @var{name}
3638 Returns the number of children of a variable object @var{name}:
3645 @subheading The @code{-var-list-children} Command
3646 @findex -var-list-children
3648 @subsubheading Synopsis
3651 -var-list-children @var{name}
3654 Returns a list of the children of the specified variable object:
3657 numchild=@var{n},children=@{@{name=@var{name},
3658 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}@}
3662 @subheading The @code{-var-info-type} Command
3663 @findex -var-info-type
3665 @subsubheading Synopsis
3668 -var-info-type @var{name}
3671 Returns the type of the specified variable @var{name}. The type is
3672 returned as a string in the same format as it is output by the
3680 @subheading The @code{-var-info-expression} Command
3681 @findex -var-info-expression
3683 @subsubheading Synopsis
3686 -var-info-expression @var{name}
3689 Returns what is represented by the variable object @var{name}:
3692 lang=@var{lang-spec},exp=@var{expression}
3696 where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
3698 @subheading The @code{-var-show-attributes} Command
3699 @findex -var-show-attributes
3701 @subsubheading Synopsis
3704 -var-show-attributes @var{name}
3707 List attributes of the specified variable object @var{name}:
3710 status=@var{attr} [ ( ,@var{attr} )* ]
3714 where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
3716 @subheading The @code{-var-evaluate-expression} Command
3717 @findex -var-evaluate-expression
3719 @subsubheading Synopsis
3722 -var-evaluate-expression @var{name}
3725 Evaluates the expression that is represented by the specified variable
3726 object and returns its value as a string in the current format specified
3733 @subheading The @code{-var-assign} Command
3736 @subsubheading Synopsis
3739 -var-assign @var{name} @var{expression}
3742 Assigns the value of @var{expression} to the variable object specified
3743 by @var{name}. The object must be @samp{editable}.
3745 @subheading The @code{-var-update} Command
3748 @subsubheading Synopsis
3751 -var-update @{@var{name} | "*"@}
3754 Update the value of the variable object @var{name} by evaluating its
3755 expression after fetching all the new values from memory or registers.
3756 A @samp{*} causes all existing variable objects to be updated.
3759 @c change-log-default-name: "ChangeLog-mi"