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}.
301 All output sequences end in a single line containing a period.
304 The @code{@var{token}} is from the corresponding request. If an execution
305 command is interrupted by the @samp{-exec-interrupt} command, the
306 @var{token} associated with the @samp{*stopped} message is the one of the
307 original execution command, not the one of the interrupt command.
310 @cindex status output in @sc{gdb/mi}
311 @var{status-async-output} contains on-going status information about the
312 progress of a slow operation. It can be discarded. All status output is
313 prefixed by @samp{+}.
316 @cindex async output in @sc{gdb/mi}
317 @var{exec-async-output} contains asynchronous state change on the target
318 (stopped, started, disappeared). All async output is prefixed by
322 @cindex notify output in @sc{gdb/mi}
323 @var{notify-async-output} contains supplementary information that the
324 client should handle (e.g., a new breakpoint information). All notify
325 output is prefixed by @samp{=}.
328 @cindex console output in @sc{gdb/mi}
329 @var{console-stream-output} is output that should be displayed as is in the
330 console. It is the textual response to a CLI command. All the console
331 output is prefixed by @samp{~}.
334 @cindex target output in @sc{gdb/mi}
335 @var{target-stream-output} is the output produced by the target program.
336 All the target output is prefixed by @samp{@@}.
339 @cindex log output in @sc{gdb/mi}
340 @var{log-stream-output} is output text coming from @value{GDBN}'s internals, for
341 instance messages that should be displayed as part of an error log. All
342 the log output is prefixed by @samp{&}.
345 @cindex list output in @sc{gdb/mi}
346 New @sc{gdb/mi} commands should only output @var{lists} containing
352 @xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
353 details about the various output records.
355 @node GDB/MI Simple Examples
356 @subsection Simple Examples of @sc{gdb/mi} Interaction
357 @cindex @sc{gdb/mi}, simple examples
359 This subsection presents several simple examples of interaction using
360 the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
361 following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
362 the output received from @sc{gdb/mi}.
364 @subsubheading Target Stop
366 Here's an example of stopping the inferior process:
377 <- *stop,reason="stop",address="0x123",source="a.c:123"
381 @subsubheading Simple CLI Command
383 Here's an example of a simple CLI command being passed through
384 @sc{gdb/mi} and on to the CLI.
392 @subsubheading Command With Side Effects
395 -> -symbol-file xyz.exe
396 <- *breakpoint,nr="3",address="0x123",source="a.c:123"
400 @subsubheading A Bad Command
402 Here's what happens if you pass a non-existent command:
406 <- error,"Rubbish not found"
410 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
411 @node GDB/MI Compatibility with CLI
412 @section @sc{gdb/mi} Compatibility with CLI
414 @cindex compatibility, @sc{gdb/mi} and CLI
415 @cindex @sc{gdb/mi}, compatibility with CLI
416 To help users familiar with @value{GDBN}'s existing CLI interface, @sc{gdb/mi}
417 accepts existing CLI commands. As specified by the syntax, such
418 commands can be directly entered into the @sc{gdb/mi} interface and @value{GDBN} will
421 This mechanism is provided as an aid to developers of @sc{gdb/mi}
422 clients and not as a reliable interface into the CLI. Since the command
423 is being interpreteted in an environment that assumes @sc{gdb/mi}
424 behaviour, the exact output of such commands is likely to end up being
425 an un-supported hybrid of @sc{gdb/mi} and CLI output.
427 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
428 @node GDB/MI Output Records
429 @section @sc{gdb/mi} Output Records
432 * GDB/MI Result Records::
433 * GDB/MI Stream Records::
434 * GDB/MI Out-of-band Records::
437 @node GDB/MI Result Records
438 @subsection @sc{gdb/mi} Result Records
440 @cindex result records in @sc{gdb/mi}
441 @cindex @sc{gdb/mi}, result records
442 In addition to a number of out-of-band notifications, the response to a
443 @sc{gdb/mi} command includes one of the following result indications:
447 @item "^done" [ "," @var{results} ]
448 The synchronous operation was successful, @code{@var{results}} are the return
453 @c Is this one correct? Should it be an out-of-band notification?
454 The asynchronous operation was successfully started. The target is
457 @item "^error" "," @var{c-string}
459 The operation failed. The @code{@var{c-string}} contains the corresponding
463 @node GDB/MI Stream Records
464 @subsection @sc{gdb/mi} Stream Records
466 @cindex @sc{gdb/mi}, stream records
467 @cindex stream records in @sc{gdb/mi}
468 @value{GDBN} internally maintains a number of output streams: the console, the
469 target, and the log. The output intended for each of these streams is
470 funneled through the @sc{gdb/mi} interface using @dfn{stream records}.
472 Each stream record begins with a unique @dfn{prefix character} which
473 identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output
474 Syntax}). In addition to the prefix, each stream record contains a
475 @code{@var{string-output}}. This is either raw text (with an implicit new
476 line) or a quoted C string (which does not contain an implicit newline).
479 @item "~" @var{string-output}
480 The console output stream contains text that should be displayed in the
481 CLI console window. It contains the textual responses to CLI commands.
483 @item "@@" @var{string-output}
484 The target output stream contains any textual output from the running
487 @item "&" @var{string-output}
488 The log stream contains debugging messages being produced by @value{GDBN}'s
492 @node GDB/MI Out-of-band Records
493 @subsection @sc{gdb/mi} Out-of-band Records
495 @cindex out-of-band records in @sc{gdb/mi}
496 @cindex @sc{gdb/mi}, out-of-band records
497 @dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of
498 additional changes that have occurred. Those changes can either be a
499 consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
500 target activity (e.g., target stopped).
502 The following is a preliminary list of possible out-of-band records.
509 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
510 @node GDB/MI Command Description Format
511 @section @sc{gdb/mi} Command Description Format
513 The remaining sections describe blocks of commands. Each block of
514 commands is laid out in a fashion similar to this section.
516 Note the the line breaks shown in the examples are here only for
517 readability. They don't appear in the real output.
518 Also note that the commands with a non-available example (N.A.@:) are
521 @subheading Motivation
523 The motivation for this collection of commands.
525 @subheading Introduction
527 A brief introduction to this collection of commands as a whole.
531 For each command in the block, the following is described:
533 @subsubheading Synopsis
536 -command @var{args}@dots{}
539 @subsubheading @value{GDBN} Command
541 The corresponding @value{GDBN} CLI command.
543 @subsubheading Result
545 @subsubheading Out-of-band
549 @subsubheading Example
552 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
553 @node GDB/MI Breakpoint Table Commands
554 @section @sc{gdb/mi} Breakpoint table commands
556 @cindex breakpoint commands for @sc{gdb/mi}
557 @cindex @sc{gdb/mi}, breakpoint commands
558 This section documents @sc{gdb/mi} commands for manipulating
561 @subheading The @code{-break-after} Command
564 @subsubheading Synopsis
567 -break-after @var{number} @var{count}
570 The breakpoint number @var{number} is not in effect until it has been
571 hit @var{count} times. To see how this is reflected in the output of
572 the @samp{-break-list} command, see the description of the
573 @samp{-break-list} command below.
575 @subsubheading @value{GDBN} Command
577 The corresponding @value{GDBN} command is @samp{ignore}.
579 @subsubheading Example
584 ^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@}
591 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
592 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
593 addr="0x000100d0",func="main",file="hello.c",line="5",times="0",
599 @subheading The @code{-break-catch} Command
602 @subheading The @code{-break-commands} Command
603 @findex -break-commands
607 @subheading The @code{-break-condition} Command
608 @findex -break-condition
610 @subsubheading Synopsis
613 -break-condition @var{number} @var{expr}
616 Breakpoint @var{number} will stop the program only if the condition in
617 @var{expr} is true. The condition becomes part of the
618 @samp{-break-list} output (see the description of the @samp{-break-list}
621 @subsubheading @value{GDBN} Command
623 The corresponding @value{GDBN} command is @samp{condition}.
625 @subsubheading Example
633 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
634 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
635 addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",
636 times="0",ignore="3"@}@}
640 @subheading The @code{-break-delete} Command
641 @findex -break-delete
643 @subsubheading Synopsis
646 -break-delete ( @var{breakpoint} )+
649 Delete the breakpoint(s) whose number(s) are specified in the argument
650 list. This is obviously reflected in the breakpoint list.
652 @subsubheading @value{GDBN} command
654 The corresponding @value{GDBN} command is @samp{delete}.
656 @subsubheading Example
664 ^done,BreakpointTable=@{@}
668 @subheading The @code{-break-disable} Command
669 @findex -break-disable
671 @subsubheading Synopsis
674 -break-disable ( @var{breakpoint} )+
677 Disable the named @var{breakpoint}(s). The field @samp{enabled} in the
678 break list is now set to @samp{n} for the named @var{breakpoint}(s).
680 @subsubheading @value{GDBN} Command
682 The corresponding @value{GDBN} command is @samp{disable}.
684 @subsubheading Example
692 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
693 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
694 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@}
698 @subheading The @code{-break-enable} Command
699 @findex -break-enable
701 @subsubheading Synopsis
704 -break-enable ( @var{breakpoint} )+
707 Enable (previously disabled) @var{breakpoint}(s).
709 @subsubheading @value{GDBN} Command
711 The corresponding @value{GDBN} command is @samp{enable}.
713 @subsubheading Example
721 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
722 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
723 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@}
727 @subheading The @code{-break-info} Command
730 @subsubheading Synopsis
733 -break-info @var{breakpoint}
737 Get information about a single breakpoint.
739 @subsubheading @value{GDBN} command
741 The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
743 @subsubheading Example
746 @subheading The @code{-break-insert} Command
747 @findex -break-insert
749 @subsubheading Synopsis
752 -break-insert [ -t ] [ -h ] [ -r ]
753 [ -c @var{condition} ] [ -i @var{ignore-count} ]
754 [ -p @var{thread} ] [ @var{line} | @var{addr} ]
758 If specified, @var{line}, can be one of:
765 @item filename:linenum
766 @item filename:function
770 The possible optional parameters of this command are:
774 Insert a tempoary breakpoint.
776 Insert a hardware breakpoint.
777 @item -c @var{condition}
778 Make the breakpoint conditional on @var{condition}.
779 @item -i @var{ignore-count}
780 Initialize the @var{ignore-count}.
782 Insert a regular breakpoint in all the functions whose names match the
783 given regular expression. Other flags are not applicable to regular
787 @subsubheading Result
789 The result is in the form:
792 ^done,bkptno="@var{number}",func="@var{funcname}",
793 file="@var{filename}",line="@var{lineno}"
797 where @var{number} is the @value{GDBN} number for this breakpoint, @var{funcname}
798 is the name of the function where the breakpoint was inserted,
799 @var{filename} is the name of the source file which contains this
800 function, and @var{lineno} is the source line number within that file.
802 Note: this format is open to change.
803 @c An out-of-band breakpoint instead of part of the result?
805 @subsubheading @value{GDBN} Command
807 The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
808 @samp{hbreak}, @samp{thbreak}, and @samp{rbreak}.
810 @subsubheading Example
815 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
818 ^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@}
821 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
822 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
823 addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@},
824 bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
825 addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}@}
827 -break-insert -r foo.*
829 ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@}
833 @subheading The @code{-break-list} Command
836 @subsubheading Synopsis
842 Displays the list of inserted breakpoints, showing the following fields:
846 number of the breakpoint
848 type of the breakpoint: @samp{breakpoint} or @samp{watchpoint}
850 should the breakpoint be deleted or disabled when it is hit: @samp{keep}
853 is the breakpoint enabled or no: @samp{y} or @samp{n}
855 memory location at which the breakpoint is set
857 logical location of the breakpoint, expressed by function name, file
860 number of times the breakpoint has been hit
863 If there are no breakpoints or watchpoints, the @code{BreakpointTable}
864 field is an empty list.
866 @subsubheading @value{GDBN} Command
868 The corresponding @value{GDBN} command is @samp{info break}.
870 @subsubheading Example
875 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
876 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
877 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
878 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
879 addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}@}
883 Here's an example of the result when there are no breakpoints:
888 ^done,BreakpointTable=@{@}
892 @subheading The @code{-break-watch} Command
895 @subsubheading Synopsis
898 -break-watch [ -a | -r ]
901 Create a watchpoint. With the @samp{-a} option it will create an
902 @dfn{access} watchpoint, i.e. a watchpoint that triggers either on a
903 read from or on a write to the memory location. With the @samp{-r}
904 option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will
905 trigger only when the memory location is accessed for reading. Without
906 either of the options, the watchpoint created is a regular watchpoint,
907 i.e. it will trigger when the memory location is accessed for writing.
908 @xref{Set Watchpoints, , Setting watchpoints}.
910 Note that @samp{-break-list} will report a single list of watchpoints and
911 breakpoints inserted.
913 @subsubheading @value{GDBN} Command
915 The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and
918 @subsubheading Example
920 Setting a watchpoint on a variable in the @code{main} function:
925 ^done,wpt=@{number="2",exp="x"@}
929 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
930 value=@{old="-268439212",new="55"@},
931 frame=@{func="main",args=[],file="recursive2.c",line="5"@}
935 Setting a watchpoint on a variable local to a function. @value{GDBN} will stop
936 the program execution twice: first for the variable changing value, then
937 for the watchpoint going out of scope.
942 ^done,wpt=@{number="5",exp="C"@}
946 ^done,reason="watchpoint-trigger",
947 wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
948 frame=@{func="callee4",args=[],
949 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
953 ^done,reason="watchpoint-scope",wpnum="5",
954 frame=@{func="callee3",args=[@{name="strarg",
955 value="0x11940 \"A string argument.\""@}],
956 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
960 Listing breakpoints and watchpoints, at different points in the program
961 execution. Note that once the watchpoint goes out of scope, it is
967 ^done,wpt=@{number="2",exp="C"@}
970 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
971 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
972 addr="0x00010734",func="callee4",
973 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
974 bkpt=@{number="2",type="watchpoint",disp="keep",
975 enabled="y",addr="",what="C",times="0"@}@}
979 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
980 value=@{old="-276895068",new="3"@},
981 frame=@{func="callee4",args=[],
982 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
985 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
986 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
987 addr="0x00010734",func="callee4",
988 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
989 bkpt=@{number="2",type="watchpoint",disp="keep",
990 enabled="y",addr="",what="C",times="-5"@}@}
994 ^done,reason="watchpoint-scope",wpnum="2",
995 frame=@{func="callee3",args=[@{name="strarg",
996 value="0x11940 \"A string argument.\""@}],
997 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1000 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
1001 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
1002 addr="0x00010734",func="callee4",
1003 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}@}
1007 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1008 @node GDB/MI Data Manipulation
1009 @section @sc{gdb/mi} Data Manipulation
1011 @cindex data manipulation, in @sc{gdb/mi}
1012 @cindex @sc{gdb/mi}, data manipulation
1013 This section describes the @sc{gdb/mi} commands that manipulate data:
1014 examine memory and registers, evaluate expressions, etc.
1016 @c REMOVED FROM THE INTERFACE.
1017 @c @subheading -data-assign
1018 @c Change the value of a program variable. Plenty of side effects.
1019 @c @subsubheading GDB command
1021 @c @subsubheading Example
1024 @subheading The @code{-data-disassemble} Command
1025 @findex -data-disassemble
1027 @subsubheading Synopsis
1031 [ -s @var{start-addr} -e @var{end-addr} ]
1032 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
1040 @item @var{start-addr}
1041 is the beginning address (or @code{$pc})
1042 @item @var{end-addr}
1044 @item @var{filename}
1045 is the name of the file to disassemble
1047 is the line number to disassemble around
1049 is the the number of disassembly lines to be produced. If it is -1,
1050 the whole function will be disassembled, in case no @var{end-addr} is
1051 specified. If @var{end-addr} is specified as a non-zero value, and
1052 @var{lines} is lower than the number of disassembly lines between
1053 @var{start-addr} and @var{end-addr}, only @var{lines} lines are
1054 displayed; if @var{lines} is higher than the number of lines between
1055 @var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
1058 is either 0 (meaning only disassembly) or 1 (meaning mixed source and
1062 @subsubheading Result
1064 The output for each instruction is composed of four fields:
1073 Note that whatever included in the instruction field, is not manipulated
1074 directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format.
1076 @subsubheading @value{GDBN} Command
1078 There's no direct mapping from this command to the CLI.
1080 @subsubheading Example
1082 Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
1086 -data-disassemble -s $pc -e "$pc + 20" -- 0
1089 @{address="0x000107c0",func-name="main",offset="4",
1090 inst="mov 2, %o0"@},
1091 @{address="0x000107c4",func-name="main",offset="8",
1092 inst="sethi %hi(0x11800), %o2"@},
1093 @{address="0x000107c8",func-name="main",offset="12",
1094 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
1095 @{address="0x000107cc",func-name="main",offset="16",
1096 inst="sethi %hi(0x11800), %o2"@},
1097 @{address="0x000107d0",func-name="main",offset="20",
1098 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}]
1102 Disassemble the whole @code{main} function. Line 32 is part of
1106 -data-disassemble -f basics.c -l 32 -- 0
1108 @{address="0x000107bc",func-name="main",offset="0",
1109 inst="save %sp, -112, %sp"@},
1110 @{address="0x000107c0",func-name="main",offset="4",
1111 inst="mov 2, %o0"@},
1112 @{address="0x000107c4",func-name="main",offset="8",
1113 inst="sethi %hi(0x11800), %o2"@},
1115 @{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
1116 @{address="0x00010820",func-name="main",offset="100",inst="restore "@}]
1120 Disassemble 3 instructions from the start of @code{main}:
1124 -data-disassemble -f basics.c -l 32 -n 3 -- 0
1126 @{address="0x000107bc",func-name="main",offset="0",
1127 inst="save %sp, -112, %sp"@},
1128 @{address="0x000107c0",func-name="main",offset="4",
1129 inst="mov 2, %o0"@},
1130 @{address="0x000107c4",func-name="main",offset="8",
1131 inst="sethi %hi(0x11800), %o2"@}]
1135 Disassemble 3 instructions from the start of @code{main} in mixed mode:
1139 -data-disassemble -f basics.c -l 32 -n 3 -- 1
1141 src_and_asm_line=@{line="31",
1142 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1143 testsuite/gdb.mi/basics.c",line_asm_insn=[
1144 @{address="0x000107bc",func-name="main",offset="0",
1145 inst="save %sp, -112, %sp"@}]@},
1146 src_and_asm_line=@{line="32",
1147 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1148 testsuite/gdb.mi/basics.c",line_asm_insn=[
1149 @{address="0x000107c0",func-name="main",offset="4",
1150 inst="mov 2, %o0"@},
1151 @{address="0x000107c4",func-name="main",offset="8",
1152 inst="sethi %hi(0x11800), %o2"@}]@}]
1157 @subheading The @code{-data-evaluate-expression} Command
1158 @findex -data-evaluate-expression
1160 @subsubheading Synopsis
1163 -data-evaluate-expression @var{expr}
1166 Evaluate @var{expr} as an expression. The expression could contain an
1167 inferior function call. The function call will execute synchronously.
1168 If the expression contains spaces, it must be enclosed in double quotes.
1170 @subsubheading @value{GDBN} Command
1172 The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
1173 @samp{call}. In @code{gdbtk} only, there's a corresponding
1174 @samp{gdb_eval} command.
1176 @subsubheading Example
1178 In the following example, the numbers that precede the commands are the
1179 @dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
1180 Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
1184 211-data-evaluate-expression A
1187 311-data-evaluate-expression &A
1188 311^done,value="0xefffeb7c"
1190 411-data-evaluate-expression A+3
1193 511-data-evaluate-expression "A + 3"
1199 @subheading The @code{-data-list-changed-registers} Command
1200 @findex -data-list-changed-registers
1202 @subsubheading Synopsis
1205 -data-list-changed-registers
1208 Display a list of the registers that have changed.
1210 @subsubheading @value{GDBN} Command
1212 @value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
1213 has the corresponding command @samp{gdb_changed_register_list}.
1215 @subsubheading Example
1225 *stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
1226 args=[],file="try.c",line="5"@}
1228 -data-list-changed-registers
1229 ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
1230 "10","11","13","14","15","16","17","18","19","20","21","22","23",
1231 "24","25","26","27","28","30","31","64","65","66","67","69"]
1236 @subheading The @code{-data-list-register-names} Command
1237 @findex -data-list-register-names
1239 @subsubheading Synopsis
1242 -data-list-register-names [ ( @var{regno} )+ ]
1245 Show a list of register names for the current target. If no arguments
1246 are given, it shows a list of the names of all the registers. If
1247 integer numbers are given as arguments, it will print a list of the
1248 names of the registers corresponding to the arguments. To ensure
1249 consistency between a register name and its number, the output list may
1250 include empty register names.
1252 @subsubheading @value{GDBN} Command
1254 @value{GDBN} does not have a command which corresponds to
1255 @samp{-data-list-register-names}. In @code{gdbtk} there is a
1256 corresponding command @samp{gdb_regnames}.
1258 @subsubheading Example
1260 For the PPC MBX board:
1263 -data-list-register-names
1264 ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
1265 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
1266 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
1267 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
1268 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
1269 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
1270 "", "pc","ps","cr","lr","ctr","xer"]
1272 -data-list-register-names 1 2 3
1273 ^done,register-names=["r1","r2","r3"]
1277 @subheading The @code{-data-list-register-values} Command
1278 @findex -data-list-register-values
1280 @subsubheading Synopsis
1283 -data-list-register-values @var{fmt} [ ( @var{regno} )*]
1286 Display the registers' contents. @var{fmt} is the format according to
1287 which the registers' contents are to be returned, followed by an optional
1288 list of numbers specifying the registers to display. A missing list of
1289 numbers indicates that the contents of all the registers must be returned.
1291 Allowed formats for @var{fmt} are:
1308 @subsubheading @value{GDBN} Command
1310 The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
1311 all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
1313 @subsubheading Example
1315 For a PPC MBX board (note: line breaks are for readability only, they
1316 don't appear in the actual output):
1320 -data-list-register-values r 64 65
1321 ^done,register-values=[@{number="64",value="0xfe00a300"@},
1322 @{number="65",value="0x00029002"@}]
1324 -data-list-register-values x
1325 ^done,register-values=[@{number="0",value="0xfe0043c8"@},
1326 @{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
1327 @{number="3",value="0x0"@},@{number="4",value="0xa"@},
1328 @{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
1329 @{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
1330 @{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
1331 @{number="11",value="0x1"@},@{number="12",value="0x0"@},
1332 @{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
1333 @{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
1334 @{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
1335 @{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
1336 @{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
1337 @{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
1338 @{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
1339 @{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
1340 @{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
1341 @{number="31",value="0x0"@},@{number="32",value="0x0"@},
1342 @{number="33",value="0x0"@},@{number="34",value="0x0"@},
1343 @{number="35",value="0x0"@},@{number="36",value="0x0"@},
1344 @{number="37",value="0x0"@},@{number="38",value="0x0"@},
1345 @{number="39",value="0x0"@},@{number="40",value="0x0"@},
1346 @{number="41",value="0x0"@},@{number="42",value="0x0"@},
1347 @{number="43",value="0x0"@},@{number="44",value="0x0"@},
1348 @{number="45",value="0x0"@},@{number="46",value="0x0"@},
1349 @{number="47",value="0x0"@},@{number="48",value="0x0"@},
1350 @{number="49",value="0x0"@},@{number="50",value="0x0"@},
1351 @{number="51",value="0x0"@},@{number="52",value="0x0"@},
1352 @{number="53",value="0x0"@},@{number="54",value="0x0"@},
1353 @{number="55",value="0x0"@},@{number="56",value="0x0"@},
1354 @{number="57",value="0x0"@},@{number="58",value="0x0"@},
1355 @{number="59",value="0x0"@},@{number="60",value="0x0"@},
1356 @{number="61",value="0x0"@},@{number="62",value="0x0"@},
1357 @{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
1358 @{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
1359 @{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
1360 @{number="69",value="0x20002b03"@}]
1365 @subheading The @code{-data-read-memory} Command
1366 @findex -data-read-memory
1368 @subsubheading Synopsis
1371 -data-read-memory [ -o @var{byte-offset} ]
1372 @var{address} @var{word-format} @var{word-size}
1373 @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
1381 An expression specifying the address of the first memory word to be
1382 read. Complex expressions containing embedded white space should be
1383 quoted using the C convention.
1385 @item @var{word-format}
1386 The format to be used to print the memory words. The notation is the
1387 same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
1390 @item @var{word-size}
1391 The size of each memory word in bytes.
1394 The number of rows in the output table.
1397 The number of columns in the output table.
1400 If present, indicates that each row should include an @sc{ascii} dump. The
1401 value of @var{aschar} is used as a padding character when a byte is not a
1402 member of the printable @sc{ascii} character set (printable @sc{ascii}
1403 characters are those whose code is between 32 and 126, inclusively).
1405 @item @var{byte-offset}
1406 An offset to add to the @var{address} before fetching memory.
1409 This command displays memory contents as a table of @var{nr-rows} by
1410 @var{nr-cols} words, each word being @var{word-size} bytes. In total,
1411 @code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
1412 (returned as @samp{total-bytes}). Should less then the requested number
1413 of bytes be returned by the target, the missing words are identified
1414 using @samp{N/A}. The number of bytes read from the target is returned
1415 in @samp{nr-bytes} and the starting address used to read memory in
1418 The address of the next/previous row or page is available in
1419 @samp{next-row} and @samp{prev-row}, @samp{next-page} and
1422 @subsubheading @value{GDBN} Command
1424 The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
1425 @samp{gdb_get_mem} memory read command.
1427 @subsubheading Example
1429 Read six bytes of memory starting at @code{bytes+6} but then offset by
1430 @code{-6} bytes. Format as three rows of two columns. One byte per
1431 word. Display each word in hex.
1435 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
1436 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
1437 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
1438 prev-page="0x0000138a",memory=[
1439 @{addr="0x00001390",data=["0x00","0x01"]@},
1440 @{addr="0x00001392",data=["0x02","0x03"]@},
1441 @{addr="0x00001394",data=["0x04","0x05"]@}]
1445 Read two bytes of memory starting at address @code{shorts + 64} and
1446 display as a single word formatted in decimal.
1450 5-data-read-memory shorts+64 d 2 1 1
1451 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
1452 next-row="0x00001512",prev-row="0x0000150e",
1453 next-page="0x00001512",prev-page="0x0000150e",memory=[
1454 @{addr="0x00001510",data=["128"]@}]
1458 Read thirty two bytes of memory starting at @code{bytes+16} and format
1459 as eight rows of four columns. Include a string encoding with @samp{x}
1460 used as the non-printable character.
1464 4-data-read-memory bytes+16 x 1 8 4 x
1465 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
1466 next-row="0x000013c0",prev-row="0x0000139c",
1467 next-page="0x000013c0",prev-page="0x00001380",memory=[
1468 @{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@},
1469 @{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@},
1470 @{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@},
1471 @{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@},
1472 @{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@},
1473 @{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@},
1474 @{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@},
1475 @{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}]
1479 @subheading The @code{-display-delete} Command
1480 @findex -display-delete
1482 @subsubheading Synopsis
1485 -display-delete @var{number}
1488 Delete the display @var{number}.
1490 @subsubheading @value{GDBN} Command
1492 The corresponding @value{GDBN} command is @samp{delete display}.
1494 @subsubheading Example
1498 @subheading The @code{-display-disable} Command
1499 @findex -display-disable
1501 @subsubheading Synopsis
1504 -display-disable @var{number}
1507 Disable display @var{number}.
1509 @subsubheading @value{GDBN} Command
1511 The corresponding @value{GDBN} command is @samp{disable display}.
1513 @subsubheading Example
1517 @subheading The @code{-display-enable} Command
1518 @findex -display-enable
1520 @subsubheading Synopsis
1523 -display-enable @var{number}
1526 Enable display @var{number}.
1528 @subsubheading @value{GDBN} Command
1530 The corresponding @value{GDBN} command is @samp{enable display}.
1532 @subsubheading Example
1536 @subheading The @code{-display-insert} Command
1537 @findex -display-insert
1539 @subsubheading Synopsis
1542 -display-insert @var{expression}
1545 Display @var{expression} every time the program stops.
1547 @subsubheading @value{GDBN} Command
1549 The corresponding @value{GDBN} command is @samp{display}.
1551 @subsubheading Example
1555 @subheading The @code{-display-list} Command
1556 @findex -display-list
1558 @subsubheading Synopsis
1564 List the displays. Do not show the current values.
1566 @subsubheading @value{GDBN} Command
1568 The corresponding @value{GDBN} command is @samp{info display}.
1570 @subsubheading Example
1574 @subheading The @code{-environment-cd} Command
1575 @findex -environment-cd
1577 @subsubheading Synopsis
1580 -environment-cd @var{pathdir}
1583 Set @value{GDBN}'s working directory.
1585 @subsubheading @value{GDBN} Command
1587 The corresponding @value{GDBN} command is @samp{cd}.
1589 @subsubheading Example
1593 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1599 @subheading The @code{-environment-directory} Command
1600 @findex -environment-directory
1602 @subsubheading Synopsis
1605 -environment-directory @var{pathdir}
1608 Add directory @var{pathdir} to beginning of search path for source files.
1610 @subsubheading @value{GDBN} Command
1612 The corresponding @value{GDBN} command is @samp{dir}.
1614 @subsubheading Example
1618 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1624 @subheading The @code{-environment-path} Command
1625 @findex -environment-path
1627 @subsubheading Synopsis
1630 -environment-path ( @var{pathdir} )+
1633 Add directories @var{pathdir} to beginning of search path for object files.
1635 @subsubheading @value{GDBN} Command
1637 The corresponding @value{GDBN} command is @samp{path}.
1639 @subsubheading Example
1643 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb
1649 @subheading The @code{-environment-pwd} Command
1650 @findex -environment-pwd
1652 @subsubheading Synopsis
1658 Show the current working directory.
1660 @subsubheading @value{GDBN} command
1662 The corresponding @value{GDBN} command is @samp{pwd}.
1664 @subsubheading Example
1669 ~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb.
1674 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1675 @node GDB/MI Program Control
1676 @section @sc{gdb/mi} Program control
1678 @subsubheading Program termination
1680 As a result of execution, the inferior program can run to completion, if
1681 it doesn't encounter any breakpoints. In this case the output will
1682 include an exit code, if the program has exited exceptionally.
1684 @subsubheading Examples
1687 Program exited normally:
1695 *stopped,reason="exited-normally"
1700 Program exited exceptionally:
1708 *stopped,reason="exited",exit-code="01"
1712 Another way the program can terminate is if it receives a signal such as
1713 @code{SIGINT}. In this case, @sc{gdb/mi} displays this:
1717 *stopped,reason="exited-signalled",signal-name="SIGINT",
1718 signal-meaning="Interrupt"
1722 @subheading The @code{-exec-abort} Command
1725 @subsubheading Synopsis
1731 Kill the inferior running program.
1733 @subsubheading @value{GDBN} Command
1735 The corresponding @value{GDBN} command is @samp{kill}.
1737 @subsubheading Example
1741 @subheading The @code{-exec-arguments} Command
1742 @findex -exec-arguments
1744 @subsubheading Synopsis
1747 -exec-arguments @var{args}
1750 Set the inferior program arguments, to be used in the next
1753 @subsubheading @value{GDBN} Command
1755 The corresponding @value{GDBN} command is @samp{set args}.
1757 @subsubheading Example
1760 Don't have one around.
1763 @subheading The @code{-exec-continue} Command
1764 @findex -exec-continue
1766 @subsubheading Synopsis
1772 Asynchronous command. Resumes the execution of the inferior program
1773 until a breakpoint is encountered, or until the inferior exits.
1775 @subsubheading @value{GDBN} Command
1777 The corresponding @value{GDBN} corresponding is @samp{continue}.
1779 @subsubheading Example
1786 *stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
1787 file="hello.c",line="13"@}
1792 @subheading The @code{-exec-finish} Command
1793 @findex -exec-finish
1795 @subsubheading Synopsis
1801 Asynchronous command. Resumes the execution of the inferior program
1802 until the current function is exited. Displays the results returned by
1805 @subsubheading @value{GDBN} Command
1807 The corresponding @value{GDBN} command is @samp{finish}.
1809 @subsubheading Example
1811 Function returning @code{void}.
1818 *stopped,reason="function-finished",frame=@{func="main",args=[],
1819 file="hello.c",line="7"@}
1823 Function returning other than @code{void}. The name of the internal
1824 @value{GDBN} variable storing the result is printed, together with the
1831 *stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
1832 args=[@{name="a",value="1"],@{name="b",value="9"@}@},
1833 file="recursive2.c",line="14"@},
1834 gdb-result-var="$1",return-value="0"
1839 @subheading The @code{-exec-interrupt} Command
1840 @findex -exec-interrupt
1842 @subsubheading Synopsis
1848 Asynchronous command. Interrupts the background execution of the target.
1849 Note how the token associated with the stop message is the one for the
1850 execution command that has been interrupted. The token for the interrupt
1851 itself only appears in the @samp{^done} output. If the user is trying to
1852 interrupt a non-running program, an error message will be printed.
1854 @subsubheading @value{GDBN} Command
1856 The corresponding @value{GDBN} command is @samp{interrupt}.
1858 @subsubheading Example
1869 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
1870 frame=@{addr="0x00010140",func="foo",args=[],file="try.c",line="13"@}
1875 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
1880 @subheading The @code{-exec-next} Command
1883 @subsubheading Synopsis
1889 Asynchronous command. Resumes execution of the inferior program, stopping
1890 when the beginning of the next source line is reached.
1892 @subsubheading @value{GDBN} Command
1894 The corresponding @value{GDBN} command is @samp{next}.
1896 @subsubheading Example
1902 *stopped,reason="end-stepping-range",line="8",file="hello.c"
1907 @subheading The @code{-exec-next-instruction} Command
1908 @findex -exec-next-instruction
1910 @subsubheading Synopsis
1913 -exec-next-instruction
1916 Asynchronous command. Executes one machine instruction. If the
1917 instruction is a function call continues until the function returns. If
1918 the program stops at an instruction in the middle of a source line, the
1919 address will be printed as well.
1921 @subsubheading @value{GDBN} Command
1923 The corresponding @value{GDBN} command is @samp{nexti}.
1925 @subsubheading Example
1929 -exec-next-instruction
1933 *stopped,reason="end-stepping-range",
1934 addr="0x000100d4",line="5",file="hello.c"
1939 @subheading The @code{-exec-return} Command
1940 @findex -exec-return
1942 @subsubheading Synopsis
1948 Makes current function return immediately. Doesn't execute the inferior.
1949 Displays the new current frame.
1951 @subsubheading @value{GDBN} Command
1953 The corresponding @value{GDBN} command is @samp{return}.
1955 @subsubheading Example
1959 200-break-insert callee4
1960 200^done,bkpt=@{number="1",addr="0x00010734",
1961 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1966 000*stopped,reason="breakpoint-hit",bkptno="1",
1967 frame=@{func="callee4",args=[],
1968 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1974 111^done,frame=@{level="0 ",func="callee3",
1975 args=[@{name="strarg",
1976 value="0x11940 \"A string argument.\""@}],
1977 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1982 @subheading The @code{-exec-run} Command
1985 @subsubheading Synopsis
1991 Asynchronous command. Starts execution of the inferior from the
1992 beginning. The inferior executes until either a breakpoint is
1993 encountered or the program exits.
1995 @subsubheading @value{GDBN} Command
1997 The corresponding @value{GDBN} command is @samp{run}.
1999 @subsubheading Example
2004 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
2009 *stopped,reason="breakpoint-hit",bkptno="1",
2010 frame=@{func="main",args=[],file="recursive2.c",line="4"@}
2015 @subheading The @code{-exec-show-arguments} Command
2016 @findex -exec-show-arguments
2018 @subsubheading Synopsis
2021 -exec-show-arguments
2024 Print the arguments of the program.
2026 @subsubheading @value{GDBN} Command
2028 The corresponding @value{GDBN} command is @samp{show args}.
2030 @subsubheading Example
2033 @c @subheading -exec-signal
2035 @subheading The @code{-exec-step} Command
2038 @subsubheading Synopsis
2044 Asynchronous command. Resumes execution of the inferior program, stopping
2045 when the beginning of the next source line is reached, if the next
2046 source line is not a function call. If it is, stop at the first
2047 instruction of the called function.
2049 @subsubheading @value{GDBN} Command
2051 The corresponding @value{GDBN} command is @samp{step}.
2053 @subsubheading Example
2055 Stepping into a function:
2061 *stopped,reason="end-stepping-range",
2062 frame=@{func="foo",args=[@{name="a",value="10"@},
2063 @{name="b",value="0"@}],file="recursive2.c",line="11"@}
2073 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
2078 @subheading The @code{-exec-step-instruction} Command
2079 @findex -exec-step-instruction
2081 @subsubheading Synopsis
2084 -exec-step-instruction
2087 Asynchronous command. Resumes the inferior which executes one machine
2088 instruction. The output, once @value{GDBN} has stopped, will vary depending on
2089 whether we have stopped in the middle of a source line or not. In the
2090 former case, the address at which the program stopped will be printed as
2093 @subsubheading @value{GDBN} Command
2095 The corresponding @value{GDBN} command is @samp{stepi}.
2097 @subsubheading Example
2101 -exec-step-instruction
2105 *stopped,reason="end-stepping-range",
2106 frame=@{func="foo",args=[],file="try.c",line="10"@}
2108 -exec-step-instruction
2112 *stopped,reason="end-stepping-range",
2113 frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@}
2118 @subheading The @code{-exec-until} Command
2121 @subsubheading Synopsis
2124 -exec-until [ @var{location} ]
2127 Asynchronous command. Executes the inferior until the @var{location}
2128 specified in the argument is reached. If there is no argument, the inferior
2129 executes until a source line greater than the current one is reached.
2130 The reason for stopping in this case will be @samp{location-reached}.
2132 @subsubheading @value{GDBN} Command
2134 The corresponding @value{GDBN} command is @samp{until}.
2136 @subsubheading Example
2140 -exec-until recursive2.c:6
2144 *stopped,reason="location-reached",frame=@{func="main",args=[],
2145 file="recursive2.c",line="6"@}
2150 @subheading -file-clear
2151 Is this going away????
2155 @subheading The @code{-file-exec-and-symbols} Command
2156 @findex -file-exec-and-symbols
2158 @subsubheading Synopsis
2161 -file-exec-and-symbols @var{file}
2164 Specify the executable file to be debugged. This file is the one from
2165 which the symbol table is also read. If no file is specified, the
2166 command clears the executable and symbol information. If breakpoints
2167 are set when using this command with no arguments, @value{GDBN} will produce
2168 error messages. Otherwise, no output is produced, except a completion
2171 @subsubheading @value{GDBN} Command
2173 The corresponding @value{GDBN} command is @samp{file}.
2175 @subsubheading Example
2179 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2185 @subheading The @code{-file-exec-file} Command
2186 @findex -file-exec-file
2188 @subsubheading Synopsis
2191 -file-exec-file @var{file}
2194 Specify the executable file to be debugged. Unlike
2195 @samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
2196 from this file. If used without argument, @value{GDBN} clears the information
2197 about the executable file. No output is produced, except a completion
2200 @subsubheading @value{GDBN} Command
2202 The corresponding @value{GDBN} command is @samp{exec-file}.
2204 @subsubheading Example
2208 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2214 @subheading The @code{-file-list-exec-sections} Command
2215 @findex -file-list-exec-sections
2217 @subsubheading Synopsis
2220 -file-list-exec-sections
2223 List the sections of the current executable file.
2225 @subsubheading @value{GDBN} Command
2227 The @value{GDBN} command @samp{info file} shows, among the rest, the same
2228 information as this command. @code{gdbtk} has a corresponding command
2229 @samp{gdb_load_info}.
2231 @subsubheading Example
2235 @subheading The @code{-file-list-exec-source-files} Command
2236 @findex -file-list-exec-source-files
2238 @subsubheading Synopsis
2241 -file-list-exec-source-files
2244 List the source files for the current executable.
2246 @subsubheading @value{GDBN} Command
2248 There's no @value{GDBN} command which directly corresponds to this one.
2249 @code{gdbtk} has an analogous command @samp{gdb_listfiles}.
2251 @subsubheading Example
2255 @subheading The @code{-file-list-shared-libraries} Command
2256 @findex -file-list-shared-libraries
2258 @subsubheading Synopsis
2261 -file-list-shared-libraries
2264 List the shared libraries in the program.
2266 @subsubheading @value{GDBN} Command
2268 The corresponding @value{GDBN} command is @samp{info shared}.
2270 @subsubheading Example
2274 @subheading The @code{-file-list-symbol-files} Command
2275 @findex -file-list-symbol-files
2277 @subsubheading Synopsis
2280 -file-list-symbol-files
2285 @subsubheading @value{GDBN} Command
2287 The corresponding @value{GDBN} command is @samp{info file} (part of it).
2289 @subsubheading Example
2293 @subheading The @code{-file-symbol-file} Command
2294 @findex -file-symbol-file
2296 @subsubheading Synopsis
2299 -file-symbol-file @var{file}
2302 Read symbol table info from the specified @var{file} argument. When
2303 used without arguments, clears @value{GDBN}'s symbol table info. No output is
2304 produced, except for a completion notification.
2306 @subsubheading @value{GDBN} Command
2308 The corresponding @value{GDBN} command is @samp{symbol-file}.
2310 @subsubheading Example
2314 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2319 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2320 @node GDB/MI Miscellaneous Commands
2321 @section Miscellaneous @value{GDBN} commands in @sc{gdb/mi}
2323 @c @subheading -gdb-complete
2325 @subheading The @code{-gdb-exit} Command
2328 @subsubheading Synopsis
2334 Exit @value{GDBN} immediately.
2336 @subsubheading @value{GDBN} Command
2338 Approximately corresponds to @samp{quit}.
2340 @subsubheading Example
2347 @subheading The @code{-gdb-set} Command
2350 @subsubheading Synopsis
2356 Set an internal @value{GDBN} variable.
2357 @c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
2359 @subsubheading @value{GDBN} Command
2361 The corresponding @value{GDBN} command is @samp{set}.
2363 @subsubheading Example
2373 @subheading The @code{-gdb-show} Command
2376 @subsubheading Synopsis
2382 Show the current value of a @value{GDBN} variable.
2384 @subsubheading @value{GDBN} command
2386 The corresponding @value{GDBN} command is @samp{show}.
2388 @subsubheading Example
2397 @c @subheading -gdb-source
2400 @subheading The @code{-gdb-version} Command
2401 @findex -gdb-version
2403 @subsubheading Synopsis
2409 Show version information for @value{GDBN}. Used mostly in testing.
2411 @subsubheading @value{GDBN} Command
2413 There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this
2414 information when you start an interactive session.
2416 @subsubheading Example
2418 @c This example modifies the actual output from GDB to avoid overfull
2424 ~Copyright 2000 Free Software Foundation, Inc.
2425 ~GDB is free software, covered by the GNU General Public License, and
2426 ~you are welcome to change it and/or distribute copies of it under
2427 ~ certain conditions.
2428 ~Type "show copying" to see the conditions.
2429 ~There is absolutely no warranty for GDB. Type "show warranty" for
2431 ~This GDB was configured as
2432 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
2438 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2439 @node GDB/MI Kod Commands
2440 @section @sc{gdb/mi} Kod Commands
2442 The Kod commands are not implemented.
2444 @c @subheading -kod-info
2446 @c @subheading -kod-list
2448 @c @subheading -kod-list-object-types
2450 @c @subheading -kod-show
2452 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2453 @node GDB/MI Memory Overlay Commands
2454 @section @sc{gdb/mi} Memory Overlay Commands
2456 The memory overlay commands are not implemented.
2458 @c @subheading -overlay-auto
2460 @c @subheading -overlay-list-mapping-state
2462 @c @subheading -overlay-list-overlays
2464 @c @subheading -overlay-map
2466 @c @subheading -overlay-off
2468 @c @subheading -overlay-on
2470 @c @subheading -overlay-unmap
2472 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2473 @node GDB/MI Signal Handling Commands
2474 @section @sc{gdb/mi} Signal Handling Commands
2476 Signal handling commands are not implemented.
2478 @c @subheading -signal-handle
2480 @c @subheading -signal-list-handle-actions
2482 @c @subheading -signal-list-signal-types
2486 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2487 @node GDB/MI Stack Manipulation
2488 @section @sc{gdb/mi} Stack Manipulation Commands
2491 @subheading The @code{-stack-info-frame} Command
2492 @findex -stack-info-frame
2494 @subsubheading Synopsis
2500 Get info on the current frame.
2502 @subsubheading @value{GDBN} Command
2504 The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
2505 (without arguments).
2507 @subsubheading Example
2510 @subheading The @code{-stack-info-depth} Command
2511 @findex -stack-info-depth
2513 @subsubheading Synopsis
2516 -stack-info-depth [ @var{max-depth} ]
2519 Return the depth of the stack. If the integer argument @var{max-depth}
2520 is specified, do not count beyond @var{max-depth} frames.
2522 @subsubheading @value{GDBN} Command
2524 There's no equivalent @value{GDBN} command.
2526 @subsubheading Example
2528 For a stack with frame levels 0 through 11:
2538 -stack-info-depth 12
2541 -stack-info-depth 11
2544 -stack-info-depth 13
2549 @subheading The @code{-stack-list-arguments} Command
2550 @findex -stack-list-arguments
2552 @subsubheading Synopsis
2555 -stack-list-arguments @var{show-values}
2556 [ @var{low-frame} @var{high-frame} ]
2559 Display a list of the arguments for the frames between @var{low-frame}
2560 and @var{high-frame} (inclusive). If @var{low-frame} and
2561 @var{high-frame} are not provided, list the arguments for the whole call
2564 The @var{show-values} argument must have a value of 0 or 1. A value of
2565 0 means that only the names of the arguments are listed, a value of 1
2566 means that both names and values of the arguments are printed.
2568 @subsubheading @value{GDBN} Command
2570 @value{GDBN} does not have an equivalent command. @code{gdbtk} has a
2571 @samp{gdb_get_args} command which partially overlaps with the
2572 functionality of @samp{-stack-list-arguments}.
2574 @subsubheading Example
2581 frame=@{level="0 ",addr="0x00010734",func="callee4",
2582 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
2583 frame=@{level="1 ",addr="0x0001076c",func="callee3",
2584 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
2585 frame=@{level="2 ",addr="0x0001078c",func="callee2",
2586 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
2587 frame=@{level="3 ",addr="0x000107b4",func="callee1",
2588 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
2589 frame=@{level="4 ",addr="0x000107e0",func="main",
2590 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
2592 -stack-list-arguments 0
2595 frame=@{level="0",args=[]@},
2596 frame=@{level="1",args=[name="strarg"]@},
2597 frame=@{level="2",args=[name="intarg",name="strarg"]@},
2598 frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@},
2599 frame=@{level="4",args=[]@}]
2601 -stack-list-arguments 1
2604 frame=@{level="0",args=[]@},
2606 args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
2607 frame=@{level="2",args=[
2608 @{name="intarg",value="2"@},
2609 @{name="strarg",value="0x11940 \"A string argument.\""@}]@},
2610 @{frame=@{level="3",args=[
2611 @{name="intarg",value="2"@},
2612 @{name="strarg",value="0x11940 \"A string argument.\""@},
2613 @{name="fltarg",value="3.5"@}]@},
2614 frame=@{level="4",args=[]@}]
2616 -stack-list-arguments 0 2 2
2617 ^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}]
2619 -stack-list-arguments 1 2 2
2620 ^done,stack-args=[frame=@{level="2",
2621 args=[@{name="intarg",value="2"@},
2622 @{name="strarg",value="0x11940 \"A string argument.\""@}]@}]
2626 @c @subheading -stack-list-exception-handlers
2629 @subheading The @code{-stack-list-frames} Command
2630 @findex -stack-list-frames
2632 @subsubheading Synopsis
2635 -stack-list-frames [ @var{low-frame} @var{high-frame} ]
2638 List the frames currently on the stack. For each frame it displays the
2643 The frame number, 0 being the topmost frame, i.e. the innermost function.
2645 The @code{$pc} value for that frame.
2649 File name of the source file where the function lives.
2651 Line number corresponding to the @code{$pc}.
2654 If invoked without arguments, this command prints a backtrace for the
2655 whole stack. If given two integer arguments, it shows the frames whose
2656 levels are between the two arguments (inclusive). If the two arguments
2657 are equal, it shows the single frame at the corresponding level.
2659 @subsubheading @value{GDBN} Command
2661 The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
2663 @subsubheading Example
2665 Full stack backtrace:
2671 [frame=@{level="0 ",addr="0x0001076c",func="foo",
2672 file="recursive2.c",line="11"@},
2673 frame=@{level="1 ",addr="0x000107a4",func="foo",
2674 file="recursive2.c",line="14"@},
2675 frame=@{level="2 ",addr="0x000107a4",func="foo",
2676 file="recursive2.c",line="14"@},
2677 frame=@{level="3 ",addr="0x000107a4",func="foo",
2678 file="recursive2.c",line="14"@},
2679 frame=@{level="4 ",addr="0x000107a4",func="foo",
2680 file="recursive2.c",line="14"@},
2681 frame=@{level="5 ",addr="0x000107a4",func="foo",
2682 file="recursive2.c",line="14"@},
2683 frame=@{level="6 ",addr="0x000107a4",func="foo",
2684 file="recursive2.c",line="14"@},
2685 frame=@{level="7 ",addr="0x000107a4",func="foo",
2686 file="recursive2.c",line="14"@},
2687 frame=@{level="8 ",addr="0x000107a4",func="foo",
2688 file="recursive2.c",line="14"@},
2689 frame=@{level="9 ",addr="0x000107a4",func="foo",
2690 file="recursive2.c",line="14"@},
2691 frame=@{level="10",addr="0x000107a4",func="foo",
2692 file="recursive2.c",line="14"@},
2693 frame=@{level="11",addr="0x00010738",func="main",
2694 file="recursive2.c",line="4"@}]
2698 Show frames between @var{low_frame} and @var{high_frame}:
2702 -stack-list-frames 3 5
2704 [frame=@{level="3 ",addr="0x000107a4",func="foo",
2705 file="recursive2.c",line="14"@},
2706 frame=@{level="4 ",addr="0x000107a4",func="foo",
2707 file="recursive2.c",line="14"@},
2708 frame=@{level="5 ",addr="0x000107a4",func="foo",
2709 file="recursive2.c",line="14"@}]
2713 Show a single frame:
2717 -stack-list-frames 3 3
2719 [frame=@{level="3 ",addr="0x000107a4",func="foo",
2720 file="recursive2.c",line="14"@}]
2725 @subheading The @code{-stack-list-locals} Command
2726 @findex -stack-list-locals
2728 @subsubheading Synopsis
2731 -stack-list-locals @var{print-values}
2734 Display the local variable names for the current frame. With an
2735 argument of 0 prints only the names of the variables, with argument of 1
2736 prints also their values.
2738 @subsubheading @value{GDBN} Command
2740 @samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
2742 @subsubheading Example
2746 -stack-list-locals 0
2747 ^done,locals=[name="A",name="B",name="C"]
2749 -stack-list-locals 1
2750 ^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
2751 @{name="C",value="3"@}]
2756 @subheading The @code{-stack-select-frame} Command
2757 @findex -stack-select-frame
2759 @subsubheading Synopsis
2762 -stack-select-frame @var{framenum}
2765 Change the current frame. Select a different frame @var{framenum} on
2768 @subsubheading @value{GDBN} Command
2770 The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
2771 @samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
2773 @subsubheading Example
2777 -stack-select-frame 2
2782 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2783 @node GDB/MI Symbol Query
2784 @section @sc{gdb/mi} Symbol Query Commands
2787 @subheading The @code{-symbol-info-address} Command
2788 @findex -symbol-info-address
2790 @subsubheading Synopsis
2793 -symbol-info-address @var{symbol}
2796 Describe where @var{symbol} is stored.
2798 @subsubheading @value{GDBN} Command
2800 The corresponding @value{GDBN} command is @samp{info address}.
2802 @subsubheading Example
2806 @subheading The @code{-symbol-info-file} Command
2807 @findex -symbol-info-file
2809 @subsubheading Synopsis
2815 Show the file for the symbol.
2817 @subsubheading @value{GDBN} Command
2819 There's no equivalent @value{GDBN} command. @code{gdbtk} has
2820 @samp{gdb_find_file}.
2822 @subsubheading Example
2826 @subheading The @code{-symbol-info-function} Command
2827 @findex -symbol-info-function
2829 @subsubheading Synopsis
2832 -symbol-info-function
2835 Show which function the symbol lives in.
2837 @subsubheading @value{GDBN} Command
2839 @samp{gdb_get_function} in @code{gdbtk}.
2841 @subsubheading Example
2845 @subheading The @code{-symbol-info-line} Command
2846 @findex -symbol-info-line
2848 @subsubheading Synopsis
2854 Show the core addresses of the code for a source line.
2856 @subsubheading @value{GDBN} Command
2858 The corresponding @value{GDBN} comamnd is @samp{info line}.
2859 @code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
2861 @subsubheading Example
2865 @subheading The @code{-symbol-info-symbol} Command
2866 @findex -symbol-info-symbol
2868 @subsubheading Synopsis
2871 -symbol-info-symbol @var{addr}
2874 Describe what symbol is at location @var{addr}.
2876 @subsubheading @value{GDBN} Command
2878 The corresponding @value{GDBN} command is @samp{info symbol}.
2880 @subsubheading Example
2884 @subheading The @code{-symbol-list-functions} Command
2885 @findex -symbol-list-functions
2887 @subsubheading Synopsis
2890 -symbol-list-functions
2893 List the functions in the executable.
2895 @subsubheading @value{GDBN} Command
2897 @samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
2898 @samp{gdb_search} in @code{gdbtk}.
2900 @subsubheading Example
2904 @subheading The @code{-symbol-list-types} Command
2905 @findex -symbol-list-types
2907 @subsubheading Synopsis
2913 List all the type names.
2915 @subsubheading @value{GDBN} Command
2917 The corresponding commands are @samp{info types} in @value{GDBN},
2918 @samp{gdb_search} in @code{gdbtk}.
2920 @subsubheading Example
2924 @subheading The @code{-symbol-list-variables} Command
2925 @findex -symbol-list-variables
2927 @subsubheading Synopsis
2930 -symbol-list-variables
2933 List all the global and static variable names.
2935 @subsubheading @value{GDBN} Command
2937 @samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
2939 @subsubheading Example
2943 @subheading The @code{-symbol-locate} Command
2944 @findex -symbol-locate
2946 @subsubheading Synopsis
2952 @subsubheading @value{GDBN} Command
2954 @samp{gdb_loc} in @code{gdbtk}.
2956 @subsubheading Example
2960 @subheading The @code{-symbol-type} Command
2961 @findex -symbol-type
2963 @subsubheading Synopsis
2966 -symbol-type @var{variable}
2969 Show type of @var{variable}.
2971 @subsubheading @value{GDBN} Command
2973 The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
2974 @samp{gdb_obj_variable}.
2976 @subsubheading Example
2980 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2981 @node GDB/MI Target Manipulation
2982 @section @sc{gdb/mi} Target Manipulation Commands
2985 @subheading The @code{-target-attach} Command
2986 @findex -target-attach
2988 @subsubheading Synopsis
2991 -target-attach @var{pid} | @var{file}
2994 Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
2996 @subsubheading @value{GDBN} command
2998 The corresponding @value{GDBN} command is @samp{attach}.
3000 @subsubheading Example
3004 @subheading The @code{-target-compare-sections} Command
3005 @findex -target-compare-sections
3007 @subsubheading Synopsis
3010 -target-compare-sections [ @var{section} ]
3013 Compare data of section @var{section} on target to the exec file.
3014 Without the argument, all sections are compared.
3016 @subsubheading @value{GDBN} Command
3018 The @value{GDBN} equivalent is @samp{compare-sections}.
3020 @subsubheading Example
3024 @subheading The @code{-target-detach} Command
3025 @findex -target-detach
3027 @subsubheading Synopsis
3033 Disconnect from the remote target. There's no output.
3035 @subsubheading @value{GDBN} command
3037 The corresponding @value{GDBN} command is @samp{detach}.
3039 @subsubheading Example
3049 @subheading The @code{-target-download} Command
3050 @findex -target-download
3052 @subsubheading Synopsis
3058 Loads the executable onto the remote target.
3059 It prints out an update message every half second, which includes the fields:
3063 The name of the section.
3065 The size of what has been sent so far for that section.
3067 The size of the section.
3069 The total size of what was sent so far (the current and the previous sections).
3071 The size of the overall executable to download.
3075 Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
3076 @sc{gdb/mi} Output Syntax}).
3078 In addition, it prints the name and size of the sections, as they are
3079 downloaded. These messages include the following fields:
3083 The name of the section.
3085 The size of the section.
3087 The size of the overall executable to download.
3091 At the end, a summary is printed.
3093 @subsubheading @value{GDBN} Command
3095 The corresponding @value{GDBN} command is @samp{load}.
3097 @subsubheading Example
3099 Note: each status message appears on a single line. Here the messages
3100 have been broken down so that they can fit onto a page.
3105 +download,@{section=".text",section-size="6668",total-size="9880"@}
3106 +download,@{section=".text",section-sent="512",section-size="6668",
3107 total-sent="512",total-size="9880"@}
3108 +download,@{section=".text",section-sent="1024",section-size="6668",
3109 total-sent="1024",total-size="9880"@}
3110 +download,@{section=".text",section-sent="1536",section-size="6668",
3111 total-sent="1536",total-size="9880"@}
3112 +download,@{section=".text",section-sent="2048",section-size="6668",
3113 total-sent="2048",total-size="9880"@}
3114 +download,@{section=".text",section-sent="2560",section-size="6668",
3115 total-sent="2560",total-size="9880"@}
3116 +download,@{section=".text",section-sent="3072",section-size="6668",
3117 total-sent="3072",total-size="9880"@}
3118 +download,@{section=".text",section-sent="3584",section-size="6668",
3119 total-sent="3584",total-size="9880"@}
3120 +download,@{section=".text",section-sent="4096",section-size="6668",
3121 total-sent="4096",total-size="9880"@}
3122 +download,@{section=".text",section-sent="4608",section-size="6668",
3123 total-sent="4608",total-size="9880"@}
3124 +download,@{section=".text",section-sent="5120",section-size="6668",
3125 total-sent="5120",total-size="9880"@}
3126 +download,@{section=".text",section-sent="5632",section-size="6668",
3127 total-sent="5632",total-size="9880"@}
3128 +download,@{section=".text",section-sent="6144",section-size="6668",
3129 total-sent="6144",total-size="9880"@}
3130 +download,@{section=".text",section-sent="6656",section-size="6668",
3131 total-sent="6656",total-size="9880"@}
3132 +download,@{section=".init",section-size="28",total-size="9880"@}
3133 +download,@{section=".fini",section-size="28",total-size="9880"@}
3134 +download,@{section=".data",section-size="3156",total-size="9880"@}
3135 +download,@{section=".data",section-sent="512",section-size="3156",
3136 total-sent="7236",total-size="9880"@}
3137 +download,@{section=".data",section-sent="1024",section-size="3156",
3138 total-sent="7748",total-size="9880"@}
3139 +download,@{section=".data",section-sent="1536",section-size="3156",
3140 total-sent="8260",total-size="9880"@}
3141 +download,@{section=".data",section-sent="2048",section-size="3156",
3142 total-sent="8772",total-size="9880"@}
3143 +download,@{section=".data",section-sent="2560",section-size="3156",
3144 total-sent="9284",total-size="9880"@}
3145 +download,@{section=".data",section-sent="3072",section-size="3156",
3146 total-sent="9796",total-size="9880"@}
3147 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
3153 @subheading The @code{-target-exec-status} Command
3154 @findex -target-exec-status
3156 @subsubheading Synopsis
3162 Provide information on the state of the target (whether it is running or
3165 @subsubheading @value{GDBN} Command
3167 There's no equivalent @value{GDBN} command.
3169 @subsubheading Example
3173 @subheading The @code{-target-list-available-targets} Command
3174 @findex -target-list-available-targets
3176 @subsubheading Synopsis
3179 -target-list-available-targets
3182 List the possible targets to connect to.
3184 @subsubheading @value{GDBN} Command
3186 The corresponding @value{GDBN} command is @samp{help target}.
3188 @subsubheading Example
3192 @subheading The @code{-target-list-current-targets} Command
3193 @findex -target-list-current-targets
3195 @subsubheading Synopsis
3198 -target-list-current-targets
3201 Describe the current target.
3203 @subsubheading @value{GDBN} Command
3205 The corresponding information is printed by @samp{info file} (among
3208 @subsubheading Example
3212 @subheading The @code{-target-list-parameters} Command
3213 @findex -target-list-parameters
3215 @subsubheading Synopsis
3218 -target-list-parameters
3223 @subsubheading @value{GDBN} Command
3227 @subsubheading Example
3231 @subheading The @code{-target-select} Command
3232 @findex -target-select
3234 @subsubheading Synopsis
3237 -target-select @var{type} @var{parameters @dots{}}
3240 Connect @value{GDBN} to the remote target. This command takes two args:
3244 The type of target, for instance @samp{async}, @samp{remote}, etc.
3245 @item @var{parameters}
3246 Device names, host names and the like. @xref{Target Commands, ,
3247 Commands for managing targets}, for more details.
3250 The output is a connection notification, followed by the address at
3251 which the target program is, in the following form:
3254 ^connected,addr="@var{address}",func="@var{function name}",
3255 args=[@var{arg list}]
3258 @subsubheading @value{GDBN} Command
3260 The corresponding @value{GDBN} command is @samp{target}.
3262 @subsubheading Example
3266 -target-select async /dev/ttya
3267 ^connected,addr="0xfe00a300",func="??",args=[]
3271 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3272 @node GDB/MI Thread Commands
3273 @section @sc{gdb/mi} Thread Commands
3276 @subheading The @code{-thread-info} Command
3277 @findex -thread-info
3279 @subsubheading Synopsis
3285 @subsubheading @value{GDBN} command
3289 @subsubheading Example
3293 @subheading The @code{-thread-list-all-threads} Command
3294 @findex -thread-list-all-threads
3296 @subsubheading Synopsis
3299 -thread-list-all-threads
3302 @subsubheading @value{GDBN} Command
3304 The equivalent @value{GDBN} command is @samp{info threads}.
3306 @subsubheading Example
3310 @subheading The @code{-thread-list-ids} Command
3311 @findex -thread-list-ids
3313 @subsubheading Synopsis
3319 Produces a list of the currently known @value{GDBN} thread ids. At the
3320 end of the list it also prints the total number of such threads.
3322 @subsubheading @value{GDBN} Command
3324 Part of @samp{info threads} supplies the same information.
3326 @subsubheading Example
3328 No threads present, besides the main process:
3333 ^done,thread-ids=@{@},number-of-threads="0"
3343 ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3344 number-of-threads="3"
3349 @subheading The @code{-thread-select} Command
3350 @findex -thread-select
3352 @subsubheading Synopsis
3355 -thread-select @var{threadnum}
3358 Make @var{threadnum} the current thread. It prints the number of the new
3359 current thread, and the topmost frame for that thread.
3361 @subsubheading @value{GDBN} Command
3363 The corresponding @value{GDBN} command is @samp{thread}.
3365 @subsubheading Example
3372 *stopped,reason="end-stepping-range",thread-id="2",line="187",
3373 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
3377 thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3378 number-of-threads="3"
3381 ^done,new-thread-id="3",
3382 frame=@{level="0 ",func="vprintf",
3383 args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
3384 @{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
3388 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3389 @node GDB/MI Tracepoint Commands
3390 @section @sc{gdb/mi} Tracepoint Commands
3392 The tracepoint commands are not yet implemented.
3394 @c @subheading -trace-actions
3396 @c @subheading -trace-delete
3398 @c @subheading -trace-disable
3400 @c @subheading -trace-dump
3402 @c @subheading -trace-enable
3404 @c @subheading -trace-exists
3406 @c @subheading -trace-find
3408 @c @subheading -trace-frame-number
3410 @c @subheading -trace-info
3412 @c @subheading -trace-insert
3414 @c @subheading -trace-list
3416 @c @subheading -trace-pass-count
3418 @c @subheading -trace-save
3420 @c @subheading -trace-start
3422 @c @subheading -trace-stop
3425 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3426 @node GDB/MI Variable Objects
3427 @section @sc{gdb/mi} Variable Objects
3430 @subheading Motivation for Variable Objects in @sc{gdb/mi}
3432 For the implementation of a variable debugger window (locals, watched
3433 expressions, etc.), we are proposing the adaptation of the existing code
3434 used by @code{Insight}.
3436 The two main reasons for that are:
3440 It has been proven in practice (it is already on its second generation).
3443 It will shorten development time (needless to say how important it is
3447 The original interface was designed to be used by Tcl code, so it was
3448 slightly changed so it could be used through @sc{gdb/mi}. This section
3449 describes the @sc{gdb/mi} operations that will be available and gives some
3450 hints about their use.
3452 @emph{Note}: In addition to the set of operations described here, we
3453 expect the @sc{gui} implementation of a variable window to require, at
3454 least, the following operations:
3457 @item @code{-gdb-show} @code{output-radix}
3458 @item @code{-stack-list-arguments}
3459 @item @code{-stack-list-locals}
3460 @item @code{-stack-select-frame}
3463 @subheading Introduction to Variable Objects in @sc{gdb/mi}
3465 @cindex variable objects in @sc{gdb/mi}
3466 The basic idea behind variable objects is the creation of a named object
3467 to represent a variable, an expression, a memory location or even a CPU
3468 register. For each object created, a set of operations is available for
3469 examining or changing its properties.
3471 Furthermore, complex data types, such as C structures, are represented
3472 in a tree format. For instance, the @code{struct} type variable is the
3473 root and the children will represent the struct members. If a child
3474 is itself of a complex type, it will also have children of its own.
3475 Appropriate language differences are handled for C, C@t{++} and Java.
3477 When returning the actual values of the objects, this facility allows
3478 for the individual selection of the display format used in the result
3479 creation. It can be chosen among: binary, decimal, hexadecimal, octal
3480 and natural. Natural refers to a default format automatically
3481 chosen based on the variable type (like decimal for an @code{int}, hex
3482 for pointers, etc.).
3484 The following is the complete set of @sc{gdb/mi} operations defined to
3485 access this functionality:
3487 @multitable @columnfractions .4 .6
3488 @item @strong{Operation}
3489 @tab @strong{Description}
3491 @item @code{-var-create}
3492 @tab create a variable object
3493 @item @code{-var-delete}
3494 @tab delete the variable object and its children
3495 @item @code{-var-set-format}
3496 @tab set the display format of this variable
3497 @item @code{-var-show-format}
3498 @tab show the display format of this variable
3499 @item @code{-var-info-num-children}
3500 @tab tells how many children this object has
3501 @item @code{-var-list-children}
3502 @tab return a list of the object's children
3503 @item @code{-var-info-type}
3504 @tab show the type of this variable object
3505 @item @code{-var-info-expression}
3506 @tab print what this variable object represents
3507 @item @code{-var-show-attributes}
3508 @tab is this variable editable? does it exist here?
3509 @item @code{-var-evaluate-expression}
3510 @tab get the value of this variable
3511 @item @code{-var-assign}
3512 @tab set the value of this variable
3513 @item @code{-var-update}
3514 @tab update the variable and its children
3517 In the next subsection we describe each operation in detail and suggest
3520 @subheading Description And Use of Operations on Variable Objects
3522 @subheading The @code{-var-create} Command
3525 @subsubheading Synopsis
3528 -var-create @{@var{name} | "-"@}
3529 @{@var{frame-addr} | "*"@} @var{expression}
3532 This operation creates a variable object, which allows the monitoring of
3533 a variable, the result of an expression, a memory cell or a CPU
3536 The @var{name} parameter is the string by which the object can be
3537 referenced. It must be unique. If @samp{-} is specified, the varobj
3538 system will generate a string ``varNNNNNN'' automatically. It will be
3539 unique provided that one does not specify @var{name} on that format.
3540 The command fails if a duplicate name is found.
3542 The frame under which the expression should be evaluated can be
3543 specified by @var{frame-addr}. A @samp{*} indicates that the current
3544 frame should be used.
3546 @var{expression} is any expression valid on the current language set (must not
3547 begin with a @samp{*}), or one of the following:
3551 @samp{*@var{addr}}, where @var{addr} is the address of a memory cell
3554 @samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
3557 @samp{$@var{regname}} --- a CPU register name
3560 @subsubheading Result
3562 This operation returns the name, number of children and the type of the
3563 object created. Type is returned as a string as the ones generated by
3564 the @value{GDBN} CLI:
3567 name="@var{name}",numchild="N",type="@var{type}"
3571 @subheading The @code{-var-delete} Command
3574 @subsubheading Synopsis
3577 -var-delete @var{name}
3580 Deletes a previously created variable object and all of its children.
3582 Returns an error if the object @var{name} is not found.
3585 @subheading The @code{-var-set-format} Command
3586 @findex -var-set-format
3588 @subsubheading Synopsis
3591 -var-set-format @var{name} @var{format-spec}
3594 Sets the output format for the value of the object @var{name} to be
3597 The syntax for the @var{format-spec} is as follows:
3600 @var{format-spec} @expansion{}
3601 @{binary | decimal | hexadecimal | octal | natural@}
3605 @subheading The @code{-var-show-format} Command
3606 @findex -var-show-format
3608 @subsubheading Synopsis
3611 -var-show-format @var{name}
3614 Returns the format used to display the value of the object @var{name}.
3617 @var{format} @expansion{}
3622 @subheading The @code{-var-info-num-children} Command
3623 @findex -var-info-num-children
3625 @subsubheading Synopsis
3628 -var-info-num-children @var{name}
3631 Returns the number of children of a variable object @var{name}:
3638 @subheading The @code{-var-list-children} Command
3639 @findex -var-list-children
3641 @subsubheading Synopsis
3644 -var-list-children @var{name}
3647 Returns a list of the children of the specified variable object:
3650 numchild=@var{n},children=@{@{name=@var{name},
3651 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}@}
3655 @subheading The @code{-var-info-type} Command
3656 @findex -var-info-type
3658 @subsubheading Synopsis
3661 -var-info-type @var{name}
3664 Returns the type of the specified variable @var{name}. The type is
3665 returned as a string in the same format as it is output by the
3673 @subheading The @code{-var-info-expression} Command
3674 @findex -var-info-expression
3676 @subsubheading Synopsis
3679 -var-info-expression @var{name}
3682 Returns what is represented by the variable object @var{name}:
3685 lang=@var{lang-spec},exp=@var{expression}
3689 where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
3691 @subheading The @code{-var-show-attributes} Command
3692 @findex -var-show-attributes
3694 @subsubheading Synopsis
3697 -var-show-attributes @var{name}
3700 List attributes of the specified variable object @var{name}:
3703 status=@var{attr} [ ( ,@var{attr} )* ]
3707 where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
3709 @subheading The @code{-var-evaluate-expression} Command
3710 @findex -var-evaluate-expression
3712 @subsubheading Synopsis
3715 -var-evaluate-expression @var{name}
3718 Evaluates the expression that is represented by the specified variable
3719 object and returns its value as a string in the current format specified
3726 @subheading The @code{-var-assign} Command
3729 @subsubheading Synopsis
3732 -var-assign @var{name} @var{expression}
3735 Assigns the value of @var{expression} to the variable object specified
3736 by @var{name}. The object must be @samp{editable}.
3738 @subheading The @code{-var-update} Command
3741 @subsubheading Synopsis
3744 -var-update @{@var{name} | "*"@}
3747 Update the value of the variable object @var{name} by evaluating its
3748 expression after fetching all the new values from memory or registers.
3749 A @samp{*} causes all existing variable objects to be updated.
3752 @c change-log-default-name: "ChangeLog-mi"