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 @value{GDBN}. It is
62 specifically intended to support the development of systems which use
63 the debugger as just one small component of a larger system.
65 This chapter is a specification of the @sc{gdb/mi} interface. It is written
66 in the form of a reference manual.
68 Note that @sc{gdb/mi} is still under construction, so some of the
69 features described below are incomplete and subject to change.
71 @unnumberedsec Notation and Terminology
73 @cindex notational conventions, for @sc{gdb/mi}
74 This chapter uses the following notation:
78 @code{|} separates two alternatives.
81 @code{[ @var{something} ]} indicates that @var{something} is optional:
82 it may or may not be given.
85 @code{( @var{group} )*} means that @var{group} inside the parentheses
86 may repeat zero or more times.
89 @code{( @var{group} )+} means that @var{group} inside the parentheses
90 may repeat one or more times.
93 @code{"@var{string}"} means a literal @var{string}.
100 @heading Acknowledgments
102 In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
106 * GDB/MI Command Syntax::
107 * GDB/MI Compatibility with CLI::
108 * GDB/MI Output Records::
109 * GDB/MI Command Description Format::
110 * GDB/MI Breakpoint Table Commands::
111 * GDB/MI Data Manipulation::
112 * GDB/MI Program Control::
113 * GDB/MI Miscellaneous Commands::
114 * GDB/MI Stack Manipulation::
115 * GDB/MI Symbol Query::
116 * GDB/MI Target Manipulation::
117 * GDB/MI Thread Commands::
118 * GDB/MI Tracepoint Commands::
119 * GDB/MI Variable Objects::
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 @value{GDBN} 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 "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 chapter}
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{}
188 The CLI commands are still handled by the @sc{mi} interpreter; their
189 output is described below.
192 The @code{@var{token}}, when present, is passed back when the command
196 Some @sc{mi} commands accept optional arguments as part of the parameter
197 list. Each option is identified by a leading @samp{-} (dash) and may be
198 followed by an optional argument parameter. Options occur first in the
199 parameter list and can be delimited from normal parameters using
200 @samp{--} (this is useful when some parameters begin with a dash).
207 We want easy access to the existing CLI syntax (for debugging).
210 We want it to be easy to spot a @sc{mi} operation.
213 @node GDB/MI Output Syntax
214 @subsection @sc{gdb/mi} Output Syntax
216 @cindex output syntax of @sc{gdb/mi}
217 @cindex @sc{gdb/mi}, output syntax
218 The output from @sc{gdb/mi} consists of zero or more out-of-band records
219 followed, optionally, by a single result record. This result record
220 is for the most recent command. The sequence of output records is
221 terminated by @samp{(@value{GDBP})}.
223 If an input command was prefixed with a @code{@var{token}} then the
224 corresponding output for that command will also be prefixed by that same
228 @item @var{output} @expansion{}
229 @code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
231 @item @var{result-record} @expansion{}
232 @code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
234 @item @var{out-of-band-record} @expansion{}
235 @code{@var{async-record} | @var{stream-record}}
237 @item @var{async-record} @expansion{}
238 @code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
240 @item @var{exec-async-output} @expansion{}
241 @code{[ @var{token} ] "*" @var{async-output}}
243 @item @var{status-async-output} @expansion{}
244 @code{[ @var{token} ] "+" @var{async-output}}
246 @item @var{notify-async-output} @expansion{}
247 @code{[ @var{token} ] "=" @var{async-output}}
249 @item @var{async-output} @expansion{}
250 @code{@var{async-class} ( "," @var{result} )* @var{nl}}
252 @item @var{result-class} @expansion{}
253 @code{"done" | "running" | "connected" | "error" | "exit"}
255 @item @var{async-class} @expansion{}
256 @code{"stopped" | @var{others}} (where @var{others} will be added
257 depending on the needs---this is still in development).
259 @item @var{result} @expansion{}
260 @code{[ @var{string} "=" ] @var{value}}
262 @item @var{value} @expansion{}
263 @code{@var{const} | "@{" @var{result} ( "," @var{result} )* "@}"}
265 @item @var{const} @expansion{}
266 @code{@var{c-string}}
268 @item @var{stream-record} @expansion{}
269 @code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
271 @item @var{console-stream-output} @expansion{}
272 @code{"~" @var{c-string}}
274 @item @var{target-stream-output} @expansion{}
275 @code{"@@" @var{c-string}}
277 @item @var{log-stream-output} @expansion{}
278 @code{"&" @var{c-string}}
280 @item @var{nl} @expansion{}
283 @item @var{token} @expansion{}
284 @emph{any sequence of digits}.
288 In addition, the following are still being developed:
292 This action is currently undefined.
300 All output sequences end in a single line containing a period.
303 The @code{@var{token}} is from the corresponding request. If an execution
304 command is interrupted by the @samp{-exec-interrupt} command, the
305 @var{token} associated with the @samp{*stopped} message is the one of the
306 original execution command, not the one of the interrupt command.
309 @cindex status output in @sc{gdb/mi}
310 @var{status-async-output} contains on-going status information about the
311 progress of a slow operation. It can be discarded. All status output is
312 prefixed by @samp{+}.
315 @cindex async output in @sc{gdb/mi}
316 @var{exec-async-output} contains asynchronous state change on the target
317 (stopped, started, disappeared). All async output is prefixed by
321 @cindex notify output in @sc{gdb/mi}
322 @var{notify-async-output} contains supplementary information that the
323 client should handle (e.g., a new breakpoint information). All notify
324 output is prefixed by @samp{=}.
327 @cindex console output in @sc{gdb/mi}
328 @var{console-stream-output} is output that should be displayed as is in the
329 console. It is the textual response to a CLI command. All the console
330 output is prefixed by @samp{~}.
333 @cindex target output in @sc{gdb/mi}
334 @var{target-stream-output} is the output produced by the target program.
335 All the target output is prefixed by @samp{@@}.
338 @cindex log output in @sc{gdb/mi}
339 @var{log-stream-output} is output text coming from @value{GDBN}'s internals, for
340 instance messages that should be displayed as part of an error log. All
341 the log output is prefixed by @samp{&}.
344 @xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
345 details about the various output records.
347 @xref{GDB/MI Draft Changes to Output Syntax, , @sc{gdb/mi} Draft Changes
348 to Output Syntax}, for proposed revisions to the current output syntax.
350 @node GDB/MI Simple Examples
351 @subsection Simple Examples of @sc{gdb/mi} Interaction
352 @cindex @sc{gdb/mi}, simple examples
354 This subsection presents several simple examples of interaction using
355 the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
356 following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
357 the output received from @sc{gdb/mi}.
359 @subsubheading Target Stop
361 Here's an example of stopping the inferior process:
372 <- *stop,reason="stop",address="0x123",source="a.c:123"
376 @subsubheading Simple CLI Command
378 Here's an example of a simple CLI command being passed through
379 @sc{gdb/mi} and on to the CLI.
387 @subsubheading Command With Side Effects
390 -> -symbol-file xyz.exe
391 <- *breakpoint,nr="3",address="0x123",source="a.c:123"
395 @subsubheading A Bad Command
397 Here's what happens if you pass a non-existent command:
401 <- error,"Rubbish not found"
405 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
406 @node GDB/MI Compatibility with CLI
407 @section @sc{gdb/mi} Compatibility with CLI
409 @cindex compatibility, @sc{gdb/mi} and CLI
410 @cindex @sc{gdb/mi}, compatibility with CLI
411 To help users familiar with @value{GDBN}'s existing CLI interface, @sc{gdb/mi}
412 accepts existing CLI commands. As specified by the syntax, such
413 commands can be directly entered into the @sc{gdb/mi} interface and @value{GDBN} will
416 This mechanism is provided as an aid to developers of @sc{gdb/mi}
417 clients and not as a reliable interface into the CLI. Since the command
418 is being interpreteted in an environment that assumes @sc{gdb/mi}
419 behaviour, the exact output of such commands is likely to end up being
420 an un-supported hybrid of @sc{gdb/mi} and CLI output.
422 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
423 @node GDB/MI Output Records
424 @section @sc{gdb/mi} Output Records
427 * GDB/MI Result Records::
428 * GDB/MI Stream Records::
429 * GDB/MI Out-of-band Records::
432 @node GDB/MI Result Records
433 @subsection @sc{gdb/mi} Result Records
435 @cindex result records in @sc{gdb/mi}
436 @cindex @sc{gdb/mi}, result records
437 In addition to a number of out-of-band notifications, the response to a
438 @sc{gdb/mi} command includes one of the following result indications:
442 @item "^done" [ "," @var{results} ]
443 The synchronous operation was successful, @code{@var{results}} are the return
448 @c Is this one correct? Should it be an out-of-band notification?
449 The asynchronous operation was successfully started. The target is
452 @item "^error" "," @var{c-string}
454 The operation failed. The @code{@var{c-string}} contains the corresponding
458 @node GDB/MI Stream Records
459 @subsection @sc{gdb/mi} Stream Records
461 @cindex @sc{gdb/mi}, stream records
462 @cindex stream records in @sc{gdb/mi}
463 @value{GDBN} internally maintains a number of output streams: the console, the
464 target, and the log. The output intended for each of these streams is
465 funneled through the @sc{gdb/mi} interface using @dfn{stream records}.
467 Each stream record begins with a unique @dfn{prefix character} which
468 identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output
469 Syntax}). In addition to the prefix, each stream record contains a
470 @code{@var{string-output}}. This is either raw text (with an implicit new
471 line) or a quoted C string (which does not contain an implicit newline).
474 @item "~" @var{string-output}
475 The console output stream contains text that should be displayed in the
476 CLI console window. It contains the textual responses to CLI commands.
478 @item "@@" @var{string-output}
479 The target output stream contains any textual output from the running
482 @item "&" @var{string-output}
483 The log stream contains debugging messages being produced by @value{GDBN}'s
487 @node GDB/MI Out-of-band Records
488 @subsection @sc{gdb/mi} Out-of-band Records
490 @cindex out-of-band records in @sc{gdb/mi}
491 @cindex @sc{gdb/mi}, out-of-band records
492 @dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of
493 additional changes that have occurred. Those changes can either be a
494 consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
495 target activity (e.g., target stopped).
497 The following is a preliminary list of possible out-of-band records.
504 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
505 @node GDB/MI Command Description Format
506 @section @sc{gdb/mi} Command Description Format
508 The remaining sections describe blocks of commands. Each block of
509 commands is laid out in a fashion similar to this section.
511 Note the the line breaks shown in the examples are here only for
512 readability. They don't appear in the real output.
513 Also note that the commands with a non-available example (N.A.@:) are
516 @subheading Motivation
518 The motivation for this collection of commands.
520 @subheading Introduction
522 A brief introduction to this collection of commands as a whole.
526 For each command in the block, the following is described:
528 @subsubheading Synopsis
531 -command @var{args}@dots{}
534 @subsubheading @value{GDBN} Command
536 The corresponding @value{GDBN} CLI command.
538 @subsubheading Result
540 @subsubheading Out-of-band
544 @subsubheading Example
547 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
548 @node GDB/MI Breakpoint Table Commands
549 @section @sc{gdb/mi} Breakpoint table commands
551 @cindex breakpoint commands for @sc{gdb/mi}
552 @cindex @sc{gdb/mi}, breakpoint commands
553 This section documents @sc{gdb/mi} commands for manipulating
556 @subheading The @code{-break-after} Command
559 @subsubheading Synopsis
562 -break-after @var{number} @var{count}
565 The breakpoint number @var{number} is not in effect until it has been
566 hit @var{count} times. To see how this is reflected in the output of
567 the @samp{-break-list} command, see the description of the
568 @samp{-break-list} command below.
570 @subsubheading @value{GDBN} Command
572 The corresponding @value{GDBN} command is @samp{ignore}.
574 @subsubheading Example
579 ^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@}
586 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
587 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
588 addr="0x000100d0",func="main",file="hello.c",line="5",times="0",
594 @subheading The @code{-break-catch} Command
597 @subheading The @code{-break-commands} Command
598 @findex -break-commands
602 @subheading The @code{-break-condition} Command
603 @findex -break-condition
605 @subsubheading Synopsis
608 -break-condition @var{number} @var{expr}
611 Breakpoint @var{number} will stop the program only if the condition in
612 @var{expr} is true. The condition becomes part of the
613 @samp{-break-list} output (see the description of the @samp{-break-list}
616 @subsubheading @value{GDBN} Command
618 The corresponding @value{GDBN} command is @samp{condition}.
620 @subsubheading Example
628 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
629 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
630 addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",
631 times="0",ignore="3"@}@}
635 @subheading The @code{-break-delete} Command
636 @findex -break-delete
638 @subsubheading Synopsis
641 -break-delete ( @var{breakpoint} )+
644 Delete the breakpoint(s) whose number(s) are specified in the argument
645 list. This is obviously reflected in the breakpoint list.
647 @subsubheading @value{GDBN} command
649 The corresponding @value{GDBN} command is @samp{delete}.
651 @subsubheading Example
659 ^done,BreakpointTable=@{@}
663 @subheading The @code{-break-disable} Command
664 @findex -break-disable
666 @subsubheading Synopsis
669 -break-disable ( @var{breakpoint} )+
672 Disable the named @var{breakpoint}(s). The field @samp{enabled} in the
673 break list is now set to @samp{n} for the named @var{breakpoint}(s).
675 @subsubheading @value{GDBN} Command
677 The corresponding @value{GDBN} command is @samp{disable}.
679 @subsubheading Example
687 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
688 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
689 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@}
693 @subheading The @code{-break-enable} Command
694 @findex -break-enable
696 @subsubheading Synopsis
699 -break-enable ( @var{breakpoint} )+
702 Enable (previously disabled) @var{breakpoint}(s).
704 @subsubheading @value{GDBN} Command
706 The corresponding @value{GDBN} command is @samp{enable}.
708 @subsubheading Example
716 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
717 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
718 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@}
722 @subheading The @code{-break-info} Command
725 @subsubheading Synopsis
728 -break-info @var{breakpoint}
732 Get information about a single breakpoint.
734 @subsubheading @value{GDBN} command
736 The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
738 @subsubheading Example
741 @subheading The @code{-break-insert} Command
742 @findex -break-insert
744 @subsubheading Synopsis
747 -break-insert [ -t ] [ -h ] [ -r ]
748 [ -c @var{condition} ] [ -i @var{ignore-count} ]
749 [ -p @var{thread} ] [ @var{line} | @var{addr} ]
753 If specified, @var{line}, can be one of:
760 @item filename:linenum
761 @item filename:function
765 The possible optional parameters of this command are:
769 Insert a tempoary breakpoint.
771 Insert a hardware breakpoint.
772 @item -c @var{condition}
773 Make the breakpoint conditional on @var{condition}.
774 @item -i @var{ignore-count}
775 Initialize the @var{ignore-count}.
777 Insert a regular breakpoint in all the functions whose names match the
778 given regular expression. Other flags are not applicable to regular
782 @subsubheading Result
784 The result is in the form:
787 ^done,bkptno="@var{number}",func="@var{funcname}",
788 file="@var{filename}",line="@var{lineno}"
792 where @var{number} is the @value{GDBN} number for this breakpoint, @var{funcname}
793 is the name of the function where the breakpoint was inserted,
794 @var{filename} is the name of the source file which contains this
795 function, and @var{lineno} is the source line number within that file.
797 Note: this format is open to change.
798 @c An out-of-band breakpoint instead of part of the result?
800 @subsubheading @value{GDBN} Command
802 The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
803 @samp{hbreak}, @samp{thbreak}, and @samp{rbreak}.
805 @subsubheading Example
810 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
813 ^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@}
816 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
817 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
818 addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@},
819 bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
820 addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}@}
822 -break-insert -r foo.*
824 ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@}
828 @subheading The @code{-break-list} Command
831 @subsubheading Synopsis
837 Displays the list of inserted breakpoints, showing the following fields:
841 number of the breakpoint
843 type of the breakpoint: @samp{breakpoint} or @samp{watchpoint}
845 should the breakpoint be deleted or disabled when it is hit: @samp{keep}
848 is the breakpoint enabled or no: @samp{y} or @samp{n}
850 memory location at which the breakpoint is set
852 logical location of the breakpoint, expressed by function name, file
855 number of times the breakpoint has been hit
858 If there are no breakpoints or watchpoints, the @code{BreakpointTable}
859 field is an empty list.
861 @subsubheading @value{GDBN} Command
863 The corresponding @value{GDBN} command is @samp{info break}.
865 @subsubheading Example
870 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
871 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
872 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
873 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
874 addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}@}
878 Here's an example of the result when there are no breakpoints:
883 ^done,BreakpointTable=@{@}
887 @subheading The @code{-break-watch} Command
890 @subsubheading Synopsis
893 -break-watch [ -a | -r ]
896 Create a watchpoint. With the @samp{-a} option it will create an
897 @dfn{access} watchpoint, i.e. a watchpoint that triggers either on a
898 read from or on a write to the memory location. With the @samp{-r}
899 option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will
900 trigger only when the memory location is accessed for reading. Without
901 either of the options, the watchpoint created is a regular watchpoint,
902 i.e. it will trigger when the memory location is accessed for writing.
903 @xref{Set Watchpoints, , Setting watchpoints}.
905 Note that @samp{-break-list} will report a single list of watchpoints and
906 breakpoints inserted.
908 @subsubheading @value{GDBN} Command
910 The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and
913 @subsubheading Example
915 Setting a watchpoint on a variable in the @code{main} function:
920 ^done,wpt=@{number="2",exp="x"@}
924 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
925 value=@{old="-268439212",new="55"@},
926 frame=@{func="main",args=@{@},file="recursive2.c",line="5"@}
930 Setting a watchpoint on a variable local to a function. @value{GDBN} will stop
931 the program execution twice: first for the variable changing value, then
932 for the watchpoint going out of scope.
937 ^done,wpt=@{number="5",exp="C"@}
941 ^done,reason="watchpoint-trigger",
942 wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
943 frame=@{func="callee4",args=@{@},
944 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
948 ^done,reason="watchpoint-scope",wpnum="5",
949 frame=@{func="callee3",args=@{@{name="strarg",
950 value="0x11940 \"A string argument.\""@}@},
951 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
955 Listing breakpoints and watchpoints, at different points in the program
956 execution. Note that once the watchpoint goes out of scope, it is
962 ^done,wpt=@{number="2",exp="C"@}
965 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
966 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
967 addr="0x00010734",func="callee4",
968 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
969 bkpt=@{number="2",type="watchpoint",disp="keep",
970 enabled="y",addr="",what="C",times="0"@}@}
974 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
975 value=@{old="-276895068",new="3"@},
976 frame=@{func="callee4",args=@{@},
977 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
980 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
981 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
982 addr="0x00010734",func="callee4",
983 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
984 bkpt=@{number="2",type="watchpoint",disp="keep",
985 enabled="y",addr="",what="C",times="-5"@}@}
989 ^done,reason="watchpoint-scope",wpnum="2",
990 frame=@{func="callee3",args=@{@{name="strarg",
991 value="0x11940 \"A string argument.\""@}@},
992 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
995 ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@},
996 bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
997 addr="0x00010734",func="callee4",
998 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}@}
1002 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1003 @node GDB/MI Data Manipulation
1004 @section @sc{gdb/mi} Data Manipulation
1006 @cindex data manipulation, in @sc{gdb/mi}
1007 @cindex @sc{gdb/mi}, data manipulation
1008 This section describes the @sc{gdb/mi} commands that manipulate data:
1009 examine memory and registers, evaluate expressions, etc.
1011 @c REMOVED FROM THE INTERFACE.
1012 @c @subheading -data-assign
1013 @c Change the value of a program variable. Plenty of side effects.
1014 @c @subsubheading GDB command
1016 @c @subsubheading Example
1019 @subheading The @code{-data-disassemble} Command
1020 @findex -data-disassemble
1022 @subsubheading Synopsis
1026 [ -s @var{start-addr} -e @var{end-addr} ]
1027 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
1035 @item @var{start-addr}
1036 is the beginning address (or @code{$pc})
1037 @item @var{end-addr}
1039 @item @var{filename}
1040 is the name of the file to disassemble
1042 is the line number to disassemble around
1044 is the the number of disassembly lines to be produced. If it is -1,
1045 the whole function will be disassembled, in case no @var{end-addr} is
1046 specified. If @var{end-addr} is specified as a non-zero value, and
1047 @var{lines} is lower than the number of disassembly lines between
1048 @var{start-addr} and @var{end-addr}, only @var{lines} lines are
1049 displayed; if @var{lines} is higher than the number of lines between
1050 @var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
1053 is either 0 (meaning only disassembly) or 1 (meaning mixed source and
1057 @subsubheading Result
1059 The output for each instruction is composed of four fields:
1068 Note that whatever included in the instruction field, is not manipulated
1069 directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format.
1071 @subsubheading @value{GDBN} Command
1073 There's no direct mapping from this command to the CLI.
1075 @subsubheading Example
1077 Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
1081 -data-disassemble -s $pc -e "$pc + 20" -- 0
1084 @{address="0x000107c0",func-name="main",offset="4",
1085 inst="mov 2, %o0"@},
1086 @{address="0x000107c4",func-name="main",offset="8",
1087 inst="sethi %hi(0x11800), %o2"@},
1088 @{address="0x000107c8",func-name="main",offset="12",
1089 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
1090 @{address="0x000107cc",func-name="main",offset="16",
1091 inst="sethi %hi(0x11800), %o2"@},
1092 @{address="0x000107d0",func-name="main",offset="20",
1093 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}@}
1097 Disassemble the whole @code{main} function. Line 32 is part of
1101 -data-disassemble -f basics.c -l 32 -- 0
1103 @{address="0x000107bc",func-name="main",offset="0",
1104 inst="save %sp, -112, %sp"@},
1105 @{address="0x000107c0",func-name="main",offset="4",
1106 inst="mov 2, %o0"@},
1107 @{address="0x000107c4",func-name="main",offset="8",
1108 inst="sethi %hi(0x11800), %o2"@},
1110 @{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
1111 @{address="0x00010820",func-name="main",offset="100",inst="restore "@}@}
1115 Disassemble 3 instructions from the start of @code{main}:
1119 -data-disassemble -f basics.c -l 32 -n 3 -- 0
1121 @{address="0x000107bc",func-name="main",offset="0",
1122 inst="save %sp, -112, %sp"@},
1123 @{address="0x000107c0",func-name="main",offset="4",
1124 inst="mov 2, %o0"@},
1125 @{address="0x000107c4",func-name="main",offset="8",
1126 inst="sethi %hi(0x11800), %o2"@}@}
1130 Disassemble 3 instructions from the start of @code{main} in mixed mode:
1134 -data-disassemble -f basics.c -l 32 -n 3 -- 1
1136 src_and_asm_line=@{line="31",
1137 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1138 testsuite/gdb.mi/basics.c",line_asm_insn=@{
1139 @{address="0x000107bc",func-name="main",offset="0",
1140 inst="save %sp, -112, %sp"@}@}@},
1142 src_and_asm_line=@{line="32",
1143 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1144 testsuite/gdb.mi/basics.c",line_asm_insn=@{
1145 @{address="0x000107c0",func-name="main",offset="4",
1146 inst="mov 2, %o0"@},
1147 @{address="0x000107c4",func-name="main",offset="8",
1148 inst="sethi %hi(0x11800), %o2"@}@}@}@}
1153 @subheading The @code{-data-evaluate-expression} Command
1154 @findex -data-evaluate-expression
1156 @subsubheading Synopsis
1159 -data-evaluate-expression @var{expr}
1162 Evaluate @var{expr} as an expression. The expression could contain an
1163 inferior function call. The function call will execute synchronously.
1164 If the expression contains spaces, it must be enclosed in double quotes.
1166 @subsubheading @value{GDBN} Command
1168 The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
1169 @samp{call}. In @code{gdbtk} only, there's a corresponding
1170 @samp{gdb_eval} command.
1172 @subsubheading Example
1174 In the following example, the numbers that precede the commands are the
1175 @dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
1176 Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
1180 211-data-evaluate-expression A
1183 311-data-evaluate-expression &A
1184 311^done,value="0xefffeb7c"
1186 411-data-evaluate-expression A+3
1189 511-data-evaluate-expression "A + 3"
1195 @subheading The @code{-data-list-changed-registers} Command
1196 @findex -data-list-changed-registers
1198 @subsubheading Synopsis
1201 -data-list-changed-registers
1204 Display a list of the registers that have changed.
1206 @subsubheading @value{GDBN} Command
1208 @value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
1209 has the corresponding command @samp{gdb_changed_register_list}.
1211 @subsubheading Example
1221 *stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
1222 args=@{@},file="try.c",line="5"@}
1224 -data-list-changed-registers
1225 ^done,changed-registers=@{"0","1","2","4","5","6","7","8","9",
1226 "10","11","13","14","15","16","17","18","19","20","21","22","23",
1227 "24","25","26","27","28","30","31","64","65","66","67","69"@}
1232 @subheading The @code{-data-list-register-names} Command
1233 @findex -data-list-register-names
1235 @subsubheading Synopsis
1238 -data-list-register-names [ ( @var{regno} )+ ]
1241 Show a list of register names for the current target. If no arguments
1242 are given, it shows a list of the names of all the registers. If
1243 integer numbers are given as arguments, it will print a list of the
1244 names of the registers corresponding to the arguments.
1246 @subsubheading @value{GDBN} Command
1248 @value{GDBN} does not have a command which corresponds to
1249 @samp{-data-list-register-names}. In @code{gdbtk} there is a
1250 corresponding command @samp{gdb_regnames}.
1252 @subsubheading Example
1254 For the PPC MBX board:
1257 -data-list-register-names
1258 ^done,register-names=@{"r0","r1","r2","r3","r4","r5","r6","r7",
1259 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
1260 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
1261 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
1262 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
1263 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
1264 "pc","ps","cr","lr","ctr","xer"@}
1266 -data-list-register-names 1 2 3
1267 ^done,register-names=@{"r1","r2","r3"@}
1271 @subheading The @code{-data-list-register-values} Command
1272 @findex -data-list-register-values
1274 @subsubheading Synopsis
1277 -data-list-register-values @var{fmt} [ ( @var{regno} )*]
1280 Display the registers' contents. @var{fmt} is the format according to
1281 which the registers' contents are to be returned, followed by an optional
1282 list of numbers specifying the registers to display. A missing list of
1283 numbers indicates that the contents of all the registers must be returned.
1285 Allowed formats for @var{fmt} are:
1302 @subsubheading @value{GDBN} Command
1304 The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
1305 all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
1307 @subsubheading Example
1309 For a PPC MBX board (note: line breaks are for readability only, they
1310 don't appear in the actual output):
1314 -data-list-register-values r 64 65
1315 ^done,register-values=@{@{number="64",value="0xfe00a300"@},
1316 @{number="65",value="0x00029002"@}@}
1318 -data-list-register-values x
1319 ^done,register-values=@{@{number="0",value="0xfe0043c8"@},
1320 @{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
1321 @{number="3",value="0x0"@},@{number="4",value="0xa"@},
1322 @{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
1323 @{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
1324 @{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
1325 @{number="11",value="0x1"@},@{number="12",value="0x0"@},
1326 @{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
1327 @{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
1328 @{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
1329 @{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
1330 @{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
1331 @{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
1332 @{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
1333 @{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
1334 @{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
1335 @{number="31",value="0x0"@},@{number="32",value="0x0"@},
1336 @{number="33",value="0x0"@},@{number="34",value="0x0"@},
1337 @{number="35",value="0x0"@},@{number="36",value="0x0"@},
1338 @{number="37",value="0x0"@},@{number="38",value="0x0"@},
1339 @{number="39",value="0x0"@},@{number="40",value="0x0"@},
1340 @{number="41",value="0x0"@},@{number="42",value="0x0"@},
1341 @{number="43",value="0x0"@},@{number="44",value="0x0"@},
1342 @{number="45",value="0x0"@},@{number="46",value="0x0"@},
1343 @{number="47",value="0x0"@},@{number="48",value="0x0"@},
1344 @{number="49",value="0x0"@},@{number="50",value="0x0"@},
1345 @{number="51",value="0x0"@},@{number="52",value="0x0"@},
1346 @{number="53",value="0x0"@},@{number="54",value="0x0"@},
1347 @{number="55",value="0x0"@},@{number="56",value="0x0"@},
1348 @{number="57",value="0x0"@},@{number="58",value="0x0"@},
1349 @{number="59",value="0x0"@},@{number="60",value="0x0"@},
1350 @{number="61",value="0x0"@},@{number="62",value="0x0"@},
1351 @{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
1352 @{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
1353 @{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
1354 @{number="69",value="0x20002b03"@}@}
1359 @subheading The @code{-data-read-memory} Command
1360 @findex -data-read-memory
1362 @subsubheading Synopsis
1365 -data-read-memory [ -o @var{byte-offset} ]
1366 @var{address} @var{word-format} @var{word-size}
1367 @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
1375 An expression specifying the address of the first memory word to be
1376 read. Complex expressions containing embedded white space should be
1377 quoted using the C convention.
1379 @item @var{word-format}
1380 The format to be used to print the memory words. The notation is the
1381 same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
1384 @item @var{word-size}
1385 The size of each memory word in bytes.
1388 The number of rows in the output table.
1391 The number of columns in the output table.
1394 If present, indicates that each row should include an @sc{ascii} dump. The
1395 value of @var{aschar} is used as a padding character when a byte is not a
1396 member of the printable @sc{ascii} character set (printable @sc{ascii}
1397 characters are those whose code is between 32 and 126, inclusively).
1399 @item @var{byte-offset}
1400 An offset to add to the @var{address} before fetching memory.
1403 This command displays memory contents as a table of @var{nr-rows} by
1404 @var{nr-cols} words, each word being @var{word-size} bytes. In total,
1405 @code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
1406 (returned as @samp{total-bytes}). Should less then the requested number
1407 of bytes be returned by the target, the missing words are identified
1408 using @samp{N/A}. The number of bytes read from the target is returned
1409 in @samp{nr-bytes} and the starting address used to read memory in
1412 The address of the next/previous row or page is available in
1413 @samp{next-row} and @samp{prev-row}, @samp{next-page} and
1416 @subsubheading @value{GDBN} Command
1418 The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
1419 @samp{gdb_get_mem} memory read command.
1421 @subsubheading Example
1423 Read six bytes of memory starting at @code{bytes+6} but then offset by
1424 @code{-6} bytes. Format as three rows of two columns. One byte per
1425 word. Display each word in hex.
1429 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
1430 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
1431 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
1432 prev-page="0x0000138a",memory=@{
1433 @{addr="0x00001390",data=@{"0x00","0x01"@}@},
1434 @{addr="0x00001392",data=@{"0x02","0x03"@}@},
1435 @{addr="0x00001394",data=@{"0x04","0x05"@}@}@}
1439 Read two bytes of memory starting at address @code{shorts + 64} and
1440 display as a single word formatted in decimal.
1444 5-data-read-memory shorts+64 d 2 1 1
1445 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
1446 next-row="0x00001512",prev-row="0x0000150e",
1447 next-page="0x00001512",prev-page="0x0000150e",memory=@{
1448 @{addr="0x00001510",data=@{"128"@}@}@}
1452 Read thirty two bytes of memory starting at @code{bytes+16} and format
1453 as eight rows of four columns. Include a string encoding with @samp{x}
1454 used as the non-printable character.
1458 4-data-read-memory bytes+16 x 1 8 4 x
1459 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
1460 next-row="0x000013c0",prev-row="0x0000139c",
1461 next-page="0x000013c0",prev-page="0x00001380",memory=@{
1462 @{addr="0x000013a0",data=@{"0x10","0x11","0x12","0x13"@},ascii="xxxx"@},
1463 @{addr="0x000013a4",data=@{"0x14","0x15","0x16","0x17"@},ascii="xxxx"@},
1464 @{addr="0x000013a8",data=@{"0x18","0x19","0x1a","0x1b"@},ascii="xxxx"@},
1465 @{addr="0x000013ac",data=@{"0x1c","0x1d","0x1e","0x1f"@},ascii="xxxx"@},
1466 @{addr="0x000013b0",data=@{"0x20","0x21","0x22","0x23"@},ascii=" !\"#"@},
1467 @{addr="0x000013b4",data=@{"0x24","0x25","0x26","0x27"@},ascii="$%&'"@},
1468 @{addr="0x000013b8",data=@{"0x28","0x29","0x2a","0x2b"@},ascii="()*+"@},
1469 @{addr="0x000013bc",data=@{"0x2c","0x2d","0x2e","0x2f"@},ascii=",-./"@}@}
1473 @subheading The @code{-display-delete} Command
1474 @findex -display-delete
1476 @subsubheading Synopsis
1479 -display-delete @var{number}
1482 Delete the display @var{number}.
1484 @subsubheading @value{GDBN} Command
1486 The corresponding @value{GDBN} command is @samp{delete display}.
1488 @subsubheading Example
1492 @subheading The @code{-display-disable} Command
1493 @findex -display-disable
1495 @subsubheading Synopsis
1498 -display-disable @var{number}
1501 Disable display @var{number}.
1503 @subsubheading @value{GDBN} Command
1505 The corresponding @value{GDBN} command is @samp{disable display}.
1507 @subsubheading Example
1511 @subheading The @code{-display-enable} Command
1512 @findex -display-enable
1514 @subsubheading Synopsis
1517 -display-enable @var{number}
1520 Enable display @var{number}.
1522 @subsubheading @value{GDBN} Command
1524 The corresponding @value{GDBN} command is @samp{enable display}.
1526 @subsubheading Example
1530 @subheading The @code{-display-insert} Command
1531 @findex -display-insert
1533 @subsubheading Synopsis
1536 -display-insert @var{expression}
1539 Display @var{expression} every time the program stops.
1541 @subsubheading @value{GDBN} Command
1543 The corresponding @value{GDBN} command is @samp{display}.
1545 @subsubheading Example
1549 @subheading The @code{-display-list} Command
1550 @findex -display-list
1552 @subsubheading Synopsis
1558 List the displays. Do not show the current values.
1560 @subsubheading @value{GDBN} Command
1562 The corresponding @value{GDBN} command is @samp{info display}.
1564 @subsubheading Example
1568 @subheading The @code{-environment-cd} Command
1569 @findex -environment-cd
1571 @subsubheading Synopsis
1574 -environment-cd @var{pathdir}
1577 Set @value{GDBN}'s working directory.
1579 @subsubheading @value{GDBN} Command
1581 The corresponding @value{GDBN} command is @samp{cd}.
1583 @subsubheading Example
1587 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1593 @subheading The @code{-environment-directory} Command
1594 @findex -environment-directory
1596 @subsubheading Synopsis
1599 -environment-directory @var{pathdir}
1602 Add directory @var{pathdir} to beginning of search path for source files.
1604 @subsubheading @value{GDBN} Command
1606 The corresponding @value{GDBN} command is @samp{dir}.
1608 @subsubheading Example
1612 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1618 @subheading The @code{-environment-path} Command
1619 @findex -environment-path
1621 @subsubheading Synopsis
1624 -environment-path ( @var{pathdir} )+
1627 Add directories @var{pathdir} to beginning of search path for object files.
1629 @subsubheading @value{GDBN} Command
1631 The corresponding @value{GDBN} command is @samp{path}.
1633 @subsubheading Example
1637 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb
1643 @subheading The @code{-environment-pwd} Command
1644 @findex -environment-pwd
1646 @subsubheading Synopsis
1652 Show the current working directory.
1654 @subsubheading @value{GDBN} command
1656 The corresponding @value{GDBN} command is @samp{pwd}.
1658 @subsubheading Example
1663 ~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb.
1668 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1669 @node GDB/MI Program Control
1670 @section @sc{gdb/mi} Program control
1672 @subsubheading Program termination
1674 As a result of execution, the inferior program can run to completion, if
1675 it doesn't encounter any breakpoints. In this case the output will
1676 include an exit code, if the program has exited exceptionally.
1678 @subsubheading Examples
1681 Program exited normally:
1689 *stopped,reason="exited-normally"
1694 Program exited exceptionally:
1702 *stopped,reason="exited",exit-code="01"
1706 Another way the program can terminate is if it receives a signal such as
1707 @code{SIGINT}. In this case, @sc{gdb/mi} displays this:
1711 *stopped,reason="exited-signalled",signal-name="SIGINT",
1712 signal-meaning="Interrupt"
1716 @subheading The @code{-exec-abort} Command
1719 @subsubheading Synopsis
1725 Kill the inferior running program.
1727 @subsubheading @value{GDBN} Command
1729 The corresponding @value{GDBN} command is @samp{kill}.
1731 @subsubheading Example
1735 @subheading The @code{-exec-arguments} Command
1736 @findex -exec-arguments
1738 @subsubheading Synopsis
1741 -exec-arguments @var{args}
1744 Set the inferior program arguments, to be used in the next
1747 @subsubheading @value{GDBN} Command
1749 The corresponding @value{GDBN} command is @samp{set args}.
1751 @subsubheading Example
1754 Don't have one around.
1757 @subheading The @code{-exec-continue} Command
1758 @findex -exec-continue
1760 @subsubheading Synopsis
1766 Asynchronous command. Resumes the execution of the inferior program
1767 until a breakpoint is encountered, or until the inferior exits.
1769 @subsubheading @value{GDBN} Command
1771 The corresponding @value{GDBN} corresponding is @samp{continue}.
1773 @subsubheading Example
1780 *stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=@{@},
1781 file="hello.c",line="13"@}
1786 @subheading The @code{-exec-finish} Command
1787 @findex -exec-finish
1789 @subsubheading Synopsis
1795 Asynchronous command. Resumes the execution of the inferior program
1796 until the current function is exited. Displays the results returned by
1799 @subsubheading @value{GDBN} Command
1801 The corresponding @value{GDBN} command is @samp{finish}.
1803 @subsubheading Example
1805 Function returning @code{void}.
1812 *stopped,reason="function-finished",frame=@{func="main",args=@{@},
1813 file="hello.c",line="7"@}
1817 Function returning other than @code{void}. The name of the internal
1818 @value{GDBN} variable storing the result is printed, together with the
1825 *stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
1826 args=@{@{name="a",value="1"@},@{name="b",value="9"@}@},
1827 file="recursive2.c",line="14"@},
1828 gdb-result-var="$1",return-value="0"
1833 @subheading The @code{-exec-interrupt} Command
1834 @findex -exec-interrupt
1836 @subsubheading Synopsis
1842 Asynchronous command. Interrupts the background execution of the target.
1843 Note how the token associated with the stop message is the one for the
1844 execution command that has been interrupted. The token for the interrupt
1845 itself only appears in the @samp{^done} output. If the user is trying to
1846 interrupt a non-running program, an error message will be printed.
1848 @subsubheading @value{GDBN} Command
1850 The corresponding @value{GDBN} command is @samp{interrupt}.
1852 @subsubheading Example
1863 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
1864 frame=@{addr="0x00010140",func="foo",args=@{@},file="try.c",line="13"@}
1869 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
1874 @subheading The @code{-exec-next} Command
1877 @subsubheading Synopsis
1883 Asynchronous command. Resumes execution of the inferior program, stopping
1884 when the beginning of the next source line is reached.
1886 @subsubheading @value{GDBN} Command
1888 The corresponding @value{GDBN} command is @samp{next}.
1890 @subsubheading Example
1896 *stopped,reason="end-stepping-range",line="8",file="hello.c"
1901 @subheading The @code{-exec-next-instruction} Command
1902 @findex -exec-next-instruction
1904 @subsubheading Synopsis
1907 -exec-next-instruction
1910 Asynchronous command. Executes one machine instruction. If the
1911 instruction is a function call continues until the function returns. If
1912 the program stops at an instruction in the middle of a source line, the
1913 address will be printed as well.
1915 @subsubheading @value{GDBN} Command
1917 The corresponding @value{GDBN} command is @samp{nexti}.
1919 @subsubheading Example
1923 -exec-next-instruction
1927 *stopped,reason="end-stepping-range",
1928 addr="0x000100d4",line="5",file="hello.c"
1933 @subheading The @code{-exec-return} Command
1934 @findex -exec-return
1936 @subsubheading Synopsis
1942 Makes current function return immediately. Doesn't execute the inferior.
1943 Displays the new current frame.
1945 @subsubheading @value{GDBN} Command
1947 The corresponding @value{GDBN} command is @samp{return}.
1949 @subsubheading Example
1953 200-break-insert callee4
1954 200^done,bkpt=@{number="1",addr="0x00010734",
1955 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1960 000*stopped,reason="breakpoint-hit",bkptno="1",
1961 frame=@{func="callee4",args=@{@},
1962 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
1968 111^done,frame=@{level="0 ",func="callee3",
1969 args=@{@{name="strarg",
1970 value="0x11940 \"A string argument.\""@}@},
1971 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1976 @subheading The @code{-exec-run} Command
1979 @subsubheading Synopsis
1985 Asynchronous command. Starts execution of the inferior from the
1986 beginning. The inferior executes until either a breakpoint is
1987 encountered or the program exits.
1989 @subsubheading @value{GDBN} Command
1991 The corresponding @value{GDBN} command is @samp{run}.
1993 @subsubheading Example
1998 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
2003 *stopped,reason="breakpoint-hit",bkptno="1",
2004 frame=@{func="main",args=@{@},file="recursive2.c",line="4"@}
2009 @subheading The @code{-exec-show-arguments} Command
2010 @findex -exec-show-arguments
2012 @subsubheading Synopsis
2015 -exec-show-arguments
2018 Print the arguments of the program.
2020 @subsubheading @value{GDBN} Command
2022 The corresponding @value{GDBN} command is @samp{show args}.
2024 @subsubheading Example
2027 @c @subheading -exec-signal
2029 @subheading The @code{-exec-step} Command
2032 @subsubheading Synopsis
2038 Asynchronous command. Resumes execution of the inferior program, stopping
2039 when the beginning of the next source line is reached, if the next
2040 source line is not a function call. If it is, stop at the first
2041 instruction of the called function.
2043 @subsubheading @value{GDBN} Command
2045 The corresponding @value{GDBN} command is @samp{step}.
2047 @subsubheading Example
2049 Stepping into a function:
2055 *stopped,reason="end-stepping-range",
2056 frame=@{func="foo",args=@{@{name="a",value="10"@},
2057 @{name="b",value="0"@}@},file="recursive2.c",line="11"@}
2067 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
2072 @subheading The @code{-exec-step-instruction} Command
2073 @findex -exec-step-instruction
2075 @subsubheading Synopsis
2078 -exec-step-instruction
2081 Asynchronous command. Resumes the inferior which executes one machine
2082 instruction. The output, once @value{GDBN} has stopped, will vary depending on
2083 whether we have stopped in the middle of a source line or not. In the
2084 former case, the address at which the program stopped will be printed as
2087 @subsubheading @value{GDBN} Command
2089 The corresponding @value{GDBN} command is @samp{stepi}.
2091 @subsubheading Example
2095 -exec-step-instruction
2099 *stopped,reason="end-stepping-range",
2100 frame=@{func="foo",args=@{@},file="try.c",line="10"@}
2102 -exec-step-instruction
2106 *stopped,reason="end-stepping-range",
2107 frame=@{addr="0x000100f4",func="foo",args=@{@},file="try.c",line="10"@}
2112 @subheading The @code{-exec-until} Command
2115 @subsubheading Synopsis
2118 -exec-until [ @var{location} ]
2121 Asynchronous command. Executes the inferior until the @var{location}
2122 specified in the argument is reached. If there is no argument, the inferior
2123 executes until a source line greater than the current one is reached.
2124 The reason for stopping in this case will be @samp{location-reached}.
2126 @subsubheading @value{GDBN} Command
2128 The corresponding @value{GDBN} command is @samp{until}.
2130 @subsubheading Example
2134 -exec-until recursive2.c:6
2138 *stopped,reason="location-reached",frame=@{func="main",args=@{@},
2139 file="recursive2.c",line="6"@}
2144 @subheading -file-clear
2145 Is this going away????
2149 @subheading The @code{-file-exec-and-symbols} Command
2150 @findex -file-exec-and-symbols
2152 @subsubheading Synopsis
2155 -file-exec-and-symbols @var{file}
2158 Specify the executable file to be debugged. This file is the one from
2159 which the symbol table is also read. If no file is specified, the
2160 command clears the executable and symbol information. If breakpoints
2161 are set when using this command with no arguments, @value{GDBN} will produce
2162 error messages. Otherwise, no output is produced, except a completion
2165 @subsubheading @value{GDBN} Command
2167 The corresponding @value{GDBN} command is @samp{file}.
2169 @subsubheading Example
2173 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2179 @subheading The @code{-file-exec-file} Command
2180 @findex -file-exec-file
2182 @subsubheading Synopsis
2185 -file-exec-file @var{file}
2188 Specify the executable file to be debugged. Unlike
2189 @samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
2190 from this file. If used without argument, @value{GDBN} clears the information
2191 about the executable file. No output is produced, except a completion
2194 @subsubheading @value{GDBN} Command
2196 The corresponding @value{GDBN} command is @samp{exec-file}.
2198 @subsubheading Example
2202 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2208 @subheading The @code{-file-list-exec-sections} Command
2209 @findex -file-list-exec-sections
2211 @subsubheading Synopsis
2214 -file-list-exec-sections
2217 List the sections of the current executable file.
2219 @subsubheading @value{GDBN} Command
2221 The @value{GDBN} command @samp{info file} shows, among the rest, the same
2222 information as this command. @code{gdbtk} has a corresponding command
2223 @samp{gdb_load_info}.
2225 @subsubheading Example
2229 @subheading The @code{-file-list-exec-source-files} Command
2230 @findex -file-list-exec-source-files
2232 @subsubheading Synopsis
2235 -file-list-exec-source-files
2238 List the source files for the current executable.
2240 @subsubheading @value{GDBN} Command
2242 There's no @value{GDBN} command which directly corresponds to this one.
2243 @code{gdbtk} has an analogous command @samp{gdb_listfiles}.
2245 @subsubheading Example
2249 @subheading The @code{-file-list-shared-libraries} Command
2250 @findex -file-list-shared-libraries
2252 @subsubheading Synopsis
2255 -file-list-shared-libraries
2258 List the shared libraries in the program.
2260 @subsubheading @value{GDBN} Command
2262 The corresponding @value{GDBN} command is @samp{info shared}.
2264 @subsubheading Example
2268 @subheading The @code{-file-list-symbol-files} Command
2269 @findex -file-list-symbol-files
2271 @subsubheading Synopsis
2274 -file-list-symbol-files
2279 @subsubheading @value{GDBN} Command
2281 The corresponding @value{GDBN} command is @samp{info file} (part of it).
2283 @subsubheading Example
2287 @subheading The @code{-file-symbol-file} Command
2288 @findex -file-symbol-file
2290 @subsubheading Synopsis
2293 -file-symbol-file @var{file}
2296 Read symbol table info from the specified @var{file} argument. When
2297 used without arguments, clears @value{GDBN}'s symbol table info. No output is
2298 produced, except for a completion notification.
2300 @subsubheading @value{GDBN} Command
2302 The corresponding @value{GDBN} command is @samp{symbol-file}.
2304 @subsubheading Example
2308 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2313 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2314 @node GDB/MI Miscellaneous Commands
2315 @section Miscellaneous @value{GDBN} commands in @sc{gdb/mi}
2317 @c @subheading -gdb-complete
2319 @subheading The @code{-gdb-exit} Command
2322 @subsubheading Synopsis
2328 Exit @value{GDBN} immediately.
2330 @subsubheading @value{GDBN} Command
2332 Approximately corresponds to @samp{quit}.
2334 @subsubheading Example
2341 @subheading The @code{-gdb-set} Command
2344 @subsubheading Synopsis
2350 Set an internal @value{GDBN} variable.
2351 @c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
2353 @subsubheading @value{GDBN} Command
2355 The corresponding @value{GDBN} command is @samp{set}.
2357 @subsubheading Example
2367 @subheading The @code{-gdb-show} Command
2370 @subsubheading Synopsis
2376 Show the current value of a @value{GDBN} variable.
2378 @subsubheading @value{GDBN} command
2380 The corresponding @value{GDBN} command is @samp{show}.
2382 @subsubheading Example
2391 @c @subheading -gdb-source
2394 @subheading The @code{-gdb-version} Command
2395 @findex -gdb-version
2397 @subsubheading Synopsis
2403 Show version information for @value{GDBN}. Used mostly in testing.
2405 @subsubheading @value{GDBN} Command
2407 There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this
2408 information when you start an interactive session.
2410 @subsubheading Example
2412 @c This example modifies the actual output from GDB to avoid overfull
2418 ~Copyright 2000 Free Software Foundation, Inc.
2419 ~GDB is free software, covered by the GNU General Public License, and
2420 ~you are welcome to change it and/or distribute copies of it under
2421 ~ certain conditions.
2422 ~Type "show copying" to see the conditions.
2423 ~There is absolutely no warranty for GDB. Type "show warranty" for
2425 ~This GDB was configured as
2426 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
2432 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2433 @node GDB/MI Kod Commands
2434 @section @sc{gdb/mi} Kod Commands
2436 The Kod commands are not implemented.
2438 @c @subheading -kod-info
2440 @c @subheading -kod-list
2442 @c @subheading -kod-list-object-types
2444 @c @subheading -kod-show
2446 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2447 @node GDB/MI Memory Overlay Commands
2448 @section @sc{gdb/mi} Memory Overlay Commands
2450 The memory overlay commands are not implemented.
2452 @c @subheading -overlay-auto
2454 @c @subheading -overlay-list-mapping-state
2456 @c @subheading -overlay-list-overlays
2458 @c @subheading -overlay-map
2460 @c @subheading -overlay-off
2462 @c @subheading -overlay-on
2464 @c @subheading -overlay-unmap
2466 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2467 @node GDB/MI Signal Handling Commands
2468 @section @sc{gdb/mi} Signal Handling Commands
2470 Signal handling commands are not implemented.
2472 @c @subheading -signal-handle
2474 @c @subheading -signal-list-handle-actions
2476 @c @subheading -signal-list-signal-types
2480 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2481 @node GDB/MI Stack Manipulation
2482 @section Stack manipulation commands in @sc{gdb/mi}
2485 @subheading The @code{-stack-info-frame} Command
2486 @findex -stack-info-frame
2488 @subsubheading Synopsis
2494 Get info on the current frame.
2496 @subsubheading @value{GDBN} Command
2498 The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
2499 (without arguments).
2501 @subsubheading Example
2504 @subheading The @code{-stack-info-depth} Command
2505 @findex -stack-info-depth
2507 @subsubheading Synopsis
2510 -stack-info-depth [ @var{max-depth} ]
2513 Return the depth of the stack. If the integer argument @var{max-depth}
2514 is specified, do not count beyond @var{max-depth} frames.
2516 @subsubheading @value{GDBN} Command
2518 There's no equivalent @value{GDBN} command.
2520 @subsubheading Example
2522 For a stack with frame levels 0 through 11:
2532 -stack-info-depth 12
2535 -stack-info-depth 11
2538 -stack-info-depth 13
2543 @subheading The @code{-stack-list-arguments} Command
2544 @findex -stack-list-arguments
2546 @subsubheading Synopsis
2549 -stack-list-arguments @var{show-values}
2550 [ @var{low-frame} @var{high-frame} ]
2553 Display a list of the arguments for the frames between @var{low-frame}
2554 and @var{high-frame} (inclusive). If @var{low-frame} and
2555 @var{high-frame} are not provided, list the arguments for the whole call
2558 The @var{show-values} argument must have a value of 0 or 1. A value of
2559 0 means that only the names of the arguments are listed, a value of 1
2560 means that both names and values of the arguments are printed.
2562 @subsubheading @value{GDBN} Command
2564 @value{GDBN} does not have an equivalent command. @code{gdbtk} has a
2565 @samp{gdb_get_args} command which partially overlaps with the
2566 functionality of @samp{-stack-list-arguments}.
2568 @subsubheading Example
2575 frame=@{level="0 ",addr="0x00010734",func="callee4",
2576 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
2577 frame=@{level="1 ",addr="0x0001076c",func="callee3",
2578 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
2579 frame=@{level="2 ",addr="0x0001078c",func="callee2",
2580 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
2581 frame=@{level="3 ",addr="0x000107b4",func="callee1",
2582 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
2583 frame=@{level="4 ",addr="0x000107e0",func="main",
2584 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}@}
2586 -stack-list-arguments 0
2589 frame=@{level="0",args=@{@}@},
2590 frame=@{level="1",args=@{name="strarg"@}@},
2591 frame=@{level="2",args=@{name="intarg",name="strarg"@}@},
2592 frame=@{level="3",args=@{name="intarg",name="strarg",name="fltarg"@}@},
2593 frame=@{level="4",args=@{@}@}@}
2595 -stack-list-arguments 1
2598 frame=@{level="0",args=@{@}@},
2600 args=@{@{name="strarg",value="0x11940 \"A string argument.\""@}@}@},
2601 frame=@{level="2",args=@{
2602 @{name="intarg",value="2"@},
2603 @{name="strarg",value="0x11940 \"A string argument.\""@}@}@},
2604 @{frame=@{level="3",args=@{
2605 @{name="intarg",value="2"@},
2606 @{name="strarg",value="0x11940 \"A string argument.\""@},
2607 @{name="fltarg",value="3.5"@}@}@},
2608 frame=@{level="4",args=@{@}@}@}
2610 -stack-list-arguments 0 2 2
2611 ^done,stack-args=@{frame=@{level="2",args=@{name="intarg",name="strarg"@}@}@}
2613 -stack-list-arguments 1 2 2
2614 ^done,stack-args=@{frame=@{level="2",
2615 args=@{@{name="intarg",value="2"@},
2616 @{name="strarg",value="0x11940 \"A string argument.\""@}@}@}@}
2620 @c @subheading -stack-list-exception-handlers
2623 @subheading The @code{-stack-list-frames} Command
2624 @findex -stack-list-frames
2626 @subsubheading Synopsis
2629 -stack-list-frames [ @var{low-frame} @var{high-frame} ]
2632 List the frames currently on the stack. For each frame it displays the
2637 The frame number, 0 being the topmost frame, i.e. the innermost function.
2639 The @code{$pc} value for that frame.
2643 File name of the source file where the function lives.
2645 Line number corresponding to the @code{$pc}.
2648 If invoked without arguments, this command prints a backtrace for the
2649 whole stack. If given two integer arguments, it shows the frames whose
2650 levels are between the two arguments (inclusive). If the two arguments
2651 are equal, it shows the single frame at the corresponding level.
2653 @subsubheading @value{GDBN} Command
2655 The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
2657 @subsubheading Example
2659 Full stack backtrace:
2665 @{frame=@{level="0 ",addr="0x0001076c",func="foo",
2666 file="recursive2.c",line="11"@},
2667 frame=@{level="1 ",addr="0x000107a4",func="foo",
2668 file="recursive2.c",line="14"@},
2669 frame=@{level="2 ",addr="0x000107a4",func="foo",
2670 file="recursive2.c",line="14"@},
2671 frame=@{level="3 ",addr="0x000107a4",func="foo",
2672 file="recursive2.c",line="14"@},
2673 frame=@{level="4 ",addr="0x000107a4",func="foo",
2674 file="recursive2.c",line="14"@},
2675 frame=@{level="5 ",addr="0x000107a4",func="foo",
2676 file="recursive2.c",line="14"@},
2677 frame=@{level="6 ",addr="0x000107a4",func="foo",
2678 file="recursive2.c",line="14"@},
2679 frame=@{level="7 ",addr="0x000107a4",func="foo",
2680 file="recursive2.c",line="14"@},
2681 frame=@{level="8 ",addr="0x000107a4",func="foo",
2682 file="recursive2.c",line="14"@},
2683 frame=@{level="9 ",addr="0x000107a4",func="foo",
2684 file="recursive2.c",line="14"@},
2685 frame=@{level="10",addr="0x000107a4",func="foo",
2686 file="recursive2.c",line="14"@},
2687 frame=@{level="11",addr="0x00010738",func="main",
2688 file="recursive2.c",line="4"@}@}
2692 Show frames between @var{low_frame} and @var{high_frame}:
2696 -stack-list-frames 3 5
2698 @{frame=@{level="3 ",addr="0x000107a4",func="foo",
2699 file="recursive2.c",line="14"@},
2700 frame=@{level="4 ",addr="0x000107a4",func="foo",
2701 file="recursive2.c",line="14"@},
2702 frame=@{level="5 ",addr="0x000107a4",func="foo",
2703 file="recursive2.c",line="14"@}@}
2707 Show a single frame:
2711 -stack-list-frames 3 3
2713 @{frame=@{level="3 ",addr="0x000107a4",func="foo",
2714 file="recursive2.c",line="14"@}@}
2719 @subheading The @code{-stack-list-locals} Command
2720 @findex -stack-list-locals
2722 @subsubheading Synopsis
2725 -stack-list-locals @var{print-values}
2728 Display the local variable names for the current frame. With an
2729 argument of 0 prints only the names of the variables, with argument of 1
2730 prints also their values.
2732 @subsubheading @value{GDBN} Command
2734 @samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
2736 @subsubheading Example
2740 -stack-list-locals 0
2741 ^done,locals=@{name="A",name="B",name="C"@}
2743 -stack-list-locals 1
2744 ^done,locals=@{@{name="A",value="1"@},@{name="B",value="2"@},
2745 @{name="C",value="3"@}@}
2750 @subheading The @code{-stack-select-frame} Command
2751 @findex -stack-select-frame
2753 @subsubheading Synopsis
2756 -stack-select-frame @var{framenum}
2759 Change the current frame. Select a different frame @var{framenum} on
2762 @subsubheading @value{GDBN} Command
2764 The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
2765 @samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
2767 @subsubheading Example
2771 -stack-select-frame 2
2776 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2777 @node GDB/MI Symbol Query
2778 @section @sc{gdb/mi} Symbol Query Commands
2781 @subheading The @code{-symbol-info-address} Command
2782 @findex -symbol-info-address
2784 @subsubheading Synopsis
2787 -symbol-info-address @var{symbol}
2790 Describe where @var{symbol} is stored.
2792 @subsubheading @value{GDBN} Command
2794 The corresponding @value{GDBN} command is @samp{info address}.
2796 @subsubheading Example
2800 @subheading The @code{-symbol-info-file} Command
2801 @findex -symbol-info-file
2803 @subsubheading Synopsis
2809 Show the file for the symbol.
2811 @subsubheading @value{GDBN} Command
2813 There's no equivalent @value{GDBN} command. @code{gdbtk} has
2814 @samp{gdb_find_file}.
2816 @subsubheading Example
2820 @subheading The @code{-symbol-info-function} Command
2821 @findex -symbol-info-function
2823 @subsubheading Synopsis
2826 -symbol-info-function
2829 Show which function the symbol lives in.
2831 @subsubheading @value{GDBN} Command
2833 @samp{gdb_get_function} in @code{gdbtk}.
2835 @subsubheading Example
2839 @subheading The @code{-symbol-info-line} Command
2840 @findex -symbol-info-line
2842 @subsubheading Synopsis
2848 Show the core addresses of the code for a source line.
2850 @subsubheading @value{GDBN} Command
2852 The corresponding @value{GDBN} comamnd is @samp{info line}.
2853 @code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
2855 @subsubheading Example
2859 @subheading The @code{-symbol-info-symbol} Command
2860 @findex -symbol-info-symbol
2862 @subsubheading Synopsis
2865 -symbol-info-symbol @var{addr}
2868 Describe what symbol is at location @var{addr}.
2870 @subsubheading @value{GDBN} Command
2872 The corresponding @value{GDBN} command is @samp{info symbol}.
2874 @subsubheading Example
2878 @subheading The @code{-symbol-list-functions} Command
2879 @findex -symbol-list-functions
2881 @subsubheading Synopsis
2884 -symbol-list-functions
2887 List the functions in the executable.
2889 @subsubheading @value{GDBN} Command
2891 @samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
2892 @samp{gdb_search} in @code{gdbtk}.
2894 @subsubheading Example
2898 @subheading The @code{-symbol-list-types} Command
2899 @findex -symbol-list-types
2901 @subsubheading Synopsis
2907 List all the type names.
2909 @subsubheading @value{GDBN} Command
2911 The corresponding commands are @samp{info types} in @value{GDBN},
2912 @samp{gdb_search} in @code{gdbtk}.
2914 @subsubheading Example
2918 @subheading The @code{-symbol-list-variables} Command
2919 @findex -symbol-list-variables
2921 @subsubheading Synopsis
2924 -symbol-list-variables
2927 List all the global and static variable names.
2929 @subsubheading @value{GDBN} Command
2931 @samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
2933 @subsubheading Example
2937 @subheading The @code{-symbol-locate} Command
2938 @findex -symbol-locate
2940 @subsubheading Synopsis
2946 @subsubheading @value{GDBN} Command
2948 @samp{gdb_loc} in @code{gdbtk}.
2950 @subsubheading Example
2954 @subheading The @code{-symbol-type} Command
2955 @findex -symbol-type
2957 @subsubheading Synopsis
2960 -symbol-type @var{variable}
2963 Show type of @var{variable}.
2965 @subsubheading @value{GDBN} Command
2967 The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
2968 @samp{gdb_obj_variable}.
2970 @subsubheading Example
2974 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2975 @node GDB/MI Target Manipulation
2976 @section @sc{gdb/mi} Target Manipulation Commands
2979 @subheading The @code{-target-attach} Command
2980 @findex -target-attach
2982 @subsubheading Synopsis
2985 -target-attach @var{pid} | @var{file}
2988 Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
2990 @subsubheading @value{GDBN} command
2992 The corresponding @value{GDBN} command is @samp{attach}.
2994 @subsubheading Example
2998 @subheading The @code{-target-compare-sections} Command
2999 @findex -target-compare-sections
3001 @subsubheading Synopsis
3004 -target-compare-sections [ @var{section} ]
3007 Compare data of section @var{section} on target to the exec file.
3008 Without the argument, all sections are compared.
3010 @subsubheading @value{GDBN} Command
3012 The @value{GDBN} equivalent is @samp{compare-sections}.
3014 @subsubheading Example
3018 @subheading The @code{-target-detach} Command
3019 @findex -target-detach
3021 @subsubheading Synopsis
3027 Disconnect from the remote target. There's no output.
3029 @subsubheading @value{GDBN} command
3031 The corresponding @value{GDBN} command is @samp{detach}.
3033 @subsubheading Example
3043 @subheading The @code{-target-download} Command
3044 @findex -target-download
3046 @subsubheading Synopsis
3052 Loads the executable onto the remote target.
3053 It prints out an update message every half second, which includes the fields:
3057 The name of the section.
3059 The size of what has been sent so far for that section.
3061 The size of the section.
3063 The total size of what was sent so far (the current and the previous sections).
3065 The size of the overall executable to download.
3069 Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
3070 @sc{gdb/mi} Output Syntax}).
3072 In addition, it prints the name and size of the sections, as they are
3073 downloaded. These messages include the following fields:
3077 The name of the section.
3079 The size of the section.
3081 The size of the overall executable to download.
3085 At the end, a summary is printed.
3087 @subsubheading @value{GDBN} Command
3089 The corresponding @value{GDBN} command is @samp{load}.
3091 @subsubheading Example
3093 Note: each status message appears on a single line. Here the messages
3094 have been broken down so that they can fit onto a page.
3099 +download,@{section=".text",section-size="6668",total-size="9880"@}
3100 +download,@{section=".text",section-sent="512",section-size="6668",
3101 total-sent="512",total-size="9880"@}
3102 +download,@{section=".text",section-sent="1024",section-size="6668",
3103 total-sent="1024",total-size="9880"@}
3104 +download,@{section=".text",section-sent="1536",section-size="6668",
3105 total-sent="1536",total-size="9880"@}
3106 +download,@{section=".text",section-sent="2048",section-size="6668",
3107 total-sent="2048",total-size="9880"@}
3108 +download,@{section=".text",section-sent="2560",section-size="6668",
3109 total-sent="2560",total-size="9880"@}
3110 +download,@{section=".text",section-sent="3072",section-size="6668",
3111 total-sent="3072",total-size="9880"@}
3112 +download,@{section=".text",section-sent="3584",section-size="6668",
3113 total-sent="3584",total-size="9880"@}
3114 +download,@{section=".text",section-sent="4096",section-size="6668",
3115 total-sent="4096",total-size="9880"@}
3116 +download,@{section=".text",section-sent="4608",section-size="6668",
3117 total-sent="4608",total-size="9880"@}
3118 +download,@{section=".text",section-sent="5120",section-size="6668",
3119 total-sent="5120",total-size="9880"@}
3120 +download,@{section=".text",section-sent="5632",section-size="6668",
3121 total-sent="5632",total-size="9880"@}
3122 +download,@{section=".text",section-sent="6144",section-size="6668",
3123 total-sent="6144",total-size="9880"@}
3124 +download,@{section=".text",section-sent="6656",section-size="6668",
3125 total-sent="6656",total-size="9880"@}
3126 +download,@{section=".init",section-size="28",total-size="9880"@}
3127 +download,@{section=".fini",section-size="28",total-size="9880"@}
3128 +download,@{section=".data",section-size="3156",total-size="9880"@}
3129 +download,@{section=".data",section-sent="512",section-size="3156",
3130 total-sent="7236",total-size="9880"@}
3131 +download,@{section=".data",section-sent="1024",section-size="3156",
3132 total-sent="7748",total-size="9880"@}
3133 +download,@{section=".data",section-sent="1536",section-size="3156",
3134 total-sent="8260",total-size="9880"@}
3135 +download,@{section=".data",section-sent="2048",section-size="3156",
3136 total-sent="8772",total-size="9880"@}
3137 +download,@{section=".data",section-sent="2560",section-size="3156",
3138 total-sent="9284",total-size="9880"@}
3139 +download,@{section=".data",section-sent="3072",section-size="3156",
3140 total-sent="9796",total-size="9880"@}
3141 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
3147 @subheading The @code{-target-exec-status} Command
3148 @findex -target-exec-status
3150 @subsubheading Synopsis
3156 Provide information on the state of the target (whether it is running or
3159 @subsubheading @value{GDBN} Command
3161 There's no equivalent @value{GDBN} command.
3163 @subsubheading Example
3167 @subheading The @code{-target-list-available-targets} Command
3168 @findex -target-list-available-targets
3170 @subsubheading Synopsis
3173 -target-list-available-targets
3176 List the possible targets to connect to.
3178 @subsubheading @value{GDBN} Command
3180 The corresponding @value{GDBN} command is @samp{help target}.
3182 @subsubheading Example
3186 @subheading The @code{-target-list-current-targets} Command
3187 @findex -target-list-current-targets
3189 @subsubheading Synopsis
3192 -target-list-current-targets
3195 Describe the current target.
3197 @subsubheading @value{GDBN} Command
3199 The corresponding information is printed by @samp{info file} (among
3202 @subsubheading Example
3206 @subheading The @code{-target-list-parameters} Command
3207 @findex -target-list-parameters
3209 @subsubheading Synopsis
3212 -target-list-parameters
3217 @subsubheading @value{GDBN} Command
3221 @subsubheading Example
3225 @subheading The @code{-target-select} Command
3226 @findex -target-select
3228 @subsubheading Synopsis
3231 -target-select @var{type} @var{parameters @dots{}}
3234 Connect @value{GDBN} to the remote target. This command takes two args:
3238 The type of target, for instance @samp{async}, @samp{remote}, etc.
3239 @item @var{parameters}
3240 Device names, host names and the like. @xref{Target Commands, ,
3241 Commands for managing targets}, for more details.
3244 The output is a connection notification, followed by the address at
3245 which the target program is, in the following form:
3248 ^connected,addr="@var{address}",func="@var{function name}",
3249 args=@{@var{arg list}@}
3252 @subsubheading @value{GDBN} Command
3254 The corresponding @value{GDBN} command is @samp{target}.
3256 @subsubheading Example
3260 -target-select async /dev/ttya
3261 ^connected,addr="0xfe00a300",func="??",args=@{@}
3265 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3266 @node GDB/MI Thread Commands
3267 @section @sc{gdb/mi} Thread Commands
3270 @subheading The @code{-thread-info} Command
3271 @findex -thread-info
3273 @subsubheading Synopsis
3279 @subsubheading @value{GDBN} command
3283 @subsubheading Example
3287 @subheading The @code{-thread-list-all-threads} Command
3288 @findex -thread-list-all-threads
3290 @subsubheading Synopsis
3293 -thread-list-all-threads
3296 @subsubheading @value{GDBN} Command
3298 The equivalent @value{GDBN} command is @samp{info threads}.
3300 @subsubheading Example
3304 @subheading The @code{-thread-list-ids} Command
3305 @findex -thread-list-ids
3307 @subsubheading Synopsis
3313 Produces a list of the currently known @value{GDBN} thread ids. At the
3314 end of the list it also prints the total number of such threads.
3316 @subsubheading @value{GDBN} Command
3318 Part of @samp{info threads} supplies the same information.
3320 @subsubheading Example
3322 No threads present, besides the main process:
3327 ^done,thread-ids=@{@},number-of-threads="0"
3337 ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3338 number-of-threads="3"
3343 @subheading The @code{-thread-select} Command
3344 @findex -thread-select
3346 @subsubheading Synopsis
3349 -thread-select @var{threadnum}
3352 Make @var{threadnum} the current thread. It prints the number of the new
3353 current thread, and the topmost frame for that thread.
3355 @subsubheading @value{GDBN} Command
3357 The corresponding @value{GDBN} command is @samp{thread}.
3359 @subsubheading Example
3366 *stopped,reason="end-stepping-range",thread-id="2",line="187",
3367 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
3371 thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3372 number-of-threads="3"
3375 ^done,new-thread-id="3",
3376 frame=@{level="0 ",func="vprintf",
3377 args=@{@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
3378 @{name="arg",value="0x2"@}@},file="vprintf.c",line="31"@}
3382 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3383 @node GDB/MI Tracepoint Commands
3384 @section @sc{gdb/mi} Tracepoint Commands
3386 The tracepoint commands are not yet implemented.
3388 @c @subheading -trace-actions
3390 @c @subheading -trace-delete
3392 @c @subheading -trace-disable
3394 @c @subheading -trace-dump
3396 @c @subheading -trace-enable
3398 @c @subheading -trace-exists
3400 @c @subheading -trace-find
3402 @c @subheading -trace-frame-number
3404 @c @subheading -trace-info
3406 @c @subheading -trace-insert
3408 @c @subheading -trace-list
3410 @c @subheading -trace-pass-count
3412 @c @subheading -trace-save
3414 @c @subheading -trace-start
3416 @c @subheading -trace-stop
3419 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3420 @node GDB/MI Variable Objects
3421 @section @sc{gdb/mi} Variable Objects
3424 @subheading Motivation for Variable Objects in @sc{gdb/mi}
3426 For the implementation of a variable debugger window (locals, watched
3427 expressions, etc.), we are proposing the adaptation of the existing code
3428 used by @code{Insight}.
3430 The two main reasons for that are:
3434 It has been proven in practice (it is already on its second generation).
3437 It will shorten development time (needless to say how important it is
3441 The original interface was designed to be used by Tcl code, so it was
3442 slightly changed so it could be used through @sc{gdb/mi}. This section
3443 describes the @sc{gdb/mi} operations that will be available and gives some
3444 hints about their use.
3446 @emph{Note}: In addition to the set of operations described here, we
3447 expect the @sc{gui} implementation of a variable window to require, at
3448 least, the following operations:
3451 @item @code{-gdb-show} @code{output-radix}
3452 @item @code{-stack-list-arguments}
3453 @item @code{-stack-list-locals}
3454 @item @code{-stack-select-frame}
3457 @subheading Introduction to Variable Objects in @sc{gdb/mi}
3459 @cindex variable objects in @sc{gdb/mi}
3460 The basic idea behind variable objects is the creation of a named object
3461 to represent a variable, an expression, a memory location or even a CPU
3462 register. For each object created, a set of operations is available for
3463 examining or changing its properties.
3465 Furthermore, complex data types, such as C structures, are represented
3466 in a tree format. For instance, the @code{struct} type variable is the
3467 root and the children will represent the struct members. If a child
3468 is itself of a complex type, it will also have children of its own.
3469 Appropriate language differences are handled for C, C@t{++} and Java.
3471 When returning the actual values of the objects, this facility allows
3472 for the individual selection of the display format used in the result
3473 creation. It can be chosen among: binary, decimal, hexadecimal, octal
3474 and natural. Natural refers to a default format automatically
3475 chosen based on the variable type (like decimal for an @code{int}, hex
3476 for pointers, etc.).
3478 The following is the complete set of @sc{gdb/mi} operations defined to
3479 access this functionality:
3481 @multitable @columnfractions .4 .6
3482 @item @strong{Operation}
3483 @tab @strong{Description}
3485 @item @code{-var-create}
3486 @tab create a variable object
3487 @item @code{-var-delete}
3488 @tab delete the variable object and its children
3489 @item @code{-var-set-format}
3490 @tab set the display format of this variable
3491 @item @code{-var-show-format}
3492 @tab show the display format of this variable
3493 @item @code{-var-info-num-children}
3494 @tab tells how many children this object has
3495 @item @code{-var-list-children}
3496 @tab return a list of the object's children
3497 @item @code{-var-info-type}
3498 @tab show the type of this variable object
3499 @item @code{-var-info-expression}
3500 @tab print what this variable object represents
3501 @item @code{-var-show-attributes}
3502 @tab is this variable editable? does it exist here?
3503 @item @code{-var-evaluate-expression}
3504 @tab get the value of this variable
3505 @item @code{-var-assign}
3506 @tab set the value of this variable
3507 @item @code{-var-update}
3508 @tab update the variable and its children
3511 In the next subsection we describe each operation in detail and suggest
3514 @subheading Description And Use of Operations on Variable Objects
3516 @subheading The @code{-var-create} Command
3519 @subsubheading Synopsis
3522 -var-create @{@var{name} | "-"@}
3523 @{@var{frame-addr} | "*"@} @var{expression}
3526 This operation creates a variable object, which allows the monitoring of
3527 a variable, the result of an expression, a memory cell or a CPU
3530 The @var{name} parameter is the string by which the object can be
3531 referenced. It must be unique. If @samp{-} is specified, the varobj
3532 system will generate a string ``varNNNNNN'' automatically. It will be
3533 unique provided that one does not specify @var{name} on that format.
3534 The command fails if a duplicate name is found.
3536 The frame under which the expression should be evaluated can be
3537 specified by @var{frame-addr}. A @samp{*} indicates that the current
3538 frame should be used.
3540 @var{expression} is any expression valid on the current language set (must not
3541 begin with a @samp{*}), or one of the following:
3545 @samp{*@var{addr}}, where @var{addr} is the address of a memory cell
3548 @samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
3551 @samp{$@var{regname}} --- a CPU register name
3554 @subsubheading Result
3556 This operation returns the name, number of children and the type of the
3557 object created. Type is returned as a string as the ones generated by
3558 the @value{GDBN} CLI:
3561 name="@var{name}",numchild="N",type="@var{type}"
3565 @subheading The @code{-var-delete} Command
3568 @subsubheading Synopsis
3571 -var-delete @var{name}
3574 Deletes a previously created variable object and all of its children.
3576 Returns an error if the object @var{name} is not found.
3579 @subheading The @code{-var-set-format} Command
3580 @findex -var-set-format
3582 @subsubheading Synopsis
3585 -var-set-format @var{name} @var{format-spec}
3588 Sets the output format for the value of the object @var{name} to be
3591 The syntax for the @var{format-spec} is as follows:
3594 @var{format-spec} @expansion{}
3595 @{binary | decimal | hexadecimal | octal | natural@}
3599 @subheading The @code{-var-show-format} Command
3600 @findex -var-show-format
3602 @subsubheading Synopsis
3605 -var-show-format @var{name}
3608 Returns the format used to display the value of the object @var{name}.
3611 @var{format} @expansion{}
3616 @subheading The @code{-var-info-num-children} Command
3617 @findex -var-info-num-children
3619 @subsubheading Synopsis
3622 -var-info-num-children @var{name}
3625 Returns the number of children of a variable object @var{name}:
3632 @subheading The @code{-var-list-children} Command
3633 @findex -var-list-children
3635 @subsubheading Synopsis
3638 -var-list-children @var{name}
3641 Returns a list of the children of the specified variable object:
3644 numchild=@var{n},children=@{@{name=@var{name},
3645 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}@}
3649 @subheading The @code{-var-info-type} Command
3650 @findex -var-info-type
3652 @subsubheading Synopsis
3655 -var-info-type @var{name}
3658 Returns the type of the specified variable @var{name}. The type is
3659 returned as a string in the same format as it is output by the
3667 @subheading The @code{-var-info-expression} Command
3668 @findex -var-info-expression
3670 @subsubheading Synopsis
3673 -var-info-expression @var{name}
3676 Returns what is represented by the variable object @var{name}:
3679 lang=@var{lang-spec},exp=@var{expression}
3683 where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
3685 @subheading The @code{-var-show-attributes} Command
3686 @findex -var-show-attributes
3688 @subsubheading Synopsis
3691 -var-show-attributes @var{name}
3694 List attributes of the specified variable object @var{name}:
3697 status=@var{attr} [ ( ,@var{attr} )* ]
3701 where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
3703 @subheading The @code{-var-evaluate-expression} Command
3704 @findex -var-evaluate-expression
3706 @subsubheading Synopsis
3709 -var-evaluate-expression @var{name}
3712 Evaluates the expression that is represented by the specified variable
3713 object and returns its value as a string in the current format specified
3720 @subheading The @code{-var-assign} Command
3723 @subsubheading Synopsis
3726 -var-assign @var{name} @var{expression}
3729 Assigns the value of @var{expression} to the variable object specified
3730 by @var{name}. The object must be @samp{editable}.
3732 @subheading The @code{-var-update} Command
3735 @subsubheading Synopsis
3738 -var-update @{@var{name} | "*"@}
3741 Update the value of the variable object @var{name} by evaluating its
3742 expression after fetching all the new values from memory or registers.
3743 A @samp{*} causes all existing variable objects to be updated.
3745 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3746 @node GDB/MI Draft Changes to Output Syntax
3747 @section @sc{gdb/mi} Draft Changes to Output Syntax
3749 @cindex draft changes to output syntax of @sc{gdb/mi}
3750 @cindex @sc{gdb/mi}, draft changes to output syntax
3752 One problem identified in the existing @sc{gdb/mi} output syntax was the
3753 difficulty in differentiating between a tuple such as:
3756 @{number="1",type="breakpoint",disp="keep",enabled="y"@}
3759 where each value has a unique label, and a list such as:
3763 @{bp="1",bp="2",bp="4"@}
3766 where values are un-labeled or the label is duplicated.
3768 What follows is a draft revision to the output specification that
3769 addresses this problem.
3771 The output from @sc{gdb/mi} consists of zero or more out-of-band records
3772 optionally followed by a single result record, the result record being
3773 for the most recent command input. The sequence is terminated by
3774 @samp{(@value{GDBP})}.
3776 Asynchronous @sc{gdb/mi} output is similar.
3778 Each output record directly associated with an input command is prefixed
3779 by the input command's @code{@var{token}}.
3782 @item @var{output} @expansion{}
3783 @{ @var{out-of-band-record} @} @code{[} @var{result-record} @code{]} "@code{(@value{GDBP})}" @var{nl}
3785 @item @var{result-record} @expansion{}
3786 @code{[} @var{token} @code{]} "^" @var{result-class} @{ "," @var{result} @} @var{nl}
3788 @item @var{out-of-band-record} @expansion{}
3789 @var{async-record} @code{|} @var{stream-record}
3791 @item @var{async-record} @expansion{}
3792 @var{exec-async-output} @code{|} @var{status-async-output} @code{|} @var{notify-async-output}
3794 @item @var{exec-async-output} @expansion{}
3795 @code{[} @var{token} @code{]} "*" @var{async-output}
3797 @item @var{status-async-output} @expansion{}
3798 @code{[} @var{token} @code{]} "+" @var{async-output}
3800 @item @var{notify-async-output} @expansion{}
3801 @code{[} @var{token} @code{]} "=" @var{async-output}
3803 @item @var{async-output} @expansion{}
3804 @var{async-class} @{ "," @var{result} @} @var{nl}
3806 @item @var{result-class} @expansion{}
3807 "done" @code{|} "running" @code{|} "connected" @code{|} "error" @code{|} "exit"
3809 @item @var{async-class} @expansion{}
3810 "stopped" @code{|} @emph{others depending on need as still in development}
3812 @item @var{result} @expansion{}
3813 @var{string} "=" @var{value}
3815 @item @var{value} @expansion{}
3816 @var{c-string} @code{|} @var{tupple} @code{|} @var{list}
3818 @item @var{tupple} @expansion{}
3819 "@{@}" @code{|} "@{" @var{result} @{ "," @var{result} @} "@}"
3821 @item @var{list} @expansion{}
3822 "@code{[]}" @code{|} "@code{[}" @var{value} @{ "," @var{value} @} "@code{]}"
3824 @item @var{string} @expansion{}
3825 @emph{[-A-Za-z\.0-9_]*}
3827 @item @var{c-string} @expansion{}
3828 @emph{See the input specification}
3830 @item @var{stream-record} @expansion{}
3831 @var{console-stream-output} @code{|} @var{target-stream-output} @code{|} @var{log-stream-output}
3833 @item @var{console-stream-output} @expansion{}
3836 @item @var{target-stream-output} @expansion{}
3839 @item @var{log-stream-output} @expansion{}
3842 @item @var{nl} @expansion{}
3845 @item @var{token} @expansion{}
3846 "any sequence of digits"
3850 In addition, the following are still being developed.
3855 This action is currently undefined.
3864 All output sequences end in a single line containing a period.
3867 The @code{@var{token}} is from the corresponding request. If an execution
3868 command is interrupted by the @code{-exec-interrupt} command, the token
3869 associated with the `*stopped' message is the one of the original
3870 execution command, not the one of the interrupt command.
3873 @var{status-async-output} contains on-going status information about the
3874 progress of a slow operation. It can be discarded. All status output is
3875 prefixed by the prefix @samp{+}.
3878 @var{exec-async-output} contains asynchronous state change on the target
3879 (stopped, started, disappeared). All async output is prefixed by
3880 the prefix @samp{*}.
3883 @var{notify-async-output} contains supplementary information that the
3884 client should handle (new breakpoint information). All notify output is
3885 prefixed by the prefix @samp{=}.
3888 @var{console-stream-output} is output that should be displayed as is, in the
3889 console. It is the textual response to a CLI command. All the console
3890 output is prefixed by the prefix @samp{~}.
3893 @var{target-stream-output} is the output produced by the target program.
3894 All the target output is prefixed by the prefix @samp{@@}.
3897 @var{log-stream-output} is output text coming from @value{GDBN}'s
3898 internals, for instance messages that should be displayed as part of an
3899 error log. All the log output is prefixed by the prefix @samp{&}.
3904 @c change-log-default-name: "ChangeLog-mi"