| \input texinfo @c -*-texinfo-*- |
| @c %**start of header |
| @setfilename gdbmi.info |
| @settitle GDB/MI Machine Interface |
| @setchapternewpage off |
| @c %**end of header |
| |
| @ifinfo |
| This file documents GDB/MI, a Machine Interface to GDB. |
| |
| Copyright (C) 2000, Free Software Foundation, Inc. |
| Contributed by Cygnus Solutions. |
| |
| Permission is granted to make and distribute verbatim copies of this |
| manual provided the copyright notice and this permission notice are |
| preserved on all copies. |
| |
| @ignore |
| Permission is granted to process this file through TeX and print the |
| results, provided the printed document carries copying permission notice |
| identical to this one except for the removal of this paragraph (this |
| paragraph not being relevant to the printed manual). |
| |
| @end ignore |
| Permission is granted to copy and distribute modified versions of this |
| manual under the conditions for verbatim copying, provided also that the |
| entire resulting derived work is distributed under the terms of a |
| permission notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this manual |
| into another language, under the above conditions for modified versions. |
| @end ifinfo |
| |
| @c This title page illustrates only one of the |
| @c two methods of forming a title page. |
| |
| @titlepage |
| @title GDB/MI |
| @subtitle Version 0.2 |
| @subtitle Feb 2000 |
| @author Andrew Cagney, Fernando Nasser and Elena Zannoni |
| |
| @c The following two commands |
| @c start the copyright page. |
| @page |
| @vskip 0pt plus 1filll |
| Permission is granted to make and distribute verbatim copies of this |
| manual provided the copyright notice and this permission notice are |
| preserved on all copies. |
| |
| Copyright @copyright{} 2000, Free Software Foundation, Inc. |
| @end titlepage |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Overview |
| |
| @heading Function and Purpose |
| |
| GDB/MI is a line based machine oriented text interface to GDB. It is |
| specifically intended to support the development of systems which use |
| the debugger as just one small component of a larger system. |
| |
| @heading This Document |
| |
| This document is a specification of the GDB/MI interface. It is written |
| in the form of a reference manual. |
| |
| @heading Terminology |
| |
| @heading Dependencies |
| |
| @heading Acknowledgments |
| |
| In alphabetic order: Fernando Nasser, Stan Shebs and Elena Zannoni. |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Command Syntax |
| |
| @section Input Syntax |
| |
| @table @code |
| |
| @item <command> @expansion{} |
| <cli-command> | <mi-command> |
| |
| @item <cli-command> @expansion{} |
| [ <token> ] "any existing GDB CLI command" <nl> |
| |
| @item <mi-command> @expansion{} |
| [ <token> ] ``-'' <operation> ( `` '' <option> )* [ `` --'' ] ( `` '' <parameter> )* <nl> |
| |
| @item <token> @expansion{} |
| ``any sequence of digits'' |
| |
| @item <option> @expansion{} |
| ``-'' <parameter> [ `` '' <parameter> ] |
| |
| @item <parameter> @expansion{} |
| <non-blank-sequence> | <c-string> |
| |
| @item <operation> @expansion{} |
| any of the operations described in this document. |
| |
| @item <non-blank-sequence> @expansion{} |
| anything provided it doesn't contain special characters such as ``-'' |
| <nl>, ``"'' and of course `` ''. |
| |
| @item <c-string> @expansion{} |
| ``"'' <seven-bit-iso-c-string-content> ``"'' |
| |
| @item <nl> @expansion{} |
| CR | CR-LF |
| |
| @end table |
| |
| Notes: |
| |
| @itemize @bullet |
| |
| @item |
| The CLI commands are still handled by the MI interpreter; their output |
| is described below |
| |
| @item |
| The @code{<token>}, when present, is passed back when the command |
| finishes. |
| |
| @item |
| Some mi commands accept optional arguments as part of the parameter |
| list. Each option is identified by a leading @code{-} (dash) and may be |
| followed by an option argument parameter. Options occure first in the |
| parameter list and can be delimiated from normal parameters using |
| @code{--}. |
| |
| @end itemize |
| |
| Pragmatics: |
| |
| @itemize @bullet |
| |
| @item |
| We want easy access to the existing CLI syntax (for debugging). |
| |
| @item |
| We want it easy to spot a MI operation |
| |
| @end itemize |
| |
| @section Output Syntax |
| |
| The output from GDB/MI consists of zero or more out-of-band records |
| followed, optionally, by a single result record. The result record |
| being for the most recent command. The sequence of output records is |
| terminated by ``(gdb)''. |
| |
| If an input command was prefixed with a @code{<token>} then the |
| corresponding output for that command will also be prefixed by that same |
| token. |
| |
| @table @code |
| @item <output> @expansion{} |
| ( <out-of-band-record> )* [ <result-record> ] ``(gdb)'' <nl> |
| |
| @item <result-record> @expansion{} |
| [ <token> ] ``^'' <result-class> ( ``,'' <result> )* <nl> |
| |
| @item <out-of-band-record> @expansion{} |
| <async-record> | <stream-record> |
| |
| @item <async-record> @expansion{} |
| <exec-async-output> | <status-async-output> | <notify-async-output> |
| |
| @item <exec-async-output> @expansion{} |
| [ <token> ] ``*'' <async-output> |
| |
| @item <status-async-output> @expansion{} |
| [ <token> ] ``+'' <async-output> |
| |
| @item <notify-async-output> @expansion{} |
| [ <token> ] ``='' <async-output> |
| |
| @item <async-output> @expansion{} |
| <async-class> ( ``,'' <result> )* <nl> |
| |
| @item <result-class> @expansion{} |
| ``done'' | ``running'' | ``connected'' | ``error'' | ``exit'' |
| |
| @item <async-class> @expansion{} |
| ``stopped'' | others (depending on needs, still in development) |
| |
| @item <result> @expansion{} |
| [ <string> ``='' ] <value> |
| |
| @item <value> @expansion{} |
| <const> | ``@{'' <result> ( ``,'' <result> )* ``@}'' |
| |
| @item <const> @expansion{} |
| <c-string> |
| |
| @item <stream-record> @expansion{} |
| <console-stream-output> | <target-stream-output> | <log-stream-output> |
| |
| @item <console-stream-output> @expansion{} |
| ``~'' <c-string> |
| |
| @item <target-stream-output> @expansion{} |
| ``@@'' <c-string> |
| |
| @item <log-stream-output> @expansion{} |
| ``&'' <c-string> |
| |
| @item <nl> @expansion{} |
| CR | CR-LF |
| |
| @item <token> @expansion{} |
| ``any sequence of digits'' |
| |
| @end table |
| |
| In addition, the following are still being developed. |
| |
| @table @code |
| |
| @item <query> |
| This action is currently undefined. |
| |
| @end table |
| |
| Notes: |
| |
| @itemize @bullet |
| |
| @item |
| All output sequences end in a single line containing a period. |
| |
| @item |
| The @code{<token>} is from the corresponding request. If an execution |
| command is interrupted by the -exec-interrupt command, the token |
| associated with the `*stopped' message is the one of the original |
| execution command, not the one of the interrupt-command. |
| |
| @item |
| <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 |
| the prefix `+'. |
| |
| @item |
| <exec-async-output> contains asynchronous state change on the target |
| (stopped, started, disappeared). All async output is prefixed by |
| the prefix `*'. |
| |
| @item |
| <notify-async-output> contains supplementary information that the client should |
| handle (new breakpoint information). All notify output is prefixed by |
| the prefix `='. |
| |
| @item |
| <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 the prefix ``~''. |
| |
| @item |
| <target-stream-output> is the output produced by the target program. |
| All the target output is prefixed by the prefix ``@@''. |
| |
| @item |
| <log-stream-output> is output text coming from GDB's internals, for |
| instance messages that should be displayed as part of an error log. All |
| the log output is prefixed by the prefix ``&''. |
| |
| @end itemize |
| |
| @section Simple Examples |
| |
| @subheading Target stop: |
| |
| @example |
| -> -stop |
| <- (gdb) |
| @end example |
| |
| (later) |
| |
| @example |
| <- *stop,reason="stop",address="0x123",source="a.c:123" |
| <- (gdb) |
| @end example |
| |
| |
| @subheading Simple CLI command being passed through the MI and on to the CLI. |
| |
| @example |
| -> print 1+2 |
| <- ~3\n |
| <- (gdb) |
| @end example |
| |
| |
| @subheading Command with side effects: |
| |
| @example |
| -> -symbol-file xyz.exe |
| <- *breakpoint,nr="3",address="0x123",source="a.c:123" |
| <- (gdb) |
| @end example |
| |
| |
| @subheading A bad command: |
| |
| @example |
| -> -rubbish |
| <- error,"Rubbish not found" |
| <- (gdb) |
| @end example |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter CLI compatibility |
| |
| To help users familiar with the GDB's existing CLI interface, the GDB/MI |
| will accept existing CLI commands. As specified by the syntax, such |
| commands can be directly entered into the MI interface and GDB will |
| respond. |
| |
| The mechanism is provided as an aid to developers of MI clients and not |
| as a reliable interface into the CLI. Since the command is being |
| interpreteted in an environment that assumes MI behaviour the exact |
| output of such commands is likely to end up being an un-supported hybrid |
| of MI and CLI output. |
| |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Output Records |
| |
| @section Result Records |
| |
| In addition to a number of out-of-band notifications the response to an |
| MI command includes one of the following result indications. |
| |
| @table @code |
| |
| @item ``^done'' [ ``,'' <results> ] |
| The synchronous operation was successful, @code{<results>} is the return |
| value. |
| |
| @item ``^running'' |
| The asynchronous operation was successfully started. The target is |
| running. @emph{Is this one correct should it be an out-of-band |
| notification?} |
| |
| @item ``^error'' ``,'' <c-string> |
| The operation failed. The @code{<c-string>} contains the corresponding |
| error message. |
| |
| @end table |
| |
| @section Stream Records |
| |
| GDB internally maintains a number of output streams: the console, the |
| target, and the log. The output intended for each of these streams is |
| tunneled through the MI interface using stream records. |
| |
| In addition to the prefix each stream record contains a |
| @code{<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 ``~'' <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 ``@@'' <string-output> |
| The target output stream contains any textual output from the running |
| target. |
| |
| @item ``&'' <string-output> |
| The LOG stream contains debugging messages being produced by GDB's |
| internals. |
| |
| @end table |
| |
| @section Out-of-band Records. |
| |
| Out-of-band records are used to notify the MI client of additional |
| changes that have occurred. Those changes can either be a consequence of |
| an MI (breakpoint modified) or as a result of target activity (target |
| stopped). |
| |
| The following is a preliminary list of possible out-of-band records. |
| |
| @table @code |
| |
| @item ``*'' ``stop'' |
| |
| @end table |
| |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Command Description Format |
| |
| The remaining chapters describe blocks of commands. Each block of |
| commands is laid out in a fashion similar to this chapter. |
| |
| Note the the line breaks shown in the examples are here only for |
| readability. They don't appear in the real output. |
| Note that the commands with a non available example (N.A.) are not yet |
| implemented. |
| |
| @section Motivation |
| |
| What motivates the collection of commands |
| |
| @section Introduction |
| |
| Brief introduction to the commands as a whole. |
| |
| @section Operations |
| |
| @subsection -command <args>... |
| |
| @subsubsection Result |
| |
| @subsubsection Out-of-band |
| |
| @subsubsection Notes |
| |
| @subsubsection Example |
| |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Breakpoint table commands |
| |
| @section -break-after <number> <count> |
| The breakpoint number <number> is not in effect until it has been hit <count> times. |
| Note how this is reflected in the output of the -break-list command. |
| |
| @subsection GDB command |
| ignore |
| |
| @subsection Example |
| @example |
| (gdb) |
| -break-insert main |
| ^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@} |
| (gdb) |
| -break-after 1 3 |
| ~ |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@}, |
| bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",line="5",times="0",ignore="3"@}@} |
| (gdb) |
| @end example |
| |
| @c @section -break-catch |
| |
| @c @section -break-commands |
| |
| @section -break-condition <number> <expr> |
| Breakpoint <number> will stop the program only if the condition in <expr> is true. |
| The condition becomes part of the -break-list output. |
| @subsection GDB command |
| condition |
| @subsection Example |
| @example |
| (gdb) |
| -break-condition 1 1 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@}, |
| bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",times="0",ignore="3"@}@} |
| (gdb) |
| @end example |
| |
| @section -break-delete @{ <breakpoint> @}+ |
| Delete the breakpoint(s) specified in the argument list. This is |
| obviously reflected in the breakpoint list. |
| @subsection GDB command |
| delete |
| @subsection Example |
| @example |
| (gdb) |
| -break-delete 1 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable=@{@} |
| (gdb) |
| @end example |
| |
| @section -break-disable @{ <breakpoint> @}+ |
| Disable the breakpoint(s). Note how the field 'enabled' in the break |
| list is now set to 'n'. |
| @subsection GDB command |
| disable |
| @subsection Example |
| @example |
| (gdb) |
| -break-disable 2 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@}, |
| bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n", |
| addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@} |
| (gdb) |
| @end example |
| |
| @section -break-enable @{ <breakpoint> @}+ |
| Enable a previously disabled breakpoint(s). |
| @subsection GDB command |
| enable |
| @subsection Example |
| @example |
| (gdb) |
| enable 2 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@}, |
| bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}@} |
| (gdb) |
| @end example |
| |
| @section -break-info <breakpoint> |
| REDUNDANT??? Get information about a single breakpoint. |
| @subsection GDB command |
| @subsection Example |
| N.A. |
| |
| @section -break-insert [ "-t" ] [ "-h" ] [ "-r" ] [ "-c" <condition> ] [ "-i" <ignore-count> ] [ "-p" <thread> ] [ <line> | <addr> ] |
| |
| <line>, if specified, accordingly to the gdb manual 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 forms of this command are: |
| |
| @table @samp |
| @item -t |
| Insert a tempoary breakpoint. |
| @item -h |
| Insert a hardware breakpoint. |
| @item -c <condition> |
| Make the breakpoint conditional on <condition> |
| @item -i <ignore-count> |
| Initialize the <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 |
| |
| |
| The result is in the form: |
| |
| ^done,bkptno="<gdb number for this breakpoint>",func="<name of the |
| function where the breakpoint was inserted>",file="<source file which |
| contains this function>",line="<source line number within the file>" |
| |
| Note: this is open to change. An out-of-band breakpoint instead of part |
| of the result? |
| @subsection GDB command |
| break, tbreak, hbreak, thbreak, rbreak. |
| @subsection Example |
| @example |
| (gdb) |
| -break-insert main |
| ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} |
| (gdb) |
| -break-insert -t foo |
| ^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@}, |
| 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"@}@} |
| (gdb) |
| -break-insert -r foo.* |
| ~int foo(int, int); |
| ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@} |
| (gdb) |
| @end example |
| |
| @section -break-list |
| Displays the list of inserted breakpoints, showing the following fields: |
| @table @samp |
| @item Number |
| Number of the breakpoint |
| @item Type |
| Type of the breakpoint: breakpoint or watchpoint |
| @item Disposition |
| Should the breakpoint be deleted or disabled when it is hit: keep or nokeep |
| @item Enabled |
| Is the breakpoint enabled or no: y or 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 BreakpointTable field is |
| an empty list. |
| @subsection GDB command |
| info break |
| |
| @subsection Example 1 |
| @example |
| (gdb) |
| -break-list |
| ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@}, |
| 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"@}@} |
| (gdb) |
| @end example |
| @subsection Example 2 |
| @example |
| (gdb) |
| -break-list |
| ^done,BreakpointTable=@{@} |
| (gdb) |
| @end example |
| |
| @section -break-watch [ "-a" | "-r" ] |
| Create a watchpoint. With the ``-a'' option it will create an access |
| watchpoint, i.e. a watchpoints that triggers either on a read or on a |
| write on the memory location. With the ``-r'' option, the watchoint |
| created is a read watchpoint, i.e. it will trigger only when the memory |
| location os accessed for reading. Without either of the options, the |
| watchpoint created is a regular watchpoint, i.e. it will trigger whe the |
| memory location is accessed for writing. |
| |
| Note that ``-break-list'' will report a single list of watchpoints and |
| breakpoints inserted. |
| |
| @subsection GDB command |
| watch, awatch, rwatch |
| |
| @subsection Example 1 |
| Watchpoint on a variable in main(). |
| @example |
| (gdb) |
| -break-watch x |
| ^done,wpt=@{number="2",exp="x"@} |
| (gdb) |
| -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"@} |
| (gdb) |
| @end example |
| @subsection Example 2 |
| Watchpoint on a variable local to a function. Gdb will stop the program execution |
| twice: first for the variable changing value, then for the watchpoint going out of scope. |
| @example |
| (gdb) |
| -break-watch C |
| ^done,wpt=@{number="5",exp="C"@} |
| (gdb) |
| -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"@} |
| (gdb) |
| -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"@} |
| (gdb) |
| @end example |
| |
| @subsection Example 3 |
| Listing breakpoints and watchpoints, at different points in the program execution. |
| Note that once the watchpoint goes out of scope, it is deleted. |
| @example |
| (gdb) |
| -break-watch C |
| ^done,wpt=@{number="2",exp="C"@} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@}, |
| 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"@}@} |
| (gdb) |
| -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"@} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@}, |
| 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"@}@} |
| (gdb) |
| -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"@} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable=@{hdr=@{"Num","Type","Disp","Enb","Address","What"@}, |
| 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"@}@} |
| (gdb) |
| @end example |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Data manipulation |
| |
| @c REMOVED FROM THE ITNERFACE. |
| @c @section -data-assign |
| @c Change the value of a program variable. Plenty of side effects. |
| @c @subsection GDB command |
| @c set variable |
| @c @subsection Example |
| @c N.A. |
| |
| @section -data-disassemble ( -s <start-addr> -e <end-addr> ) | (-f <filename> -l <linenum> [-n <lines> ]] -- <mode> |
| Where |
| @table @samp |
| @item <start-addr> |
| Is the beginning address (or $pc). |
| @item <end-addr> |
| End address. |
| @item <filename> |
| Name of the file to disassemble. |
| @item <linenum> |
| Line number to disassemble around. |
| @item <number-of-lines> |
| specifies the number of disassembly lines to be produced. If it is -1 |
| the whole function will be disassembled, in case no <end> address is |
| specified. If <end> is specified as a non-zero value, and |
| <number-of-lines> is lower that the number of disassembly lines between |
| <begin> and <end>, we'll display only <number-of-lines> lines, vice |
| versa if <number-of-lines> is higher than the number of lines between |
| <begin> and <end>, we'll display only the lines up to <end>. |
| @item <mode> |
| can be 0 (only disassembly) or 1 (mixed source and disassembly). |
| @end table |
| |
| The output for each instruction is composed of two 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 Flathead, i.e. it is not possible to adjust its format. |
| @subsection GDB command |
| N.A. No direct mapping. |
| |
| @subsection Example 1 |
| Disassemble from the current PC value to PC + 20. |
| |
| @example |
| (gdb) |
| -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>"}} |
| (gdb) |
| @end example |
| |
| @subsection Example 2 |
| Disassemble the whole function main. Line 32 is part of main. |
| @example |
| -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"}, |
| [...] |
| {address="0x0001081c",func-name="main",offset="96",inst="ret "}, |
| {address="0x00010820",func-name="main",offset="100",inst="restore "}} |
| (gdb) |
| @end example |
| |
| @subsection Example 3 |
| Disassemble 3 instruction from the start of main. |
| @example |
| (gdb) |
| -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"}} |
| (gdb) |
| @end example |
| |
| @subsection Example 4 |
| Disassemble 3 instruction from the start of main in mixed mode. |
| @example |
| (gdb) |
| -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"}}}} |
| (gdb) |
| @end example |
| |
| @section -data-evaluate-expression |
| Evaluate 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. |
| @subsection GDB command |
| print, output, gdb_eval |
| @subsection Example |
| @example |
| 211-data-evaluate-expression A |
| 211^done,value="1" |
| (gdb) |
| 311-data-evaluate-expression &A |
| 311^done,value="0xefffeb7c" |
| (gdb) |
| 411-data-evaluate-expression A+3 |
| 411^done,value="4" |
| (gdb) |
| 511-data-evaluate-expression "A + 3" |
| 511^done,value="4" |
| (gdb) |
| @end example |
| |
| @section -data-list-changed-registers |
| Display a list of the registers that have changed. |
| @subsection GDB command |
| gdb_changed_register_list. This is in gdbtk only. |
| @subsection Example |
| On a PPC MBX board. |
| @example |
| (gdb) |
| -exec-continue |
| ^running |
| |
| (gdb) |
| *stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main", |
| args=@{@},file="try.c",line="5"@} |
| (gdb) |
| -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"@} |
| (gdb) |
| @end example |
| |
| @section -data-list-register-names |
| 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 corresponding to the arguments. |
| @subsection GDB command |
| gdb_regnames |
| @subsection Example |
| For the PPC MBX board: |
| @example |
| (gdb) |
| -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"@} |
| (gdb) |
| -data-list-register-names 1 2 3 |
| ^done,register-names=@{"r1","r2","r3"@} |
| (gdb) |
| @end example |
| |
| @section -data-list-register-values |
| Display the registers contents. Arguments are the format according to |
| which the registers contents are to be returned, and a list of numbers |
| specifying the registers to display. A missing list of number indicates |
| that the contents of all the registers must be returned. |
| Allowed formats are: |
| @itemize @bullet |
| @item 'x': Hexadecimal |
| @item 'o': Octal |
| @item 't': Binary |
| @item 'd': Decimal |
| @item 'r': Raw |
| @item 'N': Natural |
| @end itemize |
| |
| @subsection GDB command |
| info reg, info all-reg AND/OR gdb_fetch_registers |
| @subsection Example |
| For a PPC MBX board. Note, line breaks are for readability only, they |
| don't appear in the actual output. |
| @example |
| (gdb) |
| -data-list-register-values r 64 65 |
| ^done,register-values=@{@{number="64",value="0xfe00a300"@}, |
| @{number="65",value="0x00029002"@}@} |
| (gdb) |
| -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"@}@} |
| (gdb) |
| @end example |
| |
| @section -data-read-memory [ -o <byte-offset> ] [ -- ] <address> <word-format> <word-size> <nr-rows> <nr-cols> [ <aschar> ] |
| Where |
| @table @samp |
| @item <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 <word-format> |
| The format to be used to print the memory words. The notation is the |
| same as for GDB's @code{print} command. |
| @item <word-size> |
| The size of each memory word in bytes. |
| @item <nr-rows> |
| The number of rows in the output table. |
| @item <nr-cols> |
| The number of columns in the output table. |
| @item <aschar> |
| If present, indicates that each row should include an ascii dump. The |
| value of <aschar> is used as a padding character when a byte is not a |
| member of the printable ascii character set (@code{<32} or @code{>126}). |
| @item <byte-offset> |
| An offset to add to the <address> before fetching memory. |
| @end table |
| Display memory contents as a table of <nr-rows> by <nr-cols> words. |
| Each word being <word-size> bytes. In total @code{<nr-rows> * <nr-cols> |
| * <word-size>} bytes are read (returned as @code{total-bytes}. Should |
| less then the requested number of bytes be returned by the target, the |
| missing words are identified using @code{N/A}. The number of bytes read |
| from the target is returned in @code{nr-bytes} and the starting address |
| used to read memory by @code{addr}. |
| |
| The address of the next/previous page or row is available in |
| @code{next-row} and @code{prev-row}, @code{next-page} and |
| @code{prev-page}. |
| @subsection GDB command |
| x AND/OR gdb_get_mem AND/OR GDBtk's memory read. |
| @subsection Example 1 |
| 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. |
| @example |
| (gdb) |
| 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"@}@}@} |
| (gdb) |
| @end example |
| @subsection Example 2 |
| Read two bytes of memory starting at address @code{shorts + 64} and |
| display as a single word formatted in decimal. |
| @example |
| (gdb) |
| 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"@}@}@} |
| (gdb) |
| @end example |
| @subsection Example 3 |
| Read thirty two bytes of memory starting at @code{bytes+16} and format |
| as eight rows of four columns. Include a string encoding with @code{x} |
| used as the non-printable character. |
| @example |
| (gdb) |
| 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=",-./"@}@} |
| (gdb) |
| @end example |
| |
| @section -display-delete <number> |
| Delete the display <number>. |
| @subsection GDB command |
| delete display |
| @subsection Example |
| N.A. |
| |
| @section -display-disable <number> |
| Disable display <number> |
| @subsection GDB command |
| disable display |
| @subsection Example |
| N.A. |
| |
| @section -display-enable <number> |
| Enable display <number> |
| @subsection GDB command |
| enable display |
| @subsection Example |
| N.A. |
| |
| @section -display-insert <expression> |
| Display <expression> every time the program stops. |
| @subsection GDB command |
| display |
| @subsection Example |
| N.A. |
| |
| @section -display-list |
| List the displays. Do not show the current values. |
| @subsection GDB command |
| info display |
| @subsection Example |
| N.A. |
| |
| @section -environment-cd <pathdir> |
| Set GDB's working directory. |
| @subsection GDB command |
| cd |
| @subsection Example |
| @example |
| (gdb) |
| -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb |
| ^done |
| (gdb) |
| @end example |
| |
| @section -environment-directory <pathdir> |
| Add directory <pathdir> to beginning of search path for source files. |
| @subsection GDB command |
| dir |
| @subsection Example |
| @example |
| (gdb) |
| -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb |
| ^done |
| (gdb) |
| @end example |
| |
| @section -environment-path @{ <pathdir> @}+ |
| Add directories to beginning of search path for object files. |
| @subsection GDB command |
| path |
| @subsection Example |
| @example |
| (gdb) |
| -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb |
| ^done |
| (gdb) |
| @end example |
| |
| @section -environment-pwd |
| Show the current working directory |
| @subsection GDB command |
| pwd |
| @subsection Example |
| @example |
| (gdb) |
| -environment-pwd |
| ~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb. |
| ^done |
| (gdb) |
| @end example |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Program control |
| |
| @section Program termination |
| As a result of execution, the inferior program can run to completion, if |
| it doesn't encouter any breakpoints. In this case the ouput will |
| include an exit code, if the program has exited exceptionally. |
| @subsection Example 1 |
| Program exited normally: |
| @example |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="exited-normally" |
| (gdb) |
| @end example |
| |
| @subsection Example 2 |
| Program exited exceptionally: |
| @example |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="exited",exit-code="01" |
| (gdb) |
| @end example |
| |
| Another way the program can terminate is if it receives a signal like SIGINT. |
| @subsection Example |
| Program exited with signal (for a more complete example, see the exec-interrupt command). |
| @example |
| (gdb) |
| *stopped,reason="exited-signalled",signal-name="SIGINT",signal-meaning="Interrupt" |
| @end example |
| |
| |
| @section -exec-abort |
| Kill the inferior running program. |
| |
| @subsection GDB command |
| kill |
| |
| @subsection Example |
| N.A. |
| |
| @section -exec-arguments |
| Set the inferior program arguments, to be used in the next -exec-run. |
| |
| @subsection GDB command |
| set args |
| |
| @subsection Example |
| Don't have it around. |
| |
| @section -exec-continue |
| Asynchronous command. Resumes the execution of the inferior program until |
| a breakpoint is encountered, or the inferior exits. |
| |
| @subsection GDB command |
| continue |
| |
| @subsection Example |
| @example |
| -exec-continue |
| ^running |
| (gdb) |
| @@Hello world |
| *stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=@{@}, |
| file="hello.c",line="13"@} |
| (gdb) |
| @end example |
| |
| @section -exec-finish |
| Asynchronous command. Resumes the execution of the inferior program until the |
| current function is exited. Displays the results returned by the function (???). |
| |
| @subsection GDB command |
| finish |
| |
| @subsection Example 1 |
| Function returning 'void'. |
| @example |
| -exec-finish |
| ^running |
| (gdb) |
| @@hello from foo |
| *stopped,reason="function-finished",frame=@{func="main",args=@{@}, |
| file="hello.c",line="7"@} |
| (gdb) |
| @end example |
| @subsection Example 2 |
| Function returning other than 'void'. The name of the internal gdb variable storing the |
| result is printed, and the value itself. |
| @example |
| -exec-finish |
| ^running |
| (gdb) |
| *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" |
| (gdb) |
| |
| @end example |
| @section -exec-interrupt |
| 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 '^done' output. If the user is trying to |
| interrupt a non running program, an error message will be printed. |
| @subsection GDB command |
| interrupt |
| |
| @subsection Example |
| @example |
| (gdb) |
| 111-exec-continue |
| 111^running |
| |
| (gdb) |
| 222-exec-interrupt |
| 222^done |
| (gdb) |
| 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", |
| frame=@{addr="0x00010140",func="foo",args=@{@},file="try.c",line="13"@} |
| (gdb) |
| |
| (gdb) |
| -exec-interrupt |
| ^error,msg="mi_cmd_exec_interrupt: Inferior not executing." |
| (gdb) |
| |
| @end example |
| |
| @section -exec-next |
| Asynchronous command. Resumes execution of the inferior program, stopping |
| when the beginning of the next source line is reached. |
| |
| @subsection GDB command |
| next |
| |
| @subsection Example |
| @example |
| -exec-next |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",line="8",file="hello.c" |
| (gdb) |
| @end example |
| |
| @section -exec-next-instruction |
| 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. |
| @subsection GDB command |
| nexti |
| |
| @subsection Example |
| @example |
| (gdb) |
| -exec-next-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| addr="0x000100d4",line="5",file="hello.c" |
| (gdb) |
| @end example |
| |
| @section -exec-return |
| Makes current function return immediately. Doesn't execute the inferior. |
| It displays the new current frame. |
| |
| @subsection GDB command |
| return |
| |
| @subsection Example |
| @example |
| (gdb) |
| 200-break-insert callee4 |
| 200^done,bkpt=@{number="1",addr="0x00010734", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} |
| (gdb) |
| 000-exec-run |
| 000^running |
| (gdb) |
| 000*stopped,reason="breakpoint-hit",bkptno="1", |
| frame=@{func="callee4",args=@{@}, |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} |
| (gdb) |
| 205-break-delete |
| 205^done |
| (gdb) |
| 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"@} |
| (gdb) |
| @end example |
| |
| @section -exec-run |
| Asynchronous command. Starts execution of the inferior from the |
| beginning. The inferior executes until either a breakpoint is |
| encountered or the program exits. |
| |
| @subsection GDB command |
| run |
| |
| @subsection Example |
| @example |
| (gdb) |
| -break-insert main |
| ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| *stopped,reason="breakpoint-hit",bkptno="1", |
| frame=@{func="main",args=@{@},file="recursive2.c",line="4"@} |
| (gdb) |
| @end example |
| |
| |
| @section -exec-show-arguments |
| Print the arguments of the program. |
| @subsection GDB command |
| show args |
| @subsection Example |
| N.A. |
| |
| @c @section -exec-signal |
| |
| @section -exec-step |
| 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. |
| |
| @subsection GDB command |
| step |
| |
| @subsection Example 1 |
| Stepping into a function: |
| @example |
| -exec-step |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",frame=@{func="foo",args=@{@{name="a",value="10"@}, |
| @{name="b",value="0"@}@},file="recursive2.c",line="11"@} |
| (gdb) |
| @end example |
| @subsection Example 2 |
| Regular stepping |
| @example |
| -exec-step |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",line="14",file="recursive2.c" |
| (gdb) |
| @end example |
| |
| @section -exec-step-instruction |
| Asynchronous command. Resumes the inferior which executes one machine |
| instruction. The output, once stop, will vary depend 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. |
| |
| @subsection GDB command |
| stepi |
| |
| @subsection Example |
| @example |
| (gdb) |
| -exec-step-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| frame=@{func="foo",args=@{@},file="try.c",line="10"@} |
| (gdb) |
| -exec-step-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| frame=@{addr="0x000100f4",func="foo",args=@{@},file="try.c",line="10"@} |
| (gdb) |
| @end example |
| |
| @section -exec-until |
| Asynchronous command. Executes the inferior until the 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 ``location-reached''. |
| @subsection GDB command |
| until |
| |
| @subsection Example |
| @example |
| (gdb) |
| -exec-until recursive2.c:6 |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="location-reached",frame=@{func="main",args=@{@}, |
| file="recursive2.c",line="6"@} |
| (gdb) |
| @end example |
| |
| @section -file-clear |
| Is this going away???? |
| |
| @section -file-exec-and-symbols <file> |
| 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, it clears |
| the executable and symbol information. If breakpoints are set when |
| using this command with no arguments, gdb will produce errors. No output |
| is produced, except a completion notification. |
| @subsection GDB command |
| file <file> |
| |
| @subsection Example |
| @example |
| (gdb) |
| -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx |
| ^done |
| (gdb) |
| @end example |
| |
| @section -file-exec-file <file> |
| Specify the executable file to be debugged. The symbol table is not read |
| from this file. If used without argument gdb clears the information |
| about the executable file. No output is produced, except a completion |
| notification. |
| @subsection GDB command |
| exec-file <file> |
| |
| @subsection Example |
| @example |
| (gdb) |
| -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx |
| ^done |
| (gdb) |
| @end example |
| |
| @section -file-list-exec-sections |
| List the sections of the current executable file. |
| @subsection GDB command |
| info file (only part of it), gdb_load_info |
| @subsection Example |
| N.A. |
| |
| @section -file-list-exec-source-files |
| List the source files for the current executable. |
| @subsection GDB command |
| gdb_listfiles (gdbtk). |
| @subsection Example |
| N.A. |
| |
| @section -file-list-shared-libraries |
| List the shared libraries in the program. |
| @subsection GDB command |
| info shared |
| @subsection Example |
| N.A. |
| |
| @section -file-list-symbol-files |
| List symbol files. |
| @subsection GDB command |
| info file (part of it). |
| @subsection Example |
| N.A. |
| |
| @section -file-symbol-file <file> |
| Read symbol table info from the file specified as argument. Used |
| without arguments clears gdb's symbol table info. No output is |
| produced, except a completion notification. |
| @subsection GDB command |
| symbol-file <file> |
| |
| @subsection Example |
| @example |
| (gdb) |
| -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx |
| ^done |
| (gdb) |
| @end example |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Misc GDB commands |
| |
| @c @section -gdb-complete |
| |
| @section -gdb-exit |
| |
| Exit GDB immediately. |
| @subsection GDB command |
| Approximately corresponds to 'quit'. |
| |
| @subsection Example |
| @example |
| (gdb) |
| -gdb-exit |
| @end example |
| |
| @section -gdb-set |
| Set an internal GDB variable. |
| IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ????? |
| |
| @subsection GDB command |
| set |
| |
| @subsection Example |
| @example |
| (gdb) |
| -gdb-set $foo=3 |
| ^done |
| (gdb) |
| @end example |
| |
| @section -gdb-show |
| Show the current value of a GDB variable. |
| |
| @subsection GDB command |
| show |
| |
| @subsection Example |
| @example |
| (gdb) |
| -gdb-show annotate |
| ^done,value="0" |
| (gdb) |
| @end example |
| |
| @c @section -gdb-source |
| |
| @section -gdb-version |
| Show version information for gdb. Used in testing mostly. |
| |
| @subsection GDB command |
| No equivalent. |
| |
| @subsection Example |
| @example |
| (gdb) |
| -gdb-version |
| ~GNU gdb 4.18.1 HEADLESS |
| ~Copyright 1998 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 |
| (gdb) |
| @end example |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Kod Commands |
| |
| The Kod commands are not implemented. |
| |
| @c @section -kod-info |
| |
| @c @section -kod-list |
| |
| @c @section -kod-list-object-types |
| |
| @c @section -kod-show |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Memory Overlay Commands |
| |
| the memory overlay commands not implemented. |
| |
| @c @section -overlay-auto |
| |
| @c @section -overlay-list-mapping-state |
| |
| @c @section -overlay-list-overlays |
| |
| @c @section -overlay-map |
| |
| @c @section -overlay-off |
| |
| @c @section -overlay-on |
| |
| @c @section -overlay-unmap |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Signal Handling Commands |
| |
| Signal handling commands are not implemented. |
| |
| @c @section -signal-handle |
| |
| @c @section -signal-list-handle-actions |
| |
| @c @section -signal-list-signal-types |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Stack manipulation commands |
| |
| @section -stack-info-frame |
| Get info on the current frame. |
| @subsection GDB command |
| info frame or frame (w/o args). |
| @subsection Example |
| N.A. |
| |
| @section -stack-info-depth [max-depth] |
| Return the depth of the stack. If the integer argument <max-depth> is specified, do not |
| count beyond max-depth frames. |
| @subsection GDB command |
| No equivalent. |
| @subsection Example |
| For a stack with frame levels 0 through 11: |
| @example |
| (gdb) |
| -stack-info-depth |
| ^done,depth="12" |
| (gdb) |
| -stack-info-depth 4 |
| ^done,depth="4" |
| (gdb) |
| -stack-info-depth 12 |
| ^done,depth="12" |
| (gdb) |
| -stack-info-depth 11 |
| ^done,depth="11" |
| (gdb) |
| -stack-info-depth 13 |
| ^done,depth="12" |
| (gdb) |
| @end example |
| |
| @section -stack-list-arguments <show-values> [ <low-frame> <high-frame> ] |
| Display a list of the arguments for the frames between low-frame and |
| high-frame (inclusive). If low-frame and high-frame are not provided, it |
| will list the arguments for the whole stack. The 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 argumetns are printed. |
| @subsection GDB command |
| gdb_get_args (partially). |
| @subsection Example |
| @example |
| (gdb) |
| -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"@}@} |
| (gdb) |
| -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=@{@}@}@} |
| (gdb) |
| -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=@{@}@}@} |
| (gdb) |
| -stack-list-arguments 0 2 2 |
| ^done,stack-args=@{frame=@{level="2",args=@{name="intarg",name="strarg"@}@}@} |
| (gdb) |
| -stack-list-arguments 1 2 2 |
| ^done,stack-args=@{frame=@{level="2", |
| args=@{@{name="intarg",value="2"@}, |
| @{name="strarg",value="0x11940 \"A string argument.\""@}@}@}@} |
| (gdb) |
| @end example |
| |
| @c @section -stack-list-exception-handlers |
| |
| @section -stack-list-frames [ <low-frame> <high-frame> ] |
| List the frames currently on the stack. For each frame it displays the following info: |
| @table @samp |
| @item <level> |
| The frame number, 0 being the topmost frame, i.e. the innermost function. |
| @item <addr> |
| Pc value for that frame. |
| @item <func> |
| Function name |
| @item <file> |
| File name of the source fle where the function lives. |
| @item <line> |
| Line number corresponding to the pc. |
| @end table |
| |
| If invoked without arguments, it 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. |
| |
| @subsection GDB command |
| backtrace or where |
| |
| @subsection Example 1 |
| Whole stack backtrace. |
| |
| @example |
| (gdb) |
| -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"@}@} |
| |
| (gdb) |
| @end example |
| |
| @subsection Example 2 |
| Show frames between low_frame and high_frame. |
| @example |
| (gdb) |
| -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"@}@} |
| (gdb) |
| @end example |
| @subsection Example 3 |
| Show one single frame. |
| @example |
| (gdb) |
| -stack-list-frames 3 3 |
| ^done,stack= |
| @{frame=@{level="3 ",addr="0x000107a4",func="foo",file="recursive2.c",line="14"@}@} |
| (gdb) |
| @end example |
| |
| @section -stack-list-locals <print-values> |
| Display the local variables names for the current frame. With an |
| argument of 0 prints only the names of the variables, with argument of 1 |
| prints also the values. |
| @subsection GDB command |
| gdb_get_locals |
| |
| @subsection Example |
| @example |
| (gdb) |
| -stack-list-locals 0 |
| ^done,locals=@{name="A",name="B",name="C"@} |
| (gdb) |
| -stack-list-locals 1 |
| ^done,locals=@{@{name="A",value="1"@},@{name="B",value="2"@},@{name="C",value="3"@}@} |
| (gdb) |
| @end example |
| |
| @section -stack-select-frame <framenum> |
| Change the current frame. Select a different frame on the stack. |
| @subsection GDB command |
| frame (part), up, down |
| AND/OR select-frame, |
| up-silent, down-silent |
| @subsection Example |
| @example |
| (gdb) |
| -stack-select-frame 2 |
| ^done |
| (gdb) |
| @end example |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Symbol query commands |
| |
| @section -symbol-info-address <symbol> |
| Describe where <symbol> is stored. |
| @subsection GDB command |
| Info address |
| @subsection Example |
| N.A. |
| |
| @section -symbol-info-file |
| Show the file for the symbol [NOT SURE] |
| @subsection GDB command |
| gdb_filnd_file (gdbtk). |
| @subsection Example |
| N.A. |
| |
| @section -symbol-info-function |
| Show which function the symbol lives in. [NOT SURE] |
| @subsection GDB command |
| gdb_get_function (gdbtk) |
| @subsection Example |
| N.A. |
| |
| @section -symbol-info-line |
| Core addresses of the code for a source line. |
| @subsection GDB command |
| info line , gdb_get_line, gdb_get_file |
| @subsection Example |
| N.A. |
| |
| @section -symbol-info-symbol |
| Describe what symbol is at location ADDR [NOT SURE] |
| @subsection GDB command |
| info symbol |
| @subsection Example |
| N.A. |
| |
| @section -symbol-list-functions |
| List the functions in the executable. |
| @subsection GDB command |
| info functions, gdb_listfunc, gdb_search |
| @subsection Example |
| N.A. |
| |
| @section -symbol-list-types |
| List all the type names. |
| @subsection GDB command |
| info types, gdb_search |
| @subsection Example |
| N.A. |
| |
| @section -symbol-list-variables |
| List all global and static variable names. |
| @subsection GDB command |
| Info variables, gdb_search |
| @subsection Example |
| N.A. |
| |
| @section -symbol-locate |
| @subsection GDB command |
| gdb_loc (gdbtk) |
| @subsection Example |
| N.A. |
| |
| @section -symbol-type |
| Show type of a variable. |
| @subsection GDB command |
| ptype, gdb_obj_variable |
| @subsection Example |
| N.A. |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Target manipulation commands |
| |
| @section -target-attach |
| Attach to a process or file outside of GDB. |
| @subsection GDB command |
| attach |
| @subsection Example |
| N.A. |
| |
| @section -target-compare-sections |
| Compare section data on target to the exec file. |
| @subsection GDB command |
| compare-sections |
| @subsection Example |
| N.A. |
| |
| @section -target-detach |
| Disconnect from the remote target. |
| No output. |
| |
| @subsection GDB command |
| detach |
| |
| @subsection Example |
| @example |
| (gdb) |
| -target-detach |
| ^done |
| (gdb) |
| @end example |
| |
| @section -target-download |
| Loads the executable onto the remote target. |
| It prints out an update message every half second, which includes the fields: |
| @itemize @bullet |
| @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 itemize |
| Each message is sent as status record. |
| |
| In addition it prints the name and size of the sections, as they are |
| downloaded. These messages include the fields: |
| @itemize @bullet |
| @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 itemize |
| At the end a summary is printed. |
| @subsection GDB command |
| load |
| |
| @subsection Example |
| Note: Each status message appears on a single line. Here the messages |
| have been broken down, so they can fit into a page. |
| @example |
| (gdb) |
| -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" |
| (gdb) |
| @end example |
| |
| @section -target-exec-status |
| Provide information on the state of the target. Whether it is running or not, for instance. |
| @subsection GDB command |
| No equivalent |
| @subsection Example |
| N.A. |
| |
| @section -target-list-available-targets |
| List the possible targets to connect to. |
| @subsection GDB command |
| help target |
| @subsection Example |
| N.A. |
| |
| @section -target-list-current-targets |
| What the current target is. |
| @subsection GDB command |
| info file (part of it). |
| @subsection Example |
| N.A. |
| |
| @section -target-list-parameters |
| ???? |
| @subsection GDB command |
| No equivalent |
| @subsection Example |
| N.A. |
| |
| @section -target-select |
| Connect GDB to the remote target. |
| It takes two args: |
| |
| -target-select <type> <parameters>. |
| |
| Where: |
| |
| @table @samp |
| @item <type> |
| The type of target, for instance async, remote, etc. |
| @item <parameters> |
| Device names, host names and the like. |
| @end table |
| The output is a connection notification, followed by the address at |
| which the target program is, in the following form: |
| ^connected,addr="<address>",func="<function name>",args=@{<arg list>@} |
| |
| @subsection GDB command |
| target |
| |
| @subsection Example |
| @example |
| (gdb) |
| -target-select async /dev/ttya |
| ^connected,addr="0xfe00a300",func="??",args=@{@} |
| (gdb) |
| @end example |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Thread commands |
| |
| @section -thread-info |
| @subsection GDB command |
| @subsection Example |
| |
| @section -thread-list-all-threads |
| @subsection GDB command |
| @subsection Example |
| |
| @section -thread-list-ids |
| Produces a list of the currently known gdb thread ids. At the end of the |
| list it also prints the toal number of such threads. |
| @subsection GDB command |
| None equivalent. (Maybe part of info threads). |
| @subsection Example 1 |
| No threads present, besides the main process. |
| @example |
| (gdb) |
| -thread-list-ids |
| ^done,thread-ids=@{@},number-of-threads="0" |
| (gdb) |
| @end example |
| @subsection Example 2 |
| Several threads. |
| @example |
| (gdb) |
| -thread-list-ids |
| ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, |
| number-of-threads="3" |
| (gdb) |
| @end example |
| |
| @section -thread-select <threadnum> |
| Make <threadnum> the current thread. It prints the number of the new |
| current thread, and the topmost frame for that thread. |
| @subsection GDB command |
| thread |
| @subsection Example |
| @example |
| (gdb) |
| -exec-next |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",thread-id="2",line="187", |
| file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" |
| (gdb) |
| -thread-list-ids |
| ^done, |
| thread-ids={thread-id="3",thread-id="2",thread-id="1"}, |
| number-of-threads="3" |
| (gdb) |
| -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"@} |
| (gdb) |
| @end example |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Tracepoint Commands |
| |
| The tracepoint commands are not implemented. |
| |
| @c @section -trace-actions |
| |
| @c @section -trace-delete |
| |
| @c @section -trace-disable |
| |
| @c @section -trace-dump |
| |
| @c @section -trace-enable |
| |
| @c @section -trace-exists |
| |
| @c @section -trace-find |
| |
| @c @section -trace-frame-number |
| |
| @c @section -trace-info |
| |
| @c @section -trace-insert |
| |
| @c @section -trace-list |
| |
| @c @section -trace-pass-count |
| |
| @c @section -trace-save |
| |
| @c @section -trace-start |
| |
| @c @section -trace-stop |
| |
| |
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @chapter Variable Objects |
| |
| @section Motivation |
| |
| For the implementation of a variable debugger window (locals, watched |
| expressions, etc.), we are proposing the adaptation of the existent code |
| used by Insight. |
| |
| The two main reason for that are: |
| |
| @enumerate 1 |
| @item |
| It has been proven in practice (it is already on it's 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 can be used through flathead. This document |
| describes the flathead operations that will be available and gives some |
| hints about its use. |
| |
| @emph{Note}: In addition to the set of operations described here, we |
| expect the GUI implementation of a variable window to require, at least, |
| the following operations: |
| @itemize bullet |
| @item -gdb-show output-radix |
| @item -stack-list-arguments |
| @item -stack-list-locals |
| @item -stack-select-frame |
| @end itemize |
| |
| @section Introduction |
| |
| 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 struct type variable is the root |
| and the children will represent the struct members. If a children is |
| itself of a complex type, it will also have children of its own. |
| Appropriate language differences are handled for C, C++ 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 the a default format automatically chosen |
| based on the variable type (like decimal for int, hex for pointers, |
| etc.). |
| |
| The following is the complete set of flathead operations defined to |
| access this functionality: |
| |
| @multitable @columnfractions .3 .6 |
| @item @strong{Operation} |
| @tab @strong{Description} |
| |
| @item -var-create |
| @tab create a variable object |
| @item -var-delete |
| @tab delete the variable object and its children |
| @item -var-set-format |
| @tab set the display format of this variable |
| @item -var-show-format |
| @tab show the display format of this variable |
| @item -var-info-num-children |
| @tab tells how many children this object has |
| @item -var-list-children |
| @tab return a list of the object's children |
| @item -var-info-type |
| @tab show the type of this variable object |
| @item -var-info-expression |
| @tab print what this variable object represents |
| @item -var-show-attributes |
| @tab is this variable editable? does it exist here? |
| @item -var-evaluate-expression |
| @tab get the value of this variable |
| @item -var-assign |
| @tab set the value of this variable |
| @item -var-update |
| @tab update the variable and its children |
| @end multitable |
| |
| In the next section we describe each operation in detail and suggest how |
| it can be used. |
| |
| |
| @section Operations Description And Use |
| |
| @subsection -var-create @{<name> | '-'@} @{<frame-addr> | '*'@} <expression> |
| |
| 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 <name> parameter is the string by which the object can be |
| referenced. It must be unique. If '-' is specified, the varobj system |
| will generate a string "varNNNNNN" automatically. It will be unique |
| provided that one does not specify <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. A '*' indicates that the current frame should be used. |
| |
| Expression is any expression valid on the current language set (must not |
| begin with '*') or: *<addr> - The address of a memory cell |
| *<addr>-<addr> - An memory address range (TBD) $<regname> - A CPU |
| register |
| |
| 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 |
| gdb CLI. |
| |
| name="<name>",numchild="N",type="<type>" |
| |
| @subsection -var-delete <name> |
| |
| Deletes a previously created variable object and all of it's children. |
| |
| Returns an error if the object <name> is not found. |
| |
| @subsection -var-set-format <name> <format-spec> |
| |
| Sets the output format for the value of the object. |
| |
| <format-spec> = @{binary | decimal | hexadecimal | octal | natural@} |
| |
| @subsection -var-show-format <name> |
| |
| Returns the format used to display the value of the object. |
| |
| format="<format-spec>" |
| |
| @subsection -var-info-num-children <name> |
| |
| Returns the number of children of a variable object. |
| |
| numchild="N" |
| |
| @subsection -var-list-children <name> |
| |
| Returns a list of the children of the specified variable object. |
| |
| numchild="N",children=@{@{name="<name>",numchild="N",type="<type>"@},(repeats N times)@} |
| |
| @subsection -var-info-type <name> |
| |
| Returns the type of the specified variable. The type is returned as a |
| string in the same format as it is output by gdb's CLI. |
| |
| type="<type>" |
| |
| @subsection -var-info-expression <name> |
| |
| Returns what is represented by the specified variable object. |
| |
| lang="<lang-spec>",exp="<expression>" |
| |
| where <lang-spec> = @{"C" | "C++" | "Java"@} |
| |
| @subsection -var-show-attributes <name> |
| |
| List attributes of the specified variable object. |
| |
| status="<attr>[,<attr>]*" |
| |
| where <attr> = @{ @{ editable | noneditable @} | TBD @} |
| |
| @subsection -var-evaluate-expression <name> |
| |
| 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. |
| |
| value="<value>" |
| |
| @subsection -var-assign <name> <expression> |
| |
| Assigns a new value for the variable object specified. The object must |
| be "editable". |
| |
| @subsection -var-update @{<name> | '*'@} |
| |
| Update the value of the variable object by evaluating its expression |
| after fetching all the new values from memory or registers. A '*' |
| causes all existing variable objects to be updated. |
| |
| |
| @c%%%%%%%%%%%%%%%%%%%%%%%%%%%% APPENDIX %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| @appendix Proposed v2.0 Output Syntax |
| |
| This appendix is not part of the MI specification. It is provided as a |
| discussion point. |
| |
| The output from GDB/MI consists of zero or more out-of-band records |
| optionally followed by a single result record. The result record being |
| for the most recent command input. The sequence being terminated by |
| ``(gdb)''. |
| |
| Asynchronous GDB/MI output is similar. |
| |
| Each output record directly associated with an input command is prefixed |
| by the input commands @code{<token>}. |
| |
| @table @code |
| @item <output> @expansion{} |
| @{ <out-of-band-record> @} [ <result-record> ] ``(gdb)'' <nl> |
| |
| @item <result-record> @expansion{} |
| [ <token> ] ``^'' <result-class> @{ ``,'' <result> @} <nl> |
| |
| @item <out-of-band-record> @expansion{} |
| <async-record> | <stream-record> |
| |
| @item <async-record> @expansion{} |
| <exec-async-output> | <status-async-output> | <notify-async-output> |
| |
| @item <exec-async-output> @expansion{} |
| [ <token> ] ``*'' <async-output> |
| |
| @item <status-async-output> @expansion{} |
| [ <token> ] ``+'' <async-output> |
| |
| @item <notify-async-output> @expansion{} |
| [ <token> ] ``='' <async-output> |
| |
| @item <async-output> @expansion{} |
| <async-class> @{ ``,'' <result> @} <nl> |
| |
| @item <result-class> @expansion{} |
| ``done'' | ``running'' | ``connected'' | ``error'' | ``exit'' |
| |
| @item <async-class> @expansion{} |
| ``stopped'' | @emph{others depending on need as still in development} |
| |
| @item <result> @expansion{} |
| <string> ``='' <value> |
| |
| @item <value> @expansion{} |
| <c-string> | <tupple> | <list> |
| |
| @item <tupple> @expansion{} |
| ``@{@}'' | ``@{'' <result> @{ ``,'' <result> @} ``@}'' |
| |
| @item <list> @expansion{} |
| ``[]'' | ``['' <value> @{ ``,'' <value> @} ``]'' |
| |
| @item <string> @expansion{} |
| @emph{[-A-Za-z\.0-9_]*} |
| |
| @item <c-string> @expansion{} |
| @emph{See the input specification} |
| |
| @item <stream-record> @expansion{} |
| <console-stream-output> | <target-stream-output> | <log-stream-output> |
| |
| @item <console-stream-output> @expansion{} |
| ``~'' <c-string> |
| |
| @item <target-stream-output> @expansion{} |
| ``@@'' <c-string> |
| |
| @item <log-stream-output> @expansion{} |
| ``&'' <c-string> |
| |
| @item <nl> @expansion{} |
| CR | CR-LF |
| |
| @item <token> @expansion{} |
| ``any sequence of digits'' |
| |
| @end table |
| |
| In addition, the following are still being developed. |
| |
| @table @code |
| |
| @item <query> |
| This action is currently undefined. |
| |
| @end table |
| |
| Notes: |
| |
| @itemize @bullet |
| |
| @item |
| All output sequences end in a single line containing a period. |
| |
| @item |
| The @code{<token>} is from the corresponding request. If an execution |
| command is interrupted by the -exec-interrupt command, the token |
| associated with the `*stopped' message is the one of the original |
| execution command, not the one of the interrupt-command. |
| |
| @item |
| <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 |
| the prefix `+'. |
| |
| @item |
| <exec-async-output> contains asynchronous state change on the target |
| (stopped, started, disappeared). All async output is prefixed by |
| the prefix `*'. |
| |
| @item |
| <notify-async-output> contains supplementary information that the client should |
| handle (new breakpoint information). All notify output is prefixed by |
| the prefix `='. |
| |
| @item |
| <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 the prefix ``~''. |
| |
| @item |
| <target-stream-output> is the output produced by the target program. |
| All the target output is prefixed by the prefix ``@@''. |
| |
| @item |
| <log-stream-output> is output text coming from GDB's internals, for |
| instance messages that should be displayed as part of an error log. All |
| the log output is prefixed by the prefix ``&''. |
| |
| @end itemize |
| |
| |
| @c Local variables: |
| @c change-log-default-name: "ChangeLog-mi" |
| @c End: |
| @bye |