1 @c \input texinfo @c -*-texinfo-*-
2 @c @c %**start of header
3 @c @setfilename gdbmi.info
4 @c @settitle GDB/MI Machine Interface
5 @c @setchapternewpage off
9 @c This file documents GDB/MI, a Machine Interface to GDB.
11 @c Copyright 2000, 2001 Free Software Foundation, Inc.
12 @c Contributed by Cygnus Solutions.
14 @c Permission is granted to copy, distribute and/or modify this document
15 @c under the terms of the GNU Free Documentation License, Version 1.1 or
16 @c any later version published by the Free Software Foundation; with the
17 @c Invariant Sections being ``The GDB/MI Interface'' and ``GGDB/MI
18 @c Command Syntax'', with the Front-Cover texts being ``A GNU Manual,''
19 @c and with the Back-Cover Texts as in (a) below.
21 @c (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
22 @c this GNU Manual, like GNU software. Copies published by the Free
23 @c Software Foundation raise funds for GNU development.''
26 @c @c This title page illustrates only one of the
27 @c @c two methods of forming a title page.
31 @c @subtitle Version 0.3
33 @c @author Andrew Cagney, Fernando Nasser and Elena Zannoni
35 @c @c The following two commands
36 @c @c start the copyright page.
38 @c @vskip 0pt plus 1filll
40 @c Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.
42 @c Permission is granted to copy, distribute and/or modify this document
43 @c under the terms of the GNU Free Documentation License, Version 1.1 or
44 @c any later version published by the Free Software Foundation; with the
45 @c Invariant Sections being ``The GDB/MI Interface'' and ``GGDB/MI
46 @c Command Syntax'', with the Front-Cover texts being ``A GNU Manual,''
47 @c and with the Back-Cover Texts as in (a) below.
49 @c (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
50 @c this GNU Manual, like GNU software. Copies published by the Free
51 @c Software Foundation raise funds for GNU development.''
54 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
56 @chapter The @sc{gdb/mi} Interface
58 @unnumberedsec Function and Purpose
60 @cindex @sc{gdb/mi}, its purpose
61 @sc{gdb/mi} is a line based machine oriented text interface to @value{GDBN}. It is
62 specifically intended to support the development of systems which use
63 the debugger as just one small component of a larger system.
65 This chapter is a specification of the @sc{gdb/mi} interface. It is written
66 in the form of a reference manual.
68 Note that @sc{gdb/mi} is still under construction, so some of the
69 features described below are incomplete and subject to change.
71 @unnumberedsec Notation and Terminology
73 @cindex notational conventions, for @sc{gdb/mi}
74 This chapter uses the following notation:
78 @code{|} separates two alternatives.
81 @code{[ @var{something} ]} indicates that @var{something} is optional:
82 it may or may not be given.
85 @code{( @var{group} )*} means that @var{group} inside the parentheses
86 may repeat zero or more times.
89 @code{( @var{group} )+} means that @var{group} inside the parentheses
90 may repeat one or more times.
93 @code{"@var{string}"} means a literal @var{string}.
100 @heading Acknowledgments
102 In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
106 * GDB/MI Command Syntax::
107 * GDB/MI Compatibility with CLI::
108 * GDB/MI Output Records::
109 * GDB/MI Command Description Format::
110 * GDB/MI Breakpoint Table Commands::
111 * GDB/MI Data Manipulation::
112 * GDB/MI Program Control::
113 * GDB/MI Miscellaneous Commands::
114 * GDB/MI Stack Manipulation::
115 * GDB/MI Symbol Query::
116 * GDB/MI Target Manipulation::
117 * GDB/MI Thread Commands::
118 * GDB/MI Tracepoint Commands::
119 * GDB/MI Variable Objects::
122 @c When these are implemented, they should be moved to be between Misc and
123 @c Stack Manipulation in the above menu. They are now outside the menu
124 @c because makeinfo 3.12 barfs if it sees @ignore or @comments in the
127 * GDB/MI Kod Commands::
128 * GDB/MI Memory Overlay Commands::
129 * GDB/MI Signal Handling Commands::
132 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
133 @node GDB/MI Command Syntax
134 @section @sc{gdb/mi} Command Syntax
137 * GDB/MI Input Syntax::
138 * GDB/MI Output Syntax::
139 * GDB/MI Simple Examples::
142 @node GDB/MI Input Syntax
143 @subsection @sc{gdb/mi} Input Syntax
145 @cindex input syntax for @sc{gdb/mi}
146 @cindex @sc{gdb/mi}, input syntax
148 @item @var{command} @expansion{}
149 @code{@var{cli-command} | @var{mi-command}}
151 @item @var{cli-command} @expansion{}
152 @code{[ @var{token} ] @var{cli-command} @var{nl}}, where
153 @var{cli-command} is any existing @value{GDBN} CLI command.
155 @item @var{mi-command} @expansion{}
156 @code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )*
157 @code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}}
159 @item @var{token} @expansion{}
160 "any sequence of digits"
162 @item @var{option} @expansion{}
163 @code{"-" @var{parameter} [ " " @var{parameter} ]}
165 @item @var{parameter} @expansion{}
166 @code{@var{non-blank-sequence} | @var{c-string}}
168 @item @var{operation} @expansion{}
169 @emph{any of the operations described in this chapter}
171 @item @var{non-blank-sequence} @expansion{}
172 @emph{anything, provided it doesn't contain special characters such as
173 "-", @var{nl}, """ and of course " "}
175 @item @var{c-string} @expansion{}
176 @code{""" @var{seven-bit-iso-c-string-content} """}
178 @item @var{nl} @expansion{}
187 The CLI commands are still handled by the @sc{mi} interpreter; their
188 output is described below.
191 The @code{@var{token}}, when present, is passed back when the command
195 Some @sc{mi} commands accept optional arguments as part of the parameter
196 list. Each option is identified by a leading @samp{-} (dash) and may be
197 followed by an optional argument parameter. Options occur first in the
198 parameter list and can be delimited from normal parameters using
199 @samp{--} (this is useful when some parameters begin with a dash).
206 We want easy access to the existing CLI syntax (for debugging).
209 We want it to be easy to spot a @sc{mi} operation.
212 @node GDB/MI Output Syntax
213 @subsection @sc{gdb/mi} Output Syntax
215 @cindex output syntax of @sc{gdb/mi}
216 @cindex @sc{gdb/mi}, output syntax
217 The output from @sc{gdb/mi} consists of zero or more out-of-band records
218 followed, optionally, by a single result record. This result record
219 is for the most recent command. The sequence of output records is
220 terminated by @samp{(@value{GDBP})}.
222 If an input command was prefixed with a @code{@var{token}} then the
223 corresponding output for that command will also be prefixed by that same
227 @item @var{output} @expansion{}
228 @code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
230 @item @var{result-record} @expansion{}
231 @code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
233 @item @var{out-of-band-record} @expansion{}
234 @code{@var{async-record} | @var{stream-record}}
236 @item @var{async-record} @expansion{}
237 @code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
239 @item @var{exec-async-output} @expansion{}
240 @code{[ @var{token} ] "*" @var{async-output}}
242 @item @var{status-async-output} @expansion{}
243 @code{[ @var{token} ] "+" @var{async-output}}
245 @item @var{notify-async-output} @expansion{}
246 @code{[ @var{token} ] "=" @var{async-output}}
248 @item @var{async-output} @expansion{}
249 @code{@var{async-class} ( "," @var{result} )* @var{nl}}
251 @item @var{result-class} @expansion{}
252 @code{"done" | "running" | "connected" | "error" | "exit"}
254 @item @var{async-class} @expansion{}
255 @code{"stopped" | @var{others}} (where @var{others} will be added
256 depending on the needs---this is still in development).
258 @item @var{result} @expansion{}
259 @code{ @var{variable} "=" @var{value}}
261 @item @var{variable} @expansion{}
262 @code{ @var{string} }
264 @item @var{value} @expansion{}
265 @code{ @var{const} | @var{tuple} | @var{list} }
267 @item @var{const} @expansion{}
268 @code{@var{c-string}}
270 @item @var{tuple} @expansion{}
271 @code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" }
273 @item @var{list} @expansion{}
274 @code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "["
275 @var{result} ( "," @var{result} )* "]" }
277 @item @var{stream-record} @expansion{}
278 @code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
280 @item @var{console-stream-output} @expansion{}
281 @code{"~" @var{c-string}}
283 @item @var{target-stream-output} @expansion{}
284 @code{"@@" @var{c-string}}
286 @item @var{log-stream-output} @expansion{}
287 @code{"&" @var{c-string}}
289 @item @var{nl} @expansion{}
292 @item @var{token} @expansion{}
293 @emph{any sequence of digits}.
301 All output sequences end in a single line containing a period.
304 The @code{@var{token}} is from the corresponding request. If an execution
305 command is interrupted by the @samp{-exec-interrupt} command, the
306 @var{token} associated with the @samp{*stopped} message is the one of the
307 original execution command, not the one of the interrupt command.
310 @cindex status output in @sc{gdb/mi}
311 @var{status-async-output} contains on-going status information about the
312 progress of a slow operation. It can be discarded. All status output is
313 prefixed by @samp{+}.
316 @cindex async output in @sc{gdb/mi}
317 @var{exec-async-output} contains asynchronous state change on the target
318 (stopped, started, disappeared). All async output is prefixed by
322 @cindex notify output in @sc{gdb/mi}
323 @var{notify-async-output} contains supplementary information that the
324 client should handle (e.g., a new breakpoint information). All notify
325 output is prefixed by @samp{=}.
328 @cindex console output in @sc{gdb/mi}
329 @var{console-stream-output} is output that should be displayed as is in the
330 console. It is the textual response to a CLI command. All the console
331 output is prefixed by @samp{~}.
334 @cindex target output in @sc{gdb/mi}
335 @var{target-stream-output} is the output produced by the target program.
336 All the target output is prefixed by @samp{@@}.
339 @cindex log output in @sc{gdb/mi}
340 @var{log-stream-output} is output text coming from @value{GDBN}'s internals, for
341 instance messages that should be displayed as part of an error log. All
342 the log output is prefixed by @samp{&}.
345 @cindex list output in @sc{gdb/mi}
346 New @sc{gdb/mi} commands should only output @var{lists} containing
352 @xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
353 details about the various output records.
355 @node GDB/MI Simple Examples
356 @subsection Simple Examples of @sc{gdb/mi} Interaction
357 @cindex @sc{gdb/mi}, simple examples
359 This subsection presents several simple examples of interaction using
360 the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
361 following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
362 the output received from @sc{gdb/mi}.
364 @subsubheading Target Stop
366 Here's an example of stopping the inferior process:
377 <- *stop,reason="stop",address="0x123",source="a.c:123"
381 @subsubheading Simple CLI Command
383 Here's an example of a simple CLI command being passed through
384 @sc{gdb/mi} and on to the CLI.
392 @subsubheading Command With Side Effects
395 -> -symbol-file xyz.exe
396 <- *breakpoint,nr="3",address="0x123",source="a.c:123"
400 @subsubheading A Bad Command
402 Here's what happens if you pass a non-existent command:
406 <- error,"Rubbish not found"
410 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
411 @node GDB/MI Compatibility with CLI
412 @section @sc{gdb/mi} Compatibility with CLI
414 @cindex compatibility, @sc{gdb/mi} and CLI
415 @cindex @sc{gdb/mi}, compatibility with CLI
416 To help users familiar with @value{GDBN}'s existing CLI interface, @sc{gdb/mi}
417 accepts existing CLI commands. As specified by the syntax, such
418 commands can be directly entered into the @sc{gdb/mi} interface and @value{GDBN} will
421 This mechanism is provided as an aid to developers of @sc{gdb/mi}
422 clients and not as a reliable interface into the CLI. Since the command
423 is being interpreteted in an environment that assumes @sc{gdb/mi}
424 behaviour, the exact output of such commands is likely to end up being
425 an un-supported hybrid of @sc{gdb/mi} and CLI output.
427 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
428 @node GDB/MI Output Records
429 @section @sc{gdb/mi} Output Records
432 * GDB/MI Result Records::
433 * GDB/MI Stream Records::
434 * GDB/MI Out-of-band Records::
437 @node GDB/MI Result Records
438 @subsection @sc{gdb/mi} Result Records
440 @cindex result records in @sc{gdb/mi}
441 @cindex @sc{gdb/mi}, result records
442 In addition to a number of out-of-band notifications, the response to a
443 @sc{gdb/mi} command includes one of the following result indications:
447 @item "^done" [ "," @var{results} ]
448 The synchronous operation was successful, @code{@var{results}} are the return
453 @c Is this one correct? Should it be an out-of-band notification?
454 The asynchronous operation was successfully started. The target is
457 @item "^error" "," @var{c-string}
459 The operation failed. The @code{@var{c-string}} contains the corresponding
463 @node GDB/MI Stream Records
464 @subsection @sc{gdb/mi} Stream Records
466 @cindex @sc{gdb/mi}, stream records
467 @cindex stream records in @sc{gdb/mi}
468 @value{GDBN} internally maintains a number of output streams: the console, the
469 target, and the log. The output intended for each of these streams is
470 funneled through the @sc{gdb/mi} interface using @dfn{stream records}.
472 Each stream record begins with a unique @dfn{prefix character} which
473 identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output
474 Syntax}). In addition to the prefix, each stream record contains a
475 @code{@var{string-output}}. This is either raw text (with an implicit new
476 line) or a quoted C string (which does not contain an implicit newline).
479 @item "~" @var{string-output}
480 The console output stream contains text that should be displayed in the
481 CLI console window. It contains the textual responses to CLI commands.
483 @item "@@" @var{string-output}
484 The target output stream contains any textual output from the running
487 @item "&" @var{string-output}
488 The log stream contains debugging messages being produced by @value{GDBN}'s
492 @node GDB/MI Out-of-band Records
493 @subsection @sc{gdb/mi} Out-of-band Records
495 @cindex out-of-band records in @sc{gdb/mi}
496 @cindex @sc{gdb/mi}, out-of-band records
497 @dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of
498 additional changes that have occurred. Those changes can either be a
499 consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
500 target activity (e.g., target stopped).
502 The following is a preliminary list of possible out-of-band records.
509 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
510 @node GDB/MI Command Description Format
511 @section @sc{gdb/mi} Command Description Format
513 The remaining sections describe blocks of commands. Each block of
514 commands is laid out in a fashion similar to this section.
516 Note the the line breaks shown in the examples are here only for
517 readability. They don't appear in the real output.
518 Also note that the commands with a non-available example (N.A.@:) are
521 @subheading Motivation
523 The motivation for this collection of commands.
525 @subheading Introduction
527 A brief introduction to this collection of commands as a whole.
531 For each command in the block, the following is described:
533 @subsubheading Synopsis
536 -command @var{args}@dots{}
539 @subsubheading @value{GDBN} Command
541 The corresponding @value{GDBN} CLI command.
543 @subsubheading Result
545 @subsubheading Out-of-band
549 @subsubheading Example
552 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
553 @node GDB/MI Breakpoint Table Commands
554 @section @sc{gdb/mi} Breakpoint table commands
556 @cindex breakpoint commands for @sc{gdb/mi}
557 @cindex @sc{gdb/mi}, breakpoint commands
558 This section documents @sc{gdb/mi} commands for manipulating
561 @subheading The @code{-break-after} Command
564 @subsubheading Synopsis
567 -break-after @var{number} @var{count}
570 The breakpoint number @var{number} is not in effect until it has been
571 hit @var{count} times. To see how this is reflected in the output of
572 the @samp{-break-list} command, see the description of the
573 @samp{-break-list} command below.
575 @subsubheading @value{GDBN} Command
577 The corresponding @value{GDBN} command is @samp{ignore}.
579 @subsubheading Example
584 ^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@}
591 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
592 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
593 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
594 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
595 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
596 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
597 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
598 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
599 addr="0x000100d0",func="main",file="hello.c",line="5",times="0",
605 @subheading The @code{-break-catch} Command
608 @subheading The @code{-break-commands} Command
609 @findex -break-commands
613 @subheading The @code{-break-condition} Command
614 @findex -break-condition
616 @subsubheading Synopsis
619 -break-condition @var{number} @var{expr}
622 Breakpoint @var{number} will stop the program only if the condition in
623 @var{expr} is true. The condition becomes part of the
624 @samp{-break-list} output (see the description of the @samp{-break-list}
627 @subsubheading @value{GDBN} Command
629 The corresponding @value{GDBN} command is @samp{condition}.
631 @subsubheading Example
639 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
640 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
641 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
642 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
643 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
644 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
645 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
646 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
647 addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",
648 times="0",ignore="3"@}]@}
652 @subheading The @code{-break-delete} Command
653 @findex -break-delete
655 @subsubheading Synopsis
658 -break-delete ( @var{breakpoint} )+
661 Delete the breakpoint(s) whose number(s) are specified in the argument
662 list. This is obviously reflected in the breakpoint list.
664 @subsubheading @value{GDBN} command
666 The corresponding @value{GDBN} command is @samp{delete}.
668 @subsubheading Example
676 ^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
677 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
678 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
679 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
680 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
681 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
682 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
687 @subheading The @code{-break-disable} Command
688 @findex -break-disable
690 @subsubheading Synopsis
693 -break-disable ( @var{breakpoint} )+
696 Disable the named @var{breakpoint}(s). The field @samp{enabled} in the
697 break list is now set to @samp{n} for the named @var{breakpoint}(s).
699 @subsubheading @value{GDBN} Command
701 The corresponding @value{GDBN} command is @samp{disable}.
703 @subsubheading Example
711 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
712 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
713 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
714 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
715 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
716 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
717 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
718 body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
719 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@}
723 @subheading The @code{-break-enable} Command
724 @findex -break-enable
726 @subsubheading Synopsis
729 -break-enable ( @var{breakpoint} )+
732 Enable (previously disabled) @var{breakpoint}(s).
734 @subsubheading @value{GDBN} Command
736 The corresponding @value{GDBN} command is @samp{enable}.
738 @subsubheading Example
746 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
747 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
748 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
749 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
750 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
751 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
752 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
753 body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
754 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@}
758 @subheading The @code{-break-info} Command
761 @subsubheading Synopsis
764 -break-info @var{breakpoint}
768 Get information about a single breakpoint.
770 @subsubheading @value{GDBN} command
772 The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
774 @subsubheading Example
777 @subheading The @code{-break-insert} Command
778 @findex -break-insert
780 @subsubheading Synopsis
783 -break-insert [ -t ] [ -h ] [ -r ]
784 [ -c @var{condition} ] [ -i @var{ignore-count} ]
785 [ -p @var{thread} ] [ @var{line} | @var{addr} ]
789 If specified, @var{line}, can be one of:
796 @item filename:linenum
797 @item filename:function
801 The possible optional parameters of this command are:
805 Insert a tempoary breakpoint.
807 Insert a hardware breakpoint.
808 @item -c @var{condition}
809 Make the breakpoint conditional on @var{condition}.
810 @item -i @var{ignore-count}
811 Initialize the @var{ignore-count}.
813 Insert a regular breakpoint in all the functions whose names match the
814 given regular expression. Other flags are not applicable to regular
818 @subsubheading Result
820 The result is in the form:
823 ^done,bkptno="@var{number}",func="@var{funcname}",
824 file="@var{filename}",line="@var{lineno}"
828 where @var{number} is the @value{GDBN} number for this breakpoint, @var{funcname}
829 is the name of the function where the breakpoint was inserted,
830 @var{filename} is the name of the source file which contains this
831 function, and @var{lineno} is the source line number within that file.
833 Note: this format is open to change.
834 @c An out-of-band breakpoint instead of part of the result?
836 @subsubheading @value{GDBN} Command
838 The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
839 @samp{hbreak}, @samp{thbreak}, and @samp{rbreak}.
841 @subsubheading Example
846 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
849 ^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@}
852 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
853 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
854 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
855 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
856 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
857 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
858 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
859 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
860 addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@},
861 bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
862 addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}]@}
864 -break-insert -r foo.*
866 ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@}
870 @subheading The @code{-break-list} Command
873 @subsubheading Synopsis
879 Displays the list of inserted breakpoints, showing the following fields:
883 number of the breakpoint
885 type of the breakpoint: @samp{breakpoint} or @samp{watchpoint}
887 should the breakpoint be deleted or disabled when it is hit: @samp{keep}
890 is the breakpoint enabled or no: @samp{y} or @samp{n}
892 memory location at which the breakpoint is set
894 logical location of the breakpoint, expressed by function name, file
897 number of times the breakpoint has been hit
900 If there are no breakpoints or watchpoints, the @code{BreakpointTable}
901 @code{body} field is an empty list.
903 @subsubheading @value{GDBN} Command
905 The corresponding @value{GDBN} command is @samp{info break}.
907 @subsubheading Example
912 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
913 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
914 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
915 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
916 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
917 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
918 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
919 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
920 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
921 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
922 addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}]@}
926 Here's an example of the result when there are no breakpoints:
931 ^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
932 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
933 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
934 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
935 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
936 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
937 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
942 @subheading The @code{-break-watch} Command
945 @subsubheading Synopsis
948 -break-watch [ -a | -r ]
951 Create a watchpoint. With the @samp{-a} option it will create an
952 @dfn{access} watchpoint, i.e. a watchpoint that triggers either on a
953 read from or on a write to the memory location. With the @samp{-r}
954 option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will
955 trigger only when the memory location is accessed for reading. Without
956 either of the options, the watchpoint created is a regular watchpoint,
957 i.e. it will trigger when the memory location is accessed for writing.
958 @xref{Set Watchpoints, , Setting watchpoints}.
960 Note that @samp{-break-list} will report a single list of watchpoints and
961 breakpoints inserted.
963 @subsubheading @value{GDBN} Command
965 The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and
968 @subsubheading Example
970 Setting a watchpoint on a variable in the @code{main} function:
975 ^done,wpt=@{number="2",exp="x"@}
979 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
980 value=@{old="-268439212",new="55"@},
981 frame=@{func="main",args=[],file="recursive2.c",line="5"@}
985 Setting a watchpoint on a variable local to a function. @value{GDBN} will stop
986 the program execution twice: first for the variable changing value, then
987 for the watchpoint going out of scope.
992 ^done,wpt=@{number="5",exp="C"@}
996 ^done,reason="watchpoint-trigger",
997 wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
998 frame=@{func="callee4",args=[],
999 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
1003 ^done,reason="watchpoint-scope",wpnum="5",
1004 frame=@{func="callee3",args=[@{name="strarg",
1005 value="0x11940 \"A string argument.\""@}],
1006 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1010 Listing breakpoints and watchpoints, at different points in the program
1011 execution. Note that once the watchpoint goes out of scope, it is
1017 ^done,wpt=@{number="2",exp="C"@}
1020 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
1021 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
1022 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
1023 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
1024 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
1025 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
1026 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
1027 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
1028 addr="0x00010734",func="callee4",
1029 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
1030 bkpt=@{number="2",type="watchpoint",disp="keep",
1031 enabled="y",addr="",what="C",times="0"@}]@}
1035 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
1036 value=@{old="-276895068",new="3"@},
1037 frame=@{func="callee4",args=[],
1038 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
1041 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
1042 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
1043 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
1044 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
1045 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
1046 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
1047 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
1048 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
1049 addr="0x00010734",func="callee4",
1050 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
1051 bkpt=@{number="2",type="watchpoint",disp="keep",
1052 enabled="y",addr="",what="C",times="-5"@}]@}
1056 ^done,reason="watchpoint-scope",wpnum="2",
1057 frame=@{func="callee3",args=[@{name="strarg",
1058 value="0x11940 \"A string argument.\""@}],
1059 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
1062 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
1063 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
1064 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
1065 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
1066 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
1067 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
1068 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
1069 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
1070 addr="0x00010734",func="callee4",
1071 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}]@}
1075 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1076 @node GDB/MI Data Manipulation
1077 @section @sc{gdb/mi} Data Manipulation
1079 @cindex data manipulation, in @sc{gdb/mi}
1080 @cindex @sc{gdb/mi}, data manipulation
1081 This section describes the @sc{gdb/mi} commands that manipulate data:
1082 examine memory and registers, evaluate expressions, etc.
1084 @c REMOVED FROM THE INTERFACE.
1085 @c @subheading -data-assign
1086 @c Change the value of a program variable. Plenty of side effects.
1087 @c @subsubheading GDB command
1089 @c @subsubheading Example
1092 @subheading The @code{-data-disassemble} Command
1093 @findex -data-disassemble
1095 @subsubheading Synopsis
1099 [ -s @var{start-addr} -e @var{end-addr} ]
1100 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
1108 @item @var{start-addr}
1109 is the beginning address (or @code{$pc})
1110 @item @var{end-addr}
1112 @item @var{filename}
1113 is the name of the file to disassemble
1115 is the line number to disassemble around
1117 is the the number of disassembly lines to be produced. If it is -1,
1118 the whole function will be disassembled, in case no @var{end-addr} is
1119 specified. If @var{end-addr} is specified as a non-zero value, and
1120 @var{lines} is lower than the number of disassembly lines between
1121 @var{start-addr} and @var{end-addr}, only @var{lines} lines are
1122 displayed; if @var{lines} is higher than the number of lines between
1123 @var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
1126 is either 0 (meaning only disassembly) or 1 (meaning mixed source and
1130 @subsubheading Result
1132 The output for each instruction is composed of four fields:
1141 Note that whatever included in the instruction field, is not manipulated
1142 directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format.
1144 @subsubheading @value{GDBN} Command
1146 There's no direct mapping from this command to the CLI.
1148 @subsubheading Example
1150 Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
1154 -data-disassemble -s $pc -e "$pc + 20" -- 0
1157 @{address="0x000107c0",func-name="main",offset="4",
1158 inst="mov 2, %o0"@},
1159 @{address="0x000107c4",func-name="main",offset="8",
1160 inst="sethi %hi(0x11800), %o2"@},
1161 @{address="0x000107c8",func-name="main",offset="12",
1162 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
1163 @{address="0x000107cc",func-name="main",offset="16",
1164 inst="sethi %hi(0x11800), %o2"@},
1165 @{address="0x000107d0",func-name="main",offset="20",
1166 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}]
1170 Disassemble the whole @code{main} function. Line 32 is part of
1174 -data-disassemble -f basics.c -l 32 -- 0
1176 @{address="0x000107bc",func-name="main",offset="0",
1177 inst="save %sp, -112, %sp"@},
1178 @{address="0x000107c0",func-name="main",offset="4",
1179 inst="mov 2, %o0"@},
1180 @{address="0x000107c4",func-name="main",offset="8",
1181 inst="sethi %hi(0x11800), %o2"@},
1183 @{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
1184 @{address="0x00010820",func-name="main",offset="100",inst="restore "@}]
1188 Disassemble 3 instructions from the start of @code{main}:
1192 -data-disassemble -f basics.c -l 32 -n 3 -- 0
1194 @{address="0x000107bc",func-name="main",offset="0",
1195 inst="save %sp, -112, %sp"@},
1196 @{address="0x000107c0",func-name="main",offset="4",
1197 inst="mov 2, %o0"@},
1198 @{address="0x000107c4",func-name="main",offset="8",
1199 inst="sethi %hi(0x11800), %o2"@}]
1203 Disassemble 3 instructions from the start of @code{main} in mixed mode:
1207 -data-disassemble -f basics.c -l 32 -n 3 -- 1
1209 src_and_asm_line=@{line="31",
1210 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1211 testsuite/gdb.mi/basics.c",line_asm_insn=[
1212 @{address="0x000107bc",func-name="main",offset="0",
1213 inst="save %sp, -112, %sp"@}]@},
1214 src_and_asm_line=@{line="32",
1215 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
1216 testsuite/gdb.mi/basics.c",line_asm_insn=[
1217 @{address="0x000107c0",func-name="main",offset="4",
1218 inst="mov 2, %o0"@},
1219 @{address="0x000107c4",func-name="main",offset="8",
1220 inst="sethi %hi(0x11800), %o2"@}]@}]
1225 @subheading The @code{-data-evaluate-expression} Command
1226 @findex -data-evaluate-expression
1228 @subsubheading Synopsis
1231 -data-evaluate-expression @var{expr}
1234 Evaluate @var{expr} as an expression. The expression could contain an
1235 inferior function call. The function call will execute synchronously.
1236 If the expression contains spaces, it must be enclosed in double quotes.
1238 @subsubheading @value{GDBN} Command
1240 The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
1241 @samp{call}. In @code{gdbtk} only, there's a corresponding
1242 @samp{gdb_eval} command.
1244 @subsubheading Example
1246 In the following example, the numbers that precede the commands are the
1247 @dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
1248 Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
1252 211-data-evaluate-expression A
1255 311-data-evaluate-expression &A
1256 311^done,value="0xefffeb7c"
1258 411-data-evaluate-expression A+3
1261 511-data-evaluate-expression "A + 3"
1267 @subheading The @code{-data-list-changed-registers} Command
1268 @findex -data-list-changed-registers
1270 @subsubheading Synopsis
1273 -data-list-changed-registers
1276 Display a list of the registers that have changed.
1278 @subsubheading @value{GDBN} Command
1280 @value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
1281 has the corresponding command @samp{gdb_changed_register_list}.
1283 @subsubheading Example
1293 *stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
1294 args=[],file="try.c",line="5"@}
1296 -data-list-changed-registers
1297 ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
1298 "10","11","13","14","15","16","17","18","19","20","21","22","23",
1299 "24","25","26","27","28","30","31","64","65","66","67","69"]
1304 @subheading The @code{-data-list-register-names} Command
1305 @findex -data-list-register-names
1307 @subsubheading Synopsis
1310 -data-list-register-names [ ( @var{regno} )+ ]
1313 Show a list of register names for the current target. If no arguments
1314 are given, it shows a list of the names of all the registers. If
1315 integer numbers are given as arguments, it will print a list of the
1316 names of the registers corresponding to the arguments. To ensure
1317 consistency between a register name and its number, the output list may
1318 include empty register names.
1320 @subsubheading @value{GDBN} Command
1322 @value{GDBN} does not have a command which corresponds to
1323 @samp{-data-list-register-names}. In @code{gdbtk} there is a
1324 corresponding command @samp{gdb_regnames}.
1326 @subsubheading Example
1328 For the PPC MBX board:
1331 -data-list-register-names
1332 ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
1333 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
1334 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
1335 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
1336 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
1337 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
1338 "", "pc","ps","cr","lr","ctr","xer"]
1340 -data-list-register-names 1 2 3
1341 ^done,register-names=["r1","r2","r3"]
1345 @subheading The @code{-data-list-register-values} Command
1346 @findex -data-list-register-values
1348 @subsubheading Synopsis
1351 -data-list-register-values @var{fmt} [ ( @var{regno} )*]
1354 Display the registers' contents. @var{fmt} is the format according to
1355 which the registers' contents are to be returned, followed by an optional
1356 list of numbers specifying the registers to display. A missing list of
1357 numbers indicates that the contents of all the registers must be returned.
1359 Allowed formats for @var{fmt} are:
1376 @subsubheading @value{GDBN} Command
1378 The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
1379 all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
1381 @subsubheading Example
1383 For a PPC MBX board (note: line breaks are for readability only, they
1384 don't appear in the actual output):
1388 -data-list-register-values r 64 65
1389 ^done,register-values=[@{number="64",value="0xfe00a300"@},
1390 @{number="65",value="0x00029002"@}]
1392 -data-list-register-values x
1393 ^done,register-values=[@{number="0",value="0xfe0043c8"@},
1394 @{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
1395 @{number="3",value="0x0"@},@{number="4",value="0xa"@},
1396 @{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
1397 @{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
1398 @{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
1399 @{number="11",value="0x1"@},@{number="12",value="0x0"@},
1400 @{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
1401 @{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
1402 @{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
1403 @{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
1404 @{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
1405 @{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
1406 @{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
1407 @{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
1408 @{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
1409 @{number="31",value="0x0"@},@{number="32",value="0x0"@},
1410 @{number="33",value="0x0"@},@{number="34",value="0x0"@},
1411 @{number="35",value="0x0"@},@{number="36",value="0x0"@},
1412 @{number="37",value="0x0"@},@{number="38",value="0x0"@},
1413 @{number="39",value="0x0"@},@{number="40",value="0x0"@},
1414 @{number="41",value="0x0"@},@{number="42",value="0x0"@},
1415 @{number="43",value="0x0"@},@{number="44",value="0x0"@},
1416 @{number="45",value="0x0"@},@{number="46",value="0x0"@},
1417 @{number="47",value="0x0"@},@{number="48",value="0x0"@},
1418 @{number="49",value="0x0"@},@{number="50",value="0x0"@},
1419 @{number="51",value="0x0"@},@{number="52",value="0x0"@},
1420 @{number="53",value="0x0"@},@{number="54",value="0x0"@},
1421 @{number="55",value="0x0"@},@{number="56",value="0x0"@},
1422 @{number="57",value="0x0"@},@{number="58",value="0x0"@},
1423 @{number="59",value="0x0"@},@{number="60",value="0x0"@},
1424 @{number="61",value="0x0"@},@{number="62",value="0x0"@},
1425 @{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
1426 @{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
1427 @{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
1428 @{number="69",value="0x20002b03"@}]
1433 @subheading The @code{-data-read-memory} Command
1434 @findex -data-read-memory
1436 @subsubheading Synopsis
1439 -data-read-memory [ -o @var{byte-offset} ]
1440 @var{address} @var{word-format} @var{word-size}
1441 @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
1449 An expression specifying the address of the first memory word to be
1450 read. Complex expressions containing embedded white space should be
1451 quoted using the C convention.
1453 @item @var{word-format}
1454 The format to be used to print the memory words. The notation is the
1455 same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
1458 @item @var{word-size}
1459 The size of each memory word in bytes.
1462 The number of rows in the output table.
1465 The number of columns in the output table.
1468 If present, indicates that each row should include an @sc{ascii} dump. The
1469 value of @var{aschar} is used as a padding character when a byte is not a
1470 member of the printable @sc{ascii} character set (printable @sc{ascii}
1471 characters are those whose code is between 32 and 126, inclusively).
1473 @item @var{byte-offset}
1474 An offset to add to the @var{address} before fetching memory.
1477 This command displays memory contents as a table of @var{nr-rows} by
1478 @var{nr-cols} words, each word being @var{word-size} bytes. In total,
1479 @code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
1480 (returned as @samp{total-bytes}). Should less then the requested number
1481 of bytes be returned by the target, the missing words are identified
1482 using @samp{N/A}. The number of bytes read from the target is returned
1483 in @samp{nr-bytes} and the starting address used to read memory in
1486 The address of the next/previous row or page is available in
1487 @samp{next-row} and @samp{prev-row}, @samp{next-page} and
1490 @subsubheading @value{GDBN} Command
1492 The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
1493 @samp{gdb_get_mem} memory read command.
1495 @subsubheading Example
1497 Read six bytes of memory starting at @code{bytes+6} but then offset by
1498 @code{-6} bytes. Format as three rows of two columns. One byte per
1499 word. Display each word in hex.
1503 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
1504 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
1505 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
1506 prev-page="0x0000138a",memory=[
1507 @{addr="0x00001390",data=["0x00","0x01"]@},
1508 @{addr="0x00001392",data=["0x02","0x03"]@},
1509 @{addr="0x00001394",data=["0x04","0x05"]@}]
1513 Read two bytes of memory starting at address @code{shorts + 64} and
1514 display as a single word formatted in decimal.
1518 5-data-read-memory shorts+64 d 2 1 1
1519 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
1520 next-row="0x00001512",prev-row="0x0000150e",
1521 next-page="0x00001512",prev-page="0x0000150e",memory=[
1522 @{addr="0x00001510",data=["128"]@}]
1526 Read thirty two bytes of memory starting at @code{bytes+16} and format
1527 as eight rows of four columns. Include a string encoding with @samp{x}
1528 used as the non-printable character.
1532 4-data-read-memory bytes+16 x 1 8 4 x
1533 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
1534 next-row="0x000013c0",prev-row="0x0000139c",
1535 next-page="0x000013c0",prev-page="0x00001380",memory=[
1536 @{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@},
1537 @{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@},
1538 @{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@},
1539 @{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@},
1540 @{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@},
1541 @{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@},
1542 @{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@},
1543 @{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}]
1547 @subheading The @code{-display-delete} Command
1548 @findex -display-delete
1550 @subsubheading Synopsis
1553 -display-delete @var{number}
1556 Delete the display @var{number}.
1558 @subsubheading @value{GDBN} Command
1560 The corresponding @value{GDBN} command is @samp{delete display}.
1562 @subsubheading Example
1566 @subheading The @code{-display-disable} Command
1567 @findex -display-disable
1569 @subsubheading Synopsis
1572 -display-disable @var{number}
1575 Disable display @var{number}.
1577 @subsubheading @value{GDBN} Command
1579 The corresponding @value{GDBN} command is @samp{disable display}.
1581 @subsubheading Example
1585 @subheading The @code{-display-enable} Command
1586 @findex -display-enable
1588 @subsubheading Synopsis
1591 -display-enable @var{number}
1594 Enable display @var{number}.
1596 @subsubheading @value{GDBN} Command
1598 The corresponding @value{GDBN} command is @samp{enable display}.
1600 @subsubheading Example
1604 @subheading The @code{-display-insert} Command
1605 @findex -display-insert
1607 @subsubheading Synopsis
1610 -display-insert @var{expression}
1613 Display @var{expression} every time the program stops.
1615 @subsubheading @value{GDBN} Command
1617 The corresponding @value{GDBN} command is @samp{display}.
1619 @subsubheading Example
1623 @subheading The @code{-display-list} Command
1624 @findex -display-list
1626 @subsubheading Synopsis
1632 List the displays. Do not show the current values.
1634 @subsubheading @value{GDBN} Command
1636 The corresponding @value{GDBN} command is @samp{info display}.
1638 @subsubheading Example
1642 @subheading The @code{-environment-cd} Command
1643 @findex -environment-cd
1645 @subsubheading Synopsis
1648 -environment-cd @var{pathdir}
1651 Set @value{GDBN}'s working directory.
1653 @subsubheading @value{GDBN} Command
1655 The corresponding @value{GDBN} command is @samp{cd}.
1657 @subsubheading Example
1661 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1667 @subheading The @code{-environment-directory} Command
1668 @findex -environment-directory
1670 @subsubheading Synopsis
1673 -environment-directory @var{pathdir}
1676 Add directory @var{pathdir} to beginning of search path for source files.
1678 @subsubheading @value{GDBN} Command
1680 The corresponding @value{GDBN} command is @samp{dir}.
1682 @subsubheading Example
1686 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
1692 @subheading The @code{-environment-path} Command
1693 @findex -environment-path
1695 @subsubheading Synopsis
1698 -environment-path ( @var{pathdir} )+
1701 Add directories @var{pathdir} to beginning of search path for object files.
1703 @subsubheading @value{GDBN} Command
1705 The corresponding @value{GDBN} command is @samp{path}.
1707 @subsubheading Example
1711 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb
1717 @subheading The @code{-environment-pwd} Command
1718 @findex -environment-pwd
1720 @subsubheading Synopsis
1726 Show the current working directory.
1728 @subsubheading @value{GDBN} command
1730 The corresponding @value{GDBN} command is @samp{pwd}.
1732 @subsubheading Example
1737 ~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb.
1742 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1743 @node GDB/MI Program Control
1744 @section @sc{gdb/mi} Program control
1746 @subsubheading Program termination
1748 As a result of execution, the inferior program can run to completion, if
1749 it doesn't encounter any breakpoints. In this case the output will
1750 include an exit code, if the program has exited exceptionally.
1752 @subsubheading Examples
1755 Program exited normally:
1763 *stopped,reason="exited-normally"
1768 Program exited exceptionally:
1776 *stopped,reason="exited",exit-code="01"
1780 Another way the program can terminate is if it receives a signal such as
1781 @code{SIGINT}. In this case, @sc{gdb/mi} displays this:
1785 *stopped,reason="exited-signalled",signal-name="SIGINT",
1786 signal-meaning="Interrupt"
1790 @subheading The @code{-exec-abort} Command
1793 @subsubheading Synopsis
1799 Kill the inferior running program.
1801 @subsubheading @value{GDBN} Command
1803 The corresponding @value{GDBN} command is @samp{kill}.
1805 @subsubheading Example
1809 @subheading The @code{-exec-arguments} Command
1810 @findex -exec-arguments
1812 @subsubheading Synopsis
1815 -exec-arguments @var{args}
1818 Set the inferior program arguments, to be used in the next
1821 @subsubheading @value{GDBN} Command
1823 The corresponding @value{GDBN} command is @samp{set args}.
1825 @subsubheading Example
1828 Don't have one around.
1831 @subheading The @code{-exec-continue} Command
1832 @findex -exec-continue
1834 @subsubheading Synopsis
1840 Asynchronous command. Resumes the execution of the inferior program
1841 until a breakpoint is encountered, or until the inferior exits.
1843 @subsubheading @value{GDBN} Command
1845 The corresponding @value{GDBN} corresponding is @samp{continue}.
1847 @subsubheading Example
1854 *stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
1855 file="hello.c",line="13"@}
1860 @subheading The @code{-exec-finish} Command
1861 @findex -exec-finish
1863 @subsubheading Synopsis
1869 Asynchronous command. Resumes the execution of the inferior program
1870 until the current function is exited. Displays the results returned by
1873 @subsubheading @value{GDBN} Command
1875 The corresponding @value{GDBN} command is @samp{finish}.
1877 @subsubheading Example
1879 Function returning @code{void}.
1886 *stopped,reason="function-finished",frame=@{func="main",args=[],
1887 file="hello.c",line="7"@}
1891 Function returning other than @code{void}. The name of the internal
1892 @value{GDBN} variable storing the result is printed, together with the
1899 *stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
1900 args=[@{name="a",value="1"],@{name="b",value="9"@}@},
1901 file="recursive2.c",line="14"@},
1902 gdb-result-var="$1",return-value="0"
1907 @subheading The @code{-exec-interrupt} Command
1908 @findex -exec-interrupt
1910 @subsubheading Synopsis
1916 Asynchronous command. Interrupts the background execution of the target.
1917 Note how the token associated with the stop message is the one for the
1918 execution command that has been interrupted. The token for the interrupt
1919 itself only appears in the @samp{^done} output. If the user is trying to
1920 interrupt a non-running program, an error message will be printed.
1922 @subsubheading @value{GDBN} Command
1924 The corresponding @value{GDBN} command is @samp{interrupt}.
1926 @subsubheading Example
1937 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
1938 frame=@{addr="0x00010140",func="foo",args=[],file="try.c",line="13"@}
1943 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
1948 @subheading The @code{-exec-next} Command
1951 @subsubheading Synopsis
1957 Asynchronous command. Resumes execution of the inferior program, stopping
1958 when the beginning of the next source line is reached.
1960 @subsubheading @value{GDBN} Command
1962 The corresponding @value{GDBN} command is @samp{next}.
1964 @subsubheading Example
1970 *stopped,reason="end-stepping-range",line="8",file="hello.c"
1975 @subheading The @code{-exec-next-instruction} Command
1976 @findex -exec-next-instruction
1978 @subsubheading Synopsis
1981 -exec-next-instruction
1984 Asynchronous command. Executes one machine instruction. If the
1985 instruction is a function call continues until the function returns. If
1986 the program stops at an instruction in the middle of a source line, the
1987 address will be printed as well.
1989 @subsubheading @value{GDBN} Command
1991 The corresponding @value{GDBN} command is @samp{nexti}.
1993 @subsubheading Example
1997 -exec-next-instruction
2001 *stopped,reason="end-stepping-range",
2002 addr="0x000100d4",line="5",file="hello.c"
2007 @subheading The @code{-exec-return} Command
2008 @findex -exec-return
2010 @subsubheading Synopsis
2016 Makes current function return immediately. Doesn't execute the inferior.
2017 Displays the new current frame.
2019 @subsubheading @value{GDBN} Command
2021 The corresponding @value{GDBN} command is @samp{return}.
2023 @subsubheading Example
2027 200-break-insert callee4
2028 200^done,bkpt=@{number="1",addr="0x00010734",
2029 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
2034 000*stopped,reason="breakpoint-hit",bkptno="1",
2035 frame=@{func="callee4",args=[],
2036 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
2042 111^done,frame=@{level="0 ",func="callee3",
2043 args=[@{name="strarg",
2044 value="0x11940 \"A string argument.\""@}],
2045 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
2050 @subheading The @code{-exec-run} Command
2053 @subsubheading Synopsis
2059 Asynchronous command. Starts execution of the inferior from the
2060 beginning. The inferior executes until either a breakpoint is
2061 encountered or the program exits.
2063 @subsubheading @value{GDBN} Command
2065 The corresponding @value{GDBN} command is @samp{run}.
2067 @subsubheading Example
2072 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
2077 *stopped,reason="breakpoint-hit",bkptno="1",
2078 frame=@{func="main",args=[],file="recursive2.c",line="4"@}
2083 @subheading The @code{-exec-show-arguments} Command
2084 @findex -exec-show-arguments
2086 @subsubheading Synopsis
2089 -exec-show-arguments
2092 Print the arguments of the program.
2094 @subsubheading @value{GDBN} Command
2096 The corresponding @value{GDBN} command is @samp{show args}.
2098 @subsubheading Example
2101 @c @subheading -exec-signal
2103 @subheading The @code{-exec-step} Command
2106 @subsubheading Synopsis
2112 Asynchronous command. Resumes execution of the inferior program, stopping
2113 when the beginning of the next source line is reached, if the next
2114 source line is not a function call. If it is, stop at the first
2115 instruction of the called function.
2117 @subsubheading @value{GDBN} Command
2119 The corresponding @value{GDBN} command is @samp{step}.
2121 @subsubheading Example
2123 Stepping into a function:
2129 *stopped,reason="end-stepping-range",
2130 frame=@{func="foo",args=[@{name="a",value="10"@},
2131 @{name="b",value="0"@}],file="recursive2.c",line="11"@}
2141 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
2146 @subheading The @code{-exec-step-instruction} Command
2147 @findex -exec-step-instruction
2149 @subsubheading Synopsis
2152 -exec-step-instruction
2155 Asynchronous command. Resumes the inferior which executes one machine
2156 instruction. The output, once @value{GDBN} has stopped, will vary depending on
2157 whether we have stopped in the middle of a source line or not. In the
2158 former case, the address at which the program stopped will be printed as
2161 @subsubheading @value{GDBN} Command
2163 The corresponding @value{GDBN} command is @samp{stepi}.
2165 @subsubheading Example
2169 -exec-step-instruction
2173 *stopped,reason="end-stepping-range",
2174 frame=@{func="foo",args=[],file="try.c",line="10"@}
2176 -exec-step-instruction
2180 *stopped,reason="end-stepping-range",
2181 frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@}
2186 @subheading The @code{-exec-until} Command
2189 @subsubheading Synopsis
2192 -exec-until [ @var{location} ]
2195 Asynchronous command. Executes the inferior until the @var{location}
2196 specified in the argument is reached. If there is no argument, the inferior
2197 executes until a source line greater than the current one is reached.
2198 The reason for stopping in this case will be @samp{location-reached}.
2200 @subsubheading @value{GDBN} Command
2202 The corresponding @value{GDBN} command is @samp{until}.
2204 @subsubheading Example
2208 -exec-until recursive2.c:6
2212 *stopped,reason="location-reached",frame=@{func="main",args=[],
2213 file="recursive2.c",line="6"@}
2218 @subheading -file-clear
2219 Is this going away????
2223 @subheading The @code{-file-exec-and-symbols} Command
2224 @findex -file-exec-and-symbols
2226 @subsubheading Synopsis
2229 -file-exec-and-symbols @var{file}
2232 Specify the executable file to be debugged. This file is the one from
2233 which the symbol table is also read. If no file is specified, the
2234 command clears the executable and symbol information. If breakpoints
2235 are set when using this command with no arguments, @value{GDBN} will produce
2236 error messages. Otherwise, no output is produced, except a completion
2239 @subsubheading @value{GDBN} Command
2241 The corresponding @value{GDBN} command is @samp{file}.
2243 @subsubheading Example
2247 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2253 @subheading The @code{-file-exec-file} Command
2254 @findex -file-exec-file
2256 @subsubheading Synopsis
2259 -file-exec-file @var{file}
2262 Specify the executable file to be debugged. Unlike
2263 @samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
2264 from this file. If used without argument, @value{GDBN} clears the information
2265 about the executable file. No output is produced, except a completion
2268 @subsubheading @value{GDBN} Command
2270 The corresponding @value{GDBN} command is @samp{exec-file}.
2272 @subsubheading Example
2276 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2282 @subheading The @code{-file-list-exec-sections} Command
2283 @findex -file-list-exec-sections
2285 @subsubheading Synopsis
2288 -file-list-exec-sections
2291 List the sections of the current executable file.
2293 @subsubheading @value{GDBN} Command
2295 The @value{GDBN} command @samp{info file} shows, among the rest, the same
2296 information as this command. @code{gdbtk} has a corresponding command
2297 @samp{gdb_load_info}.
2299 @subsubheading Example
2303 @subheading The @code{-file-list-exec-source-files} Command
2304 @findex -file-list-exec-source-files
2306 @subsubheading Synopsis
2309 -file-list-exec-source-files
2312 List the source files for the current executable.
2314 @subsubheading @value{GDBN} Command
2316 There's no @value{GDBN} command which directly corresponds to this one.
2317 @code{gdbtk} has an analogous command @samp{gdb_listfiles}.
2319 @subsubheading Example
2323 @subheading The @code{-file-list-shared-libraries} Command
2324 @findex -file-list-shared-libraries
2326 @subsubheading Synopsis
2329 -file-list-shared-libraries
2332 List the shared libraries in the program.
2334 @subsubheading @value{GDBN} Command
2336 The corresponding @value{GDBN} command is @samp{info shared}.
2338 @subsubheading Example
2342 @subheading The @code{-file-list-symbol-files} Command
2343 @findex -file-list-symbol-files
2345 @subsubheading Synopsis
2348 -file-list-symbol-files
2353 @subsubheading @value{GDBN} Command
2355 The corresponding @value{GDBN} command is @samp{info file} (part of it).
2357 @subsubheading Example
2361 @subheading The @code{-file-symbol-file} Command
2362 @findex -file-symbol-file
2364 @subsubheading Synopsis
2367 -file-symbol-file @var{file}
2370 Read symbol table info from the specified @var{file} argument. When
2371 used without arguments, clears @value{GDBN}'s symbol table info. No output is
2372 produced, except for a completion notification.
2374 @subsubheading @value{GDBN} Command
2376 The corresponding @value{GDBN} command is @samp{symbol-file}.
2378 @subsubheading Example
2382 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
2387 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2388 @node GDB/MI Miscellaneous Commands
2389 @section Miscellaneous @value{GDBN} commands in @sc{gdb/mi}
2391 @c @subheading -gdb-complete
2393 @subheading The @code{-gdb-exit} Command
2396 @subsubheading Synopsis
2402 Exit @value{GDBN} immediately.
2404 @subsubheading @value{GDBN} Command
2406 Approximately corresponds to @samp{quit}.
2408 @subsubheading Example
2415 @subheading The @code{-gdb-set} Command
2418 @subsubheading Synopsis
2424 Set an internal @value{GDBN} variable.
2425 @c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
2427 @subsubheading @value{GDBN} Command
2429 The corresponding @value{GDBN} command is @samp{set}.
2431 @subsubheading Example
2441 @subheading The @code{-gdb-show} Command
2444 @subsubheading Synopsis
2450 Show the current value of a @value{GDBN} variable.
2452 @subsubheading @value{GDBN} command
2454 The corresponding @value{GDBN} command is @samp{show}.
2456 @subsubheading Example
2465 @c @subheading -gdb-source
2468 @subheading The @code{-gdb-version} Command
2469 @findex -gdb-version
2471 @subsubheading Synopsis
2477 Show version information for @value{GDBN}. Used mostly in testing.
2479 @subsubheading @value{GDBN} Command
2481 There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this
2482 information when you start an interactive session.
2484 @subsubheading Example
2486 @c This example modifies the actual output from GDB to avoid overfull
2492 ~Copyright 2000 Free Software Foundation, Inc.
2493 ~GDB is free software, covered by the GNU General Public License, and
2494 ~you are welcome to change it and/or distribute copies of it under
2495 ~ certain conditions.
2496 ~Type "show copying" to see the conditions.
2497 ~There is absolutely no warranty for GDB. Type "show warranty" for
2499 ~This GDB was configured as
2500 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
2506 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2507 @node GDB/MI Kod Commands
2508 @section @sc{gdb/mi} Kod Commands
2510 The Kod commands are not implemented.
2512 @c @subheading -kod-info
2514 @c @subheading -kod-list
2516 @c @subheading -kod-list-object-types
2518 @c @subheading -kod-show
2520 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2521 @node GDB/MI Memory Overlay Commands
2522 @section @sc{gdb/mi} Memory Overlay Commands
2524 The memory overlay commands are not implemented.
2526 @c @subheading -overlay-auto
2528 @c @subheading -overlay-list-mapping-state
2530 @c @subheading -overlay-list-overlays
2532 @c @subheading -overlay-map
2534 @c @subheading -overlay-off
2536 @c @subheading -overlay-on
2538 @c @subheading -overlay-unmap
2540 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2541 @node GDB/MI Signal Handling Commands
2542 @section @sc{gdb/mi} Signal Handling Commands
2544 Signal handling commands are not implemented.
2546 @c @subheading -signal-handle
2548 @c @subheading -signal-list-handle-actions
2550 @c @subheading -signal-list-signal-types
2554 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2555 @node GDB/MI Stack Manipulation
2556 @section @sc{gdb/mi} Stack Manipulation Commands
2559 @subheading The @code{-stack-info-frame} Command
2560 @findex -stack-info-frame
2562 @subsubheading Synopsis
2568 Get info on the current frame.
2570 @subsubheading @value{GDBN} Command
2572 The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
2573 (without arguments).
2575 @subsubheading Example
2578 @subheading The @code{-stack-info-depth} Command
2579 @findex -stack-info-depth
2581 @subsubheading Synopsis
2584 -stack-info-depth [ @var{max-depth} ]
2587 Return the depth of the stack. If the integer argument @var{max-depth}
2588 is specified, do not count beyond @var{max-depth} frames.
2590 @subsubheading @value{GDBN} Command
2592 There's no equivalent @value{GDBN} command.
2594 @subsubheading Example
2596 For a stack with frame levels 0 through 11:
2606 -stack-info-depth 12
2609 -stack-info-depth 11
2612 -stack-info-depth 13
2617 @subheading The @code{-stack-list-arguments} Command
2618 @findex -stack-list-arguments
2620 @subsubheading Synopsis
2623 -stack-list-arguments @var{show-values}
2624 [ @var{low-frame} @var{high-frame} ]
2627 Display a list of the arguments for the frames between @var{low-frame}
2628 and @var{high-frame} (inclusive). If @var{low-frame} and
2629 @var{high-frame} are not provided, list the arguments for the whole call
2632 The @var{show-values} argument must have a value of 0 or 1. A value of
2633 0 means that only the names of the arguments are listed, a value of 1
2634 means that both names and values of the arguments are printed.
2636 @subsubheading @value{GDBN} Command
2638 @value{GDBN} does not have an equivalent command. @code{gdbtk} has a
2639 @samp{gdb_get_args} command which partially overlaps with the
2640 functionality of @samp{-stack-list-arguments}.
2642 @subsubheading Example
2649 frame=@{level="0 ",addr="0x00010734",func="callee4",
2650 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
2651 frame=@{level="1 ",addr="0x0001076c",func="callee3",
2652 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
2653 frame=@{level="2 ",addr="0x0001078c",func="callee2",
2654 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
2655 frame=@{level="3 ",addr="0x000107b4",func="callee1",
2656 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
2657 frame=@{level="4 ",addr="0x000107e0",func="main",
2658 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
2660 -stack-list-arguments 0
2663 frame=@{level="0",args=[]@},
2664 frame=@{level="1",args=[name="strarg"]@},
2665 frame=@{level="2",args=[name="intarg",name="strarg"]@},
2666 frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@},
2667 frame=@{level="4",args=[]@}]
2669 -stack-list-arguments 1
2672 frame=@{level="0",args=[]@},
2674 args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
2675 frame=@{level="2",args=[
2676 @{name="intarg",value="2"@},
2677 @{name="strarg",value="0x11940 \"A string argument.\""@}]@},
2678 @{frame=@{level="3",args=[
2679 @{name="intarg",value="2"@},
2680 @{name="strarg",value="0x11940 \"A string argument.\""@},
2681 @{name="fltarg",value="3.5"@}]@},
2682 frame=@{level="4",args=[]@}]
2684 -stack-list-arguments 0 2 2
2685 ^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}]
2687 -stack-list-arguments 1 2 2
2688 ^done,stack-args=[frame=@{level="2",
2689 args=[@{name="intarg",value="2"@},
2690 @{name="strarg",value="0x11940 \"A string argument.\""@}]@}]
2694 @c @subheading -stack-list-exception-handlers
2697 @subheading The @code{-stack-list-frames} Command
2698 @findex -stack-list-frames
2700 @subsubheading Synopsis
2703 -stack-list-frames [ @var{low-frame} @var{high-frame} ]
2706 List the frames currently on the stack. For each frame it displays the
2711 The frame number, 0 being the topmost frame, i.e. the innermost function.
2713 The @code{$pc} value for that frame.
2717 File name of the source file where the function lives.
2719 Line number corresponding to the @code{$pc}.
2722 If invoked without arguments, this command prints a backtrace for the
2723 whole stack. If given two integer arguments, it shows the frames whose
2724 levels are between the two arguments (inclusive). If the two arguments
2725 are equal, it shows the single frame at the corresponding level.
2727 @subsubheading @value{GDBN} Command
2729 The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
2731 @subsubheading Example
2733 Full stack backtrace:
2739 [frame=@{level="0 ",addr="0x0001076c",func="foo",
2740 file="recursive2.c",line="11"@},
2741 frame=@{level="1 ",addr="0x000107a4",func="foo",
2742 file="recursive2.c",line="14"@},
2743 frame=@{level="2 ",addr="0x000107a4",func="foo",
2744 file="recursive2.c",line="14"@},
2745 frame=@{level="3 ",addr="0x000107a4",func="foo",
2746 file="recursive2.c",line="14"@},
2747 frame=@{level="4 ",addr="0x000107a4",func="foo",
2748 file="recursive2.c",line="14"@},
2749 frame=@{level="5 ",addr="0x000107a4",func="foo",
2750 file="recursive2.c",line="14"@},
2751 frame=@{level="6 ",addr="0x000107a4",func="foo",
2752 file="recursive2.c",line="14"@},
2753 frame=@{level="7 ",addr="0x000107a4",func="foo",
2754 file="recursive2.c",line="14"@},
2755 frame=@{level="8 ",addr="0x000107a4",func="foo",
2756 file="recursive2.c",line="14"@},
2757 frame=@{level="9 ",addr="0x000107a4",func="foo",
2758 file="recursive2.c",line="14"@},
2759 frame=@{level="10",addr="0x000107a4",func="foo",
2760 file="recursive2.c",line="14"@},
2761 frame=@{level="11",addr="0x00010738",func="main",
2762 file="recursive2.c",line="4"@}]
2766 Show frames between @var{low_frame} and @var{high_frame}:
2770 -stack-list-frames 3 5
2772 [frame=@{level="3 ",addr="0x000107a4",func="foo",
2773 file="recursive2.c",line="14"@},
2774 frame=@{level="4 ",addr="0x000107a4",func="foo",
2775 file="recursive2.c",line="14"@},
2776 frame=@{level="5 ",addr="0x000107a4",func="foo",
2777 file="recursive2.c",line="14"@}]
2781 Show a single frame:
2785 -stack-list-frames 3 3
2787 [frame=@{level="3 ",addr="0x000107a4",func="foo",
2788 file="recursive2.c",line="14"@}]
2793 @subheading The @code{-stack-list-locals} Command
2794 @findex -stack-list-locals
2796 @subsubheading Synopsis
2799 -stack-list-locals @var{print-values}
2802 Display the local variable names for the current frame. With an
2803 argument of 0 prints only the names of the variables, with argument of 1
2804 prints also their values.
2806 @subsubheading @value{GDBN} Command
2808 @samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
2810 @subsubheading Example
2814 -stack-list-locals 0
2815 ^done,locals=[name="A",name="B",name="C"]
2817 -stack-list-locals 1
2818 ^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
2819 @{name="C",value="3"@}]
2824 @subheading The @code{-stack-select-frame} Command
2825 @findex -stack-select-frame
2827 @subsubheading Synopsis
2830 -stack-select-frame @var{framenum}
2833 Change the current frame. Select a different frame @var{framenum} on
2836 @subsubheading @value{GDBN} Command
2838 The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
2839 @samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
2841 @subsubheading Example
2845 -stack-select-frame 2
2850 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2851 @node GDB/MI Symbol Query
2852 @section @sc{gdb/mi} Symbol Query Commands
2855 @subheading The @code{-symbol-info-address} Command
2856 @findex -symbol-info-address
2858 @subsubheading Synopsis
2861 -symbol-info-address @var{symbol}
2864 Describe where @var{symbol} is stored.
2866 @subsubheading @value{GDBN} Command
2868 The corresponding @value{GDBN} command is @samp{info address}.
2870 @subsubheading Example
2874 @subheading The @code{-symbol-info-file} Command
2875 @findex -symbol-info-file
2877 @subsubheading Synopsis
2883 Show the file for the symbol.
2885 @subsubheading @value{GDBN} Command
2887 There's no equivalent @value{GDBN} command. @code{gdbtk} has
2888 @samp{gdb_find_file}.
2890 @subsubheading Example
2894 @subheading The @code{-symbol-info-function} Command
2895 @findex -symbol-info-function
2897 @subsubheading Synopsis
2900 -symbol-info-function
2903 Show which function the symbol lives in.
2905 @subsubheading @value{GDBN} Command
2907 @samp{gdb_get_function} in @code{gdbtk}.
2909 @subsubheading Example
2913 @subheading The @code{-symbol-info-line} Command
2914 @findex -symbol-info-line
2916 @subsubheading Synopsis
2922 Show the core addresses of the code for a source line.
2924 @subsubheading @value{GDBN} Command
2926 The corresponding @value{GDBN} comamnd is @samp{info line}.
2927 @code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
2929 @subsubheading Example
2933 @subheading The @code{-symbol-info-symbol} Command
2934 @findex -symbol-info-symbol
2936 @subsubheading Synopsis
2939 -symbol-info-symbol @var{addr}
2942 Describe what symbol is at location @var{addr}.
2944 @subsubheading @value{GDBN} Command
2946 The corresponding @value{GDBN} command is @samp{info symbol}.
2948 @subsubheading Example
2952 @subheading The @code{-symbol-list-functions} Command
2953 @findex -symbol-list-functions
2955 @subsubheading Synopsis
2958 -symbol-list-functions
2961 List the functions in the executable.
2963 @subsubheading @value{GDBN} Command
2965 @samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
2966 @samp{gdb_search} in @code{gdbtk}.
2968 @subsubheading Example
2972 @subheading The @code{-symbol-list-types} Command
2973 @findex -symbol-list-types
2975 @subsubheading Synopsis
2981 List all the type names.
2983 @subsubheading @value{GDBN} Command
2985 The corresponding commands are @samp{info types} in @value{GDBN},
2986 @samp{gdb_search} in @code{gdbtk}.
2988 @subsubheading Example
2992 @subheading The @code{-symbol-list-variables} Command
2993 @findex -symbol-list-variables
2995 @subsubheading Synopsis
2998 -symbol-list-variables
3001 List all the global and static variable names.
3003 @subsubheading @value{GDBN} Command
3005 @samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
3007 @subsubheading Example
3011 @subheading The @code{-symbol-locate} Command
3012 @findex -symbol-locate
3014 @subsubheading Synopsis
3020 @subsubheading @value{GDBN} Command
3022 @samp{gdb_loc} in @code{gdbtk}.
3024 @subsubheading Example
3028 @subheading The @code{-symbol-type} Command
3029 @findex -symbol-type
3031 @subsubheading Synopsis
3034 -symbol-type @var{variable}
3037 Show type of @var{variable}.
3039 @subsubheading @value{GDBN} Command
3041 The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
3042 @samp{gdb_obj_variable}.
3044 @subsubheading Example
3048 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3049 @node GDB/MI Target Manipulation
3050 @section @sc{gdb/mi} Target Manipulation Commands
3053 @subheading The @code{-target-attach} Command
3054 @findex -target-attach
3056 @subsubheading Synopsis
3059 -target-attach @var{pid} | @var{file}
3062 Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
3064 @subsubheading @value{GDBN} command
3066 The corresponding @value{GDBN} command is @samp{attach}.
3068 @subsubheading Example
3072 @subheading The @code{-target-compare-sections} Command
3073 @findex -target-compare-sections
3075 @subsubheading Synopsis
3078 -target-compare-sections [ @var{section} ]
3081 Compare data of section @var{section} on target to the exec file.
3082 Without the argument, all sections are compared.
3084 @subsubheading @value{GDBN} Command
3086 The @value{GDBN} equivalent is @samp{compare-sections}.
3088 @subsubheading Example
3092 @subheading The @code{-target-detach} Command
3093 @findex -target-detach
3095 @subsubheading Synopsis
3101 Disconnect from the remote target. There's no output.
3103 @subsubheading @value{GDBN} command
3105 The corresponding @value{GDBN} command is @samp{detach}.
3107 @subsubheading Example
3117 @subheading The @code{-target-download} Command
3118 @findex -target-download
3120 @subsubheading Synopsis
3126 Loads the executable onto the remote target.
3127 It prints out an update message every half second, which includes the fields:
3131 The name of the section.
3133 The size of what has been sent so far for that section.
3135 The size of the section.
3137 The total size of what was sent so far (the current and the previous sections).
3139 The size of the overall executable to download.
3143 Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
3144 @sc{gdb/mi} Output Syntax}).
3146 In addition, it prints the name and size of the sections, as they are
3147 downloaded. These messages include the following fields:
3151 The name of the section.
3153 The size of the section.
3155 The size of the overall executable to download.
3159 At the end, a summary is printed.
3161 @subsubheading @value{GDBN} Command
3163 The corresponding @value{GDBN} command is @samp{load}.
3165 @subsubheading Example
3167 Note: each status message appears on a single line. Here the messages
3168 have been broken down so that they can fit onto a page.
3173 +download,@{section=".text",section-size="6668",total-size="9880"@}
3174 +download,@{section=".text",section-sent="512",section-size="6668",
3175 total-sent="512",total-size="9880"@}
3176 +download,@{section=".text",section-sent="1024",section-size="6668",
3177 total-sent="1024",total-size="9880"@}
3178 +download,@{section=".text",section-sent="1536",section-size="6668",
3179 total-sent="1536",total-size="9880"@}
3180 +download,@{section=".text",section-sent="2048",section-size="6668",
3181 total-sent="2048",total-size="9880"@}
3182 +download,@{section=".text",section-sent="2560",section-size="6668",
3183 total-sent="2560",total-size="9880"@}
3184 +download,@{section=".text",section-sent="3072",section-size="6668",
3185 total-sent="3072",total-size="9880"@}
3186 +download,@{section=".text",section-sent="3584",section-size="6668",
3187 total-sent="3584",total-size="9880"@}
3188 +download,@{section=".text",section-sent="4096",section-size="6668",
3189 total-sent="4096",total-size="9880"@}
3190 +download,@{section=".text",section-sent="4608",section-size="6668",
3191 total-sent="4608",total-size="9880"@}
3192 +download,@{section=".text",section-sent="5120",section-size="6668",
3193 total-sent="5120",total-size="9880"@}
3194 +download,@{section=".text",section-sent="5632",section-size="6668",
3195 total-sent="5632",total-size="9880"@}
3196 +download,@{section=".text",section-sent="6144",section-size="6668",
3197 total-sent="6144",total-size="9880"@}
3198 +download,@{section=".text",section-sent="6656",section-size="6668",
3199 total-sent="6656",total-size="9880"@}
3200 +download,@{section=".init",section-size="28",total-size="9880"@}
3201 +download,@{section=".fini",section-size="28",total-size="9880"@}
3202 +download,@{section=".data",section-size="3156",total-size="9880"@}
3203 +download,@{section=".data",section-sent="512",section-size="3156",
3204 total-sent="7236",total-size="9880"@}
3205 +download,@{section=".data",section-sent="1024",section-size="3156",
3206 total-sent="7748",total-size="9880"@}
3207 +download,@{section=".data",section-sent="1536",section-size="3156",
3208 total-sent="8260",total-size="9880"@}
3209 +download,@{section=".data",section-sent="2048",section-size="3156",
3210 total-sent="8772",total-size="9880"@}
3211 +download,@{section=".data",section-sent="2560",section-size="3156",
3212 total-sent="9284",total-size="9880"@}
3213 +download,@{section=".data",section-sent="3072",section-size="3156",
3214 total-sent="9796",total-size="9880"@}
3215 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
3221 @subheading The @code{-target-exec-status} Command
3222 @findex -target-exec-status
3224 @subsubheading Synopsis
3230 Provide information on the state of the target (whether it is running or
3233 @subsubheading @value{GDBN} Command
3235 There's no equivalent @value{GDBN} command.
3237 @subsubheading Example
3241 @subheading The @code{-target-list-available-targets} Command
3242 @findex -target-list-available-targets
3244 @subsubheading Synopsis
3247 -target-list-available-targets
3250 List the possible targets to connect to.
3252 @subsubheading @value{GDBN} Command
3254 The corresponding @value{GDBN} command is @samp{help target}.
3256 @subsubheading Example
3260 @subheading The @code{-target-list-current-targets} Command
3261 @findex -target-list-current-targets
3263 @subsubheading Synopsis
3266 -target-list-current-targets
3269 Describe the current target.
3271 @subsubheading @value{GDBN} Command
3273 The corresponding information is printed by @samp{info file} (among
3276 @subsubheading Example
3280 @subheading The @code{-target-list-parameters} Command
3281 @findex -target-list-parameters
3283 @subsubheading Synopsis
3286 -target-list-parameters
3291 @subsubheading @value{GDBN} Command
3295 @subsubheading Example
3299 @subheading The @code{-target-select} Command
3300 @findex -target-select
3302 @subsubheading Synopsis
3305 -target-select @var{type} @var{parameters @dots{}}
3308 Connect @value{GDBN} to the remote target. This command takes two args:
3312 The type of target, for instance @samp{async}, @samp{remote}, etc.
3313 @item @var{parameters}
3314 Device names, host names and the like. @xref{Target Commands, ,
3315 Commands for managing targets}, for more details.
3318 The output is a connection notification, followed by the address at
3319 which the target program is, in the following form:
3322 ^connected,addr="@var{address}",func="@var{function name}",
3323 args=[@var{arg list}]
3326 @subsubheading @value{GDBN} Command
3328 The corresponding @value{GDBN} command is @samp{target}.
3330 @subsubheading Example
3334 -target-select async /dev/ttya
3335 ^connected,addr="0xfe00a300",func="??",args=[]
3339 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3340 @node GDB/MI Thread Commands
3341 @section @sc{gdb/mi} Thread Commands
3344 @subheading The @code{-thread-info} Command
3345 @findex -thread-info
3347 @subsubheading Synopsis
3353 @subsubheading @value{GDBN} command
3357 @subsubheading Example
3361 @subheading The @code{-thread-list-all-threads} Command
3362 @findex -thread-list-all-threads
3364 @subsubheading Synopsis
3367 -thread-list-all-threads
3370 @subsubheading @value{GDBN} Command
3372 The equivalent @value{GDBN} command is @samp{info threads}.
3374 @subsubheading Example
3378 @subheading The @code{-thread-list-ids} Command
3379 @findex -thread-list-ids
3381 @subsubheading Synopsis
3387 Produces a list of the currently known @value{GDBN} thread ids. At the
3388 end of the list it also prints the total number of such threads.
3390 @subsubheading @value{GDBN} Command
3392 Part of @samp{info threads} supplies the same information.
3394 @subsubheading Example
3396 No threads present, besides the main process:
3401 ^done,thread-ids=@{@},number-of-threads="0"
3411 ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3412 number-of-threads="3"
3417 @subheading The @code{-thread-select} Command
3418 @findex -thread-select
3420 @subsubheading Synopsis
3423 -thread-select @var{threadnum}
3426 Make @var{threadnum} the current thread. It prints the number of the new
3427 current thread, and the topmost frame for that thread.
3429 @subsubheading @value{GDBN} Command
3431 The corresponding @value{GDBN} command is @samp{thread}.
3433 @subsubheading Example
3440 *stopped,reason="end-stepping-range",thread-id="2",line="187",
3441 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
3445 thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
3446 number-of-threads="3"
3449 ^done,new-thread-id="3",
3450 frame=@{level="0 ",func="vprintf",
3451 args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
3452 @{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
3456 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3457 @node GDB/MI Tracepoint Commands
3458 @section @sc{gdb/mi} Tracepoint Commands
3460 The tracepoint commands are not yet implemented.
3462 @c @subheading -trace-actions
3464 @c @subheading -trace-delete
3466 @c @subheading -trace-disable
3468 @c @subheading -trace-dump
3470 @c @subheading -trace-enable
3472 @c @subheading -trace-exists
3474 @c @subheading -trace-find
3476 @c @subheading -trace-frame-number
3478 @c @subheading -trace-info
3480 @c @subheading -trace-insert
3482 @c @subheading -trace-list
3484 @c @subheading -trace-pass-count
3486 @c @subheading -trace-save
3488 @c @subheading -trace-start
3490 @c @subheading -trace-stop
3493 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3494 @node GDB/MI Variable Objects
3495 @section @sc{gdb/mi} Variable Objects
3498 @subheading Motivation for Variable Objects in @sc{gdb/mi}
3500 For the implementation of a variable debugger window (locals, watched
3501 expressions, etc.), we are proposing the adaptation of the existing code
3502 used by @code{Insight}.
3504 The two main reasons for that are:
3508 It has been proven in practice (it is already on its second generation).
3511 It will shorten development time (needless to say how important it is
3515 The original interface was designed to be used by Tcl code, so it was
3516 slightly changed so it could be used through @sc{gdb/mi}. This section
3517 describes the @sc{gdb/mi} operations that will be available and gives some
3518 hints about their use.
3520 @emph{Note}: In addition to the set of operations described here, we
3521 expect the @sc{gui} implementation of a variable window to require, at
3522 least, the following operations:
3525 @item @code{-gdb-show} @code{output-radix}
3526 @item @code{-stack-list-arguments}
3527 @item @code{-stack-list-locals}
3528 @item @code{-stack-select-frame}
3531 @subheading Introduction to Variable Objects in @sc{gdb/mi}
3533 @cindex variable objects in @sc{gdb/mi}
3534 The basic idea behind variable objects is the creation of a named object
3535 to represent a variable, an expression, a memory location or even a CPU
3536 register. For each object created, a set of operations is available for
3537 examining or changing its properties.
3539 Furthermore, complex data types, such as C structures, are represented
3540 in a tree format. For instance, the @code{struct} type variable is the
3541 root and the children will represent the struct members. If a child
3542 is itself of a complex type, it will also have children of its own.
3543 Appropriate language differences are handled for C, C@t{++} and Java.
3545 When returning the actual values of the objects, this facility allows
3546 for the individual selection of the display format used in the result
3547 creation. It can be chosen among: binary, decimal, hexadecimal, octal
3548 and natural. Natural refers to a default format automatically
3549 chosen based on the variable type (like decimal for an @code{int}, hex
3550 for pointers, etc.).
3552 The following is the complete set of @sc{gdb/mi} operations defined to
3553 access this functionality:
3555 @multitable @columnfractions .4 .6
3556 @item @strong{Operation}
3557 @tab @strong{Description}
3559 @item @code{-var-create}
3560 @tab create a variable object
3561 @item @code{-var-delete}
3562 @tab delete the variable object and its children
3563 @item @code{-var-set-format}
3564 @tab set the display format of this variable
3565 @item @code{-var-show-format}
3566 @tab show the display format of this variable
3567 @item @code{-var-info-num-children}
3568 @tab tells how many children this object has
3569 @item @code{-var-list-children}
3570 @tab return a list of the object's children
3571 @item @code{-var-info-type}
3572 @tab show the type of this variable object
3573 @item @code{-var-info-expression}
3574 @tab print what this variable object represents
3575 @item @code{-var-show-attributes}
3576 @tab is this variable editable? does it exist here?
3577 @item @code{-var-evaluate-expression}
3578 @tab get the value of this variable
3579 @item @code{-var-assign}
3580 @tab set the value of this variable
3581 @item @code{-var-update}
3582 @tab update the variable and its children
3585 In the next subsection we describe each operation in detail and suggest
3588 @subheading Description And Use of Operations on Variable Objects
3590 @subheading The @code{-var-create} Command
3593 @subsubheading Synopsis
3596 -var-create @{@var{name} | "-"@}
3597 @{@var{frame-addr} | "*"@} @var{expression}
3600 This operation creates a variable object, which allows the monitoring of
3601 a variable, the result of an expression, a memory cell or a CPU
3604 The @var{name} parameter is the string by which the object can be
3605 referenced. It must be unique. If @samp{-} is specified, the varobj
3606 system will generate a string ``varNNNNNN'' automatically. It will be
3607 unique provided that one does not specify @var{name} on that format.
3608 The command fails if a duplicate name is found.
3610 The frame under which the expression should be evaluated can be
3611 specified by @var{frame-addr}. A @samp{*} indicates that the current
3612 frame should be used.
3614 @var{expression} is any expression valid on the current language set (must not
3615 begin with a @samp{*}), or one of the following:
3619 @samp{*@var{addr}}, where @var{addr} is the address of a memory cell
3622 @samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
3625 @samp{$@var{regname}} --- a CPU register name
3628 @subsubheading Result
3630 This operation returns the name, number of children and the type of the
3631 object created. Type is returned as a string as the ones generated by
3632 the @value{GDBN} CLI:
3635 name="@var{name}",numchild="N",type="@var{type}"
3639 @subheading The @code{-var-delete} Command
3642 @subsubheading Synopsis
3645 -var-delete @var{name}
3648 Deletes a previously created variable object and all of its children.
3650 Returns an error if the object @var{name} is not found.
3653 @subheading The @code{-var-set-format} Command
3654 @findex -var-set-format
3656 @subsubheading Synopsis
3659 -var-set-format @var{name} @var{format-spec}
3662 Sets the output format for the value of the object @var{name} to be
3665 The syntax for the @var{format-spec} is as follows:
3668 @var{format-spec} @expansion{}
3669 @{binary | decimal | hexadecimal | octal | natural@}
3673 @subheading The @code{-var-show-format} Command
3674 @findex -var-show-format
3676 @subsubheading Synopsis
3679 -var-show-format @var{name}
3682 Returns the format used to display the value of the object @var{name}.
3685 @var{format} @expansion{}
3690 @subheading The @code{-var-info-num-children} Command
3691 @findex -var-info-num-children
3693 @subsubheading Synopsis
3696 -var-info-num-children @var{name}
3699 Returns the number of children of a variable object @var{name}:
3706 @subheading The @code{-var-list-children} Command
3707 @findex -var-list-children
3709 @subsubheading Synopsis
3712 -var-list-children @var{name}
3715 Returns a list of the children of the specified variable object:
3718 numchild=@var{n},children=@{@{name=@var{name},
3719 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}@}
3723 @subheading The @code{-var-info-type} Command
3724 @findex -var-info-type
3726 @subsubheading Synopsis
3729 -var-info-type @var{name}
3732 Returns the type of the specified variable @var{name}. The type is
3733 returned as a string in the same format as it is output by the
3741 @subheading The @code{-var-info-expression} Command
3742 @findex -var-info-expression
3744 @subsubheading Synopsis
3747 -var-info-expression @var{name}
3750 Returns what is represented by the variable object @var{name}:
3753 lang=@var{lang-spec},exp=@var{expression}
3757 where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
3759 @subheading The @code{-var-show-attributes} Command
3760 @findex -var-show-attributes
3762 @subsubheading Synopsis
3765 -var-show-attributes @var{name}
3768 List attributes of the specified variable object @var{name}:
3771 status=@var{attr} [ ( ,@var{attr} )* ]
3775 where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
3777 @subheading The @code{-var-evaluate-expression} Command
3778 @findex -var-evaluate-expression
3780 @subsubheading Synopsis
3783 -var-evaluate-expression @var{name}
3786 Evaluates the expression that is represented by the specified variable
3787 object and returns its value as a string in the current format specified
3794 @subheading The @code{-var-assign} Command
3797 @subsubheading Synopsis
3800 -var-assign @var{name} @var{expression}
3803 Assigns the value of @var{expression} to the variable object specified
3804 by @var{name}. The object must be @samp{editable}.
3806 @subheading The @code{-var-update} Command
3809 @subsubheading Synopsis
3812 -var-update @{@var{name} | "*"@}
3815 Update the value of the variable object @var{name} by evaluating its
3816 expression after fetching all the new values from memory or registers.
3817 A @samp{*} causes all existing variable objects to be updated.
3820 @c change-log-default-name: "ChangeLog-mi"