1 @c \input texinfo @c -*-texinfo-*-
2 @c @c %**start of header
3 @c @setfilename gdbmi.info
4 @c @settitle GDB/MI Machine Interface
5 @c @setchapternewpage off
9 @c This file documents GDB/MI, a Machine Interface to GDB.
11 @c Copyright 2000, 2001, 2002 Free Software Foundation, Inc.
12 @c Contributed by Cygnus Solutions.
14 @c Permission is granted to copy, distribute and/or modify this document
15 @c under the terms of the GNU Free Documentation License, Version 1.1 or
16 @c any later version published by the Free Software Foundation; with no
17 @c Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
18 @c and with the Back-Cover Texts as in (a) below.
20 @c (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
21 @c this GNU Manual, like GNU software. Copies published by the Free
22 @c Software Foundation raise funds for GNU development.''
25 @c @c This title page illustrates only one of the
26 @c @c two methods of forming a title page.
30 @c @subtitle Version 0.3
32 @c @author Andrew Cagney, Fernando Nasser and Elena Zannoni
34 @c @c The following two commands
35 @c @c start the copyright page.
37 @c @vskip 0pt plus 1filll
39 @c Copyright @copyright{} 2000, 2001, 2002 Free Software Foundation, Inc.
41 @c Permission is granted to copy, distribute and/or modify this document
42 @c under the terms of the GNU Free Documentation License, Version 1.1 or
43 @c any later version published by the Free Software Foundation; with no
44 @c Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
45 @c and with the Back-Cover Texts as in (a) below.
47 @c (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
48 @c this GNU Manual, like GNU software. Copies published by the Free
49 @c Software Foundation raise funds for GNU development.''
52 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
54 @chapter The @sc{gdb/mi} Interface
56 @unnumberedsec Function and Purpose
58 @cindex @sc{gdb/mi}, its purpose
59 @sc{gdb/mi} is a line based machine oriented text interface to @value{GDBN}. It is
60 specifically intended to support the development of systems which use
61 the debugger as just one small component of a larger system.
63 This chapter is a specification of the @sc{gdb/mi} interface. It is written
64 in the form of a reference manual.
66 Note that @sc{gdb/mi} is still under construction, so some of the
67 features described below are incomplete and subject to change.
69 @unnumberedsec Notation and Terminology
71 @cindex notational conventions, for @sc{gdb/mi}
72 This chapter uses the following notation:
76 @code{|} separates two alternatives.
79 @code{[ @var{something} ]} indicates that @var{something} is optional:
80 it may or may not be given.
83 @code{( @var{group} )*} means that @var{group} inside the parentheses
84 may repeat zero or more times.
87 @code{( @var{group} )+} means that @var{group} inside the parentheses
88 may repeat one or more times.
91 @code{"@var{string}"} means a literal @var{string}.
98 @heading Acknowledgments
100 In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
104 * GDB/MI Command Syntax::
105 * GDB/MI Compatibility with CLI::
106 * GDB/MI Output Records::
107 * GDB/MI Command Description Format::
108 * GDB/MI Breakpoint Table Commands::
109 * GDB/MI Data Manipulation::
110 * GDB/MI Program Control::
111 * GDB/MI Miscellaneous Commands::
113 * GDB/MI Kod Commands::
114 * GDB/MI Memory Overlay Commands::
115 * GDB/MI Signal Handling Commands::
117 * GDB/MI Stack Manipulation::
118 * GDB/MI Symbol Query::
119 * GDB/MI Target Manipulation::
120 * GDB/MI Thread Commands::
121 * GDB/MI Tracepoint Commands::
122 * GDB/MI Variable Objects::
125 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
126 @node GDB/MI Command Syntax
127 @section @sc{gdb/mi} Command Syntax
130 * GDB/MI Input Syntax::
131 * GDB/MI Output Syntax::
132 * GDB/MI Simple Examples::
135 @node GDB/MI Input Syntax
136 @subsection @sc{gdb/mi} Input Syntax
138 @cindex input syntax for @sc{gdb/mi}
139 @cindex @sc{gdb/mi}, input syntax
141 @item @var{command} @expansion{}
142 @code{@var{cli-command} | @var{mi-command}}
144 @item @var{cli-command} @expansion{}
145 @code{[ @var{token} ] @var{cli-command} @var{nl}}, where
146 @var{cli-command} is any existing @value{GDBN} CLI command.
148 @item @var{mi-command} @expansion{}
149 @code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )*
150 @code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}}
152 @item @var{token} @expansion{}
153 "any sequence of digits"
155 @item @var{option} @expansion{}
156 @code{"-" @var{parameter} [ " " @var{parameter} ]}
158 @item @var{parameter} @expansion{}
159 @code{@var{non-blank-sequence} | @var{c-string}}
161 @item @var{operation} @expansion{}
162 @emph{any of the operations described in this chapter}
164 @item @var{non-blank-sequence} @expansion{}
165 @emph{anything, provided it doesn't contain special characters such as
166 "-", @var{nl}, """ and of course " "}
168 @item @var{c-string} @expansion{}
169 @code{""" @var{seven-bit-iso-c-string-content} """}
171 @item @var{nl} @expansion{}
180 The CLI commands are still handled by the @sc{mi} interpreter; their
181 output is described below.
184 The @code{@var{token}}, when present, is passed back when the command
188 Some @sc{mi} commands accept optional arguments as part of the parameter
189 list. Each option is identified by a leading @samp{-} (dash) and may be
190 followed by an optional argument parameter. Options occur first in the
191 parameter list and can be delimited from normal parameters using
192 @samp{--} (this is useful when some parameters begin with a dash).
199 We want easy access to the existing CLI syntax (for debugging).
202 We want it to be easy to spot a @sc{mi} operation.
205 @node GDB/MI Output Syntax
206 @subsection @sc{gdb/mi} Output Syntax
208 @cindex output syntax of @sc{gdb/mi}
209 @cindex @sc{gdb/mi}, output syntax
210 The output from @sc{gdb/mi} consists of zero or more out-of-band records
211 followed, optionally, by a single result record. This result record
212 is for the most recent command. The sequence of output records is
213 terminated by @samp{(@value{GDBP})}.
215 If an input command was prefixed with a @code{@var{token}} then the
216 corresponding output for that command will also be prefixed by that same
220 @item @var{output} @expansion{}
221 @code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
223 @item @var{result-record} @expansion{}
224 @code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
226 @item @var{out-of-band-record} @expansion{}
227 @code{@var{async-record} | @var{stream-record}}
229 @item @var{async-record} @expansion{}
230 @code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
232 @item @var{exec-async-output} @expansion{}
233 @code{[ @var{token} ] "*" @var{async-output}}
235 @item @var{status-async-output} @expansion{}
236 @code{[ @var{token} ] "+" @var{async-output}}
238 @item @var{notify-async-output} @expansion{}
239 @code{[ @var{token} ] "=" @var{async-output}}
241 @item @var{async-output} @expansion{}
242 @code{@var{async-class} ( "," @var{result} )* @var{nl}}
244 @item @var{result-class} @expansion{}
245 @code{"done" | "running" | "connected" | "error" | "exit"}
247 @item @var{async-class} @expansion{}
248 @code{"stopped" | @var{others}} (where @var{others} will be added
249 depending on the needs---this is still in development).
251 @item @var{result} @expansion{}
252 @code{ @var{variable} "=" @var{value}}
254 @item @var{variable} @expansion{}
255 @code{ @var{string} }
257 @item @var{value} @expansion{}
258 @code{ @var{const} | @var{tuple} | @var{list} }
260 @item @var{const} @expansion{}
261 @code{@var{c-string}}
263 @item @var{tuple} @expansion{}
264 @code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" }
266 @item @var{list} @expansion{}
267 @code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "["
268 @var{result} ( "," @var{result} )* "]" }
270 @item @var{stream-record} @expansion{}
271 @code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
273 @item @var{console-stream-output} @expansion{}
274 @code{"~" @var{c-string}}
276 @item @var{target-stream-output} @expansion{}
277 @code{"@@" @var{c-string}}
279 @item @var{log-stream-output} @expansion{}
280 @code{"&" @var{c-string}}
282 @item @var{nl} @expansion{}
285 @item @var{token} @expansion{}
286 @emph{any sequence of digits}.
294 All output sequences end in a single line containing a period.
297 The @code{@var{token}} is from the corresponding request. If an execution
298 command is interrupted by the @samp{-exec-interrupt} command, the
299 @var{token} associated with the @samp{*stopped} message is the one of the
300 original execution command, not the one of the interrupt command.
303 @cindex status output in @sc{gdb/mi}
304 @var{status-async-output} contains on-going status information about the
305 progress of a slow operation. It can be discarded. All status output is
306 prefixed by @samp{+}.
309 @cindex async output in @sc{gdb/mi}
310 @var{exec-async-output} contains asynchronous state change on the target
311 (stopped, started, disappeared). All async output is prefixed by
315 @cindex notify output in @sc{gdb/mi}
316 @var{notify-async-output} contains supplementary information that the
317 client should handle (e.g., a new breakpoint information). All notify
318 output is prefixed by @samp{=}.
321 @cindex console output in @sc{gdb/mi}
322 @var{console-stream-output} is output that should be displayed as is in the
323 console. It is the textual response to a CLI command. All the console
324 output is prefixed by @samp{~}.
327 @cindex target output in @sc{gdb/mi}
328 @var{target-stream-output} is the output produced by the target program.
329 All the target output is prefixed by @samp{@@}.
332 @cindex log output in @sc{gdb/mi}
333 @var{log-stream-output} is output text coming from @value{GDBN}'s internals, for
334 instance messages that should be displayed as part of an error log. All
335 the log output is prefixed by @samp{&}.
338 @cindex list output in @sc{gdb/mi}
339 New @sc{gdb/mi} commands should only output @var{lists} containing
345 @xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
346 details about the various output records.
348 @node GDB/MI Simple Examples
349 @subsection Simple Examples of @sc{gdb/mi} Interaction
350 @cindex @sc{gdb/mi}, simple examples
352 This subsection presents several simple examples of interaction using
353 the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
354 following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
355 the output received from @sc{gdb/mi}.
357 @subsubheading Target Stop
358 @c Ummm... There is no "-stop" command. This assumes async, no?
359 Here's an example of stopping the inferior process:
370 <- *stop,reason="stop",address="0x123",source="a.c:123"
374 @subsubheading Simple CLI Command
376 Here's an example of a simple CLI command being passed through
377 @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,msg="Undefined MI command: rubbish"
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=@{nr_rows="1",nr_cols="6",
587 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
588 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
589 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
590 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
591 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
592 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
593 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
594 addr="0x000100d0",func="main",file="hello.c",line="5",times="0",
600 @subheading The @code{-break-catch} Command
603 @subheading The @code{-break-commands} Command
604 @findex -break-commands
608 @subheading The @code{-break-condition} Command
609 @findex -break-condition
611 @subsubheading Synopsis
614 -break-condition @var{number} @var{expr}
617 Breakpoint @var{number} will stop the program only if the condition in
618 @var{expr} is true. The condition becomes part of the
619 @samp{-break-list} output (see the description of the @samp{-break-list}
622 @subsubheading @value{GDBN} Command
624 The corresponding @value{GDBN} command is @samp{condition}.
626 @subsubheading Example
634 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
635 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
636 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
637 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
638 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
639 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
640 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
641 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
642 addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",
643 times="0",ignore="3"@}]@}
647 @subheading The @code{-break-delete} Command
648 @findex -break-delete
650 @subsubheading Synopsis
653 -break-delete ( @var{breakpoint} )+
656 Delete the breakpoint(s) whose number(s) are specified in the argument
657 list. This is obviously reflected in the breakpoint list.
659 @subsubheading @value{GDBN} command
661 The corresponding @value{GDBN} command is @samp{delete}.
663 @subsubheading Example
671 ^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
672 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
673 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
674 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
675 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
676 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
677 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
682 @subheading The @code{-break-disable} Command
683 @findex -break-disable
685 @subsubheading Synopsis
688 -break-disable ( @var{breakpoint} )+
691 Disable the named @var{breakpoint}(s). The field @samp{enabled} in the
692 break list is now set to @samp{n} for the named @var{breakpoint}(s).
694 @subsubheading @value{GDBN} Command
696 The corresponding @value{GDBN} command is @samp{disable}.
698 @subsubheading Example
706 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
707 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
708 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
709 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
710 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
711 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
712 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
713 body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
714 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@}
718 @subheading The @code{-break-enable} Command
719 @findex -break-enable
721 @subsubheading Synopsis
724 -break-enable ( @var{breakpoint} )+
727 Enable (previously disabled) @var{breakpoint}(s).
729 @subsubheading @value{GDBN} Command
731 The corresponding @value{GDBN} command is @samp{enable}.
733 @subsubheading Example
741 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
742 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
743 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
744 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
745 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
746 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
747 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
748 body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
749 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@}
753 @subheading The @code{-break-info} Command
756 @subsubheading Synopsis
759 -break-info @var{breakpoint}
763 Get information about a single breakpoint.
765 @subsubheading @value{GDBN} command
767 The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
769 @subsubheading Example
772 @subheading The @code{-break-insert} Command
773 @findex -break-insert
775 @subsubheading Synopsis
778 -break-insert [ -t ] [ -h ] [ -r ]
779 [ -c @var{condition} ] [ -i @var{ignore-count} ]
780 [ -p @var{thread} ] [ @var{line} | @var{addr} ]
784 If specified, @var{line}, can be one of:
791 @item filename:linenum
792 @item filename:function
796 The possible optional parameters of this command are:
800 Insert a tempoary breakpoint.
802 Insert a hardware breakpoint.
803 @item -c @var{condition}
804 Make the breakpoint conditional on @var{condition}.
805 @item -i @var{ignore-count}
806 Initialize the @var{ignore-count}.
808 Insert a regular breakpoint in all the functions whose names match the
809 given regular expression. Other flags are not applicable to regular
813 @subsubheading Result
815 The result is in the form:
818 ^done,bkptno="@var{number}",func="@var{funcname}",
819 file="@var{filename}",line="@var{lineno}"
823 where @var{number} is the @value{GDBN} number for this breakpoint, @var{funcname}
824 is the name of the function where the breakpoint was inserted,
825 @var{filename} is the name of the source file which contains this
826 function, and @var{lineno} is the source line number within that file.
828 Note: this format is open to change.
829 @c An out-of-band breakpoint instead of part of the result?
831 @subsubheading @value{GDBN} Command
833 The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
834 @samp{hbreak}, @samp{thbreak}, and @samp{rbreak}.
836 @subsubheading Example
841 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
844 ^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@}
847 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
848 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
849 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
850 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
851 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
852 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
853 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
854 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
855 addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@},
856 bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
857 addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}]@}
859 -break-insert -r foo.*
861 ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@}
865 @subheading The @code{-break-list} Command
868 @subsubheading Synopsis
874 Displays the list of inserted breakpoints, showing the following fields:
878 number of the breakpoint
880 type of the breakpoint: @samp{breakpoint} or @samp{watchpoint}
882 should the breakpoint be deleted or disabled when it is hit: @samp{keep}
885 is the breakpoint enabled or no: @samp{y} or @samp{n}
887 memory location at which the breakpoint is set
889 logical location of the breakpoint, expressed by function name, file
892 number of times the breakpoint has been hit
895 If there are no breakpoints or watchpoints, the @code{BreakpointTable}
896 @code{body} field is an empty list.
898 @subsubheading @value{GDBN} Command
900 The corresponding @value{GDBN} command is @samp{info break}.
902 @subsubheading Example
907 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
908 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
909 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
910 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
911 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
912 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
913 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
914 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
915 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
916 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
917 addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}]@}
921 Here's an example of the result when there are no breakpoints:
926 ^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
927 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
928 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
929 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
930 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
931 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
932 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
937 @subheading The @code{-break-watch} Command
940 @subsubheading Synopsis
943 -break-watch [ -a | -r ]
946 Create a watchpoint. With the @samp{-a} option it will create an
947 @dfn{access} watchpoint, i.e. a watchpoint that triggers either on a
948 read from or on a write to the memory location. With the @samp{-r}
949 option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will
950 trigger only when the memory location is accessed for reading. Without
951 either of the options, the watchpoint created is a regular watchpoint,
952 i.e. it will trigger when the memory location is accessed for writing.
953 @xref{Set Watchpoints, , Setting watchpoints}.
955 Note that @samp{-break-list} will report a single list of watchpoints and
956 breakpoints inserted.
958 @subsubheading @value{GDBN} Command
960 The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and
963 @subsubheading Example
965 Setting a watchpoint on a variable in the @code{main} function:
970 ^done,wpt=@{number="2",exp="x"@}
974 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
975 value=@{old="-268439212",new="55"@},
976 frame=@{func="main",args=[],file="recursive2.c",line="5"@}
980 Setting a watchpoint on a variable local to a function. @value{GDBN} will stop
981 the program execution twice: first for the variable changing value, then
982 for the watchpoint going out of scope.
987 ^done,wpt=@{number="5",exp="C"@}
991 ^done,reason="watchpoint-trigger",
992 wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
993 frame=@{func="callee4",args=[],
994 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
998 ^done,reason="watchpoint-scope",wpnum="5",
999 frame=@{func="callee3",args=[@{name="strarg",
1000 value="0x11940 \"A string argument.\""@}],
1001 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1005 Listing breakpoints and watchpoints, at different points in the program
1006 execution. Note that once the watchpoint goes out of scope, it is
1012 ^done,wpt=@{number="2",exp="C"@}
1015 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
1016 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
1017 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
1018 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
1019 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
1020 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
1021 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
1022 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
1023 addr="0x00010734",func="callee4",
1024 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
1025 bkpt=@{number="2",type="watchpoint",disp="keep",
1026 enabled="y",addr="",what="C",times="0"@}]@}
1030 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
1031 value=@{old="-276895068",new="3"@},
1032 frame=@{func="callee4",args=[],
1033 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
1036 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
1037 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
1038 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
1039 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
1040 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
1041 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
1042 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
1043 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
1044 addr="0x00010734",func="callee4",
1045 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
1046 bkpt=@{number="2",type="watchpoint",disp="keep",
1047 enabled="y",addr="",what="C",times="-5"@}]@}
1051 ^done,reason="watchpoint-scope",wpnum="2",
1052 frame=@{func="callee3",args=[@{name="strarg",
1053 value="0x11940 \"A string argument.\""@}],
1054 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1057 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
1058 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
1059 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
1060 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
1061 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
1062 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
1063 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
1064 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
1065 addr="0x00010734",func="callee4",
1066 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}]@}
1070 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1071 @node GDB/MI Data Manipulation
1072 @section @sc{gdb/mi} Data Manipulation
1074 @cindex data manipulation, in @sc{gdb/mi}
1075 @cindex @sc{gdb/mi}, data manipulation
1076 This section describes the @sc{gdb/mi} commands that manipulate data:
1077 examine memory and registers, evaluate expressions, etc.
1079 @c REMOVED FROM THE INTERFACE.
1080 @c @subheading -data-assign
1081 @c Change the value of a program variable. Plenty of side effects.
1082 @c @subsubheading GDB command
1084 @c @subsubheading Example
1087 @subheading The @code{-data-disassemble} Command
1088 @findex -data-disassemble
1090 @subsubheading Synopsis
1094 [ -s @var{start-addr} -e @var{end-addr} ]
1095 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
1103 @item @var{start-addr}
1104 is the beginning address (or @code{$pc})
1105 @item @var{end-addr}
1107 @item @var{filename}
1108 is the name of the file to disassemble
1110 is the line number to disassemble around
1112 is the the number of disassembly lines to be produced. If it is -1,
1113 the whole function will be disassembled, in case no @var{end-addr} is
1114 specified. If @var{end-addr} is specified as a non-zero value, and
1115 @var{lines} is lower than the number of disassembly lines between
1116 @var{start-addr} and @var{end-addr}, only @var{lines} lines are
1117 displayed; if @var{lines} is higher than the number of lines between
1118 @var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
1121 is either 0 (meaning only disassembly) or 1 (meaning mixed source and
1125 @subsubheading Result
1127 The output for each instruction is composed of four fields:
1136 Note that whatever included in the instruction field, is not manipulated
1137 directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format.
1139 @subsubheading @value{GDBN} Command
1141 There's no direct mapping from this command to the CLI.
1143 @subsubheading Example
1145 Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
1149 -data-disassemble -s $pc -e "$pc + 20" -- 0
1152 @{address="0x000107c0",func-name="main",offset="4",
1153 inst="mov 2, %o0"@},
1154 @{address="0x000107c4",func-name="main",offset="8",
1155 inst="sethi %hi(0x11800), %o2"@},
1156 @{address="0x000107c8",func-name="main",offset="12",
1157 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
1158 @{address="0x000107cc",func-name="main",offset="16",
1159 inst="sethi %hi(0x11800), %o2"@},
1160 @{address="0x000107d0",func-name="main",offset="20",
1161 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}]
1165 Disassemble the whole @code{main} function. Line 32 is part of
1169 -data-disassemble -f basics.c -l 32 -- 0
1171 @{address="0x000107bc",func-name="main",offset="0",
1172 inst="save %sp, -112, %sp"@},
1173 @{address="0x000107c0",func-name="main",offset="4",
1174 inst="mov 2, %o0"@},
1175 @{address="0x000107c4",func-name="main",offset="8",
1176 inst="sethi %hi(0x11800), %o2"@},
1178 @{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
1179 @{address="0x00010820",func-name="main",offset="100",inst="restore "@}]
1183 Disassemble 3 instructions from the start of @code{main}:
1187 -data-disassemble -f basics.c -l 32 -n 3 -- 0
1189 @{address="0x000107bc",func-name="main",offset="0",
1190 inst="save %sp, -112, %sp"@},
1191 @{address="0x000107c0",func-name="main",offset="4",
1192 inst="mov 2, %o0"@},
1193 @{address="0x000107c4",func-name="main",offset="8",
1194 inst="sethi %hi(0x11800), %o2"@}]
1198 Disassemble 3 instructions from the start of @code{main} in mixed mode:
1202 -data-disassemble -f basics.c -l 32 -n 3 -- 1
1204 src_and_asm_line=@{line="31",
1205 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1206 testsuite/gdb.mi/basics.c",line_asm_insn=[
1207 @{address="0x000107bc",func-name="main",offset="0",
1208 inst="save %sp, -112, %sp"@}]@},
1209 src_and_asm_line=@{line="32",
1210 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1211 testsuite/gdb.mi/basics.c",line_asm_insn=[
1212 @{address="0x000107c0",func-name="main",offset="4",
1213 inst="mov 2, %o0"@},
1214 @{address="0x000107c4",func-name="main",offset="8",
1215 inst="sethi %hi(0x11800), %o2"@}]@}]
1220 @subheading The @code{-data-evaluate-expression} Command
1221 @findex -data-evaluate-expression
1223 @subsubheading Synopsis
1226 -data-evaluate-expression @var{expr}
1229 Evaluate @var{expr} as an expression. The expression could contain an
1230 inferior function call. The function call will execute synchronously.
1231 If the expression contains spaces, it must be enclosed in double quotes.
1233 @subsubheading @value{GDBN} Command
1235 The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
1236 @samp{call}. In @code{gdbtk} only, there's a corresponding
1237 @samp{gdb_eval} command.
1239 @subsubheading Example
1241 In the following example, the numbers that precede the commands are the
1242 @dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
1243 Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
1247 211-data-evaluate-expression A
1250 311-data-evaluate-expression &A
1251 311^done,value="0xefffeb7c"
1253 411-data-evaluate-expression A+3
1256 511-data-evaluate-expression "A + 3"
1262 @subheading The @code{-data-list-changed-registers} Command
1263 @findex -data-list-changed-registers
1265 @subsubheading Synopsis
1268 -data-list-changed-registers
1271 Display a list of the registers that have changed.
1273 @subsubheading @value{GDBN} Command
1275 @value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
1276 has the corresponding command @samp{gdb_changed_register_list}.
1278 @subsubheading Example
1288 *stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
1289 args=[],file="try.c",line="5"@}
1291 -data-list-changed-registers
1292 ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
1293 "10","11","13","14","15","16","17","18","19","20","21","22","23",
1294 "24","25","26","27","28","30","31","64","65","66","67","69"]
1299 @subheading The @code{-data-list-register-names} Command
1300 @findex -data-list-register-names
1302 @subsubheading Synopsis
1305 -data-list-register-names [ ( @var{regno} )+ ]
1308 Show a list of register names for the current target. If no arguments
1309 are given, it shows a list of the names of all the registers. If
1310 integer numbers are given as arguments, it will print a list of the
1311 names of the registers corresponding to the arguments. To ensure
1312 consistency between a register name and its number, the output list may
1313 include empty register names.
1315 @subsubheading @value{GDBN} Command
1317 @value{GDBN} does not have a command which corresponds to
1318 @samp{-data-list-register-names}. In @code{gdbtk} there is a
1319 corresponding command @samp{gdb_regnames}.
1321 @subsubheading Example
1323 For the PPC MBX board:
1326 -data-list-register-names
1327 ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
1328 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
1329 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
1330 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
1331 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
1332 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
1333 "", "pc","ps","cr","lr","ctr","xer"]
1335 -data-list-register-names 1 2 3
1336 ^done,register-names=["r1","r2","r3"]
1340 @subheading The @code{-data-list-register-values} Command
1341 @findex -data-list-register-values
1343 @subsubheading Synopsis
1346 -data-list-register-values @var{fmt} [ ( @var{regno} )*]
1349 Display the registers' contents. @var{fmt} is the format according to
1350 which the registers' contents are to be returned, followed by an optional
1351 list of numbers specifying the registers to display. A missing list of
1352 numbers indicates that the contents of all the registers must be returned.
1354 Allowed formats for @var{fmt} are:
1371 @subsubheading @value{GDBN} Command
1373 The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
1374 all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
1376 @subsubheading Example
1378 For a PPC MBX board (note: line breaks are for readability only, they
1379 don't appear in the actual output):
1383 -data-list-register-values r 64 65
1384 ^done,register-values=[@{number="64",value="0xfe00a300"@},
1385 @{number="65",value="0x00029002"@}]
1387 -data-list-register-values x
1388 ^done,register-values=[@{number="0",value="0xfe0043c8"@},
1389 @{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
1390 @{number="3",value="0x0"@},@{number="4",value="0xa"@},
1391 @{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
1392 @{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
1393 @{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
1394 @{number="11",value="0x1"@},@{number="12",value="0x0"@},
1395 @{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
1396 @{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
1397 @{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
1398 @{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
1399 @{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
1400 @{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
1401 @{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
1402 @{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
1403 @{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
1404 @{number="31",value="0x0"@},@{number="32",value="0x0"@},
1405 @{number="33",value="0x0"@},@{number="34",value="0x0"@},
1406 @{number="35",value="0x0"@},@{number="36",value="0x0"@},
1407 @{number="37",value="0x0"@},@{number="38",value="0x0"@},
1408 @{number="39",value="0x0"@},@{number="40",value="0x0"@},
1409 @{number="41",value="0x0"@},@{number="42",value="0x0"@},
1410 @{number="43",value="0x0"@},@{number="44",value="0x0"@},
1411 @{number="45",value="0x0"@},@{number="46",value="0x0"@},
1412 @{number="47",value="0x0"@},@{number="48",value="0x0"@},
1413 @{number="49",value="0x0"@},@{number="50",value="0x0"@},
1414 @{number="51",value="0x0"@},@{number="52",value="0x0"@},
1415 @{number="53",value="0x0"@},@{number="54",value="0x0"@},
1416 @{number="55",value="0x0"@},@{number="56",value="0x0"@},
1417 @{number="57",value="0x0"@},@{number="58",value="0x0"@},
1418 @{number="59",value="0x0"@},@{number="60",value="0x0"@},
1419 @{number="61",value="0x0"@},@{number="62",value="0x0"@},
1420 @{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
1421 @{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
1422 @{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
1423 @{number="69",value="0x20002b03"@}]
1428 @subheading The @code{-data-read-memory} Command
1429 @findex -data-read-memory
1431 @subsubheading Synopsis
1434 -data-read-memory [ -o @var{byte-offset} ]
1435 @var{address} @var{word-format} @var{word-size}
1436 @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
1444 An expression specifying the address of the first memory word to be
1445 read. Complex expressions containing embedded white space should be
1446 quoted using the C convention.
1448 @item @var{word-format}
1449 The format to be used to print the memory words. The notation is the
1450 same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
1453 @item @var{word-size}
1454 The size of each memory word in bytes.
1457 The number of rows in the output table.
1460 The number of columns in the output table.
1463 If present, indicates that each row should include an @sc{ascii} dump. The
1464 value of @var{aschar} is used as a padding character when a byte is not a
1465 member of the printable @sc{ascii} character set (printable @sc{ascii}
1466 characters are those whose code is between 32 and 126, inclusively).
1468 @item @var{byte-offset}
1469 An offset to add to the @var{address} before fetching memory.
1472 This command displays memory contents as a table of @var{nr-rows} by
1473 @var{nr-cols} words, each word being @var{word-size} bytes. In total,
1474 @code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
1475 (returned as @samp{total-bytes}). Should less than the requested number
1476 of bytes be returned by the target, the missing words are identified
1477 using @samp{N/A}. The number of bytes read from the target is returned
1478 in @samp{nr-bytes} and the starting address used to read memory in
1481 The address of the next/previous row or page is available in
1482 @samp{next-row} and @samp{prev-row}, @samp{next-page} and
1485 @subsubheading @value{GDBN} Command
1487 The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
1488 @samp{gdb_get_mem} memory read command.
1490 @subsubheading Example
1492 Read six bytes of memory starting at @code{bytes+6} but then offset by
1493 @code{-6} bytes. Format as three rows of two columns. One byte per
1494 word. Display each word in hex.
1498 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
1499 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
1500 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
1501 prev-page="0x0000138a",memory=[
1502 @{addr="0x00001390",data=["0x00","0x01"]@},
1503 @{addr="0x00001392",data=["0x02","0x03"]@},
1504 @{addr="0x00001394",data=["0x04","0x05"]@}]
1508 Read two bytes of memory starting at address @code{shorts + 64} and
1509 display as a single word formatted in decimal.
1513 5-data-read-memory shorts+64 d 2 1 1
1514 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
1515 next-row="0x00001512",prev-row="0x0000150e",
1516 next-page="0x00001512",prev-page="0x0000150e",memory=[
1517 @{addr="0x00001510",data=["128"]@}]
1521 Read thirty two bytes of memory starting at @code{bytes+16} and format
1522 as eight rows of four columns. Include a string encoding with @samp{x}
1523 used as the non-printable character.
1527 4-data-read-memory bytes+16 x 1 8 4 x
1528 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
1529 next-row="0x000013c0",prev-row="0x0000139c",
1530 next-page="0x000013c0",prev-page="0x00001380",memory=[
1531 @{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@},
1532 @{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@},
1533 @{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@},
1534 @{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@},
1535 @{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@},
1536 @{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@},
1537 @{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@},
1538 @{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}]
1542 @subheading The @code{-display-delete} Command
1543 @findex -display-delete
1545 @subsubheading Synopsis
1548 -display-delete @var{number}
1551 Delete the display @var{number}.
1553 @subsubheading @value{GDBN} Command
1555 The corresponding @value{GDBN} command is @samp{delete display}.
1557 @subsubheading Example
1561 @subheading The @code{-display-disable} Command
1562 @findex -display-disable
1564 @subsubheading Synopsis
1567 -display-disable @var{number}
1570 Disable display @var{number}.
1572 @subsubheading @value{GDBN} Command
1574 The corresponding @value{GDBN} command is @samp{disable display}.
1576 @subsubheading Example
1580 @subheading The @code{-display-enable} Command
1581 @findex -display-enable
1583 @subsubheading Synopsis
1586 -display-enable @var{number}
1589 Enable display @var{number}.
1591 @subsubheading @value{GDBN} Command
1593 The corresponding @value{GDBN} command is @samp{enable display}.
1595 @subsubheading Example
1599 @subheading The @code{-display-insert} Command
1600 @findex -display-insert
1602 @subsubheading Synopsis
1605 -display-insert @var{expression}
1608 Display @var{expression} every time the program stops.
1610 @subsubheading @value{GDBN} Command
1612 The corresponding @value{GDBN} command is @samp{display}.
1614 @subsubheading Example
1618 @subheading The @code{-display-list} Command
1619 @findex -display-list
1621 @subsubheading Synopsis
1627 List the displays. Do not show the current values.
1629 @subsubheading @value{GDBN} Command
1631 The corresponding @value{GDBN} command is @samp{info display}.
1633 @subsubheading Example
1637 @subheading The @code{-environment-cd} Command
1638 @findex -environment-cd
1640 @subsubheading Synopsis
1643 -environment-cd @var{pathdir}
1646 Set @value{GDBN}'s working directory.
1648 @subsubheading @value{GDBN} Command
1650 The corresponding @value{GDBN} command is @samp{cd}.
1652 @subsubheading Example
1656 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1662 @subheading The @code{-environment-directory} Command
1663 @findex -environment-directory
1665 @subsubheading Synopsis
1668 -environment-directory @var{pathdir}
1671 Add directory @var{pathdir} to beginning of search path for source files.
1673 @subsubheading @value{GDBN} Command
1675 The corresponding @value{GDBN} command is @samp{dir}.
1677 @subsubheading Example
1681 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1687 @subheading The @code{-environment-path} Command
1688 @findex -environment-path
1690 @subsubheading Synopsis
1693 -environment-path ( @var{pathdir} )+
1696 Add directories @var{pathdir} to beginning of search path for object files.
1698 @subsubheading @value{GDBN} Command
1700 The corresponding @value{GDBN} command is @samp{path}.
1702 @subsubheading Example
1706 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb
1712 @subheading The @code{-environment-pwd} Command
1713 @findex -environment-pwd
1715 @subsubheading Synopsis
1721 Show the current working directory.
1723 @subsubheading @value{GDBN} command
1725 The corresponding @value{GDBN} command is @samp{pwd}.
1727 @subsubheading Example
1732 ~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb.
1737 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1738 @node GDB/MI Program Control
1739 @section @sc{gdb/mi} Program control
1741 @subsubheading Program termination
1743 As a result of execution, the inferior program can run to completion, if
1744 it doesn't encounter any breakpoints. In this case the output will
1745 include an exit code, if the program has exited exceptionally.
1747 @subsubheading Examples
1750 Program exited normally:
1758 *stopped,reason="exited-normally"
1763 Program exited exceptionally:
1771 *stopped,reason="exited",exit-code="01"
1775 Another way the program can terminate is if it receives a signal such as
1776 @code{SIGINT}. In this case, @sc{gdb/mi} displays this:
1780 *stopped,reason="exited-signalled",signal-name="SIGINT",
1781 signal-meaning="Interrupt"
1785 @subheading The @code{-exec-abort} Command
1788 @subsubheading Synopsis
1794 Kill the inferior running program.
1796 @subsubheading @value{GDBN} Command
1798 The corresponding @value{GDBN} command is @samp{kill}.
1800 @subsubheading Example
1804 @subheading The @code{-exec-arguments} Command
1805 @findex -exec-arguments
1807 @subsubheading Synopsis
1810 -exec-arguments @var{args}
1813 Set the inferior program arguments, to be used in the next
1816 @subsubheading @value{GDBN} Command
1818 The corresponding @value{GDBN} command is @samp{set args}.
1820 @subsubheading Example
1823 Don't have one around.
1826 @subheading The @code{-exec-continue} Command
1827 @findex -exec-continue
1829 @subsubheading Synopsis
1835 Asynchronous command. Resumes the execution of the inferior program
1836 until a breakpoint is encountered, or until the inferior exits.
1838 @subsubheading @value{GDBN} Command
1840 The corresponding @value{GDBN} corresponding is @samp{continue}.
1842 @subsubheading Example
1849 *stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
1850 file="hello.c",line="13"@}
1855 @subheading The @code{-exec-finish} Command
1856 @findex -exec-finish
1858 @subsubheading Synopsis
1864 Asynchronous command. Resumes the execution of the inferior program
1865 until the current function is exited. Displays the results returned by
1868 @subsubheading @value{GDBN} Command
1870 The corresponding @value{GDBN} command is @samp{finish}.
1872 @subsubheading Example
1874 Function returning @code{void}.
1881 *stopped,reason="function-finished",frame=@{func="main",args=[],
1882 file="hello.c",line="7"@}
1886 Function returning other than @code{void}. The name of the internal
1887 @value{GDBN} variable storing the result is printed, together with the
1894 *stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
1895 args=[@{name="a",value="1"],@{name="b",value="9"@}@},
1896 file="recursive2.c",line="14"@},
1897 gdb-result-var="$1",return-value="0"
1902 @subheading The @code{-exec-interrupt} Command
1903 @findex -exec-interrupt
1905 @subsubheading Synopsis
1911 Asynchronous command. Interrupts the background execution of the target.
1912 Note how the token associated with the stop message is the one for the
1913 execution command that has been interrupted. The token for the interrupt
1914 itself only appears in the @samp{^done} output. If the user is trying to
1915 interrupt a non-running program, an error message will be printed.
1917 @subsubheading @value{GDBN} Command
1919 The corresponding @value{GDBN} command is @samp{interrupt}.
1921 @subsubheading Example
1932 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
1933 frame=@{addr="0x00010140",func="foo",args=[],file="try.c",line="13"@}
1938 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
1943 @subheading The @code{-exec-next} Command
1946 @subsubheading Synopsis
1952 Asynchronous command. Resumes execution of the inferior program, stopping
1953 when the beginning of the next source line is reached.
1955 @subsubheading @value{GDBN} Command
1957 The corresponding @value{GDBN} command is @samp{next}.
1959 @subsubheading Example
1965 *stopped,reason="end-stepping-range",line="8",file="hello.c"
1970 @subheading The @code{-exec-next-instruction} Command
1971 @findex -exec-next-instruction
1973 @subsubheading Synopsis
1976 -exec-next-instruction
1979 Asynchronous command. Executes one machine instruction. If the
1980 instruction is a function call continues until the function returns. If
1981 the program stops at an instruction in the middle of a source line, the
1982 address will be printed as well.
1984 @subsubheading @value{GDBN} Command
1986 The corresponding @value{GDBN} command is @samp{nexti}.
1988 @subsubheading Example
1992 -exec-next-instruction
1996 *stopped,reason="end-stepping-range",
1997 addr="0x000100d4",line="5",file="hello.c"
2002 @subheading The @code{-exec-return} Command
2003 @findex -exec-return
2005 @subsubheading Synopsis
2011 Makes current function return immediately. Doesn't execute the inferior.
2012 Displays the new current frame.
2014 @subsubheading @value{GDBN} Command
2016 The corresponding @value{GDBN} command is @samp{return}.
2018 @subsubheading Example
2022 200-break-insert callee4
2023 200^done,bkpt=@{number="1",addr="0x00010734",
2024 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
2029 000*stopped,reason="breakpoint-hit",bkptno="1",
2030 frame=@{func="callee4",args=[],
2031 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
2037 111^done,frame=@{level="0 ",func="callee3",
2038 args=[@{name="strarg",
2039 value="0x11940 \"A string argument.\""@}],
2040 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
2045 @subheading The @code{-exec-run} Command
2048 @subsubheading Synopsis
2054 Asynchronous command. Starts execution of the inferior from the
2055 beginning. The inferior executes until either a breakpoint is
2056 encountered or the program exits.
2058 @subsubheading @value{GDBN} Command
2060 The corresponding @value{GDBN} command is @samp{run}.
2062 @subsubheading Example
2067 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
2072 *stopped,reason="breakpoint-hit",bkptno="1",
2073 frame=@{func="main",args=[],file="recursive2.c",line="4"@}
2078 @subheading The @code{-exec-show-arguments} Command
2079 @findex -exec-show-arguments
2081 @subsubheading Synopsis
2084 -exec-show-arguments
2087 Print the arguments of the program.
2089 @subsubheading @value{GDBN} Command
2091 The corresponding @value{GDBN} command is @samp{show args}.
2093 @subsubheading Example
2096 @c @subheading -exec-signal
2098 @subheading The @code{-exec-step} Command
2101 @subsubheading Synopsis
2107 Asynchronous command. Resumes execution of the inferior program, stopping
2108 when the beginning of the next source line is reached, if the next
2109 source line is not a function call. If it is, stop at the first
2110 instruction of the called function.
2112 @subsubheading @value{GDBN} Command
2114 The corresponding @value{GDBN} command is @samp{step}.
2116 @subsubheading Example
2118 Stepping into a function:
2124 *stopped,reason="end-stepping-range",
2125 frame=@{func="foo",args=[@{name="a",value="10"@},
2126 @{name="b",value="0"@}],file="recursive2.c",line="11"@}
2136 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
2141 @subheading The @code{-exec-step-instruction} Command
2142 @findex -exec-step-instruction
2144 @subsubheading Synopsis
2147 -exec-step-instruction
2150 Asynchronous command. Resumes the inferior which executes one machine
2151 instruction. The output, once @value{GDBN} has stopped, will vary depending on
2152 whether we have stopped in the middle of a source line or not. In the
2153 former case, the address at which the program stopped will be printed as
2156 @subsubheading @value{GDBN} Command
2158 The corresponding @value{GDBN} command is @samp{stepi}.
2160 @subsubheading Example
2164 -exec-step-instruction
2168 *stopped,reason="end-stepping-range",
2169 frame=@{func="foo",args=[],file="try.c",line="10"@}
2171 -exec-step-instruction
2175 *stopped,reason="end-stepping-range",
2176 frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@}
2181 @subheading The @code{-exec-until} Command
2184 @subsubheading Synopsis
2187 -exec-until [ @var{location} ]
2190 Asynchronous command. Executes the inferior until the @var{location}
2191 specified in the argument is reached. If there is no argument, the inferior
2192 executes until a source line greater than the current one is reached.
2193 The reason for stopping in this case will be @samp{location-reached}.
2195 @subsubheading @value{GDBN} Command
2197 The corresponding @value{GDBN} command is @samp{until}.
2199 @subsubheading Example
2203 -exec-until recursive2.c:6
2207 *stopped,reason="location-reached",frame=@{func="main",args=[],
2208 file="recursive2.c",line="6"@}
2213 @subheading -file-clear
2214 Is this going away????
2218 @subheading The @code{-file-exec-and-symbols} Command
2219 @findex -file-exec-and-symbols
2221 @subsubheading Synopsis
2224 -file-exec-and-symbols @var{file}
2227 Specify the executable file to be debugged. This file is the one from
2228 which the symbol table is also read. If no file is specified, the
2229 command clears the executable and symbol information. If breakpoints
2230 are set when using this command with no arguments, @value{GDBN} will produce
2231 error messages. Otherwise, no output is produced, except a completion
2234 @subsubheading @value{GDBN} Command
2236 The corresponding @value{GDBN} command is @samp{file}.
2238 @subsubheading Example
2242 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2248 @subheading The @code{-file-exec-file} Command
2249 @findex -file-exec-file
2251 @subsubheading Synopsis
2254 -file-exec-file @var{file}
2257 Specify the executable file to be debugged. Unlike
2258 @samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
2259 from this file. If used without argument, @value{GDBN} clears the information
2260 about the executable file. No output is produced, except a completion
2263 @subsubheading @value{GDBN} Command
2265 The corresponding @value{GDBN} command is @samp{exec-file}.
2267 @subsubheading Example
2271 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2277 @subheading The @code{-file-list-exec-sections} Command
2278 @findex -file-list-exec-sections
2280 @subsubheading Synopsis
2283 -file-list-exec-sections
2286 List the sections of the current executable file.
2288 @subsubheading @value{GDBN} Command
2290 The @value{GDBN} command @samp{info file} shows, among the rest, the same
2291 information as this command. @code{gdbtk} has a corresponding command
2292 @samp{gdb_load_info}.
2294 @subsubheading Example
2298 @subheading The @code{-file-list-exec-source-files} Command
2299 @findex -file-list-exec-source-files
2301 @subsubheading Synopsis
2304 -file-list-exec-source-files
2307 List the source files for the current executable.
2309 @subsubheading @value{GDBN} Command
2311 There's no @value{GDBN} command which directly corresponds to this one.
2312 @code{gdbtk} has an analogous command @samp{gdb_listfiles}.
2314 @subsubheading Example
2318 @subheading The @code{-file-list-shared-libraries} Command
2319 @findex -file-list-shared-libraries
2321 @subsubheading Synopsis
2324 -file-list-shared-libraries
2327 List the shared libraries in the program.
2329 @subsubheading @value{GDBN} Command
2331 The corresponding @value{GDBN} command is @samp{info shared}.
2333 @subsubheading Example
2337 @subheading The @code{-file-list-symbol-files} Command
2338 @findex -file-list-symbol-files
2340 @subsubheading Synopsis
2343 -file-list-symbol-files
2348 @subsubheading @value{GDBN} Command
2350 The corresponding @value{GDBN} command is @samp{info file} (part of it).
2352 @subsubheading Example
2356 @subheading The @code{-file-symbol-file} Command
2357 @findex -file-symbol-file
2359 @subsubheading Synopsis
2362 -file-symbol-file @var{file}
2365 Read symbol table info from the specified @var{file} argument. When
2366 used without arguments, clears @value{GDBN}'s symbol table info. No output is
2367 produced, except for a completion notification.
2369 @subsubheading @value{GDBN} Command
2371 The corresponding @value{GDBN} command is @samp{symbol-file}.
2373 @subsubheading Example
2377 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2382 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2383 @node GDB/MI Miscellaneous Commands
2384 @section Miscellaneous @value{GDBN} commands in @sc{gdb/mi}
2386 @c @subheading -gdb-complete
2388 @subheading The @code{-gdb-exit} Command
2391 @subsubheading Synopsis
2397 Exit @value{GDBN} immediately.
2399 @subsubheading @value{GDBN} Command
2401 Approximately corresponds to @samp{quit}.
2403 @subsubheading Example
2410 @subheading The @code{-gdb-set} Command
2413 @subsubheading Synopsis
2419 Set an internal @value{GDBN} variable.
2420 @c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
2422 @subsubheading @value{GDBN} Command
2424 The corresponding @value{GDBN} command is @samp{set}.
2426 @subsubheading Example
2436 @subheading The @code{-gdb-show} Command
2439 @subsubheading Synopsis
2445 Show the current value of a @value{GDBN} variable.
2447 @subsubheading @value{GDBN} command
2449 The corresponding @value{GDBN} command is @samp{show}.
2451 @subsubheading Example
2460 @c @subheading -gdb-source
2463 @subheading The @code{-gdb-version} Command
2464 @findex -gdb-version
2466 @subsubheading Synopsis
2472 Show version information for @value{GDBN}. Used mostly in testing.
2474 @subsubheading @value{GDBN} Command
2476 There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this
2477 information when you start an interactive session.
2479 @subsubheading Example
2481 @c This example modifies the actual output from GDB to avoid overfull
2487 ~Copyright 2000 Free Software Foundation, Inc.
2488 ~GDB is free software, covered by the GNU General Public License, and
2489 ~you are welcome to change it and/or distribute copies of it under
2490 ~ certain conditions.
2491 ~Type "show copying" to see the conditions.
2492 ~There is absolutely no warranty for GDB. Type "show warranty" for
2494 ~This GDB was configured as
2495 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
2501 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2502 @node GDB/MI Kod Commands
2503 @section @sc{gdb/mi} Kod Commands
2505 The Kod commands are not implemented.
2507 @c @subheading -kod-info
2509 @c @subheading -kod-list
2511 @c @subheading -kod-list-object-types
2513 @c @subheading -kod-show
2515 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2516 @node GDB/MI Memory Overlay Commands
2517 @section @sc{gdb/mi} Memory Overlay Commands
2519 The memory overlay commands are not implemented.
2521 @c @subheading -overlay-auto
2523 @c @subheading -overlay-list-mapping-state
2525 @c @subheading -overlay-list-overlays
2527 @c @subheading -overlay-map
2529 @c @subheading -overlay-off
2531 @c @subheading -overlay-on
2533 @c @subheading -overlay-unmap
2535 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2536 @node GDB/MI Signal Handling Commands
2537 @section @sc{gdb/mi} Signal Handling Commands
2539 Signal handling commands are not implemented.
2541 @c @subheading -signal-handle
2543 @c @subheading -signal-list-handle-actions
2545 @c @subheading -signal-list-signal-types
2549 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2550 @node GDB/MI Stack Manipulation
2551 @section @sc{gdb/mi} Stack Manipulation Commands
2554 @subheading The @code{-stack-info-frame} Command
2555 @findex -stack-info-frame
2557 @subsubheading Synopsis
2563 Get info on the current frame.
2565 @subsubheading @value{GDBN} Command
2567 The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
2568 (without arguments).
2570 @subsubheading Example
2573 @subheading The @code{-stack-info-depth} Command
2574 @findex -stack-info-depth
2576 @subsubheading Synopsis
2579 -stack-info-depth [ @var{max-depth} ]
2582 Return the depth of the stack. If the integer argument @var{max-depth}
2583 is specified, do not count beyond @var{max-depth} frames.
2585 @subsubheading @value{GDBN} Command
2587 There's no equivalent @value{GDBN} command.
2589 @subsubheading Example
2591 For a stack with frame levels 0 through 11:
2601 -stack-info-depth 12
2604 -stack-info-depth 11
2607 -stack-info-depth 13
2612 @subheading The @code{-stack-list-arguments} Command
2613 @findex -stack-list-arguments
2615 @subsubheading Synopsis
2618 -stack-list-arguments @var{show-values}
2619 [ @var{low-frame} @var{high-frame} ]
2622 Display a list of the arguments for the frames between @var{low-frame}
2623 and @var{high-frame} (inclusive). If @var{low-frame} and
2624 @var{high-frame} are not provided, list the arguments for the whole call
2627 The @var{show-values} argument must have a value of 0 or 1. A value of
2628 0 means that only the names of the arguments are listed, a value of 1
2629 means that both names and values of the arguments are printed.
2631 @subsubheading @value{GDBN} Command
2633 @value{GDBN} does not have an equivalent command. @code{gdbtk} has a
2634 @samp{gdb_get_args} command which partially overlaps with the
2635 functionality of @samp{-stack-list-arguments}.
2637 @subsubheading Example
2644 frame=@{level="0 ",addr="0x00010734",func="callee4",
2645 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
2646 frame=@{level="1 ",addr="0x0001076c",func="callee3",
2647 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
2648 frame=@{level="2 ",addr="0x0001078c",func="callee2",
2649 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
2650 frame=@{level="3 ",addr="0x000107b4",func="callee1",
2651 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
2652 frame=@{level="4 ",addr="0x000107e0",func="main",
2653 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
2655 -stack-list-arguments 0
2658 frame=@{level="0",args=[]@},
2659 frame=@{level="1",args=[name="strarg"]@},
2660 frame=@{level="2",args=[name="intarg",name="strarg"]@},
2661 frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@},
2662 frame=@{level="4",args=[]@}]
2664 -stack-list-arguments 1
2667 frame=@{level="0",args=[]@},
2669 args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
2670 frame=@{level="2",args=[
2671 @{name="intarg",value="2"@},
2672 @{name="strarg",value="0x11940 \"A string argument.\""@}]@},
2673 @{frame=@{level="3",args=[
2674 @{name="intarg",value="2"@},
2675 @{name="strarg",value="0x11940 \"A string argument.\""@},
2676 @{name="fltarg",value="3.5"@}]@},
2677 frame=@{level="4",args=[]@}]
2679 -stack-list-arguments 0 2 2
2680 ^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}]
2682 -stack-list-arguments 1 2 2
2683 ^done,stack-args=[frame=@{level="2",
2684 args=[@{name="intarg",value="2"@},
2685 @{name="strarg",value="0x11940 \"A string argument.\""@}]@}]
2689 @c @subheading -stack-list-exception-handlers
2692 @subheading The @code{-stack-list-frames} Command
2693 @findex -stack-list-frames
2695 @subsubheading Synopsis
2698 -stack-list-frames [ @var{low-frame} @var{high-frame} ]
2701 List the frames currently on the stack. For each frame it displays the
2706 The frame number, 0 being the topmost frame, i.e. the innermost function.
2708 The @code{$pc} value for that frame.
2712 File name of the source file where the function lives.
2714 Line number corresponding to the @code{$pc}.
2717 If invoked without arguments, this command prints a backtrace for the
2718 whole stack. If given two integer arguments, it shows the frames whose
2719 levels are between the two arguments (inclusive). If the two arguments
2720 are equal, it shows the single frame at the corresponding level.
2722 @subsubheading @value{GDBN} Command
2724 The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
2726 @subsubheading Example
2728 Full stack backtrace:
2734 [frame=@{level="0 ",addr="0x0001076c",func="foo",
2735 file="recursive2.c",line="11"@},
2736 frame=@{level="1 ",addr="0x000107a4",func="foo",
2737 file="recursive2.c",line="14"@},
2738 frame=@{level="2 ",addr="0x000107a4",func="foo",
2739 file="recursive2.c",line="14"@},
2740 frame=@{level="3 ",addr="0x000107a4",func="foo",
2741 file="recursive2.c",line="14"@},
2742 frame=@{level="4 ",addr="0x000107a4",func="foo",
2743 file="recursive2.c",line="14"@},
2744 frame=@{level="5 ",addr="0x000107a4",func="foo",
2745 file="recursive2.c",line="14"@},
2746 frame=@{level="6 ",addr="0x000107a4",func="foo",
2747 file="recursive2.c",line="14"@},
2748 frame=@{level="7 ",addr="0x000107a4",func="foo",
2749 file="recursive2.c",line="14"@},
2750 frame=@{level="8 ",addr="0x000107a4",func="foo",
2751 file="recursive2.c",line="14"@},
2752 frame=@{level="9 ",addr="0x000107a4",func="foo",
2753 file="recursive2.c",line="14"@},
2754 frame=@{level="10",addr="0x000107a4",func="foo",
2755 file="recursive2.c",line="14"@},
2756 frame=@{level="11",addr="0x00010738",func="main",
2757 file="recursive2.c",line="4"@}]
2761 Show frames between @var{low_frame} and @var{high_frame}:
2765 -stack-list-frames 3 5
2767 [frame=@{level="3 ",addr="0x000107a4",func="foo",
2768 file="recursive2.c",line="14"@},
2769 frame=@{level="4 ",addr="0x000107a4",func="foo",
2770 file="recursive2.c",line="14"@},
2771 frame=@{level="5 ",addr="0x000107a4",func="foo",
2772 file="recursive2.c",line="14"@}]
2776 Show a single frame:
2780 -stack-list-frames 3 3
2782 [frame=@{level="3 ",addr="0x000107a4",func="foo",
2783 file="recursive2.c",line="14"@}]
2788 @subheading The @code{-stack-list-locals} Command
2789 @findex -stack-list-locals
2791 @subsubheading Synopsis
2794 -stack-list-locals @var{print-values}
2797 Display the local variable names for the current frame. With an
2798 argument of 0 prints only the names of the variables, with argument of 1
2799 prints also their values.
2801 @subsubheading @value{GDBN} Command
2803 @samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
2805 @subsubheading Example
2809 -stack-list-locals 0
2810 ^done,locals=[name="A",name="B",name="C"]
2812 -stack-list-locals 1
2813 ^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
2814 @{name="C",value="3"@}]
2819 @subheading The @code{-stack-select-frame} Command
2820 @findex -stack-select-frame
2822 @subsubheading Synopsis
2825 -stack-select-frame @var{framenum}
2828 Change the current frame. Select a different frame @var{framenum} on
2831 @subsubheading @value{GDBN} Command
2833 The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
2834 @samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
2836 @subsubheading Example
2840 -stack-select-frame 2
2845 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2846 @node GDB/MI Symbol Query
2847 @section @sc{gdb/mi} Symbol Query Commands
2850 @subheading The @code{-symbol-info-address} Command
2851 @findex -symbol-info-address
2853 @subsubheading Synopsis
2856 -symbol-info-address @var{symbol}
2859 Describe where @var{symbol} is stored.
2861 @subsubheading @value{GDBN} Command
2863 The corresponding @value{GDBN} command is @samp{info address}.
2865 @subsubheading Example
2869 @subheading The @code{-symbol-info-file} Command
2870 @findex -symbol-info-file
2872 @subsubheading Synopsis
2878 Show the file for the symbol.
2880 @subsubheading @value{GDBN} Command
2882 There's no equivalent @value{GDBN} command. @code{gdbtk} has
2883 @samp{gdb_find_file}.
2885 @subsubheading Example
2889 @subheading The @code{-symbol-info-function} Command
2890 @findex -symbol-info-function
2892 @subsubheading Synopsis
2895 -symbol-info-function
2898 Show which function the symbol lives in.
2900 @subsubheading @value{GDBN} Command
2902 @samp{gdb_get_function} in @code{gdbtk}.
2904 @subsubheading Example
2908 @subheading The @code{-symbol-info-line} Command
2909 @findex -symbol-info-line
2911 @subsubheading Synopsis
2917 Show the core addresses of the code for a source line.
2919 @subsubheading @value{GDBN} Command
2921 The corresponding @value{GDBN} comamnd is @samp{info line}.
2922 @code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
2924 @subsubheading Example
2928 @subheading The @code{-symbol-info-symbol} Command
2929 @findex -symbol-info-symbol
2931 @subsubheading Synopsis
2934 -symbol-info-symbol @var{addr}
2937 Describe what symbol is at location @var{addr}.
2939 @subsubheading @value{GDBN} Command
2941 The corresponding @value{GDBN} command is @samp{info symbol}.
2943 @subsubheading Example
2947 @subheading The @code{-symbol-list-functions} Command
2948 @findex -symbol-list-functions
2950 @subsubheading Synopsis
2953 -symbol-list-functions
2956 List the functions in the executable.
2958 @subsubheading @value{GDBN} Command
2960 @samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
2961 @samp{gdb_search} in @code{gdbtk}.
2963 @subsubheading Example
2967 @subheading The @code{-symbol-list-types} Command
2968 @findex -symbol-list-types
2970 @subsubheading Synopsis
2976 List all the type names.
2978 @subsubheading @value{GDBN} Command
2980 The corresponding commands are @samp{info types} in @value{GDBN},
2981 @samp{gdb_search} in @code{gdbtk}.
2983 @subsubheading Example
2987 @subheading The @code{-symbol-list-variables} Command
2988 @findex -symbol-list-variables
2990 @subsubheading Synopsis
2993 -symbol-list-variables
2996 List all the global and static variable names.
2998 @subsubheading @value{GDBN} Command
3000 @samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
3002 @subsubheading Example
3006 @subheading The @code{-symbol-locate} Command
3007 @findex -symbol-locate
3009 @subsubheading Synopsis
3015 @subsubheading @value{GDBN} Command
3017 @samp{gdb_loc} in @code{gdbtk}.
3019 @subsubheading Example
3023 @subheading The @code{-symbol-type} Command
3024 @findex -symbol-type
3026 @subsubheading Synopsis
3029 -symbol-type @var{variable}
3032 Show type of @var{variable}.
3034 @subsubheading @value{GDBN} Command
3036 The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
3037 @samp{gdb_obj_variable}.
3039 @subsubheading Example
3043 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3044 @node GDB/MI Target Manipulation
3045 @section @sc{gdb/mi} Target Manipulation Commands
3048 @subheading The @code{-target-attach} Command
3049 @findex -target-attach
3051 @subsubheading Synopsis
3054 -target-attach @var{pid} | @var{file}
3057 Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
3059 @subsubheading @value{GDBN} command
3061 The corresponding @value{GDBN} command is @samp{attach}.
3063 @subsubheading Example
3067 @subheading The @code{-target-compare-sections} Command
3068 @findex -target-compare-sections
3070 @subsubheading Synopsis
3073 -target-compare-sections [ @var{section} ]
3076 Compare data of section @var{section} on target to the exec file.
3077 Without the argument, all sections are compared.
3079 @subsubheading @value{GDBN} Command
3081 The @value{GDBN} equivalent is @samp{compare-sections}.
3083 @subsubheading Example
3087 @subheading The @code{-target-detach} Command
3088 @findex -target-detach
3090 @subsubheading Synopsis
3096 Disconnect from the remote target. There's no output.
3098 @subsubheading @value{GDBN} command
3100 The corresponding @value{GDBN} command is @samp{detach}.
3102 @subsubheading Example
3112 @subheading The @code{-target-download} Command
3113 @findex -target-download
3115 @subsubheading Synopsis
3121 Loads the executable onto the remote target.
3122 It prints out an update message every half second, which includes the fields:
3126 The name of the section.
3128 The size of what has been sent so far for that section.
3130 The size of the section.
3132 The total size of what was sent so far (the current and the previous sections).
3134 The size of the overall executable to download.
3138 Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
3139 @sc{gdb/mi} Output Syntax}).
3141 In addition, it prints the name and size of the sections, as they are
3142 downloaded. These messages include the following fields:
3146 The name of the section.
3148 The size of the section.
3150 The size of the overall executable to download.
3154 At the end, a summary is printed.
3156 @subsubheading @value{GDBN} Command
3158 The corresponding @value{GDBN} command is @samp{load}.
3160 @subsubheading Example
3162 Note: each status message appears on a single line. Here the messages
3163 have been broken down so that they can fit onto a page.
3168 +download,@{section=".text",section-size="6668",total-size="9880"@}
3169 +download,@{section=".text",section-sent="512",section-size="6668",
3170 total-sent="512",total-size="9880"@}
3171 +download,@{section=".text",section-sent="1024",section-size="6668",
3172 total-sent="1024",total-size="9880"@}
3173 +download,@{section=".text",section-sent="1536",section-size="6668",
3174 total-sent="1536",total-size="9880"@}
3175 +download,@{section=".text",section-sent="2048",section-size="6668",
3176 total-sent="2048",total-size="9880"@}
3177 +download,@{section=".text",section-sent="2560",section-size="6668",
3178 total-sent="2560",total-size="9880"@}
3179 +download,@{section=".text",section-sent="3072",section-size="6668",
3180 total-sent="3072",total-size="9880"@}
3181 +download,@{section=".text",section-sent="3584",section-size="6668",
3182 total-sent="3584",total-size="9880"@}
3183 +download,@{section=".text",section-sent="4096",section-size="6668",
3184 total-sent="4096",total-size="9880"@}
3185 +download,@{section=".text",section-sent="4608",section-size="6668",
3186 total-sent="4608",total-size="9880"@}
3187 +download,@{section=".text",section-sent="5120",section-size="6668",
3188 total-sent="5120",total-size="9880"@}
3189 +download,@{section=".text",section-sent="5632",section-size="6668",
3190 total-sent="5632",total-size="9880"@}
3191 +download,@{section=".text",section-sent="6144",section-size="6668",
3192 total-sent="6144",total-size="9880"@}
3193 +download,@{section=".text",section-sent="6656",section-size="6668",
3194 total-sent="6656",total-size="9880"@}
3195 +download,@{section=".init",section-size="28",total-size="9880"@}
3196 +download,@{section=".fini",section-size="28",total-size="9880"@}
3197 +download,@{section=".data",section-size="3156",total-size="9880"@}
3198 +download,@{section=".data",section-sent="512",section-size="3156",
3199 total-sent="7236",total-size="9880"@}
3200 +download,@{section=".data",section-sent="1024",section-size="3156",
3201 total-sent="7748",total-size="9880"@}
3202 +download,@{section=".data",section-sent="1536",section-size="3156",
3203 total-sent="8260",total-size="9880"@}
3204 +download,@{section=".data",section-sent="2048",section-size="3156",
3205 total-sent="8772",total-size="9880"@}
3206 +download,@{section=".data",section-sent="2560",section-size="3156",
3207 total-sent="9284",total-size="9880"@}
3208 +download,@{section=".data",section-sent="3072",section-size="3156",
3209 total-sent="9796",total-size="9880"@}
3210 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
3216 @subheading The @code{-target-exec-status} Command
3217 @findex -target-exec-status
3219 @subsubheading Synopsis
3225 Provide information on the state of the target (whether it is running or
3228 @subsubheading @value{GDBN} Command
3230 There's no equivalent @value{GDBN} command.
3232 @subsubheading Example
3236 @subheading The @code{-target-list-available-targets} Command
3237 @findex -target-list-available-targets
3239 @subsubheading Synopsis
3242 -target-list-available-targets
3245 List the possible targets to connect to.
3247 @subsubheading @value{GDBN} Command
3249 The corresponding @value{GDBN} command is @samp{help target}.
3251 @subsubheading Example
3255 @subheading The @code{-target-list-current-targets} Command
3256 @findex -target-list-current-targets
3258 @subsubheading Synopsis
3261 -target-list-current-targets
3264 Describe the current target.
3266 @subsubheading @value{GDBN} Command
3268 The corresponding information is printed by @samp{info file} (among
3271 @subsubheading Example
3275 @subheading The @code{-target-list-parameters} Command
3276 @findex -target-list-parameters
3278 @subsubheading Synopsis
3281 -target-list-parameters
3286 @subsubheading @value{GDBN} Command
3290 @subsubheading Example
3294 @subheading The @code{-target-select} Command
3295 @findex -target-select
3297 @subsubheading Synopsis
3300 -target-select @var{type} @var{parameters @dots{}}
3303 Connect @value{GDBN} to the remote target. This command takes two args:
3307 The type of target, for instance @samp{async}, @samp{remote}, etc.
3308 @item @var{parameters}
3309 Device names, host names and the like. @xref{Target Commands, ,
3310 Commands for managing targets}, for more details.
3313 The output is a connection notification, followed by the address at
3314 which the target program is, in the following form:
3317 ^connected,addr="@var{address}",func="@var{function name}",
3318 args=[@var{arg list}]
3321 @subsubheading @value{GDBN} Command
3323 The corresponding @value{GDBN} command is @samp{target}.
3325 @subsubheading Example
3329 -target-select async /dev/ttya
3330 ^connected,addr="0xfe00a300",func="??",args=[]
3334 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3335 @node GDB/MI Thread Commands
3336 @section @sc{gdb/mi} Thread Commands
3339 @subheading The @code{-thread-info} Command
3340 @findex -thread-info
3342 @subsubheading Synopsis
3348 @subsubheading @value{GDBN} command
3352 @subsubheading Example
3356 @subheading The @code{-thread-list-all-threads} Command
3357 @findex -thread-list-all-threads
3359 @subsubheading Synopsis
3362 -thread-list-all-threads
3365 @subsubheading @value{GDBN} Command
3367 The equivalent @value{GDBN} command is @samp{info threads}.
3369 @subsubheading Example
3373 @subheading The @code{-thread-list-ids} Command
3374 @findex -thread-list-ids
3376 @subsubheading Synopsis
3382 Produces a list of the currently known @value{GDBN} thread ids. At the
3383 end of the list it also prints the total number of such threads.
3385 @subsubheading @value{GDBN} Command
3387 Part of @samp{info threads} supplies the same information.
3389 @subsubheading Example
3391 No threads present, besides the main process:
3396 ^done,thread-ids=@{@},number-of-threads="0"
3406 ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3407 number-of-threads="3"
3412 @subheading The @code{-thread-select} Command
3413 @findex -thread-select
3415 @subsubheading Synopsis
3418 -thread-select @var{threadnum}
3421 Make @var{threadnum} the current thread. It prints the number of the new
3422 current thread, and the topmost frame for that thread.
3424 @subsubheading @value{GDBN} Command
3426 The corresponding @value{GDBN} command is @samp{thread}.
3428 @subsubheading Example
3435 *stopped,reason="end-stepping-range",thread-id="2",line="187",
3436 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
3440 thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3441 number-of-threads="3"
3444 ^done,new-thread-id="3",
3445 frame=@{level="0 ",func="vprintf",
3446 args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
3447 @{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
3451 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3452 @node GDB/MI Tracepoint Commands
3453 @section @sc{gdb/mi} Tracepoint Commands
3455 The tracepoint commands are not yet implemented.
3457 @c @subheading -trace-actions
3459 @c @subheading -trace-delete
3461 @c @subheading -trace-disable
3463 @c @subheading -trace-dump
3465 @c @subheading -trace-enable
3467 @c @subheading -trace-exists
3469 @c @subheading -trace-find
3471 @c @subheading -trace-frame-number
3473 @c @subheading -trace-info
3475 @c @subheading -trace-insert
3477 @c @subheading -trace-list
3479 @c @subheading -trace-pass-count
3481 @c @subheading -trace-save
3483 @c @subheading -trace-start
3485 @c @subheading -trace-stop
3488 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3489 @node GDB/MI Variable Objects
3490 @section @sc{gdb/mi} Variable Objects
3493 @subheading Motivation for Variable Objects in @sc{gdb/mi}
3495 For the implementation of a variable debugger window (locals, watched
3496 expressions, etc.), we are proposing the adaptation of the existing code
3497 used by @code{Insight}.
3499 The two main reasons for that are:
3503 It has been proven in practice (it is already on its second generation).
3506 It will shorten development time (needless to say how important it is
3510 The original interface was designed to be used by Tcl code, so it was
3511 slightly changed so it could be used through @sc{gdb/mi}. This section
3512 describes the @sc{gdb/mi} operations that will be available and gives some
3513 hints about their use.
3515 @emph{Note}: In addition to the set of operations described here, we
3516 expect the @sc{gui} implementation of a variable window to require, at
3517 least, the following operations:
3520 @item @code{-gdb-show} @code{output-radix}
3521 @item @code{-stack-list-arguments}
3522 @item @code{-stack-list-locals}
3523 @item @code{-stack-select-frame}
3526 @subheading Introduction to Variable Objects in @sc{gdb/mi}
3528 @cindex variable objects in @sc{gdb/mi}
3529 The basic idea behind variable objects is the creation of a named object
3530 to represent a variable, an expression, a memory location or even a CPU
3531 register. For each object created, a set of operations is available for
3532 examining or changing its properties.
3534 Furthermore, complex data types, such as C structures, are represented
3535 in a tree format. For instance, the @code{struct} type variable is the
3536 root and the children will represent the struct members. If a child
3537 is itself of a complex type, it will also have children of its own.
3538 Appropriate language differences are handled for C, C@t{++} and Java.
3540 When returning the actual values of the objects, this facility allows
3541 for the individual selection of the display format used in the result
3542 creation. It can be chosen among: binary, decimal, hexadecimal, octal
3543 and natural. Natural refers to a default format automatically
3544 chosen based on the variable type (like decimal for an @code{int}, hex
3545 for pointers, etc.).
3547 The following is the complete set of @sc{gdb/mi} operations defined to
3548 access this functionality:
3550 @multitable @columnfractions .4 .6
3551 @item @strong{Operation}
3552 @tab @strong{Description}
3554 @item @code{-var-create}
3555 @tab create a variable object
3556 @item @code{-var-delete}
3557 @tab delete the variable object and its children
3558 @item @code{-var-set-format}
3559 @tab set the display format of this variable
3560 @item @code{-var-show-format}
3561 @tab show the display format of this variable
3562 @item @code{-var-info-num-children}
3563 @tab tells how many children this object has
3564 @item @code{-var-list-children}
3565 @tab return a list of the object's children
3566 @item @code{-var-info-type}
3567 @tab show the type of this variable object
3568 @item @code{-var-info-expression}
3569 @tab print what this variable object represents
3570 @item @code{-var-show-attributes}
3571 @tab is this variable editable? does it exist here?
3572 @item @code{-var-evaluate-expression}
3573 @tab get the value of this variable
3574 @item @code{-var-assign}
3575 @tab set the value of this variable
3576 @item @code{-var-update}
3577 @tab update the variable and its children
3580 In the next subsection we describe each operation in detail and suggest
3583 @subheading Description And Use of Operations on Variable Objects
3585 @subheading The @code{-var-create} Command
3588 @subsubheading Synopsis
3591 -var-create @{@var{name} | "-"@}
3592 @{@var{frame-addr} | "*"@} @var{expression}
3595 This operation creates a variable object, which allows the monitoring of
3596 a variable, the result of an expression, a memory cell or a CPU
3599 The @var{name} parameter is the string by which the object can be
3600 referenced. It must be unique. If @samp{-} is specified, the varobj
3601 system will generate a string ``varNNNNNN'' automatically. It will be
3602 unique provided that one does not specify @var{name} on that format.
3603 The command fails if a duplicate name is found.
3605 The frame under which the expression should be evaluated can be
3606 specified by @var{frame-addr}. A @samp{*} indicates that the current
3607 frame should be used.
3609 @var{expression} is any expression valid on the current language set (must not
3610 begin with a @samp{*}), or one of the following:
3614 @samp{*@var{addr}}, where @var{addr} is the address of a memory cell
3617 @samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
3620 @samp{$@var{regname}} --- a CPU register name
3623 @subsubheading Result
3625 This operation returns the name, number of children and the type of the
3626 object created. Type is returned as a string as the ones generated by
3627 the @value{GDBN} CLI:
3630 name="@var{name}",numchild="N",type="@var{type}"
3634 @subheading The @code{-var-delete} Command
3637 @subsubheading Synopsis
3640 -var-delete @var{name}
3643 Deletes a previously created variable object and all of its children.
3645 Returns an error if the object @var{name} is not found.
3648 @subheading The @code{-var-set-format} Command
3649 @findex -var-set-format
3651 @subsubheading Synopsis
3654 -var-set-format @var{name} @var{format-spec}
3657 Sets the output format for the value of the object @var{name} to be
3660 The syntax for the @var{format-spec} is as follows:
3663 @var{format-spec} @expansion{}
3664 @{binary | decimal | hexadecimal | octal | natural@}
3668 @subheading The @code{-var-show-format} Command
3669 @findex -var-show-format
3671 @subsubheading Synopsis
3674 -var-show-format @var{name}
3677 Returns the format used to display the value of the object @var{name}.
3680 @var{format} @expansion{}
3685 @subheading The @code{-var-info-num-children} Command
3686 @findex -var-info-num-children
3688 @subsubheading Synopsis
3691 -var-info-num-children @var{name}
3694 Returns the number of children of a variable object @var{name}:
3701 @subheading The @code{-var-list-children} Command
3702 @findex -var-list-children
3704 @subsubheading Synopsis
3707 -var-list-children @var{name}
3710 Returns a list of the children of the specified variable object:
3713 numchild=@var{n},children=@{@{name=@var{name},
3714 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}@}
3718 @subheading The @code{-var-info-type} Command
3719 @findex -var-info-type
3721 @subsubheading Synopsis
3724 -var-info-type @var{name}
3727 Returns the type of the specified variable @var{name}. The type is
3728 returned as a string in the same format as it is output by the
3736 @subheading The @code{-var-info-expression} Command
3737 @findex -var-info-expression
3739 @subsubheading Synopsis
3742 -var-info-expression @var{name}
3745 Returns what is represented by the variable object @var{name}:
3748 lang=@var{lang-spec},exp=@var{expression}
3752 where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
3754 @subheading The @code{-var-show-attributes} Command
3755 @findex -var-show-attributes
3757 @subsubheading Synopsis
3760 -var-show-attributes @var{name}
3763 List attributes of the specified variable object @var{name}:
3766 status=@var{attr} [ ( ,@var{attr} )* ]
3770 where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
3772 @subheading The @code{-var-evaluate-expression} Command
3773 @findex -var-evaluate-expression
3775 @subsubheading Synopsis
3778 -var-evaluate-expression @var{name}
3781 Evaluates the expression that is represented by the specified variable
3782 object and returns its value as a string in the current format specified
3789 @subheading The @code{-var-assign} Command
3792 @subsubheading Synopsis
3795 -var-assign @var{name} @var{expression}
3798 Assigns the value of @var{expression} to the variable object specified
3799 by @var{name}. The object must be @samp{editable}.
3801 @subheading The @code{-var-update} Command
3804 @subsubheading Synopsis
3807 -var-update @{@var{name} | "*"@}
3810 Update the value of the variable object @var{name} by evaluating its
3811 expression after fetching all the new values from memory or registers.
3812 A @samp{*} causes all existing variable objects to be updated.