* M2 Operators:: Built-in operators
* Built-In Func/Proc:: Built-in functions and procedures
* M2 Constants:: Modula-2 constants
+* M2 Types:: Modula-2 types
* M2 Defaults:: Default settings for Modula-2
* Deviations:: Deviations from standard Modula-2
* M2 Checks:: Modula-2 type and range checks
@end table
@quotation
-@emph{Warning:} Sets and their operations are not yet supported, so @value{GDBN}
+@emph{Warning:} Set expressions and their operations are not yet supported, so @value{GDBN}
treats the use of the operator @code{IN}, or the use of operators
@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#},
@code{<=}, and @code{>=} on sets as an error.
Set constants are not yet supported.
@end itemize
+@node M2 Types
+@subsubsection Modula-2 Types
+@cindex Modula-2 types
+
+Currently @value{GDBN} can print the following data types in Modula-2
+syntax: array types, record types, set types, pointer types, procedure
+types, enumerated types, subrange types and base types. You can also
+print the contents of variables declared using these type.
+This section gives a number of simple source code examples together with
+sample @value{GDBN} sessions.
+
+The first example contains the following section of code:
+
+@smallexample
+VAR
+ s: SET OF CHAR ;
+ r: [20..40] ;
+@end smallexample
+
+@noindent
+and you can request @value{GDBN} to interrogate the type and value of
+@code{r} and @code{s}.
+
+@smallexample
+(@value{GDBP}) print s
+@{'A'..'C', 'Z'@}
+(@value{GDBP}) ptype s
+SET OF CHAR
+(@value{GDBP}) print r
+21
+(@value{GDBP}) ptype r
+[20..40]
+@end smallexample
+
+@noindent
+Likewise if your source code declares @code{s} as:
+
+@smallexample
+VAR
+ s: SET ['A'..'Z'] ;
+@end smallexample
+
+@noindent
+then you may query the type of @code{s} by:
+
+@smallexample
+(@value{GDBP}) ptype s
+type = SET ['A'..'Z']
+@end smallexample
+
+@noindent
+Note that at present you cannot interactively manipulate set
+expressions using the debugger.
+
+The following example shows how you might declare an array in Modula-2
+and how you can interact with @value{GDBN} to print its type and contents:
+
+@smallexample
+VAR
+ s: ARRAY [-10..10] OF CHAR ;
+@end smallexample
+
+@smallexample
+(@value{GDBP}) ptype s
+ARRAY [-10..10] OF CHAR
+@end smallexample
+
+Note that the array handling is not yet complete and although the type
+is printed correctly, expression handling still assumes that all
+arrays have a lower bound of zero and not @code{-10} as in the example
+above. Unbounded arrays are also not yet recognized in @value{GDBN}.
+
+Here are some more type related Modula-2 examples:
+
+@smallexample
+TYPE
+ colour = (blue, red, yellow, green) ;
+ t = [blue..yellow] ;
+VAR
+ s: t ;
+BEGIN
+ s := blue ;
+@end smallexample
+
+@noindent
+The @value{GDBN} interaction shows how you can query the data type
+and value of a variable.
+
+@smallexample
+(@value{GDBP}) print s
+$1 = blue
+(@value{GDBP}) ptype t
+type = [blue..yellow]
+@end smallexample
+
+@noindent
+In this example a Modula-2 array is declared and its contents
+displayed. Observe that the contents are written in the same way as
+their @code{C} counterparts.
+
+@smallexample
+VAR
+ s: ARRAY [1..5] OF CARDINAL ;
+BEGIN
+ s[1] := 1 ;
+@end smallexample
+
+@smallexample
+(@value{GDBP}) print s
+$1 = @{1, 0, 0, 0, 0@}
+(@value{GDBP}) ptype s
+type = ARRAY [1..5] OF CARDINAL
+@end smallexample
+
+The Modula-2 language interface to @value{GDBN} also understands
+pointer types as shown in this example:
+
+@smallexample
+VAR
+ s: POINTER TO ARRAY [1..5] OF CARDINAL ;
+BEGIN
+ NEW(s) ;
+ s^[1] := 1 ;
+@end smallexample
+
+@noindent
+and you can request that @value{GDBN} describes the type of @code{s}.
+
+@smallexample
+(@value{GDBP}) ptype s
+type = POINTER TO ARRAY [1..5] OF CARDINAL
+@end smallexample
+
+@value{GDBN} handles compound types as we can see in this example.
+Here we combine array types, record types, pointer types and subrange
+types:
+
+@smallexample
+TYPE
+ foo = RECORD
+ f1: CARDINAL ;
+ f2: CHAR ;
+ f3: myarray ;
+ END ;
+
+ myarray = ARRAY myrange OF CARDINAL ;
+ myrange = [-2..2] ;
+VAR
+ s: POINTER TO ARRAY myrange OF foo ;
+@end smallexample
+
+@noindent
+and you can ask @value{GDBN} to describe the type of @code{s} as shown
+below.
+
+@smallexample
+(@value{GDBP}) ptype s
+type = POINTER TO ARRAY [-2..2] OF foo = RECORD
+ f1 : CARDINAL;
+ f2 : CHAR;
+ f3 : ARRAY [-2..2] OF CARDINAL;
+END
+@end smallexample
+
@node M2 Defaults
@subsubsection Modula-2 defaults
@cindex Modula-2 defaults
but no definition for @code{struct foo} itself, @value{GDBN} will say:
@smallexample
- (gdb) ptype foo
+ (@value{GDBP}) ptype foo
$1 = <incomplete type>
@end smallexample
* Target Commands:: Commands for managing targets
* Byte Order:: Choosing target byte order
* Remote:: Remote debugging
-* KOD:: Kernel Object Display
@end menu
@end table
-@node KOD
-@section Kernel Object Display
-@cindex kernel object display
-@cindex KOD
-
-Some targets support kernel object display. Using this facility,
-@value{GDBN} communicates specially with the underlying operating system
-and can display information about operating system-level objects such as
-mutexes and other synchronization objects. Exactly which objects can be
-displayed is determined on a per-OS basis.
-
-@kindex set os
-Use the @code{set os} command to set the operating system. This tells
-@value{GDBN} which kernel object display module to initialize:
-
-@smallexample
-(@value{GDBP}) set os cisco
-@end smallexample
-
-@kindex show os
-The associated command @code{show os} displays the operating system
-set with the @code{set os} command; if no operating system has been
-set, @code{show os} will display an empty string @samp{""}.
-
-If @code{set os} succeeds, @value{GDBN} will display some information
-about the operating system, and will create a new @code{info} command
-which can be used to query the target. The @code{info} command is named
-after the operating system:
-
-@kindex info cisco
-@smallexample
-(@value{GDBP}) info cisco
-List of Cisco Kernel Objects
-Object Description
-any Any and all objects
-@end smallexample
-
-Further subcommands can be used to query about particular objects known
-by the kernel.
-
-There is currently no way to determine whether a given operating
-system is supported other than to try setting it with @kbd{set os
-@var{name}}, where @var{name} is the name of the operating system you
-want to try.
-
-
@node Remote Debugging
@chapter Debugging remote programs
@kindex show remote
This section documents the configuration options available when
debugging remote programs. For the options related to the File I/O
-extensions of the remote protocol, see @ref{The system call,
+extensions of the remote protocol, see @ref{system,
system-call-allowed}.
@table @code
@item show remote get-thread-local-storage-address
@kindex show remote get-thread-local-storage-address
Show the current setting of @samp{qGetTLSAddr} packet usage.
+
+@item set remote supported-packets
+@kindex set remote supported-packets
+@cindex query supported packets of remote targets
+This command enables or disables the use of the @samp{qSupported}
+request packet. @xref{General Query Packets, qSupported}, for more
+details about this packet. The default is to use @samp{qSupported}.
+
+@item show remote supported-packets
+@kindex show remote supported-packets
+Show the current setting of @samp{qSupported} packet usage.
@end table
@node remote stub
This command loads symbols from a dll similarly to
add-sym command but without the need to specify a base address.
+@kindex set cygwin-exceptions
+@cindex debugging the Cygwin DLL
+@cindex Cygwin DLL, debugging
+@item set cygwin-exceptions @var{mode}
+If @var{mode} is @code{on}, @value{GDBN} will break on exceptions that
+happen inside the Cygwin DLL. If @var{mode} is @code{off},
+@value{GDBN} will delay recognition of exceptions, and may ignore some
+exceptions which seem to be caused by internal Cygwin DLL
+``bookkeeping''. This option is meant primarily for debugging the
+Cygwin DLL itself; the default value is @code{off} to avoid annoying
+@value{GDBN} users with false @code{SIGSEGV} signals.
+
+@kindex show cygwin-exceptions
+@item show cygwin-exceptions
+Displays whether @value{GDBN} will break on exceptions that happen
+inside the Cygwin DLL itself.
+
@kindex set new-console
@item set new-console @var{mode}
If @var{mode} is @code{on} the debuggee will
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.
+features described below are incomplete and subject to change
+(@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}).
@unnumberedsec Notation and Terminology
@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 Development and Front Ends::
* GDB/MI Output Records::
+* GDB/MI Simple Examples::
* GDB/MI Command Description Format::
-* GDB/MI Breakpoint Table Commands::
+* GDB/MI Breakpoint Commands::
+* GDB/MI Program Context::
+* GDB/MI Thread Commands::
+* GDB/MI Program Execution::
+* GDB/MI Stack Manipulation::
+* GDB/MI Variable Objects::
* GDB/MI Data Manipulation::
-* GDB/MI Program Control::
-* GDB/MI Miscellaneous Commands::
+* GDB/MI Tracepoint Commands::
+* GDB/MI Symbol Query::
+* GDB/MI File 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::
+* GDB/MI Miscellaneous Commands::
@end menu
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@menu
* GDB/MI Input Syntax::
* GDB/MI Output Syntax::
-* GDB/MI Simple Examples::
@end menu
@node GDB/MI Input 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})}.
+terminated by @samp{(gdb)}.
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
@table @code
@item @var{output} @expansion{}
-@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(@value{GDBP})" @var{nl}}
+@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}}
@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:
-
-@smallexample
--> -stop
-<- (@value{GDBP})
-@end smallexample
-
-@noindent
-and later:
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Compatibility with CLI
+@section @sc{gdb/mi} Compatibility with CLI
-@smallexample
-<- *stop,reason="stop",address="0x123",source="a.c:123"
-<- (@value{GDBP})
-@end smallexample
+@cindex compatibility, @sc{gdb/mi} and CLI
+@cindex @sc{gdb/mi}, compatibility with CLI
-@subsubheading Simple CLI Command
+For the developers convenience CLI commands can be entered directly,
+but there may be some unexpected behaviour. For example, commands
+that query the user will behave as if the user replied yes, breakpoint
+command lists are not executed and some CLI commands, such as
+@code{if}, @code{when} and @code{define}, prompt for further input with
+@samp{>}, which is not valid MI output.
-Here's an example of a simple CLI command being passed through
-@sc{gdb/mi} and on to the CLI.
+This feature may be removed at some stage in the future and it is
+recommended that front ends use the @code{-interpreter-exec} command
+(@pxref{-interpreter-exec}).
-@smallexample
--> print 1+2
-<- &"print 1+2\n"
-<- ~"$1 = 3\n"
-<- ^done
-<- (@value{GDBP})
-@end smallexample
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Development and Front Ends
+@section @sc{gdb/mi} Development and Front Ends
+@cindex @sc{gdb/mi} development
-@subsubheading Command With Side Effects
+The application which takes the MI output and presents the state of the
+program being debugged to the user is called a @dfn{front end}.
-@smallexample
--> -symbol-file xyz.exe
-<- *breakpoint,nr="3",address="0x123",source="a.c:123"
-<- (@value{GDBP})
-@end smallexample
+Although @sc{gdb/mi} is still incomplete, it is currently being used
+by a variety of front ends to @value{GDBN}. This makes it difficult
+to introduce new functionality without breaking existing usage. This
+section tries to minimize the problems by describing how the protocol
+might change.
-@subsubheading A Bad Command
+Some changes in MI need not break a carefully designed front end, and
+for these the MI version will remain unchanged. The following is a
+list of changes that may occur within one level, so front ends should
+parse MI output in a way that can handle them:
-Here's what happens if you pass a non-existent command:
+@itemize @bullet
+@item
+New MI commands may be added.
-@smallexample
--> -rubbish
-<- ^error,msg="Undefined MI command: rubbish"
-<- (@value{GDBP})
-@end smallexample
+@item
+New fields may be added to the output of any MI command.
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Compatibility with CLI
-@section @sc{gdb/mi} Compatibility with CLI
+@c The format of field's content e.g type prefix, may change so parse it
+@c at your own risk. Yes, in general?
-@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.
+@c The order of fields may change? Shouldn't really matter but it might
+@c resolve inconsistencies.
+@end itemize
-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.
+If the changes are likely to break front ends, the MI version level
+will be increased by one. This will allow the front end to parse the
+output according to the MI version. Apart from mi0, new versions of
+@value{GDBN} will not support old versions of MI and it will be the
+responsibility of the front end to work with the new one.
+
+@c Starting with mi3, add a new command -mi-version that prints the MI
+@c version?
+
+The best way to avoid unexpected changes in MI that might break your front
+end is to make your project known to @value{GDBN} developers and
+follow development on @email{gdb@@sourceware.org} and
+@email{gdb-patches@@sourceware.org}. There is also the mailing list
+@email{dmi-discuss@@lists.freestandards.org}, hosted by the Free Standards
+Group, which has the aim of creating a a more general MI protocol
+called Debugger Machine Interface (DMI) that will become a standard
+for all debuggers, not just @value{GDBN}.
+@cindex mailing lists
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Output Records
The asynchronous operation was successfully started. The target is
running.
+@item "^connected"
+@findex ^connected
+GDB has connected to a remote target.
+
@item "^error" "," @var{c-string}
@findex ^error
The operation failed. The @code{@var{c-string}} contains the corresponding
error message.
+
+@item "^exit"
+@findex ^exit
+GDB has terminated.
+
@end table
@node GDB/MI Stream Records
@item "@@" @var{string-output}
The target output stream contains any textual output from the running
-target.
+target. This is only present when GDB's event loop is truly
+asynchronous, which is currently only the case for remote targets.
@item "&" @var{string-output}
The log stream contains debugging messages being produced by @value{GDBN}'s
@end table
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Simple Examples
+@section 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}.
+
+Note the the line breaks shown in the examples are here only for
+readability, they don't appear in the real output.
+
+@subheading Setting a breakpoint
+
+Setting a breakpoint generates synchronous output which contains detailed
+information of the breakpoint.
+
+@smallexample
+-> -break-insert main
+<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
+ enabled="y",addr="0x08048564",func="main",file="myprog.c",
+ fullname="/home/nickrob/myprog.c",line="68",times="0"@}
+<- (gdb)
+@end smallexample
+
+@subheading Program Execution
+
+Program execution generates asynchronous records and MI gives the
+reason that execution stopped.
+
+@smallexample
+-> -exec-run
+<- ^running
+<- (gdb)
+<- *stopped,reason="breakpoint-hit",bkptno="1",thread-id="0",
+ frame=@{addr="0x08048564",func="main",
+ args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}],
+ file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"@}
+<- (gdb)
+-> -exec-continue
+<- ^running
+<- (gdb)
+<- *stopped,reason="exited-normally"
+<- (gdb)
+@end smallexample
+
+@subheading Quitting GDB
+
+Quitting GDB just prints the result class @samp{^exit}.
+
+@smallexample
+-> (gdb)
+<- -gdb-exit
+<- ^exit
+@end smallexample
+
+@subheading A Bad Command
+
+Here's what happens if you pass a non-existent command:
+
+@smallexample
+-> -rubbish
+<- ^error,msg="Undefined MI command: rubbish"
+<- (gdb)
+@end smallexample
+
+
@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.
@subsubheading Example
+Example(s) formatted for readability. Some of the described commands have
+not been implemented yet and these are labeled N.A.@: (not available).
+
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Breakpoint Table Commands
-@section @sc{gdb/mi} Breakpoint table commands
+@node GDB/MI Breakpoint Commands
+@section @sc{gdb/mi} Breakpoint Commands
@cindex breakpoint commands for @sc{gdb/mi}
@cindex @sc{gdb/mi}, breakpoint commands
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-insert main
^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",
fullname="/home/foo/hello.c",line="5",times="0"@}
-(@value{GDBP})
+(gdb)
-break-after 1 3
~
^done
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",times="0",ignore="3"@}]@}
-(@value{GDBP})
+(gdb)
@end smallexample
@ignore
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-condition 1 1
^done
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",cond="1",times="0",ignore="3"@}]@}
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-break-delete} Command
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-delete 1
^done
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[]@}
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-break-disable} Command
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-disable 2
^done
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",times="0"@}]@}
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-break-enable} Command
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-enable 2
^done
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
line="5",times="0"@}]@}
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-break-info} Command
@smallexample
^done,bkpt=@{number="@var{number}",type="@var{type}",disp="del"|"keep",
enabled="y"|"n",addr="@var{hex}",func="@var{funcname}",file="@var{filename}",
-fullname="@var{full_filename}",line="@var{lineno}",times="@var{times}"@}
+fullname="@var{full_filename}",line="@var{lineno}",[thread="@var{threadno},]
+times="@var{times}"@}
@end smallexample
@noindent
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-insert main
^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",
fullname="/home/foo/recursive2.c,line="4",times="0"@}
-(@value{GDBP})
+(gdb)
-break-insert -t foo
^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",
fullname="/home/foo/recursive2.c,line="11",times="0"@}
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
addr="0x00010774",func="foo",file="recursive2.c",
fullname="/home/foo/recursive2.c",line="11",times="0"@}]@}
-(@value{GDBP})
+(gdb)
-break-insert -r foo.*
~int foo(int, int);
^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c,
"fullname="/home/foo/recursive2.c",line="11",times="0"@}
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-break-list} Command
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
line="13",times="0"@}]@}
-(@value{GDBP})
+(gdb)
@end smallexample
Here's an example of the result when there are no breakpoints:
@smallexample
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[]@}
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-break-watch} Command
Setting a watchpoint on a variable in the @code{main} function:
@smallexample
-(@value{GDBP})
+(gdb)
-break-watch x
^done,wpt=@{number="2",exp="x"@}
-(@value{GDBP})
+(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",
fullname="/home/foo/bar/recursive2.c",line="5"@}
-(@value{GDBP})
+(gdb)
@end smallexample
Setting a watchpoint on a variable local to a function. @value{GDBN} will stop
for the watchpoint going out of scope.
@smallexample
-(@value{GDBP})
+(gdb)
-break-watch C
^done,wpt=@{number="5",exp="C"@}
-(@value{GDBP})
+(gdb)
-exec-continue
^running
^done,reason="watchpoint-trigger",
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
-(@value{GDBP})
+(gdb)
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="5",
value="0x11940 \"A string argument.\""@}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
-(@value{GDBP})
+(gdb)
@end smallexample
Listing breakpoints and watchpoints, at different points in the program
deleted.
@smallexample
-(@value{GDBP})
+(gdb)
-break-watch C
^done,wpt=@{number="2",exp="C"@}
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
fullname="/home/foo/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})
+(gdb)
-exec-continue
^running
^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
fullname="/home/foo/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})
+(gdb)
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="2",
value="0x11940 \"A string argument.\""@}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
times="1"@}]@}
-(@value{GDBP})
+(gdb)
@end smallexample
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Data Manipulation
-@section @sc{gdb/mi} Data Manipulation
+@node GDB/MI Program Context
+@section @sc{gdb/mi} Program Context
-@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{-exec-arguments} Command
+@findex -exec-arguments
-@subheading The @code{-data-disassemble} Command
-@findex -data-disassemble
@subsubheading Synopsis
@smallexample
- -data-disassemble
- [ -s @var{start-addr} -e @var{end-addr} ]
- | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
- -- @var{mode}
+ -exec-arguments @var{args}
@end smallexample
-@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.
+Set the inferior program arguments, to be used in the next
+@samp{-exec-run}.
@subsubheading @value{GDBN} Command
-There's no direct mapping from this command to the CLI.
+The corresponding @value{GDBN} command is @samp{set args}.
@subsubheading Example
-Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
+@c FIXME!
+Don't have one around.
-@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}.
+@subheading The @code{-exec-show-arguments} Command
+@findex -exec-show-arguments
+
+@subsubheading Synopsis
@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})
+ -exec-show-arguments
@end smallexample
-Disassemble 3 instructions from the start of @code{main}:
+Print the arguments of the program.
-@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
+@subsubheading @value{GDBN} Command
-Disassemble 3 instructions from the start of @code{main} in mixed mode:
+The corresponding @value{GDBN} command is @samp{show args}.
-@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
+@subsubheading Example
+N.A.
-@subheading The @code{-data-evaluate-expression} Command
-@findex -data-evaluate-expression
+@subheading The @code{-environment-cd} Command
+@findex -environment-cd
@subsubheading Synopsis
@smallexample
- -data-evaluate-expression @var{expr}
+ -environment-cd @var{pathdir}
@end smallexample
-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.
+Set @value{GDBN}'s working directory.
@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.
+The corresponding @value{GDBN} command is @samp{cd}.
@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})
+(gdb)
+-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
+^done
+(gdb)
@end smallexample
-@subheading The @code{-data-list-changed-registers} Command
-@findex -data-list-changed-registers
+@subheading The @code{-environment-directory} Command
+@findex -environment-directory
@subsubheading Synopsis
@smallexample
- -data-list-changed-registers
+ -environment-directory [ -r ] [ @var{pathdir} ]+
@end smallexample
-Display a list of the registers that have changed.
+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
-@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
-has the corresponding command @samp{gdb_changed_register_list}.
+The corresponding @value{GDBN} command is @samp{dir}.
@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",fullname="/home/foo/bar/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})
+(gdb)
+-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
+^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
+(gdb)
+-environment-directory ""
+^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
+(gdb)
+-environment-directory -r /home/jjohnstn/src/gdb /usr/src
+^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
+(gdb)
+-environment-directory -r
+^done,source-path="$cdir:$cwd"
+(gdb)
@end smallexample
-@subheading The @code{-data-list-register-names} Command
-@findex -data-list-register-names
+@subheading The @code{-environment-path} Command
+@findex -environment-path
@subsubheading Synopsis
@smallexample
- -data-list-register-names [ ( @var{regno} )+ ]
+ -environment-path [ -r ] [ @var{pathdir} ]+
@end smallexample
-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.
+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
-@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}.
+The corresponding @value{GDBN} command is @samp{path}.
@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})
+(gdb)
+-environment-path
+^done,path="/usr/bin"
+(gdb)
+-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
+^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
+(gdb)
+-environment-path -r /usr/local/bin
+^done,path="/usr/local/bin:/usr/bin"
+(gdb)
@end smallexample
-@subheading The @code{-data-list-register-values} Command
-@findex -data-list-register-values
+
+@subheading The @code{-environment-pwd} Command
+@findex -environment-pwd
@subsubheading Synopsis
@smallexample
- -data-list-register-values @var{fmt} [ ( @var{regno} )*]
+ -environment-pwd
@end smallexample
-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.
+Show the current working directory.
-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
+@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}.
+The corresponding @value{GDBN} command is @samp{pwd}.
@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})
+(gdb)
+-environment-pwd
+^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
+(gdb)
@end smallexample
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Thread Commands
+@section @sc{gdb/mi} Thread Commands
+
-@subheading The @code{-data-read-memory} Command
-@findex -data-read-memory
+@subheading The @code{-thread-info} Command
+@findex -thread-info
@subsubheading Synopsis
@smallexample
- -data-read-memory [ -o @var{byte-offset} ]
- @var{address} @var{word-format} @var{word-size}
- @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
+ -thread-info
@end smallexample
-@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
+@subsubheading @value{GDBN} command
-The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
-@samp{gdb_get_mem} memory read command.
+No equivalent.
@subsubheading Example
+N.A.
-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
+@subheading The @code{-thread-list-all-threads} Command
+@findex -thread-list-all-threads
@subsubheading Synopsis
@smallexample
- -display-delete @var{number}
+ -thread-list-all-threads
@end smallexample
-Delete the display @var{number}.
-
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{delete display}.
+The equivalent @value{GDBN} command is @samp{info threads}.
@subsubheading Example
N.A.
-@subheading The @code{-display-disable} Command
-@findex -display-disable
+@subheading The @code{-thread-list-ids} Command
+@findex -thread-list-ids
@subsubheading Synopsis
@smallexample
- -display-disable @var{number}
+ -thread-list-ids
@end smallexample
-Disable display @var{number}.
+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
-The corresponding @value{GDBN} command is @samp{disable display}.
+Part of @samp{info threads} supplies the same information.
@subsubheading Example
-N.A.
-
-@subheading The @code{-display-enable} Command
-@findex -display-enable
-
-@subsubheading Synopsis
+No threads present, besides the main process:
@smallexample
- -display-enable @var{number}
+(gdb)
+-thread-list-ids
+^done,thread-ids=@{@},number-of-threads="0"
+(gdb)
@end smallexample
-Enable display @var{number}.
-
-@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{enable display}.
+Several threads:
-@subsubheading Example
-N.A.
+@smallexample
+(gdb)
+-thread-list-ids
+^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
+number-of-threads="3"
+(gdb)
+@end smallexample
-@subheading The @code{-display-insert} Command
-@findex -display-insert
+@subheading The @code{-thread-select} Command
+@findex -thread-select
@subsubheading Synopsis
@smallexample
- -display-insert @var{expression}
+ -thread-select @var{threadnum}
@end smallexample
-Display @var{expression} every time the program stops.
+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{display}.
+The corresponding @value{GDBN} command is @samp{thread}.
@subsubheading Example
-N.A.
+@smallexample
+(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 smallexample
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Program Execution
+@section @sc{gdb/mi} Program Execution
+
+These are the asynchronous commands which generate the out-of-band
+record @samp{*stopped}. Currently GDB only really executes
+asynchronously with remote targets and this interaction is mimicked in
+other cases.
-@subheading The @code{-display-list} Command
-@findex -display-list
+@subheading The @code{-exec-continue} Command
+@findex -exec-continue
@subsubheading Synopsis
@smallexample
- -display-list
+ -exec-continue
@end smallexample
-List the displays. Do not show the current values.
+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} command is @samp{info display}.
+The corresponding @value{GDBN} corresponding is @samp{continue}.
@subsubheading Example
-N.A.
+
+@smallexample
+-exec-continue
+^running
+(gdb)
+@@Hello world
+*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
+file="hello.c",fullname="/home/foo/bar/hello.c",line="13"@}
+(gdb)
+@end smallexample
-@subheading The @code{-environment-cd} Command
-@findex -environment-cd
+@subheading The @code{-exec-finish} Command
+@findex -exec-finish
@subsubheading Synopsis
@smallexample
- -environment-cd @var{pathdir}
+ -exec-finish
@end smallexample
-Set @value{GDBN}'s working directory.
+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{cd}.
+The corresponding @value{GDBN} command is @samp{finish}.
@subsubheading Example
+Function returning @code{void}.
+
@smallexample
-(@value{GDBP})
--environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
-^done
-(@value{GDBP})
+-exec-finish
+^running
+(gdb)
+@@hello from foo
+*stopped,reason="function-finished",frame=@{func="main",args=[],
+file="hello.c",fullname="/home/foo/bar/hello.c",line="7"@}
+(gdb)
+@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
+(gdb)
+*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
+args=[@{name="a",value="1"],@{name="b",value="9"@}@},
+file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+gdb-result-var="$1",return-value="0"
+(gdb)
@end smallexample
-@subheading The @code{-environment-directory} Command
-@findex -environment-directory
+@subheading The @code{-exec-interrupt} Command
+@findex -exec-interrupt
@subsubheading Synopsis
@smallexample
- -environment-directory [ -r ] [ @var{pathdir} ]+
+ -exec-interrupt
@end smallexample
-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.
+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{dir}.
+The corresponding @value{GDBN} command is @samp{interrupt}.
@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})
+(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",
+fullname="/home/foo/bar/try.c",line="13"@}
+(gdb)
+
+(gdb)
+-exec-interrupt
+^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
+(gdb)
@end smallexample
-@subheading The @code{-environment-path} Command
-@findex -environment-path
+@subheading The @code{-exec-next} Command
+@findex -exec-next
@subsubheading Synopsis
@smallexample
- -environment-path [ -r ] [ @var{pathdir} ]+
+ -exec-next
@end smallexample
-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.
+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
+(gdb)
+*stopped,reason="end-stepping-range",line="8",file="hello.c"
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-exec-next-instruction} Command
+@findex -exec-next-instruction
+
+@subsubheading Synopsis
+
+@smallexample
+ -exec-next-instruction
+@end smallexample
+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{path}.
+The corresponding @value{GDBN} command is @samp{nexti}.
@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})
+(gdb)
+-exec-next-instruction
+^running
+
+(gdb)
+*stopped,reason="end-stepping-range",
+addr="0x000100d4",line="5",file="hello.c"
+(gdb)
@end smallexample
-@subheading The @code{-environment-pwd} Command
-@findex -environment-pwd
+@subheading The @code{-exec-return} Command
+@findex -exec-return
@subsubheading Synopsis
@smallexample
- -environment-pwd
+ -exec-return
@end smallexample
-Show the current working directory.
+Makes current function return immediately. Doesn't execute the inferior.
+Displays the new current frame.
-@subsubheading @value{GDBN} command
+@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{pwd}.
+The corresponding @value{GDBN} command is @samp{return}.
@subsubheading Example
@smallexample
-(@value{GDBP})
--environment-pwd
-^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
-(@value{GDBP})
+(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",
+fullname="/home/foo/bar/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",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+(gdb)
@end smallexample
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Program Control
-@section @sc{gdb/mi} Program control
-@subsubheading Program termination
+@subheading The @code{-exec-run} Command
+@findex -exec-run
+
+@subsubheading Synopsis
+
+@smallexample
+ -exec-run
+@end smallexample
+
+Starts execution of the inferior from the beginning. The inferior
+executes until either a breakpoint is encountered or the program
+exits. In the latter case the output will include an exit code, if
+the program has exited exceptionally.
+
+@subsubheading @value{GDBN} Command
-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.
+The corresponding @value{GDBN} command is @samp{run}.
@subsubheading Examples
+@smallexample
+(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",
+fullname="/home/foo/bar/recursive2.c",line="4"@}
+(gdb)
+@end smallexample
+
@noindent
Program exited normally:
@smallexample
-(@value{GDBP})
+(gdb)
-exec-run
^running
-(@value{GDBP})
+(gdb)
x = 55
*stopped,reason="exited-normally"
-(@value{GDBP})
+(gdb)
@end smallexample
@noindent
Program exited exceptionally:
@smallexample
-(@value{GDBP})
+(gdb)
-exec-run
^running
-(@value{GDBP})
+(gdb)
x = 55
*stopped,reason="exited",exit-code="01"
-(@value{GDBP})
+(gdb)
@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})
+(gdb)
*stopped,reason="exited-signalled",signal-name="SIGINT",
signal-meaning="Interrupt"
@end smallexample
-@subheading The @code{-exec-abort} Command
-@findex -exec-abort
+@c @subheading -exec-signal
+
+
+@subheading The @code{-exec-step} Command
+@findex -exec-step
@subsubheading Synopsis
@smallexample
- -exec-abort
+ -exec-step
@end smallexample
-Kill the inferior running program.
+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{kill}.
+The corresponding @value{GDBN} command is @samp{step}.
@subsubheading Example
-N.A.
-
-@subheading The @code{-exec-arguments} Command
-@findex -exec-arguments
-
-@subsubheading Synopsis
+Stepping into a function:
@smallexample
- -exec-arguments @var{args}
+-exec-step
+^running
+(gdb)
+*stopped,reason="end-stepping-range",
+frame=@{func="foo",args=[@{name="a",value="10"@},
+@{name="b",value="0"@}],file="recursive2.c",
+fullname="/home/foo/bar/recursive2.c",line="11"@}
+(gdb)
@end smallexample
-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
+Regular stepping:
-@c FIXME!
-Don't have one around.
+@smallexample
+-exec-step
+^running
+(gdb)
+*stopped,reason="end-stepping-range",line="14",file="recursive2.c"
+(gdb)
+@end smallexample
-@subheading The @code{-exec-continue} Command
-@findex -exec-continue
+@subheading The @code{-exec-step-instruction} Command
+@findex -exec-step-instruction
@subsubheading Synopsis
@smallexample
- -exec-continue
+ -exec-step-instruction
@end smallexample
-Asynchronous command. Resumes the execution of the inferior program
-until a breakpoint is encountered, or until the inferior exits.
+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} corresponding is @samp{continue}.
+The corresponding @value{GDBN} command is @samp{stepi}.
@subsubheading Example
@smallexample
--exec-continue
+(gdb)
+-exec-step-instruction
^running
-(@value{GDBP})
-@@Hello world
-*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
-file="hello.c",fullname="/home/foo/bar/hello.c",line="13"@}
-(@value{GDBP})
+
+(gdb)
+*stopped,reason="end-stepping-range",
+frame=@{func="foo",args=[],file="try.c",
+fullname="/home/foo/bar/try.c",line="10"@}
+(gdb)
+-exec-step-instruction
+^running
+
+(gdb)
+*stopped,reason="end-stepping-range",
+frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",
+fullname="/home/foo/bar/try.c",line="10"@}
+(gdb)
@end smallexample
-@subheading The @code{-exec-finish} Command
-@findex -exec-finish
+@subheading The @code{-exec-until} Command
+@findex -exec-until
@subsubheading Synopsis
@smallexample
- -exec-finish
+ -exec-until [ @var{location} ]
@end smallexample
-Asynchronous command. Resumes the execution of the inferior program
-until the current function is exited. Displays the results returned by
-the function.
+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{finish}.
+The corresponding @value{GDBN} command is @samp{until}.
@subsubheading Example
-Function returning @code{void}.
-
@smallexample
--exec-finish
+(gdb)
+-exec-until recursive2.c:6
^running
-(@value{GDBP})
-@@hello from foo
-*stopped,reason="function-finished",frame=@{func="main",args=[],
-file="hello.c",fullname="/home/foo/bar/hello.c",line="7"@}
-(@value{GDBP})
+(gdb)
+x = 55
+*stopped,reason="location-reached",frame=@{func="main",args=[],
+file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"@}
+(gdb)
@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.
+@ignore
+@subheading -file-clear
+Is this going away????
+@end ignore
-@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",fullname="/home/foo/bar/recursive2.c",line="14"@},
-gdb-result-var="$1",return-value="0"
-(@value{GDBP})
-@end smallexample
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Stack Manipulation
+@section @sc{gdb/mi} Stack Manipulation Commands
-@subheading The @code{-exec-interrupt} Command
-@findex -exec-interrupt
+@subheading The @code{-stack-info-frame} Command
+@findex -stack-info-frame
@subsubheading Synopsis
@smallexample
- -exec-interrupt
+ -stack-info-frame
@end smallexample
-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.
+Get info on the selected frame.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{interrupt}.
+The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
+(without arguments).
@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",
-fullname="/home/foo/bar/try.c",line="13"@}
-(@value{GDBP})
-
-(@value{GDBP})
--exec-interrupt
-^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
-(@value{GDBP})
+(gdb)
+-stack-info-frame
+^done,frame=@{level="1",addr="0x0001076c",func="callee3",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}
+(gdb)
@end smallexample
-
-@subheading The @code{-exec-next} Command
-@findex -exec-next
+@subheading The @code{-stack-info-depth} Command
+@findex -stack-info-depth
@subsubheading Synopsis
@smallexample
- -exec-next
+ -stack-info-depth [ @var{max-depth} ]
@end smallexample
-Asynchronous command. Resumes execution of the inferior program, stopping
-when the beginning of the next source line is reached.
+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
-The corresponding @value{GDBN} command is @samp{next}.
+There's no equivalent @value{GDBN} command.
@subsubheading Example
+For a stack with frame levels 0 through 11:
+
@smallexample
--exec-next
-^running
-(@value{GDBP})
-*stopped,reason="end-stepping-range",line="8",file="hello.c"
-(@value{GDBP})
+(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 smallexample
-
-@subheading The @code{-exec-next-instruction} Command
-@findex -exec-next-instruction
+@subheading The @code{-stack-list-arguments} Command
+@findex -stack-list-arguments
@subsubheading Synopsis
@smallexample
- -exec-next-instruction
+ -stack-list-arguments @var{show-values}
+ [ @var{low-frame} @var{high-frame} ]
@end smallexample
-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.
+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
-The corresponding @value{GDBN} command is @samp{nexti}.
+@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})
--exec-next-instruction
-^running
-
-(@value{GDBP})
-*stopped,reason="end-stepping-range",
-addr="0x000100d4",line="5",file="hello.c"
-(@value{GDBP})
+(gdb)
+-stack-list-frames
+^done,
+stack=[
+frame=@{level="0",addr="0x00010734",func="callee4",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
+frame=@{level="1",addr="0x0001076c",func="callee3",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
+frame=@{level="2",addr="0x0001078c",func="callee2",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
+frame=@{level="3",addr="0x000107b4",func="callee1",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
+frame=@{level="4",addr="0x000107e0",func="main",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/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 smallexample
+@c @subheading -stack-list-exception-handlers
-@subheading The @code{-exec-return} Command
-@findex -exec-return
+
+@subheading The @code{-stack-list-frames} Command
+@findex -stack-list-frames
@subsubheading Synopsis
@smallexample
- -exec-return
+ -stack-list-frames [ @var{low-frame} @var{high-frame} ]
@end smallexample
-Makes current function return immediately. Doesn't execute the inferior.
-Displays the new current frame.
-
-@subsubheading @value{GDBN} Command
+List the frames currently on the stack. For each frame it displays the
+following info:
-The corresponding @value{GDBN} command is @samp{return}.
+@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
-@subsubheading Example
+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.
-@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",
-fullname="/home/foo/bar/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",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
-(@value{GDBP})
-@end smallexample
+@subsubheading @value{GDBN} Command
+The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
-@subheading The @code{-exec-run} Command
-@findex -exec-run
+@subsubheading Example
-@subsubheading Synopsis
+Full stack backtrace:
@smallexample
- -exec-run
-@end smallexample
-
-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
+(gdb)
+-stack-list-frames
+^done,stack=
+[frame=@{level="0",addr="0x0001076c",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"@},
+frame=@{level="1",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="2",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="3",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="4",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="5",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="6",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="7",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="8",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="9",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="10",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="11",addr="0x00010738",func="main",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"@}]
+(gdb)
+@end smallexample
-The corresponding @value{GDBN} command is @samp{run}.
+Show frames between @var{low_frame} and @var{high_frame}:
-@subsubheading Example
+@smallexample
+(gdb)
+-stack-list-frames 3 5
+^done,stack=
+[frame=@{level="3",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="4",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="5",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
+(gdb)
+@end smallexample
+
+Show a single frame:
@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",
-fullname="/home/foo/bar/recursive2.c",line="4"@}
-(@value{GDBP})
+(gdb)
+-stack-list-frames 3 3
+^done,stack=
+[frame=@{level="3",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
+(gdb)
@end smallexample
-@subheading The @code{-exec-show-arguments} Command
-@findex -exec-show-arguments
+@subheading The @code{-stack-list-locals} Command
+@findex -stack-list-locals
@subsubheading Synopsis
@smallexample
- -exec-show-arguments
+ -stack-list-locals @var{print-values}
@end smallexample
-Print the arguments of the program.
+Display the local variable names for the selected frame. If
+@var{print-values} is 0 or @code{--no-values}, print only the names of
+the variables; if it is 1 or @code{--all-values}, print also their
+values; and if it is 2 or @code{--simple-values}, print the name,
+type and value for simple data types and the name and type for arrays,
+structures and unions. In this last case, a frontend can immediately
+display the value of simple data types and create variable objects for
+other data types when the the user wishes to explore their values in
+more detail.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{show args}.
+@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
@subsubheading Example
-N.A.
-@c @subheading -exec-signal
+@smallexample
+(gdb)
+-stack-list-locals 0
+^done,locals=[name="A",name="B",name="C"]
+(gdb)
+-stack-list-locals --all-values
+^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
+ @{name="C",value="@{1, 2, 3@}"@}]
+-stack-list-locals --simple-values
+^done,locals=[@{name="A",type="int",value="1"@},
+ @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}]
+(gdb)
+@end smallexample
-@subheading The @code{-exec-step} Command
-@findex -exec-step
+
+@subheading The @code{-stack-select-frame} Command
+@findex -stack-select-frame
@subsubheading Synopsis
@smallexample
- -exec-step
+ -stack-select-frame @var{framenum}
@end smallexample
-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.
+Change the selected frame. Select a different frame @var{framenum} on
+the stack.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{step}.
+The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
+@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
@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",
-fullname="/home/foo/bar/recursive2.c",line="11"@}
-(@value{GDBP})
+(gdb)
+-stack-select-frame 2
+^done
+(gdb)
@end smallexample
-Regular stepping:
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Variable Objects
+@section @sc{gdb/mi} Variable Objects
-@smallexample
--exec-step
-^running
-(@value{GDBP})
-*stopped,reason="end-stepping-range",line="14",file="recursive2.c"
-(@value{GDBP})
-@end smallexample
+@subheading Motivation for Variable Objects in @sc{gdb/mi}
-@subheading The @code{-exec-step-instruction} Command
-@findex -exec-step-instruction
+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}.
-@subsubheading Synopsis
+The two main reasons for that are:
-@smallexample
- -exec-step-instruction
-@end smallexample
+@enumerate 1
+@item
+It has been proven in practice (it is already on its second generation).
-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.
+@item
+It will shorten development time (needless to say how important it is
+now).
+@end enumerate
-@subsubheading @value{GDBN} Command
+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.
-The corresponding @value{GDBN} command is @samp{stepi}.
+@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:
-@subsubheading Example
+@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
-@smallexample
-(@value{GDBP})
--exec-step-instruction
-^running
+@subheading Introduction to Variable Objects in @sc{gdb/mi}
-(@value{GDBP})
-*stopped,reason="end-stepping-range",
-frame=@{func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/try.c",line="10"@}
-(@value{GDBP})
--exec-step-instruction
-^running
+@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.
-(@value{GDBP})
-*stopped,reason="end-stepping-range",
-frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/try.c",line="10"@}
-(@value{GDBP})
-@end smallexample
+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.).
-@subheading The @code{-exec-until} Command
-@findex -exec-until
+The following is the complete set of @sc{gdb/mi} operations defined to
+access this functionality:
-@subsubheading Synopsis
+@multitable @columnfractions .4 .6
+@item @strong{Operation}
+@tab @strong{Description}
-@smallexample
- -exec-until [ @var{location} ]
-@end smallexample
+@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
-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}.
+In the next subsection we describe each operation in detail and suggest
+how it can be used.
-@subsubheading @value{GDBN} Command
+@subheading Description And Use of Operations on Variable Objects
-The corresponding @value{GDBN} command is @samp{until}.
+@subheading The @code{-var-create} Command
+@findex -var-create
-@subsubheading Example
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--exec-until recursive2.c:6
-^running
-(@value{GDBP})
-x = 55
-*stopped,reason="location-reached",frame=@{func="main",args=[],
-file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"@}
-(@value{GDBP})
+ -var-create @{@var{name} | "-"@}
+ @{@var{frame-addr} | "*"@} @var{expression}
@end smallexample
-@ignore
-@subheading -file-clear
-Is this going away????
-@end ignore
-
+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.
-@subheading The @code{-file-exec-and-symbols} Command
-@findex -file-exec-and-symbols
+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.
-@subsubheading Synopsis
+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.
-@smallexample
- -file-exec-and-symbols @var{file}
-@end smallexample
+@var{expression} is any expression valid on the current language set (must not
+begin with a @samp{*}), or one of the following:
-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.
+@itemize @bullet
+@item
+@samp{*@var{addr}}, where @var{addr} is the address of a memory cell
-@subsubheading @value{GDBN} Command
+@item
+@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
-The corresponding @value{GDBN} command is @samp{file}.
+@item
+@samp{$@var{regname}} --- a CPU register name
+@end itemize
-@subsubheading Example
+@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:
@smallexample
-(@value{GDBP})
--file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
-^done
-(@value{GDBP})
+ name="@var{name}",numchild="N",type="@var{type}"
@end smallexample
-@subheading The @code{-file-exec-file} Command
-@findex -file-exec-file
+@subheading The @code{-var-delete} Command
+@findex -var-delete
@subsubheading Synopsis
@smallexample
- -file-exec-file @var{file}
+ -var-delete @var{name}
@end smallexample
-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.
+Deletes a previously created variable object and all of its children.
-@subsubheading @value{GDBN} Command
+Returns an error if the object @var{name} is not found.
-The corresponding @value{GDBN} command is @samp{exec-file}.
-@subsubheading Example
+@subheading The @code{-var-set-format} Command
+@findex -var-set-format
+
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
-^done
-(@value{GDBP})
+ -var-set-format @var{name} @var{format-spec}
@end smallexample
+Sets the output format for the value of the object @var{name} to be
+@var{format-spec}.
-@subheading The @code{-file-list-exec-sections} Command
-@findex -file-list-exec-sections
-
-@subsubheading Synopsis
+The syntax for the @var{format-spec} is as follows:
@smallexample
- -file-list-exec-sections
+ @var{format-spec} @expansion{}
+ @{binary | decimal | hexadecimal | octal | natural@}
@end smallexample
-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{-var-show-format} Command
+@findex -var-show-format
+@subsubheading Synopsis
-@subheading The @code{-file-list-exec-source-file} Command
-@findex -file-list-exec-source-file
+@smallexample
+ -var-show-format @var{name}
+@end smallexample
-@subsubheading Synopsis
+Returns the format used to display the value of the object @var{name}.
@smallexample
- -file-list-exec-source-file
+ @var{format} @expansion{}
+ @var{format-spec}
@end smallexample
-List the line number, the current source file, and the absolute path
-to the current source file for the current executable.
-@subsubheading @value{GDBN} Command
+@subheading The @code{-var-info-num-children} Command
+@findex -var-info-num-children
-There's no @value{GDBN} command which directly corresponds to this one.
+@subsubheading Synopsis
-@subsubheading Example
+@smallexample
+ -var-info-num-children @var{name}
+@end smallexample
+
+Returns the number of children of a variable object @var{name}:
@smallexample
-(@value{GDBP})
-123-file-list-exec-source-file
-123^done,line="1",file="foo.c",fullname="/home/bar/foo.c"
-(@value{GDBP})
+ numchild=@var{n}
@end smallexample
-@subheading The @code{-file-list-exec-source-files} Command
-@findex -file-list-exec-source-files
+@subheading The @code{-var-list-children} Command
+@findex -var-list-children
@subsubheading Synopsis
@smallexample
- -file-list-exec-source-files
+ -var-list-children [@var{print-values}] @var{name}
@end smallexample
+@anchor{-var-list-children}
-List the source files for the current executable.
-
-It will always output the filename, but only when GDB can find the absolute
-file name of a source file, will it output the fullname.
-
-@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}.
+Return a list of the children of the specified variable object and
+create variable objects for them, if they do not already exist. With
+a single argument or if @var{print-values} has a value for of 0 or
+@code{--no-values}, print only the names of the variables; if
+@var{print-values} is 1 or @code{--all-values}, also print their
+values; and if it is 2 or @code{--simple-values} print the name and
+value for simple data types and just the name for arrays, structures
+and unions.
@subsubheading Example
+
@smallexample
-(@value{GDBP})
--file-list-exec-source-files
-^done,files=[
-@{file=foo.c,fullname=/home/foo.c@},
-@{file=/home/bar.c,fullname=/home/bar.c@},
-@{file=gdb_could_not_find_fullpath.c@}]
-(@value{GDBP})
+(gdb)
+ -var-list-children n
+ ^done,numchild=@var{n},children=[@{name=@var{name},
+ numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
+(gdb)
+ -var-list-children --all-values n
+ ^done,numchild=@var{n},children=[@{name=@var{name},
+ numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
@end smallexample
-@subheading The @code{-file-list-shared-libraries} Command
-@findex -file-list-shared-libraries
+
+@subheading The @code{-var-info-type} Command
+@findex -var-info-type
@subsubheading Synopsis
@smallexample
- -file-list-shared-libraries
+ -var-info-type @var{name}
@end smallexample
-List the shared libraries in the program.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{info shared}.
+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:
-@subsubheading Example
-N.A.
+@smallexample
+ type=@var{typename}
+@end smallexample
-@subheading The @code{-file-list-symbol-files} Command
-@findex -file-list-symbol-files
+@subheading The @code{-var-info-expression} Command
+@findex -var-info-expression
@subsubheading Synopsis
@smallexample
- -file-list-symbol-files
+ -var-info-expression @var{name}
@end smallexample
-List symbol files.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{info file} (part of it).
+Returns what is represented by the variable object @var{name}:
-@subsubheading Example
-N.A.
+@smallexample
+ lang=@var{lang-spec},exp=@var{expression}
+@end smallexample
+@noindent
+where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
-@subheading The @code{-file-symbol-file} Command
-@findex -file-symbol-file
+@subheading The @code{-var-show-attributes} Command
+@findex -var-show-attributes
@subsubheading Synopsis
@smallexample
- -file-symbol-file @var{file}
+ -var-show-attributes @var{name}
@end smallexample
-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.
+List attributes of the specified variable object @var{name}:
-@subsubheading @value{GDBN} Command
+@smallexample
+ status=@var{attr} [ ( ,@var{attr} )* ]
+@end smallexample
-The corresponding @value{GDBN} command is @samp{symbol-file}.
+@noindent
+where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
-@subsubheading Example
+@subheading The @code{-var-evaluate-expression} Command
+@findex -var-evaluate-expression
+
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
-^done
-(@value{GDBP})
+ -var-evaluate-expression @var{name}
@end smallexample
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Miscellaneous Commands
-@section Miscellaneous @value{GDBN} commands in @sc{gdb/mi}
+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:
-@c @subheading -gdb-complete
+@smallexample
+ value=@var{value}
+@end smallexample
-@subheading The @code{-gdb-exit} Command
-@findex -gdb-exit
+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
@smallexample
- -gdb-exit
+ -var-assign @var{name} @var{expression}
@end smallexample
-Exit @value{GDBN} immediately.
-
-@subsubheading @value{GDBN} Command
-
-Approximately corresponds to @samp{quit}.
+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
@smallexample
-(@value{GDBP})
--gdb-exit
+(gdb)
+-var-assign var1 3
+^done,value="3"
+(gdb)
+-var-update *
+^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}]
+(gdb)
@end smallexample
-@subheading The @code{-gdb-set} Command
-@findex -gdb-set
+@subheading The @code{-var-update} Command
+@findex -var-update
@subsubheading Synopsis
@smallexample
- -gdb-set
+ -var-update [@var{print-values}] @{@var{name} | "*"@}
@end smallexample
-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}.
+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. The
+option @var{print-values} determines whether names both and values, or
+just names are printed in the manner described for
+@code{-var-list-children} (@pxref{-var-list-children}).
@subsubheading Example
@smallexample
-(@value{GDBP})
--gdb-set $foo=3
-^done
-(@value{GDBP})
+(gdb)
+-var-assign var1 3
+^done,value="3"
+(gdb)
+-var-update --all-values var1
+^done,changelist=[@{name="var1",value="3",in_scope="true",
+type_changed="false"@}]
+(gdb)
@end smallexample
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Data Manipulation
+@section @sc{gdb/mi} Data Manipulation
-@subheading The @code{-gdb-show} Command
-@findex -gdb-show
-
-@subsubheading Synopsis
-
-@smallexample
- -gdb-show
-@end smallexample
-
-Show the current value of a @value{GDBN} variable.
+@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.
-@subsubheading @value{GDBN} command
+@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.
-The corresponding @value{GDBN} command is @samp{show}.
+@subheading The @code{-data-disassemble} Command
+@findex -data-disassemble
-@subsubheading Example
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--gdb-show annotate
-^done,value="0"
-(@value{GDBP})
+ -data-disassemble
+ [ -s @var{start-addr} -e @var{end-addr} ]
+ | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
+ -- @var{mode}
@end smallexample
-@c @subheading -gdb-source
+@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
-@subheading The @code{-gdb-version} Command
-@findex -gdb-version
+@subsubheading Result
-@subsubheading Synopsis
+The output for each instruction is composed of four fields:
-@smallexample
- -gdb-version
-@end smallexample
+@itemize @bullet
+@item Address
+@item Func-name
+@item Offset
+@item Instruction
+@end itemize
-Show version information for @value{GDBN}. Used mostly in testing.
+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 equivalent @value{GDBN} command. @value{GDBN} by default shows this
-information when you start an interactive session.
+There's no direct mapping from this command to the CLI.
@subsubheading Example
-@c This example modifies the actual output from GDB to avoid overfull
-@c box in TeX.
+Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
+
@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})
+(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 smallexample
-@subheading The @code{-interpreter-exec} Command
-@findex -interpreter-exec
-
-@subheading Synopsis
+Disassemble the whole @code{main} function. Line 32 is part of
+@code{main}.
@smallexample
--interpreter-exec @var{interpreter} @var{command}
+-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 "@}]
+(gdb)
@end smallexample
-Execute the specified @var{command} in the given @var{interpreter}.
-
-@subheading @value{GDBN} Command
+Disassemble 3 instructions from the start of @code{main}:
-The corresponding @value{GDBN} command is @samp{interpreter-exec}.
+@smallexample
+(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 smallexample
-@subheading Example
+Disassemble 3 instructions from the start of @code{main} in mixed mode:
@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})
+(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 smallexample
-@subheading The @code{-inferior-tty-set} Command
-@findex -inferior-tty-set
-@subheading Synopsis
+@subheading The @code{-data-evaluate-expression} Command
+@findex -data-evaluate-expression
+
+@subsubheading Synopsis
@smallexample
--inferior-tty-set /dev/pts/1
+ -data-evaluate-expression @var{expr}
@end smallexample
-Set terminal for future runs of the program being debugged.
+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.
-@subheading @value{GDBN} Command
+@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.
-The corresponding @value{GDBN} command is @samp{set inferior-tty /dev/pts/1}.
+@subsubheading Example
-@subheading 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
-(@value{GDBP})
--inferior-tty-set /dev/pts/1
-^done
-(@value{GDBP})
+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 smallexample
-@subheading The @code{-inferior-tty-show} Command
-@findex -inferior-tty-show
-@subheading Synopsis
+@subheading The @code{-data-list-changed-registers} Command
+@findex -data-list-changed-registers
+
+@subsubheading Synopsis
@smallexample
--inferior-tty-show
+ -data-list-changed-registers
@end smallexample
-Show terminal for future runs of program being debugged.
+Display a list of the registers that have changed.
-@subheading @value{GDBN} Command
+@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{show inferior-tty}.
+@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
+has the corresponding command @samp{gdb_changed_register_list}.
-@subheading Example
+@subsubheading Example
-@smallexample
-(@value{GDBP})
--inferior-tty-set /dev/pts/1
-^done
-(@value{GDBP})
--inferior-tty-show
-^done,inferior_tty_terminal="/dev/pts/1"
-(@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
+On a PPC MBX board:
+@smallexample
+(gdb)
+-exec-continue
+^running
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Stack Manipulation
-@section @sc{gdb/mi} Stack Manipulation Commands
+(gdb)
+*stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
+args=[],file="try.c",fullname="/home/foo/bar/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 smallexample
-@subheading The @code{-stack-info-frame} Command
-@findex -stack-info-frame
+@subheading The @code{-data-list-register-names} Command
+@findex -data-list-register-names
@subsubheading Synopsis
@smallexample
- -stack-info-frame
+ -data-list-register-names [ ( @var{regno} )+ ]
@end smallexample
-Get info on the selected frame.
+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
-The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
-(without arguments).
+@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})
--stack-info-frame
-^done,frame=@{level="1",addr="0x0001076c",func="callee3",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}
-(@value{GDBP})
+(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 smallexample
-@subheading The @code{-stack-info-depth} Command
-@findex -stack-info-depth
+@subheading The @code{-data-list-register-values} Command
+@findex -data-list-register-values
@subsubheading Synopsis
@smallexample
- -stack-info-depth [ @var{max-depth} ]
+ -data-list-register-values @var{fmt} [ ( @var{regno} )*]
@end smallexample
-Return the depth of the stack. If the integer argument @var{max-depth}
-is specified, do not count beyond @var{max-depth} frames.
+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
-There's no equivalent @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 stack with frame levels 0 through 11:
+For a PPC MBX board (note: line breaks are for readability only, they
+don't appear in the actual output):
@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})
+(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 smallexample
-@subheading The @code{-stack-list-arguments} Command
-@findex -stack-list-arguments
+
+@subheading The @code{-data-read-memory} Command
+@findex -data-read-memory
@subsubheading Synopsis
@smallexample
- -stack-list-arguments @var{show-values}
- [ @var{low-frame} @var{high-frame} ]
+ -data-read-memory [ -o @var{byte-offset} ]
+ @var{address} @var{word-format} @var{word-size}
+ @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
@end smallexample
-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",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
-frame=@{level="1",addr="0x0001076c",func="callee3",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
-frame=@{level="2",addr="0x0001078c",func="callee2",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
-frame=@{level="3",addr="0x000107b4",func="callee1",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
-frame=@{level="4",addr="0x000107e0",func="main",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/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
+@noindent
+where:
-@c @subheading -stack-list-exception-handlers
+@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}).
-@subheading The @code{-stack-list-frames} Command
-@findex -stack-list-frames
+@item @var{word-size}
+The size of each memory word in bytes.
-@subsubheading Synopsis
+@item @var{nr-rows}
+The number of rows in the output table.
-@smallexample
- -stack-list-frames [ @var{low-frame} @var{high-frame} ]
-@end smallexample
+@item @var{nr-cols}
+The number of columns in the output table.
-List the frames currently on the stack. For each frame it displays the
-following info:
+@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).
-@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}.
+@item @var{byte-offset}
+An offset to add to the @var{address} before fetching memory.
@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.
+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} commands are @samp{backtrace} and @samp{where}.
+The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
+@samp{gdb_get_mem} memory read command.
@subsubheading Example
-Full stack backtrace:
+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})
--stack-list-frames
-^done,stack=
-[frame=@{level="0",addr="0x0001076c",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"@},
-frame=@{level="1",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="2",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="6",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="7",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="8",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="9",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="10",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="11",addr="0x00010738",func="main",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"@}]
-(@value{GDBP})
+(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 smallexample
-Show frames between @var{low_frame} and @var{high_frame}:
+Read two bytes of memory starting at address @code{shorts + 64} and
+display as a single word formatted in decimal.
@smallexample
-(@value{GDBP})
--stack-list-frames 3 5
-^done,stack=
-[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
-frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
-(@value{GDBP})
+(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 smallexample
-Show a single frame:
+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})
--stack-list-frames 3 3
-^done,stack=
-[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
-(@value{GDBP})
+(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 smallexample
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Tracepoint Commands
+@section @sc{gdb/mi} Tracepoint Commands
-@subheading The @code{-stack-list-locals} Command
-@findex -stack-list-locals
+The tracepoint commands are not yet implemented.
-@subsubheading Synopsis
+@c @subheading -trace-actions
-@smallexample
- -stack-list-locals @var{print-values}
-@end smallexample
+@c @subheading -trace-delete
-Display the local variable names for the selected frame. If
-@var{print-values} is 0 or @code{--no-values}, print only the names of
-the variables; if it is 1 or @code{--all-values}, print also their
-values; and if it is 2 or @code{--simple-values}, print the name,
-type and value for simple data types and the name and type for arrays,
-structures and unions. In this last case, a frontend can immediately
-display the value of simple data types and create variable objects for
-other data types when the the user wishes to explore their values in
-more detail.
+@c @subheading -trace-disable
-@subsubheading @value{GDBN} Command
+@c @subheading -trace-dump
-@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
+@c @subheading -trace-enable
-@subsubheading Example
+@c @subheading -trace-exists
-@smallexample
-(@value{GDBP})
--stack-list-locals 0
-^done,locals=[name="A",name="B",name="C"]
-(@value{GDBP})
--stack-list-locals --all-values
-^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
- @{name="C",value="@{1, 2, 3@}"@}]
--stack-list-locals --simple-values
-^done,locals=[@{name="A",type="int",value="1"@},
- @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}]
-(@value{GDBP})
-@end smallexample
+@c @subheading -trace-find
+@c @subheading -trace-frame-number
-@subheading The @code{-stack-select-frame} Command
-@findex -stack-select-frame
+@c @subheading -trace-info
-@subsubheading Synopsis
+@c @subheading -trace-insert
-@smallexample
- -stack-select-frame @var{framenum}
-@end smallexample
+@c @subheading -trace-list
-Change the selected frame. Select a different frame @var{framenum} on
-the stack.
+@c @subheading -trace-pass-count
-@subsubheading @value{GDBN} Command
+@c @subheading -trace-save
-The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
-@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
+@c @subheading -trace-start
-@subsubheading Example
+@c @subheading -trace-stop
-@smallexample
-(@value{GDBP})
--stack-select-frame 2
-^done
-(@value{GDBP})
-@end smallexample
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Symbol Query
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-symbol-list-lines basics.c
^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}]
-(@value{GDBP})
+(gdb)
@end smallexample
@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
-
-@smallexample
- -target-attach @var{pid} | @var{file}
-@end smallexample
-
-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}.
+@node GDB/MI File Commands
+@section @sc{gdb/mi} File Commands
-@subsubheading Example
-N.A.
+This section describes the GDB/MI commands to specify executable file names
+and to read in and obtain symbol table information.
-
-@subheading The @code{-target-compare-sections} Command
-@findex -target-compare-sections
+@subheading The @code{-file-exec-and-symbols} Command
+@findex -file-exec-and-symbols
@subsubheading Synopsis
@smallexample
- -target-compare-sections [ @var{section} ]
+ -file-exec-and-symbols @var{file}
@end smallexample
-Compare data of section @var{section} on target to the exec file.
-Without the argument, all sections are compared.
+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 @value{GDBN} equivalent is @samp{compare-sections}.
-
-@subsubheading Example
-N.A.
-
-
-@subheading The @code{-target-detach} Command
-@findex -target-detach
-
-@subsubheading Synopsis
-
-@smallexample
- -target-detach
-@end smallexample
-
-Disconnect from the remote target. There's no output.
-
-@subsubheading @value{GDBN} command
-
-The corresponding @value{GDBN} command is @samp{detach}.
+The corresponding @value{GDBN} command is @samp{file}.
@subsubheading Example
-@smallexample
-(@value{GDBP})
--target-detach
+@smallexample
+(gdb)
+-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
^done
-(@value{GDBP})
+(gdb)
@end smallexample
-@subheading The @code{-target-disconnect} Command
-@findex -target-disconnect
+@subheading The @code{-file-exec-file} Command
+@findex -file-exec-file
@subsubheading Synopsis
-@example
- -target-disconnect
-@end example
+@smallexample
+ -file-exec-file @var{file}
+@end smallexample
-Disconnect from the remote target. There's no output.
+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
+@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{disconnect}.
+The corresponding @value{GDBN} command is @samp{exec-file}.
@subsubheading Example
@smallexample
-(@value{GDBP})
--target-disconnect
+(gdb)
+-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
^done
-(@value{GDBP})
+(gdb)
@end smallexample
-@subheading The @code{-target-download} Command
-@findex -target-download
+@subheading The @code{-file-list-exec-sections} Command
+@findex -file-list-exec-sections
@subsubheading Synopsis
@smallexample
- -target-download
+ -file-list-exec-sections
@end smallexample
-Loads the executable onto the remote target.
-It prints out an update message every half second, which includes the fields:
+List the sections of the current executable file.
-@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
+@subsubheading @value{GDBN} Command
-@noindent
-Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
-@sc{gdb/mi} Output Syntax}).
+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}.
-In addition, it prints the name and size of the sections, as they are
-downloaded. These messages include the following fields:
+@subsubheading Example
+N.A.
-@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.
+@subheading The @code{-file-list-exec-source-file} Command
+@findex -file-list-exec-source-file
+
+@subsubheading Synopsis
+
+@smallexample
+ -file-list-exec-source-file
+@end smallexample
+
+List the line number, the current source file, and the absolute path
+to the current source file for the current executable.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{load}.
+The @value{GDBN} equivalent is @samp{info source}
@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})
+(gdb)
+123-file-list-exec-source-file
+123^done,line="1",file="foo.c",fullname="/home/bar/foo.c"
+(gdb)
@end smallexample
-@subheading The @code{-target-exec-status} Command
-@findex -target-exec-status
+@subheading The @code{-file-list-exec-source-files} Command
+@findex -file-list-exec-source-files
@subsubheading Synopsis
@smallexample
- -target-exec-status
+ -file-list-exec-source-files
@end smallexample
-Provide information on the state of the target (whether it is running or
-not, for instance).
+List the source files for the current executable.
+
+It will always output the filename, but only when GDB can find the absolute
+file name of a source file, will it output the fullname.
@subsubheading @value{GDBN} Command
-There's no equivalent @value{GDBN} command.
+The @value{GDBN} equivalent is @samp{info sources}.
+@code{gdbtk} has an analogous command @samp{gdb_listfiles}.
@subsubheading Example
-N.A.
-
+@smallexample
+(gdb)
+-file-list-exec-source-files
+^done,files=[
+@{file=foo.c,fullname=/home/foo.c@},
+@{file=/home/bar.c,fullname=/home/bar.c@},
+@{file=gdb_could_not_find_fullpath.c@}]
+(gdb)
+@end smallexample
-@subheading The @code{-target-list-available-targets} Command
-@findex -target-list-available-targets
+@subheading The @code{-file-list-shared-libraries} Command
+@findex -file-list-shared-libraries
@subsubheading Synopsis
@smallexample
- -target-list-available-targets
+ -file-list-shared-libraries
@end smallexample
-List the possible targets to connect to.
+List the shared libraries in the program.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{help target}.
+The corresponding @value{GDBN} command is @samp{info shared}.
@subsubheading Example
N.A.
-@subheading The @code{-target-list-current-targets} Command
-@findex -target-list-current-targets
+@subheading The @code{-file-list-symbol-files} Command
+@findex -file-list-symbol-files
@subsubheading Synopsis
@smallexample
- -target-list-current-targets
+ -file-list-symbol-files
@end smallexample
-Describe the current target.
+List symbol files.
@subsubheading @value{GDBN} Command
-The corresponding information is printed by @samp{info file} (among
-other things).
+The corresponding @value{GDBN} command is @samp{info file} (part of it).
@subsubheading Example
N.A.
-@subheading The @code{-target-list-parameters} Command
-@findex -target-list-parameters
+@subheading The @code{-file-symbol-file} Command
+@findex -file-symbol-file
@subsubheading Synopsis
@smallexample
- -target-list-parameters
+ -file-symbol-file @var{file}
@end smallexample
-@c ????
+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
-No equivalent.
+The corresponding @value{GDBN} command is @samp{symbol-file}.
@subsubheading Example
-N.A.
-
-
-@subheading The @code{-target-select} Command
-@findex -target-select
-
-@subsubheading Synopsis
@smallexample
- -target-select @var{type} @var{parameters @dots{}}
+(gdb)
+-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
+^done
+(gdb)
@end smallexample
-Connect @value{GDBN} to the remote target. This command takes two args:
+@ignore
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Memory Overlay Commands
+@section @sc{gdb/mi} Memory Overlay Commands
-@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 memory overlay commands are not implemented.
-The output is a connection notification, followed by the address at
-which the target program is, in the following form:
+@c @subheading -overlay-auto
-@smallexample
-^connected,addr="@var{address}",func="@var{function name}",
- args=[@var{arg list}]
-@end smallexample
+@c @subheading -overlay-list-mapping-state
-@subsubheading @value{GDBN} Command
+@c @subheading -overlay-list-overlays
-The corresponding @value{GDBN} command is @samp{target}.
+@c @subheading -overlay-map
-@subsubheading Example
+@c @subheading -overlay-off
-@smallexample
-(@value{GDBP})
--target-select async /dev/ttya
-^connected,addr="0xfe00a300",func="??",args=[]
-(@value{GDBP})
-@end smallexample
+@c @subheading -overlay-on
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Thread Commands
-@section @sc{gdb/mi} Thread Commands
+@c @subheading -overlay-unmap
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Signal Handling Commands
+@section @sc{gdb/mi} Signal Handling Commands
-@subheading The @code{-thread-info} Command
-@findex -thread-info
+Signal handling commands are not implemented.
-@subsubheading Synopsis
+@c @subheading -signal-handle
-@smallexample
- -thread-info
-@end smallexample
+@c @subheading -signal-list-handle-actions
-@subsubheading @value{GDBN} command
+@c @subheading -signal-list-signal-types
+@end ignore
-No equivalent.
-@subsubheading Example
-N.A.
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Target Manipulation
+@section @sc{gdb/mi} Target Manipulation Commands
-@subheading The @code{-thread-list-all-threads} Command
-@findex -thread-list-all-threads
+@subheading The @code{-target-attach} Command
+@findex -target-attach
@subsubheading Synopsis
@smallexample
- -thread-list-all-threads
+ -target-attach @var{pid} | @var{file}
@end smallexample
-@subsubheading @value{GDBN} Command
+Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
-The equivalent @value{GDBN} command is @samp{info threads}.
+@subsubheading @value{GDBN} command
+
+The corresponding @value{GDBN} command is @samp{attach}.
@subsubheading Example
N.A.
-@subheading The @code{-thread-list-ids} Command
-@findex -thread-list-ids
+@subheading The @code{-target-compare-sections} Command
+@findex -target-compare-sections
@subsubheading Synopsis
@smallexample
- -thread-list-ids
+ -target-compare-sections [ @var{section} ]
@end smallexample
-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.
+Compare data of section @var{section} on target to the exec file.
+Without the argument, all sections are compared.
@subsubheading @value{GDBN} Command
-Part of @samp{info threads} supplies the same information.
+The @value{GDBN} equivalent is @samp{compare-sections}.
@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
+N.A.
-@subheading The @code{-thread-select} Command
-@findex -thread-select
+@subheading The @code{-target-detach} Command
+@findex -target-detach
@subsubheading Synopsis
@smallexample
- -thread-select @var{threadnum}
+ -target-detach
@end smallexample
-Make @var{threadnum} the current thread. It prints the number of the new
-current thread, and the topmost frame for that thread.
+Detach from the remote target which normally resumes its execution.
+There's no output.
-@subsubheading @value{GDBN} Command
+@subsubheading @value{GDBN} command
-The corresponding @value{GDBN} command is @samp{thread}.
+The corresponding @value{GDBN} command is @samp{detach}.
@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})
+(gdb)
+-target-detach
+^done
+(gdb)
@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
+@subheading The @code{-target-disconnect} Command
+@findex -target-disconnect
-@c @subheading -trace-enable
+@subsubheading Synopsis
-@c @subheading -trace-exists
+@example
+ -target-disconnect
+@end example
-@c @subheading -trace-find
+Disconnect from the remote target. There's no output and the target is
+generally not resumed.
-@c @subheading -trace-frame-number
+@subsubheading @value{GDBN} command
-@c @subheading -trace-info
+The corresponding @value{GDBN} command is @samp{disconnect}.
-@c @subheading -trace-insert
+@subsubheading Example
-@c @subheading -trace-list
+@smallexample
+(gdb)
+-target-disconnect
+^done
+(gdb)
+@end smallexample
-@c @subheading -trace-pass-count
-@c @subheading -trace-save
+@subheading The @code{-target-download} Command
+@findex -target-download
-@c @subheading -trace-start
+@subsubheading Synopsis
-@c @subheading -trace-stop
+@smallexample
+ -target-download
+@end smallexample
+Loads the executable onto the remote target.
+It prints out an update message every half second, which includes the fields:
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Variable Objects
-@section @sc{gdb/mi} Variable Objects
+@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}).
-@subheading Motivation for Variable Objects in @sc{gdb/mi}
+In addition, it prints the name and size of the sections, as they are
+downloaded. These messages include the following fields:
-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}.
+@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
-The two main reasons for that are:
+@noindent
+At the end, a summary is printed.
-@enumerate 1
-@item
-It has been proven in practice (it is already on its second generation).
+@subsubheading @value{GDBN} Command
-@item
-It will shorten development time (needless to say how important it is
-now).
-@end enumerate
+The corresponding @value{GDBN} command is @samp{load}.
-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.
+@subsubheading Example
-@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:
+Note: each status message appears on a single line. Here the messages
+have been broken down so that they can fit onto a page.
-@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
+@smallexample
+(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 smallexample
-@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.
+@subheading The @code{-target-exec-status} Command
+@findex -target-exec-status
-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.
+@subsubheading Synopsis
-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.).
+@smallexample
+ -target-exec-status
+@end smallexample
-The following is the complete set of @sc{gdb/mi} operations defined to
-access this functionality:
+Provide information on the state of the target (whether it is running or
+not, for instance).
-@multitable @columnfractions .4 .6
-@item @strong{Operation}
-@tab @strong{Description}
+@subsubheading @value{GDBN} Command
-@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
+There's no equivalent @value{GDBN} command.
-In the next subsection we describe each operation in detail and suggest
-how it can be used.
+@subsubheading Example
+N.A.
-@subheading Description And Use of Operations on Variable Objects
-@subheading The @code{-var-create} Command
-@findex -var-create
+@subheading The @code{-target-list-available-targets} Command
+@findex -target-list-available-targets
@subsubheading Synopsis
@smallexample
- -var-create @{@var{name} | "-"@}
- @{@var{frame-addr} | "*"@} @var{expression}
+ -target-list-available-targets
@end smallexample
-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.
+List the possible targets to connect to.
-@var{expression} is any expression valid on the current language set (must not
-begin with a @samp{*}), or one of the following:
+@subsubheading @value{GDBN} Command
-@itemize @bullet
-@item
-@samp{*@var{addr}}, where @var{addr} is the address of a memory cell
+The corresponding @value{GDBN} command is @samp{help target}.
-@item
-@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
+@subsubheading Example
+N.A.
-@item
-@samp{$@var{regname}} --- a CPU register name
-@end itemize
-@subsubheading Result
+@subheading The @code{-target-list-current-targets} Command
+@findex -target-list-current-targets
-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:
+@subsubheading Synopsis
@smallexample
- name="@var{name}",numchild="N",type="@var{type}"
+ -target-list-current-targets
@end smallexample
+Describe the current target.
+
+@subsubheading @value{GDBN} Command
-@subheading The @code{-var-delete} Command
-@findex -var-delete
+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
@smallexample
- -var-delete @var{name}
+ -target-list-parameters
@end smallexample
-Deletes a previously created variable object and all of its children.
+@c ????
-Returns an error if the object @var{name} is not found.
+@subsubheading @value{GDBN} Command
+No equivalent.
-@subheading The @code{-var-set-format} Command
-@findex -var-set-format
+@subsubheading Example
+N.A.
+
+
+@subheading The @code{-target-select} Command
+@findex -target-select
@subsubheading Synopsis
@smallexample
- -var-set-format @var{name} @var{format-spec}
+ -target-select @var{type} @var{parameters @dots{}}
@end smallexample
-Sets the output format for the value of the object @var{name} to be
-@var{format-spec}.
+Connect @value{GDBN} to the remote target. This command takes two args:
-The syntax for the @var{format-spec} is as follows:
+@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
- @var{format-spec} @expansion{}
- @{binary | decimal | hexadecimal | octal | natural@}
+^connected,addr="@var{address}",func="@var{function name}",
+ args=[@var{arg list}]
@end smallexample
+@subsubheading @value{GDBN} Command
-@subheading The @code{-var-show-format} Command
-@findex -var-show-format
+The corresponding @value{GDBN} command is @samp{target}.
-@subsubheading Synopsis
+@subsubheading Example
@smallexample
- -var-show-format @var{name}
+(gdb)
+-target-select async /dev/ttya
+^connected,addr="0xfe00a300",func="??",args=[]
+(gdb)
@end smallexample
-Returns the format used to display the value of the object @var{name}.
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Miscellaneous Commands
+@section Miscellaneous @sc{gdb/mi} Commands
+
+@c @subheading -gdb-complete
+
+@subheading The @code{-gdb-exit} Command
+@findex -gdb-exit
+
+@subsubheading Synopsis
@smallexample
- @var{format} @expansion{}
- @var{format-spec}
+ -gdb-exit
@end smallexample
+Exit @value{GDBN} immediately.
-@subheading The @code{-var-info-num-children} Command
-@findex -var-info-num-children
+@subsubheading @value{GDBN} Command
-@subsubheading Synopsis
+Approximately corresponds to @samp{quit}.
+
+@subsubheading Example
@smallexample
- -var-info-num-children @var{name}
+(gdb)
+-gdb-exit
+^exit
@end smallexample
-Returns the number of children of a variable object @var{name}:
+
+@subheading The @code{-exec-abort} Command
+@findex -exec-abort
+
+@subsubheading Synopsis
@smallexample
- numchild=@var{n}
+ -exec-abort
@end smallexample
+Kill the inferior running program.
-@subheading The @code{-var-list-children} Command
-@findex -var-list-children
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{kill}.
+
+@subsubheading Example
+N.A.
+
+
+@subheading The @code{-gdb-set} Command
+@findex -gdb-set
@subsubheading Synopsis
@smallexample
- -var-list-children [@var{print-values}] @var{name}
+ -gdb-set
@end smallexample
-@anchor{-var-list-children}
-Return a list of the children of the specified variable object and
-create variable objects for them, if they do not already exist. With
-a single argument or if @var{print-values} has a value for of 0 or
-@code{--no-values}, print only the names of the variables; if
-@var{print-values} is 1 or @code{--all-values}, also print their
-values; and if it is 2 or @code{--simple-values} print the name and
-value for simple data types and just the name for arrays, structures
-and unions.
+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})
- -var-list-children n
- ^done,numchild=@var{n},children=[@{name=@var{name},
- numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
-(@value{GDBP})
- -var-list-children --all-values n
- ^done,numchild=@var{n},children=[@{name=@var{name},
- numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
+(gdb)
+-gdb-set $foo=3
+^done
+(gdb)
@end smallexample
-@subheading The @code{-var-info-type} Command
-@findex -var-info-type
+@subheading The @code{-gdb-show} Command
+@findex -gdb-show
@subsubheading Synopsis
@smallexample
- -var-info-type @var{name}
+ -gdb-show
@end smallexample
-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:
+Show the current value of a @value{GDBN} variable.
+
+@subsubheading @value{GDBN} command
+
+The corresponding @value{GDBN} command is @samp{show}.
+
+@subsubheading Example
@smallexample
- type=@var{typename}
+(gdb)
+-gdb-show annotate
+^done,value="0"
+(gdb)
@end smallexample
+@c @subheading -gdb-source
+
-@subheading The @code{-var-info-expression} Command
-@findex -var-info-expression
+@subheading The @code{-gdb-version} Command
+@findex -gdb-version
@subsubheading Synopsis
@smallexample
- -var-info-expression @var{name}
+ -gdb-version
@end smallexample
-Returns what is represented by the variable object @var{name}:
+Show version information for @value{GDBN}. Used mostly in testing.
+
+@subsubheading @value{GDBN} Command
+
+The @value{GDBN} equivalent is @samp{show version}. @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
- lang=@var{lang-spec},exp=@var{expression}
+(gdb)
+-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
+(gdb)
@end smallexample
-@noindent
-where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
-
-@subheading The @code{-var-show-attributes} Command
-@findex -var-show-attributes
+@subheading The @code{-interpreter-exec} Command
+@findex -interpreter-exec
-@subsubheading Synopsis
+@subheading Synopsis
@smallexample
- -var-show-attributes @var{name}
+-interpreter-exec @var{interpreter} @var{command}
@end smallexample
+@anchor{-interpreter-exec}
-List attributes of the specified variable object @var{name}:
-
-@smallexample
- status=@var{attr} [ ( ,@var{attr} )* ]
-@end smallexample
+Execute the specified @var{command} in the given @var{interpreter}.
-@noindent
-where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
+@subheading @value{GDBN} Command
-@subheading The @code{-var-evaluate-expression} Command
-@findex -var-evaluate-expression
+The corresponding @value{GDBN} command is @samp{interpreter-exec}.
-@subsubheading Synopsis
+@subheading Example
@smallexample
- -var-evaluate-expression @var{name}
+(gdb)
+-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
+(gdb)
@end smallexample
-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:
+@subheading The @code{-inferior-tty-set} Command
+@findex -inferior-tty-set
+
+@subheading Synopsis
@smallexample
- value=@var{value}
+-inferior-tty-set /dev/pts/1
@end smallexample
-Note that one must invoke @code{-var-list-children} for a variable
-before the value of a child variable can be evaluated.
+Set terminal for future runs of the program being debugged.
-@subheading The @code{-var-assign} Command
-@findex -var-assign
+@subheading @value{GDBN} Command
-@subsubheading Synopsis
+The corresponding @value{GDBN} command is @samp{set inferior-tty} /dev/pts/1.
+
+@subheading Example
@smallexample
- -var-assign @var{name} @var{expression}
+(gdb)
+-inferior-tty-set /dev/pts/1
+^done
+(gdb)
@end smallexample
-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.
+@subheading The @code{-inferior-tty-show} Command
+@findex -inferior-tty-show
-@subsubheading Example
+@subheading Synopsis
@smallexample
-(@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})
+-inferior-tty-show
@end smallexample
-@subheading The @code{-var-update} Command
-@findex -var-update
-
-@subsubheading Synopsis
+Show terminal for future runs of program being debugged.
-@smallexample
- -var-update [@var{print-values}] @{@var{name} | "*"@}
-@end smallexample
+@subheading @value{GDBN} Command
-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. The
-option @var{print-values} determines whether names both and values, or
-just names are printed in the manner described for
-@code{-var-list-children} (@pxref{-var-list-children}).
+The corresponding @value{GDBN} command is @samp{show inferior-tty}.
-@subsubheading Example
+@subheading Example
@smallexample
-(@value{GDBP})
--var-assign var1 3
-^done,value="3"
-(@value{GDBP})
--var-update --all-values var1
-^done,changelist=[@{name="var1",value="3",in_scope="true",
-type_changed="false"@}]
-(@value{GDBP})
+(gdb)
+-inferior-tty-set /dev/pts/1
+^done
+(gdb)
+-inferior-tty-show
+^done,inferior_tty_terminal="/dev/pts/1"
+(gdb)
@end smallexample
@node Annotations
foos) or @samp{Qacme.bar} (for setting bars).
@end itemize
-A query or set packet may optionally be followed by a @samp{,} or
-@samp{;} separated list. Stubs must be careful to match the full
-packet name, in case packet names have common prefixes.
+The name of a query or set packet should be separated from any
+parameters by a @samp{:}; the parameters themselves should be
+separated by @samp{,} or @samp{;}. Stubs must be careful to match the
+full packet name, and check for a separator or the end of the packet,
+in case two packet names share a common prefix. New packets should not begin
+with @samp{qC}, @samp{qP}, or @samp{qL}@footnote{The @samp{qP} and @samp{qL}
+packets predate these conventions, and have arguments without any terminator
+for the packet name; we suspect they are in widespread use in places that
+are difficult to upgrade. The @samp{qC} packet has no arguments, but some
+existing stubs (e.g.@: RedBoot) are known to not check for the end of the
+packet.}.
Like the descriptions of the other packets, each description here
has a template showing the packet's overall syntax, followed by an
Returns information on @var{threadid}. Where: @var{mode} is a hex
encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
+Don't use this packet; use the @samp{qThreadExtraInfo} query instead
+(see below).
+
Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
@item qPart:@var{object}:read:@var{annex}:@var{offset},@var{length}
encoding of @var{annex} is specific to the object; it can supply
additional details about what data to access.
+Since this packet is ambiguous with the older @code{qP} packet, we
+plan to rename it.
+
Here are the specific requests of this form defined so far. All
@samp{qPart:@var{object}:read:@dots{}} requests use the same reply
formats, listed below.
An empty reply indicates that @samp{qRcmd} is not recognized.
@end table
+(Note that the @code{qRcmd} packet's name is separated from the
+command by a @samp{,}, not a @samp{:}, contrary to the naming
+conventions above. Please don't use this packet as a model for new
+packets.)
+
+@item qSupported @r{[}:@var{gdbfeature} @r{[};@var{gdbfeature}@r{]}@dots{} @r{]}
+@cindex supported packets, remote query
+@cindex features of the remote protocol
+@cindex @samp{qSupported} packet
+Tell the remote stub about features supported by @value{GDBN}, and
+query the stub for features it supports. This packet allows
+@value{GDBN} and the remote stub to take advantage of each others'
+features. @samp{qSupported} also consolidates multiple feature probes
+at startup, to improve @value{GDBN} performance---a single larger
+packet performs better than multiple smaller probe packets on
+high-latency links. Some features may enable behavior which must not
+be on by default, e.g.@: because it would confuse older clients or
+stubs. Other features may describe packets which could be
+automatically probed for, but are not. These features must be
+reported before @value{GDBN} will use them. This ``default
+unsupported'' behavior is not appropriate for all packets, but it
+helps to keep the initial connection time under control with new
+versions of @value{GDBN} which support increasing numbers of packets.
+
+Reply:
+@table @samp
+@item @var{stubfeature} @r{[};@var{stubfeature}@r{]}@dots{}
+The stub supports or does not support each returned @var{stubfeature},
+depending on the form of each @var{stubfeature} (see below for the
+possible forms).
+@item
+An empty reply indicates that @samp{qSupported} is not recognized,
+or that no features needed to be reported to @value{GDBN}.
+@end table
+
+The allowed forms for each feature (either a @var{gdbfeature} in the
+@samp{qSupported} packet, or a @var{stubfeature} in the response)
+are:
+
+@table @samp
+@item @var{name}=@var{value}
+The remote protocol feature @var{name} is supported, and associated
+with the specified @var{value}. The format of @var{value} depends
+on the feature, but it must not include a semicolon.
+@item @var{name}+
+The remote protocol feature @var{name} is supported, and does not
+need an associated value.
+@item @var{name}-
+The remote protocol feature @var{name} is not supported.
+@item @var{name}?
+The remote protocol feature @var{name} may be supported, and
+@value{GDBN} should auto-detect support in some other way when it is
+needed. This form will not be used for @var{gdbfeature} notifications,
+but may be used for @var{stubfeature} responses.
+@end table
+
+Whenever the stub receives a @samp{qSupported} request, the
+supplied set of @value{GDBN} features should override any previous
+request. This allows @value{GDBN} to put the stub in a known
+state, even if the stub had previously been communicating with
+a different version of @value{GDBN}.
+
+No values of @var{gdbfeature} (for the packet sent by @value{GDBN})
+are defined yet. Stubs should ignore any unknown values for
+@var{gdbfeature}. Any @value{GDBN} which sends a @samp{qSupported}
+packet supports receiving packets of unlimited length (earlier
+versions of @value{GDBN} may reject overly long responses). Values
+for @var{gdbfeature} may be defined in the future to let the stub take
+advantage of new features in @value{GDBN}, e.g.@: incompatible
+improvements in the remote protocol---support for unlimited length
+responses would be a @var{gdbfeature} example, if it were not implied by
+the @samp{qSupported} query. The stub's reply should be independent
+of the @var{gdbfeature} entries sent by @value{GDBN}; first @value{GDBN}
+describes all the features it supports, and then the stub replies with
+all the features it supports.
+
+Similarly, @value{GDBN} will silently ignore unrecognized stub feature
+responses, as long as each response uses one of the standard forms.
+
+Some features are flags. A stub which supports a flag feature
+should respond with a @samp{+} form response. Other features
+require values, and the stub should respond with an @samp{=}
+form response.
+
+Each feature has a default value, which @value{GDBN} will use if
+@samp{qSupported} is not available or if the feature is not mentioned
+in the @samp{qSupported} response. The default values are fixed; a
+stub is free to omit any feature responses that match the defaults.
+
+Not all features can be probed, but for those which can, the probing
+mechanism is useful: in some cases, a stub's internal
+architecture may not allow the protocol layer to know some information
+about the underlying target in advance. This is especially common in
+stubs which may be configured for multiple targets.
+
+These are the currently defined stub features and their properties:
+
+@multitable @columnfractions 0.25 0.2 0.2 0.2
+@c NOTE: The first row should be @headitem, but we do not yet require
+@c a new enough version of Texinfo (4.7) to use @headitem.
+@item Packet Name
+@tab Value Required
+@tab Default
+@tab Probe Allowed
+
+@item @samp{PacketSize}
+@tab Yes
+@tab @samp{-}
+@tab No
+
+@end multitable
+
+These are the currently defined stub features, in more detail:
+
+@table @samp
+@cindex packet size, remote protocol
+@item PacketSize=@var{bytes}
+The remote stub can accept packets up to at least @var{bytes} in
+length. @value{GDBN} will send packets up to this size for bulk
+transfers, and will never send larger packets. This is a limit on the
+data characters in the packet, including the frame and checksum.
+There is no trailing NUL byte in a remote protocol packet; if the stub
+stores packets in a NUL-terminated format, it should allow an extra
+byte in its buffer for the NUL. If this stub feature is not supported,
+@value{GDBN} guesses based on the size of the @samp{g} packet response.
+
+@end table
+
@item qSymbol::
@cindex symbol lookup, remote request
@cindex @samp{qSymbol} packet
the thread's attributes.
@end table
+(Note that the @code{qThreadExtraInfo} packet's name is separated from
+the command by a @samp{,}, not a @samp{:}, contrary to the naming
+conventions above. Please don't use this packet as a model for new
+packets.)
+
@item QTStart
@itemx QTStop
@itemx QTinit
* Protocol basics::
* The F request packet::
* The F reply packet::
-* Memory transfer::
* The Ctrl-C message::
* Console I/O::
-* The isatty call::
-* The system call::
* List of supported calls::
* Protocol specific representation of datatypes::
* Constants::
@cindex file-i/o overview
The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the
-target to use the host's file system and console I/O when calling various
+target to use the host's file system and console I/O to perform various
system calls. System calls on the target system are translated into a
-remote protocol packet to the host system which then performs the needed
-actions and returns with an adequate response packet to the target system.
+remote protocol packet to the host system, which then performs the needed
+actions and returns a response packet to the target system.
This simulates file system operations even on targets that lack file systems.
-The protocol is defined host- and target-system independent. It uses
-its own independent representation of datatypes and values. Both,
+The protocol is defined to be independent of both the host and target systems.
+It uses its own internal representation of datatypes and values. Both
@value{GDBN} and the target's @value{GDBN} stub are responsible for
-translating the system dependent values into the unified protocol values
-when data is transmitted.
+translating the system-dependent value representations into the internal
+protocol representations when data is transmitted.
-The communication is synchronous. A system call is possible only
-when GDB is waiting for the @samp{C}, @samp{c}, @samp{S} or @samp{s}
-packets. While @value{GDBN} handles the request for a system call,
+The communication is synchronous. A system call is possible only when
+@value{GDBN} is waiting for a response from the @samp{C}, @samp{c}, @samp{S}
+or @samp{s} packets. While @value{GDBN} handles the request for a system call,
the target is stopped to allow deterministic access to the target's
-memory. Therefore File-I/O is not interuptible by target signals. It
-is possible to interrupt File-I/O by a user interrupt (Ctrl-C), though.
+memory. Therefore File-I/O is not interruptible by target signals. On
+the other hand, it is possible to interrupt File-I/O by a user interrupt
+(Ctrl-C) within @value{GDBN}.
The target's request to perform a host system call does not finish
the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means,
<- target hits breakpoint and sends a Txx packet
@end smallexample
-The protocol is only used for files on the host file system and
-for I/O on the console. Character or block special devices, pipes,
-named pipes or sockets or any other communication method on the host
+The protocol only supports I/O on the console and to regular files on
+the host file system. Character or block special devices, pipes,
+named pipes, sockets or any other communication method on the host
system are not supported by this protocol.
@node Protocol basics
@subsection Protocol basics
@cindex protocol basics, file-i/o
-The File-I/O protocol uses the @code{F} packet, as request as well
-as as reply packet. Since a File-I/O system call can only occur when
-@value{GDBN} is waiting for the continuing or stepping target, the
-File-I/O request is a reply that @value{GDBN} has to expect as a result
-of a former @samp{C}, @samp{c}, @samp{S} or @samp{s} packet.
+The File-I/O protocol uses the @code{F} packet as the request as well
+as reply packet. Since a File-I/O system call can only occur when
+@value{GDBN} is waiting for a response from the continuing or stepping target,
+the File-I/O request is a reply that @value{GDBN} has to expect as a result
+of a previous @samp{C}, @samp{c}, @samp{S} or @samp{s} packet.
This @code{F} packet contains all information needed to allow @value{GDBN}
to call the appropriate host system call:
All parameters to the system call. Pointers are given as addresses
in the target memory address space. Pointers to strings are given as
pointer/length pair. Numerical values are given as they are.
-Numerical control values are given in a protocol specific representation.
+Numerical control flags are given in a protocol specific representation.
@end itemize
-At that point @value{GDBN} has to perform the following actions.
+At this point, @value{GDBN} has to perform the following actions.
@itemize @bullet
@item
-If parameter pointer values are given, which point to data needed as input
-to a system call, @value{GDBN} requests this data from the target with a
+If the parameters include pointer values to data needed as input to a
+system call, @value{GDBN} requests this data from the target with a
standard @code{m} packet request. This additional communication has to be
expected by the target implementation and is handled as any other @code{m}
packet.
representation as needed. Datatypes are coerced into the host types.
@item
-@value{GDBN} calls the system call
+@value{GDBN} calls the system call.
@item
It then coerces datatypes back to protocol representation.
@item
-If pointer parameters in the request packet point to buffer space in which
-a system call is expected to copy data to, the data is transmitted to the
+If the system call is expected to return data in buffer space specified
+by pointer parameters to the call, the data is transmitted to the
target using a @code{M} or @code{X} packet. This packet has to be expected
by the target implementation and is handled as any other @code{M} or @code{X}
packet.
The @code{F} request packet has the following format:
@table @samp
-
-@smallexample
-@code{F}@var{call-id}@code{,}@var{parameter@dots{}}
-@end smallexample
+@item F@var{call-id},@var{parameter@dots{}}
@var{call-id} is the identifier to indicate the host system call to be called.
This is just the name of the function.
-@var{parameter@dots{}} are the parameters to the system call.
+@var{parameter@dots{}} are the parameters to the system call.
+Parameters are hexadecimal integer values, either the actual values in case
+of scalar datatypes, pointers to target buffer space in case of compound
+datatypes and unspecified memory areas, or pointer/length pairs in case
+of string parameters. These are appended to the @var{call-id} as a
+comma-delimited list. All values are transmitted in ASCII
+string representation, pointer/length pairs separated by a slash.
@end table
-Parameters are hexadecimal integer values, either the real values in case
-of scalar datatypes, as pointers to target buffer space in case of compound
-datatypes and unspecified memory areas or as pointer/length pairs in case
-of string parameters. These are appended to the call-id, each separated
-from its predecessor by a comma. All values are transmitted in ASCII
-string representation, pointer/length pairs separated by a slash.
+
@node The F reply packet
@subsection The @code{F} reply packet
@table @samp
-@smallexample
-@code{F}@var{retcode}@code{,}@var{errno}@code{,}@var{Ctrl-C flag}@code{;}@var{call specific attachment}
-@end smallexample
+@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call specific attachment}
@var{retcode} is the return code of the system call as hexadecimal value.
-@var{errno} is the errno set by the call, in protocol specific representation.
+@var{errno} is the @code{errno} set by the call, in protocol specific representation.
This parameter can be omitted if the call was successful.
-@var{Ctrl-C flag} is only send if the user requested a break. In this
-case, @var{errno} must be send as well, even if the call was successful.
-The @var{Ctrl-C flag} itself consists of the character 'C':
+@var{Ctrl-C flag} is only sent if the user requested a break. In this
+case, @var{errno} must be sent as well, even if the call was successful.
+The @var{Ctrl-C flag} itself consists of the character @samp{C}:
@smallexample
F0,0,C
@end smallexample
@noindent
-or, if the call was interupted before the host call has been performed:
+or, if the call was interrupted before the host call has been performed:
@smallexample
F-1,4,C
@end table
-@node Memory transfer
-@subsection Memory transfer
-@cindex memory transfer, in file-i/o protocol
-
-Structured data which is transferred using a memory read or write as e.g.@:
-a @code{struct stat} is expected to be in a protocol specific format with
-all scalar multibyte datatypes being big endian. This should be done by
-the target before the @code{F} packet is sent resp.@: by @value{GDBN} before
-it transfers memory to the target. Transferred pointers to structured
-data should point to the already coerced data at any time.
@node The Ctrl-C message
@subsection The Ctrl-C message
@cindex ctrl-c message, in file-i/o protocol
-A special case is, if the @var{Ctrl-C flag} is set in the @value{GDBN}
-reply packet. In this case the target should behave, as if it had
+If the Ctrl-C flag is set in the @value{GDBN}
+reply packet (@pxref{The F reply packet}),
+the target should behave as if it had
gotten a break message. The meaning for the target is ``system call
-interupted by @code{SIGINT}''. Consequentially, the target should actually stop
+interrupted by @code{SIGINT}''. Consequentially, the target should actually stop
(as with a break message) and return to @value{GDBN} with a @code{T02}
-packet. In this case, it's important for the target to know, in which
-state the system call was interrupted. Since this action is by design
-not an atomic operation, we have to differ between two cases:
+packet.
+
+It's important for the target to know in which
+state the system call was interrupted. There are two possible cases:
@itemize @bullet
@item
returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system
call hasn't been performed. This is equivalent to the @code{EINTR} handling
on POSIX systems. In any other case, the target may presume that the
-system call has been finished --- successful or not --- and should behave
+system call has been finished --- successfully or not --- and should behave
as if the break message arrived right after the system call.
-@value{GDBN} must behave reliable. If the system call has not been called
+@value{GDBN} must behave reliably. If the system call has not been called
yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as
@code{errno} in the packet. If the system call on the host has been finished
-before the user requests a break, the full action must be finshed by
-@value{GDBN}. This requires sending @code{M} or @code{X} packets as they fit.
-The @code{F} packet may only be send when either nothing has happened
+before the user requests a break, the full action must be finished by
+@value{GDBN}. This requires sending @code{M} or @code{X} packets as necessary.
+The @code{F} packet may only be sent when either nothing has happened
or the full action has been completed.
@node Console I/O
@itemize @bullet
@item
-The user presses @kbd{Ctrl-C}. The behaviour is as explained above, the
+The user presses @kbd{Ctrl-C}. The behaviour is as explained above, and the
@code{read}
system call is treated as finished.
@item
The user presses @kbd{Enter}. This is treated as end of input with a trailing
-line feed.
+newline.
@item
The user presses @kbd{Ctrl-D}. This is treated as end of input. No trailing
-character, especially no Ctrl-D is appended to the input.
+character (neither newline nor Ctrl-D) is appended to the input.
@end itemize
-If the user has typed more characters as fit in the buffer given to
-the read call, the trailing characters are buffered in @value{GDBN} until
-either another @code{read(0, @dots{})} is requested by the target or debugging
-is stopped on users request.
-
-@node The isatty call
-@subsection The @samp{isatty} function call
-@cindex isatty call, file-i/o protocol
-
-A special case in this protocol is the library call @code{isatty} which
-is implemented as its own call inside of this protocol. It returns
-1 to the target if the file descriptor given as parameter is attached
-to the @value{GDBN} console, 0 otherwise. Implementing through system calls
-would require implementing @code{ioctl} and would be more complex than
-needed.
-
-@node The system call
-@subsection The @samp{system} function call
-@cindex system call, file-i/o protocol
-
-The other special case in this protocol is the @code{system} call which
-is implemented as its own call, too. @value{GDBN} is taking over the full
-task of calling the necessary host calls to perform the @code{system}
-call. The return value of @code{system} is simplified before it's returned
-to the target. Basically, the only signal transmitted back is @code{EINTR}
-in case the user pressed @kbd{Ctrl-C}. Otherwise the return value consists
-entirely of the exit status of the called command.
-
-Due to security concerns, the @code{system} call is by default refused
-by @value{GDBN}. The user has to allow this call explicitly with the
-@kbd{set remote system-call-allowed 1} command.
-
-@table @code
-@item set remote system-call-allowed
-@kindex set remote system-call-allowed
-Control whether to allow the @code{system} calls in the File I/O
-protocol for the remote target. The default is zero (disabled).
+If the user has typed more characters than fit in the buffer given to
+the @code{read} call, the trailing characters are buffered in @value{GDBN} until
+either another @code{read(0, @dots{})} is requested by the target, or debugging
+is stopped at the user's request.
-@item show remote system-call-allowed
-@kindex show remote system-call-allowed
-Show the current setting of system calls for the remote File I/O
-protocol.
-@end table
@node List of supported calls
@subsection List of supported calls
@unnumberedsubsubsec open
@cindex open, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int open(const char *pathname, int flags);
int open(const char *pathname, int flags, mode_t mode);
-
-@exdent Request:
-Fopen,pathptr/len,flags,mode
@end smallexample
+@item Request:
+@samp{Fopen,@var{pathptr}/@var{len},@var{flags},@var{mode}}
+
@noindent
-@code{flags} is the bitwise or of the following values:
+@var{flags} is the bitwise @code{OR} of the following values:
@table @code
@item O_CREAT
are concerned.
@item O_EXCL
-When used with O_CREAT, if the file already exists it is
+When used with @code{O_CREAT}, if the file already exists it is
an error and open() fails.
@item O_TRUNC
If the file already exists and the open mode allows
-writing (O_RDWR or O_WRONLY is given) it will be
-truncated to length 0.
+writing (@code{O_RDWR} or @code{O_WRONLY} is given) it will be
+truncated to zero length.
@item O_APPEND
The file is opened in append mode.
@item O_RDWR
The file is opened for reading and writing.
+@end table
@noindent
-Each other bit is silently ignored.
+Other bits are silently ignored.
-@end table
@noindent
-@code{mode} is the bitwise or of the following values:
+@var{mode} is the bitwise @code{OR} of the following values:
@table @code
@item S_IRUSR
@item S_IWOTH
Others have write permission.
+@end table
@noindent
-Each other bit is silently ignored.
+Other bits are silently ignored.
-@end table
-@smallexample
-@exdent Return value:
-open returns the new file descriptor or -1 if an error
-occured.
+@item Return value:
+@code{open} returns the new file descriptor or -1 if an error
+occurred.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EEXIST
-pathname already exists and O_CREAT and O_EXCL were used.
+@var{pathname} already exists and @code{O_CREAT} and @code{O_EXCL} were used.
@item EISDIR
-pathname refers to a directory.
+@var{pathname} refers to a directory.
@item EACCES
The requested access is not allowed.
@item ENAMETOOLONG
-pathname was too long.
+@var{pathname} was too long.
@item ENOENT
-A directory component in pathname does not exist.
+A directory component in @var{pathname} does not exist.
@item ENODEV
-pathname refers to a device, pipe, named pipe or socket.
+@var{pathname} refers to a device, pipe, named pipe or socket.
@item EROFS
-pathname refers to a file on a read-only filesystem and
+@var{pathname} refers to a file on a read-only filesystem and
write access was requested.
@item EFAULT
-pathname is an invalid pointer value.
+@var{pathname} is an invalid pointer value.
@item ENOSPC
No space on device to create the file.
The call was interrupted by the user.
@end table
+@end table
+
@node close
@unnumberedsubsubsec close
@cindex close, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int close(int fd);
+@end smallexample
-@exdent Request:
-Fclose,fd
+@item Request:
+@samp{Fclose,@var{fd}}
-@exdent Return value:
-close returns zero on success, or -1 if an error occurred.
+@item Return value:
+@code{close} returns zero on success, or -1 if an error occurred.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EBADF
-fd isn't a valid open file descriptor.
+@var{fd} isn't a valid open file descriptor.
@item EINTR
The call was interrupted by the user.
@end table
+@end table
+
@node read
@unnumberedsubsubsec read
@cindex read, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int read(int fd, void *buf, unsigned int count);
+@end smallexample
-@exdent Request:
-Fread,fd,bufptr,count
+@item Request:
+@samp{Fread,@var{fd},@var{bufptr},@var{count}}
-@exdent Return value:
+@item Return value:
On success, the number of bytes read is returned.
Zero indicates end of file. If count is zero, read
returns zero as well. On error, -1 is returned.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EBADF
-fd is not a valid file descriptor or is not open for
+@var{fd} is not a valid file descriptor or is not open for
reading.
@item EFAULT
-buf is an invalid pointer value.
+@var{bufptr} is an invalid pointer value.
@item EINTR
The call was interrupted by the user.
@end table
+@end table
+
@node write
@unnumberedsubsubsec write
@cindex write, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int write(int fd, const void *buf, unsigned int count);
+@end smallexample
-@exdent Request:
-Fwrite,fd,bufptr,count
+@item Request:
+@samp{Fwrite,@var{fd},@var{bufptr},@var{count}}
-@exdent Return value:
+@item Return value:
On success, the number of bytes written are returned.
Zero indicates nothing was written. On error, -1
is returned.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EBADF
-fd is not a valid file descriptor or is not open for
+@var{fd} is not a valid file descriptor or is not open for
writing.
@item EFAULT
-buf is an invalid pointer value.
+@var{bufptr} is an invalid pointer value.
@item EFBIG
An attempt was made to write a file that exceeds the
The call was interrupted by the user.
@end table
+@end table
+
@node lseek
@unnumberedsubsubsec lseek
@cindex lseek, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
long lseek (int fd, long offset, int flag);
-
-@exdent Request:
-Flseek,fd,offset,flag
@end smallexample
-@code{flag} is one of:
+@item Request:
+@samp{Flseek,@var{fd},@var{offset},@var{flag}}
+
+@var{flag} is one of:
@table @code
@item SEEK_SET
-The offset is set to offset bytes.
+The offset is set to @var{offset} bytes.
@item SEEK_CUR
-The offset is set to its current location plus offset
+The offset is set to its current location plus @var{offset}
bytes.
@item SEEK_END
-The offset is set to the size of the file plus offset
+The offset is set to the size of the file plus @var{offset}
bytes.
@end table
-@smallexample
-@exdent Return value:
+@item Return value:
On success, the resulting unsigned offset in bytes from
the beginning of the file is returned. Otherwise, a
value of -1 is returned.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EBADF
-fd is not a valid open file descriptor.
+@var{fd} is not a valid open file descriptor.
@item ESPIPE
-fd is associated with the @value{GDBN} console.
+@var{fd} is associated with the @value{GDBN} console.
@item EINVAL
-flag is not a proper value.
+@var{flag} is not a proper value.
@item EINTR
The call was interrupted by the user.
@end table
+@end table
+
@node rename
@unnumberedsubsubsec rename
@cindex rename, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int rename(const char *oldpath, const char *newpath);
+@end smallexample
-@exdent Request:
-Frename,oldpathptr/len,newpathptr/len
+@item Request:
+@samp{Frename,@var{oldpathptr}/@var{len},@var{newpathptr}/@var{len}}
-@exdent Return value:
+@item Return value:
On success, zero is returned. On error, -1 is returned.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EISDIR
-newpath is an existing directory, but oldpath is not a
+@var{newpath} is an existing directory, but @var{oldpath} is not a
directory.
@item EEXIST
-newpath is a non-empty directory.
+@var{newpath} is a non-empty directory.
@item EBUSY
-oldpath or newpath is a directory that is in use by some
+@var{oldpath} or @var{newpath} is a directory that is in use by some
process.
@item EINVAL
of itself.
@item ENOTDIR
-A component used as a directory in oldpath or new
-path is not a directory. Or oldpath is a directory
-and newpath exists but is not a directory.
+A component used as a directory in @var{oldpath} or new
+path is not a directory. Or @var{oldpath} is a directory
+and @var{newpath} exists but is not a directory.
@item EFAULT
-oldpathptr or newpathptr are invalid pointer values.
+@var{oldpathptr} or @var{newpathptr} are invalid pointer values.
@item EACCES
No access to the file or the path of the file.
@item ENAMETOOLONG
-oldpath or newpath was too long.
+@var{oldpath} or @var{newpath} was too long.
@item ENOENT
-A directory component in oldpath or newpath does not exist.
+A directory component in @var{oldpath} or @var{newpath} does not exist.
@item EROFS
The file is on a read-only filesystem.
The call was interrupted by the user.
@end table
+@end table
+
@node unlink
@unnumberedsubsubsec unlink
@cindex unlink, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int unlink(const char *pathname);
+@end smallexample
-@exdent Request:
-Funlink,pathnameptr/len
+@item Request:
+@samp{Funlink,@var{pathnameptr}/@var{len}}
-@exdent Return value:
+@item Return value:
On success, zero is returned. On error, -1 is returned.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EACCES
The system does not allow unlinking of directories.
@item EBUSY
-The file pathname cannot be unlinked because it's
+The file @var{pathname} cannot be unlinked because it's
being used by another process.
@item EFAULT
-pathnameptr is an invalid pointer value.
+@var{pathnameptr} is an invalid pointer value.
@item ENAMETOOLONG
-pathname was too long.
+@var{pathname} was too long.
@item ENOENT
-A directory component in pathname does not exist.
+A directory component in @var{pathname} does not exist.
@item ENOTDIR
A component of the path is not a directory.
The call was interrupted by the user.
@end table
+@end table
+
@node stat/fstat
@unnumberedsubsubsec stat/fstat
@cindex fstat, file-i/o system call
@cindex stat, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int stat(const char *pathname, struct stat *buf);
int fstat(int fd, struct stat *buf);
+@end smallexample
-@exdent Request:
-Fstat,pathnameptr/len,bufptr
-Ffstat,fd,bufptr
+@item Request:
+@samp{Fstat,@var{pathnameptr}/@var{len},@var{bufptr}}@*
+@samp{Ffstat,@var{fd},@var{bufptr}}
-@exdent Return value:
+@item Return value:
On success, zero is returned. On error, -1 is returned.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EBADF
-fd is not a valid open file.
+@var{fd} is not a valid open file.
@item ENOENT
-A directory component in pathname does not exist or the
+A directory component in @var{pathname} does not exist or the
path is an empty string.
@item ENOTDIR
A component of the path is not a directory.
@item EFAULT
-pathnameptr is an invalid pointer value.
+@var{pathnameptr} is an invalid pointer value.
@item EACCES
No access to the file or the path of the file.
@item ENAMETOOLONG
-pathname was too long.
+@var{pathname} was too long.
@item EINTR
The call was interrupted by the user.
@end table
+@end table
+
@node gettimeofday
@unnumberedsubsubsec gettimeofday
@cindex gettimeofday, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int gettimeofday(struct timeval *tv, void *tz);
+@end smallexample
-@exdent Request:
-Fgettimeofday,tvptr,tzptr
+@item Request:
+@samp{Fgettimeofday,@var{tvptr},@var{tzptr}}
-@exdent Return value:
+@item Return value:
On success, 0 is returned, -1 otherwise.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EINVAL
-tz is a non-NULL pointer.
+@var{tz} is a non-NULL pointer.
@item EFAULT
-tvptr and/or tzptr is an invalid pointer value.
+@var{tvptr} and/or @var{tzptr} is an invalid pointer value.
+@end table
+
@end table
@node isatty
@unnumberedsubsubsec isatty
@cindex isatty, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int isatty(int fd);
+@end smallexample
-@exdent Request:
-Fisatty,fd
+@item Request:
+@samp{Fisatty,@var{fd}}
-@exdent Return value:
-Returns 1 if fd refers to the @value{GDBN} console, 0 otherwise.
+@item Return value:
+Returns 1 if @var{fd} refers to the @value{GDBN} console, 0 otherwise.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EINTR
The call was interrupted by the user.
@end table
+@end table
+
+Note that the @code{isatty} call is treated as a special case: it returns
+1 to the target if the file descriptor is attached
+to the @value{GDBN} console, 0 otherwise. Implementing through system calls
+would require implementing @code{ioctl} and would be more complex than
+needed.
+
+
@node system
@unnumberedsubsubsec system
@cindex system, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int system(const char *command);
+@end smallexample
-@exdent Request:
-Fsystem,commandptr/len
+@item Request:
+@samp{Fsystem,@var{commandptr}/@var{len}}
-@exdent Return value:
-The value returned is -1 on error and the return status
-of the command otherwise. Only the exit status of the
-command is returned, which is extracted from the hosts
-system return value by calling WEXITSTATUS(retval).
-In case /bin/sh could not be executed, 127 is returned.
+@item Return value:
+If @var{len} is zero, the return value indicates whether a shell is
+available. A zero return value indicates a shell is not available.
+For non-zero @var{len}, the value returned is -1 on error and the
+return status of the command otherwise. Only the exit status of the
+command is returned, which is extracted from the host's @code{system}
+return value by calling @code{WEXITSTATUS(retval)}. In case
+@file{/bin/sh} could not be executed, 127 is returned.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EINTR
The call was interrupted by the user.
@end table
+@end table
+
+@value{GDBN} takes over the full task of calling the necessary host calls
+to perform the @code{system} call. The return value of @code{system} on
+the host is simplified before it's returned
+to the target. Any termination signal information from the child process
+is discarded, and the return value consists
+entirely of the exit status of the called command.
+
+Due to security concerns, the @code{system} call is by default refused
+by @value{GDBN}. The user has to allow this call explicitly with the
+@code{set remote system-call-allowed 1} command.
+
+@table @code
+@item set remote system-call-allowed
+@kindex set remote system-call-allowed
+Control whether to allow the @code{system} calls in the File I/O
+protocol for the remote target. The default is zero (disabled).
+
+@item show remote system-call-allowed
+@kindex show remote system-call-allowed
+Show whether the @code{system} calls are allowed in the File I/O
+protocol.
+@end table
+
@node Protocol specific representation of datatypes
@subsection Protocol specific representation of datatypes
@cindex protocol specific representation of datatypes, in file-i/o protocol
@menu
* Integral datatypes::
* Pointer values::
+* Memory transfer::
* struct stat::
* struct timeval::
@end menu
@unnumberedsubsubsec Integral datatypes
@cindex integral datatypes, in file-i/o protocol
-The integral datatypes used in the system calls are
-
-@smallexample
-int@r{,} unsigned int@r{,} long@r{,} unsigned long@r{,} mode_t @r{and} time_t
-@end smallexample
+The integral datatypes used in the system calls are @code{int},
+@code{unsigned int}, @code{long}, @code{unsigned long},
+@code{mode_t}, and @code{time_t}.
-@code{Int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are
+@code{int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are
implemented as 32 bit values in this protocol.
-@code{Long} and @code{unsigned long} are implemented as 64 bit types.
+@code{long} and @code{unsigned long} are implemented as 64 bit types.
@xref{Limits}, for corresponding MIN and MAX values (similar to those
in @file{limits.h}) to allow range checking on host and target.
@noindent
which is a pointer to data of length 18 bytes at position 0x1aaf.
The length is defined as the full string length in bytes, including
-the trailing null byte. Example:
+the trailing null byte. For example, the string @code{"hello world"}
+at address 0x123456 is transmitted as
@smallexample
-``hello, world'' at address 0x123456
+@code{123456/d}
@end smallexample
-@noindent
-is transmitted as
+@node Memory transfer
+@unnumberedsubsubsec Memory transfer
+@cindex memory transfer, in file-i/o protocol
+
+Structured data which is transferred using a memory read or write (for
+example, a @code{struct stat}) is expected to be in a protocol specific format
+with all scalar multibyte datatypes being big endian. Translation to
+this representation needs to be done both by the target before the @code{F}
+packet is sent, and by @value{GDBN} before
+it transfers memory to the target. Transferred pointers to structured
+data should point to the already-coerced data at any time.
-@smallexample
-@code{123456/d}
-@end smallexample
@node struct stat
@unnumberedsubsubsec struct stat
@cindex struct stat, in file-i/o protocol
-The buffer of type struct stat used by the target and @value{GDBN} is defined
-as follows:
+The buffer of type @code{struct stat} used by the target and @value{GDBN}
+is defined as follows:
@smallexample
struct stat @{
@};
@end smallexample
-The integral datatypes are conforming to the definitions given in the
-approriate section (see @ref{Integral datatypes}, for details) so this
+The integral datatypes conform to the definitions given in the
+appropriate section (see @ref{Integral datatypes}, for details) so this
structure is of size 64 bytes.
The values of several fields have a restricted meaning and/or
range of values.
-@smallexample
-st_dev: 0 file
- 1 console
-
-st_ino: No valid meaning for the target. Transmitted unchanged.
+@table @code
-st_mode: Valid mode bits are described in Appendix C. Any other
- bits have currently no meaning for the target.
+@item st_dev
+A value of 0 represents a file, 1 the console.
-st_uid: No valid meaning for the target. Transmitted unchanged.
+@item st_ino
+No valid meaning for the target. Transmitted unchanged.
-st_gid: No valid meaning for the target. Transmitted unchanged.
+@item st_mode
+Valid mode bits are described in @ref{Constants}. Any other
+bits have currently no meaning for the target.
-st_rdev: No valid meaning for the target. Transmitted unchanged.
+@item st_uid
+@itemx st_gid
+@itemx st_rdev
+No valid meaning for the target. Transmitted unchanged.
-st_atime, st_mtime, st_ctime:
- These values have a host and file system dependent
- accuracy. Especially on Windows hosts the file systems
- don't support exact timing values.
-@end smallexample
+@item st_atime
+@itemx st_mtime
+@itemx st_ctime
+These values have a host and file system dependent
+accuracy. Especially on Windows hosts, the file system may not
+support exact timing values.
+@end table
-The target gets a struct stat of the above representation and is
-responsible to coerce it to the target representation before
+The target gets a @code{struct stat} of the above representation and is
+responsible for coercing it to the target representation before
continuing.
-Note that due to size differences between the host and target
-representation of stat members, these members could eventually
+Note that due to size differences between the host, target, and protocol
+representations of @code{struct stat} members, these members could eventually
get truncated on the target.
@node struct timeval
@unnumberedsubsubsec struct timeval
@cindex struct timeval, in file-i/o protocol
-The buffer of type struct timeval used by the target and @value{GDBN}
+The buffer of type @code{struct timeval} used by the File-I/O protocol
is defined as follows:
@smallexample
@};
@end smallexample
-The integral datatypes are conforming to the definitions given in the
-approriate section (see @ref{Integral datatypes}, for details) so this
+The integral datatypes conform to the definitions given in the
+appropriate section (see @ref{Integral datatypes}, for details) so this
structure is of size 8 bytes.
@node Constants
@cindex constants, in file-i/o protocol
The following values are used for the constants inside of the
-protocol. @value{GDBN} and target are resposible to translate these
+protocol. @value{GDBN} and target are responsible for translating these
values before and after the call as needed.
@menu
EUNKNOWN 9999
@end smallexample
- EUNKNOWN is used as a fallback error value if a host system returns
+ @code{EUNKNOWN} is used as a fallback error value if a host system returns
any error value not in the list of supported error numbers.
@node Lseek flags
@end smallexample
Example sequence of a read call, call fails on the host due to invalid
-file descriptor (EBADF):
+file descriptor (@code{EBADF}):
@smallexample
<- @code{Fread,3,1234,6}
projects / deliverable / binutils-gdb.git / blobdiff