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::
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 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::
120 * GDB/MI Draft Changes to Output Syntax::
123 @c When these are implemented, they should be moved to be between Misc and
124 @c Stack Manipulation in the above menu. They are now outside the menu
125 @c because makeinfo 3.12 barfs if it sees @ignore or @comments in the
128 * GDB/MI Kod Commands::
129 * GDB/MI Memory Overlay Commands::
130 * GDB/MI Signal Handling Commands::
133 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
134 @node GDB/MI Command Syntax
135 @section @sc{gdb/mi} Command Syntax
138 * GDB/MI Input Syntax::
139 * GDB/MI Output Syntax::
140 * GDB/MI Simple Examples::
143 @node GDB/MI Input Syntax
144 @subsection @sc{gdb/mi} Input Syntax
146 @cindex input syntax for @sc{gdb/mi}
147 @cindex @sc{gdb/mi}, input syntax
149 @item @var{command} @expansion{}
150 @code{@var{cli-command} | @var{mi-command}}
152 @item @var{cli-command} @expansion{}
153 @code{[ @var{token} ] @var{cli-command} @var{nl}}, where
154 @var{cli-command} is any existing GDB CLI command.
156 @item @var{mi-command} @expansion{}
157 @code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )*
158 @code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}}
160 @item @var{token} @expansion{}
161 @code{"any sequence of digits"}
163 @item @var{option} @expansion{}
164 @code{"-" @var{parameter} [ " " @var{parameter} ]}
166 @item @var{parameter} @expansion{}
167 @code{@var{non-blank-sequence} | @var{c-string}}
169 @item @var{operation} @expansion{}
170 @emph{any of the operations described in this document}
172 @item @var{non-blank-sequence} @expansion{}
173 @emph{anything, provided it doesn't contain special characters such as
174 "-", @var{nl}, """ and of course " "}
176 @item @var{c-string} @expansion{}
177 @code{""" @var{seven-bit-iso-c-string-content} """}
179 @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. The result record
219 being for the most recent command. The sequence of output records is
220 terminated by @samp{(gdb)}.
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{string} "=" ] @var{value}}
261 @item @var{value} @expansion{}
262 @code{@var{const} | "@{" @var{result} ( "," @var{result} )* "@}"}
264 @item @var{const} @expansion{}
265 @code{@var{c-string}}
267 @item @var{stream-record} @expansion{}
268 @code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
270 @item @var{console-stream-output} @expansion{}
271 @code{"~" @var{c-string}}
273 @item @var{target-stream-output} @expansion{}
274 @code{"@@" @var{c-string}}
276 @item @var{log-stream-output} @expansion{}
277 @code{"&" @var{c-string}}
279 @item @var{nl} @expansion{}
282 @item @var{token} @expansion{}
283 @emph{any sequence of digits}.
286 In addition, the following are still being developed:
290 This action is currently undefined.
297 All output sequences end in a single line containing a period.
300 The @code{@var{token}} is from the corresponding request. If an execution
301 command is interrupted by the @samp{-exec-interrupt} command, the
302 @var{token} associated with the `*stopped' message is the one of the
303 original execution command, not the one of the interrupt-command.
306 @cindex status output in @sc{gdb/mi}
307 @var{status-async-output} contains on-going status information about the
308 progress of a slow operation. It can be discarded. All status output is
309 prefixed by @samp{+}.
312 @cindex async output in @sc{gdb/mi}
313 @var{exec-async-output} contains asynchronous state change on the target
314 (stopped, started, disappeared). All async output is prefixed by
318 @cindex notify output in @sc{gdb/mi}
319 @var{notify-async-output} contains supplementary information that the
320 client should handle (e.g., a new breakpoint information). All notify
321 output is prefixed by @samp{=}.
324 @cindex console output in @sc{gdb/mi}
325 @var{console-stream-output} is output that should be displayed as is in the
326 console. It is the textual response to a CLI command. All the console
327 output is prefixed by @samp{~}.
330 @cindex target output in @sc{gdb/mi}
331 @var{target-stream-output} is the output produced by the target program.
332 All the target output is prefixed by @samp{@@}.
335 @cindex log output in @sc{gdb/mi}
336 @var{log-stream-output} is output text coming from GDB's internals, for
337 instance messages that should be displayed as part of an error log. All
338 the log output is prefixed by @samp{&}.
341 @xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
342 details about the various output records.
344 @xref{GDB/MI Draft Changes to Output Syntax, , @sc{gdb/mi} Draft Changes
345 to Output Syntax}, for proposed revisions to the current output syntax.
347 @node GDB/MI Simple Examples
348 @subsection Simple Examples of @sc{gdb/mi} Interaction
349 @cindex @sc{gdb/mi}, simple examples
351 This subsection presents several simple examples of interaction using
352 the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
353 following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
354 the output received from @sc{gdb/mi}.
356 @subsubheading Target Stop
358 Here's an example of stopping the inferior process:
369 <- *stop,reason="stop",address="0x123",source="a.c:123"
373 @subsubheading Simple CLI Command
375 Here's an example of a simple CLI command being passed through
376 @sc{gdb/mi} and on to the CLI.
384 @subsubheading Command With Side Effects
387 -> -symbol-file xyz.exe
388 <- *breakpoint,nr="3",address="0x123",source="a.c:123"
392 @subsubheading A Bad Command
394 Here's what happens if you pass a non-existent command:
398 <- error,"Rubbish not found"
402 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
403 @node GDB/MI Compatibility with CLI
404 @section @sc{gdb/mi} Compatibility with CLI
406 @cindex compatibility, @sc{gdb/mi} and CLI
407 @cindex @sc{gdb/mi}, compatibility with CLI
408 To help users familiar with the GDB's existing CLI interface, @sc{gdb/mi}
409 accepts existing CLI commands. As specified by the syntax, such
410 commands can be directly entered into the @sc{gdb/mi} interface and GDB will
413 This mechanism is provided as an aid to developers of @sc{gdb/mi}
414 clients and not as a reliable interface into the CLI. Since the command
415 is being interpreteted in an environment that assumes @sc{gdb/mi}
416 behaviour, the exact output of such commands is likely to end up being
417 an un-supported hybrid of @sc{gdb/mi} and CLI output.
419 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
420 @node GDB/MI Output Records
421 @section @sc{gdb/mi} Output Records
424 * GDB/MI Result Records::
425 * GDB/MI Stream Records::
426 * GDB/MI Out-of-band Records::
429 @node GDB/MI Result Records
430 @subsection @sc{gdb/mi} Result Records
432 @cindex result records in @sc{gdb/mi}
433 @cindex @sc{gdb/mi}, result records
434 In addition to a number of out-of-band notifications, the response to a
435 @sc{gdb/mi} command includes one of the following result indications:
439 @item "^done" [ "," @var{results} ]
440 The synchronous operation was successful, @code{@var{results}} is the return
445 @c Is this one correct? Should it be an out-of-band notification?
446 The asynchronous operation was successfully started. The target is
449 @item "^error" "," @var{c-string}
451 The operation failed. The @code{@var{c-string}} contains the corresponding
455 @node GDB/MI Stream Records
456 @subsection @sc{gdb/mi} Stream Records
458 @cindex @sc{gdb/mi}, stream records
459 @cindex stream records in @sc{gdb/mi}
460 GDB internally maintains a number of output streams: the console, the
461 target, and the log. The output intended for each of these streams is
462 funneled through the @sc{gdb/mi} interface using @dfn{stream records}.
464 Each stream record begins with a unique @dfn{prefix character} which
465 identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output
466 Syntax}). In addition to the prefix, each stream record contains a
467 @code{@var{string-output}}. This is either raw text (with an implicit new
468 line) or a quoted C string (which does not contain an implicit newline).
471 @item "~" @var{string-output}
472 The console output stream contains text that should be displayed in the
473 CLI console window. It contains the textual responses to CLI commands.
475 @item "@@" @var{string-output}
476 The target output stream contains any textual output from the running
479 @item "&" @var{string-output}
480 The LOG stream contains debugging messages being produced by GDB's
484 @node GDB/MI Out-of-band Records
485 @subsection @sc{gdb/mi} Out-of-band Records
487 @cindex out-of-band records in @sc{gdb/mi}
488 @cindex @sc{gdb/mi}, out-of-band records
489 @dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of
490 additional changes that have occurred. Those changes can either be a
491 consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
492 target activity (e.g., target stopped).
494 The following is a preliminary list of possible out-of-band records.
501 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
502 @node GDB/MI Command Description Format
503 @section @sc{gdb/mi} Command Description Format
505 The remaining sections describe blocks of commands. Each block of
506 commands is laid out in a fashion similar to this chapter.
508 Note the the line breaks shown in the examples are here only for
509 readability. They don't appear in the real output.
510 Also note that the commands with a non-available example (N.A.@:) are
513 @subheading Motivation
515 The motivation for this collection of commands
517 @subheading Introduction
519 A brief introduction to this collection of commands as a whole.
523 For each command in the block, the following is described:
525 @subsubheading Synopsis
528 -command @var{args}...
531 @subsubheading GDB Command
533 The corresponding GDB CLI command.
535 @subsubheading Result
537 @subsubheading Out-of-band
541 @subsubheading Example
544 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
545 @node GDB/MI Breakpoint Table Commands
546 @section @sc{gdb/mi} Breakpoint table commands
548 @cindex breakpoint commands for @sc{gdb/mi}
549 @cindex @sc{gdb/mi}, breakpoint commands
550 This section documents @sc{gdb/mi} commands for manipulating
553 @subheading The @code{-break-after} Command
556 @subsubheading Synopsis
559 -break-after @var{number} @var{count}
562 The breakpoint number @var{number} is not in effect until it has been
563 hit @var{count} times. To see how this is reflected in the output of
564 the @samp{-break-list} command, see the description of the
565 @samp{-break-list} command below.
567 @subsubheading GDB Command
569 The corresponding GDB command is @samp{ignore}.
571 @subsubheading Example
576 ^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@}
583 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
584 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
585 addr="0x000100d0",func="main",file="hello.c",line="5",times="0",
591 @subheading The @code{-break-catch} Command
594 @subheading The @code{-break-commands} Command
595 @findex -break-commands
599 @subheading -break-condition
600 @findex -break-condition
602 @subsubheading Synopsis
605 -break-condition @var{number} @var{expr}
608 Breakpoint @var{number} will stop the program only if the condition in
609 @var{expr} is true. The condition becomes part of the
610 @samp{-break-list} output (see the description of the @samp{-break-list}
613 @subsubheading GDB Command
615 The corresponding GDB command is @samp{condition}.
617 @subsubheading Example
625 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
626 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
627 addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",
628 times="0",ignore="3"@}@}
632 @subheading The @code{-break-delete} Command
633 @findex -break-delete
635 @subsubheading Synopsis
638 -break-delete ( @var{breakpoint} )+
641 Delete the breakpoint(s) whose number(s) are specified in the argument
642 list. This is obviously reflected in the breakpoint list.
644 @subsubheading GDB command
646 The corresponding GDB command is @samp{delete}.
648 @subsubheading Example
656 ^done,BreakpointTable=@{@}
660 @subheading The @code{-break-disable} Command
661 @findex -break-disable
663 @subsubheading Synopsis
666 -break-disable ( @var{breakpoint} )+
669 Disable the named @var{breakpoint}(s). The field @samp{enabled} in the
670 break list is now set to @samp{n} for the named @var{breakpoint}(s).
672 @subsubheading GDB Command
674 The corresponding GDB command is @samp{disable}.
676 @subsubheading Example
684 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
685 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
686 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@}
690 @subheading The @code{-break-enable} Command
691 @findex -break-enable
693 @subsubheading Synopsis
696 -break-enable ( @var{breakpoint} )+
699 Enable (previously disabled) @var{breakpoint}(s).
701 @subsubheading GDB Command
703 The corresponding GDB command is @samp{enable}.
705 @subsubheading Example
713 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
714 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
715 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@}
719 @subheading The @code{-break-info} Command
722 @subsubheading Synopsis
725 -break-info @var{breakpoint}
729 Get information about a single breakpoint.
731 @subsubheading GDB command
733 The corresponding GDB command is @samp{info break @var{breakpoint}}.
735 @subsubheading Example
738 @subheading The @code{-break-insert} Command
739 @findex -break-insert
741 @subsubheading Synopsis
744 -break-insert [ -t ] [ -h ] [ -r ]
745 [ -c @var{condition} ] [ -i @var{ignore-count} ]
746 [ -p @var{thread} ] [ @var{line} | @var{addr} ]
750 If specified, @var{line}, can be one of:
757 @item filename:linenum
758 @item filename:function
762 The possible optional parameters of this command are:
766 Insert a tempoary breakpoint.
768 Insert a hardware breakpoint.
769 @item -c @var{condition}
770 Make the breakpoint conditional on @var{condition}.
771 @item -i @var{ignore-count}
772 Initialize the @var{ignore-count}.
774 Insert a regular breakpoint in all the functions whose names match the
775 given regular expression. Other flags are not applicable to regular
779 @subsubheading Result
781 The result is in the form:
784 ^done,bkptno="@var{number}",func="@var{funcname}",
785 file="@var{filename}",line="@var{lineno}"
789 where @var{number} is the GDB number for this breakpoint, @var{funcname}
790 is the name of the function where the breakpoint was inserted,
791 @var{filename} is the name of the source file which contains this
792 function, and @var{lineno} is the source line number within that file.
794 Note: this format is open to change.
795 @c An out-of-band breakpoint instead of part of the result?
797 @subsubheading GDB Command
799 The corresponding GDB commands are @samp{break}, @samp{tbreak},
800 @samp{hbreak}, @samp{thbreak}, and @samp{rbreak}.
802 @subsubheading Example
807 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
810 ^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@}
813 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
814 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
815 addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@},
816 bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
817 addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}@}
819 -break-insert -r foo.*
821 ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@}
825 @subheading The @code{-break-list} Command
828 @subsubheading Synopsis
834 Displays the list of inserted breakpoints, showing the following fields:
838 number of the breakpoint
840 type of the breakpoint: @samp{breakpoint} or @samp{watchpoint}
842 should the breakpoint be deleted or disabled when it is hit: @samp{keep}
845 is the breakpoint enabled or no: @samp{y} or @samp{n}
847 memory location at which the breakpoint is set
849 logical location of the breakpoint, expressed by function name, file
852 number of times the breakpoint has been hit
855 If there are no breakpoints or watchpoints, the BreakpointTable field is
858 @subsubheading GDB Command
860 The corresponding GDB command is @samp{info break}.
862 @subsubheading Example
867 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
868 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
869 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
870 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
871 addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}@}
875 Here's an example of the result when there are no breakpoints:
880 ^done,BreakpointTable=@{@}
884 @subheading The @code{-break-watch} Command
887 @subsubheading Synopsis
890 -break-watch [ -a | -r ]
893 Create a watchpoint. With the @samp{-a} option it will create an
894 @dfn{access} watchpoint, i.e. a watchpoints that triggers either on a
895 read from or on a write to the memory location. With the @samp{-r}
896 option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will
897 trigger only when the memory location is accessed for reading. Without
898 either of the options, the watchpoint created is a regular watchpoint,
899 i.e. it will trigger when the memory location is accessed for writing.
900 @xref{Set Watchpoints, , Setting watchpoints}.
902 Note that @samp{-break-list} will report a single list of watchpoints and
903 breakpoints inserted.
905 @subsubheading GDB Command
907 The corresponding GDB commands are @samp{watch}, @samp{awatch}, and
910 @subsubheading Example
912 Setting a watchpoint on a variable in the @code{main} function:
917 ^done,wpt=@{number="2",exp="x"@}
921 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
922 value=@{old="-268439212",new="55"@},
923 frame=@{func="main",args=@{@},file="recursive2.c",line="5"@}
927 Setting a watchpoint on a variable local to a function. GDB will stop
928 the program execution twice: first for the variable changing value, then
929 for the watchpoint going out of scope.
934 ^done,wpt=@{number="5",exp="C"@}
938 ^done,reason="watchpoint-trigger",
939 wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
940 frame=@{func="callee4",args=@{@},
941 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
945 ^done,reason="watchpoint-scope",wpnum="5",
946 frame=@{func="callee3",args=@{@{name="strarg",
947 value="0x11940 \"A string argument.\""@}@},
948 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
952 Listing breakpoints and watchpoints, at different points in the program
953 execution. Note that once the watchpoint goes out of scope, it is
959 ^done,wpt=@{number="2",exp="C"@}
962 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
963 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
964 addr="0x00010734",func="callee4",
965 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
966 bkpt=@{number="2",type="watchpoint",disp="keep",
967 enabled="y",addr="",what="C",times="0"@}@}
971 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
972 value=@{old="-276895068",new="3"@},
973 frame=@{func="callee4",args=@{@},
974 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
977 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
978 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
979 addr="0x00010734",func="callee4",
980 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
981 bkpt=@{number="2",type="watchpoint",disp="keep",
982 enabled="y",addr="",what="C",times="-5"@}@}
986 ^done,reason="watchpoint-scope",wpnum="2",
987 frame=@{func="callee3",args=@{@{name="strarg",
988 value="0x11940 \"A string argument.\""@}@},
989 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
992 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
993 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
994 addr="0x00010734",func="callee4",
995 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}@}
999 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1000 @node GDB/MI Data Manipulation
1001 @section @sc{gdb/mi} Data Manipulation
1003 @cindex data manipulation, in @sc{gdb/mi}
1004 @cindex @sc{gdb/mi}, data manipulation
1005 This section describes the @sc{gdb/mi} commands that manipulate data:
1006 examine memory and registers, evaluate expressions, etc.
1008 @c REMOVED FROM THE INTERFACE.
1009 @c @subheading -data-assign
1010 @c Change the value of a program variable. Plenty of side effects.
1011 @c @subsubheading GDB command
1013 @c @subsubheading Example
1016 @subheading The @code{-data-disassemble} Command
1017 @findex -data-disassemble
1019 @subsubheading Synopsis
1023 [ -s @var{start-addr} -e @var{end-addr} ]
1024 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
1032 @item @var{start-addr}
1033 is the beginning address (or @code{$pc})
1034 @item @var{end-addr}
1036 @item @var{filename}
1037 is the name of the file to disassemble
1039 is the line number to disassemble around
1041 is the the number of disassembly lines to be produced. If it is -1,
1042 the whole function will be disassembled, in case no @var{end-add} is
1043 specified. If @var{end-addr} is specified as a non-zero value, and
1044 @var{lines} is lower that the number of disassembly lines between
1045 @var{start-addr} and @var{end-addr}, only @var{lines} lines are
1046 displayed; if @var{lines} is higher than the number of lines between
1047 @var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
1050 is either 0 (meaning only disassembly) or 1 (meaning mixed source and
1054 @subsubheading Result
1056 The output for each instruction is composed of two fields:
1065 Note that whatever included in the instruction field, is not manipulated
1066 directely by flathead, i.e. it is not possible to adjust its format.
1068 @subsubheading GDB Command
1070 There's no direct mapping from this command to the CLI.
1072 @subsubheading Example
1074 Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
1078 -data-disassemble -s $pc -e "$pc + 20" -- 0
1081 @{address="0x000107c0",func-name="main",offset="4",
1082 inst="mov 2, %o0"@},
1083 @{address="0x000107c4",func-name="main",offset="8",
1084 inst="sethi %hi(0x11800), %o2"@},
1085 @{address="0x000107c8",func-name="main",offset="12",
1086 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
1087 @{address="0x000107cc",func-name="main",offset="16",
1088 inst="sethi %hi(0x11800), %o2"@},
1089 @{address="0x000107d0",func-name="main",offset="20",
1090 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}@}
1094 Disassemble the whole @code{main} function. Line 32 is part of
1098 -data-disassemble -f basics.c -l 32 -- 0
1100 @{address="0x000107bc",func-name="main",offset="0",
1101 inst="save %sp, -112, %sp"@},
1102 @{address="0x000107c0",func-name="main",offset="4",
1103 inst="mov 2, %o0"@},
1104 @{address="0x000107c4",func-name="main",offset="8",
1105 inst="sethi %hi(0x11800), %o2"@},
1107 @{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
1108 @{address="0x00010820",func-name="main",offset="100",inst="restore "@}@}
1112 Disassemble 3 instruction from the start of @code{main}:
1116 -data-disassemble -f basics.c -l 32 -n 3 -- 0
1118 @{address="0x000107bc",func-name="main",offset="0",
1119 inst="save %sp, -112, %sp"@},
1120 @{address="0x000107c0",func-name="main",offset="4",
1121 inst="mov 2, %o0"@},
1122 @{address="0x000107c4",func-name="main",offset="8",
1123 inst="sethi %hi(0x11800), %o2"@}@}
1127 Disassemble 3 instruction from the start of @code{main} in mixed mode:
1131 -data-disassemble -f basics.c -l 32 -n 3 -- 1
1133 src_and_asm_line=@{line="31",
1134 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1135 testsuite/gdb.mi/basics.c",line_asm_insn=@{
1136 @{address="0x000107bc",func-name="main",offset="0",
1137 inst="save %sp, -112, %sp"@}@}@},
1139 src_and_asm_line=@{line="32",
1140 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1141 testsuite/gdb.mi/basics.c",line_asm_insn=@{
1142 @{address="0x000107c0",func-name="main",offset="4",
1143 inst="mov 2, %o0"@},
1144 @{address="0x000107c4",func-name="main",offset="8",
1145 inst="sethi %hi(0x11800), %o2"@}@}@}@}
1150 @subheading The @code{-data-evaluate-expression} Command
1151 @findex -data-evaluate-expression
1153 @subsubheading Synopsis
1156 -data-evaluate-expression @var{expr}
1159 Evaluate @var{expr} as an expression. The expression could contain an
1160 inferior function call. The function call will execute synchronously.
1161 If the expression contains spaces, it must be enclosed in double quotes.
1163 @subsubheading GDB Command
1165 The corresponding GDB commands are @samp{print}, @samp{output}, and
1166 @code{call}. In @code{gdbtk} only, there's a corresponding
1167 @samp{gdb_eval} command.
1169 @subsubheading Example
1171 In the following example, the numbers that precede the commands are the
1172 @dfn{tokens} described in @ref{GDB/MI Command Syntax, , @sc{gdb/mi}
1173 Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
1177 211-data-evaluate-expression A
1180 311-data-evaluate-expression &A
1181 311^done,value="0xefffeb7c"
1183 411-data-evaluate-expression A+3
1186 511-data-evaluate-expression "A + 3"
1192 @subheading The @code{-data-list-changed-registers} Command
1193 @findex -data-list-changed-registers
1195 @subsubheading Synopsis
1198 -data-list-changed-registers
1201 Display a list of the registers that have changed.
1203 @subsubheading GDB Command
1205 GDB doesn't have a direct analog for this command; @code{gdbtk} has the
1206 corresponding command @samp{gdb_changed_register_list}.
1208 @subsubheading Example
1218 *stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
1219 args=@{@},file="try.c",line="5"@}
1221 -data-list-changed-registers
1222 ^done,changed-registers=@{"0","1","2","4","5","6","7","8","9",
1223 "10","11","13","14","15","16","17","18","19","20","21","22","23",
1224 "24","25","26","27","28","30","31","64","65","66","67","69"@}
1229 @subheading The @code{-data-list-register-names} Command
1230 @findex -data-list-register-names
1232 @subsubheading Synopsis
1235 -data-list-register-names [ ( @var{regno} )+ ]
1238 Show a list of register names for the current target. If no arguments
1239 are given, it shows a list of the names of all the registers. If
1240 integer numbers are given as arguments, it will print a list of the
1241 names of the registers corresponding to the arguments.
1243 @subsubheading GDB Command
1245 GDB does not have a command which corresponds to
1246 @samp{-data-list-register-names}. In @code{gdbtk} there is a
1247 corresponding command @samp{gdb_regnames}.
1249 @subsubheading Example
1251 For the PPC MBX board:
1254 -data-list-register-names
1255 ^done,register-names=@{"r0","r1","r2","r3","r4","r5","r6","r7",
1256 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
1257 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
1258 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
1259 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
1260 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
1261 "pc","ps","cr","lr","ctr","xer"@}
1263 -data-list-register-names 1 2 3
1264 ^done,register-names=@{"r1","r2","r3"@}
1268 @subheading The @code{-data-list-register-values} Command
1269 @findex -data-list-register-values
1271 @subsubheading Synopsis
1274 -data-list-register-values @var{fmt} [ ( @var{regno} )*]
1277 Display the registers contents. @var{fmt} is the format according to
1278 which the registers contents are to be returned, followed by an optional
1279 list of numbers specifying the registers to display. A missing list of
1280 numbers indicates that the contents of all the registers must be returned.
1282 Allowed formats for @var{fmt} are:
1299 @subsubheading GDB Command
1301 The corresponding GDB commands are @samp{info reg}, @samp{info all-reg},
1302 and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
1304 @subsubheading Example
1306 For a PPC MBX board (note: line breaks are for readability only, they
1307 don't appear in the actual output):
1311 -data-list-register-values r 64 65
1312 ^done,register-values=@{@{number="64",value="0xfe00a300"@},
1313 @{number="65",value="0x00029002"@}@}
1315 -data-list-register-values x
1316 ^done,register-values=@{@{number="0",value="0xfe0043c8"@},
1317 @{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
1318 @{number="3",value="0x0"@},@{number="4",value="0xa"@},
1319 @{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
1320 @{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
1321 @{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
1322 @{number="11",value="0x1"@},@{number="12",value="0x0"@},
1323 @{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
1324 @{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
1325 @{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
1326 @{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
1327 @{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
1328 @{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
1329 @{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
1330 @{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
1331 @{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
1332 @{number="31",value="0x0"@},@{number="32",value="0x0"@},
1333 @{number="33",value="0x0"@},@{number="34",value="0x0"@},
1334 @{number="35",value="0x0"@},@{number="36",value="0x0"@},
1335 @{number="37",value="0x0"@},@{number="38",value="0x0"@},
1336 @{number="39",value="0x0"@},@{number="40",value="0x0"@},
1337 @{number="41",value="0x0"@},@{number="42",value="0x0"@},
1338 @{number="43",value="0x0"@},@{number="44",value="0x0"@},
1339 @{number="45",value="0x0"@},@{number="46",value="0x0"@},
1340 @{number="47",value="0x0"@},@{number="48",value="0x0"@},
1341 @{number="49",value="0x0"@},@{number="50",value="0x0"@},
1342 @{number="51",value="0x0"@},@{number="52",value="0x0"@},
1343 @{number="53",value="0x0"@},@{number="54",value="0x0"@},
1344 @{number="55",value="0x0"@},@{number="56",value="0x0"@},
1345 @{number="57",value="0x0"@},@{number="58",value="0x0"@},
1346 @{number="59",value="0x0"@},@{number="60",value="0x0"@},
1347 @{number="61",value="0x0"@},@{number="62",value="0x0"@},
1348 @{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
1349 @{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
1350 @{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
1351 @{number="69",value="0x20002b03"@}@}
1356 @subheading The @code{-data-read-memory} Command
1357 @findex -data-read-memory
1359 @subsubheading Synopsis
1362 -data-read-memory [ -o @var{byte-offset} ]
1363 @var{address} @var{word-format} @var{word-size}
1364 @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
1372 An expression specifying the address of the first memory word to be
1373 read. Complex expressions containing embedded white space should be
1374 quoted using the C convention.
1376 @item @var{word-format}
1377 The format to be used to print the memory words. The notation is the
1378 same as for GDB's @code{print} command (@pxref{Output Formats, , Output
1381 @item @var{word-size}
1382 The size of each memory word in bytes.
1385 The number of rows in the output table.
1388 The number of columns in the output table.
1391 If present, indicates that each row should include an @sc{ascii} dump. The
1392 value of @var{aschar} is used as a padding character when a byte is not a
1393 member of the printable @sc{ascii} character set (printable @sc{ascii}
1394 characters are those whose code is between 32 and 126, inclusively).
1396 @item @var{byte-offset}
1397 An offset to add to the @var{address} before fetching memory.
1400 This command displays memory contents as a table of @var{nr-rows} by
1401 @var{nr-cols} words, each word being @var{word-size} bytes. In total,
1402 @code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
1403 (returned as @samp{total-bytes}. Should less then the requested number
1404 of bytes be returned by the target, the missing words are identified
1405 using @samp{N/A}. The number of bytes read from the target is returned
1406 in @samp{nr-bytes} and the starting address used to read memory in
1409 The address of the next/previous page or row is available in
1410 @samp{next-row} and @samp{prev-row}, @samp{next-page} and
1413 @subsubheading GDB Command
1415 The corresponding GDB command is @samp{x}. @code{gdbtk} has
1416 @samp{gdb_get_mem} memory read.
1418 @subsubheading Example
1420 Read six bytes of memory starting at @code{bytes+6} but then offset by
1421 @code{-6} bytes. Format as three rows of two columns. One byte per
1422 word. Display each word in hex.
1426 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
1427 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
1428 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
1429 prev-page="0x0000138a",memory=@{
1430 @{addr="0x00001390",data=@{"0x00","0x01"@}@},
1431 @{addr="0x00001392",data=@{"0x02","0x03"@}@},
1432 @{addr="0x00001394",data=@{"0x04","0x05"@}@}@}
1436 Read two bytes of memory starting at address @code{shorts + 64} and
1437 display as a single word formatted in decimal.
1441 5-data-read-memory shorts+64 d 2 1 1
1442 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
1443 next-row="0x00001512",prev-row="0x0000150e",
1444 next-page="0x00001512",prev-page="0x0000150e",memory=@{
1445 @{addr="0x00001510",data=@{"128"@}@}@}
1449 Read thirty two bytes of memory starting at @code{bytes+16} and format
1450 as eight rows of four columns. Include a string encoding with @code{x}
1451 used as the non-printable character.
1455 4-data-read-memory bytes+16 x 1 8 4 x
1456 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
1457 next-row="0x000013c0",prev-row="0x0000139c",
1458 next-page="0x000013c0",prev-page="0x00001380",memory=@{
1459 @{addr="0x000013a0",data=@{"0x10","0x11","0x12","0x13"@},ascii="xxxx"@},
1460 @{addr="0x000013a4",data=@{"0x14","0x15","0x16","0x17"@},ascii="xxxx"@},
1461 @{addr="0x000013a8",data=@{"0x18","0x19","0x1a","0x1b"@},ascii="xxxx"@},
1462 @{addr="0x000013ac",data=@{"0x1c","0x1d","0x1e","0x1f"@},ascii="xxxx"@},
1463 @{addr="0x000013b0",data=@{"0x20","0x21","0x22","0x23"@},ascii=" !\"#"@},
1464 @{addr="0x000013b4",data=@{"0x24","0x25","0x26","0x27"@},ascii="$%&'"@},
1465 @{addr="0x000013b8",data=@{"0x28","0x29","0x2a","0x2b"@},ascii="()*+"@},
1466 @{addr="0x000013bc",data=@{"0x2c","0x2d","0x2e","0x2f"@},ascii=",-./"@}@}
1470 @subheading The @code{-display-delete} Command
1471 @findex -display-delete
1473 @subsubheading Synopsis
1476 -display-delete @var{number}
1479 Delete the display @var{number}.
1481 @subsubheading GDB Command
1483 The corresponding GDB command is @samp{delete display}.
1485 @subsubheading Example
1489 @subheading The @code{-display-disable} Command
1490 @findex -display-disable
1492 @subsubheading Synopsis
1495 -display-disable @var{number}
1498 Disable display @var{number}.
1500 @subsubheading GDB Command
1502 the corresponding GDB command is @samp{disable display}.
1504 @subsubheading Example
1508 @subheading The @code{-display-enable} Command
1509 @findex -display-enable
1511 @subsubheading Synopsis
1514 -display-enable @var{number}
1517 Enable display @var{number}.
1519 @subsubheading GDB Command
1521 The corresponding GDB command is @samp{enable display}.
1523 @subsubheading Example
1527 @subheading The @code{-display-insert} Command
1528 @findex -display-insert
1530 @subsubheading Synopsis
1533 -display-insert @var{expression}
1536 Display @var{expression} every time the program stops.
1538 @subsubheading GDB Command
1540 The corresponding GDB command is @samp{display}.
1542 @subsubheading Example
1546 @subheading The @code{-display-list} Command
1547 @findex -display-list
1549 @subsubheading Synopsis
1555 List the displays. Do not show the current values.
1557 @subsubheading GDB Command
1559 The corresponding GDB command is @samp{info display}.
1561 @subsubheading Example
1565 @subheading The @code{-environment-cd} Command
1566 @findex -environment-cd
1568 @subsubheading Synopsis
1571 -environment-cd @var{pathdir}
1574 Set GDB's working directory.
1576 @subsubheading GDB Command
1578 the corresponding GDB command is @samp{cd}.
1580 @subsubheading Example
1584 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1590 @subheading The @code{-environment-directory} Command
1591 @findex -environment-directory
1593 @subsubheading Synopsis
1596 -environment-directory @var{pathdir}
1599 Add directory @var{pathdir} to beginning of search path for source files.
1601 @subsubheading GDB Command
1603 The corresponding GDB command is @samp{dir}.
1605 @subsubheading Example
1609 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1615 @subheading The @code{-environment-path} Command
1616 @findex -environment-path
1618 @subsubheading Synopsis
1621 -environment-path ( @var{pathdir} )+
1624 Add directories to beginning of search path for object files.
1626 @subsubheading GDB Command
1628 The corresponding GDB command is @samp{path}.
1630 @subsubheading Example
1634 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb
1640 @subheading The @code{-environment-pwd} Command
1641 @findex -environment-pwd
1643 @subsubheading Synopsis
1649 Show the current working directory.
1651 @subsubheading GDB command
1653 The corresponding GDB command is @samp{pwd}.
1655 @subsubheading Example
1660 ~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb.
1665 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1666 @node GDB/MI Program Control
1667 @section @sc{gdb/mi} Program control
1669 @subsubheading Program termination
1671 As a result of execution, the inferior program can run to completion, if
1672 it doesn't encouter any breakpoints. In this case the ouput will
1673 include an exit code, if the program has exited exceptionally.
1675 @subsubheading Examples:
1678 Program exited normally:
1686 *stopped,reason="exited-normally"
1691 Program exited exceptionally:
1699 *stopped,reason="exited",exit-code="01"
1703 Another way the program can terminate is if it receives a signal such as
1704 @code{SIGINT}. In this case, @sc{gdb/mi} displays this:
1708 *stopped,reason="exited-signalled",signal-name="SIGINT",
1709 signal-meaning="Interrupt"
1713 @subheading The @code{-exec-abort} Command
1716 @subsubheading Synopsis
1722 Kill the inferior running program.
1724 @subsubheading GDB Command
1726 The corresponding GDB command is @samp{kill}.
1728 @subsubheading Example
1732 @subheading The @code{-exec-arguments} Command
1733 @findex -exec-arguments
1735 @subsubheading Synopsis
1738 -exec-arguments @var{args}
1741 Set the inferior program arguments, to be used in the next
1744 @subsubheading GDB Command
1746 The corresponding GDB command is @samp{set args}.
1748 @subsubheading Example
1751 Don't have one around.
1754 @subheading The @code{-exec-continue} Command
1755 @findex -exec-continue
1757 @subsubheading Synopsis
1763 Asynchronous command. Resumes the execution of the inferior program
1764 until a breakpoint is encountered, or until the inferior exits.
1766 @subsubheading GDB Command
1768 The corresponding GDB corresponding is @samp{continue}.
1770 @subsubheading Example
1777 *stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=@{@},
1778 file="hello.c",line="13"@}
1783 @subheading The @code{-exec-finish} Command
1784 @findex -exec-finish
1786 @subsubheading Synopsis
1792 Asynchronous command. Resumes the execution of the inferior program
1793 until the current function is exited. Displays the results returned by
1796 @subsubheading GDB Command
1798 The corresponding GDB command is @samp{finish}.
1800 @subsubheading Example
1802 Function returning @code{void}.
1809 *stopped,reason="function-finished",frame=@{func="main",args=@{@},
1810 file="hello.c",line="7"@}
1814 Function returning other than @code{void}. The name of the internal GDB
1815 variable storing the result is printed, together with the value itself.
1821 *stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
1822 args=@{@{name="a",value="1"@},@{name="b",value="9"@}@},
1823 file="recursive2.c",line="14"@},
1824 gdb-result-var="$1",return-value="0"
1829 @subheading The @code{-exec-interrupt} Command
1830 @findex -exec-interrupt
1832 @subsubheading Synopsis
1838 Asynchronous command. Interrupts the background execution of the target.
1839 Note how the token associated with the stop message is the one for the
1840 execution command that has been interrupted. The token for the interrupt
1841 itself only appears in the '^done' output. If the user is trying to
1842 interrupt a non-running program, an error message will be printed.
1844 @subsubheading GDB Command
1846 The corresponding GDB command is @samp{interrupt}.
1848 @subsubheading Example
1859 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
1860 frame=@{addr="0x00010140",func="foo",args=@{@},file="try.c",line="13"@}
1865 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
1870 @subheading The @code{-exec-next} Command
1873 @subsubheading Synopsis
1879 Asynchronous command. Resumes execution of the inferior program, stopping
1880 when the beginning of the next source line is reached.
1882 @subsubheading GDB Command
1884 The corresponding GDB command is @samp{next}.
1886 @subsubheading Example
1892 *stopped,reason="end-stepping-range",line="8",file="hello.c"
1897 @subheading The @code{-exec-next-instruction} Command
1898 @findex -exec-next-instruction
1900 @subsubheading Synopsis
1903 -exec-next-instruction
1906 Asynchronous command. Executes one machine instruction. If the
1907 instruction is a function call continues until the function returns. If
1908 the program stops at an instruction in the middle of a source line, the
1909 address will be printed as well.
1911 @subsubheading GDB Command
1913 The corresponding GDB command is @samp{nexti}.
1915 @subsubheading Example
1919 -exec-next-instruction
1923 *stopped,reason="end-stepping-range",
1924 addr="0x000100d4",line="5",file="hello.c"
1929 @subheading The @code{-exec-return} Command
1930 @findex -exec-return
1932 @subsubheading Synopsis
1938 Makes current function return immediately. Doesn't execute the inferior.
1939 Displays the new current frame.
1941 @subsubheading GDB Command
1943 The corresponding GDB command is @samp{return}.
1945 @subsubheading Example
1949 200-break-insert callee4
1950 200^done,bkpt=@{number="1",addr="0x00010734",
1951 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1956 000*stopped,reason="breakpoint-hit",bkptno="1",
1957 frame=@{func="callee4",args=@{@},
1958 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1964 111^done,frame=@{level="0 ",func="callee3",
1965 args=@{@{name="strarg",
1966 value="0x11940 \"A string argument.\""@}@},
1967 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1972 @subheading The @code{-exec-run} Command
1975 @subsubheading Synopsis
1981 Asynchronous command. Starts execution of the inferior from the
1982 beginning. The inferior executes until either a breakpoint is
1983 encountered or the program exits.
1985 @subsubheading GDB Command
1987 The corresponding GDB command is @samp{run}
1989 @subsubheading Example
1994 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
1999 *stopped,reason="breakpoint-hit",bkptno="1",
2000 frame=@{func="main",args=@{@},file="recursive2.c",line="4"@}
2005 @subheading The @code{-exec-show-arguments} Command
2006 @findex -exec-show-arguments
2008 @subsubheading Synopsis
2011 -exec-show-arguments
2014 Print the arguments of the program.
2016 @subsubheading GDB Command
2018 The corresponding GDB command is @samp{show args}.
2020 @subsubheading Example
2023 @c @subheading -exec-signal
2025 @subheading The @code{-exec-step} Command
2028 @subsubheading Synopsis
2034 Asynchronous command. Resumes execution of the inferior program, stopping
2035 when the beginning of the next source line is reached, if the next
2036 source line is not a function call. If it is, stop at the first
2037 instruction of the called function.
2039 @subsubheading GDB Command
2041 The corresponding GDB command is @samp{step}.
2043 @subsubheading Example
2045 Stepping into a function:
2051 *stopped,reason="end-stepping-range",
2052 frame=@{func="foo",args=@{@{name="a",value="10"@},
2053 @{name="b",value="0"@}@},file="recursive2.c",line="11"@}
2063 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
2068 @subheading The @code{-exec-step-instruction} Command
2069 @findex -exec-step-instruction
2071 @subsubheading Synopsis
2074 -exec-step-instruction
2077 Asynchronous command. Resumes the inferior which executes one machine
2078 instruction. The output, once stop, will vary depend on whether we have
2079 stopped in the middle of a source line or not. In the former case, the
2080 address at which the program stopped will be printed as well.
2082 @subsubheading GDB Command
2084 The corresponding GDB command is @samp{stepi}.
2086 @subsubheading Example
2090 -exec-step-instruction
2094 *stopped,reason="end-stepping-range",
2095 frame=@{func="foo",args=@{@},file="try.c",line="10"@}
2097 -exec-step-instruction
2101 *stopped,reason="end-stepping-range",
2102 frame=@{addr="0x000100f4",func="foo",args=@{@},file="try.c",line="10"@}
2107 @subheading The @code{-exec-until} Command
2110 @subsubheading Synopsis
2113 -exec-until [ @var{location} ]
2116 Asynchronous command. Executes the inferior until the @var{location}
2117 specified in the argument is reached. If there is no argument, the inferior
2118 executes until a source line greater than the current one is reached.
2119 The reason for stopping in this case will be ``location-reached''.
2121 @subsubheading GDB Command
2123 The corresponding GDB command is @samp{until}.
2125 @subsubheading Example
2129 -exec-until recursive2.c:6
2133 *stopped,reason="location-reached",frame=@{func="main",args=@{@},
2134 file="recursive2.c",line="6"@}
2139 @subheading -file-clear
2140 Is this going away????
2144 @subheading The @code{-file-exec-and-symbols} Command
2145 @findex -file-exec-and-symbols
2147 @subsubheading Synopsis
2150 -file-exec-and-symbols @var{file}
2153 Specify the executable file to be debugged. This file is the one from
2154 which the symbol table is also read. If no file is specified, the
2155 command clears the executable and symbol information. If breakpoints
2156 are set when using this command with no arguments, gdb will produce
2157 error messages. Oterwise, no output is produced, except a completion
2160 @subsubheading GDB Command
2162 The corresponding GDB command is @samp{file}.
2164 @subsubheading Example
2168 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2174 @subheading The @code{-file-exec-file} Command
2175 @findex -file-exec-file
2177 @subsubheading Synopsis
2180 -file-exec-file @var{file}
2183 Specify the executable file to be debugged. Unlike
2184 @samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
2185 from this file. If used without argument, GDB clears the information
2186 about the executable file. No output is produced, except a completion
2189 @subsubheading GDB Command
2191 The corresponding GDB command is @samp{exec-file}.
2193 @subsubheading Example
2197 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2203 @subheading The @code{-file-list-exec-sections} Command
2204 @findex -file-list-exec-sections
2206 @subsubheading Synopsis
2209 -file-list-exec-sections
2212 List the sections of the current executable file.
2214 @subsubheading GDB Command
2216 The GDB command @samp{info file} shows, among the rest, the same
2217 information as this command. @code{gdbtk} has a corresponding command
2218 @samp{gdb_load_info}.
2220 @subsubheading Example
2224 @subheading The @code{-file-list-exec-source-files} Command
2225 @findex -file-list-exec-source-files
2227 @subsubheading Synopsis
2230 -file-list-exec-source-files
2233 List the source files for the current executable.
2235 @subsubheading GDB Command
2237 There's no GDB command which directly corresponds to this one.
2238 @code{gdbtk} has an analogous command @samp{gdb_listfiles}.
2240 @subsubheading Example
2244 @subheading The @code{-file-list-shared-libraries} Command
2245 @findex -file-list-shared-libraries
2247 @subsubheading Synopsis
2250 -file-list-shared-libraries
2253 List the shared libraries in the program.
2255 @subsubheading GDB Command
2257 The corresponding GDB command os @samp{info shared}.
2259 @subsubheading Example
2263 @subheading The @code{-file-list-symbol-files} Command
2264 @findex -file-list-symbol-files
2266 @subsubheading Synopsis
2269 -file-list-symbol-files
2274 @subsubheading GDB Command
2276 The corresponding GDB command is @samp{info file} (part of it).
2278 @subsubheading Example
2282 @subheading The @code{-file-symbol-file} Command
2283 @findex -file-symbol-file
2285 @subsubheading Synopsis
2288 -file-symbol-file @var{file}
2291 Read symbol table info from the specified @var{file} argument. When
2292 used without arguments, clears GDB'S symbol table info. No output is
2293 produced, except for a completion notification.
2295 @subsubheading GDB Command
2297 The corresponding GDB command is @samp{symbol-file}.
2299 @subsubheading Example
2303 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2308 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2309 @node GDB/MI Misc Commands
2310 @section Misc GDB commands in @sc{gdb/mi}
2312 @c @subheading -gdb-complete
2314 @subheading The @code{-gdb-exit} Command
2317 @subsubheading Synopsis
2323 Exit GDB immediately.
2325 @subsubheading GDB Command
2327 Approximately corresponds to @samp{quit}.
2329 @subsubheading Example
2336 @subheading The @code{-gdb-set} Command
2339 @subsubheading Synopsis
2345 Set an internal GDB variable.
2346 @c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
2348 @subsubheading GDB Command
2350 The corresponding GDB command is @samp{set}.
2352 @subsubheading Example
2362 @subheading The @code{-gdb-show} Command
2365 @subsubheading Synopsis
2371 Show the current value of a GDB variable.
2373 @subsubheading GDB command
2375 The corresponding GDB command is @samp{show}.
2377 @subsubheading Example
2386 @c @subheading -gdb-source
2389 @subheading The @code{-gdb-version} Command
2390 @findex -gdb-version
2392 @subsubheading Synopsis
2398 Show version information for GDB. Used mostly in testing.
2400 @subsubheading GDB Command
2402 There's no equivalent GDB command. GDB by default shows this
2403 information when you start an interactive session.
2405 @subsubheading Example
2407 @c This example modifies the actual output from GDB to avoid overfull
2413 ~Copyright 2000 Free Software Foundation, Inc.
2414 ~GDB is free software, covered by the GNU General Public License, and
2415 ~you are welcome to change it and/or distribute copies of it under
2416 ~ certain conditions.
2417 ~Type "show copying" to see the conditions.
2418 ~There is absolutely no warranty for GDB. Type "show warranty" for
2420 ~This GDB was configured as
2421 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
2427 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2428 @node GDB/MI Kod Commands
2429 @section @sc{gdb/mi} Kod Commands
2431 The Kod commands are not implemented.
2433 @c @subheading -kod-info
2435 @c @subheading -kod-list
2437 @c @subheading -kod-list-object-types
2439 @c @subheading -kod-show
2441 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2442 @node GDB/MI Memory Overlay Commands
2443 @section @sc{gdb/mi} Memory Overlay Commands
2445 The memory overlay commands are not implemented.
2447 @c @subheading -overlay-auto
2449 @c @subheading -overlay-list-mapping-state
2451 @c @subheading -overlay-list-overlays
2453 @c @subheading -overlay-map
2455 @c @subheading -overlay-off
2457 @c @subheading -overlay-on
2459 @c @subheading -overlay-unmap
2461 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2462 @node GDB/MI Signal Handling Commands
2463 @section @sc{gdb/mi} Signal Handling Commands
2465 Signal handling commands are not implemented.
2467 @c @subheading -signal-handle
2469 @c @subheading -signal-list-handle-actions
2471 @c @subheading -signal-list-signal-types
2475 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2476 @node GDB/MI Stack Manipulation
2477 @section Stack manipulation commands in @sc{gdb/mi}
2480 @subheading The @code{-stack-info-frame} Command
2481 @findex -stack-info-frame
2483 @subsubheading Synopsis
2489 Get info on the current frame.
2491 @subsubheading GDB Command
2493 The corresponding GDB command is @samp{info frame} or @samp{frame}
2494 (without arguments).
2496 @subsubheading Example
2499 @subheading The @code{-stack-info-depth} Command
2500 @findex -stack-info-depth
2502 @subsubheading Synopsis
2505 -stack-info-depth [ @var{max-depth} ]
2508 Return the depth of the stack. If the integer argument @var{max-depth}
2509 is specified, do not count beyond @var{max-depth} frames.
2511 @subsubheading GDB Command
2513 There's no equivalent GDB command.
2515 @subsubheading Example
2517 For a stack with frame levels 0 through 11:
2527 -stack-info-depth 12
2530 -stack-info-depth 11
2533 -stack-info-depth 13
2538 @subheading The @code{-stack-list-arguments} Command
2539 @findex -stack-list-arguments
2541 @subsubheading Synopsis
2544 -stack-list-arguments @var{show-values}
2545 [ @var{low-frame} @var{high-frame} ]
2548 Display a list of the arguments for the frames between @var{low-frame}
2549 and @var{high-frame} (inclusive). If @var{low-frame} and
2550 @var{high-frame} are not provided, list the arguments for the whole call
2553 The @var{show-values} argument must have a value of 0 or 1. A value of
2554 0 means that only the names of the arguments are listed, a value of 1
2555 means that both names and values of the argumetns are printed.
2557 @subsubheading GDB Command
2559 GDB does not have an equivalent command. @code{gdbtk} has a
2560 @samp{gdb_get_args} command which partially overlaps with the
2561 functionality of @samp{-stack-list-arguments}.
2563 @subsubheading Example
2570 frame=@{level="0 ",addr="0x00010734",func="callee4",
2571 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
2572 frame=@{level="1 ",addr="0x0001076c",func="callee3",
2573 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
2574 frame=@{level="2 ",addr="0x0001078c",func="callee2",
2575 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
2576 frame=@{level="3 ",addr="0x000107b4",func="callee1",
2577 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
2578 frame=@{level="4 ",addr="0x000107e0",func="main",
2579 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}@}
2581 -stack-list-arguments 0
2584 frame=@{level="0",args=@{@}@},
2585 frame=@{level="1",args=@{name="strarg"@}@},
2586 frame=@{level="2",args=@{name="intarg",name="strarg"@}@},
2587 frame=@{level="3",args=@{name="intarg",name="strarg",name="fltarg"@}@},
2588 frame=@{level="4",args=@{@}@}@}
2590 -stack-list-arguments 1
2593 frame=@{level="0",args=@{@}@},
2595 args=@{@{name="strarg",value="0x11940 \"A string argument.\""@}@}@},
2596 frame=@{level="2",args=@{
2597 @{name="intarg",value="2"@},
2598 @{name="strarg",value="0x11940 \"A string argument.\""@}@}@},
2599 @{frame=@{level="3",args=@{
2600 @{name="intarg",value="2"@},
2601 @{name="strarg",value="0x11940 \"A string argument.\""@},
2602 @{name="fltarg",value="3.5"@}@}@},
2603 frame=@{level="4",args=@{@}@}@}
2605 -stack-list-arguments 0 2 2
2606 ^done,stack-args=@{frame=@{level="2",args=@{name="intarg",name="strarg"@}@}@}
2608 -stack-list-arguments 1 2 2
2609 ^done,stack-args=@{frame=@{level="2",
2610 args=@{@{name="intarg",value="2"@},
2611 @{name="strarg",value="0x11940 \"A string argument.\""@}@}@}@}
2615 @c @subheading -stack-list-exception-handlers
2618 @subheading The @code{-stack-list-frames} Command
2619 @findex -stack-list-frames
2621 @subsubheading Synopsis
2624 -stack-list-frames [ @var{low-frame} @var{high-frame} ]
2627 List the frames currently on the stack. For each frame it displays the
2632 The frame number, 0 being the topmost frame, i.e. the innermost function.
2634 The @code{$pc} value for that frame.
2638 File name of the source file where the function lives.
2640 Line number corresponding to the @code{$pc}.
2643 If invoked without arguments, this command prints a backtrace for the
2644 whole stack. If given two integer arguments, it shows the frames whose
2645 levels are between the two arguments (inclusive). If the two arguments
2646 are equal, it shows the single frame at the corresponding level.
2648 @subsubheading GDB Command
2650 The corresponding GDB commands are @samp{backtrace} and @samp{where}.
2652 @subsubheading Example
2654 Full stack backtrace:
2660 @{frame=@{level="0 ",addr="0x0001076c",func="foo",
2661 file="recursive2.c",line="11"@},
2662 frame=@{level="1 ",addr="0x000107a4",func="foo",
2663 file="recursive2.c",line="14"@},
2664 frame=@{level="2 ",addr="0x000107a4",func="foo",
2665 file="recursive2.c",line="14"@},
2666 frame=@{level="3 ",addr="0x000107a4",func="foo",
2667 file="recursive2.c",line="14"@},
2668 frame=@{level="4 ",addr="0x000107a4",func="foo",
2669 file="recursive2.c",line="14"@},
2670 frame=@{level="5 ",addr="0x000107a4",func="foo",
2671 file="recursive2.c",line="14"@},
2672 frame=@{level="6 ",addr="0x000107a4",func="foo",
2673 file="recursive2.c",line="14"@},
2674 frame=@{level="7 ",addr="0x000107a4",func="foo",
2675 file="recursive2.c",line="14"@},
2676 frame=@{level="8 ",addr="0x000107a4",func="foo",
2677 file="recursive2.c",line="14"@},
2678 frame=@{level="9 ",addr="0x000107a4",func="foo",
2679 file="recursive2.c",line="14"@},
2680 frame=@{level="10",addr="0x000107a4",func="foo",
2681 file="recursive2.c",line="14"@},
2682 frame=@{level="11",addr="0x00010738",func="main",
2683 file="recursive2.c",line="4"@}@}
2687 Show frames between low_frame and high_frame:
2691 -stack-list-frames 3 5
2693 @{frame=@{level="3 ",addr="0x000107a4",func="foo",
2694 file="recursive2.c",line="14"@},
2695 frame=@{level="4 ",addr="0x000107a4",func="foo",
2696 file="recursive2.c",line="14"@},
2697 frame=@{level="5 ",addr="0x000107a4",func="foo",
2698 file="recursive2.c",line="14"@}@}
2702 Show a single frame:
2706 -stack-list-frames 3 3
2708 @{frame=@{level="3 ",addr="0x000107a4",func="foo",
2709 file="recursive2.c",line="14"@}@}
2714 @subheading The @code{-stack-list-locals} Command
2715 @findex -stack-list-locals
2717 @subsubheading Synopsis
2720 -stack-list-locals @var{print-values}
2723 Display the local variables names for the current frame. With an
2724 argument of 0 prints only the names of the variables, with argument of 1
2725 prints also their values.
2727 @subsubheading GDB Command
2729 @samp{info locals} in GDB, @samp{gdb_get_locals} in @code{gdbtk}.
2731 @subsubheading Example
2735 -stack-list-locals 0
2736 ^done,locals=@{name="A",name="B",name="C"@}
2738 -stack-list-locals 1
2739 ^done,locals=@{@{name="A",value="1"@},@{name="B",value="2"@},
2740 @{name="C",value="3"@}@}
2745 @subheading The @code{-stack-select-frame} Command
2746 @findex -stack-select-frame
2748 @subsubheading Synopsis
2751 -stack-select-frame @var{framenum}
2754 Change the current frame. Select a different frame @var{framenum} on
2757 @subsubheading GDB Command
2759 The corresponding GDB commands are @samp{frame}, @samp{up}, @samp{down},
2760 @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
2762 @subsubheading Example
2766 -stack-select-frame 2
2771 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2772 @node GDB/MI Symbol Query
2773 @section @sc{gdb/mi} Symbol Query Commands
2776 @subheading The @code{-symbol-info-address} Command
2777 @findex -symbol-info-address
2779 @subsubheading Synopsis
2782 -symbol-info-address @var{symbol}
2785 Describe where @var{symbol} is stored.
2787 @subsubheading GDB Command
2789 the corresponding GDB command is @samp{info address}.
2791 @subsubheading Example
2795 @subheading The @code{-symbol-info-file} Command
2796 @findex -symbol-info-file
2798 @subsubheading Synopsis
2804 Show the file for the symbol.
2806 @subsubheading GDB Command
2808 There's no equivalent GDB command. @code{gdbtk} has
2809 @samp{gdb_filnd_file}.
2811 @subsubheading Example
2815 @subheading The @code{-symbol-info-function} Command
2816 @findex -symbol-info-function
2818 @subsubheading Synopsis
2821 -symbol-info-function
2824 Show which function the symbol lives in.
2826 @subsubheading GDB Command
2828 @samp{gdb_get_function} in @code{gdbtk}.
2830 @subsubheading Example
2834 @subheading The @code{-symbol-info-line} Command
2835 @findex -symbol-info-line
2837 @subsubheading Synopsis
2843 Show the core addresses of the code for a source line.
2845 @subsubheading GDB Command
2847 The corresponding GDB comamnd is @samp{info line}. @code{gdbtk} has the
2848 @samp{gdb_get_line} @samp{gdb_get_file} commands.
2850 @subsubheading Example
2854 @subheading The @code{-symbol-info-symbol} Command
2855 @findex -symbol-info-symbol
2857 @subsubheading Synopsis
2860 -symbol-info-symbol @var{addr}
2863 Describe what symbol is at location @var{addr}.
2865 @subsubheading GDB Command
2867 The corresponding GDB command is @samp{info symbol}.
2869 @subsubheading Example
2873 @subheading The @code{-symbol-list-functions} Command
2874 @findex -symbol-list-functions
2876 @subsubheading Synopsis
2879 -symbol-list-functions
2882 List the functions in the executable.
2884 @subsubheading GDB Command
2886 @samp{info functions} in GDB, @samp{gdb_listfunc} @samp{gdb_search} in
2889 @subsubheading Example
2893 @subheading The @code{-symbol-list-types} Command
2894 @findex -symbol-list-types
2896 @subsubheading Synopsis
2902 List all the type names.
2904 @subsubheading GDB Command
2906 The corresponding commands are @samp{info types} in GDB,
2907 @samp{gdb_search} in @code{gdbtk}.
2909 @subsubheading Example
2913 @subheading The @code{-symbol-list-variables} Command
2914 @findex -symbol-list-variables
2916 @subsubheading Synopsis
2919 -symbol-list-variables
2922 List all the global and static variable names.
2924 @subsubheading GDB Command
2926 @samp{info variables} in GDB, @samp{gdb_search} in @code{gdbtk}.
2928 @subsubheading Example
2932 @subheading The @code{-symbol-locate} Command
2933 @findex -symbol-locate
2935 @subsubheading Synopsis
2941 @subsubheading GDB Command
2943 @samp{gdb_loc} in @code{gdbtk}.
2945 @subsubheading Example
2949 @subheading The @code{-symbol-type} Command
2950 @findex -symbol-type
2952 @subsubheading Synopsis
2955 -symbol-type @var{variable}
2958 Show type of @var{variable}.
2960 @subsubheading GDB Command
2962 The corresponding GDB command is @samp{ptype}, @code{gdbtk} has
2963 @samp{gdb_obj_variable}.
2965 @subsubheading Example
2969 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2970 @node GDB/MI Target Manipulation
2971 @section @sc{gdb/mi} Target Manipulation Commands
2974 @subheading The @code{-target-attach} Command
2975 @findex -target-attach
2977 @subsubheading Synopsis
2980 -target-attach @var{pid} | @var{file}
2983 Attach to a process @var{pid} or a file @var{file} outside of GDB.
2985 @subsubheading GDB command
2987 The corresponding GDB command is @samp{attach}.
2989 @subsubheading Example
2993 @subheading The @code{-target-compare-sections} Command
2994 @findex -target-compare-sections
2996 @subsubheading Synopsis
2999 -target-compare-sections [ @var{section} ]
3002 Compare data of section @var{section} on target to the exec file.
3003 Without the argument, all sections are compared.
3005 @subsubheading GDB Command
3007 The GDB equivalent is @samp{compare-sections}.
3009 @subsubheading Example
3013 @subheading The @code{-target-detach} Command
3014 @findex -target-detach
3016 @subsubheading Synopsis
3022 Disconnect from the remote target. There's no output.
3024 @subsubheading GDB command
3026 The corresponding GDB command is @samp{detach}.
3028 @subsubheading Example
3038 @subheading The @code{-target-download} Command
3039 @findex -target-download
3041 @subsubheading Synopsis
3047 Loads the executable onto the remote target.
3048 It prints out an update message every half second, which includes the fields:
3052 The name of the section.
3054 The size of what has been sent so far for that section.
3056 The size of the section.
3058 The total size of what was sent so far (the current and the previous sections).
3060 The size of the overall executable to download.
3064 Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
3065 @sc{gdb/mi} Output Syntax}).
3067 In addition, it prints the name and size of the sections, as they are
3068 downloaded. These messages include the following fields:
3072 The name of the section.
3074 The size of the section.
3076 The size of the overall executable to download.
3080 At the end, a summary is printed.
3082 @subsubheading GDB Command
3084 The corresponding GDB command is @samp{load}.
3086 @subsubheading Example
3088 Note: each status message appears on a single line. Here the messages
3089 have been broken down, so they can fit into a page.
3094 +download,@{section=".text",section-size="6668",total-size="9880"@}
3095 +download,@{section=".text",section-sent="512",section-size="6668",
3096 total-sent="512",total-size="9880"@}
3097 +download,@{section=".text",section-sent="1024",section-size="6668",
3098 total-sent="1024",total-size="9880"@}
3099 +download,@{section=".text",section-sent="1536",section-size="6668",
3100 total-sent="1536",total-size="9880"@}
3101 +download,@{section=".text",section-sent="2048",section-size="6668",
3102 total-sent="2048",total-size="9880"@}
3103 +download,@{section=".text",section-sent="2560",section-size="6668",
3104 total-sent="2560",total-size="9880"@}
3105 +download,@{section=".text",section-sent="3072",section-size="6668",
3106 total-sent="3072",total-size="9880"@}
3107 +download,@{section=".text",section-sent="3584",section-size="6668",
3108 total-sent="3584",total-size="9880"@}
3109 +download,@{section=".text",section-sent="4096",section-size="6668",
3110 total-sent="4096",total-size="9880"@}
3111 +download,@{section=".text",section-sent="4608",section-size="6668",
3112 total-sent="4608",total-size="9880"@}
3113 +download,@{section=".text",section-sent="5120",section-size="6668",
3114 total-sent="5120",total-size="9880"@}
3115 +download,@{section=".text",section-sent="5632",section-size="6668",
3116 total-sent="5632",total-size="9880"@}
3117 +download,@{section=".text",section-sent="6144",section-size="6668",
3118 total-sent="6144",total-size="9880"@}
3119 +download,@{section=".text",section-sent="6656",section-size="6668",
3120 total-sent="6656",total-size="9880"@}
3121 +download,@{section=".init",section-size="28",total-size="9880"@}
3122 +download,@{section=".fini",section-size="28",total-size="9880"@}
3123 +download,@{section=".data",section-size="3156",total-size="9880"@}
3124 +download,@{section=".data",section-sent="512",section-size="3156",
3125 total-sent="7236",total-size="9880"@}
3126 +download,@{section=".data",section-sent="1024",section-size="3156",
3127 total-sent="7748",total-size="9880"@}
3128 +download,@{section=".data",section-sent="1536",section-size="3156",
3129 total-sent="8260",total-size="9880"@}
3130 +download,@{section=".data",section-sent="2048",section-size="3156",
3131 total-sent="8772",total-size="9880"@}
3132 +download,@{section=".data",section-sent="2560",section-size="3156",
3133 total-sent="9284",total-size="9880"@}
3134 +download,@{section=".data",section-sent="3072",section-size="3156",
3135 total-sent="9796",total-size="9880"@}
3136 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
3142 @subheading The @code{-target-exec-status} Command
3143 @findex -target-exec-status
3145 @subsubheading Synopsis
3151 Provide information on the state of the target (whether it is running or
3154 @subsubheading GDB Command
3156 There's no equivalent GDB command.
3158 @subsubheading Example
3162 @subheading The @code{-target-list-available-targets} Command
3163 @findex -target-list-available-targets
3165 @subsubheading Synopsis
3168 -target-list-available-targets
3171 List the possible targets to connect to.
3173 @subsubheading GDB Command
3175 The corresponding GDB command is @samp{help target}.
3177 @subsubheading Example
3181 @subheading The @code{-target-list-current-targets} Command
3182 @findex -target-list-current-targets
3184 @subsubheading Synopsis
3187 -target-list-current-targets
3190 Describe the current target.
3192 @subsubheading GDB Command
3194 The corresponding information is printed by @samp{info file} (among
3197 @subsubheading Example
3201 @subheading The @code{-target-list-parameters} Command
3202 @findex -target-list-parameters
3204 @subsubheading Synopsis
3207 -target-list-parameters
3212 @subsubheading GDB Command
3216 @subsubheading Example
3220 @subheading The @code{-target-select} Command
3221 @findex -target-select
3223 @subsubheading Synopsis
3226 -target-select @var{type} @var{parameters ...}
3229 Connect GDB to the remote target. This command takes two args:
3233 The type of target, for instance @samp{async}, @samp{remote}, etc.
3234 @item @var{parameters}
3235 Device names, host names and the like. @xref{Target Commands, ,
3236 Commands for managing targets}, for more details.
3239 The output is a connection notification, followed by the address at
3240 which the target program is, in the following form:
3243 ^connected,addr="@var{address}",func="@var{function name}",
3244 args=@{@var{arg list}@}
3247 @subsubheading GDB Command
3249 The corresponding GDB command is @samp{target}.
3251 @subsubheading Example
3255 -target-select async /dev/ttya
3256 ^connected,addr="0xfe00a300",func="??",args=@{@}
3260 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3261 @node GDB/MI Thread Commands
3262 @section @sc{gdb/mi} Thread Commands
3265 @subheading The @code{-thread-info} Command
3266 @findex -thread-info
3268 @subsubheading Synopsis
3274 @subsubheading GDB command
3278 @subsubheading Example
3282 @subheading The @code{-thread-list-all-threads} Command
3283 @findex -thread-list-all-threads
3285 @subsubheading Synopsis
3288 -thread-list-all-threads
3291 @subsubheading GDB Command
3293 The equivalent GDB command is @samp{info threads}.
3295 @subsubheading Example
3299 @subheading The @code{-thread-list-ids} Command
3300 @findex -thread-list-ids
3302 @subsubheading Synopsis
3308 Produces a list of the currently known gdb thread ids. At the end of the
3309 list it also prints the total number of such threads.
3311 @subsubheading GDB Command
3313 Part of @samp{info threads} supplies the same information.
3315 @subsubheading Example
3317 No threads present, besides the main process.
3322 ^done,thread-ids=@{@},number-of-threads="0"
3332 ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3333 number-of-threads="3"
3338 @subheading The @code{-thread-select} Command
3339 @findex -thread-select
3341 @subsubheading Synopsis
3344 -thread-select @var{threadnum}
3347 Make @var{threadnum} the current thread. It prints the number of the new
3348 current thread, and the topmost frame for that thread.
3350 @subsubheading GDB Command
3352 The corresponding GDB command is @samp{thread}.
3354 @subsubheading Example
3361 *stopped,reason="end-stepping-range",thread-id="2",line="187",
3362 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
3366 thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3367 number-of-threads="3"
3370 ^done,new-thread-id="3",
3371 frame=@{level="0 ",func="vprintf",
3372 args=@{@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
3373 @{name="arg",value="0x2"@}@},file="vprintf.c",line="31"@}
3377 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3378 @node GDB/MI Tracepoint Commands
3379 @section @sc{gdb/mi} Tracepoint Commands
3381 The tracepoint commands are not yet implemented.
3383 @c @subheading -trace-actions
3385 @c @subheading -trace-delete
3387 @c @subheading -trace-disable
3389 @c @subheading -trace-dump
3391 @c @subheading -trace-enable
3393 @c @subheading -trace-exists
3395 @c @subheading -trace-find
3397 @c @subheading -trace-frame-number
3399 @c @subheading -trace-info
3401 @c @subheading -trace-insert
3403 @c @subheading -trace-list
3405 @c @subheading -trace-pass-count
3407 @c @subheading -trace-save
3409 @c @subheading -trace-start
3411 @c @subheading -trace-stop
3414 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3415 @node GDB/MI Variable Objects
3416 @section @sc{gdb/mi} Variable Objects
3419 @subheading Motivation for Variable Objects in @sc{gdb/mi}
3421 For the implementation of a variable debugger window (locals, watched
3422 expressions, etc.), we are proposing the adaptation of the existent code
3423 used by @code{Insight}.
3425 The two main reasons for that are:
3429 It has been proven in practice (it is already on its second generation).
3432 It will shorten development time (needless to say how important it is
3436 The original interface was designed to be used by Tcl code, so it was
3437 slightly changed so it could be used through flathead. This document
3438 describes the flathead operations that will be available and gives some
3439 hints about their use.
3441 @emph{Note}: In addition to the set of operations described here, we
3442 expect the @sc{gui} implementation of a variable window to require, at
3443 least, the following operations:
3446 @item -gdb-show output-radix
3447 @item -stack-list-arguments
3448 @item -stack-list-locals
3449 @item -stack-select-frame
3452 @subheading Introduction to Variable Objects in @sc{gdb/mi}
3454 @cindex variable objects in @sc{gdb/mi}
3455 The basic idea behind variable objects is the creation of a named object
3456 to represent a variable, an expression, a memory location or even a CPU
3457 register. For each object created, a set of operations is available for
3458 examining or changing its properties.
3460 Furthermore, complex data types, such as C structures, are represented
3461 in a tree format. For instance, the @code{struct} type variable is the
3462 root and the children will represent the struct members. If a child
3463 is itself of a complex type, it will also have children of its own.
3464 Appropriate language differences are handled for C, C@t{++} and Java.
3466 When returning the actual values of the objects, this facility allows
3467 for the individual selection of the display format used in the result
3468 creation. It can be chosen among: binary, decimal, hexadecimal, octal
3469 and natural. Natural refers to the a default format automatically
3470 chosen based on the variable type (like decimal for an @code{int}, hex
3471 for pointers, etc.).
3473 The following is the complete set of flathead operations defined to
3474 access this functionality:
3476 @multitable @columnfractions .3 .6
3477 @item @strong{Operation}
3478 @tab @strong{Description}
3481 @tab create a variable object
3483 @tab delete the variable object and its children
3484 @item -var-set-format
3485 @tab set the display format of this variable
3486 @item -var-show-format
3487 @tab show the display format of this variable
3488 @item -var-info-num-children
3489 @tab tells how many children this object has
3490 @item -var-list-children
3491 @tab return a list of the object's children
3492 @item -var-info-type
3493 @tab show the type of this variable object
3494 @item -var-info-expression
3495 @tab print what this variable object represents
3496 @item -var-show-attributes
3497 @tab is this variable editable? does it exist here?
3498 @item -var-evaluate-expression
3499 @tab get the value of this variable
3501 @tab set the value of this variable
3503 @tab update the variable and its children
3506 In the next subsection we describe each operation in detail and suggest
3509 @subheading Description And Use of Operations on Variable Objects
3511 @subheading The @code{-var-create} Command
3514 @subsubheading Synopsis
3517 -var-create @{@var{name} | "-"@}
3518 @{@var{frame-addr} | "*"@} @var{expression}
3521 This operation creates a variable object, which allows the monitoring of
3522 a variable, the result of an expression, a memory cell or a CPU
3525 The @var{name} parameter is the string by which the object can be
3526 referenced. It must be unique. If @samp{-} is specified, the varobj
3527 system will generate a string "varNNNNNN'' automatically. It will be
3528 unique provided that one does not specify @var{name} on that format.
3529 The command fails if a duplicate name is found.
3531 The frame under which the expression should be evaluated can be
3532 specified by @var{frame-addr}. A @samp{*} indicates that the current
3533 frame should be used.
3535 Expression is any expression valid on the current language set (must not
3536 begin with a @samp{*}), or one of the following:
3540 @samp{*@var{addr}}, where @var{addr} is the address of a memory cell
3543 @samp{*@var{addr}-@var{addr}} -- a memory address range (TBD)
3546 @samp{$@var{regname}} -- a CPU register name
3549 @subsubheading Result
3551 This operation returns the name, number of children and the type of the
3552 object created. Type is returned as a string as the ones generated by
3556 name="@var{name}",numchild="N",type="@var{type}"
3560 @subheading The @code{-var-delete} Command
3563 @subsubheading Synopsis
3566 -var-delete @var{name}
3569 Deletes a previously created variable object and all of its children.
3571 Returns an error if the object @var{name} is not found.
3574 @subheading The @code{-var-set-format} Command
3575 @findex -var-set-format
3577 @subsubheading Synopsis
3580 -var-set-format @var{name} @var{format-spec}
3583 Sets the output format for the value of the object @var{name} to be
3586 The syntax for the @var{format-spec} is as follows:
3589 @var{format-spec} @expansion{}
3590 @{binary | decimal | hexadecimal | octal | natural@}
3594 @subheading The @code{-var-show-format} Command
3595 @findex -var-show-format
3597 @subsubheading Synopsis
3600 -var-show-format @var{name}
3603 Returns the format used to display the value of the object @var{name}.
3611 @subheading The @code{-var-info-num-children} Command
3612 @findex -var-info-num-children
3614 @subsubheading Synopsis
3617 -var-info-num-children @var{name}
3620 Returns the number of children of a variable object @var{name}:
3627 @subheading The @code{-var-list-children} Command
3628 @findex -var-list-children
3630 @subsubheading Synopsis
3633 -var-list-children @var{name}
3636 Returns a list of the children of the specified variable object:
3639 numchild=@var{n},children=@{@{name=@var{name},
3640 numchild=@var{n},type=@var{type}@},(repeats N times)@}
3644 @subheading The @code{-var-info-type} Command
3645 @findex -var-info-type
3647 @subsubheading Synopsis
3650 -var-info-type @var{name}
3653 Returns the type of the specified variable @var{name}. The type is
3654 returned as a string in the same format as it is output by the GDB CLI:
3661 @subheading The @code{-var-info-expression} Command
3662 @findex -var-info-expression
3664 @subsubheading Synopsis
3667 -var-info-expression @var{name}
3670 Returns what is represented by the variable object @var{name}:
3673 lang=@var{lang-spec},exp=@var{expression}
3677 where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
3679 @subheading The @code{-var-show-attributes} Command
3680 @findex -var-show-attributes
3682 @subsubheading Synopsis
3685 -var-show-attributes @var{name}
3688 List attributes of the specified variable object @var{name}:
3691 status=@var{attr} [ ( ,@var{attr} )* ]
3695 where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
3697 @subheading The @code{-var-evaluate-expression} Command
3698 @findex -var-evaluate-expression
3700 @subsubheading Synopsis
3703 -var-evaluate-expression @var{name}
3706 Evaluates the expression that is represented by the specified variable
3707 object and returns its value as a string in the current format specified
3714 @subheading The @code{-var-assign} Command
3717 @subsubheading Synopsis
3720 -var-assign @var{name} @var{expression}
3723 Assigns the value of @var{expression} to the variable object specified
3724 by @var{name}. The object must be ``editable''.
3726 @subheading The @code{-var-update} Command
3729 @subsubheading Synopsis
3732 -var-update @{@var{name} | "*"@}
3735 Update the value of the variable object @var{name} by evaluating its
3736 expression after fetching all the new values from memory or registers.
3737 A @samp{*} causes all existing variable objects to be updated.
3739 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3740 @node GDB/MI Draft Changes to Output Syntax
3741 @section @sc{gdb/mi} Draft Changes to Output Syntax
3743 @cindex draft changes to output syntax of @sc{gdb/mi}
3744 @cindex @sc{gdb/mi}, draft changes to output syntax
3746 One problem identified in the existing @sc{gdb/mi} output syntax was the
3747 difficulty in differentiating between a tuple such as:
3750 @{number="1",type="breakpoint",disp="keep",enabled="y"@}
3753 where each value has a unique label, and a list such as:
3757 @{bp="1",bp="2",bp="4"@}
3760 where values are un-labeled or the label is duplicated.
3762 What follows is a draft revision to the output specification that
3763 addresses this problem.
3765 The output from @sc{gdb/mi} consists of zero or more out-of-band records
3766 optionally followed by a single result record. The result record being
3767 for the most recent command input. The sequence being terminated by
3770 Asynchronous @sc{gdb/mi} output is similar.
3772 Each output record directly associated with an input command is prefixed
3773 by the input commands @code{@var{token}}.
3776 @item @var{output} @expansion{}
3777 @{ @var{out-of-band-record} @} @code{[} @var{result-record} @code{]} "(gdb)" @var{nl}
3779 @item @var{result-record} @expansion{}
3780 @code{[} @var{token} @code{]} "^" @var{result-class} @{ "," @var{result} @} @var{nl}
3782 @item @var{out-of-band-record} @expansion{}
3783 @var{async-record} @code{|} @var{stream-record}
3785 @item @var{async-record} @expansion{}
3786 @var{exec-async-output} @code{|} @var{status-async-output} @code{|} @var{notify-async-output}
3788 @item @var{exec-async-output} @expansion{}
3789 @code{[} @var{token} @code{]} "*" @var{async-output}
3791 @item @var{status-async-output} @expansion{}
3792 @code{[} @var{token} @code{]} "+" @var{async-output}
3794 @item @var{notify-async-output} @expansion{}
3795 @code{[} @var{token} @code{]} "=" @var{async-output}
3797 @item @var{async-output} @expansion{}
3798 @var{async-class} @{ "," @var{result} @} @var{nl}
3800 @item @var{result-class} @expansion{}
3801 "done" @code{|} "running" @code{|} "connected" @code{|} "error" @code{|} "exit"
3803 @item @var{async-class} @expansion{}
3804 "stopped" @code{|} @emph{others depending on need as still in development}
3806 @item @var{result} @expansion{}
3807 @var{string} "=" @var{value}
3809 @item @var{value} @expansion{}
3810 @var{c-string} @code{|} @var{tupple} @code{|} @var{list}
3812 @item @var{tupple} @expansion{}
3813 "@{@}" @code{|} "@{" @var{result} @{ "," @var{result} @} "@}"
3815 @item @var{list} @expansion{}
3816 "@code{[]}" @code{|} "@code{[}" @var{value} @{ "," @var{value} @} "@code{]}"
3818 @item @var{string} @expansion{}
3819 @emph{[-A-Za-z\.0-9_]*}
3821 @item @var{c-string} @expansion{}
3822 @emph{See the input specification}
3824 @item @var{stream-record} @expansion{}
3825 @var{console-stream-output} @code{|} @var{target-stream-output} @code{|} @var{log-stream-output}
3827 @item @var{console-stream-output} @expansion{}
3830 @item @var{target-stream-output} @expansion{}
3833 @item @var{log-stream-output} @expansion{}
3836 @item @var{nl} @expansion{}
3839 @item @var{token} @expansion{}
3840 "any sequence of digits"
3844 In addition, the following are still being developed.
3849 This action is currently undefined.
3858 All output sequences end in a single line containing a period.
3861 The @code{@var{token}} is from the corresponding request. If an execution
3862 command is interrupted by the -exec-interrupt command, the token
3863 associated with the `*stopped' message is the one of the original
3864 execution command, not the one of the interrupt-command.
3867 @var{status-async-output} contains on-going status information about the progress
3868 of a slow operation. It can be discarded. All status output is prefixed by
3872 @var{exec-async-output} contains asynchronous state change on the target
3873 (stopped, started, disappeared). All async output is prefixed by
3877 @var{notify-async-output} contains supplementary information that the client should
3878 handle (new breakpoint information). All notify output is prefixed by
3882 @var{console-stream-output} is output that should be displayed as is in the
3883 console. It is the textual response to a CLI command. All the console
3884 output is prefixed by the prefix ``~''.
3887 @var{target-stream-output} is the output produced by the target program.
3888 All the target output is prefixed by the prefix ``@@''.
3891 @var{log-stream-output} is output text coming from GDB's internals, for
3892 instance messages that should be displayed as part of an error log. All
3893 the log output is prefixed by the prefix ``&''.
3898 @c change-log-default-name: "ChangeLog-mi"