\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}
So that they may not regard their many labors as thankless, we
particularly thank those who shepherded @value{GDBN} through major
releases:
-Andrew Cagney (releases 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0);
+Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0);
Jim Blandy (release 4.18);
Jason Molenda (release 4.17);
Stan Shebs (release 4.14);
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.
+
@node Sample Session
@chapter A Sample @value{GDBN} Session
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
Execute @value{GDBN} commands from file @var{file}. @xref{Command
Files,, Command files}.
+@item -eval-command @var{command}
+@itemx -ex @var{command}
+@cindex @code{--eval-command}
+@cindex @code{-ex}
+Execute a single @value{GDBN} command.
+
+This option may be used multiple times to call multiple commands. It may
+also be interleaved with @samp{-command} as required.
+
+@smallexample
+@value{GDBP} -ex 'target sim' -ex 'load' \
+ -x setbreakpoints -ex 'run' a.out
+@end smallexample
+
@item -directory @var{directory}
@itemx -d @var{directory}
@cindex @code{--directory}
@cindex @code{-d}
-Add @var{directory} to the path to search for source files.
-
-@item -m
-@itemx -mapped
-@cindex @code{--mapped}
-@cindex @code{-m}
-@emph{Warning: this option depends on operating system facilities that are not
-supported on all systems.}@*
-If memory-mapped files are available on your system through the @code{mmap}
-system call, you can use this option
-to have @value{GDBN} write the symbols from your
-program into a reusable file in the current directory. If the program you are debugging is
-called @file{/tmp/fred}, the mapped symbol file is @file{/tmp/fred.syms}.
-Future @value{GDBN} debugging sessions notice the presence of this file,
-and can quickly map in symbol information from it, rather than reading
-the symbol table from the executable program.
-
-The @file{.syms} file is specific to the host machine where @value{GDBN}
-is run. It holds an exact image of the internal @value{GDBN} symbol
-table. It cannot be shared across multiple host platforms.
+Add @var{directory} to the path to search for source and script files.
@item -r
@itemx -readnow
@end table
-You typically combine the @code{-mapped} and @code{-readnow} options in
-order to build a @file{.syms} file that contains complete symbol
-information. (@xref{Files,,Commands to specify files}, for information
-on @file{.syms} files.) A simple @value{GDBN} invocation to do nothing
-but build a @file{.syms} file for future use is:
-
-@smallexample
-gdb -batch -nx -mapped -readnow programname
-@end smallexample
-
@node Mode Options
@subsection Choosing modes
@value{GDBN} control terminates) is not issued when running in batch
mode.
+@item -batch-silent
+@cindex @code{--batch-silent}
+Run in batch mode exactly like @samp{-batch}, but totally silently. All
+@value{GDBN} output to @code{stdout} is prevented (@code{stderr} is
+unaffected). This is much quieter than @samp{-silent} and would be useless
+for an interactive session.
+
+This is particularly useful when using targets that give @samp{Loading section}
+messages, for example.
+
+Note that targets that give their output via @value{GDBN}, as opposed to
+writing directly to @code{stdout}, will also be made silent.
+
+@item -return-child-result
+@cindex @code{--return-child-result}
+The return code from @value{GDBN} will be the return code from the child
+process (the process being debugged), with the following exceptions:
+
+@itemize @bullet
+@item
+@value{GDBN} exits abnormally. E.g., due to an incorrect argument or an
+internal error. In this case the exit code is the same as it would have been
+without @samp{-return-child-result}.
+@item
+The user quits with an explicit value. E.g., @samp{quit 1}.
+@item
+The child process never runs, or is not allowed to terminate, in which case
+the exit code will be -1.
+@end itemize
+
+This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent},
+when @value{GDBN} is being used as a remote program loader or simulator
+interface.
+
@item -nowindows
@itemx -nw
@cindex @code{--nowindows}
@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs
that control @value{GDBN}, and level 2 has been deprecated.
-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}).
@item --args
@item
Reads the command history recorded in the @dfn{history file}.
-@xref{History}, for more details about the command history and the
+@xref{Command History}, for more details about the command history and the
files where @value{GDBN} records it.
@end enumerate
* 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
When you use the @code{tty} command or redirect input in the @code{run}
command, only the input @emph{for your program} is affected. The input
-for @value{GDBN} still comes from your terminal.
+for @value{GDBN} still comes from your terminal. @code{tty} is an alias
+for @code{set inferior-tty}.
+
+@cindex inferior tty
+@cindex set inferior controlling terminal
+You can use the @code{show inferior-tty} command to tell @value{GDBN} to
+display the name of the terminal that will be used for future runs of your
+program.
+
+@table @code
+@item set inferior-tty /dev/ttyb
+@kindex set inferior-tty
+Set the tty for the program being debugged to /dev/ttyb.
+
+@item show inferior-tty
+@kindex show inferior-tty
+Show the current tty for the program being debugged.
+@end table
@node Attach
@section Debugging an already-running process
@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
@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
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
@cindex startup code, and backtrace
Most programs have a standard user entry point---a place where system
libraries and startup code transition into user code. For C this is
-@code{main}. When @value{GDBN} finds the entry function in a backtrace
+@code{main}@footnote{
+Note that embedded programs (the so-called ``free-standing''
+environment) are not required to have a @code{main} function as the
+entry point. They could even have multiple entry points.}.
+When @value{GDBN} finds the entry function in a backtrace
it will terminate the backtrace, to avoid tracing into highly
system-specific (and generally uninteresting) code.
On the 29k architecture, it needs three addresses: a register stack
pointer, a program counter, and a memory stack pointer.
-@c note to future updaters: this is conditioned on a flag
-@c SETUP_ARBITRARY_FRAME in the tm-*.h files. The above is up to date
-@c as of 27 Jan 1994.
@kindex up
@item up @var{n}
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 begining 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{}
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
Some architectures have more than one commonly-used set of instruction
mnemonics or other syntax.
+For programs that were dynamically linked and use shared libraries,
+instructions that call functions or branch to locations in the shared
+libraries might show a seemingly bogus location---it's actually a
+location of the relocation table. On some architectures, @value{GDBN}
+might be able to resolve these to actual function names.
+
@table @code
@kindex set disassembly-flavor
@cindex Intel disassembly flavor
@xref{C, , Debugging C++}, for more info about debug info formats
that are best suited to C@t{++} programs.
+If you ask to print an object whose contents are unknown to
+@value{GDBN}, e.g., because its data type is not completely specified
+by the debug information, @value{GDBN} will say @samp{<incomplete
+type>}. @xref{Symbols, incomplete type}, for more about this.
+
@node Arrays
@section Artificial arrays
Show whether compressed or pretty format is selected for displaying
arrays.
+@cindex print array indexes
+@item set print array-indexes
+@itemx set print array-indexes on
+Print the index of each element when displaying arrays. May be more
+convenient to locate a given element in the array or quickly find the
+index of a given element in that printed array. The default is off.
+
+@item set print array-indexes off
+Stop printing element indexes when displaying arrays.
+
+@item show print array-indexes
+Show whether the index of each element is printed when displaying
+arrays.
+
@item set print elements @var{number-of-elements}
@cindex number of array elements to print
@cindex limit on number of printed array elements
@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
+support of the @samp{qXfer:auxv:read} packet, see @ref{Remote
configuration, auxiliary vector}.
@table @code
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
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.
@subsection Fortran
@cindex Fortran-specific support in @value{GDBN}
+@value{GDBN} can be used to debug programs written in Fortran, but it
+currently supports only the features of Fortran 77 language.
+
+@cindex trailing underscore, in Fortran symbols
+Some Fortran compilers (@sc{gnu} Fortran 77 and Fortran 95 compilers
+among them) append an underscore to the names of variables and
+functions. When you debug programs compiled by those compilers, you
+will need to refer to variables and functions with a trailing
+underscore.
+
+@menu
+* Fortran Operators:: Fortran operators and expressions
+* Fortran Defaults:: Default settings for Fortran
+* Special Fortran commands:: Special @value{GDBN} commands for Fortran
+@end menu
+
+@node Fortran Operators
+@subsubsection Fortran operators and expressions
+
+@cindex Fortran operators and expressions
+
+Operators must be defined on values of specific types. For instance,
+@code{+} is defined on numbers, but not on characters or other non-
+arithmetic types. Operators are often defined on groups of types.
+
+@table @code
+@item **
+The exponentiation operator. It raises the first operand to the power
+of the second one.
+
+@item :
+The range operator. Normally used in the form of array(low:high) to
+represent a section of array.
+@end table
+
+@node Fortran Defaults
+@subsubsection Fortran Defaults
+
+@cindex Fortran Defaults
+
+Fortran symbols are usually case-insensitive, so @value{GDBN} by
+default uses case-insensitive matches for Fortran symbols. You can
+change that with the @samp{set case-insensitive} command, see
+@ref{Symbols}, for the details.
+
+@node Special Fortran commands
+@subsubsection Special Fortran commands
+
+@cindex Special Fortran commands
+
+@value{GDBN} had some commands to support Fortran specific feature,
+such as common block displaying.
+
@table @code
@cindex @code{COMMON} blocks, Fortran
@kindex info common
printed.
@end table
-Fortran symbols are usually case-insensitive, so @value{GDBN} by
-default uses case-insensitive matches for Fortran symbols. You can
-change that with the @samp{set case-insensitive} command, see
-@ref{Symbols}, for the details.
-
@node Pascal
@subsection Pascal
* 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:
As with @code{whatis}, using @code{ptype} without an argument refers to
the type of @code{$}, the last value in the value history.
+@cindex incomplete type
+Sometimes, programs use opaque data types or incomplete specifications
+of complex data structure. If the debug information included in the
+program does not allow @value{GDBN} to display a full declaration of
+the data type, it will say @samp{<incomplete type>}. For example,
+given these declarations:
+
+@smallexample
+ struct foo;
+ struct foo *fooptr;
+@end smallexample
+
+@noindent
+but no definition for @code{struct foo} itself, @value{GDBN} will say:
+
+@smallexample
+ (@value{GDBP}) ptype foo
+ $1 = <incomplete type>
+@end smallexample
+
+@noindent
+``Incomplete type'' is C terminology for data types that are not
+completely specified.
+
@kindex info types
@item info types @var{regexp}
@itemx info types
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
to run. You can change the value of this variable, for both @value{GDBN}
and your program, using the @code{path} command.
-On systems with memory-mapped files, an auxiliary file named
-@file{@var{filename}.syms} may hold symbol table information for
-@var{filename}. If so, @value{GDBN} maps in the symbol table from
-@file{@var{filename}.syms}, starting up more quickly. See the
-descriptions of the file options @samp{-mapped} and @samp{-readnow}
-(available on the command line, see @ref{File Options, , -readnow},
-and with the commands @code{file}, @code{symbol-file}, or
-@code{add-symbol-file}, described below), for more information.
-
@cindex unlinked object files
@cindex patching object files
You can load unlinked object @file{.o} files into @value{GDBN} using
@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.
@kindex readnow
@cindex reading symbols immediately
@cindex symbols, reading immediately
-@kindex mapped
-@cindex memory-mapped symbol file
-@cindex saving symbol table
-@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
-@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
+@item symbol-file @var{filename} @r{[} -readnow @r{]}
+@itemx file @var{filename} @r{[} -readnow @r{]}
You can override the @value{GDBN} two-stage strategy for reading symbol
tables by using the @samp{-readnow} option with any of the commands that
load symbol table information, if you want to be sure @value{GDBN} has the
entire symbol table available.
-If memory-mapped files are available on your system through the
-@code{mmap} system call, you can use another option, @samp{-mapped}, to
-cause @value{GDBN} to write the symbols for your program into a reusable
-file. Future @value{GDBN} debugging sessions map in symbol information
-from this auxiliary symbol file (if the program has not changed), rather
-than spending time reading the symbol table from the executable
-program. Using the @samp{-mapped} option has the same effect as
-starting @value{GDBN} with the @samp{-mapped} command-line option.
-
-You can use both options together, to make sure the auxiliary symbol
-file has all the symbol information for your program.
-
-The auxiliary symbol file for a program called @var{myprog} is called
-@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer
-than the corresponding executable), @value{GDBN} always attempts to use
-it when you debug @var{myprog}; no special options or commands are
-needed.
-
-The @file{.syms} file is specific to the host machine where you run
-@value{GDBN}. It holds an exact image of the internal @value{GDBN}
-symbol table. It cannot be shared across multiple host platforms.
-
@c FIXME: for now no mention of directories, since this seems to be in
@c flux. 13mar1992 status is that in theory GDB would look either in
@c current dir or in same dir as myprog; but issues like competing
@kindex add-symbol-file
@cindex dynamic linking
@item add-symbol-file @var{filename} @var{address}
-@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
+@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]}
@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{}
The @code{add-symbol-file} command reads additional symbol table
information from the file @var{filename}. You would use this command
@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
-You can use the @samp{-mapped} and @samp{-readnow} options just as with
-the @code{symbol-file} command, to change how @value{GDBN} manages the symbol
-table information for @var{filename}.
-
@kindex add-symbol-file-from-memory
@cindex @code{syscall DSO}
@cindex load symbols from memory
* 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}
@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
Start up @value{GDBN} as usual, using the name of the local copy of your
program as the first argument.
-@cindex serial line, @code{target remote}
-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.
+@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:
-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}:
+@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
-@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}:
+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.
+
+@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.
+
+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.)
-Now you can use all the usual commands to examine and change data and to
-step and continue the remote program.
+@end table
+
+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
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
@end table
-@node NetWare
-@section Using the @code{gdbserve.nlm} program
-
-@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}.
-
-@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
-using the standard @value{GDBN} remote serial protocol.
-
-@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.
-
-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}).
-
-@end table
-
@node Remote configuration
@section Remote configuration
@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 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
-on the remote. If set to off, @value{GDBN} sends the @samp{Strl-C}
+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
@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
+Set the use of the remote protocol's @samp{qXfer:auxv:read} (target
+auxiliary vector) 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
+request is first required). @xref{General Query Packets, qXfer}, 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.
+Show the current setting of use of the @samp{qXfer:auxv:read} request.
@item set remote symbol-lookup-packet
@cindex remote symbol lookup request
@item show remote get-thread-local-storage-address
@kindex show remote get-thread-local-storage-address
Show the current setting of @samp{qGetTLSAddr} packet usage.
+
+@item set remote supported-packets
+@kindex set remote supported-packets
+@cindex query supported packets of remote targets
+This command enables or disables the use of the @samp{qSupported}
+request packet. @xref{General Query Packets, qSupported}, for more
+details about this packet. The default is to use @samp{qSupported}.
+
+@item show remote supported-packets
+@kindex show remote supported-packets
+Show the current setting of @samp{qSupported} packet usage.
@end table
@node remote stub
This command loads symbols from a dll similarly to
add-sym command but without the need to specify a base address.
+@kindex set cygwin-exceptions
+@cindex debugging the Cygwin DLL
+@cindex Cygwin DLL, debugging
+@item set cygwin-exceptions @var{mode}
+If @var{mode} is @code{on}, @value{GDBN} will break on exceptions that
+happen inside the Cygwin DLL. If @var{mode} is @code{off},
+@value{GDBN} will delay recognition of exceptions, and may ignore some
+exceptions which seem to be caused by internal Cygwin DLL
+``bookkeeping''. This option is meant primarily for debugging the
+Cygwin DLL itself; the default value is @code{off} to avoid annoying
+@value{GDBN} users with false @code{SIGSEGV} signals.
+
+@kindex show cygwin-exceptions
+@item show cygwin-exceptions
+Displays whether @value{GDBN} will break on exceptions that happen
+inside the Cygwin DLL itself.
+
@kindex set new-console
@item set new-console @var{mode}
If @var{mode} is @code{on} the debuggee will
@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
@menu
* Prompt:: Prompt
* Editing:: Command editing
-* History:: Command history
+* Command History:: Command history
* Screen Size:: Screen size
* Numbers:: Numbers
* ABI:: Configuring the current ABI
interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
encouraged to read that chapter.
-@node History
+@node Command History
@section Command history
@cindex command history
package, to provide the history facility. @xref{Using History
Interactively}, for the detailed description of the History library.
+To issue a command to @value{GDBN} without affecting certain aspects of
+the state which is seen by users, prefix it with @samp{server }. This
+means that this command will not affect the command history, nor will it
+affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
+pressed on a line by itself.
+
+@cindex @code{server}, command prefix
+The server prefix does not affect the recording of values into the value
+history; to print a value without recording it into the value history,
+use the @code{output} command instead of the @code{print} command.
+
Here is the description of @value{GDBN} commands related to command
history.
@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
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
separated by whitespace. Arguments are accessed within the user command
-via @var{$arg0@dots{}$arg9}. A trivial example:
+via @code{$arg0@dots{}$arg9}. A trivial example:
@smallexample
define adder
print $arg0 + $arg1 + $arg2
+end
@end smallexample
@noindent
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.
+
+@smallexample
+define adder
+ if $argc == 2
+ print $arg0 + $arg1
+ end
+ if $argc == 3
+ print $arg0 + $arg1 + $arg2
+ end
+end
+@end smallexample
+
@table @code
@kindex define
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.
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
in the form of a reference manual.
Note that @sc{gdb/mi} is still under construction, so some of the
-features described below are incomplete and subject to change.
+features described below are incomplete and subject to change
+(@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}).
@unnumberedsec Notation and Terminology
@heading Dependencies
@end ignore
-@heading Acknowledgments
-
-In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
-Elena Zannoni.
-
@menu
* GDB/MI Command Syntax::
* GDB/MI Compatibility with CLI::
+* GDB/MI Development and Front Ends::
* GDB/MI Output Records::
+* GDB/MI Simple Examples::
* GDB/MI Command Description Format::
-* GDB/MI Breakpoint Table Commands::
+* GDB/MI Breakpoint Commands::
+* GDB/MI Program Context::
+* GDB/MI Thread Commands::
+* GDB/MI Program Execution::
+* GDB/MI Stack Manipulation::
+* GDB/MI Variable Objects::
* GDB/MI Data Manipulation::
-* GDB/MI Program Control::
-* GDB/MI Miscellaneous Commands::
+* GDB/MI Tracepoint Commands::
+* GDB/MI Symbol Query::
+* GDB/MI File Commands::
@ignore
* GDB/MI Kod Commands::
* GDB/MI Memory Overlay Commands::
* GDB/MI Signal Handling Commands::
@end ignore
-* GDB/MI Stack Manipulation::
-* GDB/MI Symbol Query::
* GDB/MI Target Manipulation::
-* GDB/MI Thread Commands::
-* GDB/MI Tracepoint Commands::
-* GDB/MI Variable Objects::
+* GDB/MI Miscellaneous Commands::
@end menu
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@menu
* GDB/MI Input Syntax::
* GDB/MI Output Syntax::
-* GDB/MI Simple Examples::
@end menu
@node GDB/MI Input Syntax
The output from @sc{gdb/mi} consists of zero or more out-of-band records
followed, optionally, by a single result record. This result record
is for the most recent command. The sequence of output records is
-terminated by @samp{(@value{GDBP})}.
+terminated by @samp{(gdb)}.
If an input command was prefixed with a @code{@var{token}} then the
corresponding output for that command will also be prefixed by that same
@table @code
@item @var{output} @expansion{}
-@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(@value{GDBP})" @var{nl}}
+@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
@item @var{result-record} @expansion{}
@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
@xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
details about the various output records.
-@node GDB/MI Simple Examples
-@subsection Simple Examples of @sc{gdb/mi} Interaction
-@cindex @sc{gdb/mi}, simple examples
-
-This subsection presents several simple examples of interaction using
-the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
-following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
-the output received from @sc{gdb/mi}.
-
-@subsubheading Target Stop
-@c Ummm... There is no "-stop" command. This assumes async, no?
-Here's an example of stopping the inferior process:
-
-@smallexample
--> -stop
-<- (@value{GDBP})
-@end smallexample
-
-@noindent
-and later:
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Compatibility with CLI
+@section @sc{gdb/mi} Compatibility with CLI
-@smallexample
-<- *stop,reason="stop",address="0x123",source="a.c:123"
-<- (@value{GDBP})
-@end smallexample
+@cindex compatibility, @sc{gdb/mi} and CLI
+@cindex @sc{gdb/mi}, compatibility with CLI
-@subsubheading Simple CLI Command
+For the developers convenience CLI commands can be entered directly,
+but there may be some unexpected behaviour. For example, commands
+that query the user will behave as if the user replied yes, breakpoint
+command lists are not executed and some CLI commands, such as
+@code{if}, @code{when} and @code{define}, prompt for further input with
+@samp{>}, which is not valid MI output.
-Here's an example of a simple CLI command being passed through
-@sc{gdb/mi} and on to the CLI.
+This feature may be removed at some stage in the future and it is
+recommended that front ends use the @code{-interpreter-exec} command
+(@pxref{-interpreter-exec}).
-@smallexample
--> print 1+2
-<- &"print 1+2\n"
-<- ~"$1 = 3\n"
-<- ^done
-<- (@value{GDBP})
-@end smallexample
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Development and Front Ends
+@section @sc{gdb/mi} Development and Front Ends
+@cindex @sc{gdb/mi} development
-@subsubheading Command With Side Effects
+The application which takes the MI output and presents the state of the
+program being debugged to the user is called a @dfn{front end}.
-@smallexample
--> -symbol-file xyz.exe
-<- *breakpoint,nr="3",address="0x123",source="a.c:123"
-<- (@value{GDBP})
-@end smallexample
+Although @sc{gdb/mi} is still incomplete, it is currently being used
+by a variety of front ends to @value{GDBN}. This makes it difficult
+to introduce new functionality without breaking existing usage. This
+section tries to minimize the problems by describing how the protocol
+might change.
-@subsubheading A Bad Command
+Some changes in MI need not break a carefully designed front end, and
+for these the MI version will remain unchanged. The following is a
+list of changes that may occur within one level, so front ends should
+parse MI output in a way that can handle them:
-Here's what happens if you pass a non-existent command:
+@itemize @bullet
+@item
+New MI commands may be added.
-@smallexample
--> -rubbish
-<- ^error,msg="Undefined MI command: rubbish"
-<- (@value{GDBP})
-@end smallexample
+@item
+New fields may be added to the output of any MI command.
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Compatibility with CLI
-@section @sc{gdb/mi} Compatibility with CLI
+@c The format of field's content e.g type prefix, may change so parse it
+@c at your own risk. Yes, in general?
-@cindex compatibility, @sc{gdb/mi} and CLI
-@cindex @sc{gdb/mi}, compatibility with CLI
-To help users familiar with @value{GDBN}'s existing CLI interface, @sc{gdb/mi}
-accepts existing CLI commands. As specified by the syntax, such
-commands can be directly entered into the @sc{gdb/mi} interface and @value{GDBN} will
-respond.
+@c The order of fields may change? Shouldn't really matter but it might
+@c resolve inconsistencies.
+@end itemize
-This mechanism is provided as an aid to developers of @sc{gdb/mi}
-clients and not as a reliable interface into the CLI. Since the command
-is being interpreteted in an environment that assumes @sc{gdb/mi}
-behaviour, the exact output of such commands is likely to end up being
-an un-supported hybrid of @sc{gdb/mi} and CLI output.
+If the changes are likely to break front ends, the MI version level
+will be increased by one. This will allow the front end to parse the
+output according to the MI version. Apart from mi0, new versions of
+@value{GDBN} will not support old versions of MI and it will be the
+responsibility of the front end to work with the new one.
+
+@c Starting with mi3, add a new command -mi-version that prints the MI
+@c version?
+
+The best way to avoid unexpected changes in MI that might break your front
+end is to make your project known to @value{GDBN} developers and
+follow development on @email{gdb@@sourceware.org} and
+@email{gdb-patches@@sourceware.org}. There is also the mailing list
+@email{dmi-discuss@@lists.freestandards.org}, hosted by the Free Standards
+Group, which has the aim of creating a a more general MI protocol
+called Debugger Machine Interface (DMI) that will become a standard
+for all debuggers, not just @value{GDBN}.
+@cindex mailing lists
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Output Records
The asynchronous operation was successfully started. The target is
running.
+@item "^connected"
+@findex ^connected
+GDB has connected to a remote target.
+
@item "^error" "," @var{c-string}
@findex ^error
The operation failed. The @code{@var{c-string}} contains the corresponding
error message.
+
+@item "^exit"
+@findex ^exit
+GDB has terminated.
+
@end table
@node GDB/MI Stream Records
@item "@@" @var{string-output}
The target output stream contains any textual output from the running
-target.
+target. This is only present when GDB's event loop is truly
+asynchronous, which is currently only the case for remote targets.
@item "&" @var{string-output}
The log stream contains debugging messages being produced by @value{GDBN}'s
@end table
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Simple Examples
+@section Simple Examples of @sc{gdb/mi} Interaction
+@cindex @sc{gdb/mi}, simple examples
+
+This subsection presents several simple examples of interaction using
+the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
+following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
+the output received from @sc{gdb/mi}.
+
+Note the the line breaks shown in the examples are here only for
+readability, they don't appear in the real output.
+
+@subheading Setting a breakpoint
+
+Setting a breakpoint generates synchronous output which contains detailed
+information of the breakpoint.
+
+@smallexample
+-> -break-insert main
+<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
+ enabled="y",addr="0x08048564",func="main",file="myprog.c",
+ fullname="/home/nickrob/myprog.c",line="68",times="0"@}
+<- (gdb)
+@end smallexample
+
+@subheading Program Execution
+
+Program execution generates asynchronous records and MI gives the
+reason that execution stopped.
+
+@smallexample
+-> -exec-run
+<- ^running
+<- (gdb)
+<- *stopped,reason="breakpoint-hit",bkptno="1",thread-id="0",
+ frame=@{addr="0x08048564",func="main",
+ args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}],
+ file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"@}
+<- (gdb)
+-> -exec-continue
+<- ^running
+<- (gdb)
+<- *stopped,reason="exited-normally"
+<- (gdb)
+@end smallexample
+
+@subheading Quitting GDB
+
+Quitting GDB just prints the result class @samp{^exit}.
+
+@smallexample
+-> (gdb)
+<- -gdb-exit
+<- ^exit
+@end smallexample
+
+@subheading A Bad Command
+
+Here's what happens if you pass a non-existent command:
+
+@smallexample
+-> -rubbish
+<- ^error,msg="Undefined MI command: rubbish"
+<- (gdb)
+@end smallexample
+
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Command Description Format
@section @sc{gdb/mi} Command Description Format
The remaining sections describe blocks of commands. Each block of
commands is laid out in a fashion similar to this section.
-Note the the line breaks shown in the examples are here only for
-readability. They don't appear in the real output.
-Also note that the commands with a non-available example (N.A.@:) are
-not yet implemented.
-
@subheading Motivation
The motivation for this collection of commands.
-command @var{args}@dots{}
@end smallexample
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} CLI command.
-
@subsubheading Result
-@subsubheading Out-of-band
+@subsubheading @value{GDBN} Command
-@subsubheading Notes
+The corresponding @value{GDBN} CLI command(s), if any.
@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}
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
Setting a watchpoint on a variable in the @code{main} function:
@smallexample
-(@value{GDBP})
+(gdb)
-break-watch x
^done,wpt=@{number="2",exp="x"@}
-(@value{GDBP})
+(gdb)
-exec-continue
^running
^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
value=@{old="-268439212",new="55"@},
frame=@{func="main",args=[],file="recursive2.c",
-fullname="/home/foo/bar/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",
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
-(@value{GDBP})
+(gdb)
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="5",
value="0x11940 \"A string argument.\""@}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
-(@value{GDBP})
+(gdb)
@end smallexample
Listing breakpoints and watchpoints, at different points in the program
deleted.
@smallexample
-(@value{GDBP})
+(gdb)
-break-watch C
^done,wpt=@{number="2",exp="C"@}
-(@value{GDBP})
+(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
@{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"@},
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
- -data-disassemble
- [ -s @var{start-addr} -e @var{end-addr} ]
- | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
- -- @var{mode}
+ -exec-arguments @var{args}
@end smallexample
-@noindent
-Where:
+Set the inferior program arguments, to be used in the next
+@samp{-exec-run}.
-@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 @value{GDBN} Command
-@subsubheading Result
+The corresponding @value{GDBN} command is @samp{set args}.
-The output for each instruction is composed of four fields:
+@subsubheading Example
-@itemize @bullet
-@item Address
-@item Func-name
-@item Offset
-@item Instruction
-@end itemize
+@c FIXME!
+Don't have one around.
-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.
+
+@subheading The @code{-exec-show-arguments} Command
+@findex -exec-show-arguments
+
+@subsubheading Synopsis
+
+@smallexample
+ -exec-show-arguments
+@end smallexample
+
+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-seperator
+character must not be used
+in any directory name.
+If no directories are specified, the current search path is displayed.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} 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-seperator
+character must not be used
+in any directory name.
+If no directories are specified, the current path is displayed.
+
@subsubheading @value{GDBN} Command
-@value{GDBN} 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.
+@smallexample
+(gdb)
+-exec-next
+^running
+(gdb)
+*stopped,reason="end-stepping-range",thread-id="2",line="187",
+file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
+(gdb)
+-thread-list-ids
+^done,
+thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
+number-of-threads="3"
+(gdb)
+-thread-select 3
+^done,new-thread-id="3",
+frame=@{level="0",func="vprintf",
+args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
+@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
+(gdb)
+@end smallexample
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Program Execution
+@section @sc{gdb/mi} Program Execution
+
+These are the asynchronous commands which generate the out-of-band
+record @samp{*stopped}. Currently GDB only really executes
+asynchronously with remote targets and this interaction is mimicked in
+other cases.
-@subheading The @code{-display-disable} Command
-@findex -display-disable
+@subheading The @code{-exec-continue} Command
+@findex -exec-continue
@subsubheading Synopsis
@smallexample
- -display-disable @var{number}
+ -exec-continue
@end smallexample
-Disable 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{disable 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-enable} Command
-@findex -display-enable
+@subheading The @code{-exec-finish} Command
+@findex -exec-finish
@subsubheading Synopsis
@smallexample
- -display-enable @var{number}
+ -exec-finish
@end smallexample
-Enable display @var{number}.
+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{enable display}.
+The corresponding @value{GDBN} command is @samp{finish}.
@subsubheading Example
-N.A.
-
-@subheading The @code{-display-insert} Command
-@findex -display-insert
-
-@subsubheading Synopsis
+Function returning @code{void}.
@smallexample
- -display-insert @var{expression}
+-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
-Display @var{expression} every time the program stops.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{display}.
+Function returning other than @code{void}. The name of the internal
+@value{GDBN} variable storing the result is printed, together with the
+value itself.
-@subsubheading Example
-N.A.
+@smallexample
+-exec-finish
+^running
+(gdb)
+*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
+args=[@{name="a",value="1"],@{name="b",value="9"@}@},
+file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+gdb-result-var="$1",return-value="0"
+(gdb)
+@end smallexample
-@subheading The @code{-display-list} Command
-@findex -display-list
+@subheading The @code{-exec-interrupt} Command
+@findex -exec-interrupt
@subsubheading Synopsis
@smallexample
- -display-list
+ -exec-interrupt
@end smallexample
-List the displays. Do not show the current values.
+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{info display}.
+The corresponding @value{GDBN} command is @samp{interrupt}.
@subsubheading Example
-N.A.
+@smallexample
+(gdb)
+111-exec-continue
+111^running
-@subheading The @code{-environment-cd} Command
-@findex -environment-cd
+(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{-exec-next} Command
+@findex -exec-next
@subsubheading Synopsis
@smallexample
- -environment-cd @var{pathdir}
+ -exec-next
@end smallexample
-Set @value{GDBN}'s working directory.
+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{cd}.
+The corresponding @value{GDBN} command is @samp{next}.
@subsubheading Example
@smallexample
-(@value{GDBP})
--environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
-^done
-(@value{GDBP})
+-exec-next
+^running
+(gdb)
+*stopped,reason="end-stepping-range",line="8",file="hello.c"
+(gdb)
@end smallexample
-@subheading The @code{-environment-directory} Command
-@findex -environment-directory
+@subheading The @code{-exec-next-instruction} Command
+@findex -exec-next-instruction
@subsubheading Synopsis
@smallexample
- -environment-directory [ -r ] [ @var{pathdir} ]+
+ -exec-next-instruction
@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.
+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{dir}.
+The corresponding @value{GDBN} command is @samp{nexti}.
@subsubheading Example
@smallexample
-(@value{GDBP})
--environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
-^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
-(@value{GDBP})
--environment-directory ""
-^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
-(@value{GDBP})
--environment-directory -r /home/jjohnstn/src/gdb /usr/src
-^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
-(@value{GDBP})
--environment-directory -r
-^done,source-path="$cdir:$cwd"
-(@value{GDBP})
+(gdb)
+-exec-next-instruction
+^running
+
+(gdb)
+*stopped,reason="end-stepping-range",
+addr="0x000100d4",line="5",file="hello.c"
+(gdb)
@end smallexample
-@subheading The @code{-environment-path} Command
-@findex -environment-path
+@subheading The @code{-exec-return} Command
+@findex -exec-return
@subsubheading Synopsis
@smallexample
- -environment-path [ -r ] [ @var{pathdir} ]+
+ -exec-return
@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.
-
+Makes current function return immediately. Doesn't execute the inferior.
+Displays the new current frame.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{path}.
+The corresponding @value{GDBN} command is @samp{return}.
@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)
+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
-@subheading The @code{-environment-pwd} Command
-@findex -environment-pwd
+@subheading The @code{-exec-run} Command
+@findex -exec-run
@subsubheading Synopsis
@smallexample
- -environment-pwd
+ -exec-run
@end smallexample
-Show the current working directory.
+Starts execution of the inferior from the beginning. The inferior
+executes until either a breakpoint is encountered or the program
+exits. In the latter case the output will include an exit code, if
+the program has exited exceptionally.
-@subsubheading @value{GDBN} command
+@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{pwd}.
+The corresponding @value{GDBN} command is @samp{run}.
-@subsubheading Example
+@subsubheading Examples
@smallexample
-(@value{GDBP})
--environment-pwd
-^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
-(@value{GDBP})
+(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
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Program Control
-@section @sc{gdb/mi} Program control
-
-@subsubheading Program termination
-
-As a result of execution, the inferior program can run to completion, if
-it doesn't encounter any breakpoints. In this case the output will
-include an exit code, if the program has exited exceptionally.
-
-@subsubheading Examples
-
@noindent
Program exited normally:
@smallexample
-(@value{GDBP})
+(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})
-@end smallexample
+(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
-@subheading The @code{-exec-finish} Command
-@findex -exec-finish
+(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-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.
+
+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.
@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
+Show frames between @var{low_frame} and @var{high_frame}:
-@subheading The @code{-exec-run} Command
-@findex -exec-run
+@smallexample
+(gdb)
+-stack-list-frames 3 5
+^done,stack=
+[frame=@{level="3",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="4",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+frame=@{level="5",addr="0x000107a4",func="foo",
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
+(gdb)
+@end smallexample
-@subsubheading Synopsis
+Show a single frame:
@smallexample
- -exec-run
+(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
-Asynchronous command. Starts execution of the inferior from the
-beginning. The inferior executes until either a breakpoint is
-encountered or the program exits.
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{run}.
-
-@subsubheading Example
-
-@smallexample
-(@value{GDBP})
--break-insert main
-^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
-(@value{GDBP})
--exec-run
-^running
-(@value{GDBP})
-*stopped,reason="breakpoint-hit",bkptno="1",
-frame=@{func="main",args=[],file="recursive2.c",
-fullname="/home/foo/bar/devo/myproject/recursive2.c",line="4"@}
-(@value{GDBP})
-@end smallexample
-
-
-@subheading The @code{-exec-show-arguments} Command
-@findex -exec-show-arguments
+@subheading The @code{-stack-list-locals} Command
+@findex -stack-list-locals
@subsubheading Synopsis
@smallexample
- -exec-show-arguments
+ -stack-list-locals @var{print-values}
@end smallexample
-Print the arguments of the program.
+Display the local variable names for the selected frame. If
+@var{print-values} is 0 or @code{--no-values}, print only the names of
+the variables; if it is 1 or @code{--all-values}, print also their
+values; and if it is 2 or @code{--simple-values}, print the name,
+type and value for simple data types and the name and type for arrays,
+structures and unions. In this last case, a frontend can immediately
+display the value of simple data types and create variable objects for
+other data types when the the user wishes to explore their values in
+more detail.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{show args}.
+@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
@subsubheading Example
-N.A.
-@c @subheading -exec-signal
+@smallexample
+(gdb)
+-stack-list-locals 0
+^done,locals=[name="A",name="B",name="C"]
+(gdb)
+-stack-list-locals --all-values
+^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
+ @{name="C",value="@{1, 2, 3@}"@}]
+-stack-list-locals --simple-values
+^done,locals=[@{name="A",type="int",value="1"@},
+ @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}]
+(gdb)
+@end smallexample
-@subheading The @code{-exec-step} Command
-@findex -exec-step
+
+@subheading The @code{-stack-select-frame} Command
+@findex -stack-select-frame
@subsubheading Synopsis
@smallexample
- -exec-step
+ -stack-select-frame @var{framenum}
@end smallexample
-Asynchronous command. Resumes execution of the inferior program, stopping
-when the beginning of the next source line is reached, if the next
-source line is not a function call. If it is, stop at the first
-instruction of the called function.
+Change the selected frame. Select a different frame @var{framenum} on
+the stack.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{step}.
+The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
+@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
@subsubheading Example
-Stepping into a function:
-
@smallexample
--exec-step
-^running
-(@value{GDBP})
-*stopped,reason="end-stepping-range",
-frame=@{func="foo",args=[@{name="a",value="10"@},
-@{name="b",value="0"@}],file="recursive2.c",
-fullname="/home/foo/bar/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
+@subheading Motivation for Variable Objects in @sc{gdb/mi}
-@subheading The @code{-exec-step-instruction} Command
-@findex -exec-step-instruction
+For the implementation of a variable debugger window (locals, watched
+expressions, etc.), we are proposing the adaptation of the existing code
+used by @code{Insight}.
-@subsubheading Synopsis
+The two main reasons for that are:
-@smallexample
- -exec-step-instruction
-@end smallexample
+@enumerate 1
+@item
+It has been proven in practice (it is already on its second generation).
-Asynchronous command. Resumes the inferior which executes one machine
-instruction. The output, once @value{GDBN} has stopped, will vary depending on
-whether we have stopped in the middle of a source line or not. In the
-former case, the address at which the program stopped will be printed as
-well.
+@item
+It will shorten development time (needless to say how important it is
+now).
+@end enumerate
-@subsubheading @value{GDBN} Command
+The original interface was designed to be used by Tcl code, so it was
+slightly changed so it could be used through @sc{gdb/mi}. This section
+describes the @sc{gdb/mi} operations that will be available and gives some
+hints about their use.
-The corresponding @value{GDBN} command is @samp{stepi}.
+@emph{Note}: In addition to the set of operations described here, we
+expect the @sc{gui} implementation of a variable window to require, at
+least, the following operations:
-@subsubheading Example
+@itemize @bullet
+@item @code{-gdb-show} @code{output-radix}
+@item @code{-stack-list-arguments}
+@item @code{-stack-list-locals}
+@item @code{-stack-select-frame}
+@end itemize
-@smallexample
-(@value{GDBP})
--exec-step-instruction
-^running
+@subheading Introduction to Variable Objects in @sc{gdb/mi}
-(@value{GDBP})
-*stopped,reason="end-stepping-range",
-frame=@{func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/devo/myproject/try.c",line="10"@}
-(@value{GDBP})
--exec-step-instruction
-^running
+@cindex variable objects in @sc{gdb/mi}
+The basic idea behind variable objects is the creation of a named object
+to represent a variable, an expression, a memory location or even a CPU
+register. For each object created, a set of operations is available for
+examining or changing its properties.
-(@value{GDBP})
-*stopped,reason="end-stepping-range",
-frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/devo/myproject/try.c",line="10"@}
-(@value{GDBP})
-@end smallexample
+Furthermore, complex data types, such as C structures, are represented
+in a tree format. For instance, the @code{struct} type variable is the
+root and the children will represent the struct members. If a child
+is itself of a complex type, it will also have children of its own.
+Appropriate language differences are handled for C, C@t{++} and Java.
+When returning the actual values of the objects, this facility allows
+for the individual selection of the display format used in the result
+creation. It can be chosen among: binary, decimal, hexadecimal, octal
+and natural. Natural refers to a default format automatically
+chosen based on the variable type (like decimal for an @code{int}, hex
+for pointers, etc.).
-@subheading The @code{-exec-until} Command
-@findex -exec-until
+The following is the complete set of @sc{gdb/mi} operations defined to
+access this functionality:
-@subsubheading Synopsis
+@multitable @columnfractions .4 .6
+@item @strong{Operation}
+@tab @strong{Description}
-@smallexample
- -exec-until [ @var{location} ]
-@end smallexample
+@item @code{-var-create}
+@tab create a variable object
+@item @code{-var-delete}
+@tab delete the variable object and its children
+@item @code{-var-set-format}
+@tab set the display format of this variable
+@item @code{-var-show-format}
+@tab show the display format of this variable
+@item @code{-var-info-num-children}
+@tab tells how many children this object has
+@item @code{-var-list-children}
+@tab return a list of the object's children
+@item @code{-var-info-type}
+@tab show the type of this variable object
+@item @code{-var-info-expression}
+@tab print what this variable object represents
+@item @code{-var-show-attributes}
+@tab is this variable editable? does it exist here?
+@item @code{-var-evaluate-expression}
+@tab get the value of this variable
+@item @code{-var-assign}
+@tab set the value of this variable
+@item @code{-var-update}
+@tab update the variable and its children
+@end multitable
-Asynchronous command. Executes the inferior until the @var{location}
-specified in the argument is reached. If there is no argument, the inferior
-executes until a source line greater than the current one is reached.
-The reason for stopping in this case will be @samp{location-reached}.
+In the next subsection we describe each operation in detail and suggest
+how it can be used.
-@subsubheading @value{GDBN} Command
+@subheading Description And Use of Operations on Variable Objects
-The corresponding @value{GDBN} command is @samp{until}.
+@subheading The @code{-var-create} Command
+@findex -var-create
-@subsubheading Example
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--exec-until recursive2.c:6
-^running
-(@value{GDBP})
-x = 55
-*stopped,reason="location-reached",frame=@{func="main",args=[],
-file="recursive2.c",fullname="/home/foo/bar/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 @var{name}
@end smallexample
-Specify the executable file to be debugged. Unlike
-@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
-from this file. If used without argument, @value{GDBN} clears the information
-about the executable file. No output is produced, except a completion
-notification.
+Deletes a previously created variable object and all of its children.
-@subsubheading @value{GDBN} Command
+Returns an error if the object @var{name} is not found.
-The corresponding @value{GDBN} command is @samp{exec-file}.
-
-@subsubheading Example
-
-@smallexample
-(@value{GDBP})
--file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
-^done
-(@value{GDBP})
-@end smallexample
-
-@subheading The @code{-file-list-exec-sections} Command
-@findex -file-list-exec-sections
+@subheading The @code{-var-set-format} Command
+@findex -var-set-format
@subsubheading Synopsis
@smallexample
- -file-list-exec-sections
+ -var-set-format @var{name} @var{format-spec}
@end smallexample
-List the sections of the current executable file.
-
-@subsubheading @value{GDBN} Command
+Sets the output format for the value of the object @var{name} to be
+@var{format-spec}.
-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}.
+The syntax for the @var{format-spec} is as follows:
-@subsubheading Example
-N.A.
+@smallexample
+ @var{format-spec} @expansion{}
+ @{binary | decimal | hexadecimal | octal | natural@}
+@end smallexample
-@subheading The @code{-file-list-exec-source-file} Command
-@findex -file-list-exec-source-file
+@subheading The @code{-var-show-format} Command
+@findex -var-show-format
@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.
+@smallexample
+(gdb)
+ -var-list-children n
+ ^done,numchild=@var{n},children=[@{name=@var{name},
+ numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
+(gdb)
+ -var-list-children --all-values n
+ ^done,numchild=@var{n},children=[@{name=@var{name},
+ numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
+@end smallexample
-@subheading The @code{-file-list-symbol-files} Command
-@findex -file-list-symbol-files
+
+@subheading The @code{-var-info-type} Command
+@findex -var-info-type
@subsubheading Synopsis
@smallexample
- -file-list-symbol-files
+ -var-info-type @var{name}
@end smallexample
-List symbol files.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{info file} (part of it).
+Returns the type of the specified variable @var{name}. The type is
+returned as a string in the same format as it is output by the
+@value{GDBN} CLI:
-@subsubheading Example
-N.A.
+@smallexample
+ type=@var{typename}
+@end smallexample
-@subheading The @code{-file-symbol-file} Command
-@findex -file-symbol-file
+@subheading The @code{-var-info-expression} Command
+@findex -var-info-expression
@subsubheading Synopsis
@smallexample
- -file-symbol-file @var{file}
+ -var-info-expression @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 what is represented by the variable object @var{name}:
@smallexample
-(@value{GDBP})
--file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
-^done
-(@value{GDBP})
+ lang=@var{lang-spec},exp=@var{expression}
@end smallexample
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Miscellaneous Commands
-@section Miscellaneous @value{GDBN} commands in @sc{gdb/mi}
-
-@c @subheading -gdb-complete
+@noindent
+where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
-@subheading The @code{-gdb-exit} Command
-@findex -gdb-exit
+@subheading The @code{-var-show-attributes} Command
+@findex -var-show-attributes
@subsubheading Synopsis
@smallexample
- -gdb-exit
+ -var-show-attributes @var{name}
@end smallexample
-Exit @value{GDBN} immediately.
-
-@subsubheading @value{GDBN} Command
-
-Approximately corresponds to @samp{quit}.
-
-@subsubheading Example
+List attributes of the specified variable object @var{name}:
@smallexample
-(@value{GDBP})
--gdb-exit
+ status=@var{attr} [ ( ,@var{attr} )* ]
@end smallexample
-@subheading The @code{-gdb-set} Command
-@findex -gdb-set
+@noindent
+where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
+
+@subheading The @code{-var-evaluate-expression} Command
+@findex -var-evaluate-expression
@subsubheading Synopsis
@smallexample
- -gdb-set
+ -var-evaluate-expression @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
+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:
@smallexample
-(@value{GDBP})
--gdb-set $foo=3
-^done
-(@value{GDBP})
+ value=@var{value}
@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{-gdb-show} Command
-@findex -gdb-show
+@subheading The @code{-var-assign} Command
+@findex -var-assign
@subsubheading Synopsis
@smallexample
- -gdb-show
+ -var-assign @var{name} @var{expression}
@end smallexample
-Show the current value of a @value{GDBN} variable.
-
-@subsubheading @value{GDBN} command
-
-The corresponding @value{GDBN} command is @samp{show}.
+Assigns the value of @var{expression} to the variable object specified
+by @var{name}. The object must be @samp{editable}. If the variable's
+value is altered by the assign, the variable will show up in any
+subsequent @code{-var-update} list.
@subsubheading Example
@smallexample
-(@value{GDBP})
--gdb-show annotate
-^done,value="0"
-(@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
-@c @subheading -gdb-source
-
-
-@subheading The @code{-gdb-version} Command
-@findex -gdb-version
+@subheading The @code{-var-update} Command
+@findex -var-update
@subsubheading Synopsis
@smallexample
- -gdb-version
+ -var-update [@var{print-values}] @{@var{name} | "*"@}
@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.
+Update the value of the variable object @var{name} by evaluating its
+expression after fetching all the new values from memory or registers.
+A @samp{*} causes all existing variable objects to be updated. The
+option @var{print-values} determines whether names both and values, or
+just names are printed in the manner described for
+@code{-var-list-children} (@pxref{-var-list-children}).
@subsubheading Example
-@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 --all-values var1
+^done,changelist=[@{name="var1",value="3",in_scope="true",
+type_changed="false"@}]
+(gdb)
@end smallexample
-@subheading The @code{-interpreter-exec} Command
-@findex -interpreter-exec
-
-@subheading Synopsis
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Data Manipulation
+@section @sc{gdb/mi} Data Manipulation
-@smallexample
--interpreter-exec @var{interpreter} @var{command}
-@end smallexample
+@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.
-Execute the specified @var{command} in the given @var{interpreter}.
-
-@subheading @value{GDBN} Command
+@c REMOVED FROM THE INTERFACE.
+@c @subheading -data-assign
+@c Change the value of a program variable. Plenty of side effects.
+@c @subsubheading GDB command
+@c set variable
+@c @subsubheading Example
+@c N.A.
-The corresponding @value{GDBN} command is @samp{interpreter-exec}.
+@subheading The @code{-data-disassemble} Command
+@findex -data-disassemble
-@subheading Example
+@subsubheading Synopsis
@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})
+ -data-disassemble
+ [ -s @var{start-addr} -e @var{end-addr} ]
+ | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
+ -- @var{mode}
@end smallexample
-@ignore
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Kod Commands
-@section @sc{gdb/mi} Kod Commands
+@noindent
+Where:
-The Kod commands are not implemented.
+@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
-@c @subheading -kod-info
+@subsubheading Result
-@c @subheading -kod-list
+The output for each instruction is composed of four fields:
-@c @subheading -kod-list-object-types
+@itemize @bullet
+@item Address
+@item Func-name
+@item Offset
+@item Instruction
+@end itemize
-@c @subheading -kod-show
+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.
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Memory Overlay Commands
-@section @sc{gdb/mi} Memory Overlay Commands
+@subsubheading @value{GDBN} Command
-The memory overlay commands are not implemented.
+There's no direct mapping from this command to the CLI.
-@c @subheading -overlay-auto
+@subsubheading Example
-@c @subheading -overlay-list-mapping-state
+Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
-@c @subheading -overlay-list-overlays
+@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 @subheading -overlay-map
+Disassemble the whole @code{main} function. Line 32 is part of
+@code{main}.
-@c @subheading -overlay-off
+@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-on
+Disassemble 3 instructions from the start of @code{main}:
-@c @subheading -overlay-unmap
+@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 %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Signal Handling Commands
-@section @sc{gdb/mi} Signal Handling Commands
+Disassemble 3 instructions from the start of @code{main} in mixed mode:
-Signal handling commands are not implemented.
+@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 -signal-handle
-@c @subheading -signal-list-handle-actions
+@subheading The @code{-data-evaluate-expression} Command
+@findex -data-evaluate-expression
-@c @subheading -signal-list-signal-types
-@end ignore
+@subsubheading Synopsis
+@smallexample
+ -data-evaluate-expression @var{expr}
+@end smallexample
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Stack Manipulation
-@section @sc{gdb/mi} Stack Manipulation Commands
+Evaluate @var{expr} as an expression. The expression could contain an
+inferior function call. The function call will execute synchronously.
+If the expression contains spaces, it must be enclosed in double quotes.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
+@samp{call}. In @code{gdbtk} only, there's a corresponding
+@samp{gdb_eval} command.
+
+@subsubheading Example
+
+In the following example, the numbers that precede the commands are the
+@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
+Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
+output.
+
+@smallexample
+211-data-evaluate-expression A
+211^done,value="1"
+(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-depth} Command
-@findex -stack-info-depth
+
+@subheading The @code{-data-list-changed-registers} Command
+@findex -data-list-changed-registers
@subsubheading Synopsis
@smallexample
- -stack-info-depth [ @var{max-depth} ]
+ -data-list-changed-registers
@end smallexample
-Return the depth of the stack. If the integer argument @var{max-depth}
-is specified, do not count beyond @var{max-depth} frames.
+Display a list of the registers that have changed.
@subsubheading @value{GDBN} Command
-There's no equivalent @value{GDBN} command.
+@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
+has the corresponding command @samp{gdb_changed_register_list}.
@subsubheading Example
-For a stack with frame levels 0 through 11:
+On a PPC MBX board:
@smallexample
-(@value{GDBP})
--stack-info-depth
-^done,depth="12"
-(@value{GDBP})
--stack-info-depth 4
-^done,depth="4"
-(@value{GDBP})
--stack-info-depth 12
-^done,depth="12"
-(@value{GDBP})
--stack-info-depth 11
-^done,depth="11"
-(@value{GDBP})
--stack-info-depth 13
-^done,depth="12"
-(@value{GDBP})
+(gdb)
+-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-list-arguments} Command
-@findex -stack-list-arguments
+
+@subheading The @code{-data-list-register-names} Command
+@findex -data-list-register-names
@subsubheading Synopsis
@smallexample
- -stack-list-arguments @var{show-values}
- [ @var{low-frame} @var{high-frame} ]
+ -data-list-register-names [ ( @var{regno} )+ ]
@end smallexample
-Display a list of the arguments for the frames between @var{low-frame}
-and @var{high-frame} (inclusive). If @var{low-frame} and
-@var{high-frame} are not provided, list the arguments for the whole call
-stack.
-
-The @var{show-values} argument must have a value of 0 or 1. A value of
-0 means that only the names of the arguments are listed, a value of 1
-means that both names and values of the arguments are printed.
+Show a list of register names for the current target. If no arguments
+are given, it shows a list of the names of all the registers. If
+integer numbers are given as arguments, it will print a list of the
+names of the registers corresponding to the arguments. To ensure
+consistency between a register name and its number, the output list may
+include empty register names.
@subsubheading @value{GDBN} Command
-@value{GDBN} does not have an equivalent command. @code{gdbtk} has a
-@samp{gdb_get_args} command which partially overlaps with the
-functionality of @samp{-stack-list-arguments}.
+@value{GDBN} does not have a command which corresponds to
+@samp{-data-list-register-names}. In @code{gdbtk} there is a
+corresponding command @samp{gdb_regnames}.
@subsubheading Example
+For the PPC MBX board:
@smallexample
-(@value{GDBP})
--stack-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)
+-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
-@c @subheading -stack-list-exception-handlers
-
-
-@subheading The @code{-stack-list-frames} Command
-@findex -stack-list-frames
+@subheading The @code{-data-list-register-values} Command
+@findex -data-list-register-values
@subsubheading Synopsis
@smallexample
- -stack-list-frames [ @var{low-frame} @var{high-frame} ]
+ -data-list-register-values @var{fmt} [ ( @var{regno} )*]
@end smallexample
-List the frames currently on the stack. For each frame it displays the
-following info:
+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.
-@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
+Allowed formats for @var{fmt} are:
-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.
+@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{backtrace} and @samp{where}.
+The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
+all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
@subsubheading Example
-Full stack backtrace:
+For a PPC MBX board (note: line breaks are for readability only, they
+don't appear in the actual output):
@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})
+(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
-Show frames between @var{low_frame} and @var{high_frame}:
-@smallexample
-(@value{GDBP})
--stack-list-frames 3 5
-^done,stack=
-[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",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})
-@end smallexample
+@subheading The @code{-data-read-memory} Command
+@findex -data-read-memory
-Show a single frame:
+@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})
+ -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
+@noindent
+where:
-@subheading The @code{-stack-list-locals} Command
-@findex -stack-list-locals
+@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.
-@subsubheading Synopsis
+@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}).
-@smallexample
- -stack-list-locals @var{print-values}
-@end smallexample
+@item @var{word-size}
+The size of each memory word in bytes.
-Display the local variable names for the current frame. With an
-argument of 0 or @code{--no-values}, prints only the names of the variables.
-With argument of 1 or @code{--all-values}, prints also their values. With
-argument of 2 or @code{--simple-values}, prints the name, type and value for
-simple data types and the name and type for arrays, structures and
-unions. In this last case, the idea is that the user can see the
-value of simple data types immediately and he can create variable
-objects for other data types if he wishes to explore their values in
-more detail.
+@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
-@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
+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-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)
+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.
-@subheading The @code{-stack-select-frame} Command
-@findex -stack-select-frame
+@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
-@subsubheading Synopsis
+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
- -stack-select-frame @var{framenum}
+(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
-Change the current frame. Select a different frame @var{framenum} on
-the stack.
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Tracepoint Commands
+@section @sc{gdb/mi} Tracepoint Commands
-@subsubheading @value{GDBN} Command
+The tracepoint commands are not yet implemented.
-The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
-@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
+@c @subheading -trace-actions
-@subsubheading Example
+@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
-@smallexample
-(@value{GDBP})
--stack-select-frame 2
-^done
-(@value{GDBP})
-@end smallexample
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Symbol Query
@subsubheading Example
@smallexample
-(@value{GDBP})
+(gdb)
-symbol-list-lines basics.c
^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}]
-(@value{GDBP})
+(gdb)
@end smallexample
@subheading The @code{-symbol-list-variables} Command
@findex -symbol-list-variables
-
-@subsubheading Synopsis
-
-@smallexample
- -symbol-list-variables
-@end smallexample
-
-List all the global and static variable names.
-
-@subsubheading @value{GDBN} Command
-
-@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
-
-@subsubheading Example
-N.A.
-
-
-@subheading The @code{-symbol-locate} Command
-@findex -symbol-locate
-
-@subsubheading Synopsis
-
-@smallexample
- -symbol-locate
-@end smallexample
-
-@subsubheading @value{GDBN} Command
-
-@samp{gdb_loc} in @code{gdbtk}.
-
-@subsubheading Example
-N.A.
-
-
-@subheading The @code{-symbol-type} Command
-@findex -symbol-type
-
-@subsubheading Synopsis
-
-@smallexample
- -symbol-type @var{variable}
-@end smallexample
-
-Show type of @var{variable}.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
-@samp{gdb_obj_variable}.
-
-@subsubheading Example
-N.A.
-
-
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Target Manipulation
-@section @sc{gdb/mi} Target Manipulation Commands
-
-
-@subheading The @code{-target-attach} Command
-@findex -target-attach
-
-@subsubheading Synopsis
-
-@smallexample
- -target-attach @var{pid} | @var{file}
-@end smallexample
-
-Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
-
-@subsubheading @value{GDBN} command
-
-The corresponding @value{GDBN} command is @samp{attach}.
-
-@subsubheading Example
-N.A.
-
-
-@subheading The @code{-target-compare-sections} Command
-@findex -target-compare-sections
-
-@subsubheading Synopsis
-
-@smallexample
- -target-compare-sections [ @var{section} ]
-@end smallexample
-
-Compare data of section @var{section} on target to the exec file.
-Without the argument, all sections are compared.
-
-@subsubheading @value{GDBN} Command
-
-The @value{GDBN} equivalent is @samp{compare-sections}.
-
-@subsubheading Example
-N.A.
-
-
-@subheading The @code{-target-detach} Command
-@findex -target-detach
-
-@subsubheading Synopsis
-
-@smallexample
- -target-detach
-@end smallexample
-
-Disconnect from the remote target. There's no output.
-
-@subsubheading @value{GDBN} command
-
-The corresponding @value{GDBN} command is @samp{detach}.
-
-@subsubheading Example
-
-@smallexample
-(@value{GDBP})
--target-detach
-^done
-(@value{GDBP})
-@end smallexample
-
-
-@subheading The @code{-target-disconnect} Command
-@findex -target-disconnect
-
-@subsubheading Synopsis
-
-@example
- -target-disconnect
-@end example
-
-Disconnect from the remote target. There's no output.
-
-@subsubheading @value{GDBN} command
-
-The corresponding @value{GDBN} command is @samp{disconnect}.
-
-@subsubheading Example
-
-@smallexample
-(@value{GDBP})
--target-disconnect
-^done
-(@value{GDBP})
-@end smallexample
-
-
-@subheading The @code{-target-download} Command
-@findex -target-download
-
-@subsubheading Synopsis
-
-@smallexample
- -target-download
-@end smallexample
-
-Loads the executable onto the remote target.
-It prints out an update message every half second, which includes the fields:
-
-@table @samp
-@item section
-The name of the section.
-@item section-sent
-The size of what has been sent so far for that section.
-@item section-size
-The size of the section.
-@item total-sent
-The total size of what was sent so far (the current and the previous sections).
-@item total-size
-The size of the overall executable to download.
-@end table
-
-@noindent
-Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
-@sc{gdb/mi} Output Syntax}).
-
-In addition, it prints the name and size of the sections, as they are
-downloaded. These messages include the following fields:
-
-@table @samp
-@item section
-The name of the section.
-@item section-size
-The size of the section.
-@item total-size
-The size of the overall executable to download.
-@end table
-
-@noindent
-At the end, a summary is printed.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{load}.
-
-@subsubheading Example
-
-Note: each status message appears on a single line. Here the messages
-have been broken down so that they can fit onto a page.
-
-@smallexample
-(@value{GDBP})
--target-download
-+download,@{section=".text",section-size="6668",total-size="9880"@}
-+download,@{section=".text",section-sent="512",section-size="6668",
-total-sent="512",total-size="9880"@}
-+download,@{section=".text",section-sent="1024",section-size="6668",
-total-sent="1024",total-size="9880"@}
-+download,@{section=".text",section-sent="1536",section-size="6668",
-total-sent="1536",total-size="9880"@}
-+download,@{section=".text",section-sent="2048",section-size="6668",
-total-sent="2048",total-size="9880"@}
-+download,@{section=".text",section-sent="2560",section-size="6668",
-total-sent="2560",total-size="9880"@}
-+download,@{section=".text",section-sent="3072",section-size="6668",
-total-sent="3072",total-size="9880"@}
-+download,@{section=".text",section-sent="3584",section-size="6668",
-total-sent="3584",total-size="9880"@}
-+download,@{section=".text",section-sent="4096",section-size="6668",
-total-sent="4096",total-size="9880"@}
-+download,@{section=".text",section-sent="4608",section-size="6668",
-total-sent="4608",total-size="9880"@}
-+download,@{section=".text",section-sent="5120",section-size="6668",
-total-sent="5120",total-size="9880"@}
-+download,@{section=".text",section-sent="5632",section-size="6668",
-total-sent="5632",total-size="9880"@}
-+download,@{section=".text",section-sent="6144",section-size="6668",
-total-sent="6144",total-size="9880"@}
-+download,@{section=".text",section-sent="6656",section-size="6668",
-total-sent="6656",total-size="9880"@}
-+download,@{section=".init",section-size="28",total-size="9880"@}
-+download,@{section=".fini",section-size="28",total-size="9880"@}
-+download,@{section=".data",section-size="3156",total-size="9880"@}
-+download,@{section=".data",section-sent="512",section-size="3156",
-total-sent="7236",total-size="9880"@}
-+download,@{section=".data",section-sent="1024",section-size="3156",
-total-sent="7748",total-size="9880"@}
-+download,@{section=".data",section-sent="1536",section-size="3156",
-total-sent="8260",total-size="9880"@}
-+download,@{section=".data",section-sent="2048",section-size="3156",
-total-sent="8772",total-size="9880"@}
-+download,@{section=".data",section-sent="2560",section-size="3156",
-total-sent="9284",total-size="9880"@}
-+download,@{section=".data",section-sent="3072",section-size="3156",
-total-sent="9796",total-size="9880"@}
-^done,address="0x10004",load-size="9880",transfer-rate="6586",
-write-rate="429"
-(@value{GDBP})
+
+@subsubheading Synopsis
+
+@smallexample
+ -symbol-list-variables
@end smallexample
+List all the global and static variable names.
-@subheading The @code{-target-exec-status} Command
-@findex -target-exec-status
+@subsubheading @value{GDBN} Command
+
+@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
+
+@subsubheading Example
+N.A.
+
+
+@subheading The @code{-symbol-locate} Command
+@findex -symbol-locate
@subsubheading Synopsis
@smallexample
- -target-exec-status
+ -symbol-locate
@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.
+@samp{gdb_loc} in @code{gdbtk}.
@subsubheading Example
N.A.
-@subheading The @code{-target-list-available-targets} Command
-@findex -target-list-available-targets
+@subheading The @code{-symbol-type} Command
+@findex -symbol-type
@subsubheading Synopsis
@smallexample
- -target-list-available-targets
+ -symbol-type @var{variable}
@end smallexample
-List the possible targets to connect to.
+Show type of @var{variable}.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{help target}.
+The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
+@samp{gdb_obj_variable}.
@subsubheading Example
N.A.
-@subheading The @code{-target-list-current-targets} Command
-@findex -target-list-current-targets
+@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
- -target-list-current-targets
+ -file-exec-and-symbols @var{file}
@end smallexample
-Describe the current target.
+Specify the executable file to be debugged. This file is the one from
+which the symbol table is also read. If no file is specified, the
+command clears the executable and symbol information. If breakpoints
+are set when using this command with no arguments, @value{GDBN} will produce
+error messages. Otherwise, no output is produced, except a completion
+notification.
@subsubheading @value{GDBN} Command
-The corresponding information is printed by @samp{info file} (among
-other things).
+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{-target-list-parameters} Command
-@findex -target-list-parameters
+
+@subheading The @code{-file-exec-file} Command
+@findex -file-exec-file
@subsubheading Synopsis
@smallexample
- -target-list-parameters
+ -file-exec-file @var{file}
@end smallexample
-@c ????
+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
-No equivalent.
+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{-target-select} Command
-@findex -target-select
+@subheading The @code{-file-list-exec-sections} Command
+@findex -file-list-exec-sections
@subsubheading Synopsis
@smallexample
- -target-select @var{type} @var{parameters @dots{}}
+ -file-list-exec-sections
@end smallexample
-Connect @value{GDBN} to the remote target. This command takes two args:
+List the sections of the current executable file.
-@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
+@subsubheading @value{GDBN} Command
-The output is a connection notification, followed by the address at
-which the target program is, in the following form:
+The @value{GDBN} command @samp{info file} shows, among the rest, the same
+information as this command. @code{gdbtk} has a corresponding command
+@samp{gdb_load_info}.
+
+@subsubheading Example
+N.A.
+
+
+@subheading The @code{-file-list-exec-source-file} Command
+@findex -file-list-exec-source-file
+
+@subsubheading Synopsis
@smallexample
-^connected,addr="@var{address}",func="@var{function name}",
- args=[@var{arg list}]
+ -file-list-exec-source-file
@end smallexample
+List the line number, the current source file, and the absolute path
+to the current source file for the current executable.
+
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{target}.
+The @value{GDBN} equivalent is @samp{info source}
@subsubheading Example
@smallexample
-(@value{GDBP})
--target-select async /dev/ttya
-^connected,addr="0xfe00a300",func="??",args=[]
-(@value{GDBP})
+(gdb)
+123-file-list-exec-source-file
+123^done,line="1",file="foo.c",fullname="/home/bar/foo.c"
+(gdb)
@end smallexample
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Thread Commands
-@section @sc{gdb/mi} Thread Commands
+@subheading The @code{-file-list-exec-source-files} Command
+@findex -file-list-exec-source-files
+
+@subsubheading Synopsis
-@subheading The @code{-thread-info} Command
-@findex -thread-info
+@smallexample
+ -file-list-exec-source-files
+@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
+
+The @value{GDBN} equivalent is @samp{info sources}.
+@code{gdbtk} has an analogous command @samp{gdb_listfiles}.
+
+@subsubheading Example
+@smallexample
+(gdb)
+-file-list-exec-source-files
+^done,files=[
+@{file=foo.c,fullname=/home/foo.c@},
+@{file=/home/bar.c,fullname=/home/bar.c@},
+@{file=gdb_could_not_find_fullpath.c@}]
+(gdb)
+@end smallexample
+
+@subheading The @code{-file-list-shared-libraries} Command
+@findex -file-list-shared-libraries
@subsubheading Synopsis
@smallexample
- -thread-info
+ -file-list-shared-libraries
@end smallexample
-@subsubheading @value{GDBN} command
+List the shared libraries in the program.
-No equivalent.
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info shared}.
@subsubheading Example
N.A.
-@subheading The @code{-thread-list-all-threads} Command
-@findex -thread-list-all-threads
+@subheading The @code{-file-list-symbol-files} Command
+@findex -file-list-symbol-files
@subsubheading Synopsis
@smallexample
- -thread-list-all-threads
+ -file-list-symbol-files
@end smallexample
+List symbol files.
+
@subsubheading @value{GDBN} Command
-The equivalent @value{GDBN} command is @samp{info threads}.
+The corresponding @value{GDBN} command is @samp{info file} (part of it).
@subsubheading Example
N.A.
-@subheading The @code{-thread-list-ids} Command
-@findex -thread-list-ids
+@subheading The @code{-file-symbol-file} Command
+@findex -file-symbol-file
@subsubheading Synopsis
@smallexample
- -thread-list-ids
+ -file-symbol-file @var{file}
@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.
+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
-Part of @samp{info threads} supplies the same information.
+The corresponding @value{GDBN} command is @samp{symbol-file}.
@subsubheading Example
-No threads present, besides the main process:
-
@smallexample
-(@value{GDBP})
--thread-list-ids
-^done,thread-ids=@{@},number-of-threads="0"
-(@value{GDBP})
+(gdb)
+-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
+^done
+(gdb)
@end smallexample
+@ignore
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Memory Overlay Commands
+@section @sc{gdb/mi} Memory Overlay Commands
+
+The memory overlay commands are not implemented.
-Several threads:
+@c @subheading -overlay-auto
+
+@c @subheading -overlay-list-mapping-state
+
+@c @subheading -overlay-list-overlays
+
+@c @subheading -overlay-map
+
+@c @subheading -overlay-off
+
+@c @subheading -overlay-on
+
+@c @subheading -overlay-unmap
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Signal Handling Commands
+@section @sc{gdb/mi} Signal Handling Commands
+
+Signal handling commands are not implemented.
+
+@c @subheading -signal-handle
+
+@c @subheading -signal-list-handle-actions
+
+@c @subheading -signal-list-signal-types
+@end ignore
+
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Target Manipulation
+@section @sc{gdb/mi} Target Manipulation Commands
+
+
+@subheading The @code{-target-attach} Command
+@findex -target-attach
+
+@subsubheading Synopsis
@smallexample
-(@value{GDBP})
--thread-list-ids
-^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
-number-of-threads="3"
-(@value{GDBP})
+ -target-attach @var{pid} | @var{file}
@end smallexample
+Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
+
+@subsubheading @value{GDBN} command
+
+The corresponding @value{GDBN} command is @samp{attach}.
+
+@subsubheading Example
+N.A.
-@subheading The @code{-thread-select} Command
-@findex -thread-select
+
+@subheading The @code{-target-compare-sections} Command
+@findex -target-compare-sections
@subsubheading Synopsis
@smallexample
- -thread-select @var{threadnum}
+ -target-compare-sections [ @var{section} ]
@end smallexample
-Make @var{threadnum} the current thread. It prints the number of the new
-current thread, and the topmost frame for that thread.
+Compare data of section @var{section} on target to the exec file.
+Without the argument, all sections are compared.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{thread}.
+The @value{GDBN} equivalent is @samp{compare-sections}.
@subsubheading Example
+N.A.
+
+
+@subheading The @code{-target-detach} Command
+@findex -target-detach
+
+@subsubheading Synopsis
@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})
+ -target-detach
@end smallexample
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Tracepoint Commands
-@section @sc{gdb/mi} Tracepoint Commands
+Detach from the remote target which normally resumes its execution.
+There's no output.
-The tracepoint commands are not yet implemented.
+@subsubheading @value{GDBN} command
-@c @subheading -trace-actions
+The corresponding @value{GDBN} command is @samp{detach}.
-@c @subheading -trace-delete
+@subsubheading Example
-@c @subheading -trace-disable
+@smallexample
+(gdb)
+-target-detach
+^done
+(gdb)
+@end smallexample
-@c @subheading -trace-dump
-@c @subheading -trace-enable
+@subheading The @code{-target-disconnect} Command
+@findex -target-disconnect
-@c @subheading -trace-exists
+@subsubheading Synopsis
-@c @subheading -trace-find
+@example
+ -target-disconnect
+@end example
-@c @subheading -trace-frame-number
+Disconnect from the remote target. There's no output and the target is
+generally not resumed.
-@c @subheading -trace-info
+@subsubheading @value{GDBN} command
-@c @subheading -trace-insert
+The corresponding @value{GDBN} command is @samp{disconnect}.
-@c @subheading -trace-list
+@subsubheading Example
-@c @subheading -trace-pass-count
+@smallexample
+(gdb)
+-target-disconnect
+^done
+(gdb)
+@end smallexample
-@c @subheading -trace-save
-@c @subheading -trace-start
+@subheading The @code{-target-download} Command
+@findex -target-download
-@c @subheading -trace-stop
+@subsubheading Synopsis
+@smallexample
+ -target-download
+@end smallexample
-@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Variable Objects
-@section @sc{gdb/mi} Variable Objects
+Loads the executable onto the remote target.
+It prints out an update message every half second, which includes the fields:
+@table @samp
+@item section
+The name of the section.
+@item section-sent
+The size of what has been sent so far for that section.
+@item section-size
+The size of the section.
+@item total-sent
+The total size of what was sent so far (the current and the previous sections).
+@item total-size
+The size of the overall executable to download.
+@end table
-@subheading Motivation for Variable Objects in @sc{gdb/mi}
+@noindent
+Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
+@sc{gdb/mi} Output Syntax}).
-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}.
+In addition, it prints the name and size of the sections, as they are
+downloaded. These messages include the following fields:
-The two main reasons for that are:
+@table @samp
+@item section
+The name of the section.
+@item section-size
+The size of the section.
+@item total-size
+The size of the overall executable to download.
+@end table
-@enumerate 1
-@item
-It has been proven in practice (it is already on its second generation).
+@noindent
+At the end, a summary is printed.
-@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{load}.
-@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
+Note: each status message appears on a single line. Here the messages
+have been broken down so that they can fit onto a page.
-@subheading Introduction to Variable Objects in @sc{gdb/mi}
+@smallexample
+(gdb)
+-target-download
++download,@{section=".text",section-size="6668",total-size="9880"@}
++download,@{section=".text",section-sent="512",section-size="6668",
+total-sent="512",total-size="9880"@}
++download,@{section=".text",section-sent="1024",section-size="6668",
+total-sent="1024",total-size="9880"@}
++download,@{section=".text",section-sent="1536",section-size="6668",
+total-sent="1536",total-size="9880"@}
++download,@{section=".text",section-sent="2048",section-size="6668",
+total-sent="2048",total-size="9880"@}
++download,@{section=".text",section-sent="2560",section-size="6668",
+total-sent="2560",total-size="9880"@}
++download,@{section=".text",section-sent="3072",section-size="6668",
+total-sent="3072",total-size="9880"@}
++download,@{section=".text",section-sent="3584",section-size="6668",
+total-sent="3584",total-size="9880"@}
++download,@{section=".text",section-sent="4096",section-size="6668",
+total-sent="4096",total-size="9880"@}
++download,@{section=".text",section-sent="4608",section-size="6668",
+total-sent="4608",total-size="9880"@}
++download,@{section=".text",section-sent="5120",section-size="6668",
+total-sent="5120",total-size="9880"@}
++download,@{section=".text",section-sent="5632",section-size="6668",
+total-sent="5632",total-size="9880"@}
++download,@{section=".text",section-sent="6144",section-size="6668",
+total-sent="6144",total-size="9880"@}
++download,@{section=".text",section-sent="6656",section-size="6668",
+total-sent="6656",total-size="9880"@}
++download,@{section=".init",section-size="28",total-size="9880"@}
++download,@{section=".fini",section-size="28",total-size="9880"@}
++download,@{section=".data",section-size="3156",total-size="9880"@}
++download,@{section=".data",section-sent="512",section-size="3156",
+total-sent="7236",total-size="9880"@}
++download,@{section=".data",section-sent="1024",section-size="3156",
+total-sent="7748",total-size="9880"@}
++download,@{section=".data",section-sent="1536",section-size="3156",
+total-sent="8260",total-size="9880"@}
++download,@{section=".data",section-sent="2048",section-size="3156",
+total-sent="8772",total-size="9880"@}
++download,@{section=".data",section-sent="2560",section-size="3156",
+total-sent="9284",total-size="9880"@}
++download,@{section=".data",section-sent="3072",section-size="3156",
+total-sent="9796",total-size="9880"@}
+^done,address="0x10004",load-size="9880",transfer-rate="6586",
+write-rate="429"
+(gdb)
+@end smallexample
-@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.
+@subheading The @code{-target-exec-status} Command
+@findex -target-exec-status
-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.).
+@subsubheading Synopsis
-The following is the complete set of @sc{gdb/mi} operations defined to
-access this functionality:
+@smallexample
+ -target-exec-status
+@end smallexample
-@multitable @columnfractions .4 .6
-@item @strong{Operation}
-@tab @strong{Description}
+Provide information on the state of the target (whether it is running or
+not, for instance).
-@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
+@subsubheading @value{GDBN} Command
-In the next subsection we describe each operation in detail and suggest
-how it can be used.
+There's no equivalent @value{GDBN} command.
-@subheading Description And Use of Operations on Variable Objects
+@subsubheading Example
+N.A.
-@subheading The @code{-var-create} Command
-@findex -var-create
+
+@subheading The @code{-target-list-available-targets} Command
+@findex -target-list-available-targets
@subsubheading Synopsis
@smallexample
- -var-create @{@var{name} | "-"@}
- @{@var{frame-addr} | "*"@} @var{expression}
+ -target-list-available-targets
@end smallexample
-This operation creates a variable object, which allows the monitoring of
-a variable, the result of an expression, a memory cell or a CPU
-register.
-
-The @var{name} parameter is the string by which the object can be
-referenced. It must be unique. If @samp{-} is specified, the varobj
-system will generate a string ``varNNNNNN'' automatically. It will be
-unique provided that one does not specify @var{name} on that format.
-The command fails if a duplicate name is found.
-
-The frame under which the expression should be evaluated can be
-specified by @var{frame-addr}. A @samp{*} indicates that the current
-frame should be used.
+List the possible targets to connect to.
-@var{expression} is any expression valid on the current language set (must not
-begin with a @samp{*}), or one of the following:
+@subsubheading @value{GDBN} Command
-@itemize @bullet
-@item
-@samp{*@var{addr}}, where @var{addr} is the address of a memory cell
+The corresponding @value{GDBN} command is @samp{help target}.
-@item
-@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
+@subsubheading Example
+N.A.
-@item
-@samp{$@var{regname}} --- a CPU register name
-@end itemize
-@subsubheading Result
+@subheading The @code{-target-list-current-targets} Command
+@findex -target-list-current-targets
-This operation returns the name, number of children and the type of the
-object created. Type is returned as a string as the ones generated by
-the @value{GDBN} CLI:
+@subsubheading Synopsis
@smallexample
- name="@var{name}",numchild="N",type="@var{type}"
+ -target-list-current-targets
@end smallexample
+Describe the current target.
-@subheading The @code{-var-delete} Command
-@findex -var-delete
+@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
- -var-delete @var{name}
+ -target-list-parameters
@end smallexample
-Deletes a previously created variable object and all of its children.
+@c ????
-Returns an error if the object @var{name} is not found.
+@subsubheading @value{GDBN} Command
+No equivalent.
+
+@subsubheading Example
+N.A.
-@subheading The @code{-var-set-format} Command
-@findex -var-set-format
+
+@subheading The @code{-target-select} Command
+@findex -target-select
@subsubheading Synopsis
@smallexample
- -var-set-format @var{name} @var{format-spec}
+ -target-select @var{type} @var{parameters @dots{}}
@end smallexample
-Sets the output format for the value of the object @var{name} to be
-@var{format-spec}.
+Connect @value{GDBN} to the remote target. This command takes two args:
-The syntax for the @var{format-spec} is as follows:
+@table @samp
+@item @var{type}
+The type of target, for instance @samp{async}, @samp{remote}, etc.
+@item @var{parameters}
+Device names, host names and the like. @xref{Target Commands, ,
+Commands for managing targets}, for more details.
+@end table
+
+The output is a connection notification, followed by the address at
+which the target program is, in the following form:
@smallexample
- @var{format-spec} @expansion{}
- @{binary | decimal | hexadecimal | octal | natural@}
+^connected,addr="@var{address}",func="@var{function name}",
+ args=[@var{arg list}]
@end smallexample
+@subsubheading @value{GDBN} Command
-@subheading The @code{-var-show-format} Command
-@findex -var-show-format
+The corresponding @value{GDBN} command is @samp{target}.
-@subsubheading Synopsis
+@subsubheading Example
@smallexample
- -var-show-format @var{name}
+(gdb)
+-target-select async /dev/ttya
+^connected,addr="0xfe00a300",func="??",args=[]
+(gdb)
@end smallexample
-Returns the format used to display the value of the object @var{name}.
-
-@smallexample
- @var{format} @expansion{}
- @var{format-spec}
-@end smallexample
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Miscellaneous Commands
+@section Miscellaneous @sc{gdb/mi} Commands
+@c @subheading -gdb-complete
-@subheading The @code{-var-info-num-children} Command
-@findex -var-info-num-children
+@subheading The @code{-gdb-exit} Command
+@findex -gdb-exit
@subsubheading Synopsis
@smallexample
- -var-info-num-children @var{name}
+ -gdb-exit
@end smallexample
-Returns the number of children of a variable object @var{name}:
+Exit @value{GDBN} immediately.
+
+@subsubheading @value{GDBN} Command
+
+Approximately corresponds to @samp{quit}.
+
+@subsubheading Example
@smallexample
- numchild=@var{n}
+(gdb)
+-gdb-exit
+^exit
@end smallexample
-@subheading The @code{-var-list-children} Command
-@findex -var-list-children
+@subheading The @code{-exec-abort} Command
+@findex -exec-abort
@subsubheading Synopsis
@smallexample
- -var-list-children [@var{print-values}] @var{name}
+ -exec-abort
@end smallexample
-Returns a list of the children of the specified variable object. With
-just the variable object name as an argument or with an optional
-preceding argument of 0 or @code{--no-values}, prints only the names of the
-variables. With an optional preceding argument of 1 or @code{--all-values},
-also prints their values.
+Kill the inferior running program.
-@subsubheading Example
+@subsubheading @value{GDBN} Command
-@smallexample
-(@value{GDBP})
- -var-list-children n
- 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
- numchild=@var{n},children=[@{name=@var{name},
- numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
-@end smallexample
+The corresponding @value{GDBN} command is @samp{kill}.
+
+@subsubheading Example
+N.A.
-@subheading The @code{-var-info-type} Command
-@findex -var-info-type
+@subheading The @code{-gdb-set} Command
+@findex -gdb-set
@subsubheading Synopsis
@smallexample
- -var-info-type @var{name}
+ -gdb-set
@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:
+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
- type=@var{typename}
+(gdb)
+-gdb-set $foo=3
+^done
+(gdb)
@end smallexample
-@subheading The @code{-var-info-expression} Command
-@findex -var-info-expression
+@subheading The @code{-gdb-show} Command
+@findex -gdb-show
@subsubheading Synopsis
@smallexample
- -var-info-expression @var{name}
+ -gdb-show
@end smallexample
-Returns what is represented by the variable object @var{name}:
+Show the current value of a @value{GDBN} variable.
+
+@subsubheading @value{GDBN} command
+
+The corresponding @value{GDBN} command is @samp{show}.
+
+@subsubheading Example
@smallexample
- lang=@var{lang-spec},exp=@var{expression}
+(gdb)
+-gdb-show annotate
+^done,value="0"
+(gdb)
@end smallexample
-@noindent
-where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
+@c @subheading -gdb-source
-@subheading The @code{-var-show-attributes} Command
-@findex -var-show-attributes
+
+@subheading The @code{-gdb-version} Command
+@findex -gdb-version
@subsubheading Synopsis
@smallexample
- -var-show-attributes @var{name}
+ -gdb-version
@end smallexample
-List attributes of the specified variable object @var{name}:
+Show version information for @value{GDBN}. Used mostly in testing.
+
+@subsubheading @value{GDBN} Command
+
+The @value{GDBN} equivalent is @samp{show version}. @value{GDBN} by
+default shows this information when you start an interactive session.
+
+@subsubheading Example
+@c This example modifies the actual output from GDB to avoid overfull
+@c box in TeX.
@smallexample
- status=@var{attr} [ ( ,@var{attr} )* ]
+(gdb)
+-gdb-version
+~GNU gdb 5.2.1
+~Copyright 2000 Free Software Foundation, Inc.
+~GDB is free software, covered by the GNU General Public License, and
+~you are welcome to change it and/or distribute copies of it under
+~ certain conditions.
+~Type "show copying" to see the conditions.
+~There is absolutely no warranty for GDB. Type "show warranty" for
+~ details.
+~This GDB was configured as
+ "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
+^done
+(gdb)
@end smallexample
-@noindent
-where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
-
-@subheading The @code{-var-evaluate-expression} Command
-@findex -var-evaluate-expression
+@subheading The @code{-interpreter-exec} Command
+@findex -interpreter-exec
-@subsubheading Synopsis
+@subheading Synopsis
@smallexample
- -var-evaluate-expression @var{name}
+-interpreter-exec @var{interpreter} @var{command}
@end smallexample
+@anchor{-interpreter-exec}
-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:
+Execute the specified @var{command} in the given @var{interpreter}.
+
+@subheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{interpreter-exec}.
+
+@subheading Example
@smallexample
- value=@var{value}
+(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
-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-set} Command
+@findex -inferior-tty-set
-@subsubheading Synopsis
+@subheading Synopsis
@smallexample
- -var-assign @var{name} @var{expression}
+-inferior-tty-set /dev/pts/1
@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.
+Set terminal for future runs of the program being debugged.
+
+@subheading @value{GDBN} Command
-@subsubheading Example
+The corresponding @value{GDBN} command is @samp{set inferior-tty} /dev/pts/1.
+
+@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)
@end smallexample
-@subheading The @code{-var-update} Command
-@findex -var-update
+@subheading The @code{-inferior-tty-show} Command
+@findex -inferior-tty-show
-@subsubheading Synopsis
+@subheading Synopsis
@smallexample
- -var-update @{@var{name} | "*"@}
+-inferior-tty-show
@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.
+Show terminal for future runs of program being debugged.
+
+@subheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{show inferior-tty}.
+@subheading Example
+
+@smallexample
+(gdb)
+-inferior-tty-set /dev/pts/1
+^done
+(gdb)
+-inferior-tty-show
+^done,inferior_tty_terminal="/dev/pts/1"
+(gdb)
+@end smallexample
@node Annotations
@chapter @value{GDBN} Annotations
@menu
* Annotations Overview:: What annotations are; the general syntax.
-* Server Prefix:: Issuing a command without affecting user state.
* Prompting:: Annotations marking @value{GDBN}'s need for input.
* Errors:: Annotations for error messages.
* Invalidation:: Some annotations describe things now invalid.
denotes a @samp{control-z} character) are annotations; the rest is
output from @value{GDBN}.
-@node Server Prefix
-@section The Server Prefix
-@cindex server prefix for annotations
-
-To issue a command to @value{GDBN} without affecting certain aspects of
-the state which is seen by users, prefix it with @samp{server }. This
-means that this command will not affect the command history, nor will it
-affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
-pressed on a line by itself.
-
-The server prefix does not affect the recording of values into the value
-history; to print a value without recording it into the value history,
-use the @code{output} command instead of the @code{print} command.
-
@node Prompting
@section Annotation for @value{GDBN} Input
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
+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
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
@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
+@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 currently only used to implement some remote-specific
+features.
+
+@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
* Stop Reply Packets::
* General Query Packets::
* Register Packet Format::
+* Tracepoint Packets::
+* Interrupts::
* Examples::
* File-I/O remote protocol extension::
@end menu
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
@xref{File-I/O remote protocol extension}, for details about the File
I/O extension of the remote protocol.
-@table @r
+Each packet's description has a template showing the packet's overall
+syntax, followed by an explanation of the packet's meaning. We
+include spaces in some of the templates for clarity; these are not
+part of the packet's syntax. No @value{GDBN} packet uses spaces to
+separate its components. For example, a template like @samp{foo
+@var{bar} @var{baz}} describes a packet beginning with the three ASCII
+bytes @samp{foo}, followed by a @var{bar}, followed directly by a
+@var{baz}. GDB does not transmit a space character between the
+@samp{foo} and the @var{bar}, or between the @var{bar} and the
+@var{baz}.
+
+Note that all packet forms beginning with an upper- or lower-case
+letter, other than those described here, are reserved for future use.
-@item @code{!} --- extended mode
-@cindex @code{!} packet
+Here are the packet descriptions.
+
+@table @samp
+@item !
+@cindex @samp{!} packet
Enable extended mode. In extended mode, the remote server is made
persistent. The @samp{R} packet is used to restart the program being
debugged.
The remote target both supports and has enabled extended mode.
@end table
-@item @code{?} --- last signal
-@cindex @code{?} packet
-
+@item ?
+@cindex @samp{?} packet
Indicate the reason the target halted. The reply is the same as for
step and continue.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item @code{a} --- reserved
-
-Reserved for future use.
-
-@item @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,@dots{}} --- set program arguments @strong{(reserved)}
-@cindex @code{A} packet
-
-Initialized @samp{argv[]} array passed into program. @var{arglen}
-specifies the number of bytes in the hex encoded byte stream @var{arg}.
-See @code{gdbserver} for more details.
+@item A @var{arglen},@var{argnum},@var{arg},@dots{}
+@cindex @samp{A} packet
+Initialized @code{argv[]} array passed into program. @var{arglen}
+specifies the number of bytes in the hex encoded byte stream
+@var{arg}. See @code{gdbserver} for more details.
Reply:
@table @samp
@item OK
-@item E@var{NN}
+The arguments were set.
+@item E @var{NN}
+An error occurred.
@end table
-@item @code{b}@var{baud} --- set baud @strong{(deprecated)}
-@cindex @code{b} packet
-
+@item b @var{baud}
+@cindex @samp{b} packet
+(Don't use this packet; its behavior is not well-defined.)
Change the serial line speed to @var{baud}.
JTC: @emph{When does the transport layer state change? When it's
switch happen "in between" packets, so that from remote protocol's point
of view, nothing actually happened.}
-@item @code{B}@var{addr},@var{mode} --- set breakpoint @strong{(deprecated)}
-@cindex @code{B} packet
-
+@item B @var{addr},@var{mode}
+@cindex @samp{B} packet
Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
breakpoint at @var{addr}.
-This packet has been replaced by the @samp{Z} and @samp{z} packets
+Don't use this packet. Use the @samp{Z} and @samp{z} packets instead
(@pxref{insert breakpoint or watchpoint packet}).
-@item @code{c}@var{addr} --- continue
-@cindex @code{c} packet
-
-@var{addr} is address to resume. If @var{addr} is omitted, resume at
-current address.
+@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 @code{C}@var{sig}@code{;}@var{addr} --- continue with signal
-@cindex @code{C} packet
-
+@item C @var{sig}@r{[};@var{addr}@r{]}
+@cindex @samp{C} packet
Continue with signal @var{sig} (hex signal number). If
-@code{;}@var{addr} is omitted, resume at same address.
+@samp{;@var{addr}} is omitted, resume at same address.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item @code{d} --- toggle debug @strong{(deprecated)}
-@cindex @code{d} packet
-
+@item d
+@cindex @samp{d} packet
Toggle debug flag.
-@item @code{D} --- detach
-@cindex @code{D} packet
+Don't use this packet; instead, define a general set packet
+(@pxref{General Query Packets}).
+@item D
+@cindex @samp{D} packet
Detach @value{GDBN} from the remote system. Sent to the remote target
before @value{GDBN} disconnects via the @code{detach} command.
Reply:
@table @samp
-@item @emph{no response}
-@value{GDBN} does not check for any response after sending this packet.
+@item OK
+for success
+@item E @var{NN}
+for an error
@end table
-@item @code{e} --- reserved
-
-Reserved for future use.
-
-@item @code{E} --- reserved
-
-Reserved for future use.
-
-@item @code{f} --- reserved
-
-Reserved for future use.
+@item F @var{RC},@var{EE},@var{CF};@var{XX}
+@cindex @samp{F} packet
+A reply from @value{GDBN} to an @samp{F} packet sent by the target.
+This is part of the File-I/O protocol extension. @xref{File-I/O
+remote protocol extension}, for the specification.
-@item @code{F}@var{RC}@code{,}@var{EE}@code{,}@var{CF}@code{;}@var{XX} --- Reply to target's F packet.
-@cindex @code{F} packet
-
-This packet is send by @value{GDBN} as reply to a @code{F} request packet
-sent by the target. This is part of the File-I/O protocol extension.
-@xref{File-I/O remote protocol extension}, for the specification.
-
-@item @code{g} --- read registers
+@item g
@anchor{read registers packet}
-@cindex @code{g} packet
-
+@cindex @samp{g} packet
Read general registers.
Reply:
@item @var{XX@dots{}}
Each byte of register data is described by two hex digits. The bytes
with the register are transmitted in target byte order. The size of
-each register and their position within the @samp{g} @var{packet} are
+each register and their position within the @samp{g} packet are
determined by the @value{GDBN} internal macros
-@var{DEPRECATED_REGISTER_RAW_SIZE} and @var{REGISTER_NAME} macros. The
-specification of several standard @code{g} packets is specified below.
-@item E@var{NN}
+@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{REGISTER_NAME} macros. The
+specification of several standard @samp{g} packets is specified below.
+@item E @var{NN}
for an error.
@end table
-@item @code{G}@var{XX@dots{}} --- write regs
-@cindex @code{G} packet
-
-@xref{read registers packet}, for a description of the @var{XX@dots{}}
-data.
+@item G @var{XX@dots{}}
+@cindex @samp{G} packet
+Write general registers. @xref{read registers packet}, for a
+description of the @var{XX@dots{}} data.
Reply:
@table @samp
@item OK
for success
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
-@item @code{h} --- reserved
-
-Reserved for future use.
-
-@item @code{H}@var{c}@var{t@dots{}} --- set thread
-@cindex @code{H} packet
-
+@item H @var{c} @var{t}
+@cindex @samp{H} packet
Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
@samp{G}, et.al.). @var{c} depends on the operation to be performed: it
should be @samp{c} for step and continue operations, @samp{g} for other
-operations. The thread designator @var{t@dots{}} may be -1, meaning all
-the threads, a thread number, or zero which means pick any thread.
+operations. The thread designator @var{t} may be @samp{-1}, meaning all
+the threads, a thread number, or @samp{0} which means pick any thread.
Reply:
@table @samp
@item OK
for success
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
@c selected, sets the registers of the register block of
@c that thread; otherwise sets current registers.
-@item @code{i}@var{addr}@code{,}@var{nnn} --- cycle step @strong{(draft)}
+@item i @r{[}@var{addr}@r{[},@var{nnn}@r{]]}
@anchor{cycle step packet}
-@cindex @code{i} packet
-
-Step the remote target by a single clock cycle. If @code{,}@var{nnn} is
+@cindex @samp{i} packet
+Step the remote target by a single clock cycle. If @samp{,@var{nnn}} is
present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
step starting at that address.
-@item @code{I} --- signal then cycle step @strong{(reserved)}
-@cindex @code{I} packet
-
-@xref{step with signal packet}. @xref{cycle step packet}.
-
-@item @code{j} --- reserved
+@item I
+@cindex @samp{I} packet
+Signal, then cycle step. @xref{step with signal packet}. @xref{cycle
+step packet}.
-Reserved for future use.
-
-@item @code{J} --- reserved
-
-Reserved for future use.
-
-@item @code{k} --- kill request
-@cindex @code{k} packet
+@item k
+@cindex @samp{k} packet
+Kill request.
FIXME: @emph{There is no description of how to operate when a specific
thread context has been selected (i.e.@: does 'k' kill only that
thread?)}.
-@item @code{K} --- reserved
-
-Reserved for future use.
-
-@item @code{l} --- reserved
-
-Reserved for future use.
-
-@item @code{L} --- reserved
-
-Reserved for future use.
-
-@item @code{m}@var{addr}@code{,}@var{length} --- read memory
-@cindex @code{m} packet
-
+@item m @var{addr},@var{length}
+@cindex @samp{m} packet
Read @var{length} bytes of memory starting at address @var{addr}.
-Neither @value{GDBN} nor the stub assume that sized memory transfers are
-assumed using word aligned accesses. FIXME: @emph{A word aligned memory
-transfer mechanism is needed.}
+Note that @var{addr} may not be aligned to any particular boundary.
+
+The stub need not use any particular size or alignment when gathering
+data from memory for the response; even if @var{addr} is word-aligned
+and @var{length} is a multiple of the word size, the stub is free to
+use byte accesses, or not. For this reason, this packet may not be
+suitable for accessing memory-mapped I/O devices.
+@cindex alignment of remote memory accesses
+@cindex size of remote memory accesses
+@cindex memory, alignment and size of remote accesses
Reply:
@table @samp
@item @var{XX@dots{}}
-@var{XX@dots{}} is mem contents. Can be fewer bytes than requested if able
-to read only part of the data. Neither @value{GDBN} nor the stub assume
-that sized memory transfers are assumed using word aligned
-accesses. FIXME: @emph{A word aligned memory transfer mechanism is
-needed.}
-@item E@var{NN}
+Memory contents; each byte is transmitted as a two-digit hexidecimal
+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}
@var{NN} is errno
@end table
-@item @code{M}@var{addr},@var{length}@code{:}@var{XX@dots{}} --- write mem
-@cindex @code{M} packet
-
+@item M @var{addr},@var{length}:@var{XX@dots{}}
+@cindex @samp{M} packet
Write @var{length} bytes of memory starting at address @var{addr}.
-@var{XX@dots{}} is the data.
+@var{XX@dots{}} is the data; each byte is transmitted as a two-digit
+hexidecimal number.
Reply:
@table @samp
@item OK
for success
-@item E@var{NN}
+@item E @var{NN}
for an error (this includes the case where only part of the data was
written).
@end table
-@item @code{n} --- reserved
-
-Reserved for future use.
-
-@item @code{N} --- reserved
-
-Reserved for future use.
-
-@item @code{o} --- reserved
-
-Reserved for future use.
-
-@item @code{O} --- reserved
-
-@item @code{p}@var{hex number of register} --- read register packet
-@cindex @code{p} packet
-
+@item p @var{n}
+@cindex @samp{p} packet
+Read the value of register @var{n}; @var{n} is in hex.
@xref{read registers packet}, for a description of how the returned
register value is encoded.
@table @samp
@item @var{XX@dots{}}
the register's value
-@item E@var{NN}
+@item E @var{NN}
for an error
@item
Indicating an unrecognized @var{query}.
@end table
-@item @code{P}@var{n@dots{}}@code{=}@var{r@dots{}} --- write register
+@item P @var{n@dots{}}=@var{r@dots{}}
@anchor{write register packet}
-@cindex @code{P} packet
-
-Write register @var{n@dots{}} with value @var{r@dots{}}, which contains two hex
+@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
digits for each byte in the register (target byte order).
Reply:
@table @samp
@item OK
for success
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
-@item @code{q}@var{query} --- general query
-@anchor{general query packet}
-@cindex @code{q} packet
-
-Request info about @var{query}. In general @value{GDBN} queries have a
-leading upper case letter. Custom vendor queries should use a company
-prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may optionally
-be followed by a @samp{,} or @samp{;} separated list. Stubs must ensure
-that they match the full @var{query} name.
-
-Reply:
-@table @samp
-@item @var{XX@dots{}}
-Hex encoded data from query. The reply can not be empty.
-@item E@var{NN}
-error reply
-@item
-Indicating an unrecognized @var{query}.
-@end table
-
-@item @code{Q}@var{var}@code{=}@var{val} --- general set
-@cindex @code{Q} packet
-
-Set value of @var{var} to @var{val}.
-
-@xref{general query packet}, for a discussion of naming conventions.
-
-@item @code{r} --- reset @strong{(deprecated)}
-@cindex @code{r} packet
+@item q @var{name} @var{params}@dots{}
+@itemx Q @var{name} @var{params}@dots{}
+@cindex @samp{q} packet
+@cindex @samp{Q} packet
+General query (@samp{q}) and set (@samp{Q}). These packets are
+described fully in @ref{General Query Packets}.
+@item r
+@cindex @samp{r} packet
Reset the entire system.
-@item @code{R}@var{XX} --- remote restart
-@cindex @code{R} packet
+Don't use this packet; use the @samp{R} packet instead.
+@item R @var{XX}
+@cindex @samp{R} packet
Restart the program being debugged. @var{XX}, while needed, is ignored.
This packet is only available in extended mode.
-Reply:
-@table @samp
-@item @emph{no reply}
The @samp{R} packet has no reply.
-@end table
-
-@item @code{s}@var{addr} --- step
-@cindex @code{s} packet
-@var{addr} is address to resume. If @var{addr} is omitted, resume at
-same address.
+@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 @code{S}@var{sig}@code{;}@var{addr} --- step with signal
+@item S @var{sig}@r{[};@var{addr}@r{]}
@anchor{step with signal packet}
-@cindex @code{S} packet
-
-Like @samp{C} but step not continue.
+@cindex @samp{S} packet
+Step with signal. This is analogous to the @samp{C} packet, but
+requests a single-step, rather than a normal resumption of execution.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} --- search
-@cindex @code{t} packet
-
+@item t @var{addr}:@var{PP},@var{MM}
+@cindex @samp{t} packet
Search backwards starting at address @var{addr} for a match with pattern
@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes.
@var{addr} must be at least 3 digits.
-@item @code{T}@var{XX} --- thread alive
-@cindex @code{T} packet
-
+@item T @var{XX}
+@cindex @samp{T} packet
Find out if the thread XX is alive.
Reply:
@table @samp
@item OK
thread is still alive
-@item E@var{NN}
+@item E @var{NN}
thread is dead
@end table
-@item @code{u} --- reserved
-
-Reserved for future use.
-
-@item @code{U} --- reserved
-
-Reserved for future use.
-
-@item @code{v} --- verbose packet prefix
-
-Packets starting with @code{v} are identified by a multi-letter name,
-up to the first @code{;} or @code{?} (or the end of the packet).
-
-@item @code{vCont}[;@var{action}[@code{:}@var{tid}]]... --- extended resume
-@cindex @code{vCont} packet
+@item v
+Packets starting with @samp{v} are identified by a multi-letter name,
+up to the first @samp{;} or @samp{?} (or the end of the packet).
-Resume the inferior. Different actions may be specified for each thread.
+@item vCont@r{[};@var{action}@r{[}:@var{tid}@r{]]}@dots{}
+@cindex @samp{vCont} packet
+Resume the inferior, specifying different actions for each thread.
If an action is specified with no @var{tid}, then it is applied to any
threads that don't have a specific action specified; if no default action is
specified then other threads should remain stopped. Specifying multiple
default actions is an error; specifying no actions is also an error.
Thread IDs are specified in hexadecimal. Currently supported actions are:
-@table @code
+@table @samp
@item c
Continue.
-@item C@var{sig}
+@item C @var{sig}
Continue with signal @var{sig}. @var{sig} should be two hex digits.
@item s
Step.
-@item S@var{sig}
+@item S @var{sig}
Step with signal @var{sig}. @var{sig} should be two hex digits.
@end table
The optional @var{addr} argument normally associated with these packets is
-not supported in @code{vCont}.
+not supported in @samp{vCont}.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item @code{vCont?} --- extended resume query
-@cindex @code{vCont?} packet
-
-Query support for the @code{vCont} packet.
+@item vCont?
+@cindex @samp{vCont?} packet
+Request a list of actions supporetd by the @samp{vCont} packet.
Reply:
@table @samp
-@item @code{vCont}[;@var{action}]...
-The @code{vCont} packet is supported. Each @var{action} is a supported
-command in the @code{vCont} packet.
+@item vCont@r{[};@var{action}@dots{}@r{]}
+The @samp{vCont} packet is supported. Each @var{action} is a supported
+command in the @samp{vCont} packet.
@item
-The @code{vCont} packet is not supported.
+The @samp{vCont} packet is not supported.
@end table
-@item @code{V} --- reserved
-
-Reserved for future use.
-
-@item @code{w} --- reserved
-
-Reserved for future use.
-
-@item @code{W} --- reserved
-
-Reserved for future use.
-
-@item @code{x} --- reserved
-
-Reserved for future use.
-
-@item @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX@dots{}} --- write mem (binary)
-@cindex @code{X} packet
-
-@var{addr} is address, @var{length} is number of bytes, @var{XX@dots{}}
-is binary data. The characters @code{$}, @code{#}, and @code{0x7d} are
-escaped using @code{0x7d}, and then XORed with @code{0x20}.
-For example, @code{0x7d} would be transmitted as @code{0x7d 0x5d}.
+@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 (@pxref{Binary Data}).
Reply:
@table @samp
@item OK
for success
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
-@item @code{y} --- reserved
-
-Reserved for future use.
-
-@item @code{Y} reserved
-
-Reserved for future use.
-
-@item @code{z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- remove breakpoint or watchpoint @strong{(draft)}
-@itemx @code{Z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- insert breakpoint or watchpoint @strong{(draft)}
+@item z @var{type},@var{addr},@var{length}
+@itemx Z @var{type},@var{addr},@var{length}
@anchor{insert breakpoint or watchpoint packet}
-@cindex @code{z} packet
-@cindex @code{Z} packets
-
-Insert (@code{Z}) or remove (@code{z}) a @var{type} breakpoint or
+@cindex @samp{z} packet
+@cindex @samp{Z} packets
+Insert (@samp{Z}) or remove (@samp{z}) a @var{type} breakpoint or
watchpoint starting at address @var{address} and covering the next
@var{length} bytes.
@emph{Implementation notes: A remote target shall return an empty string
for an unrecognized breakpoint or watchpoint packet @var{type}. A
remote target shall support either both or neither of a given
-@code{Z}@var{type}@dots{} and @code{z}@var{type}@dots{} packet pair. To
+@samp{Z@var{type}@dots{}} and @samp{z@var{type}@dots{}} packet pair. To
avoid potential problems with duplicate packets, the operations should
be implemented in an idempotent way.}
-@item @code{z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- remove memory breakpoint @strong{(draft)}
-@item @code{Z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- insert memory breakpoint @strong{(draft)}
-@cindex @code{z0} packet
-@cindex @code{Z0} packet
-
-Insert (@code{Z0}) or remove (@code{z0}) a memory breakpoint at address
-@code{addr} of size @code{length}.
+@item z0,@var{addr},@var{length}
+@itemx Z0,@var{addr},@var{length}
+@cindex @samp{z0} packet
+@cindex @samp{Z0} packet
+Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
+@var{addr} of size @var{length}.
A memory breakpoint is implemented by replacing the instruction at
@var{addr} with a software breakpoint or trap instruction. The
-@code{length} is used by targets that indicates the size of the
+@var{length} is used by targets that indicates the size of the
breakpoint (in bytes) that should be inserted (e.g., the @sc{arm} and
@sc{mips} can insert either a 2 or 4 byte breakpoint).
success
@item
not supported
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
-@item @code{z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- remove hardware breakpoint @strong{(draft)}
-@item @code{Z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- insert hardware breakpoint @strong{(draft)}
-@cindex @code{z1} packet
-@cindex @code{Z1} packet
-
-Insert (@code{Z1}) or remove (@code{z1}) a hardware breakpoint at
-address @code{addr} of size @code{length}.
+@item z1,@var{addr},@var{length}
+@itemx Z1,@var{addr},@var{length}
+@cindex @samp{z1} packet
+@cindex @samp{Z1} packet
+Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
+address @var{addr} of size @var{length}.
A hardware breakpoint is implemented using a mechanism that is not
dependant on being able to modify the target's memory.
success
@item
not supported
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
-@item @code{z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- remove write watchpoint @strong{(draft)}
-@item @code{Z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- insert write watchpoint @strong{(draft)}
-@cindex @code{z2} packet
-@cindex @code{Z2} packet
-
-Insert (@code{Z2}) or remove (@code{z2}) a write watchpoint.
+@item z2,@var{addr},@var{length}
+@itemx Z2,@var{addr},@var{length}
+@cindex @samp{z2} packet
+@cindex @samp{Z2} packet
+Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint.
Reply:
@table @samp
success
@item
not supported
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
-@item @code{z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- remove read watchpoint @strong{(draft)}
-@item @code{Z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- insert read watchpoint @strong{(draft)}
-@cindex @code{z3} packet
-@cindex @code{Z3} packet
-
-Insert (@code{Z3}) or remove (@code{z3}) a read watchpoint.
+@item z3,@var{addr},@var{length}
+@itemx Z3,@var{addr},@var{length}
+@cindex @samp{z3} packet
+@cindex @samp{Z3} packet
+Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint.
Reply:
@table @samp
success
@item
not supported
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
-@item @code{z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- remove access watchpoint @strong{(draft)}
-@item @code{Z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- insert access watchpoint @strong{(draft)}
-@cindex @code{z4} packet
-@cindex @code{Z4} packet
-
-Insert (@code{Z4}) or remove (@code{z4}) an access watchpoint.
+@item z4,@var{addr},@var{length}
+@itemx Z4,@var{addr},@var{length}
+@cindex @samp{z4} packet
+@cindex @samp{Z4} packet
+Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint.
Reply:
@table @samp
success
@item
not supported
-@item E@var{NN}
+@item E @var{NN}
for an error
@end table
The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can
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 @samp{signal
-number} is poorly defined. In general one of the UNIX signal numbering
-conventions is used.
-
-@table @samp
+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.
-@item S@var{AA}
-@var{AA} is the signal number
+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
+syntax. No @value{GDBN} stop reply packet uses spaces to separate its
+components.
-@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}
-@cindex @code{T} packet reply
-
-@var{AA} = two hex digit signal number; @var{n...} = register number
-(hex), @var{r...} = target byte ordered register contents, size defined
-by @code{DEPRECATED_REGISTER_RAW_SIZE}; @var{n...} = @samp{thread},
-@var{r...} = thread process ID, this is a hex integer; @var{n...} =
-(@samp{watch} | @samp{rwatch} | @samp{awatch}, @var{r...} = data
-address, this is a hex integer; @var{n...} = other string not starting
-with valid hex digit. @value{GDBN} should ignore this @var{n...},
-@var{r...} pair and go on to the next. This way we can extend the
-protocol.
+@table @samp
-@item W@var{AA}
+@item S @var{AA}
+The program received signal number @var{AA} (a two-digit hexidecimal
+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). 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
+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.
+@item
+If @var{n} is @samp{thread}, then @var{r} is the thread process ID, in
+hex.
+@item
+If @var{n} is @samp{watch}, @samp{rwatch}, or @samp{awatch}, then the
+packet indicates a watchpoint hit, and @var{r} is the data address, in
+hex.
+@item
+Otherwise, @value{GDBN} should ignore this @samp{@var{n}:@var{r}} pair
+and go on to the next; this allows us to extend the protocol in the
+future.
+@end enumerate
+@item W @var{AA}
The process exited, and @var{AA} is the exit status. This is only
applicable to certain targets.
-@item X@var{AA}
-
+@item X @var{AA}
The process terminated with signal @var{AA}.
-@item O@var{XX@dots{}}
-
-@var{XX@dots{}} is hex encoding of @sc{ascii} data. This can happen at
-any time while the program is running and the debugger should continue
-to wait for @samp{W}, @samp{T}, etc.
-
-@item F@var{call-id}@code{,}@var{parameter@dots{}}
+@item O @var{XX}@dots{}
+@samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be
+written as the program's console output. This can happen at any time
+while the program is running and the debugger should continue to wait
+for @samp{W}, @samp{T}, etc.
+@item F @var{call-id},@var{parameter}@dots{}
@var{call-id} is the identifier which says which host system call should
be called. This is just the name of the function. Translation into the
correct system call is only applicable as it's defined in @value{GDBN}.
@xref{File-I/O remote protocol extension}, for a list of implemented
system calls.
-@var{parameter@dots{}} is a list of parameters as defined for this very
-system call.
+@samp{@var{parameter}@dots{}} is a list of parameters as defined for
+this very system call.
-The target replies with this packet when it expects @value{GDBN} to call
-a host system call on behalf of the target. @value{GDBN} replies with
-an appropriate @code{F} packet and keeps up waiting for the next reply
-packet from the target. The latest @samp{C}, @samp{c}, @samp{S} or
-@samp{s} action is expected to be continued.
-@xref{File-I/O remote protocol extension}, for more details.
+The target replies with this packet when it expects @value{GDBN} to
+call a host system call on behalf of the target. @value{GDBN} replies
+with an appropriate @samp{F} packet and keeps up waiting for the next
+reply packet from the target. The latest @samp{C}, @samp{c}, @samp{S}
+or @samp{s} action is expected to be continued. @xref{File-I/O remote
+protocol extension}, for more details.
@end table
@section General Query Packets
@cindex remote query requests
-The following set and query packets have already been defined.
+Packets starting with @samp{q} are @dfn{general query packets};
+packets starting with @samp{Q} are @dfn{general set packets}. General
+query and set packets are a semi-unified form for retrieving and
+sending information to and from the stub.
-@table @r
+The initial letter of a query or set packet is followed by a name
+indicating what sort of thing the packet applies to. For example,
+@value{GDBN} may use a @samp{qSymbol} packet to exchange symbol
+definitions with the stub. These packet names follow some
+conventions:
+
+@itemize @bullet
+@item
+The name must not contain commas, colons or semicolons.
+@item
+Most @value{GDBN} query and set packets have a leading upper case
+letter.
+@item
+The names of custom vendor packets should use a company prefix, in
+lower case, followed by a period. For example, packets designed at
+the Acme Corporation might begin with @samp{qacme.foo} (for querying
+foos) or @samp{Qacme.bar} (for setting bars).
+@end itemize
-@item @code{q}@code{C} --- current thread
+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
+explanation of the packet's meaning. We include spaces in some of the
+templates for clarity; these are not part of the packet's syntax. No
+@value{GDBN} packet uses spaces to separate its components.
+
+Here are the currently defined query and set packets:
+
+@table @samp
+
+@item qC
@cindex current thread, remote request
-@cindex @code{qC} packet
+@cindex @samp{qC} packet
Return the current thread id.
Reply:
@table @samp
-@item @code{QC}@var{pid}
+@item QC @var{pid}
Where @var{pid} is an unsigned hexidecimal process id.
-@item *
+@item @r{(anything else)}
Any other reply implies the old pid.
@end table
-@item @code{q}@code{fThreadInfo} -- all thread ids
-@cindex list active threads, remote request
-@cindex @code{qfThreadInfo} packet
-@code{q}@code{sThreadInfo}
+@item qCRC:@var{addr},@var{length}
+@cindex CRC of memory block, remote request
+@cindex @samp{qCRC} packet
+Compute the CRC checksum of a block of memory.
+Reply:
+@table @samp
+@item E @var{NN}
+An error (such as memory fault)
+@item C @var{crc32}
+The specified memory region's checksum is @var{crc32}.
+@end table
-Obtain a list of active thread ids from the target (OS). Since there
+@item qfThreadInfo
+@itemx qsThreadInfo
+@cindex list active threads, remote request
+@cindex @samp{qfThreadInfo} packet
+@cindex @samp{qsThreadInfo} packet
+Obtain a list of all active thread ids from the target (OS). Since there
may be too many active threads to fit into one reply packet, this query
works iteratively: it may require more than one query/reply sequence to
obtain the entire list of threads. The first query of the sequence will
-be the @code{qf}@code{ThreadInfo} query; subsequent queries in the
-sequence will be the @code{qs}@code{ThreadInfo} query.
+be the @samp{qfThreadInfo} query; subsequent queries in the
+sequence will be the @samp{qsThreadInfo} query.
-NOTE: replaces the @code{qL} query (see below).
+NOTE: This packet replaces the @samp{qL} query (see below).
Reply:
@table @samp
-@item @code{m}@var{id}
+@item m @var{id}
A single thread id
-@item @code{m}@var{id},@var{id}@dots{}
+@item m @var{id},@var{id}@dots{}
a comma-separated list of thread ids
-@item @code{l}
-(lower case 'el') denotes end of list.
+@item l
+(lower case letter @samp{L}) denotes end of list.
@end table
In response to each query, the target will reply with a list of one or
more thread ids, in big-endian unsigned hex, separated by commas.
@value{GDBN} will respond to each reply with a request for more thread
-ids (using the @code{qs} form of the query), until the target responds
-with @code{l} (lower-case el, for @code{'last'}).
+ids (using the @samp{qs} form of the query), until the target responds
+with @samp{l} (lower-case el, for @dfn{last}).
-@item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info
-@cindex thread attributes info, remote request
-@cindex @code{qThreadExtraInfo} packet
-Where @var{id} is a thread-id in big-endian hex. Obtain a printable
-string description of a thread's attributes from the target OS. This
-string may contain anything that the target OS thinks is interesting for
-@value{GDBN} to tell the user about the thread. The string is displayed
-in @value{GDBN}'s @samp{info threads} display. Some examples of
-possible thread extra info strings are ``Runnable'', or ``Blocked on
-Mutex''.
+@item qGetTLSAddr:@var{thread-id},@var{offset},@var{lm}
+@cindex get thread-local storage address, remote request
+@cindex @samp{qGetTLSAddr} packet
+Fetch the address associated with thread local storage specified
+by @var{thread-id}, @var{offset}, and @var{lm}.
+
+@var{thread-id} is the (big endian, hex encoded) thread id associated with the
+thread for which to fetch the TLS address.
+
+@var{offset} is the (big endian, hex encoded) offset associated with the
+thread local variable. (This offset is obtained from the debug
+information associated with the variable.)
+
+@var{lm} is the (big endian, hex encoded) OS/ABI specific encoding of the
+the load module associated with the thread local storage. For example,
+a @sc{gnu}/Linux system will pass the link map address of the shared
+object associated with the thread local storage under consideration.
+Other operating environments may choose to represent the load module
+differently, so the precise meaning of this parameter will vary.
Reply:
@table @samp
-@item @var{XX@dots{}}
-Where @var{XX@dots{}} is a hex encoding of @sc{ascii} data, comprising
-the printable string containing the extra information about the thread's
-attributes.
+@item @var{XX}@dots{}
+Hex encoded (big endian) bytes representing the address of the thread
+local storage requested.
+
+@item E @var{nn}
+An error occurred. @var{nn} are hex digits.
+
+@item
+An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
@end table
-@item @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} --- query @var{LIST} or @var{threadLIST} @strong{(deprecated)}
+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
subsequent query; @var{threadcount} (two hex digits) is the maximum
(eight hex digits), for subsequent queries (@var{startflag} is zero), is
returned in the response as @var{argthread}.
-NOTE: this query is replaced by the @code{q}@code{fThreadInfo} query
-(see above).
+Don't use this packet; use the @samp{qfThreadInfo} query instead (see above).
Reply:
@table @samp
-@item @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread@dots{}}
+@item qM @var{count} @var{done} @var{argthread} @var{thread}@dots{}
Where: @var{count} (two hex digits) is the number of threads being
returned; @var{done} (one hex digit) is zero to indicate more threads
and one indicates no further threads; @var{argthreadid} (eight hex
-digits) is @var{nextthread} from the request packet; @var{thread@dots{}}
+digits) is @var{nextthread} from the request packet; @var{thread}@dots{}
is a sequence of thread IDs from the target. @var{threadid} (eight hex
digits). See @code{remote.c:parse_threadlist_response()}.
@end table
-@item @code{q}@code{CRC:}@var{addr}@code{,}@var{length} --- compute CRC of memory block
-@cindex CRC of memory block, remote request
-@cindex @code{qCRC} packet
-Reply:
-@table @samp
-@item @code{E}@var{NN}
-An error (such as memory fault)
-@item @code{C}@var{CRC32}
-A 32 bit cyclic redundancy check of the specified memory region.
-@end table
-
-@item @code{q}@code{Offsets} --- query sect offs
+@item qOffsets
@cindex section offsets, remote request
-@cindex @code{qOffsets} packet
+@cindex @samp{qOffsets} packet
Get section offsets that the target used when re-locating the downloaded
image. @emph{Note: while a @code{Bss} offset is included in the
response, @value{GDBN} ignores this and instead applies the @code{Data}
Reply:
@table @samp
-@item @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
+@item Text=@var{xxx};Data=@var{yyy};Bss=@var{zzz}
@end table
-@item @code{q}@code{P}@var{mode}@var{threadid} --- thread info request
+@item qP @var{mode} @var{threadid}
@cindex thread information, remote request
-@cindex @code{qP} packet
+@cindex @samp{qP} packet
Returns information on @var{threadid}. Where: @var{mode} is a hex
encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
+Don't use this packet; use the @samp{qThreadExtraInfo} query instead
+(see below).
+
+Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
+
+@item qRcmd,@var{command}
+@cindex execute remote command, remote request
+@cindex @samp{qRcmd} packet
+@var{command} (hex encoded) is passed to the local interpreter for
+execution. Invalid commands should be reported using the output
+string. Before the final result packet, the target may also respond
+with a number of intermediate @samp{O@var{output}} console output
+packets. @emph{Implementors should note that providing access to a
+stubs's interpreter may have security implications}.
+
Reply:
@table @samp
-@item *
+@item OK
+A command response with no output.
+@item @var{OUTPUT}
+A command response with the hex encoded output string @var{OUTPUT}.
+@item E @var{NN}
+Indicate a badly formed request.
+@item
+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
-See @code{remote.c:remote_unpack_thread_info_response()}.
+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
+
+@end multitable
-@item @code{q}@code{Rcmd,}@var{command} --- remote command
-@cindex execute remote command, remote request
-@cindex @code{qRcmd} packet
-@var{command} (hex encoded) is passed to the local interpreter for
-execution. Invalid commands should be reported using the output string.
-Before the final result packet, the target may also respond with a
-number of intermediate @code{O}@var{output} console output packets.
-@emph{Implementors should note that providing access to a stubs's
-interpreter may have security implications}.
+These are the currently defined stub features, in more detail:
-Reply:
@table @samp
-@item OK
-A command response with no output.
-@item @var{OUTPUT}
-A command response with the hex encoded output string @var{OUTPUT}.
-@item @code{E}@var{NN}
-Indicate a badly formed request.
-@item @samp{}
-When @samp{q}@samp{Rcmd} is not recognized.
+@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}).
+
@end table
-z
-@item @code{qSymbol::} --- symbol lookup
+
+@item qSymbol::
@cindex symbol lookup, remote request
-@cindex @code{qSymbol} packet
+@cindex @samp{qSymbol} packet
Notify the target that @value{GDBN} is prepared to serve symbol lookup
requests. Accept requests from the target for the values of symbols.
Reply:
@table @samp
-@item @code{OK}
+@item OK
The target does not need to look up any (more) symbols.
-@item @code{qSymbol:}@var{sym_name}
+@item qSymbol:@var{sym_name}
The target requests the value of symbol @var{sym_name} (hex encoded).
@value{GDBN} may provide the value by using the
-@code{qSymbol:}@var{sym_value}:@var{sym_name} message, described below.
+@samp{qSymbol:@var{sym_value}:@var{sym_name}} message, described
+below.
@end table
-@item @code{qSymbol:}@var{sym_value}:@var{sym_name} --- symbol value
-
+@item qSymbol:@var{sym_value}:@var{sym_name}
Set the value of @var{sym_name} to @var{sym_value}.
@var{sym_name} (hex encoded) is the name of a symbol whose value the
Reply:
@table @samp
-@item @code{OK}
+@item OK
The target does not need to look up any (more) symbols.
-@item @code{qSymbol:}@var{sym_name}
+@item qSymbol:@var{sym_name}
The target requests the value of a new symbol @var{sym_name} (hex
encoded). @value{GDBN} will continue to supply the values of symbols
(if available), until the target ceases to request them.
@end table
-@item @code{qPart}:@var{object}:@code{read}:@var{annex}:@var{offset},@var{length} --- read special data
+@item QTDP
+@itemx QTFrame
+@xref{Tracepoint Packets}.
+
+@item qThreadExtraInfo,@var{id}
+@cindex thread attributes info, remote request
+@cindex @samp{qThreadExtraInfo} packet
+Obtain a printable string description of a thread's attributes from
+the target OS. @var{id} is a thread-id in big-endian hex. This
+string may contain anything that the target OS thinks is interesting
+for @value{GDBN} to tell the user about the thread. The string is
+displayed in @value{GDBN}'s @code{info threads} display. Some
+examples of possible thread extra info strings are @samp{Runnable}, or
+@samp{Blocked on Mutex}.
+
+Reply:
+@table @samp
+@item @var{XX}@dots{}
+Where @samp{@var{XX}@dots{}} is a hex encoding of @sc{ascii} data,
+comprising the printable string containing the extra information about
+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 @code{qPart} packet
+@cindex @samp{qXfer} packet
Read uninterpreted bytes from the target's special data area
-identified by the keyword @code{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.
+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{@code{qPart}:@var{object}:@code{read}:@dots{}}
-requests use the same reply formats, listed below.
+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 @asis
-@item @code{qPart}:@code{auxv}:@code{read}::@var{offset},@var{length}
+@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}, and see @ref{Remote configuration,
+auxiliary vector}, and @ref{Remote configuration,
read-aux-vector-packet}. Note @var{annex} must be empty.
+
+This packet is not probed by default; the remote stub must request it,
+by suppling an appropriate @samp{qSupported} response (@pxref{qSupported}).
@end table
Reply:
-@table @asis
-@item @code{OK}
+@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 @var{XX@dots{}}
-Hex encoded data bytes read.
-This may be fewer bytes than the @var{length} in the request.
-
-@item @code{E00}
+@item E00
The request was malformed, or @var{annex} was invalid.
-@item @code{E}@var{nn}
+@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 @code{""} (empty)
-An empty reply indicates the @var{object} or @var{annex} string was not
-recognized by the stub.
+@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 @code{qPart}:@var{object}:@code{write}:@var{annex}:@var{offset}:@var{data@dots{}}
+@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 @code{object},
-starting at @var{offset} bytes into the data.
-@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.
+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 @asis
+@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 @code{E00}
+@item E00
The request was malformed, or @var{annex} was invalid.
-@item @code{E}@var{nn}
+@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 @code{""} (empty)
-An empty reply indicates the @var{object} or @var{annex} string was not
+@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 @code{qPart}:@var{object}:@var{operation}:@dots{}
+@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.
-
-@item @code{qGetTLSAddr}:@var{thread-id},@var{offset},@var{lm} --- get thread local storage address
-@cindex get thread-local storage address, remote request
-@cindex @code{qGetTLSAddr} packet
-Fetch the address associated with thread local storage specified
-by @var{thread-id}, @var{offset}, and @var{lm}.
-
-@var{thread-id} is the (big endian, hex encoded) thread id associated with the
-thread for which to fetch the TLS address.
-
-@var{offset} is the (big endian, hex encoded) offset associated with the
-thread local variable. (This offset is obtained from the debug
-information associated with the variable.)
-
-@var{lm} is the (big endian, hex encoded) OS/ABI specific encoding of the
-the load module associated with the thread local storage. For example,
-a @sc{gnu}/Linux system will pass the link map address of the shared
-object associated with the thread local storage under consideration.
-Other operating environments may choose to represent the load module
-differently, so the precise meaning of this parameter will vary.
-
-Reply:
-@table @asis
-@item @var{XX@dots{}}
-Hex encoded (big endian) bytes representing the address of the thread
-local storage requested.
-
-@item @code{E}@var{nn} (where @var{nn} are hex digits)
-An error occurred.
-
-@item @code{""} (empty)
-An empty reply indicates that @code{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}).
+@var{object} does not recognize the @var{operation} keyword, the stub
+must respond with an empty packet.
@end table
@node Register Packet Format
@section Register Packet Format
-The following @samp{g}/@samp{G} packets have previously been defined.
+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
@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 hexidecimal 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 hexidecimal
+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 hexidecimal 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 hexidecimal 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 hexidecimal 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 hexidecimal 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 hexidecimal
+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}).
+
+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.
+
+@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
+(Ctrl-C) within @value{GDBN}.
The target's request to perform a host system call does not finish
the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means,
<- target hits breakpoint and sends a Txx packet
@end smallexample
-The protocol is only used for files on the host file system and
-for I/O on the console. Character or block special devices, pipes,
-named pipes or sockets or any other communication method on the host
+The protocol only supports I/O on the console and to regular files on
+the host file system. Character or block special devices, pipes,
+named pipes, sockets or any other communication method on the host
system are not supported by this protocol.
@node Protocol basics
@subsection Protocol basics
@cindex protocol basics, file-i/o
-The File-I/O protocol uses the @code{F} packet, as request as well
-as as reply packet. Since a File-I/O system call can only occur when
-@value{GDBN} is waiting for the continuing or stepping target, the
-File-I/O request is a reply that @value{GDBN} has to expect as a result
-of a former @samp{C}, @samp{c}, @samp{S} or @samp{s} packet.
+The File-I/O protocol uses the @code{F} packet as the request as well
+as reply packet. Since a File-I/O system call can only occur when
+@value{GDBN} is waiting for a response from the continuing or stepping target,
+the File-I/O request is a reply that @value{GDBN} has to expect as a result
+of a previous @samp{C}, @samp{c}, @samp{S} or @samp{s} packet.
This @code{F} packet contains all information needed to allow @value{GDBN}
to call the appropriate host system call:
All parameters to the system call. Pointers are given as addresses
in the target memory address space. Pointers to strings are given as
pointer/length pair. Numerical values are given as they are.
-Numerical control values are given in a protocol specific representation.
+Numerical control flags are given in a protocol specific representation.
@end itemize
-At that point @value{GDBN} has to perform the following actions.
+At this point, @value{GDBN} has to perform the following actions.
@itemize @bullet
@item
-If parameter pointer values are given, which point to data needed as input
-to a system call, @value{GDBN} requests this data from the target with a
+If the parameters include pointer values to data needed as input to a
+system call, @value{GDBN} requests this data from the target with a
standard @code{m} packet request. This additional communication has to be
expected by the target implementation and is handled as any other @code{m}
packet.
representation as needed. Datatypes are coerced into the host types.
@item
-@value{GDBN} calls the system call
+@value{GDBN} calls the system call.
@item
It then coerces datatypes back to protocol representation.
@item
-If pointer parameters in the request packet point to buffer space in which
-a system call is expected to copy data to, the data is transmitted to the
+If the system call is expected to return data in buffer space specified
+by pointer parameters to the call, the data is transmitted to the
target using a @code{M} or @code{X} packet. This packet has to be expected
by the target implementation and is handled as any other @code{M} or @code{X}
packet.
The @code{F} request packet has the following format:
@table @samp
-
-@smallexample
-@code{F}@var{call-id}@code{,}@var{parameter@dots{}}
-@end smallexample
+@item F@var{call-id},@var{parameter@dots{}}
@var{call-id} is the identifier to indicate the host system call to be called.
This is just the name of the function.
-@var{parameter@dots{}} are the parameters to the system call.
+@var{parameter@dots{}} are the parameters to the system call.
+Parameters are hexadecimal integer values, either the actual values in case
+of scalar datatypes, pointers to target buffer space in case of compound
+datatypes and unspecified memory areas, or pointer/length pairs in case
+of string parameters. These are appended to the @var{call-id} as a
+comma-delimited list. All values are transmitted in ASCII
+string representation, pointer/length pairs separated by a slash.
@end table
-Parameters are hexadecimal integer values, either the real values in case
-of scalar datatypes, as pointers to target buffer space in case of compound
-datatypes and unspecified memory areas or as pointer/length pairs in case
-of string parameters. These are appended to the call-id, each separated
-from its predecessor by a comma. All values are transmitted in ASCII
-string representation, pointer/length pairs separated by a slash.
+
@node The F reply packet
@subsection The @code{F} reply packet
@table @samp
-@smallexample
-@code{F}@var{retcode}@code{,}@var{errno}@code{,}@var{Ctrl-C flag}@code{;}@var{call specific attachment}
-@end smallexample
+@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call specific attachment}
@var{retcode} is the return code of the system call as hexadecimal value.
-@var{errno} is the errno set by the call, in protocol specific representation.
+@var{errno} is the @code{errno} set by the call, in protocol specific representation.
This parameter can be omitted if the call was successful.
-@var{Ctrl-C flag} is only send if the user requested a break. In this
-case, @var{errno} must be send as well, even if the call was successful.
-The @var{Ctrl-C flag} itself consists of the character 'C':
+@var{Ctrl-C flag} is only sent if the user requested a break. In this
+case, @var{errno} must be sent as well, even if the call was successful.
+The @var{Ctrl-C flag} itself consists of the character @samp{C}:
@smallexample
F0,0,C
@end smallexample
@noindent
-or, if the call was interupted before the host call has been performed:
+or, if the call was interrupted before the host call has been performed:
@smallexample
F-1,4,C
@end table
-@node Memory transfer
-@subsection Memory transfer
-@cindex memory transfer, in file-i/o protocol
-
-Structured data which is transferred using a memory read or write as e.g.@:
-a @code{struct stat} is expected to be in a protocol specific format with
-all scalar multibyte datatypes being big endian. This should be done by
-the target before the @code{F} packet is sent resp.@: by @value{GDBN} before
-it transfers memory to the target. Transferred pointers to structured
-data should point to the already coerced data at any time.
@node The Ctrl-C message
@subsection The Ctrl-C message
@cindex ctrl-c message, in file-i/o protocol
-A special case is, if the @var{Ctrl-C flag} is set in the @value{GDBN}
-reply packet. In this case the target should behave, as if it had
+If the Ctrl-C flag is set in the @value{GDBN}
+reply packet (@pxref{The F reply packet}),
+the target should behave as if it had
gotten a break message. The meaning for the target is ``system call
-interupted by @code{SIGINT}''. Consequentially, the target should actually stop
+interrupted by @code{SIGINT}''. Consequentially, the target should actually stop
(as with a break message) and return to @value{GDBN} with a @code{T02}
-packet. In this case, it's important for the target to know, in which
-state the system call was interrupted. Since this action is by design
-not an atomic operation, we have to differ between two cases:
+packet.
+
+It's important for the target to know in which
+state the system call was interrupted. There are two possible cases:
@itemize @bullet
@item
returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system
call hasn't been performed. This is equivalent to the @code{EINTR} handling
on POSIX systems. In any other case, the target may presume that the
-system call has been finished --- successful or not --- and should behave
+system call has been finished --- successfully or not --- and should behave
as if the break message arrived right after the system call.
-@value{GDBN} must behave reliable. If the system call has not been called
+@value{GDBN} must behave reliably. If the system call has not been called
yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as
@code{errno} in the packet. If the system call on the host has been finished
-before the user requests a break, the full action must be finshed by
-@value{GDBN}. This requires sending @code{M} or @code{X} packets as they fit.
-The @code{F} packet may only be send when either nothing has happened
+before the user requests a break, the full action must be finished by
+@value{GDBN}. This requires sending @code{M} or @code{X} packets as necessary.
+The @code{F} packet may only be sent when either nothing has happened
or the full action has been completed.
@node Console I/O
@itemize @bullet
@item
-The user presses @kbd{Ctrl-C}. The behaviour is as explained above, the
+The user presses @kbd{Ctrl-C}. The behaviour is as explained above, and the
@code{read}
system call is treated as finished.
@item
The user presses @kbd{Enter}. This is treated as end of input with a trailing
-line feed.
+newline.
@item
The user presses @kbd{Ctrl-D}. This is treated as end of input. No trailing
-character, especially no Ctrl-D is appended to the input.
+character (neither newline nor Ctrl-D) is appended to the input.
@end itemize
-If the user has typed more characters as fit in the buffer given to
-the read call, the trailing characters are buffered in @value{GDBN} until
-either another @code{read(0, @dots{})} is requested by the target or debugging
-is stopped on users request.
-
-@node The isatty call
-@subsection The @samp{isatty} function call
-@cindex isatty call, file-i/o protocol
-
-A special case in this protocol is the library call @code{isatty} which
-is implemented as its own call inside of this protocol. It returns
-1 to the target if the file descriptor given as parameter is attached
-to the @value{GDBN} console, 0 otherwise. Implementing through system calls
-would require implementing @code{ioctl} and would be more complex than
-needed.
-
-@node The system call
-@subsection The @samp{system} function call
-@cindex system call, file-i/o protocol
-
-The other special case in this protocol is the @code{system} call which
-is implemented as its own call, too. @value{GDBN} is taking over the full
-task of calling the necessary host calls to perform the @code{system}
-call. The return value of @code{system} is simplified before it's returned
-to the target. Basically, the only signal transmitted back is @code{EINTR}
-in case the user pressed @kbd{Ctrl-C}. Otherwise the return value consists
-entirely of the exit status of the called command.
-
-Due to security concerns, the @code{system} call is by default refused
-by @value{GDBN}. The user has to allow this call explicitly with the
-@kbd{set remote system-call-allowed 1} command.
-
-@table @code
-@item set remote system-call-allowed
-@kindex set remote system-call-allowed
-Control whether to allow the @code{system} calls in the File I/O
-protocol for the remote target. The default is zero (disabled).
+If the user has typed more characters than fit in the buffer given to
+the @code{read} call, the trailing characters are buffered in @value{GDBN} until
+either another @code{read(0, @dots{})} is requested by the target, or debugging
+is stopped at the user's request.
-@item show remote system-call-allowed
-@kindex show remote system-call-allowed
-Show the current setting of system calls for the remote File I/O
-protocol.
-@end table
@node List of supported calls
@subsection List of supported calls
@unnumberedsubsubsec open
@cindex open, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int open(const char *pathname, int flags);
int open(const char *pathname, int flags, mode_t mode);
-
-@exdent Request:
-Fopen,pathptr/len,flags,mode
@end smallexample
+@item Request:
+@samp{Fopen,@var{pathptr}/@var{len},@var{flags},@var{mode}}
+
@noindent
-@code{flags} is the bitwise or of the following values:
+@var{flags} is the bitwise @code{OR} of the following values:
@table @code
@item O_CREAT
are concerned.
@item O_EXCL
-When used with O_CREAT, if the file already exists it is
+When used with @code{O_CREAT}, if the file already exists it is
an error and open() fails.
@item O_TRUNC
If the file already exists and the open mode allows
-writing (O_RDWR or O_WRONLY is given) it will be
-truncated to length 0.
+writing (@code{O_RDWR} or @code{O_WRONLY} is given) it will be
+truncated to zero length.
@item O_APPEND
The file is opened in append mode.
@item O_RDWR
The file is opened for reading and writing.
+@end table
@noindent
-Each other bit is silently ignored.
+Other bits are silently ignored.
-@end table
@noindent
-@code{mode} is the bitwise or of the following values:
+@var{mode} is the bitwise @code{OR} of the following values:
@table @code
@item S_IRUSR
@item S_IWOTH
Others have write permission.
+@end table
@noindent
-Each other bit is silently ignored.
+Other bits are silently ignored.
-@end table
-@smallexample
-@exdent Return value:
-open returns the new file descriptor or -1 if an error
-occured.
+@item Return value:
+@code{open} returns the new file descriptor or -1 if an error
+occurred.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EEXIST
-pathname already exists and O_CREAT and O_EXCL were used.
+@var{pathname} already exists and @code{O_CREAT} and @code{O_EXCL} were used.
@item EISDIR
-pathname refers to a directory.
+@var{pathname} refers to a directory.
@item EACCES
The requested access is not allowed.
@item ENAMETOOLONG
-pathname was too long.
+@var{pathname} was too long.
@item ENOENT
-A directory component in pathname does not exist.
+A directory component in @var{pathname} does not exist.
@item ENODEV
-pathname refers to a device, pipe, named pipe or socket.
+@var{pathname} refers to a device, pipe, named pipe or socket.
@item EROFS
-pathname refers to a file on a read-only filesystem and
+@var{pathname} refers to a file on a read-only filesystem and
write access was requested.
@item EFAULT
-pathname is an invalid pointer value.
+@var{pathname} is an invalid pointer value.
@item ENOSPC
No space on device to create the file.
The call was interrupted by the user.
@end table
+@end table
+
@node close
@unnumberedsubsubsec close
@cindex close, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int close(int fd);
+@end smallexample
-@exdent Request:
-Fclose,fd
+@item Request:
+@samp{Fclose,@var{fd}}
-@exdent Return value:
-close returns zero on success, or -1 if an error occurred.
+@item Return value:
+@code{close} returns zero on success, or -1 if an error occurred.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EBADF
-fd isn't a valid open file descriptor.
+@var{fd} isn't a valid open file descriptor.
@item EINTR
The call was interrupted by the user.
@end table
+@end table
+
@node read
@unnumberedsubsubsec read
@cindex read, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int read(int fd, void *buf, unsigned int count);
+@end smallexample
-@exdent Request:
-Fread,fd,bufptr,count
+@item Request:
+@samp{Fread,@var{fd},@var{bufptr},@var{count}}
-@exdent Return value:
+@item Return value:
On success, the number of bytes read is returned.
Zero indicates end of file. If count is zero, read
returns zero as well. On error, -1 is returned.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EBADF
-fd is not a valid file descriptor or is not open for
+@var{fd} is not a valid file descriptor or is not open for
reading.
@item EFAULT
-buf is an invalid pointer value.
+@var{bufptr} is an invalid pointer value.
@item EINTR
The call was interrupted by the user.
@end table
+@end table
+
@node write
@unnumberedsubsubsec write
@cindex write, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int write(int fd, const void *buf, unsigned int count);
+@end smallexample
-@exdent Request:
-Fwrite,fd,bufptr,count
+@item Request:
+@samp{Fwrite,@var{fd},@var{bufptr},@var{count}}
-@exdent Return value:
+@item Return value:
On success, the number of bytes written are returned.
Zero indicates nothing was written. On error, -1
is returned.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EBADF
-fd is not a valid file descriptor or is not open for
+@var{fd} is not a valid file descriptor or is not open for
writing.
@item EFAULT
-buf is an invalid pointer value.
+@var{bufptr} is an invalid pointer value.
@item EFBIG
An attempt was made to write a file that exceeds the
The call was interrupted by the user.
@end table
+@end table
+
@node lseek
@unnumberedsubsubsec lseek
@cindex lseek, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
long lseek (int fd, long offset, int flag);
-
-@exdent Request:
-Flseek,fd,offset,flag
@end smallexample
-@code{flag} is one of:
+@item Request:
+@samp{Flseek,@var{fd},@var{offset},@var{flag}}
+
+@var{flag} is one of:
@table @code
@item SEEK_SET
-The offset is set to offset bytes.
+The offset is set to @var{offset} bytes.
@item SEEK_CUR
-The offset is set to its current location plus offset
+The offset is set to its current location plus @var{offset}
bytes.
@item SEEK_END
-The offset is set to the size of the file plus offset
+The offset is set to the size of the file plus @var{offset}
bytes.
@end table
-@smallexample
-@exdent Return value:
+@item Return value:
On success, the resulting unsigned offset in bytes from
the beginning of the file is returned. Otherwise, a
value of -1 is returned.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EBADF
-fd is not a valid open file descriptor.
+@var{fd} is not a valid open file descriptor.
@item ESPIPE
-fd is associated with the @value{GDBN} console.
+@var{fd} is associated with the @value{GDBN} console.
@item EINVAL
-flag is not a proper value.
+@var{flag} is not a proper value.
@item EINTR
The call was interrupted by the user.
@end table
+@end table
+
@node rename
@unnumberedsubsubsec rename
@cindex rename, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int rename(const char *oldpath, const char *newpath);
+@end smallexample
-@exdent Request:
-Frename,oldpathptr/len,newpathptr/len
+@item Request:
+@samp{Frename,@var{oldpathptr}/@var{len},@var{newpathptr}/@var{len}}
-@exdent Return value:
+@item Return value:
On success, zero is returned. On error, -1 is returned.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EISDIR
-newpath is an existing directory, but oldpath is not a
+@var{newpath} is an existing directory, but @var{oldpath} is not a
directory.
@item EEXIST
-newpath is a non-empty directory.
+@var{newpath} is a non-empty directory.
@item EBUSY
-oldpath or newpath is a directory that is in use by some
+@var{oldpath} or @var{newpath} is a directory that is in use by some
process.
@item EINVAL
of itself.
@item ENOTDIR
-A component used as a directory in oldpath or new
-path is not a directory. Or oldpath is a directory
-and newpath exists but is not a directory.
+A component used as a directory in @var{oldpath} or new
+path is not a directory. Or @var{oldpath} is a directory
+and @var{newpath} exists but is not a directory.
@item EFAULT
-oldpathptr or newpathptr are invalid pointer values.
+@var{oldpathptr} or @var{newpathptr} are invalid pointer values.
@item EACCES
No access to the file or the path of the file.
@item ENAMETOOLONG
-oldpath or newpath was too long.
+@var{oldpath} or @var{newpath} was too long.
@item ENOENT
-A directory component in oldpath or newpath does not exist.
+A directory component in @var{oldpath} or @var{newpath} does not exist.
@item EROFS
The file is on a read-only filesystem.
The call was interrupted by the user.
@end table
+@end table
+
@node unlink
@unnumberedsubsubsec unlink
@cindex unlink, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int unlink(const char *pathname);
+@end smallexample
-@exdent Request:
-Funlink,pathnameptr/len
+@item Request:
+@samp{Funlink,@var{pathnameptr}/@var{len}}
-@exdent Return value:
+@item Return value:
On success, zero is returned. On error, -1 is returned.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EACCES
The system does not allow unlinking of directories.
@item EBUSY
-The file pathname cannot be unlinked because it's
+The file @var{pathname} cannot be unlinked because it's
being used by another process.
@item EFAULT
-pathnameptr is an invalid pointer value.
+@var{pathnameptr} is an invalid pointer value.
@item ENAMETOOLONG
-pathname was too long.
+@var{pathname} was too long.
@item ENOENT
-A directory component in pathname does not exist.
+A directory component in @var{pathname} does not exist.
@item ENOTDIR
A component of the path is not a directory.
The call was interrupted by the user.
@end table
+@end table
+
@node stat/fstat
@unnumberedsubsubsec stat/fstat
@cindex fstat, file-i/o system call
@cindex stat, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int stat(const char *pathname, struct stat *buf);
int fstat(int fd, struct stat *buf);
+@end smallexample
-@exdent Request:
-Fstat,pathnameptr/len,bufptr
-Ffstat,fd,bufptr
+@item Request:
+@samp{Fstat,@var{pathnameptr}/@var{len},@var{bufptr}}@*
+@samp{Ffstat,@var{fd},@var{bufptr}}
-@exdent Return value:
+@item Return value:
On success, zero is returned. On error, -1 is returned.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EBADF
-fd is not a valid open file.
+@var{fd} is not a valid open file.
@item ENOENT
-A directory component in pathname does not exist or the
+A directory component in @var{pathname} does not exist or the
path is an empty string.
@item ENOTDIR
A component of the path is not a directory.
@item EFAULT
-pathnameptr is an invalid pointer value.
+@var{pathnameptr} is an invalid pointer value.
@item EACCES
No access to the file or the path of the file.
@item ENAMETOOLONG
-pathname was too long.
+@var{pathname} was too long.
@item EINTR
The call was interrupted by the user.
@end table
+@end table
+
@node gettimeofday
@unnumberedsubsubsec gettimeofday
@cindex gettimeofday, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int gettimeofday(struct timeval *tv, void *tz);
+@end smallexample
-@exdent Request:
-Fgettimeofday,tvptr,tzptr
+@item Request:
+@samp{Fgettimeofday,@var{tvptr},@var{tzptr}}
-@exdent Return value:
+@item Return value:
On success, 0 is returned, -1 otherwise.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EINVAL
-tz is a non-NULL pointer.
+@var{tz} is a non-NULL pointer.
@item EFAULT
-tvptr and/or tzptr is an invalid pointer value.
+@var{tvptr} and/or @var{tzptr} is an invalid pointer value.
+@end table
+
@end table
@node isatty
@unnumberedsubsubsec isatty
@cindex isatty, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int isatty(int fd);
+@end smallexample
-@exdent Request:
-Fisatty,fd
+@item Request:
+@samp{Fisatty,@var{fd}}
-@exdent Return value:
-Returns 1 if fd refers to the @value{GDBN} console, 0 otherwise.
+@item Return value:
+Returns 1 if @var{fd} refers to the @value{GDBN} console, 0 otherwise.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EINTR
The call was interrupted by the user.
@end table
+@end table
+
+Note that the @code{isatty} call is treated as a special case: it returns
+1 to the target if the file descriptor is attached
+to the @value{GDBN} console, 0 otherwise. Implementing through system calls
+would require implementing @code{ioctl} and would be more complex than
+needed.
+
+
@node system
@unnumberedsubsubsec system
@cindex system, file-i/o system call
+@table @asis
+@item Synopsis:
@smallexample
-@exdent Synopsis:
int system(const char *command);
+@end smallexample
-@exdent Request:
-Fsystem,commandptr/len
+@item Request:
+@samp{Fsystem,@var{commandptr}/@var{len}}
-@exdent Return value:
-The value returned is -1 on error and the return status
-of the command otherwise. Only the exit status of the
-command is returned, which is extracted from the hosts
-system return value by calling WEXITSTATUS(retval).
-In case /bin/sh could not be executed, 127 is returned.
+@item Return value:
+If @var{len} is zero, the return value indicates whether a shell is
+available. A zero return value indicates a shell is not available.
+For non-zero @var{len}, the value returned is -1 on error and the
+return status of the command otherwise. Only the exit status of the
+command is returned, which is extracted from the host's @code{system}
+return value by calling @code{WEXITSTATUS(retval)}. In case
+@file{/bin/sh} could not be executed, 127 is returned.
-@exdent Errors:
-@end smallexample
+@item Errors:
@table @code
@item EINTR
The call was interrupted by the user.
@end table
+@end table
+
+@value{GDBN} takes over the full task of calling the necessary host calls
+to perform the @code{system} call. The return value of @code{system} on
+the host is simplified before it's returned
+to the target. Any termination signal information from the child process
+is discarded, and the return value consists
+entirely of the exit status of the called command.
+
+Due to security concerns, the @code{system} call is by default refused
+by @value{GDBN}. The user has to allow this call explicitly with the
+@code{set remote system-call-allowed 1} command.
+
+@table @code
+@item set remote system-call-allowed
+@kindex set remote system-call-allowed
+Control whether to allow the @code{system} calls in the File I/O
+protocol for the remote target. The default is zero (disabled).
+
+@item show remote system-call-allowed
+@kindex show remote system-call-allowed
+Show whether the @code{system} calls are allowed in the File I/O
+protocol.
+@end table
+
@node Protocol specific representation of datatypes
@subsection Protocol specific representation of datatypes
@cindex protocol specific representation of datatypes, in file-i/o protocol
@menu
* Integral datatypes::
* Pointer values::
+* Memory transfer::
* struct stat::
* struct timeval::
@end menu
@unnumberedsubsubsec Integral datatypes
@cindex integral datatypes, in file-i/o protocol
-The integral datatypes used in the system calls are
-
-@smallexample
-int@r{,} unsigned int@r{,} long@r{,} unsigned long@r{,} mode_t @r{and} time_t
-@end smallexample
+The integral datatypes used in the system calls are @code{int},
+@code{unsigned int}, @code{long}, @code{unsigned long},
+@code{mode_t}, and @code{time_t}.
-@code{Int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are
+@code{int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are
implemented as 32 bit values in this protocol.
-@code{Long} and @code{unsigned long} are implemented as 64 bit types.
+@code{long} and @code{unsigned long} are implemented as 64 bit types.
@xref{Limits}, for corresponding MIN and MAX values (similar to those
in @file{limits.h}) to allow range checking on host and target.
@noindent
which is a pointer to data of length 18 bytes at position 0x1aaf.
The length is defined as the full string length in bytes, including
-the trailing null byte. Example:
+the trailing null byte. For example, the string @code{"hello world"}
+at address 0x123456 is transmitted as
@smallexample
-``hello, world'' at address 0x123456
+@code{123456/d}
@end smallexample
-@noindent
-is transmitted as
+@node Memory transfer
+@unnumberedsubsubsec Memory transfer
+@cindex memory transfer, in file-i/o protocol
+
+Structured data which is transferred using a memory read or write (for
+example, a @code{struct stat}) is expected to be in a protocol specific format
+with all scalar multibyte datatypes being big endian. Translation to
+this representation needs to be done both by the target before the @code{F}
+packet is sent, and by @value{GDBN} before
+it transfers memory to the target. Transferred pointers to structured
+data should point to the already-coerced data at any time.
-@smallexample
-@code{123456/d}
-@end smallexample
@node struct stat
@unnumberedsubsubsec struct stat
@cindex struct stat, in file-i/o protocol
-The buffer of type struct stat used by the target and @value{GDBN} is defined
-as follows:
+The buffer of type @code{struct stat} used by the target and @value{GDBN}
+is defined as follows:
@smallexample
struct stat @{
@};
@end smallexample
-The integral datatypes are conforming to the definitions given in the
-approriate section (see @ref{Integral datatypes}, for details) so this
+The integral datatypes conform to the definitions given in the
+appropriate section (see @ref{Integral datatypes}, for details) so this
structure is of size 64 bytes.
The values of several fields have a restricted meaning and/or
range of values.
-@smallexample
-st_dev: 0 file
- 1 console
-
-st_ino: No valid meaning for the target. Transmitted unchanged.
+@table @code
-st_mode: Valid mode bits are described in Appendix C. Any other
- bits have currently no meaning for the target.
+@item st_dev
+A value of 0 represents a file, 1 the console.
-st_uid: No valid meaning for the target. Transmitted unchanged.
+@item st_ino
+No valid meaning for the target. Transmitted unchanged.
-st_gid: No valid meaning for the target. Transmitted unchanged.
+@item st_mode
+Valid mode bits are described in @ref{Constants}. Any other
+bits have currently no meaning for the target.
-st_rdev: No valid meaning for the target. Transmitted unchanged.
+@item st_uid
+@itemx st_gid
+@itemx st_rdev
+No valid meaning for the target. Transmitted unchanged.
-st_atime, st_mtime, st_ctime:
- These values have a host and file system dependent
- accuracy. Especially on Windows hosts the file systems
- don't support exact timing values.
-@end smallexample
+@item st_atime
+@itemx st_mtime
+@itemx st_ctime
+These values have a host and file system dependent
+accuracy. Especially on Windows hosts, the file system may not
+support exact timing values.
+@end table
-The target gets a struct stat of the above representation and is
-responsible to coerce it to the target representation before
+The target gets a @code{struct stat} of the above representation and is
+responsible for coercing it to the target representation before
continuing.
-Note that due to size differences between the host and target
-representation of stat members, these members could eventually
+Note that due to size differences between the host, target, and protocol
+representations of @code{struct stat} members, these members could eventually
get truncated on the target.
@node struct timeval
@unnumberedsubsubsec struct timeval
@cindex struct timeval, in file-i/o protocol
-The buffer of type struct timeval used by the target and @value{GDBN}
+The buffer of type @code{struct timeval} used by the File-I/O protocol
is defined as follows:
@smallexample
@};
@end smallexample
-The integral datatypes are conforming to the definitions given in the
-approriate section (see @ref{Integral datatypes}, for details) so this
+The integral datatypes conform to the definitions given in the
+appropriate section (see @ref{Integral datatypes}, for details) so this
structure is of size 8 bytes.
@node Constants
@cindex constants, in file-i/o protocol
The following values are used for the constants inside of the
-protocol. @value{GDBN} and target are resposible to translate these
+protocol. @value{GDBN} and target are responsible for translating these
values before and after the call as needed.
@menu
EUNKNOWN 9999
@end smallexample
- EUNKNOWN is used as a fallback error value if a host system returns
+ @code{EUNKNOWN} is used as a fallback error value if a host system returns
any error value not in the list of supported error numbers.
@node Lseek flags
@end smallexample
Example sequence of a read call, call fails on the host due to invalid
-file descriptor (EBADF):
+file descriptor (@code{EBADF}):
@smallexample
<- @code{Fread,3,1234,6}
projects / deliverable / binutils-gdb.git / blobdiff