\input texinfo @c -*-texinfo-*-
-@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 1999, 2000, 2001, 2002, 2003, 2004, 2005
+@c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
+@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
@c Free Software Foundation, Inc.
@c
@c %**start of header
Version @value{GDBVN}.
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
- 1999, 2000, 2001, 2002, 2003, 2004, 2005@*
+ 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006@*
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
@vskip 0pt plus 1filll
Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
-1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005
+1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2006
Free Software Foundation, Inc.
@sp 2
Published by the Free Software Foundation @*
-59 Temple Place - Suite 330, @*
-Boston, MA 02111-1307 USA @*
+51 Franklin Street, Fifth Floor,
+Boston, MA 02110-1301, USA@*
ISBN 1-882114-77-9 @*
Permission is granted to copy, distribute and/or modify this document
This is the @value{EDITION} Edition, for @value{GDBN} Version
@value{GDBVN}.
-Copyright (C) 1988-2005 Free Software Foundation, Inc.
+Copyright (C) 1988-2006 Free Software Foundation, Inc.
@menu
* Summary:: Summary of @value{GDBN}
* Configurations:: Configuration-specific information
* Controlling GDB:: Controlling @value{GDBN}
* Sequences:: Canned sequences of commands
-* TUI:: @value{GDBN} Text User Interface
* Interpreters:: Command Interpreters
+* TUI:: @value{GDBN} Text User Interface
* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
-* Annotations:: @value{GDBN}'s annotation interface.
* GDB/MI:: @value{GDBN}'s Machine Interface.
+* Annotations:: @value{GDBN}'s annotation interface.
* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Formatting Documentation:: How to format and print @value{GDBN} documentation
* Command Line Editing:: Command Line Editing
* Using History Interactively:: Using History Interactively
+* Formatting Documentation:: How to format and print @value{GDBN} documentation
* Installing GDB:: Installing GDB
* Maintenance Commands:: Maintenance Commands
* Remote Protocol:: GDB Remote Serial Protocol
* Agent Expressions:: The GDB Agent Expression Mechanism
+* Target Descriptions:: How targets can describe themselves to
+ @value{GDBN}
* Copying:: GNU General Public License says
how you can copy and share GDB
* GNU Free Documentation License:: The license for this documentation
Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped
with the migration of old architectures to this new framework.
+Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s
+unwinder framework, this consisting of a fresh new design featuring
+frame IDs, independent frame sniffers, and the sentinel frame. Mark
+Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the
+libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and
+trad unwinders. The architecture specific changes, each involving a
+complete rewrite of the architecture's frame code, were carried out by
+Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane
+Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel
+Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei
+Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich
+Weigand.
+
+Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from
+Tensilica, Inc.@: contributed support for Xtensa processors. Others
+who have worked on the Xtensa port of @value{GDBN} in the past include
+Steve Tjiang, John Newlin, and Scott Foehner.
+
@node Sample Session
@chapter A Sample @value{GDBN} Session
@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
@b{baz}
-@b{C-d}
+@b{Ctrl-d}
m4: End of input: 0: fatal error: EOF in string
@end smallexample
lengths. We allow @code{m4} exit by giving it an EOF as input:
@smallexample
-@b{C-d}
+@b{Ctrl-d}
Program exited normally.
@end smallexample
@item
type @samp{@value{GDBP}} to start @value{GDBN}.
@item
-type @kbd{quit} or @kbd{C-d} to exit.
+type @kbd{quit} or @kbd{Ctrl-d} to exit.
@end itemize
@menu
When @value{GDBN} starts, it reads any arguments other than options as
specifying an executable file and core file (or process ID). This is
the same as if the arguments were specified by the @samp{-se} and
-@samp{-c} (or @samp{-p} options respectively. (@value{GDBN} reads the
+@samp{-c} (or @samp{-p}) options respectively. (@value{GDBN} reads the
first argument that does not have an associated option flag as
equivalent to the @samp{-se} option followed by that argument; and the
second argument that does not have an associated option flag, if any, as
first attempt to attach to it as a process, and if that fails, attempt
to open it as a corefile. If you have a corefile whose name begins with
a digit, you can prevent @value{GDBN} from treating it as a pid by
-prefixing it with @file{./}, eg. @file{./12345}.
+prefixing it with @file{./}, e.g.@: @file{./12345}.
If @value{GDBN} has not been configured to included core file support,
such as for most embedded targets, then it will complain about a second
@itemx -d @var{directory}
@cindex @code{--directory}
@cindex @code{-d}
-Add @var{directory} to the path to search for source files.
+Add @var{directory} to the path to search for source and script files.
@item -r
@itemx -readnow
@item quit @r{[}@var{expression}@r{]}
@itemx q
To exit @value{GDBN}, use the @code{quit} command (abbreviated
-@code{q}), or type an end-of-file character (usually @kbd{C-d}). If you
+@code{q}), or type an end-of-file character (usually @kbd{Ctrl-d}). If you
do not supply @var{expression}, @value{GDBN} will terminate normally;
otherwise it will terminate using the result of @var{expression} as the
error code.
@end table
@cindex interrupt
-An interrupt (often @kbd{C-c}) does not exit from @value{GDBN}, but rather
+An interrupt (often @kbd{Ctrl-c}) does not exit from @value{GDBN}, but rather
terminates the action of any @value{GDBN} command that is in progress and
returns to @value{GDBN} command level. It is safe to type the interrupt
character at any time because @value{GDBN} does not allow it to take effect
Files,,Command files}).
@cindex repeating command sequences
-@kindex C-o @r{(operate-and-get-next)}
-The @kbd{C-o} binding is useful for repeating a complex sequence of
-commands. This command accepts the current line, like @kbd{RET}, and
+@kindex Ctrl-o @r{(operate-and-get-next)}
+The @kbd{Ctrl-o} binding is useful for repeating a complex sequence of
+commands. This command accepts the current line, like @key{RET}, and
then fetches the next line relative to the current line from the history
for editing.
* Threads:: Debugging programs with multiple threads
* Processes:: Debugging programs with multiple processes
+* Checkpoint/Restart:: Setting a @emph{bookmark} to return to later
@end menu
@node Compilation
@kindex thread apply
@cindex apply command to several threads
-@item thread apply [@var{threadno}] [@var{all}] @var{args}
-The @code{thread apply} command allows you to apply a command to one or
-more threads. Specify the numbers of the threads that you want affected
-with the command argument @var{threadno}. @var{threadno} is the internal
-@value{GDBN} thread number, as shown in the first field of the @samp{info
-threads} display. To apply a command to all threads, use
-@code{thread apply all} @var{args}.
+@item thread apply [@var{threadno}] [@var{all}] @var{command}
+The @code{thread apply} command allows you to apply the named
+@var{command} to one or more threads. Specify the numbers of the
+threads that you want affected with the command argument
+@var{threadno}. It can be a single thread number, one of the numbers
+shown in the first field of the @samp{info threads} display; or it
+could be a range of thread numbers, as in @code{2-4}. To apply a
+command to all threads, type @kbd{thread apply all @var{command}}.
@end table
@cindex automatic thread selection
Display the current debugger response to a @code{fork} or @code{vfork} call.
@end table
+@cindex debugging multiple processes
+On Linux, if you want to debug both the parent and child processes, use the
+command @w{@code{set detach-on-fork}}.
+
+@table @code
+@kindex set detach-on-fork
+@item set detach-on-fork @var{mode}
+Tells gdb whether to detach one of the processes after a fork, or
+retain debugger control over them both.
+
+@table @code
+@item on
+The child process (or parent process, depending on the value of
+@code{follow-fork-mode}) will be detached and allowed to run
+independently. This is the default.
+
+@item off
+Both processes will be held under the control of @value{GDBN}.
+One process (child or parent, depending on the value of
+@code{follow-fork-mode}) is debugged as usual, while the other
+is held suspended.
+
+@end table
+
+@kindex show detach-on-follow
+@item show detach-on-follow
+Show whether detach-on-follow mode is on/off.
+@end table
+
+If you choose to set @var{detach-on-follow} mode off, then
+@value{GDBN} will retain control of all forked processes (including
+nested forks). You can list the forked processes under the control of
+@value{GDBN} by using the @w{@code{info forks}} command, and switch
+from one fork to another by using the @w{@code{fork}} command.
+
+@table @code
+@kindex info forks
+@item info forks
+Print a list of all forked processes under the control of @value{GDBN}.
+The listing will include a fork id, a process id, and the current
+position (program counter) of the process.
+
+
+@kindex fork @var{fork-id}
+@item fork @var{fork-id}
+Make fork number @var{fork-id} the current process. The argument
+@var{fork-id} is the internal fork number assigned by @value{GDBN},
+as shown in the first field of the @samp{info forks} display.
+
+@end table
+
+To quit debugging one of the forked processes, you can either detach
+from it by using the @w{@code{detach fork}} command (allowing it to
+run independently), or delete (and kill) it using the
+@w{@code{delete fork}} command.
+
+@table @code
+@kindex detach fork @var{fork-id}
+@item detach fork @var{fork-id}
+Detach from the process identified by @value{GDBN} fork number
+@var{fork-id}, and remove it from the fork list. The process will be
+allowed to run independently.
+
+@kindex delete fork @var{fork-id}
+@item delete fork @var{fork-id}
+Kill the process identified by @value{GDBN} fork number @var{fork-id},
+and remove it from the fork list.
+
+@end table
+
If you ask to debug a child process and a @code{vfork} is followed by an
@code{exec}, @value{GDBN} executes the new target up to the first
breakpoint in the new target. If you have a breakpoint set on
a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
Catchpoints, ,Setting catchpoints}.
+@node Checkpoint/Restart
+@section Setting a @emph{bookmark} to return to later
+
+@cindex checkpoint
+@cindex restart
+@cindex bookmark
+@cindex snapshot of a process
+@cindex rewind program state
+
+On certain operating systems@footnote{Currently, only
+@sc{gnu}/Linux.}, @value{GDBN} is able to save a @dfn{snapshot} of a
+program's state, called a @dfn{checkpoint}, and come back to it
+later.
+
+Returning to a checkpoint effectively undoes everything that has
+happened in the program since the @code{checkpoint} was saved. This
+includes changes in memory, registers, and even (within some limits)
+system state. Effectively, it is like going back in time to the
+moment when the checkpoint was saved.
+
+Thus, if you're stepping thru a program and you think you're
+getting close to the point where things go wrong, you can save
+a checkpoint. Then, if you accidentally go too far and miss
+the critical statement, instead of having to restart your program
+from the beginning, you can just go back to the checkpoint and
+start again from there.
+
+This can be especially useful if it takes a lot of time or
+steps to reach the point where you think the bug occurs.
+
+To use the @code{checkpoint}/@code{restart} method of debugging:
+
+@table @code
+@kindex checkpoint
+@item checkpoint
+Save a snapshot of the debugged program's current execution state.
+The @code{checkpoint} command takes no arguments, but each checkpoint
+is assigned a small integer id, similar to a breakpoint id.
+
+@kindex info checkpoints
+@item info checkpoints
+List the checkpoints that have been saved in the current debugging
+session. For each checkpoint, the following information will be
+listed:
+
+@table @code
+@item Checkpoint ID
+@item Process ID
+@item Code Address
+@item Source line, or label
+@end table
+
+@kindex restart @var{checkpoint-id}
+@item restart @var{checkpoint-id}
+Restore the program state that was saved as checkpoint number
+@var{checkpoint-id}. All program variables, registers, stack frames
+etc.@: will be returned to the values that they had when the checkpoint
+was saved. In essence, gdb will ``wind back the clock'' to the point
+in time when the checkpoint was saved.
+
+Note that breakpoints, @value{GDBN} variables, command history etc.
+are not affected by restoring a checkpoint. In general, a checkpoint
+only restores things that reside in the program being debugged, not in
+the debugger.
+
+@kindex delete checkpoint @var{checkpoint-id}
+@item delete checkpoint @var{checkpoint-id}
+Delete the previously-saved checkpoint identified by @var{checkpoint-id}.
+
+@end table
+
+Returning to a previously saved checkpoint will restore the user state
+of the program being debugged, plus a significant subset of the system
+(OS) state, including file pointers. It won't ``un-write'' data from
+a file, but it will rewind the file pointer to the previous location,
+so that the previously written data can be overwritten. For files
+opened in read mode, the pointer will also be restored so that the
+previously read data can be read again.
+
+Of course, characters that have been sent to a printer (or other
+external device) cannot be ``snatched back'', and characters received
+from eg.@: a serial device can be removed from internal program buffers,
+but they cannot be ``pushed back'' into the serial pipeline, ready to
+be received again. Similarly, the actual contents of files that have
+been changed cannot be restored (at this time).
+
+However, within those constraints, you actually can ``rewind'' your
+program to a previously saved point in time, and begin debugging it
+again --- and you can change the course of events so as to debug a
+different execution path this time.
+
+@cindex checkpoints and process id
+Finally, there is one bit of internal program state that will be
+different when you return to a checkpoint --- the program's process
+id. Each checkpoint will have a unique process id (or @var{pid}),
+and each will be different from the program's original @var{pid}.
+If your program has saved a local copy of its process id, this could
+potentially pose a problem.
+
+@subsection A non-obvious benefit of using checkpoints
+
+On some systems such as @sc{gnu}/Linux, address space randomization
+is performed on new processes for security reasons. This makes it
+difficult or impossible to set a breakpoint, or watchpoint, on an
+absolute address if you have to restart the program, since the
+absolute location of a symbol will change from one execution to the
+next.
+
+A checkpoint, however, is an @emph{identical} copy of a process.
+Therefore if you create a checkpoint at (eg.@:) the start of main,
+and simply return to that checkpoint instead of restarting the
+process, you can avoid the effects of address randomization and
+your symbols will all stay in the same place.
+
@node Stopping
@chapter Stopping and Continuing
call).
@cindex watchpoints
+@cindex data breakpoints
@cindex memory tracing
@cindex breakpoint on memory address
@cindex breakpoint on variable modification
A @dfn{watchpoint} is a special breakpoint that stops your program
-when the value of an expression changes. You must use a different
-command to set watchpoints (@pxref{Set Watchpoints, ,Setting
-watchpoints}), but aside from that, you can manage a watchpoint like
-any other breakpoint: you enable, disable, and delete both breakpoints
-and watchpoints using the same commands.
+when the value of an expression changes. The expression may be a value
+of a variable, or it could involve values of one or more variables
+combined by operators, such as @samp{a + b}. This is sometimes called
+@dfn{data breakpoints}. You must use a different command to set
+watchpoints (@pxref{Set Watchpoints, ,Setting watchpoints}), but aside
+from that, you can manage a watchpoint like any other breakpoint: you
+enable, disable, and delete both breakpoints and watchpoints using the
+same commands.
You can arrange to have values from your program displayed automatically
whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,,
operate. A breakpoint range is either a single breakpoint number, like
@samp{5}, or two such numbers, in increasing order, separated by a
hyphen, like @samp{5-7}. When a breakpoint range is given to a command,
-all breakpoint in that range are operated on.
+all breakpoints in that range are operated on.
@menu
* Set Breaks:: Setting breakpoints
@itemx info break @r{[}@var{n}@r{]}
@itemx info watchpoints @r{[}@var{n}@r{]}
Print a table of all breakpoints, watchpoints, and catchpoints set and
-not deleted, with the following columns for each breakpoint:
+not deleted. Optional argument @var{n} means print information only
+about the specified breakpoint (or watchpoint or catchpoint). For
+each breakpoint, following columns are printed:
@table @emph
@item Breakpoint Numbers
occurred since the time the breakpoint was disabled and one or more
of these loads could resolve the location.
+@cindex automatic hardware breakpoints
+For some targets, @value{GDBN} can automatically decide if hardware or
+software breakpoints should be used, depending on whether the
+breakpoint address is read-only or read-write. This applies to
+breakpoints set with the @code{break} command as well as to internal
+breakpoints set by commands like @code{next} and @code{finish}. For
+breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
+breakpoints.
+
+You can control this automatic behaviour with the following commands::
+
+@kindex set breakpoint auto-hw
+@kindex show breakpoint auto-hw
+@table @code
+@item set breakpoint auto-hw on
+This is the default behavior. When @value{GDBN} sets a breakpoint, it
+will try to use the target memory map to decide if software or hardware
+breakpoint must be used.
+
+@item set breakpoint auto-hw off
+This indicates @value{GDBN} should not automatically select breakpoint
+type. If the target provides a memory map, @value{GDBN} will warn when
+trying to set software breakpoint at a read-only address.
+@end table
+
+
@cindex negative breakpoint numbers
@cindex internal @value{GDBN} breakpoints
@value{GDBN} itself sometimes sets breakpoints in your program for
@cindex setting watchpoints
You can use a watchpoint to stop execution whenever the value of an
expression changes, without having to predict a particular place where
-this may happen.
+this may happen. (This is sometimes called a @dfn{data breakpoint}.)
+The expression may be as simple as the value of a single variable, or
+as complex as many variables combined by operators. Examples include:
+
+@itemize @bullet
+@item
+A reference to the value of a single variable.
+
+@item
+An address cast to an appropriate data type. For example,
+@samp{*(int *)0x12345678} will watch a 4-byte region at the specified
+address (assuming an @code{int} occupies 4 bytes).
+
+@item
+An arbitrarily complex expression, such as @samp{a*b + c/d}. The
+expression can use any operators valid in the program's native
+language (@pxref{Languages}).
+@end itemize
@cindex software watchpoints
@cindex hardware watchpoints
@table @code
@kindex watch
@item watch @var{expr}
-Set a watchpoint for an expression. @value{GDBN} will break when @var{expr}
-is written into by the program and its value changes.
+Set a watchpoint for an expression. @value{GDBN} will break when the
+expression @var{expr} is written into by the program and its value
+changes. The simplest (and the most popular) use of this command is
+to watch the value of a single variable:
+
+@smallexample
+(@value{GDBP}) watch foo
+@end smallexample
@kindex rwatch
@item rwatch @var{expr}
Set a watchpoint that will break when @var{expr} is either read from
or written into by the program.
-@kindex info watchpoints
+@kindex info watchpoints @r{[}@var{n}@r{]}
@item info watchpoints
This command prints a list of watchpoints, breakpoints, and catchpoints;
it is the same as @code{info break} (@pxref{Set Breaks}).
the underlying system supports them. (Note that hardware-assisted
watchpoints that were set @emph{before} setting
@code{can-use-hw-watchpoints} to zero will still use the hardware
-mechanism of watching expressiion values.)
+mechanism of watching expression values.)
@table @code
@item set can-use-hw-watchpoints
@noindent
If this happens, delete or disable some of the watchpoints.
+Watching complex expressions that reference many variables can also
+exhaust the resources available for hardware-assisted watchpoints.
+That's because @value{GDBN} needs to watch every variable in the
+expression with separately allocated resources.
+
The SPARClite DSU will generate traps when a program accesses some data
or instruction address that is assigned to the debug registers. For the
data addresses, DSU facilitates the @code{watch} command. However the
@item catch
The catching of a C@t{++} exception.
+@item exception
+@cindex Ada exception catching
+@cindex catch Ada exceptions
+An Ada exception being raised. If an exception name is specified
+at the end of the command (eg @code{catch exception Program_Error}),
+the debugger will stop only when this specific exception is raised.
+Otherwise, the debugger stops execution when any Ada exception is raised.
+
+@item exception unhandled
+An exception that was raised but is not handled by the program.
+
+@item assert
+A failed Ada assertion.
+
@item exec
@cindex break on fork/exec
A call to @code{exec}. This is currently only available for HP-UX.
@table @code
@kindex commands
-@kindex end
+@kindex end@r{ (breakpoint commands)}
@item commands @r{[}@var{bnum}@r{]}
@itemx @dots{} @var{command-list} @dots{}
@itemx end
A signal is an asynchronous event that can happen in a program. The
operating system defines the possible kinds of signals, and gives each
kind a name and a number. For example, in Unix @code{SIGINT} is the
-signal a program gets when you type an interrupt character (often @kbd{C-c});
+signal a program gets when you type an interrupt character (often @kbd{Ctrl-c});
@code{SIGSEGV} is the signal a program gets from referencing a place in
memory far away from all the areas in use; @code{SIGALRM} occurs when
the alarm clock timer goes off (which happens only if your program has
handle each one. You can use this to see the signal numbers of all
the defined types of signals.
+@item info signals @var{sig}
+Similar, but print information only about the specified signal number.
+
@code{info handle} is an alias for @code{info signals}.
@kindex handle
-@item handle @var{signal} @var{keywords}@dots{}
+@item handle @var{signal} @r{[}@var{keywords}@dots{}@r{]}
Change the way @value{GDBN} handles signal @var{signal}. @var{signal}
can be the number of a signal or its name (with or without the
@samp{SIG} at the beginning); a list of signal numbers of the form
@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the
-known signals. The @var{keywords} say what change to make.
+known signals. Optional arguments @var{keywords}, described below,
+say what change to make.
@end table
@c @group
@c underflow problems.
@cindex frameless execution
Some compilers provide a way to compile functions so that they operate
-without stack frames. (For example, the @value{GCC} option
+without stack frames. (For example, the @value{NGCC} option
@smallexample
@samp{-fomit-frame-pointer}
@end smallexample
frames in the stack.
You can stop the backtrace at any time by typing the system interrupt
-character, normally @kbd{C-c}.
+character, normally @kbd{Ctrl-c}.
@item backtrace @var{n}
@itemx bt @var{n}
Similar, but print only the outermost @var{n} frames.
@item backtrace full
-Print the values of the local variables also.
@itemx bt full
+@itemx bt full @var{n}
+@itemx bt full -@var{n}
+Print the values of the local variables also. @var{n} specifies the
+number of frames to print, as described above.
@end table
@kindex where
The names @code{where} and @code{info stack} (abbreviated @code{info s})
are additional aliases for @code{backtrace}.
+@cindex multiple threads, backtrace
+In a multi-threaded program, @value{GDBN} by default shows the
+backtrace only for the current thread. To display the backtrace for
+several or all of the threads, use the command @code{thread apply}
+(@pxref{Threads, thread apply}). For example, if you type @kbd{thread
+apply all backtrace}, @value{GDBN} will display the backtrace for all
+the threads; this is handy when you debug a core dump of a
+multi-threaded program.
+
Each line in the backtrace shows the frame number and the function name.
The program counter value is also shown---unless you use @code{set
print address off}. The backtrace also shows the source file name and
and is likely before the user entry point @code{main} (or equivalent) is called.
@item set backtrace past-entry off
-Backtraces will stop when they encouter the internal entry point of an
+Backtraces will stop when they encounter the internal entry point of an
application. This is the default.
@item show backtrace past-entry
that---@file{/mnt/cross/foo.c}.
Note that the executable search path is @emph{not} used to locate the
-source files. Neither is the current working directory, unless it
-happens to be in the source path.
+source files.
Whenever you reset or rearrange the source path, @value{GDBN} clears out
any information it has cached about where source files are found and where
and @samp{cwd}, in that order.
To add other directories, use the @code{directory} command.
+The search path is used to find both program source files and @value{GDBN}
+script files (read using the @samp{-command} option and @samp{source} command).
+
+In addition to the source path, @value{GDBN} provides a set of commands
+that manage a list of source path substitution rules. A @dfn{substitution
+rule} specifies how to rewrite source directories stored in the program's
+debug information in case the sources were moved to a different
+directory between compilation and debugging. A rule is made of
+two strings, the first specifying what needs to be rewritten in
+the path, and the second specifying how it should be rewritten.
+In @ref{set substitute-path}, we name these two parts @var{from} and
+@var{to} respectively. @value{GDBN} does a simple string replacement
+of @var{from} with @var{to} at the start of the directory part of the
+source file name, and uses that result instead of the original file
+name to look up the sources.
+
+Using the previous example, suppose the @file{foo-1.0} tree has been
+moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell
+GDB to replace @file{/usr/src} in all source path names with
+@file{/mnt/cross}. The first lookup will then be
+@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location
+of @file{/usr/src/foo-1.0/lib/foo.c}. To define a source path
+substitution rule, use the @code{set substitute-path} command
+(@pxref{set substitute-path}).
+
+To avoid unexpected substitution results, a rule is applied only if the
+@var{from} part of the directory name ends at a directory separator.
+For instance, a rule substituting @file{/usr/source} into
+@file{/mnt/cross} will be applied to @file{/usr/source/foo-1.0} but
+not to @file{/usr/sourceware/foo-2.0}. And because the substitution
+is applied only at the beginning of the directory name, this rule will
+not be applied to @file{/root/usr/source/baz.c} either.
+
+In many cases, you can achieve the same result using the @code{directory}
+command. However, @code{set substitute-path} can be more efficient in
+the case where the sources are organized in a complex tree with multiple
+subdirectories. With the @code{directory} command, you need to add each
+subdirectory of your project. If you moved the entire tree while
+preserving its internal organization, then @code{set substitute-path}
+allows you to direct the debugger to all the sources with one single
+command.
+
+@code{set substitute-path} is also more than just a shortcut command.
+The source path is only used if the file at the original location no
+longer exists. On the other hand, @code{set substitute-path} modifies
+the debugger behavior to look at the rewritten location instead. So, if
+for any reason a source file that is not relevant to your executable is
+located at the original location, a substitution rule is the only
+method available to point GDB at the new location.
+
@table @code
@item directory @var{dirname} @dots{}
@item dir @var{dirname} @dots{}
@kindex cdir
@kindex cwd
@vindex $cdir@r{, convenience variable}
-@vindex $cwdr@r{, convenience variable}
+@vindex $cwd@r{, convenience variable}
@cindex compilation directory
@cindex current directory
@cindex working directory
directory at the time you add an entry to the source path.
@item directory
-Reset the source path to empty again. This requires confirmation.
+Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation.
@c RET-repeat for @code{directory} is explicitly disabled, but since
@c repeating it would be a no-op we do not say that. (thanks to RMS)
@item show directories
@kindex show directories
Print the source path: show which directories it contains.
+
+@anchor{set substitute-path}
+@item set substitute-path @var{from} @var{to}
+@kindex set substitute-path
+Define a source path substitution rule, and add it at the end of the
+current list of existing substitution rules. If a rule with the same
+@var{from} was already defined, then the old rule is also deleted.
+
+For example, if the file @file{/foo/bar/baz.c} was moved to
+@file{/mnt/cross/baz.c}, then the command
+
+@smallexample
+(@value{GDBP}) set substitute-path /usr/src /mnt/cross
+@end smallexample
+
+@noindent
+will tell @value{GDBN} to replace @samp{/usr/src} with
+@samp{/mnt/cross}, which will allow @value{GDBN} to find the file
+@file{baz.c} even though it was moved.
+
+In the case when more than one substitution rule have been defined,
+the rules are evaluated one by one in the order where they have been
+defined. The first one matching, if any, is selected to perform
+the substitution.
+
+For instance, if we had entered the following commands:
+
+@smallexample
+(@value{GDBP}) set substitute-path /usr/src/include /mnt/include
+(@value{GDBP}) set substitute-path /usr/src /mnt/src
+@end smallexample
+
+@noindent
+@value{GDBN} would then rewrite @file{/usr/src/include/defs.h} into
+@file{/mnt/include/defs.h} by using the first rule. However, it would
+use the second rule to rewrite @file{/usr/src/lib/foo.c} into
+@file{/mnt/src/lib/foo.c}.
+
+
+@item unset substitute-path [path]
+@kindex unset substitute-path
+If a path is specified, search the current list of substitution rules
+for a rule that would rewrite that path. Delete that rule if found.
+A warning is emitted by the debugger if no rule could be found.
+
+If no path is specified, then all substitution rules are deleted.
+
+@item show substitute-path [path]
+@kindex show substitute-path
+If a path is specified, then print the source path substitution rule
+which would rewrite that path, if any.
+
+If no path is specified, then print all existing source path substitution
+rules.
+
@end table
If your source path is cluttered with directories that are no longer of
@enumerate
@item
-Use @code{directory} with no argument to reset the source path to empty.
+Use @code{directory} with no argument to reset the source path to its default value.
@item
Use @code{directory} with suitable arguments to reinstall the
produces debug info in a format that is superior to formats such as
COFF. You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also
an effective form for debug info. @xref{Debugging Options,,Options
-for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}.
-@xref{C, , Debugging C++}, for more info about debug info formats
+for Debugging Your Program or GCC, gcc.info, Using the @sc{gnu}
+Compiler Collection (GCC)}.
+@xref{C, , Debugging C++}, for more information about debug info formats
that are best suited to C@t{++} programs.
If you ask to print an object whose contents are unknown to
by the debug information, @value{GDBN} will say @samp{<incomplete
type>}. @xref{Symbols, incomplete type}, for more about this.
+Strings are identified as arrays of @code{char} values without specified
+signedness. Arrays of either @code{signed char} or @code{unsigned char} get
+printed as arrays of 1 byte sized integers. @code{-fsigned-char} or
+@code{-funsigned-char} @value{NGCC} options have no effect as @value{GDBN}
+defines literal string type @code{"char"} as @code{char} without a sign.
+For program code
+
+@smallexample
+char var0[] = "A";
+signed char var1[] = "A";
+@end smallexample
+
+You get during debugging
+@smallexample
+(gdb) print var0
+$1 = "A"
+(gdb) print var1
+$2 = @{65 'A', 0 '\0'@}
+@end smallexample
+
@node Arrays
@section Artificial arrays
@item set print repeats
@cindex repeated array elements
Set the threshold for suppressing display of repeated array
-elelments. When the number of consecutive identical elements of an
+elements. When the number of consecutive identical elements of an
array exceeds the threshold, @value{GDBN} prints the string
@code{"<repeats @var{n} times>"}, where @var{n} is the number of
identical repetitions, instead of displaying the identical elements
@item set print pascal_static-members
@itemx set print pascal_static-members on
-@cindex static members of Pacal objects
-@cindex Pacal objects, static members display
+@cindex static members of Pascal objects
+@cindex Pascal objects, static members display
Print static members when displaying a Pascal object. The default is on.
@item set print pascal_static-members off
@item show convenience
Print a list of convenience variables used so far, and their values.
Abbreviated @code{show conv}.
+
+@kindex init-if-undefined
+@cindex convenience variables, initializing
+@item init-if-undefined $@var{variable} = @var{expression}
+Set a convenience variable if it has not already been set. This is useful
+for user-defined commands that keep some state. It is similar, in concept,
+to using local static variables with initializers in C (except that
+convenience variables are global). It can also be used to allow users to
+override default values used in a command script.
+
+If the variable is already defined then the expression is not evaluated so
+any side-effects do not occur.
@end table
One of the ways to use a convenience variable is as a counter to be
that makes sense for your program), but the @code{info registers} command
prints the data in both formats.
+@cindex SSE registers (x86)
+@cindex MMX registers (x86)
+Some machines have special registers whose contents can be interpreted
+in several different ways. For example, modern x86-based machines
+have SSE and MMX registers that can hold several values packed
+together in several different formats. @value{GDBN} refers to such
+registers in @code{struct} notation:
+
+@smallexample
+(@value{GDBP}) print $xmm1
+$1 = @{
+ v4_float = @{0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044@},
+ v2_double = @{9.92129282474342e-303, 2.7585945287983262e-313@},
+ v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000",
+ v8_int16 = @{0, 0, 14072, 315, 11, 0, 13, 0@},
+ v4_int32 = @{0, 20657912, 11, 13@},
+ v2_int64 = @{88725056443645952, 55834574859@},
+ uint128 = 0x0000000d0000000b013b36f800000000
+@}
+@end smallexample
+
+@noindent
+To set values of such registers, you need to tell @value{GDBN} which
+view of the register you wish to change, as if you were assigning
+value to a @code{struct} member:
+
+@smallexample
+ (@value{GDBP}) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF
+@end smallexample
+
Normally, register values are relative to the selected stack frame
(@pxref{Selection, ,Selecting a frame}). This means that you get the
value that the register would contain if all stack frames farther in
Depending on the configuration and operating system facilities,
@value{GDBN} may be able to show you this information. For remote
targets, this functionality may further depend on the remote stub's
-support of the @samp{qPart:auxv:read} packet, see @ref{Remote
-configuration, auxiliary vector}.
+support of the @samp{qXfer:auxv:read} packet, see
+@ref{qXfer auxiliary vector read}.
@table @code
@kindex info auxv
@cindex memory region attributes
@dfn{Memory region attributes} allow you to describe special handling
-required by regions of your target's memory. @value{GDBN} uses attributes
-to determine whether to allow certain types of memory accesses; whether to
-use specific width accesses; and whether to cache target memory.
+required by regions of your target's memory. @value{GDBN} uses
+attributes to determine whether to allow certain types of memory
+accesses; whether to use specific width accesses; and whether to cache
+target memory. By default the description of memory regions is
+fetched from the target (if the current target supports this), but the
+user can override the fetched regions.
Defined memory regions can be individually enabled and disabled. When a
memory region is disabled, @value{GDBN} uses the default attributes when
Define a memory region bounded by @var{lower} and @var{upper} with
attributes @var{attributes}@dots{}, and add it to the list of regions
monitored by @value{GDBN}. Note that @var{upper} == 0 is a special
-case: it is treated as the the target's maximum memory address.
+case: it is treated as the target's maximum memory address.
(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.)
+@item mem auto
+Discard any user changes to the memory regions and use target-supplied
+regions, if available, or no regions if the target does not support.
+
@kindex delete mem
@item delete mem @var{nums}@dots{}
Remove memory regions @var{nums}@dots{} from the list of regions
While these attributes prevent @value{GDBN} from performing invalid
memory accesses, they do nothing to prevent the target system, I/O DMA,
-etc. from accessing memory.
+etc.@: from accessing memory.
@table @code
@item ro
@end table
@subsubsection Memory Access Size
-The acccess size attributes tells @value{GDBN} to use specific sized
+The access size attribute tells @value{GDBN} to use specific sized
accesses in the memory region. Often memory mapped device registers
require specific sized accesses. If no access size attribute is
specified, @value{GDBN} may use accesses of any size.
Disable @value{GDBN} from caching target memory. This is the default.
@end table
+@subsection Memory Access Checking
+@value{GDBN} can be instructed to refuse accesses to memory that is
+not explicitly described. This can be useful if accessing such
+regions has undesired effects for a specific target, or to provide
+better error checking. The following commands control this behaviour.
+
+@table @code
+@kindex set mem inaccessible-by-default
+@item set mem inaccessible-by-default [on|off]
+If @code{on} is specified, make @value{GDBN} treat memory not
+explicitly described by the memory ranges as non-existent and refuse accesses
+to such memory. The checks are only performed if there's at least one
+memory range defined. If @code{off} is specified, make @value{GDBN}
+treat the memory not explicitly described by the memory ranges as RAM.
+The default value is @code{off}.
+@kindex show mem inaccessible-by-default
+@item show mem inaccessible-by-default
+Show the current handling of accesses to unknown memory.
+@end table
+
+
@c @subsubsection Memory Write Verification
@c The memory write verification attributes set whether @value{GDBN}
@c will re-reads data after each write to verify the write was successful.
unobtrusively, hopefully not disturbing the program's behavior.
The tracepoint facility is currently available only for remote
-targets. @xref{Targets}. In addition, your remote target must know how
-to collect trace data. This functionality is implemented in the remote
-stub; however, none of the stubs distributed with @value{GDBN} support
-tracepoints as of this writing.
+targets. @xref{Targets}. In addition, your remote target must know
+how to collect trace data. This functionality is implemented in the
+remote stub; however, none of the stubs distributed with @value{GDBN}
+support tracepoints as of this writing. The format of the remote
+packets used to implement tracepoints are described in @ref{Tracepoint
+Packets}.
This chapter describes the tracepoint commands and features.
format; if it doesn't work on your system, try the stabs+ debugging
format. You can select those formats explicitly with the @code{g++}
command-line options @option{-gdwarf-2} and @option{-gstabs+}.
-@xref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
-CC, gcc.info, Using @sc{gnu} CC}.
+@xref{Debugging Options,,Options for Debugging Your Program or GCC,
+gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}.
@menu
* C Operators:: C and C@t{++} operators
attempts to invoke the redefined version instead of using the operator's
predefined meaning.
-@menu
-* C Constants::
-@end menu
-
@node C Constants
@subsubsection C and C@t{++} constants
and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
@end itemize
-@menu
-* C plus plus expressions::
-* C Defaults::
-* C Checks::
-
-* Debugging C::
-@end menu
-
@node C plus plus expressions
@subsubsection C@t{++} expressions
with pointers and a memory allocation function. @xref{Expressions,
,Expressions}.
-@menu
-* Debugging C plus plus::
-@end menu
-
@node Debugging C plus plus
@subsubsection @value{GDBN} features for C@t{++}
* The Print Command with Objective-C::
@end menu
-@node Method Names in Commands, The Print Command with Objective-C, Objective-C, Objective-C
+@node Method Names in Commands
@subsubsection Method Names in Commands
The following commands have been extended to accept Objective-C method
@item info common @r{[}@var{common-name}@r{]}
This command prints the values contained in the Fortran @code{COMMON}
block whose name is @var{common-name}. With no argument, the names of
-all @code{COMMON} blocks visible at current program location are
+all @code{COMMON} blocks visible at the current program location are
printed.
@end table
* 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
are not implemented.
@item
-There are no record or array aggregates.
+@cindex array aggregates (Ada)
+@cindex record aggregates (Ada)
+@cindex aggregates (Ada)
+There is limited support for array and record aggregates. They are
+permitted only on the right sides of assignments, as in these examples:
+
+@smallexample
+set An_Array := (1, 2, 3, 4, 5, 6)
+set An_Array := (1, others => 0)
+set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)
+set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))
+set A_Record := (1, "Peter", True);
+set A_Record := (Name => "Peter", Id => 1, Alive => True)
+@end smallexample
+
+Changing a
+discriminant's value by assigning an aggregate has an
+undefined effect if that discriminant is used within the record.
+However, you can first modify discriminants by directly assigning to
+them (which normally would not be allowed in Ada), and then performing an
+aggregate assignment. For example, given a variable @code{A_Rec}
+declared to have a type such as:
+
+@smallexample
+type Rec (Len : Small_Integer := 0) is record
+ Id : Integer;
+ Vals : IntArray (1 .. Len);
+end record;
+@end smallexample
+
+you can assign a value with a different size of @code{Vals} with two
+assignments:
+
+@smallexample
+set A_Rec.Len := 4
+set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))
+@end smallexample
+
+As this example also illustrates, @value{GDBN} is very loose about the usual
+rules concerning aggregates. You may leave out some of the
+components of an array or record aggregate (such as the @code{Len}
+component in the assignment to @code{A_Rec} above); they will retain their
+original values upon assignment. You may freely use dynamic values as
+indices in component associations. You may even use overlapping or
+redundant component associations, although which component values are
+assigned in such cases is not defined.
@item
Calls to dispatching subprograms are not implemented.
it to find out the name of a variable or a function given its address.
@kindex whatis
-@item whatis @var{expr}
-Print the data type of expression @var{expr}. @var{expr} is not
-actually evaluated, and any side-effecting operations (such as
-assignments or function calls) inside it do not take place.
+@item whatis [@var{arg}]
+Print the data type of @var{arg}, which can be either an expression or
+a data type. With no argument, print the data type of @code{$}, the
+last value in the value history. If @var{arg} is an expression, it is
+not actually evaluated, and any side-effecting operations (such as
+assignments or function calls) inside it do not take place. If
+@var{arg} is a type name, it may be the name of a type or typedef, or
+for C code it may have the form @samp{class @var{class-name}},
+@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
+@samp{enum @var{enum-tag}}.
@xref{Expressions, ,Expressions}.
-@item whatis
-Print the data type of @code{$}, the last value in the value history.
-
@kindex ptype
-@item ptype @var{typename}
-Print a description of data type @var{typename}. @var{typename} may be
-the name of a type, or for C code it may have the form @samp{class
-@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union
-@var{union-tag}} or @samp{enum @var{enum-tag}}.
-
-@item ptype @var{expr}
-@itemx ptype
-Print a description of the type of expression @var{expr}. @code{ptype}
-differs from @code{whatis} by printing a detailed description, instead
-of just the name of the type.
+@item ptype [@var{arg}]
+@code{ptype} accepts the same arguments as @code{whatis}, but prints a
+detailed description of the type, instead of just the name of the type.
+@xref{Expressions, ,Expressions}.
For example, for this variable declaration:
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
Thus, @samp{info fun step} finds all functions whose names
include @code{step}; @samp{info fun ^step} finds those whose names
start with @code{step}. If a function name contains characters
-that conflict with the regular expression language (eg.
+that conflict with the regular expression language (e.g.@:
@samp{operator*()}), they may be quoted with a backslash.
@kindex info variables
@cindex calling functions
@cindex inferior functions, calling
@item print @var{expr}
-Evaluate the expression @var{expr} and display the resuling value.
+Evaluate the expression @var{expr} and display the resulting value.
@var{expr} may include calls to functions in the program being
debugged.
Occasionally it is necessary to change to a different file during a
@value{GDBN} session. Or you may run @value{GDBN} and forget to
specify a file you want to use. Or you are debugging a remote target
-via @code{gdbserver} (@pxref{Server, file}). In these situations the
-@value{GDBN} commands to specify new files are useful.
+via @code{gdbserver} (@pxref{Server, file, Using the gdbserver
+program}). In these situations the @value{GDBN} commands to specify
+new files are useful.
@table @code
@cindex executable file
@code{symbol-file} with no argument clears out @value{GDBN} information on your
program's symbol table.
-The @code{symbol-file} command causes @value{GDBN} to forget the contents
-of its convenience variables, the value history, and all breakpoints and
-auto-display expressions. This is because they may contain pointers to
-the internal data recording symbols and data types, which are part of
-the old symbol table data being discarded inside @value{GDBN}.
+The @code{symbol-file} command causes @value{GDBN} to forget the contents of
+some breakpoints and auto-display expressions. This is because they may
+contain pointers to the internal data recording symbols and data types,
+which are part of the old symbol table data being discarded inside
+@value{GDBN}.
@code{symbol-file} does not repeat if you press @key{RET} again after
executing it once.
generated for that environment; you may use either a @sc{gnu} compiler, or
other compilers that adhere to the local conventions.
Best results are usually obtained from @sc{gnu} compilers; for example,
-using @code{@value{GCC}} you can generate debugging information for
+using @code{@value{NGCC}} you can generate debugging information for
optimized code.
For most kinds of object files, with the exception of old SVR3 systems
symbols from shared libraries. To that end, type @kbd{set
auto-solib-add off} before running the inferior, then load each
library whose debug symbols you do need with @kbd{sharedlibrary
-@var{regexp}}, where @var{regexp} is a regular expresion that matches
+@var{regexp}}, where @var{regexp} is a regular expression that matches
the libraries whose symbols you want to be loaded.
@kindex show auto-solib-add
@table @code
@cindex prefix for shared library file names
+@cindex system root, alternate
@kindex set solib-absolute-prefix
-@item set solib-absolute-prefix @var{path}
-If this variable is set, @var{path} will be used as a prefix for any
-absolute shared library paths; many runtime loaders store the absolute
-paths to the shared library in the target program's memory. If you use
-@samp{solib-absolute-prefix} to find shared libraries, they need to be laid
-out in the same way that they are on the target, with e.g.@: a
-@file{/usr/lib} hierarchy under @var{path}.
-
-@cindex default value of @samp{solib-absolute-prefix}
+@kindex set sysroot
+@item set sysroot @var{path}
+Use @var{path} as the system root for the program being debugged. Any
+absolute shared library paths will be prefixed with @var{path}; many
+runtime loaders store the absolute paths to the shared library in the
+target program's memory. If you use @code{set sysroot} to find shared
+libraries, they need to be laid out in the same way that they are on
+the target, with e.g.@: a @file{/lib} and @file{/usr/lib} hierarchy
+under @var{path}.
+
+The @code{set solib-absolute-prefix} command is an alias for @code{set
+sysroot}.
+
+@cindex default system root
@cindex @samp{--with-sysroot}
-You can set the default value of @samp{solib-absolute-prefix} by using the
-configure-time @samp{--with-sysroot} option.
-
-@kindex show solib-absolute-prefix
-@item show solib-absolute-prefix
+You can set the default system root by using the configure-time
+@samp{--with-sysroot} option. If the system root is inside
+@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or
+@samp{--exec-prefix}), then the default system root will be updated
+automatically if the installed @value{GDBN} is moved to a new
+location.
+
+@kindex show sysroot
+@item show sysroot
Display the current shared library prefix.
@kindex set solib-search-path
@item set solib-search-path @var{path}
-If this variable is set, @var{path} is a colon-separated list of directories
-to search for shared libraries. @samp{solib-search-path} is used after
-@samp{solib-absolute-prefix} fails to locate the library, or if the path to
-the library is relative instead of absolute. If you want to use
-@samp{solib-search-path} instead of @samp{solib-absolute-prefix}, be sure to
-set @samp{solib-absolute-prefix} to a nonexistant directory to prevent
-@value{GDBN} from finding your host's libraries.
+If this variable is set, @var{path} is a colon-separated list of
+directories to search for shared libraries. @samp{solib-search-path}
+is used after @samp{sysroot} fails to locate the library, or if the
+path to the library is relative instead of absolute. If you want to
+use @samp{solib-search-path} instead of @samp{sysroot}, be sure to set
+@samp{sysroot} to a nonexistent directory to prevent @value{GDBN} from
+finding your host's libraries. @samp{sysroot} is preferred; setting
+it to a nonexistent directory may interfere with automatic loading
+of shared library symbols.
@kindex show solib-search-path
@item show solib-search-path
* Target Commands:: Commands for managing targets
* Byte Order:: Choosing target byte order
* Remote:: Remote debugging
-* KOD:: Kernel Object Display
@end menu
A core dump file. @samp{target core @var{filename}} is the same as
@samp{core-file @var{filename}}.
-@item target remote @var{dev}
+@item target remote @var{medium}
@cindex remote target
-Remote serial target in GDB-specific protocol. The argument @var{dev}
-specifies what serial device to use for the connection (e.g.
-@file{/dev/ttya}). @xref{Remote, ,Remote debugging}. @code{target remote}
-supports the @code{load} command. This is only useful if you have
-some other way of getting the stub to the target system, and you can put
-it somewhere in memory where it won't get clobbered by the download.
+A remote system connected to @value{GDBN} via a serial line or network
+connection. This command tells @value{GDBN} to use its own remote
+protocol over @var{medium} for debugging. @xref{Remote Debugging}.
+
+For example, if you have a board connected to @file{/dev/ttya} on the
+machine running @value{GDBN}, you could say:
+
+@smallexample
+target remote /dev/ttya
+@end smallexample
+
+@code{target remote} supports the @code{load} command. This is only
+useful if you have some other way of getting the stub to the target
+system, and you can put it somewhere in memory where it won't get
+clobbered by the download.
@item target sim
@cindex built-in simulator target
Many remote targets require you to download the executable's code once
you've successfully established a connection. You may wish to control
-various aspects of this process, such as the size of the data chunks
-used by @value{GDBN} to download program parts to the remote target.
+various aspects of this process.
@table @code
-@kindex set download-write-size
-@item set download-write-size @var{size}
-Set the write size used when downloading a program. Only used when
-downloading a program onto a remote target. Specify zero or a
-negative value to disable blocked writes. The actual size of each
-transfer is also limited by the size of the target packet and the
-memory cache.
-
-@kindex show download-write-size
-@item show download-write-size
-@kindex show download-write-size
-Show the current value of the write size.
@item set hash
@kindex set hash@r{, for remote monitors}
specifies a fixed address.
@c FIXME! This would be a good place for an xref to the GNU linker doc.
+Depending on the remote side capabilities, @value{GDBN} may be able to
+load programs into flash memory.
+
@code{load} does not repeat if you press @key{RET} again after using it.
@end table
@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
@menu
* Connecting:: Connecting to a remote target
* Server:: Using the gdbserver program
-* NetWare:: Using the gdbserve.nlm program
* Remote configuration:: Remote configuration
* remote stub:: Implementing a remote stub
@end menu
@section Connecting to a remote target
On the @value{GDBN} host machine, you will need an unstripped copy of
-your program, since @value{GDBN} needs symobl and debugging information.
+your program, since @value{GDBN} needs symbol and debugging information.
Start up @value{GDBN} as usual, using the name of the local copy of your
program as the first argument.
+@cindex @code{target remote}
+@value{GDBN} can communicate with the target over a serial line, or
+over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In
+each case, @value{GDBN} uses the same protocol for debugging your
+program; only the medium carrying the debugging packets varies. The
+@code{target remote} command establishes a connection to the target.
+Its arguments indicate which medium to use:
+
+@table @code
+
+@item target remote @var{serial-device}
@cindex serial line, @code{target remote}
+Use @var{serial-device} to communicate with the target. For example,
+to use a serial line connected to the device named @file{/dev/ttyb}:
+
+@smallexample
+target remote /dev/ttyb
+@end smallexample
+
If you're using a serial line, you may want to give @value{GDBN} the
@w{@samp{--baud}} option, or use the @code{set remotebaud} command
(@pxref{Remote configuration, set remotebaud}) before the
@code{target} command.
-After that, use @code{target remote} to establish communications with
-the target machine. Its argument specifies how to communicate---either
-via a devicename attached to a direct serial line, or a TCP or UDP port
-(possibly to a terminal server which in turn has a serial line to the
-target). For example, to use a serial line connected to the device
-named @file{/dev/ttyb}:
-
-@smallexample
-target remote /dev/ttyb
-@end smallexample
+@item target remote @code{@var{host}:@var{port}}
+@itemx target remote @code{tcp:@var{host}:@var{port}}
+@cindex @acronym{TCP} port, @code{target remote}
+Debug using a @acronym{TCP} connection to @var{port} on @var{host}.
+The @var{host} may be either a host name or a numeric @acronym{IP}
+address; @var{port} must be a decimal number. The @var{host} could be
+the target machine itself, if it is directly connected to the net, or
+it might be a terminal server which in turn has a serial line to the
+target.
-@cindex TCP port, @code{target remote}
-To use a TCP connection, use an argument of the form
-@code{@var{host}:@var{port}} or @code{tcp:@var{host}:@var{port}}.
-For example, to connect to port 2828 on a
-terminal server named @code{manyfarms}:
+For example, to connect to port 2828 on a terminal server named
+@code{manyfarms}:
@smallexample
target remote manyfarms:2828
@end smallexample
-If your remote target is actually running on the same machine as
-your debugger session (e.g.@: a simulator of your target running on
-the same host), you can omit the hostname. For example, to connect
-to port 1234 on your local machine:
+If your remote target is actually running on the same machine as your
+debugger session (e.g.@: a simulator for your target running on the
+same host), you can omit the hostname. For example, to connect to
+port 1234 on your local machine:
@smallexample
target remote :1234
Note that the colon is still required here.
-@cindex UDP port, @code{target remote}
-To use a UDP connection, use an argument of the form
-@code{udp:@var{host}:@var{port}}. For example, to connect to UDP port 2828
-on a terminal server named @code{manyfarms}:
+@item target remote @code{udp:@var{host}:@var{port}}
+@cindex @acronym{UDP} port, @code{target remote}
+Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to
+connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}:
@smallexample
target remote udp:manyfarms:2828
@end smallexample
-When using a UDP connection for remote debugging, you should keep in mind
-that the `U' stands for ``Unreliable''. UDP can silently drop packets on
-busy or unreliable networks, which will cause havoc with your debugging
-session.
+When using a @acronym{UDP} connection for remote debugging, you should
+keep in mind that the `U' stands for ``Unreliable''. @acronym{UDP}
+can silently drop packets on busy or unreliable networks, which will
+cause havoc with your debugging session.
+
+@item target remote | @var{command}
+@cindex pipe, @code{target remote} to
+Run @var{command} in the background and communicate with it using a
+pipe. The @var{command} is a shell command, to be parsed and expanded
+by the system's command shell, @code{/bin/sh}; it should expect remote
+protocol packets on its standard input, and send replies on its
+standard output. You could use this to run a stand-alone simulator
+that speaks the remote debugging protocol, to make net connections
+using programs like @code{ssh}, or for other similar tricks.
+
+If @var{command} closes its standard output (perhaps by exiting),
+@value{GDBN} will try to send it a @code{SIGTERM} signal. (If the
+program has already exited, this will have no effect.)
+
+@end table
-Now you can use all the usual commands to examine and change data and to
-step and continue the remote program.
+Once the connection has been established, you can use all the usual
+commands to examine and change data and to step and continue the
+remote program.
@cindex interrupting remote programs
@cindex remote programs, interrupting
Whenever @value{GDBN} is waiting for the remote program, if you type the
-interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
+interrupt character (often @kbd{Ctrl-c}), @value{GDBN} attempts to stop the
program. This may or may not succeed, depending in part on the hardware
and the serial drivers the remote system uses. If you type the
interrupt character once again, @value{GDBN} displays this prompt:
another target.
@cindex send command to remote monitor
+@cindex extend @value{GDBN} for remote targets
+@cindex add new commands for external monitor
@kindex monitor
@item monitor @var{cmd}
-This command allows you to send commands directly to the remote
-monitor.
+This command allows you to send arbitrary commands directly to the
+remote monitor. Since @value{GDBN} doesn't care about the commands it
+sends like this, this command is the way to extend @value{GDBN}---you
+can add new commands that only the external monitor will understand
+and implement.
@end table
@node Server
@code{pidof} utility:
@smallexample
-target> gdbserver @var{comm} --attach `pidof @var{PROGRAM}`
+target> gdbserver @var{comm} --attach `pidof @var{program}`
@end smallexample
-In case more than one copy of @var{PROGRAM} is running, or @var{PROGRAM}
+In case more than one copy of @var{program} is running, or @var{program}
has multiple threads, most versions of @code{pidof} support the
@code{-s} option to only return the first process ID.
@item On the host machine,
-connect to your target (@pxref{Connecting,,Connecting to a remote target}).
+first make sure you have the necessary symbol files. Load symbols for
+your application using the @code{file} command before you connect. Use
+@code{set sysroot} to locate target libraries (unless your @value{GDBN}
+was compiled with the correct sysroot using @code{--with-system-root}).
+
+The symbol file and target libraries must exactly match the executable
+and libraries on the target, with one exception: the files on the host
+system should not be stripped, even if the files on the target system
+are. Mismatched or missing files will lead to confusing results
+during debugging. On @sc{gnu}/Linux targets, mismatched or missing
+files may also prevent @code{gdbserver} from debugging multi-threaded
+programs.
+
+Connect to your target (@pxref{Connecting,,Connecting to a remote target}).
For TCP connections, you must start up @code{gdbserver} prior to using
the @code{target remote} command. Otherwise you may get an error whose
text depends on the host system, but which usually looks something like
@samp{Connection refused}. You don't need to use the @code{load}
command in @value{GDBN} when using @code{gdbserver}, since the program is
-already on the target. However, if you want to load the symbols (as
-you normally would), do that with the @code{file} command, and issue
-it @emph{before} connecting to the server; otherwise, you will get an
-error message saying @code{"Program is already running"}, since the
-program is considered running after the connection.
+already on the target.
@end table
-@node NetWare
-@section Using the @code{gdbserve.nlm} program
+@subsection Monitor commands for @code{gdbserver}
+@cindex monitor commands, for @code{gdbserver}
-@kindex gdbserve.nlm
-@code{gdbserve.nlm} is a control program for NetWare systems, which
-allows you to connect your program with a remote @value{GDBN} via
-@code{target remote}.
+During a @value{GDBN} session using @code{gdbserver}, you can use the
+@code{monitor} command to send special requests to @code{gdbserver}.
+Here are the available commands; they are only of interest when
+debugging @value{GDBN} or @code{gdbserver}.
-@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
-using the standard @value{GDBN} remote serial protocol.
+@table @code
+@item monitor help
+List the available monitor commands.
-@table @emph
-@item On the target machine,
-you need to have a copy of the program you want to debug.
-@code{gdbserve.nlm} does not need your program's symbol table, so you
-can strip the program if necessary to save space. @value{GDBN} on the
-host system does all the symbol handling.
+@item monitor set debug 0
+@itemx monitor set debug 1
+Disable or enable general debugging messages.
-To use the server, you must tell it how to communicate with
-@value{GDBN}; the name of your program; and the arguments for your
-program. The syntax is:
-
-@smallexample
-load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
- [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
-@end smallexample
-
-@var{board} and @var{port} specify the serial line; @var{baud} specifies
-the baud rate used by the connection. @var{port} and @var{node} default
-to 0, @var{baud} defaults to 9600@dmn{bps}.
-
-For example, to debug Emacs with the argument @samp{foo.txt}and
-communicate with @value{GDBN} over serial port number 2 or board 1
-using a 19200@dmn{bps} connection:
-
-@smallexample
-load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
-@end smallexample
-
-@item
-On the @value{GDBN} host machine, connect to your target (@pxref{Connecting,,
-Connecting to a remote target}).
+@item monitor set remote-debug 0
+@itemx monitor set remote-debug 1
+Disable or enable specific debugging messages associated with the remote
+protocol (@pxref{Remote Protocol}).
@end table
@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 set remoteaddresssize @var{bits}
-@cindex adress size for remote targets
+@cindex address size for remote targets
@cindex bits in remote address
Set the maximum size of address in a memory packet to the specified
number of bits. @value{GDBN} will mask off the address bits above
@item set remotebreak
@cindex interrupt remote programs
@cindex BREAK signal instead of Ctrl-C
+@anchor{set remotebreak}
If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote
-when you press the @key{Ctrl-C} key to interrupt the program running
+when you type @kbd{Ctrl-c} to interrupt the program running
on the remote. If set to off, @value{GDBN} sends the @samp{Ctrl-C}
character instead. The default is off, since most remote systems
expect to see @samp{Ctrl-C} as the interrupt signal.
Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to
interrupt the remote program.
-@item set remotedebug
-@cindex debug remote protocol
-@cindex remote protocol debugging
-@cindex display remote packets
-Control the debugging of the remote protocol. When enabled, each
-packet sent to or received from the remote target is displayed. The
-defaults is off.
-
-@item show remotedebug
-Show the current setting of the remote protocol debugging.
-
@item set remotedevice @var{device}
@cindex serial port name
Set the name of the serial port through which to communicate to the
@itemx set remote hardware-breakpoint-limit @var{limit}
Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
watchpoints. A limit of -1, the default, is treated as unlimited.
+@end table
-@item set remote fetch-register-packet
-@itemx set remote set-register-packet
-@itemx set remote P-packet
-@itemx set remote p-packet
-@cindex P-packet
-@cindex fetch registers from remote targets
-@cindex set registers in remote targets
-Determine whether @value{GDBN} can set and fetch registers from the
-remote target using the @samp{P} packets. The default depends on the
-remote stub's support of the @samp{P} packets (@value{GDBN} queries
-the stub when this packet is first required).
-
-@item show remote fetch-register-packet
-@itemx show remote set-register-packet
-@itemx show remote P-packet
-@itemx show remote p-packet
-Show the current setting of using the @samp{P} packets for setting and
-fetching registers from the remote target.
-
-@cindex binary downloads
-@cindex X-packet
-@item set remote binary-download-packet
-@itemx set remote X-packet
-Determine whether @value{GDBN} sends downloads in binary mode using
-the @samp{X} packets. The default is on.
-
-@item show remote binary-download-packet
-@itemx show remote X-packet
-Show the current setting of using the @samp{X} packets for binary
-downloads.
-
-@item set remote read-aux-vector-packet
-@cindex auxiliary vector of remote target
-@cindex @code{auxv}, and remote targets
-Set the use of the remote protocol's @samp{qPart:auxv:read} (target
-auxiliary vector read) request. This request is used to fetch the
-remote target's @dfn{auxiliary vector}, see @ref{OS Information,
-Auxiliary Vector}. The default setting depends on the remote stub's
-support of this request (@value{GDBN} queries the stub when this
-request is first required). @xref{General Query Packets, qPart}, for
-more information about this request.
-
-@item show remote read-aux-vector-packet
-Show the current setting of use of the @samp{qPart:auxv:read} request.
-
-@item set remote symbol-lookup-packet
-@cindex remote symbol lookup request
-Set the use of the remote protocol's @samp{qSymbol} (target symbol
-lookup) request. This request is used to communicate symbol
-information to the remote target, e.g., whenever a new shared library
-is loaded by the remote (@pxref{Files, shared libraries}). The
-default setting depends on the remote stub's support of this request
-(@value{GDBN} queries the stub when this request is first required).
-@xref{General Query Packets, qSymbol}, for more information about this
-request.
+@cindex remote packets, enabling and disabling
+The @value{GDBN} remote protocol autodetects the packets supported by
+your debugging stub. If you need to override the autodetection, you
+can use these commands to enable or disable individual packets. Each
+packet can be set to @samp{on} (the remote target supports this
+packet), @samp{off} (the remote target does not support this packet),
+or @samp{auto} (detect remote target support for this packet). They
+all default to @samp{auto}. For more information about each packet,
+see @ref{Remote Protocol}.
-@item show remote symbol-lookup-packet
-Show the current setting of use of the @samp{qSymbol} request.
-
-@item set remote verbose-resume-packet
-@cindex resume remote target
-@cindex signal thread, and remote targets
-@cindex single-step thread, and remote targets
-@cindex thread-specific operations on remote targets
-Set the use of the remote protocol's @samp{vCont} (descriptive resume)
-request. This request is used to resume specific threads in the
-remote target, and to single-step or signal them. The default setting
-depends on the remote stub's support of this request (@value{GDBN}
-queries the stub when this request is first required). This setting
-affects debugging of multithreaded programs: if @samp{vCont} cannot be
-used, @value{GDBN} might be unable to single-step a specific thread,
-especially under @code{set scheduler-locking off}; it is also
-impossible to pause a specific thread. @xref{Packets, vCont}, for
-more details.
-
-@item show remote verbose-resume-packet
-Show the current setting of use of the @samp{vCont} request
-
-@item set remote software-breakpoint-packet
-@itemx set remote hardware-breakpoint-packet
-@itemx set remote write-watchpoint-packet
-@itemx set remote read-watchpoint-packet
-@itemx set remote access-watchpoint-packet
-@itemx set remote Z-packet
-@cindex Z-packet
-@cindex remote hardware breakpoints and watchpoints
-These commands enable or disable the use of @samp{Z} packets for
-setting breakpoints and watchpoints in the remote target. The default
-depends on the remote stub's support of the @samp{Z} packets
-(@value{GDBN} queries the stub when each packet is first required).
-The command @code{set remote Z-packet}, kept for back-compatibility,
-turns on or off all the features that require the use of @samp{Z}
-packets.
-
-@item show remote software-breakpoint-packet
-@itemx show remote hardware-breakpoint-packet
-@itemx show remote write-watchpoint-packet
-@itemx show remote read-watchpoint-packet
-@itemx show remote access-watchpoint-packet
-@itemx show remote Z-packet
-Show the current setting of @samp{Z} packets usage.
-
-@item set remote get-thread-local-storage-address
-@kindex set remote get-thread-local-storage-address
-@cindex thread local storage of remote targets
-This command enables or disables the use of the @samp{qGetTLSAddr}
-(Get Thread Local Storage Address) request packet. The default
-depends on whether the remote stub supports this request.
-@xref{General Query Packets, qGetTLSAddr}, for more details about this
-packet.
+During normal use, you should not have to use any of these commands.
+If you do, that may be a bug in your remote debugging stub, or a bug
+in @value{GDBN}. You may want to report the problem to the
+@value{GDBN} developers.
-@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.
-@end table
+The available settings are:
+
+@multitable @columnfractions 0.3 0.2 0.35
+@item Command Name
+@tab Remote Packet
+@tab Related Features
+
+@item @code{fetch-register-packet}
+@tab @code{p}
+@tab @code{info registers}
+
+@item @code{set-register-packet}
+@tab @code{P}
+@tab @code{set}
+
+@item @code{binary-download-packet}
+@tab @code{X}
+@tab @code{load}, @code{set}
+
+@item @code{read-aux-vector-packet}
+@tab @code{qXfer:auxv:read}
+@tab @code{info auxv}
+
+@item @code{symbol-lookup-packet}
+@tab @code{qSymbol}
+@tab Detecting multiple threads
+
+@item @code{verbose-resume-packet}
+@tab @code{vCont}
+@tab Stepping or resuming multiple threads
+
+@item @code{software-breakpoint-packet}
+@tab @code{Z0}
+@tab @code{break}
+
+@item @code{hardware-breakpoint-packet}
+@tab @code{Z1}
+@tab @code{hbreak}
+
+@item @code{write-watchpoint-packet}
+@tab @code{Z2}
+@tab @code{watch}
+
+@item @code{read-watchpoint-packet}
+@tab @code{Z3}
+@tab @code{rwatch}
+
+@item @code{access-watchpoint-packet}
+@tab @code{Z4}
+@tab @code{awatch}
+
+@item @code{get-thread-local-storage-address-packet}
+@tab @code{qGetTLSAddr}
+@tab Displaying @code{__thread} variables
+
+@item @code{supported-packets}
+@tab @code{qSupported}
+@tab Remote communications parameters
+
+@item @code{pass-signals-packet}
+@tab @code{QPassSignals}
+@tab @code{handle @var{signal}}
+
+@end multitable
@node remote stub
@section Implementing a remote stub
If you do not use the GNU C compiler, you may need other standard
library subroutines as well; this varies from one stub to another,
but in general the stubs are likely to use any of the common library
-subroutines which @code{@value{GCC}} generates as inline code.
+subroutines which @code{@value{NGCC}} generates as inline code.
@node Debug Session
It takes an optional argument that is evaluated to
a long value to give the information about this given selector.
Without argument, this command displays information
-about the the six segment registers.
+about the six segment registers.
@kindex info dll
@item info dll
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
This boolean value controls whether the debuggee should
start a new group or stay in the same group as the debugger.
This affects the way the Windows OS handles
-Ctrl-C.
+@samp{Ctrl-C}.
@kindex show new-group
@item show new-group
@kindex set debugevents
@item set debugevents
-This boolean value adds debug output concerning events seen by the debugger.
+This boolean value adds debug output concerning kernel events related
+to the debuggee seen by the debugger. This includes events that
+signal thread and process creation and exit, DLL loading and
+unloading, console interrupts, and debugging messages produced by the
+Windows @code{OutputDebugString} API call.
@kindex set debugexec
@item set debugexec
This boolean value adds debug output concerning execute events
-seen by the debugger.
+(such as resume thread) seen by the debugger.
@kindex set debugexceptions
@item set debugexceptions
-This boolean value adds debug ouptut concerning exception events
-seen by the debugger.
+This boolean value adds debug output concerning exceptions in the
+debuggee seen by the debugger.
@kindex set debugmemory
@item set debugmemory
-This boolean value adds debug ouptut concerning memory events
-seen by the debugger.
+This boolean value adds debug output concerning debuggee memory reads
+and writes by the debugger.
@kindex set shell
@item set shell
though the file name of the DLL is lower-case, or vice-versa. Since
symbols within @value{GDBN} are @emph{case-sensitive} this may cause
some confusion. If in doubt, try the @code{info functions} and
-@code{info variables} commands or even @code{maint print msymbols} (see
-@pxref{Symbols}). Here's an example:
+@code{info variables} commands or even @code{maint print msymbols}
+(@pxref{Symbols}). Here's an example:
@smallexample
(@value{GDBP}) info function CreateFileA
This command shows the state of current thread suspension.
@item set thread run
-This comamnd sets whether the current thread is allowed to run.
+This command sets whether the current thread is allowed to run.
@item show thread run
Show whether the current thread is allowed to run.
* MIPS Embedded:: MIPS Embedded
* OpenRISC 1000:: OpenRisc 1000
* PA:: HP PA Embedded
-* PowerPC: PowerPC
+* PowerPC:: PowerPC
* SH:: Renesas SH
* Sparclet:: Tsqware Sparclet
* Sparclite:: Fujitsu Sparclite
Use the @sc{reset} button on the development board
@itemize @bullet
@item
-to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
+to interrupt your program (don't use @kbd{Ctrl-c} on the DOS host---it has
no way to pass an interrupt signal to the development board); and
@item
@item set download-path @var{path}
@kindex set download-path
@cindex find downloadable @sc{srec} files (M32R)
-Set the default path for finding donwloadable @sc{srec} files.
+Set the default path for finding downloadable @sc{srec} files.
@item show download-path
@kindex show download-path
@table @code
@kindex hwatch
@item hwatch @var{conditional}
-Set hardware watchpoint on combination of Load/Store Effecive Address(es)
+Set hardware watchpoint on combination of Load/Store Effective Address(es)
or Data. For example:
@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
@end table
@cindex SDS protocol
-The following commands specifi to the SDS protocol are supported
+The following commands specific to the SDS protocol are supported
by@value{GDBN}:
@table @code
Connect the controlling terminal to the STDBUG command monitor. When
you are done interacting with STDBUG, typing either of two character
sequences gets you back to the @value{GDBN} command prompt:
-@kbd{@key{RET}~.} (Return, followed by tilde and period) or
-@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
+@kbd{@key{RET} ~ .} (Return, followed by tilde and period) or
+@kbd{@key{RET} ~ Ctrl-d} (Return, followed by tilde and control-D).
@end table
@node Z8000
@subsection HPPA
@cindex HPPA support
-When @value{GDBN} is debugging te HP PA architecture, it provides the
+When @value{GDBN} is debugging the HP PA architecture, it provides the
following special commands:
@table @code
@item set debug hppa
@kindex set debug hppa
-THis command determines whether HPPA architecture specific debugging
+This command determines whether HPPA architecture specific debugging
messages are to be displayed.
@item show debug hppa
@end table
+@cindex command tracing
+If you need to debug user-defined commands or sourced files you may find it
+useful to enable @dfn{command tracing}. In this mode each command will be
+printed as it is executed, prefixed with one or more @samp{+} symbols, the
+quantity denoting the call depth of each command.
+
+@table @code
+@kindex set trace-commands
+@cindex command scripts, debugging
+@item set trace-commands on
+Enable command tracing.
+@item set trace-commands off
+Disable command tracing.
+@item show trace-commands
+Display the current state of command tracing.
+@end table
+
@node Debugging Output
@section Optional messages about internal happenings
@cindex optional debugging messages
@item set debug overload
@cindex C@t{++} overload debugging info
Turns on or off display of @value{GDBN} C@t{++} overload debugging
-info. This includes info such as ranking of functions, etc. The default
+info. This includes info such as ranking of functions, etc. The default
is off.
@item show debug overload
Displays the current state of displaying @value{GDBN} C@t{++} overload
debugging info.
@cindex packets, reporting on stdout
@cindex serial connections, debugging
+@cindex debug remote protocol
+@cindex remote protocol debugging
+@cindex display remote packets
@item set debug remote
Turns on or off display of reports on all packets sent back and forth across
the serial line to the remote machine. The info is printed on the
@item show debugvarobj
Displays the current state of displaying @value{GDBN} variable object
debugging info.
+@item set debug xml
+@cindex XML parser debugging
+Turns on or off debugging messages for built-in XML parsers.
+@item show debug xml
+Displays the current state of XML debugging messages.
@end table
@node Sequences
files.
@menu
-* Define:: User-defined commands
-* Hooks:: User-defined command hooks
-* Command Files:: Command files
-* Output:: Commands for controlled output
+* Define:: How to define your own commands
+* Hooks:: Hooks for user-defined commands
+* Command Files:: How to write scripts of commands to be stored in a file
+* Output:: Commands for controlled output
@end menu
@node Define
@section User-defined commands
@cindex user-defined command
+@cindex arguments, to user-defined commands
A @dfn{user-defined command} is a sequence of @value{GDBN} commands to
which you assign a new name as a command. This is done with the
@code{define} command. User commands may accept up to 10 arguments
reference variables, use complex expressions, or even perform inferior
functions calls.
+@cindex argument count in user-defined commands
+@cindex how many arguments (user-defined commands)
In addition, @code{$argc} may be used to find out how many arguments have
been passed. This expands to a number in the range 0@dots{}10.
which are given following the @code{define} command. The end of these
commands is marked by a line containing @code{end}.
-@kindex if
-@kindex else
-@item if
-@itemx else
-Takes a single argument, which is an expression to evaluate.
-It is followed by a series of commands that are executed
-only if the expression is true (nonzero).
-There can then optionally be a line @code{else}, followed
-by a series of commands that are only executed if the expression
-was false. The end of the list is marked by a line containing @code{end}.
-
-@kindex while
-@item while
-The syntax is similar to @code{if}: the command takes a single argument,
-which is an expression to evaluate, and must be followed by the commands to
-execute, one per line, terminated by an @code{end}.
-The commands are executed repeatedly as long as the expression
-evaluates to true.
-
@kindex document
+@kindex end@r{ (user-defined commands)}
@item document @var{commandname}
Document the user-defined command @var{commandname}, so that it can be
accessed by @code{help}. The command @var{commandname} must already be
not its documentation). If no @var{commandname} is given, display the
definitions for all user-defined commands.
-@cindex infinite recusrion in user-defined commands
+@cindex infinite recursion in user-defined commands
@kindex show max-user-call-depth
@kindex set max-user-call-depth
@item show max-user-call-depth
The value of @code{max-user-call-depth} controls how many recursion
levels are allowed in user-defined commands before GDB suspects an
infinite recursion and aborts the command.
-
@end table
+In addition to the above commands, user-defined commands frequently
+use control flow commands, described in @ref{Command Files}.
+
When user-defined commands are executed, the
commands of the definition are not printed. An error in any command
stops execution of the user-defined command.
end
define hook-continue
-handle SIGLARM pass
+handle SIGALRM pass
end
@end smallexample
-As a further example, to hook at the begining and end of the @code{echo}
+As a further example, to hook at the beginning and end of the @code{echo}
command, and to add extra text to the beginning and end of the message,
you could define:
You can define a hook for any single-word command in @value{GDBN}, but
not for command aliases; you should define a hook for the basic command
-name, e.g. @code{backtrace} rather than @code{bt}.
+name, e.g.@: @code{backtrace} rather than @code{bt}.
@c FIXME! So how does Joe User discover whether a command is an alias
@c or not?
If an error occurs during the execution of your hook, execution of
@section Command files
@cindex command files
+@cindex scripting commands
A command file for @value{GDBN} is a text file made of lines that are
@value{GDBN} commands. Comments (lines starting with @kbd{#}) may
also be included. An empty line in a command file does nothing; it
@table @code
@kindex source
-@item source @var{filename}
+@cindex execute commands from a file
+@item source [@code{-v}] @var{filename}
Execute the command file @var{filename}.
@end table
-The lines in a command file are executed sequentially. They are not
+The lines in a command file are generally executed sequentially,
+unless the order of execution is changed by one of the
+@emph{flow-control commands} described below. The commands are not
printed as they are executed. An error in any command terminates
execution of the command file and control is returned to the console.
+@value{GDBN} searches for @var{filename} in the current directory and then
+on the search path (specified with the @samp{directory} command).
+
+If @code{-v}, for verbose mode, is given then @value{GDBN} displays
+each command as it is executed. The option must be given before
+@var{filename}, and is interpreted as part of the filename anywhere else.
+
Commands that would ask for confirmation if used interactively proceed
without asking when used in a command file. Many @value{GDBN} commands that
normally print messages to say what they are doing omit the messages
will execute commands from the file @file{cmds}. All output and errors
would be directed to @file{log}.
+Since commands stored on command files tend to be more general than
+commands typed interactively, they frequently need to deal with
+complicated situations, such as different or unexpected values of
+variables and symbols, changes in how the program being debugged is
+built, etc. @value{GDBN} provides a set of flow-control commands to
+deal with these complexities. Using these commands, you can write
+complex scripts that loop over data structures, execute commands
+conditionally, etc.
+
+@table @code
+@kindex if
+@kindex else
+@item if
+@itemx else
+This command allows to include in your script conditionally executed
+commands. The @code{if} command takes a single argument, which is an
+expression to evaluate. It is followed by a series of commands that
+are executed only if the expression is true (its value is nonzero).
+There can then optionally be an @code{else} line, followed by a series
+of commands that are only executed if the expression was false. The
+end of the list is marked by a line containing @code{end}.
+
+@kindex while
+@item while
+This command allows to write loops. Its syntax is similar to
+@code{if}: the command takes a single argument, which is an expression
+to evaluate, and must be followed by the commands to execute, one per
+line, terminated by an @code{end}. These commands are called the
+@dfn{body} of the loop. The commands in the body of @code{while} are
+executed repeatedly as long as the expression evaluates to true.
+
+@kindex loop_break
+@item loop_break
+This command exits the @code{while} loop in whose body it is included.
+Execution of the script continues after that @code{while}s @code{end}
+line.
+
+@kindex loop_continue
+@item loop_continue
+This command skips the execution of the rest of the body of commands
+in the @code{while} loop in whose body it is included. Execution
+branches to the beginning of the @code{while} loop, where it evaluates
+the controlling expression.
+
+@kindex end@r{ (if/else/while commands)}
+@item end
+Terminate the block of commands that are the body of @code{if},
+@code{else}, or @code{while} flow-control commands.
+@end table
+
+
@node Output
@section Commands for controlled output
for scrolling. This means they are available for readline when the
active window is the command window. When the command window
does not have the focus, it is necessary to use other readline
-key bindings such as @key{C-p}, @key{C-n}, @key{C-b} and @key{C-f}.
+key bindings such as @kbd{C-p}, @kbd{C-n}, @kbd{C-b} and @kbd{C-f}.
@node TUI Single Key Mode
@section TUI Single Key Mode
it is possible to type most @value{GDBN} commands without interaction
with the TUI @emph{SingleKey} mode. Once the command is entered the TUI
@emph{SingleKey} mode is restored. The only way to permanently leave
-this mode is by hitting @key{q} or @samp{@key{C-x} @key{s}}.
+this mode is by typing @kbd{q} or @kbd{C-x s}.
@node TUI Commands
@item refresh
@kindex refresh
-Refresh the screen. This is similar to using @key{C-L} key.
+Refresh the screen. This is similar to typing @kbd{C-L}.
@item tui reg float
@kindex tui reg
@value{GDBN} @code{down} command.
@end table
-In any source file, the Emacs command @kbd{C-x SPC} (@code{gud-break})
+In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break})
tells @value{GDBN} to set a breakpoint on the source line point is on.
If you type @kbd{M-x speedbar}, then Emacs displays a separate frame which
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
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Compatibility with CLI
+@section @sc{gdb/mi} Compatibility with CLI
-@noindent
-and later:
+@cindex compatibility, @sc{gdb/mi} and CLI
+@cindex @sc{gdb/mi}, compatibility with CLI
-@smallexample
-<- *stop,reason="stop",address="0x123",source="a.c:123"
-<- (@value{GDBP})
-@end smallexample
+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.
-@subsubheading Simple CLI Command
+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}).
-Here's an example of a simple CLI command being passed through
-@sc{gdb/mi} and on to the CLI.
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Development and Front Ends
+@section @sc{gdb/mi} Development and Front Ends
+@cindex @sc{gdb/mi} development
-@smallexample
--> print 1+2
-<- &"print 1+2\n"
-<- ~"$1 = 3\n"
-<- ^done
-<- (@value{GDBP})
-@end smallexample
+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}.
-@subsubheading Command With Side Effects
+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.
-@smallexample
--> -symbol-file xyz.exe
-<- *breakpoint,nr="3",address="0x123",source="a.c:123"
-<- (@value{GDBP})
-@end smallexample
+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:
-@subsubheading A Bad Command
+@itemize @bullet
+@item
+New MI commands may be added.
-Here's what happens if you pass a non-existent command:
+@item
+New fields may be added to the output of any MI command.
-@smallexample
--> -rubbish
-<- ^error,msg="Undefined MI command: rubbish"
-<- (@value{GDBP})
-@end smallexample
+@item
+The range of values for fields with specified values, e.g.,
+@code{in_scope} (@pxref{-var-update}) may be extended.
-@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 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 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",line="5"@}
-(@value{GDBP})
+^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",
+fullname="/home/foo/hello.c",line="5",times="0"@}
+(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"@},
@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
-addr="0x000100d0",func="main",file="hello.c",line="5",times="0",
-ignore="3"@}]@}
-(@value{GDBP})
+addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
+line="5",times="0",ignore="3"@}]@}
+(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"@},
@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
-addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",
-times="0",ignore="3"@}]@}
-(@value{GDBP})
+addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
+line="5",cond="1",times="0",ignore="3"@}]@}
+(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"@},
@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
-addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@}
-(@value{GDBP})
+addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
+line="5",times="0"@}]@}
+(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"@},
@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
-addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@}
-(@value{GDBP})
+addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
+line="5",times="0"@}]@}
+(gdb)
@end smallexample
@subheading The @code{-break-info} Command
@table @samp
@item -t
-Insert a tempoary breakpoint.
+Insert a temporary breakpoint.
@item -h
Insert a hardware breakpoint.
@item -c @var{condition}
@item -r
Insert a regular breakpoint in all the functions whose names match the
given regular expression. Other flags are not applicable to regular
-expresson.
+expressions.
@end table
@subsubheading Result
The result is in the form:
@smallexample
- ^done,bkptno="@var{number}",func="@var{funcname}",
- file="@var{filename}",line="@var{lineno}"
+^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}",[thread="@var{threadno},]
+times="@var{times}"@}
@end smallexample
@noindent
-where @var{number} is the @value{GDBN} number for this breakpoint, @var{funcname}
-is the name of the function where the breakpoint was inserted,
-@var{filename} is the name of the source file which contains this
-function, and @var{lineno} is the source line number within that file.
+where @var{number} is the @value{GDBN} number for this breakpoint,
+@var{funcname} is the name of the function where the breakpoint was
+inserted, @var{filename} is the name of the source file which contains
+this function, @var{lineno} is the source line number within that file
+and @var{times} the number of times that the breakpoint has been hit
+(always 0 for -break-insert but may be greater for -break-info or -break-list
+which use the same output).
Note: this format is open to change.
@c An out-of-band breakpoint instead of part of the result?
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-break-insert main
-^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
-(@value{GDBP})
+^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",
+fullname="/home/foo/recursive2.c,line="4",times="0"@}
+(gdb)
-break-insert -t foo
-^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@}
-(@value{GDBP})
+^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",
+fullname="/home/foo/recursive2.c,line="11",times="0"@}
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="2",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=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
-addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@},
+addr="0x0001072c", func="main",file="recursive2.c",
+fullname="/home/foo/recursive2.c,"line="4",times="0"@},
bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
-addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}]@}
-(@value{GDBP})
+addr="0x00010774",func="foo",file="recursive2.c",
+fullname="/home/foo/recursive2.c",line="11",times="0"@}]@}
+(gdb)
-break-insert -r foo.*
~int foo(int, int);
-^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@}
-(@value{GDBP})
+^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c,
+"fullname="/home/foo/recursive2.c",line="11",times="0"@}
+(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"@},
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
-addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}]@}
-(@value{GDBP})
+addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
+line="13",times="0"@}]@}
+(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
@end smallexample
Create a watchpoint. With the @samp{-a} option it will create an
-@dfn{access} watchpoint, i.e. a watchpoint that triggers either on a
+@dfn{access} watchpoint, i.e., a watchpoint that triggers either on a
read from or on a write to the memory location. With the @samp{-r}
-option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will
+option, the watchpoint created is a @dfn{read} watchpoint, i.e., it will
trigger only when the memory location is accessed for reading. Without
either of the options, the watchpoint created is a regular watchpoint,
-i.e. it will trigger when the memory location is accessed for writing.
+i.e., it will trigger when the memory location is accessed for writing.
@xref{Set Watchpoints, , Setting watchpoints}.
Note that @samp{-break-list} will report a single list of watchpoints and
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"@},
+(gdb)
+*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
value=@{old="-268439212",new="55"@},
frame=@{func="main",args=[],file="recursive2.c",
-fullname="/home/foo/bar/devo/myproject/recursive2.c",line="5"@}
-(@value{GDBP})
+fullname="/home/foo/bar/recursive2.c",line="5"@}
+(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",
+(gdb)
+*stopped,reason="watchpoint-trigger",
wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
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",
+(gdb)
+*stopped,reason="watchpoint-scope",wpnum="5",
frame=@{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})
+(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"@},
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x00010734",func="callee4",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+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"@},
+(gdb)
+*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
value=@{old="-276895068",new="3"@},
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
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"@},
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x00010734",func="callee4",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+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"@},
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x00010734",func="callee4",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}]@}
-(@value{GDBP})
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
+times="1"@}]@}
+(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.
+@subheading The @code{-exec-arguments} Command
+@findex -exec-arguments
-@c REMOVED FROM THE INTERFACE.
-@c @subheading -data-assign
-@c Change the value of a program variable. Plenty of side effects.
-@c @subsubheading GDB command
-@c set variable
-@c @subsubheading Example
-@c N.A.
-@subheading The @code{-data-disassemble} Command
-@findex -data-disassemble
+@subsubheading Synopsis
+
+@smallexample
+ -exec-arguments @var{args}
+@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
+
+@c FIXME!
+Don't have one around.
+
+
+@subheading The @code{-exec-show-arguments} Command
+@findex -exec-show-arguments
@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-show-arguments
@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.
+Print the arguments of the program.
@subsubheading @value{GDBN} Command
-There's no direct mapping from this command to the CLI.
+The corresponding @value{GDBN} command is @samp{show args}.
@subsubheading Example
+N.A.
-Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
-@smallexample
-(@value{GDBP})
--data-disassemble -s $pc -e "$pc + 20" -- 0
-^done,
-asm_insns=[
-@{address="0x000107c0",func-name="main",offset="4",
-inst="mov 2, %o0"@},
-@{address="0x000107c4",func-name="main",offset="8",
-inst="sethi %hi(0x11800), %o2"@},
-@{address="0x000107c8",func-name="main",offset="12",
-inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
-@{address="0x000107cc",func-name="main",offset="16",
-inst="sethi %hi(0x11800), %o2"@},
-@{address="0x000107d0",func-name="main",offset="20",
-inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}]
-(@value{GDBP})
-@end smallexample
+@subheading The @code{-environment-cd} Command
+@findex -environment-cd
-Disassemble the whole @code{main} function. Line 32 is part of
-@code{main}.
+@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})
+ -environment-cd @var{pathdir}
@end smallexample
-Disassemble 3 instructions from the start of @code{main}:
+Set @value{GDBN}'s working directory.
-@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{cd}.
+
+@subsubheading Example
@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})
+(gdb)
+-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
+^done
+(gdb)
@end smallexample
-@subheading The @code{-data-evaluate-expression} Command
-@findex -data-evaluate-expression
+@subheading The @code{-environment-directory} Command
+@findex -environment-directory
@subsubheading Synopsis
@smallexample
- -data-evaluate-expression @var{expr}
+ -environment-directory [ -r ] [ @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.
+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-separator
+character must not be used
+in any directory name.
+If no directories are specified, the current search path is displayed.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} 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{dir}.
@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-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-changed-registers} Command
-@findex -data-list-changed-registers
+@subheading The @code{-environment-path} Command
+@findex -environment-path
@subsubheading Synopsis
@smallexample
- -data-list-changed-registers
+ -environment-path [ -r ] [ @var{pathdir} ]+
@end smallexample
-Display a list of the registers that have changed.
+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-separator
+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} 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{path}.
@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/devo/myproject/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-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-names} Command
-@findex -data-list-register-names
+@subheading The @code{-environment-pwd} Command
+@findex -environment-pwd
@subsubheading Synopsis
@smallexample
- -data-list-register-names [ ( @var{regno} )+ ]
+ -environment-pwd
@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.
+Show the current working directory.
-@subsubheading @value{GDBN} Command
+@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{pwd}.
@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-pwd
+^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
+(gdb)
@end smallexample
-@subheading The @code{-data-list-register-values} Command
-@findex -data-list-register-values
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Thread Commands
+@section @sc{gdb/mi} Thread Commands
+
+
+@subheading The @code{-thread-info} Command
+@findex -thread-info
@subsubheading Synopsis
@smallexample
- -data-list-register-values @var{fmt} [ ( @var{regno} )*]
+ -thread-info
@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.
-
-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}.
+No equivalent.
@subsubheading Example
-
-For a PPC MBX board (note: line breaks are for readability only, they
-don't appear in the actual output):
-
-@smallexample
-(@value{GDBP})
--data-list-register-values r 64 65
-^done,register-values=[@{number="64",value="0xfe00a300"@},
-@{number="65",value="0x00029002"@}]
-(@value{GDBP})
--data-list-register-values x
-^done,register-values=[@{number="0",value="0xfe0043c8"@},
-@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
-@{number="3",value="0x0"@},@{number="4",value="0xa"@},
-@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
-@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
-@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
-@{number="11",value="0x1"@},@{number="12",value="0x0"@},
-@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
-@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
-@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
-@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
-@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
-@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
-@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
-@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
-@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
-@{number="31",value="0x0"@},@{number="32",value="0x0"@},
-@{number="33",value="0x0"@},@{number="34",value="0x0"@},
-@{number="35",value="0x0"@},@{number="36",value="0x0"@},
-@{number="37",value="0x0"@},@{number="38",value="0x0"@},
-@{number="39",value="0x0"@},@{number="40",value="0x0"@},
-@{number="41",value="0x0"@},@{number="42",value="0x0"@},
-@{number="43",value="0x0"@},@{number="44",value="0x0"@},
-@{number="45",value="0x0"@},@{number="46",value="0x0"@},
-@{number="47",value="0x0"@},@{number="48",value="0x0"@},
-@{number="49",value="0x0"@},@{number="50",value="0x0"@},
-@{number="51",value="0x0"@},@{number="52",value="0x0"@},
-@{number="53",value="0x0"@},@{number="54",value="0x0"@},
-@{number="55",value="0x0"@},@{number="56",value="0x0"@},
-@{number="57",value="0x0"@},@{number="58",value="0x0"@},
-@{number="59",value="0x0"@},@{number="60",value="0x0"@},
-@{number="61",value="0x0"@},@{number="62",value="0x0"@},
-@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
-@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
-@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
-@{number="69",value="0x20002b03"@}]
-(@value{GDBP})
-@end smallexample
+N.A.
-@subheading The @code{-data-read-memory} Command
-@findex -data-read-memory
+@subheading The @code{-thread-list-all-threads} Command
+@findex -thread-list-all-threads
@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-list-all-threads
@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}).
+@subsubheading @value{GDBN} Command
-@item @var{word-size}
-The size of each memory word in bytes.
+The equivalent @value{GDBN} command is @samp{info threads}.
-@item @var{nr-rows}
-The number of rows in the output table.
+@subsubheading Example
+N.A.
-@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).
+@subheading The @code{-thread-list-ids} Command
+@findex -thread-list-ids
-@item @var{byte-offset}
-An offset to add to the @var{address} before fetching memory.
-@end table
+@subsubheading Synopsis
-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}.
+@smallexample
+ -thread-list-ids
+@end smallexample
-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}.
+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{x}. @code{gdbtk} has
-@samp{gdb_get_mem} memory read command.
+Part of @samp{info threads} supplies the same information.
@subsubheading Example
-Read six bytes of memory starting at @code{bytes+6} but then offset by
-@code{-6} bytes. Format as three rows of two columns. One byte per
-word. Display each word in hex.
+No threads present, besides the main process:
@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})
+(gdb)
+-thread-list-ids
+^done,thread-ids=@{@},number-of-threads="0"
+(gdb)
@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.
+Several threads:
@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})
+(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-delete} Command
-@findex -display-delete
+
+@subheading The @code{-thread-select} Command
+@findex -thread-select
@subsubheading Synopsis
@smallexample
- -display-delete @var{number}
+ -thread-select @var{threadnum}
@end smallexample
-Delete the display @var{number}.
+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{delete display}.
+The corresponding @value{GDBN} command is @samp{thread}.
@subsubheading Example
-N.A.
-
-
-@subheading The @code{-display-disable} Command
-@findex -display-disable
-
-@subsubheading Synopsis
@smallexample
- -display-disable @var{number}
+(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
-Disable display @var{number}.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{disable display}.
-
-@subsubheading Example
-N.A.
+@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-enable} Command
-@findex -display-enable
+@subheading The @code{-exec-continue} Command
+@findex -exec-continue
@subsubheading Synopsis
@smallexample
- -display-enable @var{number}
+ -exec-continue
@end smallexample
-Enable display @var{number}.
+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{enable 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{-display-insert} Command
-@findex -display-insert
+
+@subheading The @code{-exec-finish} Command
+@findex -exec-finish
@subsubheading Synopsis
@smallexample
- -display-insert @var{expression}
+ -exec-finish
@end smallexample
-Display @var{expression} every time the program stops.
+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{display}.
+The corresponding @value{GDBN} command is @samp{finish}.
@subsubheading Example
-N.A.
+Function returning @code{void}.
-@subheading The @code{-display-list} Command
-@findex -display-list
+@smallexample
+-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
-@subsubheading Synopsis
+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
- -display-list
+-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
-List the displays. Do not show the current values.
-@subsubheading @value{GDBN} Command
+@subheading The @code{-exec-interrupt} Command
+@findex -exec-interrupt
-The corresponding @value{GDBN} command is @samp{info display}.
-
-@subsubheading Example
-N.A.
-
-
-@subheading The @code{-environment-cd} Command
-@findex -environment-cd
-
-@subsubheading Synopsis
+@subsubheading Synopsis
@smallexample
- -environment-cd @var{pathdir}
+ -exec-interrupt
@end smallexample
-Set @value{GDBN}'s working directory.
+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{cd}.
+The corresponding @value{GDBN} command is @samp{interrupt}.
@subsubheading Example
@smallexample
-(@value{GDBP})
--environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
-^done
-(@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-directory} Command
-@findex -environment-directory
+@subheading The @code{-exec-next} Command
+@findex -exec-next
@subsubheading Synopsis
@smallexample
- -environment-directory [ -r ] [ @var{pathdir} ]+
+ -exec-next
@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.
+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{dir}.
+The corresponding @value{GDBN} command is @samp{next}.
@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})
+-exec-next
+^running
+(gdb)
+*stopped,reason="end-stepping-range",line="8",file="hello.c"
+(gdb)
@end smallexample
-@subheading The @code{-environment-path} Command
-@findex -environment-path
+@subheading The @code{-exec-next-instruction} Command
+@findex -exec-next-instruction
@subsubheading Synopsis
@smallexample
- -environment-path [ -r ] [ @var{pathdir} ]+
+ -exec-next-instruction
@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.
-
+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.
-As a result of execution, the inferior program can run to completion, if
-it doesn't encounter any breakpoints. In this case the output will
-include an exit code, if the program has exited exceptionally.
+@subsubheading @value{GDBN} Command
+
+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/devo/myproject/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/devo/myproject/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/devo/myproject/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/devo/myproject/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. If the two arguments are equal, show the single frame
+at the corresponding level. It is an error if @var{low-frame} is
+larger than the actual number of frames. On the other hand,
+@var{high-frame} may be larger than the actual number of frames, in
+which case only existing frames will be returned.
+
+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.
+List the frames currently on the stack. For each frame it displays the
+following info:
+
+@table @samp
+@item @var{level}
+The frame number, 0 being the topmost frame, i.e., the innermost function.
+@item @var{addr}
+The @code{$pc} value for that frame.
+@item @var{func}
+Function name.
+@item @var{file}
+File name of the source file where the function lives.
+@item @var{line}
+Line number corresponding to the @code{$pc}.
+@end table
+
+If invoked without arguments, this command prints a backtrace for the
+whole stack. If given two integer arguments, it shows the frames whose
+levels are between the two arguments (inclusive). If the two arguments
+are equal, it shows the single frame at the corresponding level. It is
+an error if @var{low-frame} is larger than the actual number of
+frames. On the other hand, @var{high-frame} may be larger than the
+actual number of frames, in which case only existing frames will be returned.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{return}.
+The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
@subsubheading Example
+Full stack backtrace:
+
@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})
+(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
-
-@subheading The @code{-exec-run} Command
-@findex -exec-run
-
-@subsubheading Synopsis
+Show frames between @var{low_frame} and @var{high_frame}:
@smallexample
- -exec-run
+(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
-Asynchronous command. Starts execution of the inferior from the
-beginning. The inferior executes until either a breakpoint is
-encountered or the program exits.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{run}.
-
-@subsubheading Example
+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/devo/myproject/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 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/devo/myproject/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
+@ignore
+@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
+@end ignore
-(@value{GDBP})
-*stopped,reason="end-stepping-range",
-frame=@{func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/devo/myproject/try.c",line="10"@}
-(@value{GDBP})
--exec-step-instruction
-^running
+@subheading Introduction to Variable Objects
-(@value{GDBP})
-*stopped,reason="end-stepping-range",
-frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/devo/myproject/try.c",line="10"@}
-(@value{GDBP})
-@end smallexample
+@cindex variable objects in @sc{gdb/mi}
+Variable objects are "object-oriented" MI interface for examining and
+changing values of expressions. Unlike some other MI interfaces that
+work with expressions, variable objects are specifically designed for
+simple and efficient presentation in the frontend. A variable object
+is identified by string name. When a variable object is created, the
+frontend specifies the expression for that variable object. The
+expression can be a simple variable, or it can be an arbitrary complex
+expression, and can even involve CPU registers. After creating a
+variable object, the frontend can invoke other variable object
+operations---for example to obtain or change the value of a variable
+object, or to change display format.
+
+Variable objects have hierarchical tree structure. Any variable object
+that corresponds to a composite type, such as structure in C, has
+a number of child variable objects, for example corresponding to each
+element of a structure. A child variable object can itself have
+children, recursively. Recursion ends when we reach
+leaf variable objects, which always have built-in types.
+
+For a leaf variable object it is possible to obtain its value as a
+string, or set the value from a string. String value can be also
+obtained for a non-leaf variable object, but it's generally a string
+that only indicates the type of the object, and does not list its
+contents. Assignment to a non-leaf variable object is not allowed.
+
+A frontend does not need to read the values of all variable objects each time
+the program stops. Instead, MI provides an update command that lists all
+variable objects whose values has changed since the last update
+operation. This considerably reduces the amount of data that must
+be transferred to the frontend.
-@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/or 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/devo/myproject/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.
+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.
-@subheading The @code{-file-exec-and-symbols} Command
-@findex -file-exec-and-symbols
+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.
-@subsubheading Synopsis
+@var{expression} is any expression valid on the current language set (must not
+begin with a @samp{*}), or one of the following:
-@smallexample
- -file-exec-and-symbols @var{file}
-@end smallexample
+@itemize @bullet
+@item
+@samp{*@var{addr}}, where @var{addr} is the address of a memory cell
-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.
+@item
+@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
-@subsubheading @value{GDBN} Command
+@item
+@samp{$@var{regname}} --- a CPU register name
+@end itemize
-The corresponding @value{GDBN} command is @samp{file}.
+@subsubheading Result
-@subsubheading Example
+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 [ -c ] @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.
+With the @samp{-c} option, just deletes the 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.
+The natural format is the default format choosen automatically
+based on the variable type (like decimal for an @code{int}, hex
+for pointers, etc.).
-@subsubheading @value{GDBN} Command
+For a variable with children, the format is set only on the
+variable itself, and the children are not affected.
-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}.
+@subheading The @code{-var-show-format} Command
+@findex -var-show-format
-@subsubheading Example
-N.A.
-
-
-@subheading The @code{-file-list-exec-source-file} Command
-@findex -file-list-exec-source-file
-
-@subsubheading Synopsis
+@subsubheading Synopsis
@smallexample
- -file-list-exec-source-file
+ -var-show-format @var{name}
@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
-
-There's no @value{GDBN} command which directly corresponds to this one.
-
-@subsubheading Example
+Returns the format used to display the value of the 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})
+ @var{format} @expansion{}
+ @var{format-spec}
@end smallexample
-@subheading The @code{-file-list-exec-source-files} Command
-@findex -file-list-exec-source-files
+@subheading The @code{-var-info-num-children} Command
+@findex -var-info-num-children
@subsubheading Synopsis
@smallexample
- -file-list-exec-source-files
+ -var-info-num-children @var{name}
@end smallexample
-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}.
+Returns the number of children of a variable object @var{name}:
-@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})
+ numchild=@var{n}
@end smallexample
-@subheading The @code{-file-list-shared-libraries} Command
-@findex -file-list-shared-libraries
+
+@subheading The @code{-var-list-children} Command
+@findex -var-list-children
@subsubheading Synopsis
@smallexample
- -file-list-shared-libraries
+ -var-list-children [@var{print-values}] @var{name}
@end smallexample
+@anchor{-var-list-children}
-List the shared libraries in the program.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{info shared}.
+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
-N.A.
-
-
-@subheading The @code{-file-list-symbol-files} Command
-@findex -file-list-symbol-files
-
-@subsubheading Synopsis
@smallexample
- -file-list-symbol-files
+(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
-List symbol files.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{info file} (part of it).
-
-@subsubheading Example
-N.A.
-
-@subheading The @code{-file-symbol-file} Command
-@findex -file-symbol-file
+@subheading The @code{-var-info-type} Command
+@findex -var-info-type
@subsubheading Synopsis
@smallexample
- -file-symbol-file @var{file}
+ -var-info-type @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.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{symbol-file}.
-
-@subsubheading Example
+Returns the type of the specified variable @var{name}. The type is
+returned as a string in the same format as it is output by the
+@value{GDBN} CLI:
@smallexample
-(@value{GDBP})
--file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
-^done
-(@value{GDBP})
+ type=@var{typename}
@end smallexample
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Miscellaneous Commands
-@section Miscellaneous @value{GDBN} commands in @sc{gdb/mi}
-
-@c @subheading -gdb-complete
-@subheading The @code{-gdb-exit} Command
-@findex -gdb-exit
+@subheading The @code{-var-info-expression} Command
+@findex -var-info-expression
@subsubheading Synopsis
@smallexample
- -gdb-exit
+ -var-info-expression @var{name}
@end smallexample
-Exit @value{GDBN} immediately.
-
-@subsubheading @value{GDBN} Command
-
-Approximately corresponds to @samp{quit}.
-
-@subsubheading Example
+Returns what is represented by the variable object @var{name}:
@smallexample
-(@value{GDBP})
--gdb-exit
+ lang=@var{lang-spec},exp=@var{expression}
@end smallexample
-@subheading The @code{-gdb-set} Command
-@findex -gdb-set
+@noindent
+where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
+
+@subheading The @code{-var-show-attributes} Command
+@findex -var-show-attributes
@subsubheading Synopsis
@smallexample
- -gdb-set
+ -var-show-attributes @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}.
-
-@subsubheading Example
+List attributes of the specified variable object @var{name}:
@smallexample
-(@value{GDBP})
--gdb-set $foo=3
-^done
-(@value{GDBP})
+ status=@var{attr} [ ( ,@var{attr} )* ]
@end smallexample
+@noindent
+where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
-@subheading The @code{-gdb-show} Command
-@findex -gdb-show
+@subheading The @code{-var-evaluate-expression} Command
+@findex -var-evaluate-expression
@subsubheading Synopsis
@smallexample
- -gdb-show
+ -var-evaluate-expression @var{name}
@end smallexample
-Show the current value of a @value{GDBN} variable.
-
-@subsubheading @value{GDBN} command
-
-The corresponding @value{GDBN} command is @samp{show}.
-
-@subsubheading Example
+Evaluates the expression that is represented by the specified variable
+object and returns its value as a string. The format of the
+string can be changed using the @code{-var-set-format} command.
@smallexample
-(@value{GDBP})
--gdb-show annotate
-^done,value="0"
-(@value{GDBP})
+ value=@var{value}
@end smallexample
-@c @subheading -gdb-source
-
+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{-gdb-version} Command
-@findex -gdb-version
+@subheading The @code{-var-assign} Command
+@findex -var-assign
@subsubheading Synopsis
@smallexample
- -gdb-version
+ -var-assign @var{name} @var{expression}
@end smallexample
-Show version information for @value{GDBN}. Used mostly in testing.
-
-@subsubheading @value{GDBN} Command
-
-There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this
-information when you start an interactive session.
+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
-@c This example modifies the actual output from GDB to avoid overfull
-@c box in TeX.
@smallexample
-(@value{GDBP})
--gdb-version
-~GNU gdb 5.2.1
-~Copyright 2000 Free Software Foundation, Inc.
-~GDB is free software, covered by the GNU General Public License, and
-~you are welcome to change it and/or distribute copies of it under
-~ certain conditions.
-~Type "show copying" to see the conditions.
-~There is absolutely no warranty for GDB. Type "show warranty" for
-~ details.
-~This GDB was configured as
- "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
-^done
-(@value{GDBP})
+(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{-interpreter-exec} Command
-@findex -interpreter-exec
+@subheading The @code{-var-update} Command
+@findex -var-update
-@subheading Synopsis
+@subsubheading Synopsis
@smallexample
--interpreter-exec @var{interpreter} @var{command}
+ -var-update [@var{print-values}] @{@var{name} | "*"@}
@end smallexample
-Execute the specified @var{command} in the given @var{interpreter}.
-
-@subheading @value{GDBN} Command
+Reevaluate the expressions corresponding to the variable object
+@var{name} and all its direct and indirect children, and return the
+list of variable objects whose values have changed; @var{name} must
+be a root variable object. Here, ``changed'' means that the result of
+@code{-var-evaluate-expression} before and after the
+@code{-var-update} is different. If @samp{*} is used as the variable
+object names, all existing variable objects are updated. The option
+@var{print-values} determines whether both names and values, or just
+names are printed. The possible values of this options are the same
+as for @code{-var-list-children} (@pxref{-var-list-children}). It is
+recommended to use the @samp{--all-values} option, to reduce the
+number of MI commands needed on each program stop.
-The corresponding @value{GDBN} command is @samp{interpreter-exec}.
-@subheading Example
+@subsubheading Example
@smallexample
-(@value{GDBP})
--interpreter-exec console "break main"
-&"During symbol reading, couldn't parse type; debugger out of date?.\n"
-&"During symbol reading, bad structure-type format.\n"
-~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
-^done
-(@value{GDBP})
+(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
-@subheading The @code{-inferior-tty-set} Command
-@findex -inferior-tty-set
+@anchor{-var-update}
+The field in_scope may take three values:
-@subheading Synopsis
+@table @code
+@item "true"
+The variable object's current value is valid.
-@smallexample
--inferior-tty-set /dev/pts/1
-@end smallexample
+@item "false"
+The variable object does not currently hold a valid value but it may
+hold one in the future if its associated expression comes back into
+scope.
-Set terminal for future runs of the program being debugged.
+@item "invalid"
+The variable object no longer holds a valid value.
+This can occur when the executable file being debugged has changed,
+either through recompilation or by using the @value{GDBN} @code{file}
+command. The front end should normally choose to delete these variable
+objects.
+@end table
-@subheading @value{GDBN} Command
+In the future new values may be added to this list so the front should
+be prepared for this possibility. @xref{GDB/MI Development and Front Ends, ,@sc{GDB/MI} Development and Front Ends}.
-The corresponding @value{GDBN} command is @samp{set inferior-tty /dev/pts/1}.
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Data Manipulation
+@section @sc{gdb/mi} Data Manipulation
-@subheading Example
+@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.
-@smallexample
-(@value{GDBP})
--inferior-tty-set /dev/pts/1
-^done
-(@value{GDBP})
-@end smallexample
+@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{-inferior-tty-show} Command
-@findex -inferior-tty-show
+@subheading The @code{-data-disassemble} Command
+@findex -data-disassemble
-@subheading Synopsis
+@subsubheading Synopsis
@smallexample
--inferior-tty-show
+ -data-disassemble
+ [ -s @var{start-addr} -e @var{end-addr} ]
+ | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
+ -- @var{mode}
@end smallexample
-Show terminal for future runs of program being debugged.
+@noindent
+Where:
-@subheading @value{GDBN} Command
+@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 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
-The corresponding @value{GDBN} command is @samp{show inferior-tty}.
+@subsubheading Result
-@subheading Example
+The output for each instruction is composed of four fields:
-@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
+@itemize @bullet
+@item Address
+@item Func-name
+@item Offset
+@item Instruction
+@end itemize
-@ignore
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Kod Commands
-@section @sc{gdb/mi} Kod Commands
+Note that whatever included in the instruction field, is not manipulated
+directly by @sc{gdb/mi}, i.e., it is not possible to adjust its format.
-The Kod commands are not implemented.
+@subsubheading @value{GDBN} Command
-@c @subheading -kod-info
+There's no direct mapping from this command to the CLI.
-@c @subheading -kod-list
+@subsubheading Example
-@c @subheading -kod-list-object-types
+Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
-@c @subheading -kod-show
+@smallexample
+(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
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Memory Overlay Commands
-@section @sc{gdb/mi} Memory Overlay Commands
+Disassemble the whole @code{main} function. Line 32 is part of
+@code{main}.
-The memory overlay commands are not implemented.
+@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 "@}]
+(gdb)
+@end smallexample
-@c @subheading -overlay-auto
+Disassemble 3 instructions from the start of @code{main}:
-@c @subheading -overlay-list-mapping-state
+@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
-@c @subheading -overlay-list-overlays
+Disassemble 3 instructions from the start of @code{main} in mixed mode:
-@c @subheading -overlay-map
+@smallexample
+(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
-@c @subheading -overlay-off
-@c @subheading -overlay-on
+@subheading The @code{-data-evaluate-expression} Command
+@findex -data-evaluate-expression
-@c @subheading -overlay-unmap
+@subsubheading Synopsis
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Signal Handling Commands
-@section @sc{gdb/mi} Signal Handling Commands
+@smallexample
+ -data-evaluate-expression @var{expr}
+@end smallexample
-Signal handling commands are not implemented.
+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.
-@c @subheading -signal-handle
+@subsubheading @value{GDBN} Command
-@c @subheading -signal-list-handle-actions
+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.
-@c @subheading -signal-list-signal-types
-@end ignore
+@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.
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Stack Manipulation
-@section @sc{gdb/mi} Stack Manipulation Commands
+@smallexample
+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{-stack-info-frame} Command
-@findex -stack-info-frame
+@subheading The @code{-data-list-changed-registers} Command
+@findex -data-list-changed-registers
@subsubheading Synopsis
@smallexample
- -stack-info-frame
+ -data-list-changed-registers
@end smallexample
-Get info on the selected frame.
+Display a list of the registers that have changed.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
-(without arguments).
+@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
+has the corresponding command @samp{gdb_changed_register_list}.
@subsubheading Example
+On a PPC MBX board:
+
@smallexample
-(@value{GDBP})
--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)
+-exec-continue
+^running
+
+(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-depth} Command
-@findex -stack-info-depth
+
+@subheading The @code{-data-list-register-names} Command
+@findex -data-list-register-names
@subsubheading Synopsis
@smallexample
- -stack-info-depth [ @var{max-depth} ]
+ -data-list-register-names [ ( @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.
+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
-There's no equivalent @value{GDBN} command.
+@value{GDBN} does not have a command which corresponds to
+@samp{-data-list-register-names}. In @code{gdbtk} there is a
+corresponding command @samp{gdb_regnames}.
@subsubheading Example
-For a stack with frame levels 0 through 11:
+For the PPC MBX board:
+@smallexample
+(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{-data-list-register-values} Command
+@findex -data-list-register-values
+
+@subsubheading Synopsis
@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})
+ -data-list-register-values @var{fmt} [ ( @var{regno} )*]
@end smallexample
-@subheading The @code{-stack-list-arguments} Command
-@findex -stack-list-arguments
+Display the registers' contents. @var{fmt} is the format according to
+which the registers' contents are to be returned, followed by an optional
+list of numbers specifying the registers to display. A missing list of
+numbers indicates that the contents of all the registers must be returned.
+
+Allowed formats for @var{fmt} are:
+
+@table @code
+@item x
+Hexadecimal
+@item o
+Octal
+@item t
+Binary
+@item d
+Decimal
+@item r
+Raw
+@item N
+Natural
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
+all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
+
+@subsubheading Example
+
+For a PPC MBX board (note: line breaks are for readability only, they
+don't appear in the actual output):
+
+@smallexample
+(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{-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.
+@noindent
+where:
-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.
+@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
-@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}.
+The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
+@samp{gdb_get_mem} memory read command.
@subsubheading Example
+Read six bytes of memory starting at @code{bytes+6} but then offset by
+@code{-6} bytes. Format as three rows of two columns. One byte per
+word. Display each word in hex.
+
@smallexample
-(@value{GDBP})
--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})
+(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
+
+Read two bytes of memory starting at address @code{shorts + 64} and
+display as a single word formatted in decimal.
+
+@smallexample
+(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
+
+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
+(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
+
+The tracepoint commands are not yet implemented.
+
+@c @subheading -trace-actions
+
+@c @subheading -trace-delete
+
+@c @subheading -trace-disable
+
+@c @subheading -trace-dump
+
+@c @subheading -trace-enable
+
+@c @subheading -trace-exists
+
+@c @subheading -trace-find
+
+@c @subheading -trace-frame-number
+
+@c @subheading -trace-info
+
+@c @subheading -trace-insert
+
+@c @subheading -trace-list
+
+@c @subheading -trace-pass-count
+
+@c @subheading -trace-save
+
+@c @subheading -trace-start
+
+@c @subheading -trace-stop
+
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Symbol Query
+@section @sc{gdb/mi} Symbol Query Commands
+
+
+@subheading The @code{-symbol-info-address} Command
+@findex -symbol-info-address
+
+@subsubheading Synopsis
+
+@smallexample
+ -symbol-info-address @var{symbol}
+@end smallexample
+
+Describe where @var{symbol} is stored.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info address}.
+
+@subsubheading Example
+N.A.
+
+
+@subheading The @code{-symbol-info-file} Command
+@findex -symbol-info-file
+
+@subsubheading Synopsis
+
+@smallexample
+ -symbol-info-file
+@end smallexample
+
+Show the file for the symbol.
+
+@subsubheading @value{GDBN} Command
+
+There's no equivalent @value{GDBN} command. @code{gdbtk} has
+@samp{gdb_find_file}.
+
+@subsubheading Example
+N.A.
+
+
+@subheading The @code{-symbol-info-function} Command
+@findex -symbol-info-function
+
+@subsubheading Synopsis
+
+@smallexample
+ -symbol-info-function
@end smallexample
-@c @subheading -stack-list-exception-handlers
+Show which function the symbol lives in.
+
+@subsubheading @value{GDBN} Command
+@samp{gdb_get_function} in @code{gdbtk}.
-@subheading The @code{-stack-list-frames} Command
-@findex -stack-list-frames
+@subsubheading Example
+N.A.
+
+
+@subheading The @code{-symbol-info-line} Command
+@findex -symbol-info-line
@subsubheading Synopsis
@smallexample
- -stack-list-frames [ @var{low-frame} @var{high-frame} ]
+ -symbol-info-line
@end smallexample
-List the frames currently on the stack. For each frame it displays the
-following info:
-
-@table @samp
-@item @var{level}
-The frame number, 0 being the topmost frame, i.e. the innermost function.
-@item @var{addr}
-The @code{$pc} value for that frame.
-@item @var{func}
-Function name.
-@item @var{file}
-File name of the source file where the function lives.
-@item @var{line}
-Line number corresponding to the @code{$pc}.
-@end table
-
-If invoked without arguments, this command prints a backtrace for the
-whole stack. If given two integer arguments, it shows the frames whose
-levels are between the two arguments (inclusive). If the two arguments
-are equal, it shows the single frame at the corresponding level.
+Show the core addresses of the code for a source line.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
+The corresponding @value{GDBN} command is @samp{info line}.
+@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
@subsubheading Example
+N.A.
-Full stack backtrace:
-@smallexample
-(@value{GDBP})
--stack-list-frames
-^done,stack=
-[frame=@{level="0",addr="0x0001076c",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="11"@},
-frame=@{level="1",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
-frame=@{level="2",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
-frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
-frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
-frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
-frame=@{level="6",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
-frame=@{level="7",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
-frame=@{level="8",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
-frame=@{level="9",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
-frame=@{level="10",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
-frame=@{level="11",addr="0x00010738",func="main",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="4"@}]
-(@value{GDBP})
-@end smallexample
+@subheading The @code{-symbol-info-symbol} Command
+@findex -symbol-info-symbol
-Show frames between @var{low_frame} and @var{high_frame}:
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--stack-list-frames 3 5
-^done,stack=
-[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
-frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@},
-frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@}]
-(@value{GDBP})
+ -symbol-info-symbol @var{addr}
@end smallexample
-Show a single frame:
+Describe what symbol is at location @var{addr}.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info symbol}.
+
+@subsubheading Example
+N.A.
+
+
+@subheading The @code{-symbol-list-functions} Command
+@findex -symbol-list-functions
+
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--stack-list-frames 3 3
-^done,stack=
-[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/devo/myproject/recursive2.c",line="14"@}]
-(@value{GDBP})
+ -symbol-list-functions
@end smallexample
+List the functions in the executable.
+
+@subsubheading @value{GDBN} Command
-@subheading The @code{-stack-list-locals} Command
-@findex -stack-list-locals
+@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
+@samp{gdb_search} in @code{gdbtk}.
+
+@subsubheading Example
+N.A.
+
+
+@subheading The @code{-symbol-list-lines} Command
+@findex -symbol-list-lines
@subsubheading Synopsis
@smallexample
- -stack-list-locals @var{print-values}
+ -symbol-list-lines @var{filename}
@end smallexample
-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.
+Print the list of lines that contain code and their associated program
+addresses for the given source filename. The entries are sorted in
+ascending PC order.
@subsubheading @value{GDBN} Command
-@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
+There is no corresponding @value{GDBN} command.
@subsubheading Example
-
@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})
+(gdb)
+-symbol-list-lines basics.c
+^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}]
+(gdb)
@end smallexample
-@subheading The @code{-stack-select-frame} Command
-@findex -stack-select-frame
+@subheading The @code{-symbol-list-types} Command
+@findex -symbol-list-types
@subsubheading Synopsis
@smallexample
- -stack-select-frame @var{framenum}
+ -symbol-list-types
@end smallexample
-Change the selected frame. Select a different frame @var{framenum} on
-the stack.
+List all the type names.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
-@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
+The corresponding commands are @samp{info types} in @value{GDBN},
+@samp{gdb_search} in @code{gdbtk}.
@subsubheading Example
+N.A.
+
+
+@subheading The @code{-symbol-list-variables} Command
+@findex -symbol-list-variables
+
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--stack-select-frame 2
-^done
-(@value{GDBP})
+ -symbol-list-variables
@end smallexample
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Symbol Query
-@section @sc{gdb/mi} Symbol Query Commands
+List all the global and static variable names.
+
+@subsubheading @value{GDBN} Command
+@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
-@subheading The @code{-symbol-info-address} Command
-@findex -symbol-info-address
+@subsubheading Example
+N.A.
+
+
+@subheading The @code{-symbol-locate} Command
+@findex -symbol-locate
@subsubheading Synopsis
@smallexample
- -symbol-info-address @var{symbol}
+ -symbol-locate
@end smallexample
-Describe where @var{symbol} is stored.
-
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{info address}.
+@samp{gdb_loc} in @code{gdbtk}.
@subsubheading Example
N.A.
-@subheading The @code{-symbol-info-file} Command
-@findex -symbol-info-file
+@subheading The @code{-symbol-type} Command
+@findex -symbol-type
@subsubheading Synopsis
@smallexample
- -symbol-info-file
+ -symbol-type @var{variable}
@end smallexample
-Show the file for the symbol.
+Show type of @var{variable}.
@subsubheading @value{GDBN} Command
-There's no equivalent @value{GDBN} command. @code{gdbtk} has
-@samp{gdb_find_file}.
+The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
+@samp{gdb_obj_variable}.
@subsubheading Example
N.A.
-@subheading The @code{-symbol-info-function} Command
-@findex -symbol-info-function
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI File Commands
+@section @sc{gdb/mi} File Commands
+
+This section describes the GDB/MI commands to specify executable file names
+and to read in and obtain symbol table information.
+
+@subheading The @code{-file-exec-and-symbols} Command
+@findex -file-exec-and-symbols
@subsubheading Synopsis
@smallexample
- -symbol-info-function
+ -file-exec-and-symbols @var{file}
@end smallexample
-Show which function the symbol lives in.
+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
-@samp{gdb_get_function} in @code{gdbtk}.
+The corresponding @value{GDBN} command is @samp{file}.
@subsubheading Example
-N.A.
+@smallexample
+(gdb)
+-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
+^done
+(gdb)
+@end smallexample
-@subheading The @code{-symbol-info-line} Command
-@findex -symbol-info-line
+
+@subheading The @code{-file-exec-file} Command
+@findex -file-exec-file
@subsubheading Synopsis
@smallexample
- -symbol-info-line
+ -file-exec-file @var{file}
@end smallexample
-Show the core addresses of the code for a source line.
+Specify the executable file to be debugged. Unlike
+@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
+from this file. If used without argument, @value{GDBN} clears the information
+about the executable file. No output is produced, except a completion
+notification.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{info line}.
-@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
+The corresponding @value{GDBN} command is @samp{exec-file}.
@subsubheading Example
-N.A.
+@smallexample
+(gdb)
+-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
+^done
+(gdb)
+@end smallexample
-@subheading The @code{-symbol-info-symbol} Command
-@findex -symbol-info-symbol
+
+@subheading The @code{-file-list-exec-sections} Command
+@findex -file-list-exec-sections
@subsubheading Synopsis
@smallexample
- -symbol-info-symbol @var{addr}
+ -file-list-exec-sections
@end smallexample
-Describe what symbol is at location @var{addr}.
+List the sections of the current executable file.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{info symbol}.
+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{-symbol-list-functions} Command
-@findex -symbol-list-functions
+@subheading The @code{-file-list-exec-source-file} Command
+@findex -file-list-exec-source-file
@subsubheading Synopsis
@smallexample
- -symbol-list-functions
+ -file-list-exec-source-file
@end smallexample
-List the functions in the executable.
+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
-@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
-@samp{gdb_search} in @code{gdbtk}.
+The @value{GDBN} equivalent is @samp{info source}
@subsubheading Example
-N.A.
+
+@smallexample
+(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{-symbol-list-lines} Command
-@findex -symbol-list-lines
+@subheading The @code{-file-list-exec-source-files} Command
+@findex -file-list-exec-source-files
@subsubheading Synopsis
@smallexample
- -symbol-list-lines @var{filename}
+ -file-list-exec-source-files
@end smallexample
-Print the list of lines that contain code and their associated program
-addresses for the given source filename. The entries are sorted in
-ascending PC order.
+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 is no corresponding @value{GDBN} command.
+The @value{GDBN} equivalent is @samp{info sources}.
+@code{gdbtk} has an analogous command @samp{gdb_listfiles}.
@subsubheading Example
@smallexample
-(@value{GDBP})
--symbol-list-lines basics.c
-^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}]
-(@value{GDBP})
+(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{-symbol-list-types} Command
-@findex -symbol-list-types
+@subheading The @code{-file-list-shared-libraries} Command
+@findex -file-list-shared-libraries
@subsubheading Synopsis
@smallexample
- -symbol-list-types
+ -file-list-shared-libraries
@end smallexample
-List all the type names.
+List the shared libraries in the program.
@subsubheading @value{GDBN} Command
-The corresponding commands are @samp{info types} in @value{GDBN},
-@samp{gdb_search} in @code{gdbtk}.
+The corresponding @value{GDBN} command is @samp{info shared}.
@subsubheading Example
N.A.
-@subheading The @code{-symbol-list-variables} Command
-@findex -symbol-list-variables
+@subheading The @code{-file-list-symbol-files} Command
+@findex -file-list-symbol-files
@subsubheading Synopsis
@smallexample
- -symbol-list-variables
+ -file-list-symbol-files
@end smallexample
-List all the global and static variable names.
+List symbol files.
@subsubheading @value{GDBN} Command
-@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
+The corresponding @value{GDBN} command is @samp{info file} (part of it).
@subsubheading Example
N.A.
-@subheading The @code{-symbol-locate} Command
-@findex -symbol-locate
+@subheading The @code{-file-symbol-file} Command
+@findex -file-symbol-file
@subsubheading Synopsis
@smallexample
- -symbol-locate
+ -file-symbol-file @var{file}
@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.
+
@subsubheading @value{GDBN} Command
-@samp{gdb_loc} in @code{gdbtk}.
+The corresponding @value{GDBN} command is @samp{symbol-file}.
@subsubheading Example
-N.A.
+@smallexample
+(gdb)
+-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
+^done
+(gdb)
+@end smallexample
-@subheading The @code{-symbol-type} Command
-@findex -symbol-type
+@ignore
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Memory Overlay Commands
+@section @sc{gdb/mi} Memory Overlay Commands
-@subsubheading Synopsis
+The memory overlay commands are not implemented.
-@smallexample
- -symbol-type @var{variable}
-@end smallexample
+@c @subheading -overlay-auto
-Show type of @var{variable}.
+@c @subheading -overlay-list-mapping-state
-@subsubheading @value{GDBN} Command
+@c @subheading -overlay-list-overlays
-The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
-@samp{gdb_obj_variable}.
+@c @subheading -overlay-map
-@subsubheading Example
-N.A.
+@c @subheading -overlay-off
+
+@c @subheading -overlay-on
+
+@c @subheading -overlay-unmap
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Signal Handling Commands
+@section @sc{gdb/mi} Signal Handling Commands
+
+Signal handling commands are not implemented.
+
+@c @subheading -signal-handle
+
+@c @subheading -signal-list-handle-actions
+
+@c @subheading -signal-list-signal-types
+@end ignore
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-target-detach
@end smallexample
-Disconnect from the remote target. There's no output.
+Detach from the remote target which normally resumes its execution.
+There's no output.
@subsubheading @value{GDBN} command
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-target-detach
^done
-(@value{GDBP})
+(gdb)
@end smallexample
@subsubheading Synopsis
-@example
+@smallexample
-target-disconnect
-@end example
+@end smallexample
-Disconnect from the remote target. There's no output.
+Disconnect from the remote target. There's no output and the target is
+generally not resumed.
@subsubheading @value{GDBN} command
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-target-disconnect
^done
-(@value{GDBP})
+(gdb)
@end smallexample
have been broken down so that they can fit onto a page.
@smallexample
-(@value{GDBP})
+(gdb)
-target-download
+download,@{section=".text",section-size="6668",total-size="9880"@}
+download,@{section=".text",section-sent="512",section-size="6668",
total-sent="6144",total-size="9880"@}
+download,@{section=".text",section-sent="6656",section-size="6668",
total-sent="6656",total-size="9880"@}
-+download,@{section=".init",section-size="28",total-size="9880"@}
-+download,@{section=".fini",section-size="28",total-size="9880"@}
-+download,@{section=".data",section-size="3156",total-size="9880"@}
-+download,@{section=".data",section-sent="512",section-size="3156",
-total-sent="7236",total-size="9880"@}
-+download,@{section=".data",section-sent="1024",section-size="3156",
-total-sent="7748",total-size="9880"@}
-+download,@{section=".data",section-sent="1536",section-size="3156",
-total-sent="8260",total-size="9880"@}
-+download,@{section=".data",section-sent="2048",section-size="3156",
-total-sent="8772",total-size="9880"@}
-+download,@{section=".data",section-sent="2560",section-size="3156",
-total-sent="9284",total-size="9880"@}
-+download,@{section=".data",section-sent="3072",section-size="3156",
-total-sent="9796",total-size="9880"@}
-^done,address="0x10004",load-size="9880",transfer-rate="6586",
-write-rate="429"
-(@value{GDBP})
-@end smallexample
-
-
-@subheading The @code{-target-exec-status} Command
-@findex -target-exec-status
-
-@subsubheading Synopsis
-
-@smallexample
- -target-exec-status
-@end smallexample
-
-Provide information on the state of the target (whether it is running or
-not, for instance).
-
-@subsubheading @value{GDBN} Command
-
-There's no equivalent @value{GDBN} command.
-
-@subsubheading Example
-N.A.
-
-
-@subheading The @code{-target-list-available-targets} Command
-@findex -target-list-available-targets
-
-@subsubheading Synopsis
-
-@smallexample
- -target-list-available-targets
-@end smallexample
-
-List the possible targets to connect to.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{help target}.
-
-@subsubheading Example
-N.A.
-
-
-@subheading The @code{-target-list-current-targets} Command
-@findex -target-list-current-targets
-
-@subsubheading Synopsis
-
-@smallexample
- -target-list-current-targets
-@end smallexample
-
-Describe the current target.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding information is printed by @samp{info file} (among
-other things).
-
-@subsubheading Example
-N.A.
-
-
-@subheading The @code{-target-list-parameters} Command
-@findex -target-list-parameters
-
-@subsubheading Synopsis
-
-@smallexample
- -target-list-parameters
-@end smallexample
-
-@c ????
-
-@subsubheading @value{GDBN} Command
-
-No equivalent.
-
-@subsubheading Example
-N.A.
-
-
-@subheading The @code{-target-select} Command
-@findex -target-select
-
-@subsubheading Synopsis
-
-@smallexample
- -target-select @var{type} @var{parameters @dots{}}
-@end smallexample
-
-Connect @value{GDBN} to the remote target. This command takes two args:
-
-@table @samp
-@item @var{type}
-The type of target, for instance @samp{async}, @samp{remote}, etc.
-@item @var{parameters}
-Device names, host names and the like. @xref{Target Commands, ,
-Commands for managing targets}, for more details.
-@end table
-
-The output is a connection notification, followed by the address at
-which the target program is, in the following form:
-
-@smallexample
-^connected,addr="@var{address}",func="@var{function name}",
- args=[@var{arg list}]
-@end smallexample
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{target}.
-
-@subsubheading Example
-
-@smallexample
-(@value{GDBP})
--target-select async /dev/ttya
-^connected,addr="0xfe00a300",func="??",args=[]
-(@value{GDBP})
++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
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Thread Commands
-@section @sc{gdb/mi} Thread Commands
-
-@subheading The @code{-thread-info} Command
-@findex -thread-info
+@subheading The @code{-target-exec-status} Command
+@findex -target-exec-status
@subsubheading Synopsis
@smallexample
- -thread-info
+ -target-exec-status
@end smallexample
-@subsubheading @value{GDBN} command
+Provide information on the state of the target (whether it is running or
+not, for instance).
-No equivalent.
+@subsubheading @value{GDBN} Command
+
+There's no equivalent @value{GDBN} command.
@subsubheading Example
N.A.
-@subheading The @code{-thread-list-all-threads} Command
-@findex -thread-list-all-threads
+@subheading The @code{-target-list-available-targets} Command
+@findex -target-list-available-targets
@subsubheading Synopsis
@smallexample
- -thread-list-all-threads
+ -target-list-available-targets
@end smallexample
+List the possible targets to connect to.
+
@subsubheading @value{GDBN} Command
-The equivalent @value{GDBN} command is @samp{info threads}.
+The corresponding @value{GDBN} command is @samp{help target}.
@subsubheading Example
N.A.
-@subheading The @code{-thread-list-ids} Command
-@findex -thread-list-ids
+@subheading The @code{-target-list-current-targets} Command
+@findex -target-list-current-targets
@subsubheading Synopsis
@smallexample
- -thread-list-ids
+ -target-list-current-targets
@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.
+Describe the current target.
@subsubheading @value{GDBN} Command
-Part of @samp{info threads} supplies the same information.
+The corresponding information is printed by @samp{info file} (among
+other things).
@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-list-parameters} Command
+@findex -target-list-parameters
@subsubheading Synopsis
@smallexample
- -thread-select @var{threadnum}
+ -target-list-parameters
@end smallexample
-Make @var{threadnum} the current thread. It prints the number of the new
-current thread, and the topmost frame for that thread.
+@c ????
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{thread}.
+No equivalent.
@subsubheading Example
+N.A.
-@smallexample
-(@value{GDBP})
--exec-next
-^running
-(@value{GDBP})
-*stopped,reason="end-stepping-range",thread-id="2",line="187",
-file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
-(@value{GDBP})
--thread-list-ids
-^done,
-thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
-number-of-threads="3"
-(@value{GDBP})
--thread-select 3
-^done,new-thread-id="3",
-frame=@{level="0",func="vprintf",
-args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
-@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
-(@value{GDBP})
-@end smallexample
-
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Tracepoint Commands
-@section @sc{gdb/mi} Tracepoint Commands
-
-The tracepoint commands are not yet implemented.
-
-@c @subheading -trace-actions
-
-@c @subheading -trace-delete
-
-@c @subheading -trace-disable
-
-@c @subheading -trace-dump
-
-@c @subheading -trace-enable
-
-@c @subheading -trace-exists
-
-@c @subheading -trace-find
-
-@c @subheading -trace-frame-number
-
-@c @subheading -trace-info
-
-@c @subheading -trace-insert
-
-@c @subheading -trace-list
-
-@c @subheading -trace-pass-count
-
-@c @subheading -trace-save
-
-@c @subheading -trace-start
-
-@c @subheading -trace-stop
-
-
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Variable Objects
-@section @sc{gdb/mi} Variable Objects
-
-
-@subheading Motivation for Variable Objects in @sc{gdb/mi}
-
-For the implementation of a variable debugger window (locals, watched
-expressions, etc.), we are proposing the adaptation of the existing code
-used by @code{Insight}.
-
-The two main reasons for that are:
-
-@enumerate 1
-@item
-It has been proven in practice (it is already on its second generation).
-
-@item
-It will shorten development time (needless to say how important it is
-now).
-@end enumerate
-
-The original interface was designed to be used by Tcl code, so it was
-slightly changed so it could be used through @sc{gdb/mi}. This section
-describes the @sc{gdb/mi} operations that will be available and gives some
-hints about their use.
-
-@emph{Note}: In addition to the set of operations described here, we
-expect the @sc{gui} implementation of a variable window to require, at
-least, the following operations:
-
-@itemize @bullet
-@item @code{-gdb-show} @code{output-radix}
-@item @code{-stack-list-arguments}
-@item @code{-stack-list-locals}
-@item @code{-stack-select-frame}
-@end itemize
-
-@subheading Introduction to Variable Objects in @sc{gdb/mi}
-
-@cindex variable objects in @sc{gdb/mi}
-The basic idea behind variable objects is the creation of a named object
-to represent a variable, an expression, a memory location or even a CPU
-register. For each object created, a set of operations is available for
-examining or changing its properties.
-
-Furthermore, complex data types, such as C structures, are represented
-in a tree format. For instance, the @code{struct} type variable is the
-root and the children will represent the struct members. If a child
-is itself of a complex type, it will also have children of its own.
-Appropriate language differences are handled for C, C@t{++} and Java.
-
-When returning the actual values of the objects, this facility allows
-for the individual selection of the display format used in the result
-creation. It can be chosen among: binary, decimal, hexadecimal, octal
-and natural. Natural refers to a default format automatically
-chosen based on the variable type (like decimal for an @code{int}, hex
-for pointers, etc.).
-
-The following is the complete set of @sc{gdb/mi} operations defined to
-access this functionality:
-
-@multitable @columnfractions .4 .6
-@item @strong{Operation}
-@tab @strong{Description}
-
-@item @code{-var-create}
-@tab create a variable object
-@item @code{-var-delete}
-@tab delete the variable object and its children
-@item @code{-var-set-format}
-@tab set the display format of this variable
-@item @code{-var-show-format}
-@tab show the display format of this variable
-@item @code{-var-info-num-children}
-@tab tells how many children this object has
-@item @code{-var-list-children}
-@tab return a list of the object's children
-@item @code{-var-info-type}
-@tab show the type of this variable object
-@item @code{-var-info-expression}
-@tab print what this variable object represents
-@item @code{-var-show-attributes}
-@tab is this variable editable? does it exist here?
-@item @code{-var-evaluate-expression}
-@tab get the value of this variable
-@item @code{-var-assign}
-@tab set the value of this variable
-@item @code{-var-update}
-@tab update the variable and its children
-@end multitable
-
-In the next subsection we describe each operation in detail and suggest
-how it can be used.
-
-@subheading Description And Use of Operations on Variable Objects
-
-@subheading The @code{-var-create} Command
-@findex -var-create
-
-@subsubheading Synopsis
-
-@smallexample
- -var-create @{@var{name} | "-"@}
- @{@var{frame-addr} | "*"@} @var{expression}
-@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.
-@var{expression} is any expression valid on the current language set (must not
-begin with a @samp{*}), or one of the following:
+@subheading The @code{-target-select} Command
+@findex -target-select
-@itemize @bullet
-@item
-@samp{*@var{addr}}, where @var{addr} is the address of a memory cell
+@subsubheading Synopsis
-@item
-@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
+@smallexample
+ -target-select @var{type} @var{parameters @dots{}}
+@end smallexample
-@item
-@samp{$@var{regname}} --- a CPU register name
-@end itemize
+Connect @value{GDBN} to the remote target. This command takes two args:
-@subsubheading Result
+@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
-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:
+The output is a connection notification, followed by the address at
+which the target program is, in the following form:
@smallexample
- name="@var{name}",numchild="N",type="@var{type}"
+^connected,addr="@var{address}",func="@var{function name}",
+ args=[@var{arg list}]
@end smallexample
+@subsubheading @value{GDBN} Command
-@subheading The @code{-var-delete} Command
-@findex -var-delete
+The corresponding @value{GDBN} command is @samp{target}.
-@subsubheading Synopsis
+@subsubheading Example
@smallexample
- -var-delete @var{name}
+(gdb)
+-target-select async /dev/ttya
+^connected,addr="0xfe00a300",func="??",args=[]
+(gdb)
@end smallexample
-Deletes a previously created variable object and all of its children.
-
-Returns an error if the object @var{name} is not found.
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Miscellaneous Commands
+@section Miscellaneous @sc{gdb/mi} Commands
+@c @subheading -gdb-complete
-@subheading The @code{-var-set-format} Command
-@findex -var-set-format
+@subheading The @code{-gdb-exit} Command
+@findex -gdb-exit
@subsubheading Synopsis
@smallexample
- -var-set-format @var{name} @var{format-spec}
+ -gdb-exit
@end smallexample
-Sets the output format for the value of the object @var{name} to be
-@var{format-spec}.
+Exit @value{GDBN} immediately.
-The syntax for the @var{format-spec} is as follows:
+@subsubheading @value{GDBN} Command
+
+Approximately corresponds to @samp{quit}.
+
+@subsubheading Example
@smallexample
- @var{format-spec} @expansion{}
- @{binary | decimal | hexadecimal | octal | natural@}
+(gdb)
+-gdb-exit
+^exit
@end smallexample
-@subheading The @code{-var-show-format} Command
-@findex -var-show-format
+@subheading The @code{-exec-abort} Command
+@findex -exec-abort
@subsubheading Synopsis
@smallexample
- -var-show-format @var{name}
+ -exec-abort
@end smallexample
-Returns the format used to display the value of the object @var{name}.
+Kill the inferior running program.
-@smallexample
- @var{format} @expansion{}
- @var{format-spec}
-@end smallexample
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{kill}.
+@subsubheading Example
+N.A.
-@subheading The @code{-var-info-num-children} Command
-@findex -var-info-num-children
+
+@subheading The @code{-gdb-set} Command
+@findex -gdb-set
@subsubheading Synopsis
@smallexample
- -var-info-num-children @var{name}
+ -gdb-set
@end smallexample
-Returns the number of children of a variable object @var{name}:
+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
- numchild=@var{n}
+(gdb)
+-gdb-set $foo=3
+^done
+(gdb)
@end smallexample
-@subheading The @code{-var-list-children} Command
-@findex -var-list-children
+@subheading The @code{-gdb-show} Command
+@findex -gdb-show
@subsubheading Synopsis
@smallexample
- -var-list-children [@var{print-values}] @var{name}
+ -gdb-show
@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.
+Show the current value of a @value{GDBN} variable.
+
+@subsubheading @value{GDBN} command
+
+The corresponding @value{GDBN} command is @samp{show}.
@subsubheading Example
@smallexample
-(@value{GDBP})
- -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-show annotate
+^done,value="0"
+(gdb)
@end smallexample
+@c @subheading -gdb-source
-@subheading The @code{-var-info-type} Command
-@findex -var-info-type
+
+@subheading The @code{-gdb-version} Command
+@findex -gdb-version
@subsubheading Synopsis
@smallexample
- -var-info-type @var{name}
+ -gdb-version
@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:
-
-@smallexample
- type=@var{typename}
-@end smallexample
+Show version information for @value{GDBN}. Used mostly in testing.
+@subsubheading @value{GDBN} Command
-@subheading The @code{-var-info-expression} Command
-@findex -var-info-expression
+The @value{GDBN} equivalent is @samp{show version}. @value{GDBN} by
+default shows this information when you start an interactive session.
-@subsubheading Synopsis
+@subsubheading Example
+@c This example modifies the actual output from GDB to avoid overfull
+@c box in TeX.
@smallexample
- -var-info-expression @var{name}
+(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
-Returns what is represented by the variable object @var{name}:
+@subheading The @code{-interpreter-exec} Command
+@findex -interpreter-exec
+
+@subheading Synopsis
@smallexample
- lang=@var{lang-spec},exp=@var{expression}
+-interpreter-exec @var{interpreter} @var{command}
@end smallexample
+@anchor{-interpreter-exec}
-@noindent
-where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
+Execute the specified @var{command} in the given @var{interpreter}.
-@subheading The @code{-var-show-attributes} Command
-@findex -var-show-attributes
+@subheading @value{GDBN} Command
-@subsubheading Synopsis
+The corresponding @value{GDBN} command is @samp{interpreter-exec}.
+
+@subheading Example
@smallexample
- -var-show-attributes @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
-List attributes of the specified variable object @var{name}:
+@subheading The @code{-inferior-tty-set} Command
+@findex -inferior-tty-set
+
+@subheading Synopsis
@smallexample
- status=@var{attr} [ ( ,@var{attr} )* ]
+-inferior-tty-set /dev/pts/1
@end smallexample
-@noindent
-where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
-
-@subheading The @code{-var-evaluate-expression} Command
-@findex -var-evaluate-expression
+Set terminal for future runs of the program being debugged.
-@subsubheading Synopsis
+@subheading @value{GDBN} Command
-@smallexample
- -var-evaluate-expression @var{name}
-@end smallexample
+The corresponding @value{GDBN} command is @samp{set inferior-tty} /dev/pts/1.
-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 Example
@smallexample
- value=@var{value}
+(gdb)
+-inferior-tty-set /dev/pts/1
+^done
+(gdb)
@end smallexample
-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
+@subheading The @code{-inferior-tty-show} Command
+@findex -inferior-tty-show
-@subsubheading Synopsis
+@subheading Synopsis
@smallexample
- -var-assign @var{name} @var{expression}
+-inferior-tty-show
@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.
+Show terminal for future runs of program being debugged.
-@subsubheading Example
+@subheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{show inferior-tty}.
+
+@subheading Example
@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})
+(gdb)
+-inferior-tty-set /dev/pts/1
+^done
+(gdb)
+-inferior-tty-show
+^done,inferior_tty_terminal="/dev/pts/1"
+(gdb)
@end smallexample
-@subheading The @code{-var-update} Command
-@findex -var-update
+@subheading The @code{-enable-timings} Command
+@findex -enable-timings
-@subsubheading Synopsis
+@subheading Synopsis
@smallexample
- -var-update [@var{print-values}] @{@var{name} | "*"@}
+-enable-timings [yes | no]
@end smallexample
-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}).
+Toggle the printing of the wallclock, user and system times for an MI
+command as a field in its output. This command is to help frontend
+developers optimize the performance of their code. No argument is
+equivalent to @samp{yes}.
-@subsubheading Example
+@subheading @value{GDBN} Command
-@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})
+No equivalent.
+
+@subheading Example
+
+@smallexample
+(gdb)
+-enable-timings
+^done
+(gdb)
+-break-insert main
+^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
+addr="0x080484ed",func="main",file="myprog.c",
+fullname="/home/nickrob/myprog.c",line="73",times="0"@},
+time=@{wallclock="0.05185",user="0.00800",system="0.00000"@}
+(gdb)
+-enable-timings no
+^done
+(gdb)
+-exec-run
+^running
+(gdb)
+*stopped,reason="breakpoint-hit",bkptno="1",thread-id="0",
+frame=@{addr="0x080484ed",func="main",args=[@{name="argc",value="1"@},
+@{name="argv",value="0xbfb60364"@}],file="myprog.c",
+fullname="/home/nickrob/myprog.c",line="73"@}
+(gdb)
@end smallexample
@node Annotations
similar programs which want to interact with @value{GDBN} at a
relatively high level.
-The annotation mechanism has largely been superseeded by @sc{gdb/mi}
+The annotation mechanism has largely been superseded by @sc{gdb/mi}
(@pxref{GDB/MI}).
@ignore
@option{--annotate} command line option (@pxref{Mode Options}), controls
how much information @value{GDBN} prints together with its prompt,
values of expressions, source lines, and other types of output. Level 0
-is for no anntations, level 1 is for use when @value{GDBN} is run as a
+is for no annotations, level 1 is for use when @value{GDBN} is run as a
subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable
for programs that control @value{GDBN}, and level 2 annotations have
been made obsolete (@pxref{Limitations, , Limitations of the Annotation
The input types are
@table @code
-@findex pre-prompt
-@findex prompt
-@findex post-prompt
+@findex pre-prompt annotation
+@findex prompt annotation
+@findex post-prompt annotation
@item prompt
When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
-@findex pre-commands
-@findex commands
-@findex post-commands
+@findex pre-commands annotation
+@findex commands annotation
+@findex post-commands annotation
@item commands
When @value{GDBN} prompts for a set of commands, like in the @code{commands}
command. The annotations are repeated for each command which is input.
-@findex pre-overload-choice
-@findex overload-choice
-@findex post-overload-choice
+@findex pre-overload-choice annotation
+@findex overload-choice annotation
+@findex post-overload-choice annotation
@item overload-choice
When @value{GDBN} wants the user to select between various overloaded functions.
-@findex pre-query
-@findex query
-@findex post-query
+@findex pre-query annotation
+@findex query annotation
+@findex post-query annotation
@item query
When @value{GDBN} wants the user to confirm a potentially dangerous operation.
-@findex pre-prompt-for-continue
-@findex prompt-for-continue
-@findex post-prompt-for-continue
+@findex pre-prompt-for-continue annotation
+@findex prompt-for-continue annotation
+@findex post-prompt-for-continue annotation
@item prompt-for-continue
When @value{GDBN} is asking the user to press return to continue. Note: Don't
expect this to work well; instead use @code{set height 0} to disable
@section Errors
@cindex annotations for errors, warnings and interrupts
-@findex quit
+@findex quit annotation
@smallexample
^Z^Zquit
@end smallexample
This annotation occurs right before @value{GDBN} responds to an interrupt.
-@findex error
+@findex error annotation
@smallexample
^Z^Zerror
@end smallexample
does not necessarily mean that @value{GDBN} is immediately returning all the way
to the top level.
-@findex error-begin
+@findex error-begin annotation
A quit or error annotation may be preceded by
@smallexample
changed.
@table @code
-@findex frames-invalid
+@findex frames-invalid annotation
@item ^Z^Zframes-invalid
The frames (for example, output from the @code{backtrace} command) may
have changed.
-@findex breakpoints-invalid
+@findex breakpoints-invalid annotation
@item ^Z^Zbreakpoints-invalid
The breakpoints may have changed. For example, the user just added or
@section Running the Program
@cindex annotations for running programs
-@findex starting
-@findex stopping
+@findex starting annotation
+@findex stopping annotation
When the program starts executing due to a @value{GDBN} command such as
@code{step} or @code{continue},
annotations describe how the program stopped.
@table @code
-@findex exited
+@findex exited annotation
@item ^Z^Zexited @var{exit-status}
The program exited, and @var{exit-status} is the exit status (zero for
successful exit, otherwise nonzero).
-@findex signalled
-@findex signal-name
-@findex signal-name-end
-@findex signal-string
-@findex signal-string-end
+@findex signalled annotation
+@findex signal-name annotation
+@findex signal-name-end annotation
+@findex signal-string annotation
+@findex signal-string-end annotation
@item ^Z^Zsignalled
The program exited with a signal. After the @code{^Z^Zsignalled}, the
annotation continues:
@var{intro-text}, @var{middle-text}, and @var{end-text} are for the
user's benefit and have no particular format.
-@findex signal
+@findex signal annotation
@item ^Z^Zsignal
The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
just saying that the program received the signal, not that it was
terminated with it.
-@findex breakpoint
+@findex breakpoint annotation
@item ^Z^Zbreakpoint @var{number}
The program hit breakpoint number @var{number}.
-@findex watchpoint
+@findex watchpoint annotation
@item ^Z^Zwatchpoint @var{number}
The program hit watchpoint number @var{number}.
@end table
@section Displaying Source
@cindex annotations for source display
-@findex source
+@findex source annotation
The following annotation is used instead of displaying source code:
@smallexample
@c should add a web page ref...
In any event, we also recommend that you submit bug reports for
-@value{GDBN}. The prefered method is to submit them directly using
+@value{GDBN}. The preferred method is to submit them directly using
@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web
page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can
be used.
version number.
@item
-What compiler (and its version) was used to compile @value{GDBN}---e.g.
+What compiler (and its version) was used to compile @value{GDBN}---e.g.@:
``@value{GCC}--2.8.1''.
@item
What compiler (and its version) was used to compile the program you are
-debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
-C Compiler''. For GCC, you can say @code{gcc --version} to get this
+debugging---e.g.@: ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
+C Compiler''. For @value{NGCC}, you can say @kbd{gcc --version} to get this
information; for other compilers, see the documentation for those
compilers.
@c inc-hist.texinfo
@c Use -I with makeinfo to point to the appropriate directory,
@c environment var TEXINPUTS with TeX.
-@include rluser.texinfo
+@include rluser.texi
@include inc-hist.texinfo
directory.
If you have @TeX{} and a @sc{dvi} printer program installed, you can
-typeset and print this manual. First switch to the the @file{gdb}
+typeset and print this manual. First switch to the @file{gdb}
subdirectory of the main source directory (for example, to
@file{gdb-@value{GDBVN}/gdb}) and type:
@node Installing GDB
@appendix Installing @value{GDBN}
-@cindex configuring @value{GDBN}
@cindex installation
-@cindex configuring @value{GDBN}, and source tree subdirectories
+@menu
+* Requirements:: Requirements for building @value{GDBN}
+* Running Configure:: Invoking the @value{GDBN} @code{configure} script
+* Separate Objdir:: Compiling @value{GDBN} in another directory
+* Config Names:: Specifying names for hosts and targets
+* Configure Options:: Summary of options for configure
+@end menu
+
+@node Requirements
+@section Requirements for building @value{GDBN}
+@cindex building @value{GDBN}, requirements for
+
+Building @value{GDBN} requires various tools and packages to be available.
+Other packages will be used only if they are found.
+
+@heading Tools/packages necessary for building @value{GDBN}
+@table @asis
+@item ISO C90 compiler
+@value{GDBN} is written in ISO C90. It should be buildable with any
+working C90 compiler, e.g.@: GCC.
+
+@end table
+
+@heading Tools/packages optional for building @value{GDBN}
+@table @asis
+@item Expat
+@anchor{Expat}
+@value{GDBN} can use the Expat XML parsing library. This library may be
+included with your operating system distribution; if it is not, you
+can get the latest version from @url{http://expat.sourceforge.net}.
+The @code{configure} script will search for this library in several
+standard locations; if it is installed in an unusual path, you can
+use the @option{--with-libexpat-prefix} option to specify its location.
+
+Expat is used for remote protocol memory maps (@pxref{Memory map format})
+and for target descriptions (@pxref{Target Descriptions}).
+
+@end table
+
+@node Running Configure
+@section Invoking the @value{GDBN} @code{configure} script
+@cindex configuring @value{GDBN}
@value{GDBN} comes with a @code{configure} script that automates the process
of preparing @value{GDBN} for installation; you can then use @code{make} to
build the @code{gdb} program.
that @value{GDBN} uses the shell to start your program---some systems refuse to
let @value{GDBN} debug child processes whose programs are not readable.
-@menu
-* Separate Objdir:: Compiling @value{GDBN} in another directory
-* Config Names:: Specifying names for hosts and targets
-* Configure Options:: Summary of options for configure
-@end menu
-
@node Separate Objdir
@section Compiling @value{GDBN} in another directory
@kindex maint demangle
@item maint demangle @var{name}
-Demangle a C@t{++} or Objective-C manled @var{name}.
+Demangle a C@t{++} or Objective-C mangled @var{name}.
@kindex maint deprecate
@kindex maint undeprecate
These commands take an optional parameter @var{message-text} that is
used as the text of the error or warning message.
-Here's an example of using @code{indernal-error}:
+Here's an example of using @code{internal-error}:
@smallexample
(@value{GDBP}) @kbd{maint internal-error testing, 1, 2}
This command prints, for each object file in the program, various data
about that object file followed by the byte cache (@dfn{bcache})
statistics for the object file. The objfile data includes the number
-of minimal, partical, full, and stabs symbols, the number of types
+of minimal, partial, full, and stabs symbols, the number of types
defined by the objfile, the number of as yet unexpanded psym tables,
the number of line tables and string tables, and the amount of memory
used by the various tables. The bcache statistics include the counts,
savings, and various measures of the hash table size and chain
lengths.
+@kindex maint print target-stack
+@cindex target stack description
+@item maint print target-stack
+A @dfn{target} is an interface between the debugger and a particular
+kind of file or process. Targets can be stacked in @dfn{strata},
+so that more than one target can potentially respond to a request.
+In particular, memory accesses will walk down the stack of targets
+until they find a target that is interested in handling that particular
+address.
+
+This command prints a short description of each layer that was pushed on
+the @dfn{target stack}, starting from the top layer down to the bottom one.
+
@kindex maint print type
@cindex type chain of a data type
@item maint print type @var{expr}
* Stop Reply Packets::
* General Query Packets::
* Register Packet Format::
+* Tracepoint Packets::
+* Interrupts::
* Examples::
* File-I/O remote protocol extension::
+* Memory map format::
@end menu
@node Overview
exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
exceptions).
-Fields within the packet should be separated using @samp{,} @samp{;} or
@cindex remote protocol, field separator
+Fields within the packet should be separated using @samp{,} @samp{;} or
@samp{:}. Except where otherwise noted all numbers are represented in
@sc{hex} with leading zeros suppressed.
@samp{:} could not appear as the third character in a packet (as it
would potentially conflict with the @var{sequence-id}).
+@cindex remote protocol, binary data
+@anchor{Binary Data}
+Binary data in most packets is encoded either as two hexadecimal
+digits per byte of binary data. This allowed the traditional remote
+protocol to work over connections which were only seven-bit clean.
+Some packets designed more recently assume an eight-bit clean
+connection, and use a more efficient encoding to send and receive
+binary data.
+
+The binary data representation uses @code{7d} (@sc{ascii} @samp{@}})
+as an escape character. Any escaped byte is transmitted as the escape
+character followed by the original character XORed with @code{0x20}.
+For example, the byte @code{0x7d} would be transmitted as the two
+bytes @code{0x7d 0x5d}. The bytes @code{0x23} (@sc{ascii} @samp{#}),
+@code{0x24} (@sc{ascii} @samp{$}), and @code{0x7d} (@sc{ascii}
+@samp{@}}) must always be escaped. Responses sent by the stub
+must also escape @code{0x2a} (@sc{ascii} @samp{*}), so that it
+is not interpreted as the start of a run-length encoded sequence
+(described next).
+
Response @var{data} can be run-length encoded to save space. A @samp{*}
means that the next character is an @sc{ascii} encoding giving a repeat count
which stands for that many repetitions of the character preceding the
The error response returned for some packets includes a two character
error number. That number is not well defined.
+@cindex empty response, for unsupported packets
For any @var{command} not supported by the stub, an empty response
(@samp{$#00}) should be returned. That way it is possible to extend the
protocol. A newer @value{GDBN} can tell if a packet is supported based
Don't use this packet. Use the @samp{Z} and @samp{z} packets instead
(@pxref{insert breakpoint or watchpoint packet}).
-@item c @var{addr}
+@item c @r{[}@var{addr}@r{]}
@cindex @samp{c} packet
Continue. @var{addr} is address to resume. If @var{addr} is omitted,
resume at current address.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item C @var{sig};@var{addr}
+@item C @var{sig}@r{[};@var{addr}@r{]}
@cindex @samp{C} packet
Continue with signal @var{sig} (hex signal number). If
@samp{;@var{addr}} is omitted, resume at same address.
Reply:
@table @samp
@item @var{XX@dots{}}
-Memory contents; each byte is transmitted as a two-digit hexidecimal
+Memory contents; each byte is transmitted as a two-digit hexadecimal
number. The reply may contain fewer bytes than requested if the
server was able to read only part of the region of memory.
@item E @var{NN}
@cindex @samp{M} packet
Write @var{length} bytes of memory starting at address @var{addr}.
@var{XX@dots{}} is the data; each byte is transmitted as a two-digit
-hexidecimal number.
+hexadecimal number.
Reply:
@table @samp
@anchor{write register packet}
@cindex @samp{P} packet
Write register @var{n@dots{}} with value @var{r@dots{}}. The register
-number @var{n} is in hexidecimal, and @var{r@dots{}} contains two hex
+number @var{n} is in hexadecimal, and @var{r@dots{}} contains two hex
digits for each byte in the register (target byte order).
Reply:
The @samp{R} packet has no reply.
-@item s @var{addr}
+@item s @r{[}@var{addr}@r{]}
@cindex @samp{s} packet
Single step. @var{addr} is the address at which to resume. If
@var{addr} is omitted, resume at same address.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item S @var{sig};@var{addr}
+@item S @var{sig}@r{[};@var{addr}@r{]}
@anchor{step with signal packet}
@cindex @samp{S} packet
Step with signal. This is analogous to the @samp{C} packet, but
@item vCont?
@cindex @samp{vCont?} packet
-Request a list of actions supporetd by the @samp{vCont} packet.
+Request a list of actions supported by the @samp{vCont} packet.
Reply:
@table @samp
The @samp{vCont} packet is not supported.
@end table
+@item vFlashErase:@var{addr},@var{length}
+@cindex @samp{vFlashErase} packet
+Direct the stub to erase @var{length} bytes of flash starting at
+@var{addr}. The region may enclose any number of flash blocks, but
+its start and end must fall on block boundaries, as indicated by the
+flash block size appearing in the memory map (@pxref{Memory map
+format}). @value{GDBN} groups flash memory programming operations
+together, and sends a @samp{vFlashDone} request after each group; the
+stub is allowed to delay erase operation until the @samp{vFlashDone}
+packet is received.
+
+Reply:
+@table @samp
+@item OK
+for success
+@item E @var{NN}
+for an error
+@end table
+
+@item vFlashWrite:@var{addr}:@var{XX@dots{}}
+@cindex @samp{vFlashWrite} packet
+Direct the stub to write data to flash address @var{addr}. The data
+is passed in binary form using the same encoding as for the @samp{X}
+packet (@pxref{Binary Data}). The memory ranges specified by
+@samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must
+not overlap, and must appear in order of increasing addresses
+(although @samp{vFlashErase} packets for higher addresses may already
+have been received; the ordering is guaranteed only between
+@samp{vFlashWrite} packets). If a packet writes to an address that was
+neither erased by a preceding @samp{vFlashErase} packet nor by some other
+target-specific method, the results are unpredictable.
+
+
+Reply:
+@table @samp
+@item OK
+for success
+@item E.memtype
+for vFlashWrite addressing non-flash memory
+@item E @var{NN}
+for an error
+@end table
+
+@item vFlashDone
+@cindex @samp{vFlashDone} packet
+Indicate to the stub that flash programming operation is finished.
+The stub is permitted to delay or batch the effects of a group of
+@samp{vFlashErase} and @samp{vFlashWrite} packets until a
+@samp{vFlashDone} packet is received. The contents of the affected
+regions of flash memory are unpredictable until the @samp{vFlashDone}
+request is completed.
+
@item X @var{addr},@var{length}:@var{XX@dots{}}
+@anchor{X packet}
@cindex @samp{X} packet
Write data to memory, where the data is transmitted in binary.
@var{addr} is address, @var{length} is number of bytes,
-@samp{@var{XX}@dots{}} is binary data. The bytes @code{0x23}
-(@sc{ascii} @samp{#}), @code{0x24} (@sc{ascii} @samp{$}), and
-@code{0x7d} (@sc{ascii} @samp{@}}) are escaped using @code{0x7d}
-(@sc{ascii} @samp{@}}), and then XORed with @code{0x20}. For example,
-the byte @code{0x7d} would be transmitted as the two bytes @code{0x7d
-0x5d}.
+@samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}).
Reply:
@table @samp
receive any of the below as a reply. In the case of the @samp{C},
@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned
when the target halts. In the below the exact meaning of @dfn{signal
-number} is poorly defined. In general one of the UNIX signal
-numbering conventions is used.
+number} is defined by the header @file{include/gdb/signals.h} in the
+@value{GDBN} source code.
As in the description of request packets, we include spaces in the
reply templates for clarity; these are not part of the reply packet's
@table @samp
@item S @var{AA}
-The program received signal number @var{AA} (a two-digit hexidecimal
-number).
+The program received signal number @var{AA} (a two-digit hexadecimal
+number). This is equivalent to a @samp{T} response with no
+@var{n}:@var{r} pairs.
@item T @var{AA} @var{n1}:@var{r1};@var{n2}:@var{r2};@dots{}
@cindex @samp{T} packet reply
-The program received signal number @var{AA} (a two-digit hexidecimal
-number). Single-step and breakpoint traps are reported this way. The
-@samp{@var{n}:@var{r}} pairs give the values of important registers or
-other information:
+The program received signal number @var{AA} (a two-digit hexadecimal
+number). This is equivalent to an @samp{S} response, except that the
+@samp{@var{n}:@var{r}} pairs can carry values of important registers
+and other information directly in the stop reply packet, reducing
+round-trip latency. Single-step and breakpoint traps are reported
+this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows:
@enumerate
@item
-If @var{n} is a hexidecimal number, it is a register number, and the
+If @var{n} is a hexadecimal number, it is a register number, and the
corresponding @var{r} gives that register's value. @var{r} is a
series of bytes in target byte order, with each byte given by a
two-digit hex number.
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
Reply:
@table @samp
@item QC @var{pid}
-Where @var{pid} is an unsigned hexidecimal process id.
+Where @var{pid} is an unsigned hexadecimal process id.
@item @r{(anything else)}
Any other reply implies the old pid.
@end table
An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
@end table
-Use of this request packet is controlled by the @code{set remote
-get-thread-local-storage-address} command (@pxref{Remote
-configuration, set remote get-thread-local-storage-address}).
-
@item qL @var{startflag} @var{threadcount} @var{nextthread}
Obtain thread information from RTOS. Where: @var{startflag} (one hex
digit) is one to indicate the first query and zero to indicate a
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.
-Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
-
-@item qPart:@var{object}:read:@var{annex}:@var{offset},@var{length}
-@cindex read special object, remote request
-@cindex @samp{qPart} packet
-Read uninterpreted bytes from the target's special data area
-identified by the keyword @var{object}. Request @var{length} bytes
-starting at @var{offset} bytes into the data. The content and
-encoding of @var{annex} is specific to the object; it can supply
-additional details about what data to access.
+Don't use this packet; use the @samp{qThreadExtraInfo} query instead
+(see below).
-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.
+Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
-@table @samp
-@item qPart:auxv:read::@var{offset},@var{length}
-Access the target's @dfn{auxiliary vector}. @xref{OS Information,
-auxiliary vector}, and see @ref{Remote configuration,
-read-aux-vector-packet}. Note @var{annex} must be empty.
-@end table
+@item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{}
+@cindex pass signals to inferior, remote request
+@cindex @samp{QPassSignals} packet
+@anchor{QPassSignals}
+Each listed @var{signal} should be passed directly to the inferior process.
+Signals are numbered identically to continue packets and stop replies
+(@pxref{Stop Reply Packets}). Each @var{signal} list item should be
+strictly greater than the previous item. These signals do not need to stop
+the inferior, or be reported to @value{GDBN}. All other signals should be
+reported to @value{GDBN}. Multiple @samp{QPassSignals} packets do not
+combine; any earlier @samp{QPassSignals} list is completely replaced by the
+new list. This packet improves performance when using @samp{handle
+@var{signal} nostop noprint pass}.
Reply:
@table @samp
@item OK
-The @var{offset} in the request is at the end of the data.
-There is no more data to be read.
-
-@item @var{XX}@dots{}
-Hex encoded data bytes read.
-This may be fewer bytes than the @var{length} in the request.
-
-@item E00
-The request was malformed, or @var{annex} was invalid.
-
-@item E @var{nn}
-The offset was invalid, or there was an error encountered reading the data.
-@var{nn} is a hex-encoded @code{errno} value.
-
-@item
-An empty reply indicates the @var{object} or @var{annex} string was not
-recognized by the stub.
-@end table
-
-@item qPart:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
-@cindex write data into object, remote request
-Write uninterpreted bytes into the target's special data area
-identified by the keyword @var{object}, starting at @var{offset} bytes
-into the data. @samp{@var{data}@dots{}} is the hex-encoded data to be
-written. The content and encoding of @var{annex} is specific to the
-object; it can supply additional details about what data to access.
-
-No requests of this form are presently in use. This specification
-serves as a placeholder to document the common format that new
-specific request specifications ought to use.
-
-Reply:
-@table @samp
-@item @var{nn}
-@var{nn} (hex encoded) is the number of bytes written.
-This may be fewer bytes than supplied in the request.
-
-@item E00
-The request was malformed, or @var{annex} was invalid.
+The request succeeded.
@item E @var{nn}
-The offset was invalid, or there was an error encountered writing the data.
-@var{nn} is a hex-encoded @code{errno} value.
+An error occurred. @var{nn} are hex digits.
@item
-An empty reply indicates the @var{object} or @var{annex} string was not
-recognized by the stub, or that the object does not support writing.
+An empty reply indicates that @samp{QPassSignals} is not supported by
+the stub.
@end table
-@item qPart:@var{object}:@var{operation}:@dots{}
-Requests of this form may be added in the future. When a stub does
-not recognize the @var{object} keyword, or its support for
-@var{object} does not recognize the @var{operation} keyword, the stub
-must respond with an empty packet.
+Use of this packet is controlled by the @code{set remote pass-signals}
+command (@pxref{Remote configuration, set remote pass-signals}).
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
@item qRcmd,@var{command}
@cindex execute remote command, remote request
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
+@anchor{qSupported}
+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 Feature Name
+@tab Value Required
+@tab Default
+@tab Probe Allowed
+
+@item @samp{PacketSize}
+@tab Yes
+@tab @samp{-}
+@tab No
+
+@item @samp{qXfer:auxv:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@item @samp{qXfer:features:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@item @samp{qXfer:memory-map:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@item @samp{QPassSignals}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@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.
+
+@item qXfer:auxv:read
+The remote stub understands the @samp{qXfer:auxv:read} packet
+(@pxref{qXfer auxiliary vector read}).
+
+@item qXfer:features:read
+The remote stub understands the @samp{qXfer:features:read} packet
+(@pxref{qXfer target description read}).
+
+@item qXfer:memory-map:read
+The remote stub understands the @samp{qXfer:memory-map:read} packet
+(@pxref{qXfer memory map read}).
+
+@item QPassSignals
+The remote stub understands the @samp{QPassSignals} packet
+(@pxref{QPassSignals}).
+
+@end table
+
@item qSymbol::
@cindex symbol lookup, remote request
@cindex @samp{qSymbol} packet
(if available), until the target ceases to request them.
@end table
+@item QTDP
+@itemx QTFrame
+@xref{Tracepoint Packets}.
+
@item qThreadExtraInfo,@var{id}
@cindex thread attributes info, remote request
@cindex @samp{qThreadExtraInfo} 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
+@itemx QTro
+@itemx qTStatus
+@xref{Tracepoint Packets}.
+
+@item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length}
+@cindex read special object, remote request
+@cindex @samp{qXfer} packet
+@anchor{qXfer read}
+Read uninterpreted bytes from the target's special data area
+identified by the keyword @var{object}. Request @var{length} bytes
+starting at @var{offset} bytes into the data. The content and
+encoding of @var{annex} is specific to the object; it can supply
+additional details about what data to access.
+
+Here are the specific requests of this form defined so far. All
+@samp{qXfer:@var{object}:read:@dots{}} requests use the same reply
+formats, listed below.
+
+@table @samp
+@item qXfer:auxv:read::@var{offset},@var{length}
+@anchor{qXfer auxiliary vector read}
+Access the target's @dfn{auxiliary vector}. @xref{OS Information,
+auxiliary vector}. Note @var{annex} must be empty.
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
+@item qXfer:features:read:@var{annex}:@var{offset},@var{length}
+@anchor{qXfer target description read}
+Access the @dfn{target description}. @xref{Target Descriptions}. The
+annex specifies which XML document to access. The main description is
+always loaded from the @samp{target.xml} annex.
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
+@item qXfer:memory-map:read::@var{offset},@var{length}
+@anchor{qXfer memory map read}
+Access the target's @dfn{memory-map}. @xref{Memory map format}. The
+annex part of the generic @samp{qXfer} packet must be empty
+(@pxref{qXfer read}).
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@end table
+
+Reply:
+@table @samp
+@item m @var{data}
+Data @var{data} (@pxref{Binary Data}) has been read from the
+target. There may be more data at a higher address (although
+it is permitted to return @samp{m} even for the last valid
+block of data, as long as at least one byte of data was read).
+@var{data} may have fewer bytes than the @var{length} in the
+request.
+
+@item l @var{data}
+Data @var{data} (@pxref{Binary Data}) has been read from the target.
+There is no more data to be read. @var{data} may have fewer bytes
+than the @var{length} in the request.
+
+@item l
+The @var{offset} in the request is at the end of the data.
+There is no more data to be read.
+
+@item E00
+The request was malformed, or @var{annex} was invalid.
+
+@item E @var{nn}
+The offset was invalid, or there was an error encountered reading the data.
+@var{nn} is a hex-encoded @code{errno} value.
+
+@item
+An empty reply indicates the @var{object} string was not recognized by
+the stub, or that the object does not support reading.
+@end table
+
+@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
+@cindex write data into object, remote request
+Write uninterpreted bytes into the target's special data area
+identified by the keyword @var{object}, starting at @var{offset} bytes
+into the data. @samp{@var{data}@dots{}} is the binary-encoded data
+(@pxref{Binary Data}) to be written. The content and encoding of @var{annex}
+is specific to the object; it can supply additional details about what data
+to access.
+
+No requests of this form are presently in use. This specification
+serves as a placeholder to document the common format that new
+specific request specifications ought to use.
+
+Reply:
+@table @samp
+@item @var{nn}
+@var{nn} (hex encoded) is the number of bytes written.
+This may be fewer bytes than supplied in the request.
+
+@item E00
+The request was malformed, or @var{annex} was invalid.
+
+@item E @var{nn}
+The offset was invalid, or there was an error encountered writing the data.
+@var{nn} is a hex-encoded @code{errno} value.
+
+@item
+An empty reply indicates the @var{object} string was not
+recognized by the stub, or that the object does not support writing.
+@end table
+
+@item qXfer:@var{object}:@var{operation}:@dots{}
+Requests of this form may be added in the future. When a stub does
+not recognize the @var{object} keyword, or its support for
+@var{object} does not recognize the @var{operation} keyword, the stub
+must respond with an empty packet.
+
@end table
@node Register Packet Format
The following @code{g}/@code{G} packets have previously been defined.
In the below, some thirty-two bit registers are transferred as
sixty-four bits. Those registers should be zero/sign extended (which?)
-to fill the space allocated. Register bytes are transfered in target
-byte order. The two nibbles within a register byte are transfered
+to fill the space allocated. Register bytes are transferred in target
+byte order. The two nibbles within a register byte are transferred
most-significant - least-significant.
@table @r
@item MIPS32
-All registers are transfered as thirty-two bit quantities in the order:
+All registers are transferred as thirty-two bit quantities in the order:
32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
registers; fsr; fir; fp.
-@item MIPS64
+@item MIPS64
+
+All registers are transferred as sixty-four bit quantities (including
+thirty-two bit registers such as @code{sr}). The ordering is the same
+as @code{MIPS32}.
+
+@end table
+
+@node Tracepoint Packets
+@section Tracepoint Packets
+@cindex tracepoint packets
+@cindex packets, tracepoint
+
+Here we describe the packets @value{GDBN} uses to implement
+tracepoints (@pxref{Tracepoints}).
+
+@table @samp
+
+@item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}@r{[}-@r{]}
+Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena}
+is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then
+the tracepoint is disabled. @var{step} is the tracepoint's step
+count, and @var{pass} is its pass count. If the trailing @samp{-} is
+present, further @samp{QTDP} packets will follow to specify this
+tracepoint's actions.
+
+Replies:
+@table @samp
+@item OK
+The packet was understood and carried out.
+@item
+The packet was not recognized.
+@end table
+
+@item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]}
+Define actions to be taken when a tracepoint is hit. @var{n} and
+@var{addr} must be the same as in the initial @samp{QTDP} packet for
+this tracepoint. This packet may only be sent immediately after
+another @samp{QTDP} packet that ended with a @samp{-}. If the
+trailing @samp{-} is present, further @samp{QTDP} packets will follow,
+specifying more actions for this tracepoint.
+
+In the series of action packets for a given tracepoint, at most one
+can have an @samp{S} before its first @var{action}. If such a packet
+is sent, it and the following packets define ``while-stepping''
+actions. Any prior packets define ordinary actions --- that is, those
+taken when the tracepoint is first hit. If no action packet has an
+@samp{S}, then all the packets in the series specify ordinary
+tracepoint actions.
+
+The @samp{@var{action}@dots{}} portion of the packet is a series of
+actions, concatenated without separators. Each action has one of the
+following forms:
+
+@table @samp
+
+@item R @var{mask}
+Collect the registers whose bits are set in @var{mask}. @var{mask} is
+a hexadecimal number whose @var{i}'th bit is set if register number
+@var{i} should be collected. (The least significant bit is numbered
+zero.) Note that @var{mask} may be any number of digits long; it may
+not fit in a 32-bit word.
+
+@item M @var{basereg},@var{offset},@var{len}
+Collect @var{len} bytes of memory starting at the address in register
+number @var{basereg}, plus @var{offset}. If @var{basereg} is
+@samp{-1}, then the range has a fixed address: @var{offset} is the
+address of the lowest byte to collect. The @var{basereg},
+@var{offset}, and @var{len} parameters are all unsigned hexadecimal
+values (the @samp{-1} value for @var{basereg} is a special case).
+
+@item X @var{len},@var{expr}
+Evaluate @var{expr}, whose length is @var{len}, and collect memory as
+it directs. @var{expr} is an agent expression, as described in
+@ref{Agent Expressions}. Each byte of the expression is encoded as a
+two-digit hex number in the packet; @var{len} is the number of bytes
+in the expression (and thus one-half the number of hex digits in the
+packet).
+
+@end table
+
+Any number of actions may be packed together in a single @samp{QTDP}
+packet, as long as the packet does not exceed the maximum packet
+length (400 bytes, for many stubs). There may be only one @samp{R}
+action per tracepoint, and it must precede any @samp{M} or @samp{X}
+actions. Any registers referred to by @samp{M} and @samp{X} actions
+must be collected by a preceding @samp{R} action. (The
+``while-stepping'' actions are treated as if they were attached to a
+separate tracepoint, as far as these restrictions are concerned.)
+
+Replies:
+@table @samp
+@item OK
+The packet was understood and carried out.
+@item
+The packet was not recognized.
+@end table
+
+@item QTFrame:@var{n}
+Select the @var{n}'th tracepoint frame from the buffer, and use the
+register and memory contents recorded there to answer subsequent
+request packets from @value{GDBN}.
+
+A successful reply from the stub indicates that the stub has found the
+requested frame. The response is a series of parts, concatenated
+without separators, describing the frame we selected. Each part has
+one of the following forms:
+
+@table @samp
+@item F @var{f}
+The selected frame is number @var{n} in the trace frame buffer;
+@var{f} is a hexadecimal number. If @var{f} is @samp{-1}, then there
+was no frame matching the criteria in the request packet.
+
+@item T @var{t}
+The selected trace frame records a hit of tracepoint number @var{t};
+@var{t} is a hexadecimal number.
+
+@end table
+
+@item QTFrame:pc:@var{addr}
+Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
+currently selected frame whose PC is @var{addr};
+@var{addr} is a hexadecimal number.
+
+@item QTFrame:tdp:@var{t}
+Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
+currently selected frame that is a hit of tracepoint @var{t}; @var{t}
+is a hexadecimal number.
+
+@item QTFrame:range:@var{start}:@var{end}
+Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
+currently selected frame whose PC is between @var{start} (inclusive)
+and @var{end} (exclusive); @var{start} and @var{end} are hexadecimal
+numbers.
+
+@item QTFrame:outside:@var{start}:@var{end}
+Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first
+frame @emph{outside} the given range of addresses.
+
+@item QTStart
+Begin the tracepoint experiment. Begin collecting data from tracepoint
+hits in the trace frame buffer.
+
+@item QTStop
+End the tracepoint experiment. Stop collecting trace frames.
+
+@item QTinit
+Clear the table of tracepoints, and empty the trace frame buffer.
+
+@item QTro:@var{start1},@var{end1}:@var{start2},@var{end2}:@dots{}
+Establish the given ranges of memory as ``transparent''. The stub
+will answer requests for these ranges from memory's current contents,
+if they were not collected as part of the tracepoint hit.
+
+@value{GDBN} uses this to mark read-only regions of memory, like those
+containing program code. Since these areas never change, they should
+still have the same contents they did when the tracepoint was hit, so
+there's no reason for the stub to refuse to provide their contents.
+
+@item qTStatus
+Ask the stub if there is a trace experiment running right now.
+
+Replies:
+@table @samp
+@item T0
+There is no trace experiment running.
+@item T1
+There is a trace experiment running.
+@end table
+
+@end table
+
+
+@node Interrupts
+@section Interrupts
+@cindex interrupts (remote protocol)
+
+When a program on the remote target is running, @value{GDBN} may
+attempt to interrupt it by sending a @samp{Ctrl-C} or a @code{BREAK},
+control of which is specified via @value{GDBN}'s @samp{remotebreak}
+setting (@pxref{set remotebreak}).
-All registers are transfered as sixty-four bit quantities (including
-thirty-two bit registers such as @code{sr}). The ordering is the same
-as @code{MIPS32}.
+The precise meaning of @code{BREAK} is defined by the transport
+mechanism and may, in fact, be undefined. @value{GDBN} does
+not currently define a @code{BREAK} mechanism for any of the network
+interfaces.
-@end table
+@samp{Ctrl-C}, on the other hand, is defined and implemented for all
+transport mechanisms. It is represented by sending the single byte
+@code{0x03} without any of the usual packet overhead described in
+the Overview section (@pxref{Overview}). When a @code{0x03} byte is
+transmitted as part of a packet, it is considered to be packet data
+and does @emph{not} represent an interrupt. E.g., an @samp{X} packet
+(@pxref{X packet}), used for binary downloads, may include an unescaped
+@code{0x03} as part of its packet.
+
+Stubs are not required to recognize these interrupt mechanisms and the
+precise meaning associated with receipt of the interrupt is
+implementation defined. If the stub is successful at interrupting the
+running program, it is expected that it will send one of the Stop
+Reply Packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result
+of successfully stopping the program. Interrupts received while the
+program is stopped will be discarded.
@node Examples
@section Examples
* 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
+(@samp{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
+@subsection The @samp{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 @samp{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
@subsection Console I/O
@cindex console i/o as part of file-i/o
-By default and if not explicitely closed by the target system, the file
+By default and if not explicitly closed by the target system, the file
descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output
on the @value{GDBN} console is handled as any other file output operation
(@code{write(1, @dots{})} or @code{write(2, @dots{})}). Console input is handled
@itemize @bullet
@item
-The user presses @kbd{Ctrl-C}. The behaviour is as explained above, the
+The user types @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.
+The user presses @key{RET}. This is treated as end of input with a trailing
+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.
+The user types @kbd{Ctrl-d}. This is treated as end of input. No trailing
+character (neither newline nor @samp{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}
-> @code{F-1,9}
@end smallexample
-Example sequence of a read call, user presses Ctrl-C before syscall on
+Example sequence of a read call, user presses @kbd{Ctrl-c} before syscall on
host is called:
@smallexample
<- @code{T02}
@end smallexample
-Example sequence of a read call, user presses Ctrl-C after syscall on
+Example sequence of a read call, user presses @kbd{Ctrl-c} after syscall on
host is called:
@smallexample
<- @code{T02}
@end smallexample
+@node Memory map format
+@section Memory map format
+@cindex memory map format
+
+To be able to write into flash memory, @value{GDBN} needs to obtain a
+memory map from the target. This section describes the format of the
+memory map.
+
+The memory map is obtained using the @samp{qXfer:memory-map:read}
+(@pxref{qXfer memory map read}) packet and is an XML document that
+lists memory regions. The top-level structure of the document is shown below:
+
+@smallexample
+<?xml version="1.0"?>
+<!DOCTYPE memory-map
+ PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
+ "http://sourceware.org/gdb/gdb-memory-map.dtd">
+<memory-map>
+ region...
+</memory-map>
+@end smallexample
+
+Each region can be either:
+
+@itemize
+
+@item
+A region of RAM starting at @var{addr} and extending for @var{length}
+bytes from there:
+
+@smallexample
+<memory type="ram" start="@var{addr}" length="@var{length}"/>
+@end smallexample
+
+
+@item
+A region of read-only memory:
+
+@smallexample
+<memory type="rom" start="@var{addr}" length="@var{length}"/>
+@end smallexample
+
+
+@item
+A region of flash memory, with erasure blocks @var{blocksize}
+bytes in length:
+
+@smallexample
+<memory type="flash" start="@var{addr}" length="@var{length}">
+ <property name="blocksize">@var{blocksize}</property>
+</memory>
+@end smallexample
+
+@end itemize
+
+Regions must not overlap. @value{GDBN} assumes that areas of memory not covered
+by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X}
+packets to write to addresses in such ranges.
+
+The formal DTD for memory map format is given below:
+
+@smallexample
+<!-- ................................................... -->
+<!-- Memory Map XML DTD ................................ -->
+<!-- File: memory-map.dtd .............................. -->
+<!-- .................................... .............. -->
+<!-- memory-map.dtd -->
+<!-- memory-map: Root element with versioning -->
+<!ELEMENT memory-map (memory | property)>
+<!ATTLIST memory-map version CDATA #FIXED "1.0.0">
+<!ELEMENT memory (property)>
+<!-- memory: Specifies a memory region,
+ and its type, or device. -->
+<!ATTLIST memory type CDATA #REQUIRED
+ start CDATA #REQUIRED
+ length CDATA #REQUIRED
+ device CDATA #IMPLIED>
+<!-- property: Generic attribute tag -->
+<!ELEMENT property (#PCDATA | property)*>
+<!ATTLIST property name CDATA #REQUIRED>
+@end smallexample
+
@include agentexpr.texi
+@node Target Descriptions
+@appendix Target Descriptions
+@cindex target descriptions
+
+@strong{Warning:} target descriptions are still under active development,
+and the contents and format may change between @value{GDBN} releases.
+The format is expected to stabilize in the future.
+
+One of the challenges of using @value{GDBN} to debug embedded systems
+is that there are so many minor variants of each processor
+architecture in use. It is common practice for vendors to start with
+a standard processor core --- ARM, PowerPC, or MIPS, for example ---
+and then make changes to adapt it to a particular market niche. Some
+architectures have hundreds of variants, available from dozens of
+vendors. This leads to a number of problems:
+
+@itemize @bullet
+@item
+With so many different customized processors, it is difficult for
+the @value{GDBN} maintainers to keep up with the changes.
+@item
+Since individual variants may have short lifetimes or limited
+audiences, it may not be worthwhile to carry information about every
+variant in the @value{GDBN} source tree.
+@item
+When @value{GDBN} does support the architecture of the embedded system
+at hand, the task of finding the correct architecture name to give the
+@command{set architecture} command can be error-prone.
+@end itemize
+
+To address these problems, the @value{GDBN} remote protocol allows a
+target system to not only identify itself to @value{GDBN}, but to
+actually describe its own features. This lets @value{GDBN} support
+processor variants it has never seen before --- to the extent that the
+descriptions are accurate, and that @value{GDBN} understands them.
+
+@value{GDBN} must be compiled with Expat support to support XML target
+descriptions. @xref{Expat}.
+
+@menu
+* Retrieving Descriptions:: How descriptions are fetched from a target.
+* Target Description Format:: The contents of a target description.
+* Predefined Target Types:: Standard types available for target
+ descriptions.
+* Standard Target Features:: Features @value{GDBN} knows about.
+@end menu
+
+@node Retrieving Descriptions
+@section Retrieving Descriptions
+
+Target descriptions can be read from the target automatically, or
+specified by the user manually. The default behavior is to read the
+description from the target. @value{GDBN} retrieves it via the remote
+protocol using @samp{qXfer} requests (@pxref{General Query Packets,
+qXfer}). The @var{annex} in the @samp{qXfer} packet will be
+@samp{target.xml}. The contents of the @samp{target.xml} annex are an
+XML document, of the form described in @ref{Target Description
+Format}.
+
+Alternatively, you can specify a file to read for the target description.
+If a file is set, the target will not be queried. The commands to
+specify a file are:
+
+@table @code
+@cindex set tdesc filename
+@item set tdesc filename @var{path}
+Read the target description from @var{path}.
+
+@cindex unset tdesc filename
+@item unset tdesc filename
+Do not read the XML target description from a file. @value{GDBN}
+will use the description supplied by the current target.
+
+@cindex show tdesc filename
+@item show tdesc filename
+Show the filename to read for a target description, if any.
+@end table
+
+
+@node Target Description Format
+@section Target Description Format
+@cindex target descriptions, XML format
+
+A target description annex is an @uref{http://www.w3.org/XML/, XML}
+document which complies with the Document Type Definition provided in
+the @value{GDBN} sources in @file{gdb/features/gdb-target.dtd}. This
+means you can use generally available tools like @command{xmllint} to
+check that your feature descriptions are well-formed and valid.
+However, to help people unfamiliar with XML write descriptions for
+their targets, we also describe the grammar here.
+
+Target descriptions can identify the architecture of the remote target
+and (for some architectures) provide information about custom register
+sets. @value{GDBN} can use this information to autoconfigure for your
+target, or to warn you if you connect to an unsupported target.
+
+Here is a simple target description:
+
+@smallexample
+<target>
+ <architecture>i386:x86-64</architecture>
+</target>
+@end smallexample
+
+@noindent
+This minimal description only says that the target uses
+the x86-64 architecture.
+
+A target description has the following overall form, with [ ] marking
+optional elements and @dots{} marking repeatable elements. The elements
+are explained further below.
+
+@smallexample
+<?xml version="1.0"?>
+<!DOCTYPE target SYSTEM "gdb-target.dtd">
+<target>
+ @r{[}@var{architecture}@r{]}
+ @r{[}@var{feature}@dots{}@r{]}
+</target>
+@end smallexample
+
+@noindent
+The description is generally insensitive to whitespace and line
+breaks, under the usual common-sense rules. The XML version
+declaration and document type declaration can generally be omitted
+(@value{GDBN} does not require them), but specifying them may be
+useful for XML validation tools.
+
+@subsection Inclusion
+@cindex target descriptions, inclusion
+@cindex XInclude
+@ifnotinfo
+@cindex <xi:include>
+@end ifnotinfo
+
+It can sometimes be valuable to split a target description up into
+several different annexes, either for organizational purposes, or to
+share files between different possible target descriptions. You can
+divide a description into multiple files by replacing any element of
+the target description with an inclusion directive of the form:
+
+@smallexample
+<xi:include href="@var{document}"/>
+@end smallexample
+
+@noindent
+When @value{GDBN} encounters an element of this form, it will retrieve
+the named XML @var{document}, and replace the inclusion directive with
+the contents of that document. If the current description was read
+using @samp{qXfer}, then so will be the included document;
+@var{document} will be interpreted as the name of an annex. If the
+current description was read from a file, @value{GDBN} will look for
+@var{document} as a file in the same directory where it found the
+original description.
+
+@subsection Architecture
+@cindex <architecture>
+
+An @samp{<architecture>} element has this form:
+
+@smallexample
+ <architecture>@var{arch}</architecture>
+@end smallexample
+
+@var{arch} is an architecture name from the same selection
+accepted by @code{set architecture} (@pxref{Targets, ,Specifying a
+Debugging Target}).
+
+@subsection Features
+@cindex <feature>
+
+Each @samp{<feature>} describes some logical portion of the target
+system. Features are currently used to describe available CPU
+registers and the types of their contents. A @samp{<feature>} element
+has this form:
+
+@smallexample
+<feature name="@var{name}">
+ @r{[}@var{type}@dots{}@r{]}
+ @var{reg}@dots{}
+</feature>
+@end smallexample
+
+@noindent
+Each feature's name should be unique within the description. The name
+of a feature does not matter unless @value{GDBN} has some special
+knowledge of the contents of that feature; if it does, the feature
+should have its standard name. @xref{Standard Target Features}.
+
+@subsection Types
+
+Any register's value is a collection of bits which @value{GDBN} must
+interpret. The default interpretation is a two's complement integer,
+but other types can be requested by name in the register description.
+Some predefined types are provided by @value{GDBN} (@pxref{Predefined
+Target Types}), and the description can define additional composite types.
+
+Each type element must have an @samp{id} attribute, which gives
+a unique (within the containing @samp{<feature>}) name to the type.
+Types must be defined before they are used.
+
+@cindex <vector>
+Some targets offer vector registers, which can be treated as arrays
+of scalar elements. These types are written as @samp{<vector>} elements,
+specifying the array element type, @var{type}, and the number of elements,
+@var{count}:
+
+@smallexample
+<vector id="@var{id}" type="@var{type}" count="@var{count}"/>
+@end smallexample
+
+@cindex <union>
+If a register's value is usefully viewed in multiple ways, define it
+with a union type containing the useful representations. The
+@samp{<union>} element contains one or more @samp{<field>} elements,
+each of which has a @var{name} and a @var{type}:
+
+@smallexample
+<union id="@var{id}">
+ <field name="@var{name}" type="@var{type}"/>
+ @dots{}
+</union>
+@end smallexample
+
+@subsection Registers
+@cindex <reg>
+
+Each register is represented as an element with this form:
+
+@smallexample
+<reg name="@var{name}"
+ bitsize="@var{size}"
+ @r{[}regnum="@var{num}"@r{]}
+ @r{[}save-restore="@var{save-restore}"@r{]}
+ @r{[}type="@var{type}"@r{]}
+ @r{[}group="@var{group}"@r{]}/>
+@end smallexample
+
+@noindent
+The components are as follows:
+
+@table @var
+
+@item name
+The register's name; it must be unique within the target description.
+
+@item bitsize
+The register's size, in bits.
+
+@item regnum
+The register's number. If omitted, a register's number is one greater
+than that of the previous register (either in the current feature or in
+a preceeding feature); the first register in the target description
+defaults to zero. This register number is used to read or write
+the register; e.g.@: it is used in the remote @code{p} and @code{P}
+packets, and registers appear in the @code{g} and @code{G} packets
+in order of increasing register number.
+
+@item save-restore
+Whether the register should be preserved across inferior function
+calls; this must be either @code{yes} or @code{no}. The default is
+@code{yes}, which is appropriate for most registers except for
+some system control registers; this is not related to the target's
+ABI.
+
+@item type
+The type of the register. @var{type} may be a predefined type, a type
+defined in the current feature, or one of the special types @code{int}
+and @code{float}. @code{int} is an integer type of the correct size
+for @var{bitsize}, and @code{float} is a floating point type (in the
+architecture's normal floating point format) of the correct size for
+@var{bitsize}. The default is @code{int}.
+
+@item group
+The register group to which this register belongs. @var{group} must
+be either @code{general}, @code{float}, or @code{vector}. If no
+@var{group} is specified, @value{GDBN} will not display the register
+in @code{info registers}.
+
+@end table
+
+@node Predefined Target Types
+@section Predefined Target Types
+@cindex target descriptions, predefined types
+
+Type definitions in the self-description can build up composite types
+from basic building blocks, but can not define fundamental types. Instead,
+standard identifiers are provided by @value{GDBN} for the fundamental
+types. The currently supported types are:
+
+@table @code
+
+@item int8
+@itemx int16
+@itemx int32
+@itemx int64
+Signed integer types holding the specified number of bits.
+
+@item uint8
+@itemx uint16
+@itemx uint32
+@itemx uint64
+Unsigned integer types holding the specified number of bits.
+
+@item code_ptr
+@itemx data_ptr
+Pointers to unspecified code and data. The program counter and
+any dedicated return address register may be marked as code
+pointers; printing a code pointer converts it into a symbolic
+address. The stack pointer and any dedicated address registers
+may be marked as data pointers.
+
+@item arm_fpa_ext
+The 12-byte extended precision format used by ARM FPA registers.
+
+@end table
+
+@node Standard Target Features
+@section Standard Target Features
+@cindex target descriptions, standard features
+
+A target description must contain either no registers or all the
+target's registers. If the description contains no registers, then
+@value{GDBN} will assume a default register layout, selected based on
+the architecture. If the description contains any registers, the
+default layout will not be used; the standard registers must be
+described in the target description, in such a way that @value{GDBN}
+can recognize them.
+
+This is accomplished by giving specific names to feature elements
+which contain standard registers. @value{GDBN} will look for features
+with those names and verify that they contain the expected registers;
+if any known feature is missing required registers, or if any required
+feature is missing, @value{GDBN} will reject the target
+description. You can add additional registers to any of the
+standard features --- @value{GDBN} will display them just as if
+they were added to an unrecognized feature.
+
+This section lists the known features and their expected contents.
+Sample XML documents for these features are included in the
+@value{GDBN} source tree, in the directory @file{gdb/features}.
+
+Names recognized by @value{GDBN} should include the name of the
+company or organization which selected the name, and the overall
+architecture to which the feature applies; so e.g.@: the feature
+containing ARM core registers is named @samp{org.gnu.gdb.arm.core}.
+
+The names of registers are not case sensitive for the purpose
+of recognizing standard features, but @value{GDBN} will only display
+registers using the capitalization used in the description.
+
+@subsection ARM Features
+@cindex target descriptions, ARM features
+
+The @samp{org.gnu.gdb.arm.core} feature is required for ARM targets.
+It should contain registers @samp{r0} through @samp{r13}, @samp{sp},
+@samp{lr}, @samp{pc}, and @samp{cpsr}.
+
+The @samp{org.gnu.gdb.arm.fpa} feature is optional. If present, it
+should contain registers @samp{f0} through @samp{f7} and @samp{fps}.
+
+The @samp{org.gnu.gdb.xscale.iwmmxt} feature is optional. If present,
+it should contain at least registers @samp{wR0} through @samp{wR15} and
+@samp{wCGR0} through @samp{wCGR3}. The @samp{wCID}, @samp{wCon},
+@samp{wCSSF}, and @samp{wCASF} registers are optional.
+
@include gpl.texi
@raisesections
projects / deliverable / binutils-gdb.git / blobdiff