diff options
Diffstat (limited to 'gdb/mi/gdbmi.texinfo')
| -rw-r--r-- | gdb/mi/gdbmi.texinfo | 3902 |
1 files changed, 0 insertions, 3902 deletions
diff --git a/gdb/mi/gdbmi.texinfo b/gdb/mi/gdbmi.texinfo deleted file mode 100644 index da8b77c..0000000 --- a/gdb/mi/gdbmi.texinfo +++ /dev/null @@ -1,3902 +0,0 @@ -@c \input texinfo @c -*-texinfo-*- -@c @c %**start of header -@c @setfilename gdbmi.info -@c @settitle GDB/MI Machine Interface -@c @setchapternewpage off -@c @c %**end of header - -@c @ifinfo -@c This file documents GDB/MI, a Machine Interface to GDB. - -@c Copyright 2000, 2001, 2002 Free Software Foundation, Inc. -@c Contributed by Cygnus Solutions. - -@c Permission is granted to copy, distribute and/or modify this document -@c under the terms of the GNU Free Documentation License, Version 1.1 or -@c any later version published by the Free Software Foundation; with no -@c Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -@c and with the Back-Cover Texts as in (a) below. - -@c (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify -@c this GNU Manual, like GNU software. Copies published by the Free -@c Software Foundation raise funds for GNU development.'' -@c @end ifinfo - -@c @c This title page illustrates only one of the -@c @c two methods of forming a title page. - -@c @titlepage -@c @title GDB/MI -@c @subtitle Version 0.3 -@c @subtitle Apr 2001 -@c @author Andrew Cagney, Fernando Nasser and Elena Zannoni - -@c @c The following two commands -@c @c start the copyright page. -@c @page -@c @vskip 0pt plus 1filll - -@c Copyright @copyright{} 2000, 2001, 2002 Free Software Foundation, Inc. - -@c Permission is granted to copy, distribute and/or modify this document -@c under the terms of the GNU Free Documentation License, Version 1.1 or -@c any later version published by the Free Software Foundation; with no -@c Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -@c and with the Back-Cover Texts as in (a) below. - -@c (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify -@c this GNU Manual, like GNU software. Copies published by the Free -@c Software Foundation raise funds for GNU development.'' -@c @end titlepage - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI -@chapter The @sc{gdb/mi} Interface - -@unnumberedsec Function and Purpose - -@cindex @sc{gdb/mi}, its purpose -@sc{gdb/mi} is a line based machine oriented text interface to @value{GDBN}. It is -specifically intended to support the development of systems which use -the debugger as just one small component of a larger system. - -This chapter is a specification of the @sc{gdb/mi} interface. It is written -in the form of a reference manual. - -Note that @sc{gdb/mi} is still under construction, so some of the -features described below are incomplete and subject to change. - -@unnumberedsec Notation and Terminology - -@cindex notational conventions, for @sc{gdb/mi} -This chapter uses the following notation: - -@itemize @bullet -@item -@code{|} separates two alternatives. - -@item -@code{[ @var{something} ]} indicates that @var{something} is optional: -it may or may not be given. - -@item -@code{( @var{group} )*} means that @var{group} inside the parentheses -may repeat zero or more times. - -@item -@code{( @var{group} )+} means that @var{group} inside the parentheses -may repeat one or more times. - -@item -@code{"@var{string}"} means a literal @var{string}. -@end itemize - -@ignore -@heading Dependencies -@end ignore - -@heading Acknowledgments - -In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and -Elena Zannoni. - -@menu -* GDB/MI Command Syntax:: -* GDB/MI Compatibility with CLI:: -* GDB/MI Output Records:: -* GDB/MI Command Description Format:: -* GDB/MI Breakpoint Table Commands:: -* GDB/MI Data Manipulation:: -* GDB/MI Program Control:: -* GDB/MI Miscellaneous Commands:: -@ignore -* GDB/MI Kod Commands:: -* GDB/MI Memory Overlay Commands:: -* GDB/MI Signal Handling Commands:: -@end ignore -* GDB/MI Stack Manipulation:: -* GDB/MI Symbol Query:: -* GDB/MI Target Manipulation:: -* GDB/MI Thread Commands:: -* GDB/MI Tracepoint Commands:: -* GDB/MI Variable Objects:: -@end menu - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Command Syntax -@section @sc{gdb/mi} Command Syntax - -@menu -* GDB/MI Input Syntax:: -* GDB/MI Output Syntax:: -* GDB/MI Simple Examples:: -@end menu - -@node GDB/MI Input Syntax -@subsection @sc{gdb/mi} Input Syntax - -@cindex input syntax for @sc{gdb/mi} -@cindex @sc{gdb/mi}, input syntax -@table @code -@item @var{command} @expansion{} -@code{@var{cli-command} | @var{mi-command}} - -@item @var{cli-command} @expansion{} -@code{[ @var{token} ] @var{cli-command} @var{nl}}, where -@var{cli-command} is any existing @value{GDBN} CLI command. - -@item @var{mi-command} @expansion{} -@code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )* -@code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}} - -@item @var{token} @expansion{} -"any sequence of digits" - -@item @var{option} @expansion{} -@code{"-" @var{parameter} [ " " @var{parameter} ]} - -@item @var{parameter} @expansion{} -@code{@var{non-blank-sequence} | @var{c-string}} - -@item @var{operation} @expansion{} -@emph{any of the operations described in this chapter} - -@item @var{non-blank-sequence} @expansion{} -@emph{anything, provided it doesn't contain special characters such as -"-", @var{nl}, """ and of course " "} - -@item @var{c-string} @expansion{} -@code{""" @var{seven-bit-iso-c-string-content} """} - -@item @var{nl} @expansion{} -@code{CR | CR-LF} -@end table - -@noindent -Notes: - -@itemize @bullet -@item -The CLI commands are still handled by the @sc{mi} interpreter; their -output is described below. - -@item -The @code{@var{token}}, when present, is passed back when the command -finishes. - -@item -Some @sc{mi} commands accept optional arguments as part of the parameter -list. Each option is identified by a leading @samp{-} (dash) and may be -followed by an optional argument parameter. Options occur first in the -parameter list and can be delimited from normal parameters using -@samp{--} (this is useful when some parameters begin with a dash). -@end itemize - -Pragmatics: - -@itemize @bullet -@item -We want easy access to the existing CLI syntax (for debugging). - -@item -We want it to be easy to spot a @sc{mi} operation. -@end itemize - -@node GDB/MI Output Syntax -@subsection @sc{gdb/mi} Output Syntax - -@cindex output syntax of @sc{gdb/mi} -@cindex @sc{gdb/mi}, output syntax -The output from @sc{gdb/mi} consists of zero or more out-of-band records -followed, optionally, by a single result record. This result record -is for the most recent command. The sequence of output records is -terminated by @samp{(@value{GDBP})}. - -If an input command was prefixed with a @code{@var{token}} then the -corresponding output for that command will also be prefixed by that same -@var{token}. - -@table @code -@item @var{output} @expansion{} -@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}} - -@item @var{result-record} @expansion{} -@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}} - -@item @var{out-of-band-record} @expansion{} -@code{@var{async-record} | @var{stream-record}} - -@item @var{async-record} @expansion{} -@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}} - -@item @var{exec-async-output} @expansion{} -@code{[ @var{token} ] "*" @var{async-output}} - -@item @var{status-async-output} @expansion{} -@code{[ @var{token} ] "+" @var{async-output}} - -@item @var{notify-async-output} @expansion{} -@code{[ @var{token} ] "=" @var{async-output}} - -@item @var{async-output} @expansion{} -@code{@var{async-class} ( "," @var{result} )* @var{nl}} - -@item @var{result-class} @expansion{} -@code{"done" | "running" | "connected" | "error" | "exit"} - -@item @var{async-class} @expansion{} -@code{"stopped" | @var{others}} (where @var{others} will be added -depending on the needs---this is still in development). - -@item @var{result} @expansion{} -@code{ @var{variable} "=" @var{value}} - -@item @var{variable} @expansion{} -@code{ @var{string} } - -@item @var{value} @expansion{} -@code{ @var{const} | @var{tuple} | @var{list} } - -@item @var{const} @expansion{} -@code{@var{c-string}} - -@item @var{tuple} @expansion{} -@code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" } - -@item @var{list} @expansion{} -@code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "[" -@var{result} ( "," @var{result} )* "]" } - -@item @var{stream-record} @expansion{} -@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}} - -@item @var{console-stream-output} @expansion{} -@code{"~" @var{c-string}} - -@item @var{target-stream-output} @expansion{} -@code{"@@" @var{c-string}} - -@item @var{log-stream-output} @expansion{} -@code{"&" @var{c-string}} - -@item @var{nl} @expansion{} -@code{CR | CR-LF} - -@item @var{token} @expansion{} -@emph{any sequence of digits}. -@end table - -@noindent -Notes: - -@itemize @bullet -@item -All output sequences end in a single line containing a period. - -@item -The @code{@var{token}} is from the corresponding request. If an execution -command is interrupted by the @samp{-exec-interrupt} command, the -@var{token} associated with the @samp{*stopped} message is the one of the -original execution command, not the one of the interrupt command. - -@item -@cindex status output in @sc{gdb/mi} -@var{status-async-output} contains on-going status information about the -progress of a slow operation. It can be discarded. All status output is -prefixed by @samp{+}. - -@item -@cindex async output in @sc{gdb/mi} -@var{exec-async-output} contains asynchronous state change on the target -(stopped, started, disappeared). All async output is prefixed by -@samp{*}. - -@item -@cindex notify output in @sc{gdb/mi} -@var{notify-async-output} contains supplementary information that the -client should handle (e.g., a new breakpoint information). All notify -output is prefixed by @samp{=}. - -@item -@cindex console output in @sc{gdb/mi} -@var{console-stream-output} is output that should be displayed as is in the -console. It is the textual response to a CLI command. All the console -output is prefixed by @samp{~}. - -@item -@cindex target output in @sc{gdb/mi} -@var{target-stream-output} is the output produced by the target program. -All the target output is prefixed by @samp{@@}. - -@item -@cindex log output in @sc{gdb/mi} -@var{log-stream-output} is output text coming from @value{GDBN}'s internals, for -instance messages that should be displayed as part of an error log. All -the log output is prefixed by @samp{&}. - -@item -@cindex list output in @sc{gdb/mi} -New @sc{gdb/mi} commands should only output @var{lists} containing -@var{values}. - - -@end itemize - -@xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more -details about the various output records. - -@node GDB/MI Simple Examples -@subsection Simple Examples of @sc{gdb/mi} Interaction -@cindex @sc{gdb/mi}, simple examples - -This subsection presents several simple examples of interaction using -the @sc{gdb/mi} interface. In these examples, @samp{->} means that the -following line is passed to @sc{gdb/mi} as input, while @samp{<-} means -the output received from @sc{gdb/mi}. - -@subsubheading Target Stop -@c Ummm... There is no "-stop" command. This assumes async, no? -Here's an example of stopping the inferior process: - -@example --> -stop -<- (@value{GDBP}) -@end example - -@noindent -and later: - -@example -<- *stop,reason="stop",address="0x123",source="a.c:123" -<- (@value{GDBP}) -@end example - -@subsubheading Simple CLI Command - -Here's an example of a simple CLI command being passed through -@sc{gdb/mi} and on to the CLI. - -@example --> print 1+2 -<- &"print 1+2\n" -<- ~"$1 = 3\n" -<- ^done -<- (@value{GDBP}) -@end example - -@subsubheading Command With Side Effects - -@example --> -symbol-file xyz.exe -<- *breakpoint,nr="3",address="0x123",source="a.c:123" -<- (@value{GDBP}) -@end example - -@subsubheading A Bad Command - -Here's what happens if you pass a non-existent command: - -@example --> -rubbish -<- ^error,msg="Undefined MI command: rubbish" -<- (@value{GDBP}) -@end example - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Compatibility with CLI -@section @sc{gdb/mi} Compatibility with CLI - -@cindex compatibility, @sc{gdb/mi} and CLI -@cindex @sc{gdb/mi}, compatibility with CLI -To help users familiar with @value{GDBN}'s existing CLI interface, @sc{gdb/mi} -accepts existing CLI commands. As specified by the syntax, such -commands can be directly entered into the @sc{gdb/mi} interface and @value{GDBN} will -respond. - -This mechanism is provided as an aid to developers of @sc{gdb/mi} -clients and not as a reliable interface into the CLI. Since the command -is being interpreteted in an environment that assumes @sc{gdb/mi} -behaviour, the exact output of such commands is likely to end up being -an un-supported hybrid of @sc{gdb/mi} and CLI output. - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Output Records -@section @sc{gdb/mi} Output Records - -@menu -* GDB/MI Result Records:: -* GDB/MI Stream Records:: -* GDB/MI Out-of-band Records:: -@end menu - -@node GDB/MI Result Records -@subsection @sc{gdb/mi} Result Records - -@cindex result records in @sc{gdb/mi} -@cindex @sc{gdb/mi}, result records -In addition to a number of out-of-band notifications, the response to a -@sc{gdb/mi} command includes one of the following result indications: - -@table @code -@findex ^done -@item "^done" [ "," @var{results} ] -The synchronous operation was successful, @code{@var{results}} are the return -values. - -@item "^running" -@findex ^running -@c Is this one correct? Should it be an out-of-band notification? -The asynchronous operation was successfully started. The target is -running. - -@item "^error" "," @var{c-string} -@findex ^error -The operation failed. The @code{@var{c-string}} contains the corresponding -error message. -@end table - -@node GDB/MI Stream Records -@subsection @sc{gdb/mi} Stream Records - -@cindex @sc{gdb/mi}, stream records -@cindex stream records in @sc{gdb/mi} -@value{GDBN} internally maintains a number of output streams: the console, the -target, and the log. The output intended for each of these streams is -funneled through the @sc{gdb/mi} interface using @dfn{stream records}. - -Each stream record begins with a unique @dfn{prefix character} which -identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output -Syntax}). In addition to the prefix, each stream record contains a -@code{@var{string-output}}. This is either raw text (with an implicit new -line) or a quoted C string (which does not contain an implicit newline). - -@table @code -@item "~" @var{string-output} -The console output stream contains text that should be displayed in the -CLI console window. It contains the textual responses to CLI commands. - -@item "@@" @var{string-output} -The target output stream contains any textual output from the running -target. - -@item "&" @var{string-output} -The log stream contains debugging messages being produced by @value{GDBN}'s -internals. -@end table - -@node GDB/MI Out-of-band Records -@subsection @sc{gdb/mi} Out-of-band Records - -@cindex out-of-band records in @sc{gdb/mi} -@cindex @sc{gdb/mi}, out-of-band records -@dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of -additional changes that have occurred. Those changes can either be a -consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of -target activity (e.g., target stopped). - -The following is a preliminary list of possible out-of-band records. - -@table @code -@item "*" "stop" -@end table - - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Command Description Format -@section @sc{gdb/mi} Command Description Format - -The remaining sections describe blocks of commands. Each block of -commands is laid out in a fashion similar to this section. - -Note the the line breaks shown in the examples are here only for -readability. They don't appear in the real output. -Also note that the commands with a non-available example (N.A.@:) are -not yet implemented. - -@subheading Motivation - -The motivation for this collection of commands. - -@subheading Introduction - -A brief introduction to this collection of commands as a whole. - -@subheading Commands - -For each command in the block, the following is described: - -@subsubheading Synopsis - -@example - -command @var{args}@dots{} -@end example - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} CLI command. - -@subsubheading Result - -@subsubheading Out-of-band - -@subsubheading Notes - -@subsubheading Example - - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Breakpoint Table Commands -@section @sc{gdb/mi} Breakpoint table commands - -@cindex breakpoint commands for @sc{gdb/mi} -@cindex @sc{gdb/mi}, breakpoint commands -This section documents @sc{gdb/mi} commands for manipulating -breakpoints. - -@subheading The @code{-break-after} Command -@findex -break-after - -@subsubheading Synopsis - -@example - -break-after @var{number} @var{count} -@end example - -The breakpoint number @var{number} is not in effect until it has been -hit @var{count} times. To see how this is reflected in the output of -the @samp{-break-list} command, see the description of the -@samp{-break-list} command below. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{ignore}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-insert main -^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@} -(@value{GDBP}) --break-after 1 3 -~ -^done -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="1",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", -addr="0x000100d0",func="main",file="hello.c",line="5",times="0", -ignore="3"@}]@} -(@value{GDBP}) -@end smallexample - -@ignore -@subheading The @code{-break-catch} Command -@findex -break-catch - -@subheading The @code{-break-commands} Command -@findex -break-commands -@end ignore - - -@subheading The @code{-break-condition} Command -@findex -break-condition - -@subsubheading Synopsis - -@example - -break-condition @var{number} @var{expr} -@end example - -Breakpoint @var{number} will stop the program only if the condition in -@var{expr} is true. The condition becomes part of the -@samp{-break-list} output (see the description of the @samp{-break-list} -command below). - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{condition}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-condition 1 1 -^done -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="1",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", -addr="0x000100d0",func="main",file="hello.c",line="5",cond="1", -times="0",ignore="3"@}]@} -(@value{GDBP}) -@end smallexample - -@subheading The @code{-break-delete} Command -@findex -break-delete - -@subsubheading Synopsis - -@example - -break-delete ( @var{breakpoint} )+ -@end example - -Delete the breakpoint(s) whose number(s) are specified in the argument -list. This is obviously reflected in the breakpoint list. - -@subsubheading @value{GDBN} command - -The corresponding @value{GDBN} command is @samp{delete}. - -@subsubheading Example - -@example -(@value{GDBP}) --break-delete 1 -^done -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="0",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[]@} -(@value{GDBP}) -@end example - -@subheading The @code{-break-disable} Command -@findex -break-disable - -@subsubheading Synopsis - -@example - -break-disable ( @var{breakpoint} )+ -@end example - -Disable the named @var{breakpoint}(s). The field @samp{enabled} in the -break list is now set to @samp{n} for the named @var{breakpoint}(s). - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{disable}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-disable 2 -^done -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="1",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n", -addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@} -(@value{GDBP}) -@end smallexample - -@subheading The @code{-break-enable} Command -@findex -break-enable - -@subsubheading Synopsis - -@example - -break-enable ( @var{breakpoint} )+ -@end example - -Enable (previously disabled) @var{breakpoint}(s). - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{enable}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-enable 2 -^done -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="1",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", -addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@} -(@value{GDBP}) -@end smallexample - -@subheading The @code{-break-info} Command -@findex -break-info - -@subsubheading Synopsis - -@example - -break-info @var{breakpoint} -@end example - -@c REDUNDANT??? -Get information about a single breakpoint. - -@subsubheading @value{GDBN} command - -The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}. - -@subsubheading Example -N.A. - -@subheading The @code{-break-insert} Command -@findex -break-insert - -@subsubheading Synopsis - -@example - -break-insert [ -t ] [ -h ] [ -r ] - [ -c @var{condition} ] [ -i @var{ignore-count} ] - [ -p @var{thread} ] [ @var{line} | @var{addr} ] -@end example - -@noindent -If specified, @var{line}, can be one of: - -@itemize @bullet -@item function -@c @item +offset -@c @item -offset -@c @item linenum -@item filename:linenum -@item filename:function -@item *address -@end itemize - -The possible optional parameters of this command are: - -@table @samp -@item -t -Insert a tempoary breakpoint. -@item -h -Insert a hardware breakpoint. -@item -c @var{condition} -Make the breakpoint conditional on @var{condition}. -@item -i @var{ignore-count} -Initialize the @var{ignore-count}. -@item -r -Insert a regular breakpoint in all the functions whose names match the -given regular expression. Other flags are not applicable to regular -expresson. -@end table - -@subsubheading Result - -The result is in the form: - -@example - ^done,bkptno="@var{number}",func="@var{funcname}", - file="@var{filename}",line="@var{lineno}" -@end example - -@noindent -where @var{number} is the @value{GDBN} number for this breakpoint, @var{funcname} -is the name of the function where the breakpoint was inserted, -@var{filename} is the name of the source file which contains this -function, and @var{lineno} is the source line number within that file. - -Note: this format is open to change. -@c An out-of-band breakpoint instead of part of the result? - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak}, -@samp{hbreak}, @samp{thbreak}, and @samp{rbreak}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-insert main -^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} -(@value{GDBP}) --break-insert -t foo -^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@} -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="2",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", -addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@}, -bkpt=@{number="2",type="breakpoint",disp="del",enabled="y", -addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}]@} -(@value{GDBP}) --break-insert -r foo.* -~int foo(int, int); -^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@} -(@value{GDBP}) -@end smallexample - -@subheading The @code{-break-list} Command -@findex -break-list - -@subsubheading Synopsis - -@example - -break-list -@end example - -Displays the list of inserted breakpoints, showing the following fields: - -@table @samp -@item Number -number of the breakpoint -@item Type -type of the breakpoint: @samp{breakpoint} or @samp{watchpoint} -@item Disposition -should the breakpoint be deleted or disabled when it is hit: @samp{keep} -or @samp{nokeep} -@item Enabled -is the breakpoint enabled or no: @samp{y} or @samp{n} -@item Address -memory location at which the breakpoint is set -@item What -logical location of the breakpoint, expressed by function name, file -name, line number -@item Times -number of times the breakpoint has been hit -@end table - -If there are no breakpoints or watchpoints, the @code{BreakpointTable} -@code{body} field is an empty list. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info break}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="2",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", -addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}, -bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", -addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}]@} -(@value{GDBP}) -@end smallexample - -Here's an example of the result when there are no breakpoints: - -@smallexample -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="0",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[]@} -(@value{GDBP}) -@end smallexample - -@subheading The @code{-break-watch} Command -@findex -break-watch - -@subsubheading Synopsis - -@example - -break-watch [ -a | -r ] -@end example - -Create a watchpoint. With the @samp{-a} option it will create an -@dfn{access} watchpoint, i.e. a watchpoint that triggers either on a -read from or on a write to the memory location. With the @samp{-r} -option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will -trigger only when the memory location is accessed for reading. Without -either of the options, the watchpoint created is a regular watchpoint, -i.e. it will trigger when the memory location is accessed for writing. -@xref{Set Watchpoints, , Setting watchpoints}. - -Note that @samp{-break-list} will report a single list of watchpoints and -breakpoints inserted. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and -@samp{rwatch}. - -@subsubheading Example - -Setting a watchpoint on a variable in the @code{main} function: - -@smallexample -(@value{GDBP}) --break-watch x -^done,wpt=@{number="2",exp="x"@} -(@value{GDBP}) --exec-continue -^running -^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@}, -value=@{old="-268439212",new="55"@}, -frame=@{func="main",args=[],file="recursive2.c",line="5"@} -(@value{GDBP}) -@end smallexample - -Setting a watchpoint on a variable local to a function. @value{GDBN} will stop -the program execution twice: first for the variable changing value, then -for the watchpoint going out of scope. - -@smallexample -(@value{GDBP}) --break-watch C -^done,wpt=@{number="5",exp="C"@} -(@value{GDBP}) --exec-continue -^running -^done,reason="watchpoint-trigger", -wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@}, -frame=@{func="callee4",args=[], -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@} -(@value{GDBP}) --exec-continue -^running -^done,reason="watchpoint-scope",wpnum="5", -frame=@{func="callee3",args=[@{name="strarg", -value="0x11940 \"A string argument.\""@}], -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} -(@value{GDBP}) -@end smallexample - -Listing breakpoints and watchpoints, at different points in the program -execution. Note that once the watchpoint goes out of scope, it is -deleted. - -@smallexample -(@value{GDBP}) --break-watch C -^done,wpt=@{number="2",exp="C"@} -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="2",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", -addr="0x00010734",func="callee4", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}, -bkpt=@{number="2",type="watchpoint",disp="keep", -enabled="y",addr="",what="C",times="0"@}]@} -(@value{GDBP}) --exec-continue -^running -^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@}, -value=@{old="-276895068",new="3"@}, -frame=@{func="callee4",args=[], -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@} -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="2",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", -addr="0x00010734",func="callee4", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}, -bkpt=@{number="2",type="watchpoint",disp="keep", -enabled="y",addr="",what="C",times="-5"@}]@} -(@value{GDBP}) --exec-continue -^running -^done,reason="watchpoint-scope",wpnum="2", -frame=@{func="callee3",args=[@{name="strarg", -value="0x11940 \"A string argument.\""@}], -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="1",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", -addr="0x00010734",func="callee4", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}]@} -(@value{GDBP}) -@end smallexample - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Data Manipulation -@section @sc{gdb/mi} Data Manipulation - -@cindex data manipulation, in @sc{gdb/mi} -@cindex @sc{gdb/mi}, data manipulation -This section describes the @sc{gdb/mi} commands that manipulate data: -examine memory and registers, evaluate expressions, etc. - -@c REMOVED FROM THE INTERFACE. -@c @subheading -data-assign -@c Change the value of a program variable. Plenty of side effects. -@c @subsubheading GDB command -@c set variable -@c @subsubheading Example -@c N.A. - -@subheading The @code{-data-disassemble} Command -@findex -data-disassemble - -@subsubheading Synopsis - -@example - -data-disassemble - [ -s @var{start-addr} -e @var{end-addr} ] - | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ] - -- @var{mode} -@end example - -@noindent -Where: - -@table @samp -@item @var{start-addr} -is the beginning address (or @code{$pc}) -@item @var{end-addr} -is the end address -@item @var{filename} -is the name of the file to disassemble -@item @var{linenum} -is the line number to disassemble around -@item @var{lines} -is the the number of disassembly lines to be produced. If it is -1, -the whole function will be disassembled, in case no @var{end-addr} is -specified. If @var{end-addr} is specified as a non-zero value, and -@var{lines} is lower than the number of disassembly lines between -@var{start-addr} and @var{end-addr}, only @var{lines} lines are -displayed; if @var{lines} is higher than the number of lines between -@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr} -are displayed. -@item @var{mode} -is either 0 (meaning only disassembly) or 1 (meaning mixed source and -disassembly). -@end table - -@subsubheading Result - -The output for each instruction is composed of four fields: - -@itemize @bullet -@item Address -@item Func-name -@item Offset -@item Instruction -@end itemize - -Note that whatever included in the instruction field, is not manipulated -directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format. - -@subsubheading @value{GDBN} Command - -There's no direct mapping from this command to the CLI. - -@subsubheading Example - -Disassemble from the current value of @code{$pc} to @code{$pc + 20}: - -@smallexample -(@value{GDBP}) --data-disassemble -s $pc -e "$pc + 20" -- 0 -^done, -asm_insns=[ -@{address="0x000107c0",func-name="main",offset="4", -inst="mov 2, %o0"@}, -@{address="0x000107c4",func-name="main",offset="8", -inst="sethi %hi(0x11800), %o2"@}, -@{address="0x000107c8",func-name="main",offset="12", -inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@}, -@{address="0x000107cc",func-name="main",offset="16", -inst="sethi %hi(0x11800), %o2"@}, -@{address="0x000107d0",func-name="main",offset="20", -inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}] -(@value{GDBP}) -@end smallexample - -Disassemble the whole @code{main} function. Line 32 is part of -@code{main}. - -@smallexample --data-disassemble -f basics.c -l 32 -- 0 -^done,asm_insns=[ -@{address="0x000107bc",func-name="main",offset="0", -inst="save %sp, -112, %sp"@}, -@{address="0x000107c0",func-name="main",offset="4", -inst="mov 2, %o0"@}, -@{address="0x000107c4",func-name="main",offset="8", -inst="sethi %hi(0x11800), %o2"@}, -[@dots{}] -@{address="0x0001081c",func-name="main",offset="96",inst="ret "@}, -@{address="0x00010820",func-name="main",offset="100",inst="restore "@}] -(@value{GDBP}) -@end smallexample - -Disassemble 3 instructions from the start of @code{main}: - -@smallexample -(@value{GDBP}) --data-disassemble -f basics.c -l 32 -n 3 -- 0 -^done,asm_insns=[ -@{address="0x000107bc",func-name="main",offset="0", -inst="save %sp, -112, %sp"@}, -@{address="0x000107c0",func-name="main",offset="4", -inst="mov 2, %o0"@}, -@{address="0x000107c4",func-name="main",offset="8", -inst="sethi %hi(0x11800), %o2"@}] -(@value{GDBP}) -@end smallexample - -Disassemble 3 instructions from the start of @code{main} in mixed mode: - -@smallexample -(@value{GDBP}) --data-disassemble -f basics.c -l 32 -n 3 -- 1 -^done,asm_insns=[ -src_and_asm_line=@{line="31", -file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ - testsuite/gdb.mi/basics.c",line_asm_insn=[ -@{address="0x000107bc",func-name="main",offset="0", -inst="save %sp, -112, %sp"@}]@}, -src_and_asm_line=@{line="32", -file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ - testsuite/gdb.mi/basics.c",line_asm_insn=[ -@{address="0x000107c0",func-name="main",offset="4", -inst="mov 2, %o0"@}, -@{address="0x000107c4",func-name="main",offset="8", -inst="sethi %hi(0x11800), %o2"@}]@}] -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-data-evaluate-expression} Command -@findex -data-evaluate-expression - -@subsubheading Synopsis - -@example - -data-evaluate-expression @var{expr} -@end example - -Evaluate @var{expr} as an expression. The expression could contain an -inferior function call. The function call will execute synchronously. -If the expression contains spaces, it must be enclosed in double quotes. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and -@samp{call}. In @code{gdbtk} only, there's a corresponding -@samp{gdb_eval} command. - -@subsubheading Example - -In the following example, the numbers that precede the commands are the -@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi} -Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its -output. - -@smallexample -211-data-evaluate-expression A -211^done,value="1" -(@value{GDBP}) -311-data-evaluate-expression &A -311^done,value="0xefffeb7c" -(@value{GDBP}) -411-data-evaluate-expression A+3 -411^done,value="4" -(@value{GDBP}) -511-data-evaluate-expression "A + 3" -511^done,value="4" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-data-list-changed-registers} Command -@findex -data-list-changed-registers - -@subsubheading Synopsis - -@example - -data-list-changed-registers -@end example - -Display a list of the registers that have changed. - -@subsubheading @value{GDBN} Command - -@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk} -has the corresponding command @samp{gdb_changed_register_list}. - -@subsubheading Example - -On a PPC MBX board: - -@smallexample -(@value{GDBP}) --exec-continue -^running - -(@value{GDBP}) -*stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main", -args=[],file="try.c",line="5"@} -(@value{GDBP}) --data-list-changed-registers -^done,changed-registers=["0","1","2","4","5","6","7","8","9", -"10","11","13","14","15","16","17","18","19","20","21","22","23", -"24","25","26","27","28","30","31","64","65","66","67","69"] -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-data-list-register-names} Command -@findex -data-list-register-names - -@subsubheading Synopsis - -@example - -data-list-register-names [ ( @var{regno} )+ ] -@end example - -Show a list of register names for the current target. If no arguments -are given, it shows a list of the names of all the registers. If -integer numbers are given as arguments, it will print a list of the -names of the registers corresponding to the arguments. To ensure -consistency between a register name and its number, the output list may -include empty register names. - -@subsubheading @value{GDBN} Command - -@value{GDBN} does not have a command which corresponds to -@samp{-data-list-register-names}. In @code{gdbtk} there is a -corresponding command @samp{gdb_regnames}. - -@subsubheading Example - -For the PPC MBX board: -@smallexample -(@value{GDBP}) --data-list-register-names -^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", -"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", -"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", -"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", -"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", -"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", -"", "pc","ps","cr","lr","ctr","xer"] -(@value{GDBP}) --data-list-register-names 1 2 3 -^done,register-names=["r1","r2","r3"] -(@value{GDBP}) -@end smallexample - -@subheading The @code{-data-list-register-values} Command -@findex -data-list-register-values - -@subsubheading Synopsis - -@example - -data-list-register-values @var{fmt} [ ( @var{regno} )*] -@end example - -Display the registers' contents. @var{fmt} is the format according to -which the registers' contents are to be returned, followed by an optional -list of numbers specifying the registers to display. A missing list of -numbers indicates that the contents of all the registers must be returned. - -Allowed formats for @var{fmt} are: - -@table @code -@item x -Hexadecimal -@item o -Octal -@item t -Binary -@item d -Decimal -@item r -Raw -@item N -Natural -@end table - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info -all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}. - -@subsubheading Example - -For a PPC MBX board (note: line breaks are for readability only, they -don't appear in the actual output): - -@smallexample -(@value{GDBP}) --data-list-register-values r 64 65 -^done,register-values=[@{number="64",value="0xfe00a300"@}, -@{number="65",value="0x00029002"@}] -(@value{GDBP}) --data-list-register-values x -^done,register-values=[@{number="0",value="0xfe0043c8"@}, -@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@}, -@{number="3",value="0x0"@},@{number="4",value="0xa"@}, -@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@}, -@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@}, -@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@}, -@{number="11",value="0x1"@},@{number="12",value="0x0"@}, -@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@}, -@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@}, -@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@}, -@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@}, -@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@}, -@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@}, -@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@}, -@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@}, -@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@}, -@{number="31",value="0x0"@},@{number="32",value="0x0"@}, -@{number="33",value="0x0"@},@{number="34",value="0x0"@}, -@{number="35",value="0x0"@},@{number="36",value="0x0"@}, -@{number="37",value="0x0"@},@{number="38",value="0x0"@}, -@{number="39",value="0x0"@},@{number="40",value="0x0"@}, -@{number="41",value="0x0"@},@{number="42",value="0x0"@}, -@{number="43",value="0x0"@},@{number="44",value="0x0"@}, -@{number="45",value="0x0"@},@{number="46",value="0x0"@}, -@{number="47",value="0x0"@},@{number="48",value="0x0"@}, -@{number="49",value="0x0"@},@{number="50",value="0x0"@}, -@{number="51",value="0x0"@},@{number="52",value="0x0"@}, -@{number="53",value="0x0"@},@{number="54",value="0x0"@}, -@{number="55",value="0x0"@},@{number="56",value="0x0"@}, -@{number="57",value="0x0"@},@{number="58",value="0x0"@}, -@{number="59",value="0x0"@},@{number="60",value="0x0"@}, -@{number="61",value="0x0"@},@{number="62",value="0x0"@}, -@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@}, -@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@}, -@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@}, -@{number="69",value="0x20002b03"@}] -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-data-read-memory} Command -@findex -data-read-memory - -@subsubheading Synopsis - -@example - -data-read-memory [ -o @var{byte-offset} ] - @var{address} @var{word-format} @var{word-size} - @var{nr-rows} @var{nr-cols} [ @var{aschar} ] -@end example - -@noindent -where: - -@table @samp -@item @var{address} -An expression specifying the address of the first memory word to be -read. Complex expressions containing embedded white space should be -quoted using the C convention. - -@item @var{word-format} -The format to be used to print the memory words. The notation is the -same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats, -,Output formats}). - -@item @var{word-size} -The size of each memory word in bytes. - -@item @var{nr-rows} -The number of rows in the output table. - -@item @var{nr-cols} -The number of columns in the output table. - -@item @var{aschar} -If present, indicates that each row should include an @sc{ascii} dump. The -value of @var{aschar} is used as a padding character when a byte is not a -member of the printable @sc{ascii} character set (printable @sc{ascii} -characters are those whose code is between 32 and 126, inclusively). - -@item @var{byte-offset} -An offset to add to the @var{address} before fetching memory. -@end table - -This command displays memory contents as a table of @var{nr-rows} by -@var{nr-cols} words, each word being @var{word-size} bytes. In total, -@code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read -(returned as @samp{total-bytes}). Should less than the requested number -of bytes be returned by the target, the missing words are identified -using @samp{N/A}. The number of bytes read from the target is returned -in @samp{nr-bytes} and the starting address used to read memory in -@samp{addr}. - -The address of the next/previous row or page is available in -@samp{next-row} and @samp{prev-row}, @samp{next-page} and -@samp{prev-page}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has -@samp{gdb_get_mem} memory read command. - -@subsubheading Example - -Read six bytes of memory starting at @code{bytes+6} but then offset by -@code{-6} bytes. Format as three rows of two columns. One byte per -word. Display each word in hex. - -@smallexample -(@value{GDBP}) -9-data-read-memory -o -6 -- bytes+6 x 1 3 2 -9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", -next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", -prev-page="0x0000138a",memory=[ -@{addr="0x00001390",data=["0x00","0x01"]@}, -@{addr="0x00001392",data=["0x02","0x03"]@}, -@{addr="0x00001394",data=["0x04","0x05"]@}] -(@value{GDBP}) -@end smallexample - -Read two bytes of memory starting at address @code{shorts + 64} and -display as a single word formatted in decimal. - -@smallexample -(@value{GDBP}) -5-data-read-memory shorts+64 d 2 1 1 -5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", -next-row="0x00001512",prev-row="0x0000150e", -next-page="0x00001512",prev-page="0x0000150e",memory=[ -@{addr="0x00001510",data=["128"]@}] -(@value{GDBP}) -@end smallexample - -Read thirty two bytes of memory starting at @code{bytes+16} and format -as eight rows of four columns. Include a string encoding with @samp{x} -used as the non-printable character. - -@smallexample -(@value{GDBP}) -4-data-read-memory bytes+16 x 1 8 4 x -4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", -next-row="0x000013c0",prev-row="0x0000139c", -next-page="0x000013c0",prev-page="0x00001380",memory=[ -@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@}, -@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@}, -@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@}, -@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@}, -@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@}, -@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@}, -@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@}, -@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}] -(@value{GDBP}) -@end smallexample - -@subheading The @code{-display-delete} Command -@findex -display-delete - -@subsubheading Synopsis - -@example - -display-delete @var{number} -@end example - -Delete the display @var{number}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{delete display}. - -@subsubheading Example -N.A. - - -@subheading The @code{-display-disable} Command -@findex -display-disable - -@subsubheading Synopsis - -@example - -display-disable @var{number} -@end example - -Disable display @var{number}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{disable display}. - -@subsubheading Example -N.A. - - -@subheading The @code{-display-enable} Command -@findex -display-enable - -@subsubheading Synopsis - -@example - -display-enable @var{number} -@end example - -Enable display @var{number}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{enable display}. - -@subsubheading Example -N.A. - - -@subheading The @code{-display-insert} Command -@findex -display-insert - -@subsubheading Synopsis - -@example - -display-insert @var{expression} -@end example - -Display @var{expression} every time the program stops. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{display}. - -@subsubheading Example -N.A. - - -@subheading The @code{-display-list} Command -@findex -display-list - -@subsubheading Synopsis - -@example - -display-list -@end example - -List the displays. Do not show the current values. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info display}. - -@subsubheading Example -N.A. - - -@subheading The @code{-environment-cd} Command -@findex -environment-cd - -@subsubheading Synopsis - -@example - -environment-cd @var{pathdir} -@end example - -Set @value{GDBN}'s working directory. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{cd}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb -^done -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-environment-directory} Command -@findex -environment-directory - -@subsubheading Synopsis - -@example - -environment-directory [ -r ] [ @var{pathdir} ]+ -@end example - -Add directories @var{pathdir} to beginning of search path for source files. -If the @samp{-r} option is used, the search path is reset to the default -search path. If directories @var{pathdir} are supplied in addition to the -@samp{-r} option, the search path is first reset and then addition -occurs as normal. -Multiple directories may be specified, separated by blanks. Specifying -multiple directories in a single command -results in the directories added to the beginning of the -search path in the same order they were presented in the command. -If blanks are needed as -part of a directory name, double-quotes should be used around -the name. In the command output, the path will show up separated -by the system directory-separator character. The directory-seperator -character must not be used -in any directory name. -If no directories are specified, the current search path is displayed. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{dir}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb -^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" -(@value{GDBP}) --environment-directory "" -^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" -(@value{GDBP}) --environment-directory -r /home/jjohnstn/src/gdb /usr/src -^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" -(@value{GDBP}) --environment-directory -r -^done,source-path="$cdir:$cwd" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-environment-path} Command -@findex -environment-path - -@subsubheading Synopsis - -@example - -environment-path [ -r ] [ @var{pathdir} ]+ -@end example - -Add directories @var{pathdir} to beginning of search path for object files. -If the @samp{-r} option is used, the search path is reset to the original -search path that existed at gdb start-up. If directories @var{pathdir} are -supplied in addition to the -@samp{-r} option, the search path is first reset and then addition -occurs as normal. -Multiple directories may be specified, separated by blanks. Specifying -multiple directories in a single command -results in the directories added to the beginning of the -search path in the same order they were presented in the command. -If blanks are needed as -part of a directory name, double-quotes should be used around -the name. In the command output, the path will show up separated -by the system directory-separator character. The directory-seperator -character must not be used -in any directory name. -If no directories are specified, the current path is displayed. - - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{path}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --environment-path -^done,path="/usr/bin" -(@value{GDBP}) --environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin -^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" -(@value{GDBP}) --environment-path -r /usr/local/bin -^done,path="/usr/local/bin:/usr/bin" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-environment-pwd} Command -@findex -environment-pwd - -@subsubheading Synopsis - -@example - -environment-pwd -@end example - -Show the current working directory. - -@subsubheading @value{GDBN} command - -The corresponding @value{GDBN} command is @samp{pwd}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --environment-pwd -^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" -(@value{GDBP}) -@end smallexample - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Program Control -@section @sc{gdb/mi} Program control - -@subsubheading Program termination - -As a result of execution, the inferior program can run to completion, if -it doesn't encounter any breakpoints. In this case the output will -include an exit code, if the program has exited exceptionally. - -@subsubheading Examples - -@noindent -Program exited normally: - -@smallexample -(@value{GDBP}) --exec-run -^running -(@value{GDBP}) -x = 55 -*stopped,reason="exited-normally" -(@value{GDBP}) -@end smallexample - -@noindent -Program exited exceptionally: - -@smallexample -(@value{GDBP}) --exec-run -^running -(@value{GDBP}) -x = 55 -*stopped,reason="exited",exit-code="01" -(@value{GDBP}) -@end smallexample - -Another way the program can terminate is if it receives a signal such as -@code{SIGINT}. In this case, @sc{gdb/mi} displays this: - -@smallexample -(@value{GDBP}) -*stopped,reason="exited-signalled",signal-name="SIGINT", -signal-meaning="Interrupt" -@end smallexample - - -@subheading The @code{-exec-abort} Command -@findex -exec-abort - -@subsubheading Synopsis - -@example - -exec-abort -@end example - -Kill the inferior running program. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{kill}. - -@subsubheading Example -N.A. - - -@subheading The @code{-exec-arguments} Command -@findex -exec-arguments - -@subsubheading Synopsis - -@example - -exec-arguments @var{args} -@end example - -Set the inferior program arguments, to be used in the next -@samp{-exec-run}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{set args}. - -@subsubheading Example - -@c FIXME! -Don't have one around. - - -@subheading The @code{-exec-continue} Command -@findex -exec-continue - -@subsubheading Synopsis - -@example - -exec-continue -@end example - -Asynchronous command. Resumes the execution of the inferior program -until a breakpoint is encountered, or until the inferior exits. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} corresponding is @samp{continue}. - -@subsubheading Example - -@smallexample --exec-continue -^running -(@value{GDBP}) -@@Hello world -*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[], -file="hello.c",line="13"@} -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-finish} Command -@findex -exec-finish - -@subsubheading Synopsis - -@example - -exec-finish -@end example - -Asynchronous command. Resumes the execution of the inferior program -until the current function is exited. Displays the results returned by -the function. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{finish}. - -@subsubheading Example - -Function returning @code{void}. - -@smallexample --exec-finish -^running -(@value{GDBP}) -@@hello from foo -*stopped,reason="function-finished",frame=@{func="main",args=[], -file="hello.c",line="7"@} -(@value{GDBP}) -@end smallexample - -Function returning other than @code{void}. The name of the internal -@value{GDBN} variable storing the result is printed, together with the -value itself. - -@smallexample --exec-finish -^running -(@value{GDBP}) -*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo", -args=[@{name="a",value="1"],@{name="b",value="9"@}@}, -file="recursive2.c",line="14"@}, -gdb-result-var="$1",return-value="0" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-interrupt} Command -@findex -exec-interrupt - -@subsubheading Synopsis - -@example - -exec-interrupt -@end example - -Asynchronous command. Interrupts the background execution of the target. -Note how the token associated with the stop message is the one for the -execution command that has been interrupted. The token for the interrupt -itself only appears in the @samp{^done} output. If the user is trying to -interrupt a non-running program, an error message will be printed. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{interrupt}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) -111-exec-continue -111^running - -(@value{GDBP}) -222-exec-interrupt -222^done -(@value{GDBP}) -111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", -frame=@{addr="0x00010140",func="foo",args=[],file="try.c",line="13"@} -(@value{GDBP}) - -(@value{GDBP}) --exec-interrupt -^error,msg="mi_cmd_exec_interrupt: Inferior not executing." -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-next} Command -@findex -exec-next - -@subsubheading Synopsis - -@example - -exec-next -@end example - -Asynchronous command. Resumes execution of the inferior program, stopping -when the beginning of the next source line is reached. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{next}. - -@subsubheading Example - -@smallexample --exec-next -^running -(@value{GDBP}) -*stopped,reason="end-stepping-range",line="8",file="hello.c" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-next-instruction} Command -@findex -exec-next-instruction - -@subsubheading Synopsis - -@example - -exec-next-instruction -@end example - -Asynchronous command. Executes one machine instruction. If the -instruction is a function call continues until the function returns. If -the program stops at an instruction in the middle of a source line, the -address will be printed as well. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{nexti}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --exec-next-instruction -^running - -(@value{GDBP}) -*stopped,reason="end-stepping-range", -addr="0x000100d4",line="5",file="hello.c" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-return} Command -@findex -exec-return - -@subsubheading Synopsis - -@example - -exec-return -@end example - -Makes current function return immediately. Doesn't execute the inferior. -Displays the new current frame. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{return}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) -200-break-insert callee4 -200^done,bkpt=@{number="1",addr="0x00010734", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} -(@value{GDBP}) -000-exec-run -000^running -(@value{GDBP}) -000*stopped,reason="breakpoint-hit",bkptno="1", -frame=@{func="callee4",args=[], -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} -(@value{GDBP}) -205-break-delete -205^done -(@value{GDBP}) -111-exec-return -111^done,frame=@{level="0",func="callee3", -args=[@{name="strarg", -value="0x11940 \"A string argument.\""@}], -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-run} Command -@findex -exec-run - -@subsubheading Synopsis - -@example - -exec-run -@end example - -Asynchronous command. Starts execution of the inferior from the -beginning. The inferior executes until either a breakpoint is -encountered or the program exits. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{run}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-insert main -^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} -(@value{GDBP}) --exec-run -^running -(@value{GDBP}) -*stopped,reason="breakpoint-hit",bkptno="1", -frame=@{func="main",args=[],file="recursive2.c",line="4"@} -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-show-arguments} Command -@findex -exec-show-arguments - -@subsubheading Synopsis - -@example - -exec-show-arguments -@end example - -Print the arguments of the program. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{show args}. - -@subsubheading Example -N.A. - -@c @subheading -exec-signal - -@subheading The @code{-exec-step} Command -@findex -exec-step - -@subsubheading Synopsis - -@example - -exec-step -@end example - -Asynchronous command. Resumes execution of the inferior program, stopping -when the beginning of the next source line is reached, if the next -source line is not a function call. If it is, stop at the first -instruction of the called function. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{step}. - -@subsubheading Example - -Stepping into a function: - -@smallexample --exec-step -^running -(@value{GDBP}) -*stopped,reason="end-stepping-range", -frame=@{func="foo",args=[@{name="a",value="10"@}, -@{name="b",value="0"@}],file="recursive2.c",line="11"@} -(@value{GDBP}) -@end smallexample - -Regular stepping: - -@smallexample --exec-step -^running -(@value{GDBP}) -*stopped,reason="end-stepping-range",line="14",file="recursive2.c" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-step-instruction} Command -@findex -exec-step-instruction - -@subsubheading Synopsis - -@example - -exec-step-instruction -@end example - -Asynchronous command. Resumes the inferior which executes one machine -instruction. The output, once @value{GDBN} has stopped, will vary depending on -whether we have stopped in the middle of a source line or not. In the -former case, the address at which the program stopped will be printed as -well. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{stepi}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --exec-step-instruction -^running - -(@value{GDBP}) -*stopped,reason="end-stepping-range", -frame=@{func="foo",args=[],file="try.c",line="10"@} -(@value{GDBP}) --exec-step-instruction -^running - -(@value{GDBP}) -*stopped,reason="end-stepping-range", -frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@} -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-until} Command -@findex -exec-until - -@subsubheading Synopsis - -@example - -exec-until [ @var{location} ] -@end example - -Asynchronous command. Executes the inferior until the @var{location} -specified in the argument is reached. If there is no argument, the inferior -executes until a source line greater than the current one is reached. -The reason for stopping in this case will be @samp{location-reached}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{until}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --exec-until recursive2.c:6 -^running -(@value{GDBP}) -x = 55 -*stopped,reason="location-reached",frame=@{func="main",args=[], -file="recursive2.c",line="6"@} -(@value{GDBP}) -@end smallexample - -@ignore -@subheading -file-clear -Is this going away???? -@end ignore - - -@subheading The @code{-file-exec-and-symbols} Command -@findex -file-exec-and-symbols - -@subsubheading Synopsis - -@example - -file-exec-and-symbols @var{file} -@end example - -Specify the executable file to be debugged. This file is the one from -which the symbol table is also read. If no file is specified, the -command clears the executable and symbol information. If breakpoints -are set when using this command with no arguments, @value{GDBN} will produce -error messages. Otherwise, no output is produced, except a completion -notification. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{file}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx -^done -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-file-exec-file} Command -@findex -file-exec-file - -@subsubheading Synopsis - -@example - -file-exec-file @var{file} -@end example - -Specify the executable file to be debugged. Unlike -@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read -from this file. If used without argument, @value{GDBN} clears the information -about the executable file. No output is produced, except a completion -notification. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{exec-file}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx -^done -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-file-list-exec-sections} Command -@findex -file-list-exec-sections - -@subsubheading Synopsis - -@example - -file-list-exec-sections -@end example - -List the sections of the current executable file. - -@subsubheading @value{GDBN} Command - -The @value{GDBN} command @samp{info file} shows, among the rest, the same -information as this command. @code{gdbtk} has a corresponding command -@samp{gdb_load_info}. - -@subsubheading Example -N.A. - - -@subheading The @code{-file-list-exec-source-files} Command -@findex -file-list-exec-source-files - -@subsubheading Synopsis - -@example - -file-list-exec-source-files -@end example - -List the source files for the current executable. - -@subsubheading @value{GDBN} Command - -There's no @value{GDBN} command which directly corresponds to this one. -@code{gdbtk} has an analogous command @samp{gdb_listfiles}. - -@subsubheading Example -N.A. - - -@subheading The @code{-file-list-shared-libraries} Command -@findex -file-list-shared-libraries - -@subsubheading Synopsis - -@example - -file-list-shared-libraries -@end example - -List the shared libraries in the program. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info shared}. - -@subsubheading Example -N.A. - - -@subheading The @code{-file-list-symbol-files} Command -@findex -file-list-symbol-files - -@subsubheading Synopsis - -@example - -file-list-symbol-files -@end example - -List symbol files. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info file} (part of it). - -@subsubheading Example -N.A. - - -@subheading The @code{-file-symbol-file} Command -@findex -file-symbol-file - -@subsubheading Synopsis - -@example - -file-symbol-file @var{file} -@end example - -Read symbol table info from the specified @var{file} argument. When -used without arguments, clears @value{GDBN}'s symbol table info. No output is -produced, except for a completion notification. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{symbol-file}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx -^done -(@value{GDBP}) -@end smallexample - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Miscellaneous Commands -@section Miscellaneous @value{GDBN} commands in @sc{gdb/mi} - -@c @subheading -gdb-complete - -@subheading The @code{-gdb-exit} Command -@findex -gdb-exit - -@subsubheading Synopsis - -@example - -gdb-exit -@end example - -Exit @value{GDBN} immediately. - -@subsubheading @value{GDBN} Command - -Approximately corresponds to @samp{quit}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --gdb-exit -@end smallexample - -@subheading The @code{-gdb-set} Command -@findex -gdb-set - -@subsubheading Synopsis - -@example - -gdb-set -@end example - -Set an internal @value{GDBN} variable. -@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ????? - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{set}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --gdb-set $foo=3 -^done -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-gdb-show} Command -@findex -gdb-show - -@subsubheading Synopsis - -@example - -gdb-show -@end example - -Show the current value of a @value{GDBN} variable. - -@subsubheading @value{GDBN} command - -The corresponding @value{GDBN} command is @samp{show}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --gdb-show annotate -^done,value="0" -(@value{GDBP}) -@end smallexample - -@c @subheading -gdb-source - - -@subheading The @code{-gdb-version} Command -@findex -gdb-version - -@subsubheading Synopsis - -@example - -gdb-version -@end example - -Show version information for @value{GDBN}. Used mostly in testing. - -@subsubheading @value{GDBN} Command - -There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this -information when you start an interactive session. - -@subsubheading Example - -@c This example modifies the actual output from GDB to avoid overfull -@c box in TeX. -@smallexample -(@value{GDBP}) --gdb-version -~GNU gdb 5.2.1 -~Copyright 2000 Free Software Foundation, Inc. -~GDB is free software, covered by the GNU General Public License, and -~you are welcome to change it and/or distribute copies of it under -~ certain conditions. -~Type "show copying" to see the conditions. -~There is absolutely no warranty for GDB. Type "show warranty" for -~ details. -~This GDB was configured as - "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". -^done -(@value{GDBP}) -@end smallexample - -@subheading The @code{-interpreter-exec} Command -@findex -interpreter-exec - -@subheading Synopsis - -@smallexample --interpreter-exec @var{interpreter} @var{command} -@end smallexample - -Execute the specified @var{command} in the given @var{interpreter}. - -@subheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{interpreter-exec}. - -@subheading Example - -@smallexample -(@value{GDBP}) --interpreter-exec console "break main" -&"During symbol reading, couldn't parse type; debugger out of date?.\n" -&"During symbol reading, bad structure-type format.\n" -~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" -^done -(@value{GDBP}) -@end smallexample - -@ignore -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Kod Commands -@section @sc{gdb/mi} Kod Commands - -The Kod commands are not implemented. - -@c @subheading -kod-info - -@c @subheading -kod-list - -@c @subheading -kod-list-object-types - -@c @subheading -kod-show - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Memory Overlay Commands -@section @sc{gdb/mi} Memory Overlay Commands - -The memory overlay commands are not implemented. - -@c @subheading -overlay-auto - -@c @subheading -overlay-list-mapping-state - -@c @subheading -overlay-list-overlays - -@c @subheading -overlay-map - -@c @subheading -overlay-off - -@c @subheading -overlay-on - -@c @subheading -overlay-unmap - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Signal Handling Commands -@section @sc{gdb/mi} Signal Handling Commands - -Signal handling commands are not implemented. - -@c @subheading -signal-handle - -@c @subheading -signal-list-handle-actions - -@c @subheading -signal-list-signal-types -@end ignore - - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Stack Manipulation -@section @sc{gdb/mi} Stack Manipulation Commands - - -@subheading The @code{-stack-info-frame} Command -@findex -stack-info-frame - -@subsubheading Synopsis - -@example - -stack-info-frame -@end example - -Get info on the current frame. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame} -(without arguments). - -@subsubheading Example -N.A. - -@subheading The @code{-stack-info-depth} Command -@findex -stack-info-depth - -@subsubheading Synopsis - -@example - -stack-info-depth [ @var{max-depth} ] -@end example - -Return the depth of the stack. If the integer argument @var{max-depth} -is specified, do not count beyond @var{max-depth} frames. - -@subsubheading @value{GDBN} Command - -There's no equivalent @value{GDBN} command. - -@subsubheading Example - -For a stack with frame levels 0 through 11: - -@smallexample -(@value{GDBP}) --stack-info-depth -^done,depth="12" -(@value{GDBP}) --stack-info-depth 4 -^done,depth="4" -(@value{GDBP}) --stack-info-depth 12 -^done,depth="12" -(@value{GDBP}) --stack-info-depth 11 -^done,depth="11" -(@value{GDBP}) --stack-info-depth 13 -^done,depth="12" -(@value{GDBP}) -@end smallexample - -@subheading The @code{-stack-list-arguments} Command -@findex -stack-list-arguments - -@subsubheading Synopsis - -@example - -stack-list-arguments @var{show-values} - [ @var{low-frame} @var{high-frame} ] -@end example - -Display a list of the arguments for the frames between @var{low-frame} -and @var{high-frame} (inclusive). If @var{low-frame} and -@var{high-frame} are not provided, list the arguments for the whole call -stack. - -The @var{show-values} argument must have a value of 0 or 1. A value of -0 means that only the names of the arguments are listed, a value of 1 -means that both names and values of the arguments are printed. - -@subsubheading @value{GDBN} Command - -@value{GDBN} does not have an equivalent command. @code{gdbtk} has a -@samp{gdb_get_args} command which partially overlaps with the -functionality of @samp{-stack-list-arguments}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --stack-list-frames -^done, -stack=[ -frame=@{level="0",addr="0x00010734",func="callee4", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}, -frame=@{level="1",addr="0x0001076c",func="callee3", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}, -frame=@{level="2",addr="0x0001078c",func="callee2", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@}, -frame=@{level="3",addr="0x000107b4",func="callee1", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@}, -frame=@{level="4",addr="0x000107e0",func="main", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}] -(@value{GDBP}) --stack-list-arguments 0 -^done, -stack-args=[ -frame=@{level="0",args=[]@}, -frame=@{level="1",args=[name="strarg"]@}, -frame=@{level="2",args=[name="intarg",name="strarg"]@}, -frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@}, -frame=@{level="4",args=[]@}] -(@value{GDBP}) --stack-list-arguments 1 -^done, -stack-args=[ -frame=@{level="0",args=[]@}, -frame=@{level="1", - args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, -frame=@{level="2",args=[ -@{name="intarg",value="2"@}, -@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, -@{frame=@{level="3",args=[ -@{name="intarg",value="2"@}, -@{name="strarg",value="0x11940 \"A string argument.\""@}, -@{name="fltarg",value="3.5"@}]@}, -frame=@{level="4",args=[]@}] -(@value{GDBP}) --stack-list-arguments 0 2 2 -^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}] -(@value{GDBP}) --stack-list-arguments 1 2 2 -^done,stack-args=[frame=@{level="2", -args=[@{name="intarg",value="2"@}, -@{name="strarg",value="0x11940 \"A string argument.\""@}]@}] -(@value{GDBP}) -@end smallexample - -@c @subheading -stack-list-exception-handlers - - -@subheading The @code{-stack-list-frames} Command -@findex -stack-list-frames - -@subsubheading Synopsis - -@example - -stack-list-frames [ @var{low-frame} @var{high-frame} ] -@end example - -List the frames currently on the stack. For each frame it displays the -following info: - -@table @samp -@item @var{level} -The frame number, 0 being the topmost frame, i.e. the innermost function. -@item @var{addr} -The @code{$pc} value for that frame. -@item @var{func} -Function name. -@item @var{file} -File name of the source file where the function lives. -@item @var{line} -Line number corresponding to the @code{$pc}. -@end table - -If invoked without arguments, this command prints a backtrace for the -whole stack. If given two integer arguments, it shows the frames whose -levels are between the two arguments (inclusive). If the two arguments -are equal, it shows the single frame at the corresponding level. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}. - -@subsubheading Example - -Full stack backtrace: - -@smallexample -(@value{GDBP}) --stack-list-frames -^done,stack= -[frame=@{level="0",addr="0x0001076c",func="foo", - file="recursive2.c",line="11"@}, -frame=@{level="1",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="2",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="3",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="4",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="5",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="6",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="7",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="8",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="9",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="10",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="11",addr="0x00010738",func="main", - file="recursive2.c",line="4"@}] -(@value{GDBP}) -@end smallexample - -Show frames between @var{low_frame} and @var{high_frame}: - -@smallexample -(@value{GDBP}) --stack-list-frames 3 5 -^done,stack= -[frame=@{level="3",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="4",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="5",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}] -(@value{GDBP}) -@end smallexample - -Show a single frame: - -@smallexample -(@value{GDBP}) --stack-list-frames 3 3 -^done,stack= -[frame=@{level="3",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}] -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-stack-list-locals} Command -@findex -stack-list-locals - -@subsubheading Synopsis - -@example - -stack-list-locals @var{print-values} -@end example - -Display the local variable names for the current frame. With an -argument of 0 prints only the names of the variables, with argument of 1 -prints also their values. - -@subsubheading @value{GDBN} Command - -@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --stack-list-locals 0 -^done,locals=[name="A",name="B",name="C"] -(@value{GDBP}) --stack-list-locals 1 -^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@}, - @{name="C",value="3"@}] -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-stack-select-frame} Command -@findex -stack-select-frame - -@subsubheading Synopsis - -@example - -stack-select-frame @var{framenum} -@end example - -Change the current frame. Select a different frame @var{framenum} on -the stack. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} commands are @samp{frame}, @samp{up}, -@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --stack-select-frame 2 -^done -(@value{GDBP}) -@end smallexample - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Symbol Query -@section @sc{gdb/mi} Symbol Query Commands - - -@subheading The @code{-symbol-info-address} Command -@findex -symbol-info-address - -@subsubheading Synopsis - -@example - -symbol-info-address @var{symbol} -@end example - -Describe where @var{symbol} is stored. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info address}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-info-file} Command -@findex -symbol-info-file - -@subsubheading Synopsis - -@example - -symbol-info-file -@end example - -Show the file for the symbol. - -@subsubheading @value{GDBN} Command - -There's no equivalent @value{GDBN} command. @code{gdbtk} has -@samp{gdb_find_file}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-info-function} Command -@findex -symbol-info-function - -@subsubheading Synopsis - -@example - -symbol-info-function -@end example - -Show which function the symbol lives in. - -@subsubheading @value{GDBN} Command - -@samp{gdb_get_function} in @code{gdbtk}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-info-line} Command -@findex -symbol-info-line - -@subsubheading Synopsis - -@example - -symbol-info-line -@end example - -Show the core addresses of the code for a source line. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} comamnd is @samp{info line}. -@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-info-symbol} Command -@findex -symbol-info-symbol - -@subsubheading Synopsis - -@example - -symbol-info-symbol @var{addr} -@end example - -Describe what symbol is at location @var{addr}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info symbol}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-list-functions} Command -@findex -symbol-list-functions - -@subsubheading Synopsis - -@example - -symbol-list-functions -@end example - -List the functions in the executable. - -@subsubheading @value{GDBN} Command - -@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and -@samp{gdb_search} in @code{gdbtk}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-list-types} Command -@findex -symbol-list-types - -@subsubheading Synopsis - -@example - -symbol-list-types -@end example - -List all the type names. - -@subsubheading @value{GDBN} Command - -The corresponding commands are @samp{info types} in @value{GDBN}, -@samp{gdb_search} in @code{gdbtk}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-list-variables} Command -@findex -symbol-list-variables - -@subsubheading Synopsis - -@example - -symbol-list-variables -@end example - -List all the global and static variable names. - -@subsubheading @value{GDBN} Command - -@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-locate} Command -@findex -symbol-locate - -@subsubheading Synopsis - -@example - -symbol-locate -@end example - -@subsubheading @value{GDBN} Command - -@samp{gdb_loc} in @code{gdbtk}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-type} Command -@findex -symbol-type - -@subsubheading Synopsis - -@example - -symbol-type @var{variable} -@end example - -Show type of @var{variable}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has -@samp{gdb_obj_variable}. - -@subsubheading Example -N.A. - - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Target Manipulation -@section @sc{gdb/mi} Target Manipulation Commands - - -@subheading The @code{-target-attach} Command -@findex -target-attach - -@subsubheading Synopsis - -@example - -target-attach @var{pid} | @var{file} -@end example - -Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}. - -@subsubheading @value{GDBN} command - -The corresponding @value{GDBN} command is @samp{attach}. - -@subsubheading Example -N.A. - - -@subheading The @code{-target-compare-sections} Command -@findex -target-compare-sections - -@subsubheading Synopsis - -@example - -target-compare-sections [ @var{section} ] -@end example - -Compare data of section @var{section} on target to the exec file. -Without the argument, all sections are compared. - -@subsubheading @value{GDBN} Command - -The @value{GDBN} equivalent is @samp{compare-sections}. - -@subsubheading Example -N.A. - - -@subheading The @code{-target-detach} Command -@findex -target-detach - -@subsubheading Synopsis - -@example - -target-detach -@end example - -Disconnect from the remote target. There's no output. - -@subsubheading @value{GDBN} command - -The corresponding @value{GDBN} command is @samp{detach}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --target-detach -^done -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-target-download} Command -@findex -target-download - -@subsubheading Synopsis - -@example - -target-download -@end example - -Loads the executable onto the remote target. -It prints out an update message every half second, which includes the fields: - -@table @samp -@item section -The name of the section. -@item section-sent -The size of what has been sent so far for that section. -@item section-size -The size of the section. -@item total-sent -The total size of what was sent so far (the current and the previous sections). -@item total-size -The size of the overall executable to download. -@end table - -@noindent -Each message is sent as status record (@pxref{GDB/MI Output Syntax, , -@sc{gdb/mi} Output Syntax}). - -In addition, it prints the name and size of the sections, as they are -downloaded. These messages include the following fields: - -@table @samp -@item section -The name of the section. -@item section-size -The size of the section. -@item total-size -The size of the overall executable to download. -@end table - -@noindent -At the end, a summary is printed. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{load}. - -@subsubheading Example - -Note: each status message appears on a single line. Here the messages -have been broken down so that they can fit onto a page. - -@smallexample -(@value{GDBP}) --target-download -+download,@{section=".text",section-size="6668",total-size="9880"@} -+download,@{section=".text",section-sent="512",section-size="6668", -total-sent="512",total-size="9880"@} -+download,@{section=".text",section-sent="1024",section-size="6668", -total-sent="1024",total-size="9880"@} -+download,@{section=".text",section-sent="1536",section-size="6668", -total-sent="1536",total-size="9880"@} -+download,@{section=".text",section-sent="2048",section-size="6668", -total-sent="2048",total-size="9880"@} -+download,@{section=".text",section-sent="2560",section-size="6668", -total-sent="2560",total-size="9880"@} -+download,@{section=".text",section-sent="3072",section-size="6668", -total-sent="3072",total-size="9880"@} -+download,@{section=".text",section-sent="3584",section-size="6668", -total-sent="3584",total-size="9880"@} -+download,@{section=".text",section-sent="4096",section-size="6668", -total-sent="4096",total-size="9880"@} -+download,@{section=".text",section-sent="4608",section-size="6668", -total-sent="4608",total-size="9880"@} -+download,@{section=".text",section-sent="5120",section-size="6668", -total-sent="5120",total-size="9880"@} -+download,@{section=".text",section-sent="5632",section-size="6668", -total-sent="5632",total-size="9880"@} -+download,@{section=".text",section-sent="6144",section-size="6668", -total-sent="6144",total-size="9880"@} -+download,@{section=".text",section-sent="6656",section-size="6668", -total-sent="6656",total-size="9880"@} -+download,@{section=".init",section-size="28",total-size="9880"@} -+download,@{section=".fini",section-size="28",total-size="9880"@} -+download,@{section=".data",section-size="3156",total-size="9880"@} -+download,@{section=".data",section-sent="512",section-size="3156", -total-sent="7236",total-size="9880"@} -+download,@{section=".data",section-sent="1024",section-size="3156", -total-sent="7748",total-size="9880"@} -+download,@{section=".data",section-sent="1536",section-size="3156", -total-sent="8260",total-size="9880"@} -+download,@{section=".data",section-sent="2048",section-size="3156", -total-sent="8772",total-size="9880"@} -+download,@{section=".data",section-sent="2560",section-size="3156", -total-sent="9284",total-size="9880"@} -+download,@{section=".data",section-sent="3072",section-size="3156", -total-sent="9796",total-size="9880"@} -^done,address="0x10004",load-size="9880",transfer-rate="6586", -write-rate="429" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-target-exec-status} Command -@findex -target-exec-status - -@subsubheading Synopsis - -@example - -target-exec-status -@end example - -Provide information on the state of the target (whether it is running or -not, for instance). - -@subsubheading @value{GDBN} Command - -There's no equivalent @value{GDBN} command. - -@subsubheading Example -N.A. - - -@subheading The @code{-target-list-available-targets} Command -@findex -target-list-available-targets - -@subsubheading Synopsis - -@example - -target-list-available-targets -@end example - -List the possible targets to connect to. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{help target}. - -@subsubheading Example -N.A. - - -@subheading The @code{-target-list-current-targets} Command -@findex -target-list-current-targets - -@subsubheading Synopsis - -@example - -target-list-current-targets -@end example - -Describe the current target. - -@subsubheading @value{GDBN} Command - -The corresponding information is printed by @samp{info file} (among -other things). - -@subsubheading Example -N.A. - - -@subheading The @code{-target-list-parameters} Command -@findex -target-list-parameters - -@subsubheading Synopsis - -@example - -target-list-parameters -@end example - -@c ???? - -@subsubheading @value{GDBN} Command - -No equivalent. - -@subsubheading Example -N.A. - - -@subheading The @code{-target-select} Command -@findex -target-select - -@subsubheading Synopsis - -@example - -target-select @var{type} @var{parameters @dots{}} -@end example - -Connect @value{GDBN} to the remote target. This command takes two args: - -@table @samp -@item @var{type} -The type of target, for instance @samp{async}, @samp{remote}, etc. -@item @var{parameters} -Device names, host names and the like. @xref{Target Commands, , -Commands for managing targets}, for more details. -@end table - -The output is a connection notification, followed by the address at -which the target program is, in the following form: - -@smallexample -^connected,addr="@var{address}",func="@var{function name}", - args=[@var{arg list}] -@end smallexample - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{target}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --target-select async /dev/ttya -^connected,addr="0xfe00a300",func="??",args=[] -(@value{GDBP}) -@end smallexample - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Thread Commands -@section @sc{gdb/mi} Thread Commands - - -@subheading The @code{-thread-info} Command -@findex -thread-info - -@subsubheading Synopsis - -@example - -thread-info -@end example - -@subsubheading @value{GDBN} command - -No equivalent. - -@subsubheading Example -N.A. - - -@subheading The @code{-thread-list-all-threads} Command -@findex -thread-list-all-threads - -@subsubheading Synopsis - -@example - -thread-list-all-threads -@end example - -@subsubheading @value{GDBN} Command - -The equivalent @value{GDBN} command is @samp{info threads}. - -@subsubheading Example -N.A. - - -@subheading The @code{-thread-list-ids} Command -@findex -thread-list-ids - -@subsubheading Synopsis - -@example - -thread-list-ids -@end example - -Produces a list of the currently known @value{GDBN} thread ids. At the -end of the list it also prints the total number of such threads. - -@subsubheading @value{GDBN} Command - -Part of @samp{info threads} supplies the same information. - -@subsubheading Example - -No threads present, besides the main process: - -@smallexample -(@value{GDBP}) --thread-list-ids -^done,thread-ids=@{@},number-of-threads="0" -(@value{GDBP}) -@end smallexample - - -Several threads: - -@smallexample -(@value{GDBP}) --thread-list-ids -^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, -number-of-threads="3" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-thread-select} Command -@findex -thread-select - -@subsubheading Synopsis - -@example - -thread-select @var{threadnum} -@end example - -Make @var{threadnum} the current thread. It prints the number of the new -current thread, and the topmost frame for that thread. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{thread}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --exec-next -^running -(@value{GDBP}) -*stopped,reason="end-stepping-range",thread-id="2",line="187", -file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" -(@value{GDBP}) --thread-list-ids -^done, -thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, -number-of-threads="3" -(@value{GDBP}) --thread-select 3 -^done,new-thread-id="3", -frame=@{level="0",func="vprintf", -args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@}, -@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@} -(@value{GDBP}) -@end smallexample - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Tracepoint Commands -@section @sc{gdb/mi} Tracepoint Commands - -The tracepoint commands are not yet implemented. - -@c @subheading -trace-actions - -@c @subheading -trace-delete - -@c @subheading -trace-disable - -@c @subheading -trace-dump - -@c @subheading -trace-enable - -@c @subheading -trace-exists - -@c @subheading -trace-find - -@c @subheading -trace-frame-number - -@c @subheading -trace-info - -@c @subheading -trace-insert - -@c @subheading -trace-list - -@c @subheading -trace-pass-count - -@c @subheading -trace-save - -@c @subheading -trace-start - -@c @subheading -trace-stop - - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Variable Objects -@section @sc{gdb/mi} Variable Objects - - -@subheading Motivation for Variable Objects in @sc{gdb/mi} - -For the implementation of a variable debugger window (locals, watched -expressions, etc.), we are proposing the adaptation of the existing code -used by @code{Insight}. - -The two main reasons for that are: - -@enumerate 1 -@item -It has been proven in practice (it is already on its second generation). - -@item -It will shorten development time (needless to say how important it is -now). -@end enumerate - -The original interface was designed to be used by Tcl code, so it was -slightly changed so it could be used through @sc{gdb/mi}. This section -describes the @sc{gdb/mi} operations that will be available and gives some -hints about their use. - -@emph{Note}: In addition to the set of operations described here, we -expect the @sc{gui} implementation of a variable window to require, at -least, the following operations: - -@itemize @bullet -@item @code{-gdb-show} @code{output-radix} -@item @code{-stack-list-arguments} -@item @code{-stack-list-locals} -@item @code{-stack-select-frame} -@end itemize - -@subheading Introduction to Variable Objects in @sc{gdb/mi} - -@cindex variable objects in @sc{gdb/mi} -The basic idea behind variable objects is the creation of a named object -to represent a variable, an expression, a memory location or even a CPU -register. For each object created, a set of operations is available for -examining or changing its properties. - -Furthermore, complex data types, such as C structures, are represented -in a tree format. For instance, the @code{struct} type variable is the -root and the children will represent the struct members. If a child -is itself of a complex type, it will also have children of its own. -Appropriate language differences are handled for C, C@t{++} and Java. - -When returning the actual values of the objects, this facility allows -for the individual selection of the display format used in the result -creation. It can be chosen among: binary, decimal, hexadecimal, octal -and natural. Natural refers to a default format automatically -chosen based on the variable type (like decimal for an @code{int}, hex -for pointers, etc.). - -The following is the complete set of @sc{gdb/mi} operations defined to -access this functionality: - -@multitable @columnfractions .4 .6 -@item @strong{Operation} -@tab @strong{Description} - -@item @code{-var-create} -@tab create a variable object -@item @code{-var-delete} -@tab delete the variable object and its children -@item @code{-var-set-format} -@tab set the display format of this variable -@item @code{-var-show-format} -@tab show the display format of this variable -@item @code{-var-info-num-children} -@tab tells how many children this object has -@item @code{-var-list-children} -@tab return a list of the object's children -@item @code{-var-info-type} -@tab show the type of this variable object -@item @code{-var-info-expression} -@tab print what this variable object represents -@item @code{-var-show-attributes} -@tab is this variable editable? does it exist here? -@item @code{-var-evaluate-expression} -@tab get the value of this variable -@item @code{-var-assign} -@tab set the value of this variable -@item @code{-var-update} -@tab update the variable and its children -@end multitable - -In the next subsection we describe each operation in detail and suggest -how it can be used. - -@subheading Description And Use of Operations on Variable Objects - -@subheading The @code{-var-create} Command -@findex -var-create - -@subsubheading Synopsis - -@example - -var-create @{@var{name} | "-"@} - @{@var{frame-addr} | "*"@} @var{expression} -@end example - -This operation creates a variable object, which allows the monitoring of -a variable, the result of an expression, a memory cell or a CPU -register. - -The @var{name} parameter is the string by which the object can be -referenced. It must be unique. If @samp{-} is specified, the varobj -system will generate a string ``varNNNNNN'' automatically. It will be -unique provided that one does not specify @var{name} on that format. -The command fails if a duplicate name is found. - -The frame under which the expression should be evaluated can be -specified by @var{frame-addr}. A @samp{*} indicates that the current -frame should be used. - -@var{expression} is any expression valid on the current language set (must not -begin with a @samp{*}), or one of the following: - -@itemize @bullet -@item -@samp{*@var{addr}}, where @var{addr} is the address of a memory cell - -@item -@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD) - -@item -@samp{$@var{regname}} --- a CPU register name -@end itemize - -@subsubheading Result - -This operation returns the name, number of children and the type of the -object created. Type is returned as a string as the ones generated by -the @value{GDBN} CLI: - -@example - name="@var{name}",numchild="N",type="@var{type}" -@end example - - -@subheading The @code{-var-delete} Command -@findex -var-delete - -@subsubheading Synopsis - -@example - -var-delete @var{name} -@end example - -Deletes a previously created variable object and all of its children. - -Returns an error if the object @var{name} is not found. - - -@subheading The @code{-var-set-format} Command -@findex -var-set-format - -@subsubheading Synopsis - -@example - -var-set-format @var{name} @var{format-spec} -@end example - -Sets the output format for the value of the object @var{name} to be -@var{format-spec}. - -The syntax for the @var{format-spec} is as follows: - -@example - @var{format-spec} @expansion{} - @{binary | decimal | hexadecimal | octal | natural@} -@end example - - -@subheading The @code{-var-show-format} Command -@findex -var-show-format - -@subsubheading Synopsis - -@example - -var-show-format @var{name} -@end example - -Returns the format used to display the value of the object @var{name}. - -@example - @var{format} @expansion{} - @var{format-spec} -@end example - - -@subheading The @code{-var-info-num-children} Command -@findex -var-info-num-children - -@subsubheading Synopsis - -@example - -var-info-num-children @var{name} -@end example - -Returns the number of children of a variable object @var{name}: - -@example - numchild=@var{n} -@end example - - -@subheading The @code{-var-list-children} Command -@findex -var-list-children - -@subsubheading Synopsis - -@example - -var-list-children @var{name} -@end example - -Returns a list of the children of the specified variable object: - -@example - numchild=@var{n},children=[@{name=@var{name}, - numchild=@var{n},type=@var{type}@},@r{(repeats N times)}] -@end example - - -@subheading The @code{-var-info-type} Command -@findex -var-info-type - -@subsubheading Synopsis - -@example - -var-info-type @var{name} -@end example - -Returns the type of the specified variable @var{name}. The type is -returned as a string in the same format as it is output by the -@value{GDBN} CLI: - -@example - type=@var{typename} -@end example - - -@subheading The @code{-var-info-expression} Command -@findex -var-info-expression - -@subsubheading Synopsis - -@example - -var-info-expression @var{name} -@end example - -Returns what is represented by the variable object @var{name}: - -@example - lang=@var{lang-spec},exp=@var{expression} -@end example - -@noindent -where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}. - -@subheading The @code{-var-show-attributes} Command -@findex -var-show-attributes - -@subsubheading Synopsis - -@example - -var-show-attributes @var{name} -@end example - -List attributes of the specified variable object @var{name}: - -@example - status=@var{attr} [ ( ,@var{attr} )* ] -@end example - -@noindent -where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}. - -@subheading The @code{-var-evaluate-expression} Command -@findex -var-evaluate-expression - -@subsubheading Synopsis - -@example - -var-evaluate-expression @var{name} -@end example - -Evaluates the expression that is represented by the specified variable -object and returns its value as a string in the current format specified -for the object: - -@example - value=@var{value} -@end example - -Note that one must invoke @code{-var-list-children} for a variable -before the value of a child variable can be evaluated. - -@subheading The @code{-var-assign} Command -@findex -var-assign - -@subsubheading Synopsis - -@example - -var-assign @var{name} @var{expression} -@end example - -Assigns the value of @var{expression} to the variable object specified -by @var{name}. The object must be @samp{editable}. If the variable's -value is altered by the assign, the variable will show up in any -subsequent @code{-var-update} list. - -@subsubheading Example - -@example -(@value{GDBP}) --var-assign var1 3 -^done,value="3" -(@value{GDBP}) --var-update * -^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}] -(@value{GDBP}) -@end example - -@subheading The @code{-var-update} Command -@findex -var-update - -@subsubheading Synopsis - -@example - -var-update @{@var{name} | "*"@} -@end example - -Update the value of the variable object @var{name} by evaluating its -expression after fetching all the new values from memory or registers. -A @samp{*} causes all existing variable objects to be updated. |