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 (C) 2000, Free Software Foundation, Inc.
12 @c Contributed by Cygnus Solutions.
14 @c Permission is granted to make and distribute verbatim copies of this
15 @c manual provided the copyright notice and this permission notice are
16 @c preserved on all copies.
19 @c Permission is granted to process this file through TeX and print the
20 @c results, provided the printed document carries copying permission notice
21 @c identical to this one except for the removal of this paragraph (this
22 @c paragraph not being relevant to the printed manual).
25 @c Permission is granted to copy and distribute modified versions of this
26 @c manual under the conditions for verbatim copying, provided also that the
27 @c entire resulting derived work is distributed under the terms of a
28 @c permission notice identical to this one.
30 @c Permission is granted to copy and distribute translations of this manual
31 @c into another language, under the above conditions for modified versions.
34 @c @c This title page illustrates only one of the
35 @c @c two methods of forming a title page.
39 @c @subtitle Version 0.2
41 @c @author Andrew Cagney, Fernando Nasser and Elena Zannoni
43 @c @c The following two commands
44 @c @c start the copyright page.
46 @c @vskip 0pt plus 1filll
47 @c Permission is granted to make and distribute verbatim copies of this
48 @c manual provided the copyright notice and this permission notice are
49 @c preserved on all copies.
51 @c Copyright @copyright{} 2000, Free Software Foundation, Inc.
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 GDB. 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::
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 Misc 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 GDB 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 @code{"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 document}
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{}
186 The CLI commands are still handled by the @sc{mi} interpreter; their
187 output is described below.
190 The @code{@var{token}}, when present, is passed back when the command
194 Some @sc{mi} commands accept optional arguments as part of the parameter
195 list. Each option is identified by a leading @samp{-} (dash) and may be
196 followed by an optional argument parameter. Options occur first in the
197 parameter list and can be delimited from normal parameters using
198 @samp{--} (this is useful when some parameters begin with a dash).
205 We want easy access to the existing CLI syntax (for debugging).
208 We want it to be easy to spot a @sc{mi} operation.
211 @node GDB/MI Output Syntax
212 @subsection @sc{gdb/mi} Output Syntax
214 @cindex output syntax of @sc{gdb/mi}
215 @cindex @sc{gdb/mi}, output syntax
216 The output from @sc{gdb/mi} consists of zero or more out-of-band records
217 followed, optionally, by a single result record. The result record
218 being for the most recent command. The sequence of output records is
219 terminated by @samp{(gdb)}.
221 If an input command was prefixed with a @code{@var{token}} then the
222 corresponding output for that command will also be prefixed by that same
226 @item @var{output} @expansion{}
227 @code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
229 @item @var{result-record} @expansion{}
230 @code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
232 @item @var{out-of-band-record} @expansion{}
233 @code{@var{async-record} | @var{stream-record}}
235 @item @var{async-record} @expansion{}
236 @code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
238 @item @var{exec-async-output} @expansion{}
239 @code{[ @var{token} ] "*" @var{async-output}}
241 @item @var{status-async-output} @expansion{}
242 @code{[ @var{token} ] "+" @var{async-output}}
244 @item @var{notify-async-output} @expansion{}
245 @code{[ @var{token} ] "=" @var{async-output}}
247 @item @var{async-output} @expansion{}
248 @code{@var{async-class} ( "," @var{result} )* @var{nl}}
250 @item @var{result-class} @expansion{}
251 @code{"done" | "running" | "connected" | "error" | "exit"}
253 @item @var{async-class} @expansion{}
254 @code{"stopped" | @var{others}} (where @var{others} will be added
255 depending on the needs---this is still in development).
257 @item @var{result} @expansion{}
258 @code{[ @var{string} "=" ] @var{value}}
260 @item @var{value} @expansion{}
261 @code{@var{const} | "@{" @var{result} ( "," @var{result} )* "@}"}
263 @item @var{const} @expansion{}
264 @code{@var{c-string}}
266 @item @var{stream-record} @expansion{}
267 @code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
269 @item @var{console-stream-output} @expansion{}
270 @code{"~" @var{c-string}}
272 @item @var{target-stream-output} @expansion{}
273 @code{"@@" @var{c-string}}
275 @item @var{log-stream-output} @expansion{}
276 @code{"&" @var{c-string}}
278 @item @var{nl} @expansion{}
281 @item @var{token} @expansion{}
282 @emph{any sequence of digits}.
285 In addition, the following are still being developed:
289 This action is currently undefined.
296 All output sequences end in a single line containing a period.
299 The @code{@var{token}} is from the corresponding request. If an execution
300 command is interrupted by the @samp{-exec-interrupt} command, the
301 @var{token} associated with the `*stopped' message is the one of the
302 original execution command, not the one of the interrupt-command.
305 @cindex status output in @sc{gdb/mi}
306 @var{status-async-output} contains on-going status information about the
307 progress of a slow operation. It can be discarded. All status output is
308 prefixed by @samp{+}.
311 @cindex async output in @sc{gdb/mi}
312 @var{exec-async-output} contains asynchronous state change on the target
313 (stopped, started, disappeared). All async output is prefixed by
317 @cindex notify output in @sc{gdb/mi}
318 @var{notify-async-output} contains supplementary information that the
319 client should handle (e.g., a new breakpoint information). All notify
320 output is prefixed by @samp{=}.
323 @cindex console output in @sc{gdb/mi}
324 @var{console-stream-output} is output that should be displayed as is in the
325 console. It is the textual response to a CLI command. All the console
326 output is prefixed by @samp{~}.
329 @cindex target output in @sc{gdb/mi}
330 @var{target-stream-output} is the output produced by the target program.
331 All the target output is prefixed by @samp{@@}.
334 @cindex log output in @sc{gdb/mi}
335 @var{log-stream-output} is output text coming from GDB's internals, for
336 instance messages that should be displayed as part of an error log. All
337 the log output is prefixed by @samp{&}.
340 @xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
341 details about the various output records.
343 @node GDB/MI Simple Examples
344 @subsection Simple Examples of @sc{gdb/mi} Interaction
345 @cindex @sc{gdb/mi}, simple examples
347 This subsection presents several simple examples of interaction using
348 the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
349 following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
350 the output received from @sc{gdb/mi}.
352 @subsubheading Target Stop
354 Here's an example of stopping the inferior process:
365 <- *stop,reason="stop",address="0x123",source="a.c:123"
369 @subsubheading Simple CLI Command
371 Here's an example of a simple CLI command being passed through
372 @sc{gdb/mi} and on to the CLI.
380 @subsubheading Command With Side Effects
383 -> -symbol-file xyz.exe
384 <- *breakpoint,nr="3",address="0x123",source="a.c:123"
388 @subsubheading A Bad Command
390 Here's what happens if you pass a non-existent command:
394 <- error,"Rubbish not found"
398 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
400 @section @sc{gdb/mi} Compatibility with CLI
402 @cindex compatibility, @sc{gdb/mi} and CLI
403 @cindex @sc{gdb/mi}, compatibility with CLI
404 To help users familiar with the GDB's existing CLI interface, @sc{gdb/mi}
405 accepts existing CLI commands. As specified by the syntax, such
406 commands can be directly entered into the @sc{gdb/mi} interface and GDB will
409 This mechanism is provided as an aid to developers of @sc{gdb/mi}
410 clients and not as a reliable interface into the CLI. Since the command
411 is being interpreteted in an environment that assumes @sc{gdb/mi}
412 behaviour, the exact output of such commands is likely to end up being
413 an un-supported hybrid of @sc{gdb/mi} and CLI output.
415 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
416 @node GDB/MI Output Records
417 @section @sc{gdb/mi} Output Records
420 * GDB/MI Result Records::
421 * GDB/MI Stream Records::
422 * GDB/MI Out-of-band Records::
425 @node GDB/MI Result Records
426 @subsection @sc{gdb/mi} Result Records
428 @cindex result records in @sc{gdb/mi}
429 @cindex @sc{gdb/mi}, result records
430 In addition to a number of out-of-band notifications, the response to a
431 @sc{gdb/mi} command includes one of the following result indications:
435 @item "^done" [ "," @var{results} ]
436 The synchronous operation was successful, @code{@var{results}} is the return
441 @c Is this one correct? Should it be an out-of-band notification?
442 The asynchronous operation was successfully started. The target is
445 @item "^error" "," @var{c-string}
447 The operation failed. The @code{@var{c-string}} contains the corresponding
451 @node GDB/MI Stream Records
452 @subsection @sc{gdb/mi} Stream Records
454 @cindex @sc{gdb/mi}, stream records
455 @cindex stream records in @sc{gdb/mi}
456 GDB internally maintains a number of output streams: the console, the
457 target, and the log. The output intended for each of these streams is
458 funneled through the @sc{gdb/mi} interface using @dfn{stream records}.
460 Each stream record begins with a unique @dfn{prefix character} which
461 identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output
462 Syntax}). In addition to the prefix, each stream record contains a
463 @code{@var{string-output}}. This is either raw text (with an implicit new
464 line) or a quoted C string (which does not contain an implicit newline).
467 @item "~" @var{string-output}
468 The console output stream contains text that should be displayed in the
469 CLI console window. It contains the textual responses to CLI commands.
471 @item "@@" @var{string-output}
472 The target output stream contains any textual output from the running
475 @item "&" @var{string-output}
476 The LOG stream contains debugging messages being produced by GDB's
480 @node GDB/MI Out-of-band Records
481 @subsection @sc{gdb/mi} Out-of-band Records
483 @cindex out-of-band records in @sc{gdb/mi}
484 @cindex @sc{gdb/mi}, out-of-band records
485 @dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of
486 additional changes that have occurred. Those changes can either be a
487 consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
488 target activity (e.g., target stopped).
490 The following is a preliminary list of possible out-of-band records.
497 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
498 @node GDB/MI Command Description Format
499 @section @sc{gdb/mi} Command Description Format
501 The remaining sections describe blocks of commands. Each block of
502 commands is laid out in a fashion similar to this chapter.
504 Note the the line breaks shown in the examples are here only for
505 readability. They don't appear in the real output.
506 Also note that the commands with a non-available example (N.A.@:) are
509 @subheading Motivation
511 The motivation for this collection of commands
513 @subheading Introduction
515 A brief introduction to this collection of commands as a whole.
519 For each command in the block, the following is described:
521 @subsubheading Synopsis
524 -command @var{args}...
527 @subsubheading GDB Command
529 The corresponding GDB CLI command.
531 @subsubheading Result
533 @subsubheading Out-of-band
537 @subsubheading Example
540 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
541 @node GDB/MI Breakpoint Table Commands
542 @section @sc{gdb/mi} Breakpoint table commands
544 @cindex breakpoint commands for @sc{gdb/mi}
545 @cindex @sc{gdb/mi}, breakpoint commands
546 This section documents @sc{gdb/mi} commands for manipulating
549 @subheading The @code{-break-after} Command
552 @subsubheading Synopsis
555 -break-after @var{number} @var{count}
558 The breakpoint number @var{number} is not in effect until it has been
559 hit @var{count} times. To see how this is reflected in the output of
560 the @samp{-break-list} command, see the description of the
561 @samp{-break-list} command below.
563 @subsubheading GDB Command
565 The corresponding GDB command is @samp{ignore}.
567 @subsubheading Example
572 ^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@}
579 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
580 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
581 addr="0x000100d0",func="main",file="hello.c",line="5",times="0",
587 @subheading The @code{-break-catch} Command
590 @subheading The @code{-break-commands} Command
591 @findex -break-commands
595 @subheading -break-condition
596 @findex -break-condition
598 @subsubheading Synopsis
601 -break-condition @var{number} @var{expr}
604 Breakpoint @var{number} will stop the program only if the condition in
605 @var{expr} is true. The condition becomes part of the
606 @samp{-break-list} output (see the description of the @samp{-break-list}
609 @subsubheading GDB Command
611 The corresponding GDB command is @samp{condition}.
613 @subsubheading Example
621 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
622 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
623 addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",
624 times="0",ignore="3"@}@}
628 @subheading The @code{-break-delete} Command
629 @findex -break-delete
631 @subsubheading Synopsis
634 -break-delete ( @var{breakpoint} )+
637 Delete the breakpoint(s) whose number(s) are specified in the argument
638 list. This is obviously reflected in the breakpoint list.
640 @subsubheading GDB command
642 The corresponding GDB command is @samp{delete}.
644 @subsubheading Example
652 ^done,BreakpointTable=@{@}
656 @subheading The @code{-break-disable} Command
657 @findex -break-disable
659 @subsubheading Synopsis
662 -break-disable ( @var{breakpoint} )+
665 Disable the named @var{breakpoint}(s). The field @samp{enabled} in the
666 break list is now set to @samp{n} for the named @var{breakpoint}(s).
668 @subsubheading GDB Command
670 The corresponding GDB command is @samp{disable}.
672 @subsubheading Example
680 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
681 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
682 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@}
686 @subheading The @code{-break-enable} Command
687 @findex -break-enable
689 @subsubheading Synopsis
692 -break-enable ( @var{breakpoint} )+
695 Enable (previously disabled) @var{breakpoint}(s).
697 @subsubheading GDB Command
699 The corresponding GDB command is @samp{enable}.
701 @subsubheading Example
709 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
710 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
711 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@}
715 @subheading The @code{-break-info} Command
718 @subsubheading Synopsis
721 -break-info @var{breakpoint}
725 Get information about a single breakpoint.
727 @subsubheading GDB command
729 The corresponding GDB command is @samp{info break @var{breakpoint}}.
731 @subsubheading Example
734 @subheading The @code{-break-insert} Command
735 @findex -break-insert
737 @subsubheading Synopsis
740 -break-insert [ -t ] [ -h ] [ -r ]
741 [ -c @var{condition} ] [ -i @var{ignore-count} ]
742 [ -p @var{thread} ] [ @var{line} | @var{addr} ]
746 If specified, @var{line}, can be one of:
753 @item filename:linenum
754 @item filename:function
758 The possible optional parameters of this command are:
762 Insert a tempoary breakpoint.
764 Insert a hardware breakpoint.
765 @item -c @var{condition}
766 Make the breakpoint conditional on @var{condition}.
767 @item -i @var{ignore-count}
768 Initialize the @var{ignore-count}.
770 Insert a regular breakpoint in all the functions whose names match the
771 given regular expression. Other flags are not applicable to regular
775 @subsubheading Result
777 The result is in the form:
780 ^done,bkptno="@var{number}",func="@var{funcname}",
781 file="@var{filename}",line="@var{lineno}"
785 where @var{number} is the GDB number for this breakpoint, @var{funcname}
786 is the name of the function where the breakpoint was inserted,
787 @var{filename} is the name of the source file which contains this
788 function, and @var{lineno} is the source line number within that file.
790 Note: this format is open to change.
791 @c An out-of-band breakpoint instead of part of the result?
793 @subsubheading GDB Command
795 The corresponding GDB commands are @samp{break}, @samp{tbreak},
796 @samp{hbreak}, @samp{thbreak}, and @samp{rbreak}.
798 @subsubheading Example
803 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
806 ^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@}
809 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
810 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
811 addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@},
812 bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
813 addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}@}
815 -break-insert -r foo.*
817 ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@}
821 @subheading The @code{-break-list} Command
824 @subsubheading Synopsis
830 Displays the list of inserted breakpoints, showing the following fields:
834 number of the breakpoint
836 type of the breakpoint: @samp{breakpoint} or @samp{watchpoint}
838 should the breakpoint be deleted or disabled when it is hit: @samp{keep}
841 is the breakpoint enabled or no: @samp{y} or @samp{n}
843 memory location at which the breakpoint is set
845 logical location of the breakpoint, expressed by function name, file
848 number of times the breakpoint has been hit
851 If there are no breakpoints or watchpoints, the BreakpointTable field is
854 @subsubheading GDB Command
856 The corresponding GDB command is @samp{info break}.
858 @subsubheading Example
863 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
864 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
865 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
866 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
867 addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}@}
871 Here's an example of the result when there are no breakpoints:
876 ^done,BreakpointTable=@{@}
880 @subheading The @code{-break-watch} Command
883 @subsubheading Synopsis
886 -break-watch [ -a | -r ]
889 Create a watchpoint. With the @samp{-a} option it will create an
890 @dfn{access} watchpoint, i.e. a watchpoints that triggers either on a
891 read from or on a write to the memory location. With the @samp{-r}
892 option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will
893 trigger only when the memory location is accessed for reading. Without
894 either of the options, the watchpoint created is a regular watchpoint,
895 i.e. it will trigger when the memory location is accessed for writing.
896 @xref{Set Watchpoints, , Setting watchpoints}.
898 Note that @samp{-break-list} will report a single list of watchpoints and
899 breakpoints inserted.
901 @subsubheading GDB Command
903 The corresponding GDB commands are @samp{watch}, @samp{awatch}, and
906 @subsubheading Example
908 Setting a watchpoint on a variable in the @code{main} function:
913 ^done,wpt=@{number="2",exp="x"@}
917 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
918 value=@{old="-268439212",new="55"@},
919 frame=@{func="main",args=@{@},file="recursive2.c",line="5"@}
923 Setting a watchpoint on a variable local to a function. GDB will stop
924 the program execution twice: first for the variable changing value, then
925 for the watchpoint going out of scope.
930 ^done,wpt=@{number="5",exp="C"@}
934 ^done,reason="watchpoint-trigger",
935 wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
936 frame=@{func="callee4",args=@{@},
937 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
941 ^done,reason="watchpoint-scope",wpnum="5",
942 frame=@{func="callee3",args=@{@{name="strarg",
943 value="0x11940 \"A string argument.\""@}@},
944 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
948 Listing breakpoints and watchpoints, at different points in the program
949 execution. Note that once the watchpoint goes out of scope, it is
955 ^done,wpt=@{number="2",exp="C"@}
958 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
959 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
960 addr="0x00010734",func="callee4",
961 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
962 bkpt=@{number="2",type="watchpoint",disp="keep",
963 enabled="y",addr="",what="C",times="0"@}@}
967 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
968 value=@{old="-276895068",new="3"@},
969 frame=@{func="callee4",args=@{@},
970 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
973 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
974 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
975 addr="0x00010734",func="callee4",
976 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
977 bkpt=@{number="2",type="watchpoint",disp="keep",
978 enabled="y",addr="",what="C",times="-5"@}@}
982 ^done,reason="watchpoint-scope",wpnum="2",
983 frame=@{func="callee3",args=@{@{name="strarg",
984 value="0x11940 \"A string argument.\""@}@},
985 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
988 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
989 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
990 addr="0x00010734",func="callee4",
991 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}@}
995 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
996 @node GDB/MI Data Manipulation
997 @section @sc{gdb/mi} Data Manipulation
999 @cindex data manipulation, in @sc{gdb/mi}
1000 @cindex @sc{gdb/mi}, data manipulation
1001 This section describes the @sc{gdb/mi} commands that manipulate data:
1002 examine memory and registers, evaluate expressions, etc.
1004 @c REMOVED FROM THE INTERFACE.
1005 @c @subheading -data-assign
1006 @c Change the value of a program variable. Plenty of side effects.
1007 @c @subsubheading GDB command
1009 @c @subsubheading Example
1012 @subheading The @code{-data-disassemble} Command
1013 @findex -data-disassemble
1015 @subsubheading Synopsis
1019 [ -s @var{start-addr} -e @var{end-addr} ]
1020 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
1028 @item @var{start-addr}
1029 is the beginning address (or @code{$pc})
1030 @item @var{end-addr}
1032 @item @var{filename}
1033 is the name of the file to disassemble
1035 is the line number to disassemble around
1037 is the the number of disassembly lines to be produced. If it is -1,
1038 the whole function will be disassembled, in case no @var{end-add} is
1039 specified. If @var{end-addr} is specified as a non-zero value, and
1040 @var{lines} is lower that the number of disassembly lines between
1041 @var{start-addr} and @var{end-addr}, only @var{lines} lines are
1042 displayed; if @var{lines} is higher than the number of lines between
1043 @var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
1046 is either 0 (meaning only disassembly) or 1 (meaning mixed source and
1050 @subsubheading Result
1052 The output for each instruction is composed of two fields:
1061 Note that whatever included in the instruction field, is not manipulated
1062 directely by flathead, i.e. it is not possible to adjust its format.
1064 @subsubheading GDB Command
1066 There's no direct mapping from this command to the CLI.
1068 @subsubheading Example
1070 Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
1074 -data-disassemble -s $pc -e "$pc + 20" -- 0
1077 @{address="0x000107c0",func-name="main",offset="4",
1078 inst="mov 2, %o0"@},
1079 @{address="0x000107c4",func-name="main",offset="8",
1080 inst="sethi %hi(0x11800), %o2"@},
1081 @{address="0x000107c8",func-name="main",offset="12",
1082 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
1083 @{address="0x000107cc",func-name="main",offset="16",
1084 inst="sethi %hi(0x11800), %o2"@},
1085 @{address="0x000107d0",func-name="main",offset="20",
1086 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}@}
1090 Disassemble the whole @code{main} function. Line 32 is part of
1094 -data-disassemble -f basics.c -l 32 -- 0
1096 @{address="0x000107bc",func-name="main",offset="0",
1097 inst="save %sp, -112, %sp"@},
1098 @{address="0x000107c0",func-name="main",offset="4",
1099 inst="mov 2, %o0"@},
1100 @{address="0x000107c4",func-name="main",offset="8",
1101 inst="sethi %hi(0x11800), %o2"@},
1103 @{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
1104 @{address="0x00010820",func-name="main",offset="100",inst="restore "@}@}
1108 Disassemble 3 instruction from the start of @code{main}:
1112 -data-disassemble -f basics.c -l 32 -n 3 -- 0
1114 @{address="0x000107bc",func-name="main",offset="0",
1115 inst="save %sp, -112, %sp"@},
1116 @{address="0x000107c0",func-name="main",offset="4",
1117 inst="mov 2, %o0"@},
1118 @{address="0x000107c4",func-name="main",offset="8",
1119 inst="sethi %hi(0x11800), %o2"@}@}
1123 Disassemble 3 instruction from the start of @code{main} in mixed mode:
1127 -data-disassemble -f basics.c -l 32 -n 3 -- 1
1129 src_and_asm_line=@{line="31",
1130 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1131 testsuite/gdb.mi/basics.c",line_asm_insn=@{
1132 @{address="0x000107bc",func-name="main",offset="0",
1133 inst="save %sp, -112, %sp"@}@}@},
1135 src_and_asm_line=@{line="32",
1136 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1137 testsuite/gdb.mi/basics.c",line_asm_insn=@{
1138 @{address="0x000107c0",func-name="main",offset="4",
1139 inst="mov 2, %o0"@},
1140 @{address="0x000107c4",func-name="main",offset="8",
1141 inst="sethi %hi(0x11800), %o2"@}@}@}@}
1146 @subheading The @code{-data-evaluate-expression} Command
1147 @findex -data-evaluate-expression
1149 @subsubheading Synopsis
1152 -data-evaluate-expression @var{expr}
1155 Evaluate @var{expr} as an expression. The expression could contain an
1156 inferior function call. The function call will execute synchronously.
1157 If the expression contains spaces, it must be enclosed in double quotes.
1159 @subsubheading GDB Command
1161 The corresponding GDB commands are @samp{print}, @samp{output}, and
1162 @code{call}. In @code{gdbtk} only, there's a corresponding
1163 @samp{gdb_eval} command.
1165 @subsubheading Example
1167 In the following example, the numbers that precede the commands are the
1168 @dfn{tokens} described in @ref{GDB/MI Command Syntax, , @sc{gdb/mi}
1169 Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
1173 211-data-evaluate-expression A
1176 311-data-evaluate-expression &A
1177 311^done,value="0xefffeb7c"
1179 411-data-evaluate-expression A+3
1182 511-data-evaluate-expression "A + 3"
1188 @subheading The @code{-data-list-changed-registers} Command
1189 @findex -data-list-changed-registers
1191 @subsubheading Synopsis
1194 -data-list-changed-registers
1197 Display a list of the registers that have changed.
1199 @subsubheading GDB Command
1201 GDB doesn't have a direct analog for this command; @code{gdbtk} has the
1202 corresponding command @samp{gdb_changed_register_list}.
1204 @subsubheading Example
1214 *stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
1215 args=@{@},file="try.c",line="5"@}
1217 -data-list-changed-registers
1218 ^done,changed-registers=@{"0","1","2","4","5","6","7","8","9",
1219 "10","11","13","14","15","16","17","18","19","20","21","22","23",
1220 "24","25","26","27","28","30","31","64","65","66","67","69"@}
1225 @subheading The @code{-data-list-register-names} Command
1226 @findex -data-list-register-names
1228 @subsubheading Synopsis
1231 -data-list-register-names [ ( @var{regno} )+ ]
1234 Show a list of register names for the current target. If no arguments
1235 are given, it shows a list of the names of all the registers. If
1236 integer numbers are given as arguments, it will print a list of the
1237 names of the registers corresponding to the arguments.
1239 @subsubheading GDB Command
1241 GDB does not have a command which corresponds to
1242 @samp{-data-list-register-names}. In @code{gdbtk} there is a
1243 corresponding command @samp{gdb_regnames}.
1245 @subsubheading Example
1247 For the PPC MBX board:
1250 -data-list-register-names
1251 ^done,register-names=@{"r0","r1","r2","r3","r4","r5","r6","r7",
1252 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
1253 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
1254 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
1255 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
1256 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
1257 "pc","ps","cr","lr","ctr","xer"@}
1259 -data-list-register-names 1 2 3
1260 ^done,register-names=@{"r1","r2","r3"@}
1264 @subheading The @code{-data-list-register-values} Command
1265 @findex -data-list-register-values
1267 @subsubheading Synopsis
1270 -data-list-register-values @var{fmt} [ ( @var{regno} )*]
1273 Display the registers contents. @var{fmt} is the format according to
1274 which the registers contents are to be returned, followed by an optional
1275 list of numbers specifying the registers to display. A missing list of
1276 numbers indicates that the contents of all the registers must be returned.
1278 Allowed formats for @var{fmt} are:
1295 @subsubheading GDB Command
1297 The corresponding GDB commands are @samp{info reg}, @samp{info all-reg},
1298 and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
1300 @subsubheading Example
1302 For a PPC MBX board (note: line breaks are for readability only, they
1303 don't appear in the actual output):
1307 -data-list-register-values r 64 65
1308 ^done,register-values=@{@{number="64",value="0xfe00a300"@},
1309 @{number="65",value="0x00029002"@}@}
1311 -data-list-register-values x
1312 ^done,register-values=@{@{number="0",value="0xfe0043c8"@},
1313 @{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
1314 @{number="3",value="0x0"@},@{number="4",value="0xa"@},
1315 @{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
1316 @{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
1317 @{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
1318 @{number="11",value="0x1"@},@{number="12",value="0x0"@},
1319 @{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
1320 @{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
1321 @{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
1322 @{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
1323 @{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
1324 @{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
1325 @{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
1326 @{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
1327 @{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
1328 @{number="31",value="0x0"@},@{number="32",value="0x0"@},
1329 @{number="33",value="0x0"@},@{number="34",value="0x0"@},
1330 @{number="35",value="0x0"@},@{number="36",value="0x0"@},
1331 @{number="37",value="0x0"@},@{number="38",value="0x0"@},
1332 @{number="39",value="0x0"@},@{number="40",value="0x0"@},
1333 @{number="41",value="0x0"@},@{number="42",value="0x0"@},
1334 @{number="43",value="0x0"@},@{number="44",value="0x0"@},
1335 @{number="45",value="0x0"@},@{number="46",value="0x0"@},
1336 @{number="47",value="0x0"@},@{number="48",value="0x0"@},
1337 @{number="49",value="0x0"@},@{number="50",value="0x0"@},
1338 @{number="51",value="0x0"@},@{number="52",value="0x0"@},
1339 @{number="53",value="0x0"@},@{number="54",value="0x0"@},
1340 @{number="55",value="0x0"@},@{number="56",value="0x0"@},
1341 @{number="57",value="0x0"@},@{number="58",value="0x0"@},
1342 @{number="59",value="0x0"@},@{number="60",value="0x0"@},
1343 @{number="61",value="0x0"@},@{number="62",value="0x0"@},
1344 @{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
1345 @{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
1346 @{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
1347 @{number="69",value="0x20002b03"@}@}
1352 @subheading The @code{-data-read-memory} Command
1353 @findex -data-read-memory
1355 @subsubheading Synopsis
1358 -data-read-memory [ -o @var{byte-offset} ]
1359 @var{address} @var{word-format} @var{word-size}
1360 @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
1368 An expression specifying the address of the first memory word to be
1369 read. Complex expressions containing embedded white space should be
1370 quoted using the C convention.
1372 @item @var{word-format}
1373 The format to be used to print the memory words. The notation is the
1374 same as for GDB's @code{print} command (@pxref{Output Formats, , Output
1377 @item @var{word-size}
1378 The size of each memory word in bytes.
1381 The number of rows in the output table.
1384 The number of columns in the output table.
1387 If present, indicates that each row should include an @sc{ascii} dump. The
1388 value of @var{aschar} is used as a padding character when a byte is not a
1389 member of the printable @sc{ascii} character set (printable @sc{ascii}
1390 characters are those whose code is between 32 and 126, inclusively).
1392 @item @var{byte-offset}
1393 An offset to add to the @var{address} before fetching memory.
1396 This command displays memory contents as a table of @var{nr-rows} by
1397 @var{nr-cols} words, each word being @var{word-size} bytes. In total,
1398 @code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
1399 (returned as @samp{total-bytes}. Should less then the requested number
1400 of bytes be returned by the target, the missing words are identified
1401 using @samp{N/A}. The number of bytes read from the target is returned
1402 in @samp{nr-bytes} and the starting address used to read memory in
1405 The address of the next/previous page or row is available in
1406 @samp{next-row} and @samp{prev-row}, @samp{next-page} and
1409 @subsubheading GDB Command
1411 The corresponding GDB command is @samp{x}. @code{gdbtk} has
1412 @samp{gdb_get_mem} memory read.
1414 @subsubheading Example
1416 Read six bytes of memory starting at @code{bytes+6} but then offset by
1417 @code{-6} bytes. Format as three rows of two columns. One byte per
1418 word. Display each word in hex.
1422 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
1423 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
1424 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
1425 prev-page="0x0000138a",memory=@{
1426 @{addr="0x00001390",data=@{"0x00","0x01"@}@},
1427 @{addr="0x00001392",data=@{"0x02","0x03"@}@},
1428 @{addr="0x00001394",data=@{"0x04","0x05"@}@}@}
1432 Read two bytes of memory starting at address @code{shorts + 64} and
1433 display as a single word formatted in decimal.
1437 5-data-read-memory shorts+64 d 2 1 1
1438 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
1439 next-row="0x00001512",prev-row="0x0000150e",
1440 next-page="0x00001512",prev-page="0x0000150e",memory=@{
1441 @{addr="0x00001510",data=@{"128"@}@}@}
1445 Read thirty two bytes of memory starting at @code{bytes+16} and format
1446 as eight rows of four columns. Include a string encoding with @code{x}
1447 used as the non-printable character.
1451 4-data-read-memory bytes+16 x 1 8 4 x
1452 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
1453 next-row="0x000013c0",prev-row="0x0000139c",
1454 next-page="0x000013c0",prev-page="0x00001380",memory=@{
1455 @{addr="0x000013a0",data=@{"0x10","0x11","0x12","0x13"@},ascii="xxxx"@},
1456 @{addr="0x000013a4",data=@{"0x14","0x15","0x16","0x17"@},ascii="xxxx"@},
1457 @{addr="0x000013a8",data=@{"0x18","0x19","0x1a","0x1b"@},ascii="xxxx"@},
1458 @{addr="0x000013ac",data=@{"0x1c","0x1d","0x1e","0x1f"@},ascii="xxxx"@},
1459 @{addr="0x000013b0",data=@{"0x20","0x21","0x22","0x23"@},ascii=" !\"#"@},
1460 @{addr="0x000013b4",data=@{"0x24","0x25","0x26","0x27"@},ascii="$%&'"@},
1461 @{addr="0x000013b8",data=@{"0x28","0x29","0x2a","0x2b"@},ascii="()*+"@},
1462 @{addr="0x000013bc",data=@{"0x2c","0x2d","0x2e","0x2f"@},ascii=",-./"@}@}
1466 @subheading The @code{-display-delete} Command
1467 @findex -display-delete
1469 @subsubheading Synopsis
1472 -display-delete @var{number}
1475 Delete the display @var{number}.
1477 @subsubheading GDB Command
1479 The corresponding GDB command is @samp{delete display}.
1481 @subsubheading Example
1485 @subheading The @code{-display-disable} Command
1486 @findex -display-disable
1488 @subsubheading Synopsis
1491 -display-disable @var{number}
1494 Disable display @var{number}.
1496 @subsubheading GDB Command
1498 the corresponding GDB command is @samp{disable display}.
1500 @subsubheading Example
1504 @subheading The @code{-display-enable} Command
1505 @findex -display-enable
1507 @subsubheading Synopsis
1510 -display-enable @var{number}
1513 Enable display @var{number}.
1515 @subsubheading GDB Command
1517 The corresponding GDB command is @samp{enable display}.
1519 @subsubheading Example
1523 @subheading The @code{-display-insert} Command
1524 @findex -display-insert
1526 @subsubheading Synopsis
1529 -display-insert @var{expression}
1532 Display @var{expression} every time the program stops.
1534 @subsubheading GDB Command
1536 The corresponding GDB command is @samp{display}.
1538 @subsubheading Example
1542 @subheading The @code{-display-list} Command
1543 @findex -display-list
1545 @subsubheading Synopsis
1551 List the displays. Do not show the current values.
1553 @subsubheading GDB Command
1555 The corresponding GDB command is @samp{info display}.
1557 @subsubheading Example
1561 @subheading The @code{-environment-cd} Command
1562 @findex -environment-cd
1564 @subsubheading Synopsis
1567 -environment-cd @var{pathdir}
1570 Set GDB's working directory.
1572 @subsubheading GDB Command
1574 the corresponding GDB command is @samp{cd}.
1576 @subsubheading Example
1580 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1586 @subheading The @code{-environment-directory} Command
1587 @findex -environment-directory
1589 @subsubheading Synopsis
1592 -environment-directory @var{pathdir}
1595 Add directory @var{pathdir} to beginning of search path for source files.
1597 @subsubheading GDB Command
1599 The corresponding GDB command is @samp{dir}.
1601 @subsubheading Example
1605 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1611 @subheading The @code{-environment-path} Command
1612 @findex -environment-path
1614 @subsubheading Synopsis
1617 -environment-path ( @var{pathdir} )+
1620 Add directories to beginning of search path for object files.
1622 @subsubheading GDB Command
1624 The corresponding GDB command is @samp{path}.
1626 @subsubheading Example
1630 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb
1636 @subheading The @code{-environment-pwd} Command
1637 @findex -environment-pwd
1639 @subsubheading Synopsis
1645 Show the current working directory.
1647 @subsubheading GDB command
1649 The corresponding GDB command is @samp{pwd}.
1651 @subsubheading Example
1656 ~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb.
1661 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1662 @node GDB/MI Program Control
1663 @section @sc{gdb/mi} Program control
1665 @subsubheading Program termination
1667 As a result of execution, the inferior program can run to completion, if
1668 it doesn't encouter any breakpoints. In this case the ouput will
1669 include an exit code, if the program has exited exceptionally.
1671 @subsubheading Examples:
1674 Program exited normally:
1682 *stopped,reason="exited-normally"
1687 Program exited exceptionally:
1695 *stopped,reason="exited",exit-code="01"
1699 Another way the program can terminate is if it receives a signal such as
1700 @code{SIGINT}. In this case, @sc{gdb/mi} displays this:
1704 *stopped,reason="exited-signalled",signal-name="SIGINT",
1705 signal-meaning="Interrupt"
1709 @subheading The @code{-exec-abort} Command
1712 @subsubheading Synopsis
1718 Kill the inferior running program.
1720 @subsubheading GDB Command
1722 The corresponding GDB command is @samp{kill}.
1724 @subsubheading Example
1728 @subheading The @code{-exec-arguments} Command
1729 @findex -exec-arguments
1731 @subsubheading Synopsis
1734 -exec-arguments @var{args}
1737 Set the inferior program arguments, to be used in the next
1740 @subsubheading GDB Command
1742 The corresponding GDB command is @samp{set args}.
1744 @subsubheading Example
1747 Don't have one around.
1750 @subheading The @code{-exec-continue} Command
1751 @findex -exec-continue
1753 @subsubheading Synopsis
1759 Asynchronous command. Resumes the execution of the inferior program
1760 until a breakpoint is encountered, or until the inferior exits.
1762 @subsubheading GDB Command
1764 The corresponding GDB corresponding is @samp{continue}.
1766 @subsubheading Example
1773 *stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=@{@},
1774 file="hello.c",line="13"@}
1779 @subheading The @code{-exec-finish} Command
1780 @findex -exec-finish
1782 @subsubheading Synopsis
1788 Asynchronous command. Resumes the execution of the inferior program
1789 until the current function is exited. Displays the results returned by
1792 @subsubheading GDB Command
1794 The corresponding GDB command is @samp{finish}.
1796 @subsubheading Example
1798 Function returning @code{void}.
1805 *stopped,reason="function-finished",frame=@{func="main",args=@{@},
1806 file="hello.c",line="7"@}
1810 Function returning other than @code{void}. The name of the internal GDB
1811 variable storing the result is printed, together with the value itself.
1817 *stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
1818 args=@{@{name="a",value="1"@},@{name="b",value="9"@}@},
1819 file="recursive2.c",line="14"@},
1820 gdb-result-var="$1",return-value="0"
1825 @subheading The @code{-exec-interrupt} Command
1826 @findex -exec-interrupt
1828 @subsubheading Synopsis
1834 Asynchronous command. Interrupts the background execution of the target.
1835 Note how the token associated with the stop message is the one for the
1836 execution command that has been interrupted. The token for the interrupt
1837 itself only appears in the '^done' output. If the user is trying to
1838 interrupt a non-running program, an error message will be printed.
1840 @subsubheading GDB Command
1842 The corresponding GDB command is @samp{interrupt}.
1844 @subsubheading Example
1855 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
1856 frame=@{addr="0x00010140",func="foo",args=@{@},file="try.c",line="13"@}
1861 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
1866 @subheading The @code{-exec-next} Command
1869 @subsubheading Synopsis
1875 Asynchronous command. Resumes execution of the inferior program, stopping
1876 when the beginning of the next source line is reached.
1878 @subsubheading GDB Command
1880 The corresponding GDB command is @samp{next}.
1882 @subsubheading Example
1888 *stopped,reason="end-stepping-range",line="8",file="hello.c"
1893 @subheading The @code{-exec-next-instruction} Command
1894 @findex -exec-next-instruction
1896 @subsubheading Synopsis
1899 -exec-next-instruction
1902 Asynchronous command. Executes one machine instruction. If the
1903 instruction is a function call continues until the function returns. If
1904 the program stops at an instruction in the middle of a source line, the
1905 address will be printed as well.
1907 @subsubheading GDB Command
1909 The corresponding GDB command is @samp{nexti}.
1911 @subsubheading Example
1915 -exec-next-instruction
1919 *stopped,reason="end-stepping-range",
1920 addr="0x000100d4",line="5",file="hello.c"
1925 @subheading The @code{-exec-return} Command
1926 @findex -exec-return
1928 @subsubheading Synopsis
1934 Makes current function return immediately. Doesn't execute the inferior.
1935 Displays the new current frame.
1937 @subsubheading GDB Command
1939 The corresponding GDB command is @samp{return}.
1941 @subsubheading Example
1945 200-break-insert callee4
1946 200^done,bkpt=@{number="1",addr="0x00010734",
1947 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1952 000*stopped,reason="breakpoint-hit",bkptno="1",
1953 frame=@{func="callee4",args=@{@},
1954 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1960 111^done,frame=@{level="0 ",func="callee3",
1961 args=@{@{name="strarg",
1962 value="0x11940 \"A string argument.\""@}@},
1963 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1968 @subheading The @code{-exec-run} Command
1971 @subsubheading Synopsis
1977 Asynchronous command. Starts execution of the inferior from the
1978 beginning. The inferior executes until either a breakpoint is
1979 encountered or the program exits.
1981 @subsubheading GDB Command
1983 The corresponding GDB command is @samp{run}
1985 @subsubheading Example
1990 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
1995 *stopped,reason="breakpoint-hit",bkptno="1",
1996 frame=@{func="main",args=@{@},file="recursive2.c",line="4"@}
2001 @subheading The @code{-exec-show-arguments} Command
2002 @findex -exec-show-arguments
2004 @subsubheading Synopsis
2007 -exec-show-arguments
2010 Print the arguments of the program.
2012 @subsubheading GDB Command
2014 The corresponding GDB command is @samp{show args}.
2016 @subsubheading Example
2019 @c @subheading -exec-signal
2021 @subheading The @code{-exec-step} Command
2024 @subsubheading Synopsis
2030 Asynchronous command. Resumes execution of the inferior program, stopping
2031 when the beginning of the next source line is reached, if the next
2032 source line is not a function call. If it is, stop at the first
2033 instruction of the called function.
2035 @subsubheading GDB Command
2037 The corresponding GDB command is @samp{step}.
2039 @subsubheading Example
2041 Stepping into a function:
2047 *stopped,reason="end-stepping-range",
2048 frame=@{func="foo",args=@{@{name="a",value="10"@},
2049 @{name="b",value="0"@}@},file="recursive2.c",line="11"@}
2059 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
2064 @subheading The @code{-exec-step-instruction} Command
2065 @findex -exec-step-instruction
2067 @subsubheading Synopsis
2070 -exec-step-instruction
2073 Asynchronous command. Resumes the inferior which executes one machine
2074 instruction. The output, once stop, will vary depend on whether we have
2075 stopped in the middle of a source line or not. In the former case, the
2076 address at which the program stopped will be printed as well.
2078 @subsubheading GDB Command
2080 The corresponding GDB command is @samp{stepi}.
2082 @subsubheading Example
2086 -exec-step-instruction
2090 *stopped,reason="end-stepping-range",
2091 frame=@{func="foo",args=@{@},file="try.c",line="10"@}
2093 -exec-step-instruction
2097 *stopped,reason="end-stepping-range",
2098 frame=@{addr="0x000100f4",func="foo",args=@{@},file="try.c",line="10"@}
2103 @subheading The @code{-exec-until} Command
2106 @subsubheading Synopsis
2109 -exec-until [ @var{location} ]
2112 Asynchronous command. Executes the inferior until the @var{location}
2113 specified in the argument is reached. If there is no argument, the inferior
2114 executes until a source line greater than the current one is reached.
2115 The reason for stopping in this case will be ``location-reached''.
2117 @subsubheading GDB Command
2119 The corresponding GDB command is @samp{until}.
2121 @subsubheading Example
2125 -exec-until recursive2.c:6
2129 *stopped,reason="location-reached",frame=@{func="main",args=@{@},
2130 file="recursive2.c",line="6"@}
2135 @subheading -file-clear
2136 Is this going away????
2140 @subheading The @code{-file-exec-and-symbols} Command
2141 @findex -file-exec-and-symbols
2143 @subsubheading Synopsis
2146 -file-exec-and-symbols @var{file}
2149 Specify the executable file to be debugged. This file is the one from
2150 which the symbol table is also read. If no file is specified, the
2151 command clears the executable and symbol information. If breakpoints
2152 are set when using this command with no arguments, gdb will produce
2153 error messages. Oterwise, no output is produced, except a completion
2156 @subsubheading GDB Command
2158 The corresponding GDB command is @samp{file}.
2160 @subsubheading Example
2164 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2170 @subheading The @code{-file-exec-file} Command
2171 @findex -file-exec-file
2173 @subsubheading Synopsis
2176 -file-exec-file @var{file}
2179 Specify the executable file to be debugged. Unlike
2180 @samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
2181 from this file. If used without argument, GDB clears the information
2182 about the executable file. No output is produced, except a completion
2185 @subsubheading GDB Command
2187 The corresponding GDB command is @samp{exec-file}.
2189 @subsubheading Example
2193 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2199 @subheading The @code{-file-list-exec-sections} Command
2200 @findex -file-list-exec-sections
2202 @subsubheading Synopsis
2205 -file-list-exec-sections
2208 List the sections of the current executable file.
2210 @subsubheading GDB Command
2212 The GDB command @samp{info file} shows, among the rest, the same
2213 information as this command. @code{gdbtk} has a corresponding command
2214 @samp{gdb_load_info}.
2216 @subsubheading Example
2220 @subheading The @code{-file-list-exec-source-files} Command
2221 @findex -file-list-exec-source-files
2223 @subsubheading Synopsis
2226 -file-list-exec-source-files
2229 List the source files for the current executable.
2231 @subsubheading GDB Command
2233 There's no GDB command which directly corresponds to this one.
2234 @code{gdbtk} has an analogous command @samp{gdb_listfiles}.
2236 @subsubheading Example
2240 @subheading The @code{-file-list-shared-libraries} Command
2241 @findex -file-list-shared-libraries
2243 @subsubheading Synopsis
2246 -file-list-shared-libraries
2249 List the shared libraries in the program.
2251 @subsubheading GDB Command
2253 The corresponding GDB command os @samp{info shared}.
2255 @subsubheading Example
2259 @subheading The @code{-file-list-symbol-files} Command
2260 @findex -file-list-symbol-files
2262 @subsubheading Synopsis
2265 -file-list-symbol-files
2270 @subsubheading GDB Command
2272 The corresponding GDB command is @samp{info file} (part of it).
2274 @subsubheading Example
2278 @subheading The @code{-file-symbol-file} Command
2279 @findex -file-symbol-file
2281 @subsubheading Synopsis
2284 -file-symbol-file @var{file}
2287 Read symbol table info from the specified @var{file} argument. When
2288 used without arguments, clears GDB'S symbol table info. No output is
2289 produced, except for a completion notification.
2291 @subsubheading GDB Command
2293 The corresponding GDB command is @samp{symbol-file}.
2295 @subsubheading Example
2299 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2304 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2305 @node GDB/MI Misc Commands
2306 @section Misc GDB commands in @sc{gdb/mi}
2308 @c @subheading -gdb-complete
2310 @subheading The @code{-gdb-exit} Command
2313 @subsubheading Synopsis
2319 Exit GDB immediately.
2321 @subsubheading GDB Command
2323 Approximately corresponds to @samp{quit}.
2325 @subsubheading Example
2332 @subheading The @code{-gdb-set} Command
2335 @subsubheading Synopsis
2341 Set an internal GDB variable.
2342 @c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
2344 @subsubheading GDB Command
2346 The corresponding GDB command is @samp{set}.
2348 @subsubheading Example
2358 @subheading The @code{-gdb-show} Command
2361 @subsubheading Synopsis
2367 Show the current value of a GDB variable.
2369 @subsubheading GDB command
2371 The corresponding GDB command is @samp{show}.
2373 @subsubheading Example
2382 @c @subheading -gdb-source
2385 @subheading The @code{-gdb-version} Command
2386 @findex -gdb-version
2388 @subsubheading Synopsis
2394 Show version information for GDB. Used mostly in testing.
2396 @subsubheading GDB Command
2398 There's no equivalent GDB command. GDB by default shows this
2399 information when you start an interactive session.
2401 @subsubheading Example
2403 @c This example modifies the actual output from GDB to avoid overfull
2409 ~Copyright 2000 Free Software Foundation, Inc.
2410 ~GDB is free software, covered by the GNU General Public License, and
2411 ~you are welcome to change it and/or distribute copies of it under
2412 ~ certain conditions.
2413 ~Type "show copying" to see the conditions.
2414 ~There is absolutely no warranty for GDB. Type "show warranty" for
2416 ~This GDB was configured as
2417 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
2423 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2424 @node GDB/MI Kod Commands
2425 @section @sc{gdb/mi} Kod Commands
2427 The Kod commands are not implemented.
2429 @c @subheading -kod-info
2431 @c @subheading -kod-list
2433 @c @subheading -kod-list-object-types
2435 @c @subheading -kod-show
2437 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2438 @node GDB/MI Memory Overlay Commands
2439 @section @sc{gdb/mi} Memory Overlay Commands
2441 The memory overlay commands are not implemented.
2443 @c @subheading -overlay-auto
2445 @c @subheading -overlay-list-mapping-state
2447 @c @subheading -overlay-list-overlays
2449 @c @subheading -overlay-map
2451 @c @subheading -overlay-off
2453 @c @subheading -overlay-on
2455 @c @subheading -overlay-unmap
2457 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2458 @node GDB/MI Signal Handling Commands
2459 @section @sc{gdb/mi} Signal Handling Commands
2461 Signal handling commands are not implemented.
2463 @c @subheading -signal-handle
2465 @c @subheading -signal-list-handle-actions
2467 @c @subheading -signal-list-signal-types
2471 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2472 @node GDB/MI Stack Manipulation
2473 @section Stack manipulation commands in @sc{gdb/mi}
2476 @subheading The @code{-stack-info-frame} Command
2477 @findex -stack-info-frame
2479 @subsubheading Synopsis
2485 Get info on the current frame.
2487 @subsubheading GDB Command
2489 The corresponding GDB command is @samp{info frame} or @samp{frame}
2490 (without arguments).
2492 @subsubheading Example
2495 @subheading The @code{-stack-info-depth} Command
2496 @findex -stack-info-depth
2498 @subsubheading Synopsis
2501 -stack-info-depth [ @var{max-depth} ]
2504 Return the depth of the stack. If the integer argument @var{max-depth}
2505 is specified, do not count beyond @var{max-depth} frames.
2507 @subsubheading GDB Command
2509 There's no equivalent GDB command.
2511 @subsubheading Example
2513 For a stack with frame levels 0 through 11:
2523 -stack-info-depth 12
2526 -stack-info-depth 11
2529 -stack-info-depth 13
2534 @subheading The @code{-stack-list-arguments} Command
2535 @findex -stack-list-arguments
2537 @subsubheading Synopsis
2540 -stack-list-arguments @var{show-values}
2541 [ @var{low-frame} @var{high-frame} ]
2544 Display a list of the arguments for the frames between @var{low-frame}
2545 and @var{high-frame} (inclusive). If @var{low-frame} and
2546 @var{high-frame} are not provided, list the arguments for the whole call
2549 The @var{show-values} argument must have a value of 0 or 1. A value of
2550 0 means that only the names of the arguments are listed, a value of 1
2551 means that both names and values of the argumetns are printed.
2553 @subsubheading GDB Command
2555 GDB does not have an equivalent command. @code{gdbtk} has a
2556 @samp{gdb_get_args} command which partially overlaps with the
2557 functionality of @samp{-stack-list-arguments}.
2559 @subsubheading Example
2566 frame=@{level="0 ",addr="0x00010734",func="callee4",
2567 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
2568 frame=@{level="1 ",addr="0x0001076c",func="callee3",
2569 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
2570 frame=@{level="2 ",addr="0x0001078c",func="callee2",
2571 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
2572 frame=@{level="3 ",addr="0x000107b4",func="callee1",
2573 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
2574 frame=@{level="4 ",addr="0x000107e0",func="main",
2575 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}@}
2577 -stack-list-arguments 0
2580 frame=@{level="0",args=@{@}@},
2581 frame=@{level="1",args=@{name="strarg"@}@},
2582 frame=@{level="2",args=@{name="intarg",name="strarg"@}@},
2583 frame=@{level="3",args=@{name="intarg",name="strarg",name="fltarg"@}@},
2584 frame=@{level="4",args=@{@}@}@}
2586 -stack-list-arguments 1
2589 frame=@{level="0",args=@{@}@},
2591 args=@{@{name="strarg",value="0x11940 \"A string argument.\""@}@}@},
2592 frame=@{level="2",args=@{
2593 @{name="intarg",value="2"@},
2594 @{name="strarg",value="0x11940 \"A string argument.\""@}@}@},
2595 @{frame=@{level="3",args=@{
2596 @{name="intarg",value="2"@},
2597 @{name="strarg",value="0x11940 \"A string argument.\""@},
2598 @{name="fltarg",value="3.5"@}@}@},
2599 frame=@{level="4",args=@{@}@}@}
2601 -stack-list-arguments 0 2 2
2602 ^done,stack-args=@{frame=@{level="2",args=@{name="intarg",name="strarg"@}@}@}
2604 -stack-list-arguments 1 2 2
2605 ^done,stack-args=@{frame=@{level="2",
2606 args=@{@{name="intarg",value="2"@},
2607 @{name="strarg",value="0x11940 \"A string argument.\""@}@}@}@}
2611 @c @subheading -stack-list-exception-handlers
2614 @subheading The @code{-stack-list-frames} Command
2615 @findex -stack-list-frames
2617 @subsubheading Synopsis
2620 -stack-list-frames [ @var{low-frame} @var{high-frame} ]
2623 List the frames currently on the stack. For each frame it displays the
2628 The frame number, 0 being the topmost frame, i.e. the innermost function.
2630 The @code{$pc} value for that frame.
2634 File name of the source file where the function lives.
2636 Line number corresponding to the @code{$pc}.
2639 If invoked without arguments, this command prints a backtrace for the
2640 whole stack. If given two integer arguments, it shows the frames whose
2641 levels are between the two arguments (inclusive). If the two arguments
2642 are equal, it shows the single frame at the corresponding level.
2644 @subsubheading GDB Command
2646 The corresponding GDB commands are @samp{backtrace} and @samp{where}.
2648 @subsubheading Example
2650 Full stack backtrace:
2656 @{frame=@{level="0 ",addr="0x0001076c",func="foo",
2657 file="recursive2.c",line="11"@},
2658 frame=@{level="1 ",addr="0x000107a4",func="foo",
2659 file="recursive2.c",line="14"@},
2660 frame=@{level="2 ",addr="0x000107a4",func="foo",
2661 file="recursive2.c",line="14"@},
2662 frame=@{level="3 ",addr="0x000107a4",func="foo",
2663 file="recursive2.c",line="14"@},
2664 frame=@{level="4 ",addr="0x000107a4",func="foo",
2665 file="recursive2.c",line="14"@},
2666 frame=@{level="5 ",addr="0x000107a4",func="foo",
2667 file="recursive2.c",line="14"@},
2668 frame=@{level="6 ",addr="0x000107a4",func="foo",
2669 file="recursive2.c",line="14"@},
2670 frame=@{level="7 ",addr="0x000107a4",func="foo",
2671 file="recursive2.c",line="14"@},
2672 frame=@{level="8 ",addr="0x000107a4",func="foo",
2673 file="recursive2.c",line="14"@},
2674 frame=@{level="9 ",addr="0x000107a4",func="foo",
2675 file="recursive2.c",line="14"@},
2676 frame=@{level="10",addr="0x000107a4",func="foo",
2677 file="recursive2.c",line="14"@},
2678 frame=@{level="11",addr="0x00010738",func="main",
2679 file="recursive2.c",line="4"@}@}
2683 Show frames between low_frame and high_frame:
2687 -stack-list-frames 3 5
2689 @{frame=@{level="3 ",addr="0x000107a4",func="foo",
2690 file="recursive2.c",line="14"@},
2691 frame=@{level="4 ",addr="0x000107a4",func="foo",
2692 file="recursive2.c",line="14"@},
2693 frame=@{level="5 ",addr="0x000107a4",func="foo",
2694 file="recursive2.c",line="14"@}@}
2698 Show a single frame:
2702 -stack-list-frames 3 3
2704 @{frame=@{level="3 ",addr="0x000107a4",func="foo",
2705 file="recursive2.c",line="14"@}@}
2710 @subheading The @code{-stack-list-locals} Command
2711 @findex -stack-list-locals
2713 @subsubheading Synopsis
2716 -stack-list-locals @var{print-values}
2719 Display the local variables names for the current frame. With an
2720 argument of 0 prints only the names of the variables, with argument of 1
2721 prints also their values.
2723 @subsubheading GDB Command
2725 @samp{info locals} in GDB, @samp{gdb_get_locals} in @code{gdbtk}.
2727 @subsubheading Example
2731 -stack-list-locals 0
2732 ^done,locals=@{name="A",name="B",name="C"@}
2734 -stack-list-locals 1
2735 ^done,locals=@{@{name="A",value="1"@},@{name="B",value="2"@},
2736 @{name="C",value="3"@}@}
2741 @subheading The @code{-stack-select-frame} Command
2742 @findex -stack-select-frame
2744 @subsubheading Synopsis
2747 -stack-select-frame @var{framenum}
2750 Change the current frame. Select a different frame @var{framenum} on
2753 @subsubheading GDB Command
2755 The corresponding GDB commands are @samp{frame}, @samp{up}, @samp{down},
2756 @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
2758 @subsubheading Example
2762 -stack-select-frame 2
2767 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2768 @node GDB/MI Symbol Query
2769 @section @sc{gdb/mi} Symbol Query Commands
2772 @subheading The @code{-symbol-info-address} Command
2773 @findex -symbol-info-address
2775 @subsubheading Synopsis
2778 -symbol-info-address @var{symbol}
2781 Describe where @var{symbol} is stored.
2783 @subsubheading GDB Command
2785 the corresponding GDB command is @samp{info address}.
2787 @subsubheading Example
2791 @subheading The @code{-symbol-info-file} Command
2792 @findex -symbol-info-file
2794 @subsubheading Synopsis
2800 Show the file for the symbol.
2802 @subsubheading GDB Command
2804 There's no equivalent GDB command. @code{gdbtk} has
2805 @samp{gdb_filnd_file}.
2807 @subsubheading Example
2811 @subheading The @code{-symbol-info-function} Command
2812 @findex -symbol-info-function
2814 @subsubheading Synopsis
2817 -symbol-info-function
2820 Show which function the symbol lives in.
2822 @subsubheading GDB Command
2824 @samp{gdb_get_function} in @code{gdbtk}.
2826 @subsubheading Example
2830 @subheading The @code{-symbol-info-line} Command
2831 @findex -symbol-info-line
2833 @subsubheading Synopsis
2839 Show the core addresses of the code for a source line.
2841 @subsubheading GDB Command
2843 The corresponding GDB comamnd is @samp{info line}. @code{gdbtk} has the
2844 @samp{gdb_get_line} @samp{gdb_get_file} commands.
2846 @subsubheading Example
2850 @subheading The @code{-symbol-info-symbol} Command
2851 @findex -symbol-info-symbol
2853 @subsubheading Synopsis
2856 -symbol-info-symbol @var{addr}
2859 Describe what symbol is at location @var{addr}.
2861 @subsubheading GDB Command
2863 The corresponding GDB command is @samp{info symbol}.
2865 @subsubheading Example
2869 @subheading The @code{-symbol-list-functions} Command
2870 @findex -symbol-list-functions
2872 @subsubheading Synopsis
2875 -symbol-list-functions
2878 List the functions in the executable.
2880 @subsubheading GDB Command
2882 @samp{info functions} in GDB, @samp{gdb_listfunc} @samp{gdb_search} in
2885 @subsubheading Example
2889 @subheading The @code{-symbol-list-types} Command
2890 @findex -symbol-list-types
2892 @subsubheading Synopsis
2898 List all the type names.
2900 @subsubheading GDB Command
2902 The corresponding commands are @samp{info types} in GDB,
2903 @samp{gdb_search} in @code{gdbtk}.
2905 @subsubheading Example
2909 @subheading The @code{-symbol-list-variables} Command
2910 @findex -symbol-list-variables
2912 @subsubheading Synopsis
2915 -symbol-list-variables
2918 List all the global and static variable names.
2920 @subsubheading GDB Command
2922 @samp{info variables} in GDB, @samp{gdb_search} in @code{gdbtk}.
2924 @subsubheading Example
2928 @subheading The @code{-symbol-locate} Command
2929 @findex -symbol-locate
2931 @subsubheading Synopsis
2937 @subsubheading GDB Command
2939 @samp{gdb_loc} in @code{gdbtk}.
2941 @subsubheading Example
2945 @subheading The @code{-symbol-type} Command
2946 @findex -symbol-type
2948 @subsubheading Synopsis
2951 -symbol-type @var{variable}
2954 Show type of @var{variable}.
2956 @subsubheading GDB Command
2958 The corresponding GDB command is @samp{ptype}, @code{gdbtk} has
2959 @samp{gdb_obj_variable}.
2961 @subsubheading Example
2965 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2966 @node GDB/MI Target Manipulation
2967 @section @sc{gdb/mi} Target Manipulation Commands
2970 @subheading The @code{-target-attach} Command
2971 @findex -target-attach
2973 @subsubheading Synopsis
2976 -target-attach @var{pid} | @var{file}
2979 Attach to a process @var{pid} or a file @var{file} outside of GDB.
2981 @subsubheading GDB command
2983 The corresponding GDB command is @samp{attach}.
2985 @subsubheading Example
2989 @subheading The @code{-target-compare-sections} Command
2990 @findex -target-compare-sections
2992 @subsubheading Synopsis
2995 -target-compare-sections [ @var{section} ]
2998 Compare data of section @var{section} on target to the exec file.
2999 Without the argument, all sections are compared.
3001 @subsubheading GDB Command
3003 The GDB equivalent is @samp{compare-sections}.
3005 @subsubheading Example
3009 @subheading The @code{-target-detach} Command
3010 @findex -target-detach
3012 @subsubheading Synopsis
3018 Disconnect from the remote target. There's no output.
3020 @subsubheading GDB command
3022 The corresponding GDB command is @samp{detach}.
3024 @subsubheading Example
3034 @subheading The @code{-target-download} Command
3035 @findex -target-download
3037 @subsubheading Synopsis
3043 Loads the executable onto the remote target.
3044 It prints out an update message every half second, which includes the fields:
3048 The name of the section.
3050 The size of what has been sent so far for that section.
3052 The size of the section.
3054 The total size of what was sent so far (the current and the previous sections).
3056 The size of the overall executable to download.
3060 Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
3061 @sc{gdb/mi} Output Syntax}).
3063 In addition, it prints the name and size of the sections, as they are
3064 downloaded. These messages include the following fields:
3068 The name of the section.
3070 The size of the section.
3072 The size of the overall executable to download.
3076 At the end, a summary is printed.
3078 @subsubheading GDB Command
3080 The corresponding GDB command is @samp{load}.
3082 @subsubheading Example
3084 Note: each status message appears on a single line. Here the messages
3085 have been broken down, so they can fit into a page.
3090 +download,@{section=".text",section-size="6668",total-size="9880"@}
3091 +download,@{section=".text",section-sent="512",section-size="6668",
3092 total-sent="512",total-size="9880"@}
3093 +download,@{section=".text",section-sent="1024",section-size="6668",
3094 total-sent="1024",total-size="9880"@}
3095 +download,@{section=".text",section-sent="1536",section-size="6668",
3096 total-sent="1536",total-size="9880"@}
3097 +download,@{section=".text",section-sent="2048",section-size="6668",
3098 total-sent="2048",total-size="9880"@}
3099 +download,@{section=".text",section-sent="2560",section-size="6668",
3100 total-sent="2560",total-size="9880"@}
3101 +download,@{section=".text",section-sent="3072",section-size="6668",
3102 total-sent="3072",total-size="9880"@}
3103 +download,@{section=".text",section-sent="3584",section-size="6668",
3104 total-sent="3584",total-size="9880"@}
3105 +download,@{section=".text",section-sent="4096",section-size="6668",
3106 total-sent="4096",total-size="9880"@}
3107 +download,@{section=".text",section-sent="4608",section-size="6668",
3108 total-sent="4608",total-size="9880"@}
3109 +download,@{section=".text",section-sent="5120",section-size="6668",
3110 total-sent="5120",total-size="9880"@}
3111 +download,@{section=".text",section-sent="5632",section-size="6668",
3112 total-sent="5632",total-size="9880"@}
3113 +download,@{section=".text",section-sent="6144",section-size="6668",
3114 total-sent="6144",total-size="9880"@}
3115 +download,@{section=".text",section-sent="6656",section-size="6668",
3116 total-sent="6656",total-size="9880"@}
3117 +download,@{section=".init",section-size="28",total-size="9880"@}
3118 +download,@{section=".fini",section-size="28",total-size="9880"@}
3119 +download,@{section=".data",section-size="3156",total-size="9880"@}
3120 +download,@{section=".data",section-sent="512",section-size="3156",
3121 total-sent="7236",total-size="9880"@}
3122 +download,@{section=".data",section-sent="1024",section-size="3156",
3123 total-sent="7748",total-size="9880"@}
3124 +download,@{section=".data",section-sent="1536",section-size="3156",
3125 total-sent="8260",total-size="9880"@}
3126 +download,@{section=".data",section-sent="2048",section-size="3156",
3127 total-sent="8772",total-size="9880"@}
3128 +download,@{section=".data",section-sent="2560",section-size="3156",
3129 total-sent="9284",total-size="9880"@}
3130 +download,@{section=".data",section-sent="3072",section-size="3156",
3131 total-sent="9796",total-size="9880"@}
3132 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
3138 @subheading The @code{-target-exec-status} Command
3139 @findex -target-exec-status
3141 @subsubheading Synopsis
3147 Provide information on the state of the target (whether it is running or
3150 @subsubheading GDB Command
3152 There's no equivalent GDB command.
3154 @subsubheading Example
3158 @subheading The @code{-target-list-available-targets} Command
3159 @findex -target-list-available-targets
3161 @subsubheading Synopsis
3164 -target-list-available-targets
3167 List the possible targets to connect to.
3169 @subsubheading GDB Command
3171 The corresponding GDB command is @samp{help target}.
3173 @subsubheading Example
3177 @subheading The @code{-target-list-current-targets} Command
3178 @findex -target-list-current-targets
3180 @subsubheading Synopsis
3183 -target-list-current-targets
3186 Describe the current target.
3188 @subsubheading GDB Command
3190 The corresponding information is printed by @samp{info file} (among
3193 @subsubheading Example
3197 @subheading The @code{-target-list-parameters} Command
3198 @findex -target-list-parameters
3200 @subsubheading Synopsis
3203 -target-list-parameters
3208 @subsubheading GDB Command
3212 @subsubheading Example
3216 @subheading The @code{-target-select} Command
3217 @findex -target-select
3219 @subsubheading Synopsis
3222 -target-select @var{type} @var{parameters ...}
3225 Connect GDB to the remote target. This command takes two args:
3229 The type of target, for instance @samp{async}, @samp{remote}, etc.
3230 @item @var{parameters}
3231 Device names, host names and the like. @xref{Target Commands, ,
3232 Commands for managing targets}, for more details.
3235 The output is a connection notification, followed by the address at
3236 which the target program is, in the following form:
3239 ^connected,addr="@var{address}",func="@var{function name}",
3240 args=@{@var{arg list}@}
3243 @subsubheading GDB Command
3245 The corresponding GDB command is @samp{target}.
3247 @subsubheading Example
3251 -target-select async /dev/ttya
3252 ^connected,addr="0xfe00a300",func="??",args=@{@}
3256 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3257 @node GDB/MI Thread Commands
3258 @section @sc{gdb/mi} Thread Commands
3261 @subheading The @code{-thread-info} Command
3262 @findex -thread-info
3264 @subsubheading Synopsis
3270 @subsubheading GDB command
3274 @subsubheading Example
3278 @subheading The @code{-thread-list-all-threads} Command
3279 @findex -thread-list-all-threads
3281 @subsubheading Synopsis
3284 -thread-list-all-threads
3287 @subsubheading GDB Command
3289 The equivalent GDB command is @samp{info threads}.
3291 @subsubheading Example
3295 @subheading The @code{-thread-list-ids} Command
3296 @findex -thread-list-ids
3298 @subsubheading Synopsis
3304 Produces a list of the currently known gdb thread ids. At the end of the
3305 list it also prints the total number of such threads.
3307 @subsubheading GDB Command
3309 Part of @samp{info threads} supplies the same information.
3311 @subsubheading Example
3313 No threads present, besides the main process.
3318 ^done,thread-ids=@{@},number-of-threads="0"
3328 ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3329 number-of-threads="3"
3334 @subheading The @code{-thread-select} Command
3335 @findex -thread-select
3337 @subsubheading Synopsis
3340 -thread-select @var{threadnum}
3343 Make @var{threadnum} the current thread. It prints the number of the new
3344 current thread, and the topmost frame for that thread.
3346 @subsubheading GDB Command
3348 The corresponding GDB command is @samp{thread}.
3350 @subsubheading Example
3357 *stopped,reason="end-stepping-range",thread-id="2",line="187",
3358 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
3362 thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3363 number-of-threads="3"
3366 ^done,new-thread-id="3",
3367 frame=@{level="0 ",func="vprintf",
3368 args=@{@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
3369 @{name="arg",value="0x2"@}@},file="vprintf.c",line="31"@}
3373 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3374 @node GDB/MI Tracepoint Commands
3375 @section @sc{gdb/mi} Tracepoint Commands
3377 The tracepoint commands are not yet implemented.
3379 @c @subheading -trace-actions
3381 @c @subheading -trace-delete
3383 @c @subheading -trace-disable
3385 @c @subheading -trace-dump
3387 @c @subheading -trace-enable
3389 @c @subheading -trace-exists
3391 @c @subheading -trace-find
3393 @c @subheading -trace-frame-number
3395 @c @subheading -trace-info
3397 @c @subheading -trace-insert
3399 @c @subheading -trace-list
3401 @c @subheading -trace-pass-count
3403 @c @subheading -trace-save
3405 @c @subheading -trace-start
3407 @c @subheading -trace-stop
3410 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3411 @node GDB/MI Variable Objects
3412 @section @sc{gdb/mi} Variable Objects
3415 @subheading Motivation for Variable Objects in @sc{gdb/mi}
3417 For the implementation of a variable debugger window (locals, watched
3418 expressions, etc.), we are proposing the adaptation of the existent code
3419 used by @code{Insight}.
3421 The two main reasons for that are:
3425 It has been proven in practice (it is already on its second generation).
3428 It will shorten development time (needless to say how important it is
3432 The original interface was designed to be used by Tcl code, so it was
3433 slightly changed so it could be used through flathead. This document
3434 describes the flathead operations that will be available and gives some
3435 hints about their use.
3437 @emph{Note}: In addition to the set of operations described here, we
3438 expect the @sc{gui} implementation of a variable window to require, at
3439 least, the following operations:
3442 @item -gdb-show output-radix
3443 @item -stack-list-arguments
3444 @item -stack-list-locals
3445 @item -stack-select-frame
3448 @subheading Introduction to Variable Objects in @sc{gdb/mi}
3450 @cindex variable objects in @sc{gdb/mi}
3451 The basic idea behind variable objects is the creation of a named object
3452 to represent a variable, an expression, a memory location or even a CPU
3453 register. For each object created, a set of operations is available for
3454 examining or changing its properties.
3456 Furthermore, complex data types, such as C structures, are represented
3457 in a tree format. For instance, the @code{struct} type variable is the
3458 root and the children will represent the struct members. If a child
3459 is itself of a complex type, it will also have children of its own.
3460 Appropriate language differences are handled for C, C@t{++} and Java.
3462 When returning the actual values of the objects, this facility allows
3463 for the individual selection of the display format used in the result
3464 creation. It can be chosen among: binary, decimal, hexadecimal, octal
3465 and natural. Natural refers to the a default format automatically
3466 chosen based on the variable type (like decimal for an @code{int}, hex
3467 for pointers, etc.).
3469 The following is the complete set of flathead operations defined to
3470 access this functionality:
3472 @multitable @columnfractions .3 .6
3473 @item @strong{Operation}
3474 @tab @strong{Description}
3477 @tab create a variable object
3479 @tab delete the variable object and its children
3480 @item -var-set-format
3481 @tab set the display format of this variable
3482 @item -var-show-format
3483 @tab show the display format of this variable
3484 @item -var-info-num-children
3485 @tab tells how many children this object has
3486 @item -var-list-children
3487 @tab return a list of the object's children
3488 @item -var-info-type
3489 @tab show the type of this variable object
3490 @item -var-info-expression
3491 @tab print what this variable object represents
3492 @item -var-show-attributes
3493 @tab is this variable editable? does it exist here?
3494 @item -var-evaluate-expression
3495 @tab get the value of this variable
3497 @tab set the value of this variable
3499 @tab update the variable and its children
3502 In the next subsection we describe each operation in detail and suggest
3505 @subheading Description And Use of Operations on Variable Objects
3507 @subheading The @code{-var-create} Command
3510 @subsubheading Synopsis
3513 -var-create @{@var{name} | "-"@}
3514 @{@var{frame-addr} | "*"@} @var{expression}
3517 This operation creates a variable object, which allows the monitoring of
3518 a variable, the result of an expression, a memory cell or a CPU
3521 The @var{name} parameter is the string by which the object can be
3522 referenced. It must be unique. If @samp{-} is specified, the varobj
3523 system will generate a string "varNNNNNN'' automatically. It will be
3524 unique provided that one does not specify @var{name} on that format.
3525 The command fails if a duplicate name is found.
3527 The frame under which the expression should be evaluated can be
3528 specified by @var{frame-addr}. A @samp{*} indicates that the current
3529 frame should be used.
3531 Expression is any expression valid on the current language set (must not
3532 begin with a @samp{*}), or one of the following:
3536 @samp{*@var{addr}}, where @var{addr} is the address of a memory cell
3539 @samp{*@var{addr}-@var{addr}} -- a memory address range (TBD)
3542 @samp{$@var{regname}} -- a CPU register name
3545 @subsubheading Result
3547 This operation returns the name, number of children and the type of the
3548 object created. Type is returned as a string as the ones generated by
3552 name="@var{name}",numchild="N",type="@var{type}"
3556 @subheading The @code{-var-delete} Command
3559 @subsubheading Synopsis
3562 -var-delete @var{name}
3565 Deletes a previously created variable object and all of its children.
3567 Returns an error if the object @var{name} is not found.
3570 @subheading The @code{-var-set-format} Command
3571 @findex -var-set-format
3573 @subsubheading Synopsis
3576 -var-set-format @var{name} @var{format-spec}
3579 Sets the output format for the value of the object @var{name} to be
3582 The syntax for the @var{format-spec} is as follows:
3585 @var{format-spec} @expansion{}
3586 @{binary | decimal | hexadecimal | octal | natural@}
3590 @subheading The @code{-var-show-format} Command
3591 @findex -var-show-format
3593 @subsubheading Synopsis
3596 -var-show-format @var{name}
3599 Returns the format used to display the value of the object @var{name}.
3607 @subheading The @code{-var-info-num-children} Command
3608 @findex -var-info-num-children
3610 @subsubheading Synopsis
3613 -var-info-num-children @var{name}
3616 Returns the number of children of a variable object @var{name}:
3623 @subheading The @code{-var-list-children} Command
3624 @findex -var-list-children
3626 @subsubheading Synopsis
3629 -var-list-children @var{name}
3632 Returns a list of the children of the specified variable object:
3635 numchild=@var{n},children=@{@{name=@var{name},
3636 numchild=@var{n},type=@var{type}@},(repeats N times)@}
3640 @subheading The @code{-var-info-type} Command
3641 @findex -var-info-type
3643 @subsubheading Synopsis
3646 -var-info-type @var{name}
3649 Returns the type of the specified variable @var{name}. The type is
3650 returned as a string in the same format as it is output by the GDB CLI:
3657 @subheading The @code{-var-info-expression} Command
3658 @findex -var-info-expression
3660 @subsubheading Synopsis
3663 -var-info-expression @var{name}
3666 Returns what is represented by the variable object @var{name}:
3669 lang=@var{lang-spec},exp=@var{expression}
3673 where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
3675 @subheading The @code{-var-show-attributes} Command
3676 @findex -var-show-attributes
3678 @subsubheading Synopsis
3681 -var-show-attributes @var{name}
3684 List attributes of the specified variable object @var{name}:
3687 status=@var{attr} [ ( ,@var{attr} )* ]
3691 where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
3693 @subheading The @code{-var-evaluate-expression} Command
3694 @findex -var-evaluate-expression
3696 @subsubheading Synopsis
3699 -var-evaluate-expression @var{name}
3702 Evaluates the expression that is represented by the specified variable
3703 object and returns its value as a string in the current format specified
3710 @subheading The @code{-var-assign} Command
3713 @subsubheading Synopsis
3716 -var-assign @var{name} @var{expression}
3719 Assigns the value of @var{expression} to the variable object specified
3720 by @var{name}. The object must be ``editable''.
3722 @subheading The @code{-var-update} Command
3725 @subsubheading Synopsis
3728 -var-update @{@var{name} | "*"@}
3731 Update the value of the variable object @var{name} by evaluating its
3732 expression after fetching all the new values from memory or registers.
3733 A @samp{*} causes all existing variable objects to be updated.
3736 @c%%%%%%%%%%%%%%%%%%%%%%%%%%%% APPENDIX %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3737 @appendix Proposed v2.0 Output Syntax
3739 This appendix is not part of the MI specification. It is provided as a
3742 The output from @sc{gdb/mi} consists of zero or more out-of-band records
3743 optionally followed by a single result record. The result record being
3744 for the most recent command input. The sequence being terminated by
3747 Asynchronous @sc{gdb/mi} output is similar.
3749 Each output record directly associated with an input command is prefixed
3750 by the input commands @code{@var{token}}.
3753 @item @var{output} @expansion{}
3754 @{ @var{out-of-band-record} @} @code{[} @var{result-record} @code{]} "(gdb)" @var{nl}
3756 @item @var{result-record} @expansion{}
3757 @code{[} @var{token} @code{]} "^" @var{result-class} @{ "," @var{result} @} @var{nl}
3759 @item @var{out-of-band-record} @expansion{}
3760 @var{async-record} @code{|} @var{stream-record}
3762 @item @var{async-record} @expansion{}
3763 @var{exec-async-output} @code{|} @var{status-async-output} @code{|} @var{notify-async-output}
3765 @item @var{exec-async-output} @expansion{}
3766 @code{[} @var{token} @code{]} "*" @var{async-output}
3768 @item @var{status-async-output} @expansion{}
3769 @code{[} @var{token} @code{]} "+" @var{async-output}
3771 @item @var{notify-async-output} @expansion{}
3772 @code{[} @var{token} @code{]} "=" @var{async-output}
3774 @item @var{async-output} @expansion{}
3775 @var{async-class} @{ "," @var{result} @} @var{nl}
3777 @item @var{result-class} @expansion{}
3778 "done" @code{|} "running" @code{|} "connected" @code{|} "error" @code{|} "exit"
3780 @item @var{async-class} @expansion{}
3781 "stopped" @code{|} @emph{others depending on need as still in development}
3783 @item @var{result} @expansion{}
3784 @var{string} "=" @var{value}
3786 @item @var{value} @expansion{}
3787 @var{c-string} @code{|} @var{tupple} @code{|} @var{list}
3789 @item @var{tupple} @expansion{}
3790 "@{@}" @code{|} "@{" @var{result} @{ "," @var{result} @} "@}"
3792 @item @var{list} @expansion{}
3793 "@code{[]}" @code{|} "@code{[}" @var{value} @{ "," @var{value} @} "@code{]}"
3795 @item @var{string} @expansion{}
3796 @emph{[-A-Za-z\.0-9_]*}
3798 @item @var{c-string} @expansion{}
3799 @emph{See the input specification}
3801 @item @var{stream-record} @expansion{}
3802 @var{console-stream-output} @code{|} @var{target-stream-output} @code{|} @var{log-stream-output}
3804 @item @var{console-stream-output} @expansion{}
3807 @item @var{target-stream-output} @expansion{}
3810 @item @var{log-stream-output} @expansion{}
3813 @item @var{nl} @expansion{}
3816 @item @var{token} @expansion{}
3817 "any sequence of digits"
3821 In addition, the following are still being developed.
3826 This action is currently undefined.
3835 All output sequences end in a single line containing a period.
3838 The @code{@var{token}} is from the corresponding request. If an execution
3839 command is interrupted by the -exec-interrupt command, the token
3840 associated with the `*stopped' message is the one of the original
3841 execution command, not the one of the interrupt-command.
3844 @var{status-async-output} contains on-going status information about the progress
3845 of a slow operation. It can be discarded. All status output is prefixed by
3849 @var{exec-async-output} contains asynchronous state change on the target
3850 (stopped, started, disappeared). All async output is prefixed by
3854 @var{notify-async-output} contains supplementary information that the client should
3855 handle (new breakpoint information). All notify output is prefixed by
3859 @var{console-stream-output} is output that should be displayed as is in the
3860 console. It is the textual response to a CLI command. All the console
3861 output is prefixed by the prefix ``~''.
3864 @var{target-stream-output} is the output produced by the target program.
3865 All the target output is prefixed by the prefix ``@@''.
3868 @var{log-stream-output} is output text coming from GDB's internals, for
3869 instance messages that should be displayed as part of an error log. All
3870 the log output is prefixed by the prefix ``&''.
3878 @c change-log-default-name: "ChangeLog-mi"