\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}
@end itemize
You can use @value{GDBN} to debug programs written in C and C@t{++}.
-For more information, see @ref{Support,,Supported languages}.
+For more information, see @ref{Supported languages,,Supported languages}.
For more information, see @ref{C,,C and C++}.
@cindex Modula-2
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);
Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
Zuhn have made contributions both large and small.
+Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for
+Cygnus Solutions, implemented the original @sc{gdb/mi} interface.
+
Jim Blandy added support for preprocessor macros, while working for Red
Hat.
+Andrew Cagney designed @value{GDBN}'s architecture vector. Many
+people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick
+Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei
+Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason
+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
@menu
* File Options:: Choosing files
* Mode Options:: Choosing modes
+* Startup:: What @value{GDBN} does during startup
@end menu
@node File Options
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
@samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes
@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, ,
-The @sc{gdb/mi} Interface}) included since @var{GDBN} version 6.0. The
+The @sc{gdb/mi} Interface}) included since @value{GDBN} version 6.0. The
previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and
selected with @samp{--interpreter=mi1}, is deprecated. Earlier
@sc{gdb/mi} interfaces are no longer supported.
@end table
+@node Startup
+@subsection What @value{GDBN} does during startup
+@cindex @value{GDBN} startup
+
+Here's the description of what @value{GDBN} does during session startup:
+
+@enumerate
+@item
+Sets up the command interpreter as specified by the command line
+(@pxref{Mode Options, interpreter}).
+
+@item
+@cindex init file
+Reads the @dfn{init file} (if any) in your home directory@footnote{On
+DOS/Windows systems, the home directory is the one pointed to by the
+@code{HOME} environment variable.} and executes all the commands in
+that file.
+
+@item
+Processes command line options and operands.
+
+@item
+Reads and executes the commands from init file (if any) in the current
+working directory. This is only done if the current directory is
+different from your home directory. Thus, you can have more than one
+init file, one generic in your home directory, and another, specific
+to the program you are debugging, in the directory where you invoke
+@value{GDBN}.
+
+@item
+Reads command files specified by the @samp{-x} option. @xref{Command
+Files}, for more details about @value{GDBN} command files.
+
+@item
+Reads the command history recorded in the @dfn{history file}.
+@xref{Command History}, for more details about the command history and the
+files where @value{GDBN} records it.
+@end enumerate
+
+Init files use the same syntax as @dfn{command files} (@pxref{Command
+Files}) and are processed by @value{GDBN} in the same way. The init
+file in your home directory can set options (such as @samp{set
+complaints}) that affect subsequent processing of command line options
+and operands. Init files are not executed if you use the @samp{-nx}
+option (@pxref{Mode Options, ,Choosing modes}).
+
+@cindex init file name
+@cindex @file{.gdbinit}
+The @value{GDBN} init files are normally called @file{.gdbinit}.
+On some configurations of @value{GDBN}, the init file is known by a
+different name (these are typically environments where a specialized
+form of @value{GDBN} may need to coexist with other forms, hence a
+different name for the specialized version's init file). These are the
+environments with special init file names:
+
+@itemize @bullet
+@cindex @file{gdb.ini}
+@item
+The DJGPP port of @value{GDBN} uses the name @file{gdb.ini}, due to
+the limitations of file names imposed by DOS filesystems. The Windows
+ports of @value{GDBN} use the standard name, but if they find a
+@file{gdb.ini} file, they warn you about that and suggest to rename
+the file to the standard name.
+
+@cindex @file{.vxgdbinit}
+@item
+VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
+
+@cindex @file{.os68gdbinit}
+@item
+OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
+
+@cindex @file{.esgdbinit}
+@item
+ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
+
+@item
+CISCO 68k: @file{.cisco-gdbinit}
+@end itemize
+
+
@node Quitting GDB
@section Quitting @value{GDBN}
@cindex exiting @value{GDBN}
@node Logging output
@section Logging output
@cindex logging @value{GDBN} output
+@cindex save @value{GDBN} output to a file
You may want to save the output of @value{GDBN} commands to a file.
There are several commands to control @value{GDBN}'s logging.
Enable logging.
@item set logging off
Disable logging.
+@cindex logging file name
@item set logging file @var{file}
Change the name of the current logfile. The default logfile is @file{gdb.txt}.
@item set logging overwrite [on|off]
repeat the previous command. Certain commands (for example, @code{run})
will not repeat this way; these are commands whose unintentional
repetition might cause trouble and which you are unlikely to want to
-repeat.
+repeat. User-defined commands can disable this feature; see
+@ref{Define, dont-repeat}.
The @code{list} and @code{x} commands, when you repeat them with
@key{RET}, construct new arguments rather than repeating
@table @code
@kindex show version
-@cindex version number
+@cindex @value{GDBN} version number
@item show version
Show what version of @value{GDBN} is running. You should include this
information in @value{GDBN} bug-reports. If multiple versions of
@kindex show copying
@kindex info copying
+@cindex display @value{GDBN} copyright
@item show copying
@itemx info copying
Display information about permission for copying @value{GDBN}.
* 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
To request debugging information, specify the @samp{-g} option when you run
the compiler.
-Most compilers do not include information about preprocessor macros in
-the debugging information if you specify the @option{-g} flag alone,
-because this information is rather large. Version 3.1 of @value{NGCC},
-the @sc{gnu} C compiler, provides macro information if you specify the
-options @option{-gdwarf-2} and @option{-g3}; the former option requests
-debugging information in the Dwarf 2 format, and the latter requests
-``extra information''. In the future, we hope to find more compact ways
-to represent macro information, so that it can be included with
-@option{-g} alone.
-
-Many C compilers are unable to handle the @samp{-g} and @samp{-O}
-options together. Using those compilers, you cannot generate optimized
+Programs that are to be shipped to your customers are compiled with
+optimizations, using the @samp{-O} compiler option. However, many
+compilers are unable to handle the @samp{-g} and @samp{-O} options
+together. Using those compilers, you cannot generate optimized
executables containing debugging information.
-@value{NGCC}, the @sc{gnu} C compiler, supports @samp{-g} with or
+@value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or
without @samp{-O}, making it possible to debug optimized code. We
recommend that you @emph{always} use @samp{-g} whenever you compile a
program. You may think your program is correct, but there is no sense
@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this
format; if your @sc{gnu} C compiler has this option, do not use it.
+@value{GDBN} knows about preprocessor macros and can show you their
+expansion (@pxref{Macros}). Most compilers do not include information
+about preprocessor macros in the debugging information if you specify
+the @option{-g} flag alone, because this information is rather large.
+Version 3.1 and later of @value{NGCC}, the @sc{gnu} C compiler,
+provides macro information if you specify the options
+@option{-gdwarf-2} and @option{-g3}; the former option requests
+debugging information in the Dwarf 2 format, and the latter requests
+``extra information''. In the future, we hope to find more compact
+ways to represent macro information, so that it can be included with
+@option{-g} alone.
+
@need 2000
@node Starting
@section Starting your program
@table @code
@kindex cd
+@cindex change working directory
@item cd @var{directory}
Set the @value{GDBN} working directory to @var{directory}.
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
from /usr/lib/libc.2
@end smallexample
+On Solaris, you can display more information about user threads with a
+Solaris-specific command:
+
+@table @code
+@item maint info sol-threads
+@kindex maint info sol-threads
+@cindex thread info (Solaris)
+Display info on Solaris user threads.
+@end table
+
@table @code
@kindex thread @var{threadno}
@item thread @var{threadno}
@samp{Switching to} depends on your system's conventions for identifying
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}.
+@kindex thread apply
+@cindex apply command to several threads
+@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
@item set follow-fork-mode @var{mode}
Set the debugger response to a program call of @code{fork} or
@code{vfork}. A call to @code{fork} or @code{vfork} creates a new
-process. The @var{mode} can be:
+process. The @var{mode} argument can be:
@table @code
@item parent
@end table
+@kindex show follow-fork-mode
@item show follow-fork-mode
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
program stops there. @xref{Disabling, ,Disabling breakpoints}.
@kindex hbreak
+@cindex hardware breakpoints
@item hbreak @var{args}
Set a hardware-assisted breakpoint. @var{args} are the same as for the
@code{break} command and the breakpoint is set in the same way, but the
@value{GDBN} will reject this command if more than two are used. Delete
or disable unused hardware breakpoints before setting new ones
(@pxref{Disabling, ,Disabling}). @xref{Conditions, ,Break conditions}.
-@xref{set remote hardware-breakpoint-limit}.
+For remote targets, you can restrict the number of hardware
+breakpoints @value{GDBN} will use, see @ref{set remote
+hardware-breakpoint-limit}.
@kindex thbreak
@kindex rbreak
@cindex regular expression
+@cindex breakpoints in functions matching a regexp
+@cindex set breakpoints in many functions
@item rbreak @var{regex}
Set breakpoints on all functions matching the regular expression
@var{regex}. This command sets an unconditional breakpoint on all
executes more slowly and reports the change in value at the next
@emph{statement}, not the instruction, after the change occurs.
-@vindex can-use-hw-watchpoints
@cindex use only software watchpoints
You can force @value{GDBN} to use only software watchpoints with the
@kbd{set can-use-hw-watchpoints 0} command. With this variable set to
@code{can-use-hw-watchpoints} to zero will still use the hardware
mechanism of watching expressiion values.)
+@table @code
+@item set can-use-hw-watchpoints
+@kindex set can-use-hw-watchpoints
+Set whether or not to use hardware watchpoints.
+
+@item show can-use-hw-watchpoints
+@kindex show can-use-hw-watchpoints
+Show the current mode of using hardware watchpoints.
+@end table
+
+For remote targets, you can restrict the number of hardware
+watchpoints @value{GDBN} will use, see @ref{set remote
+hardware-breakpoint-limit}.
+
When you issue the @code{watch} command, @value{GDBN} reports
@smallexample
@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
Causes the @code{step} command to step over any functions which contains no
debug information. This is the default.
+@item show step-mode
+Show whether @value{GDBN} will stop in or step over functions without
+source line debug information.
+
@kindex finish
@item finish
Continue running until just after function in the selected stack frame
@table @code
@item set scheduler-locking @var{mode}
+@cindex scheduler locking mode
+@cindex lock scheduler
Set the scheduler locking mode. If it is @code{off}, then there is no
locking and any thread may run at any time. If @code{on}, then only the
current thread may run when the inferior is resumed. The @code{step}
stack frame consists of many bytes, each of which has its own address; each
kind of computer has a convention for choosing one byte whose
address serves as the address of the frame. Usually this address is kept
-in a register called the @dfn{frame pointer register} while execution is
-going on in that frame.
+in a register called the @dfn{frame pointer register}
+(@pxref{Registers, $fp}) while execution is going on in that frame.
@cindex frame number
@value{GDBN} assigns numbers to all existing stack frames, starting with
@item backtrace -@var{n}
@itemx bt -@var{n}
Similar, but print only the outermost @var{n} frames.
+
+@item backtrace full
+Print the values of the local variables also.
+@itemx bt full
@end table
@kindex where
The names @code{where} and @code{info stack} (abbreviated @code{info s})
are additional aliases for @code{backtrace}.
+@cindex multiple threads, backtrace
+In a multi-threaded program, @value{GDBN} by default shows the
+backtrace only for the current thread. To display the backtrace for
+several or all of the threads, use the command @code{thread apply}
+(@pxref{Threads, thread apply}). For example, if you type @kbd{thread
+apply all backtrace}, @value{GDBN} will display the backtrace for all
+the threads; this is handy when you debug a core dump of a
+multi-threaded program.
+
Each line in the backtrace shows the frame number and the function name.
The program counter value is also shown---unless you use @code{set
print address off}. The backtrace also shows the source file name and
value, indicating that your program has stopped at the beginning of the
code for line @code{993} of @code{builtin.c}.
+@cindex value optimized out, in backtrace
+@cindex function call arguments, optimized out
+If your program was compiled with optimizations, some compilers will
+optimize away arguments passed to functions if those arguments are
+never used after the call. Such optimizations generate code that
+passes arguments through registers, but doesn't store those arguments
+in the stack frame. @value{GDBN} has no way of displaying such
+arguments in stack frames other than the innermost one. Here's what
+such a backtrace might look like:
+
+@smallexample
+@group
+#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
+ at builtin.c:993
+#1 0x6e38 in expand_macro (sym=<value optimized out>) at macro.c:242
+#2 0x6840 in expand_token (obs=0x0, t=<value optimized out>, td=0xf7fffb08)
+ at macro.c:71
+(More stack frames follow...)
+@end group
+@end smallexample
+
+@noindent
+The values of arguments that were not saved in their stack frames are
+shown as @samp{<value optimized out>}.
+
+If you need to display the values of such optimized-out arguments,
+either deduce that from other variables whose values depend on the one
+you are interested in, or recompile without optimizations.
+
@cindex backtrace beyond @code{main} function
@cindex program entry point
@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}
Print lines just before the lines last printed.
@end table
+@cindex @code{list}, how many lines to display
By default, @value{GDBN} prints ten source lines with any of these forms of
the @code{list} command. You can change this using @code{set listsize}:
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).
+
@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)
@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
can set @var{instruction-set} to either @code{intel} or @code{att}.
The default is @code{att}, the AT&T flavor used by default by Unix
assemblers for x86-based targets.
+
+@kindex show disassembly-flavor
+@item show disassembly-flavor
+Show the current setting of the disassembly flavor.
@end table
* Registers:: Registers
* Floating Point Hardware:: Floating point hardware
* Vector Unit:: Vector Unit
-* Auxiliary Vector:: Auxiliary data provided by operating system
+* OS Information:: Auxiliary data provided by operating system
* Memory Region Attributes:: Memory region attributes
* Dump/Restore Files:: Copy between memory and a file
* Core File Generation:: Cause a program dump its core
@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
@xref{Symbols, info symbol}.
@item c
-Regard as an integer and print it as a character constant.
+Regard as an integer and print it as a character constant. This
+prints both the numerical value and its character representation. The
+character representation is replaced with the octal escape @samp{\nnn}
+for characters outside the 7-bit @sc{ascii} range.
@item f
Regard the bits of the value as a floating point number and print
@c 4.1.2.
@item @var{f}, the display format
-The display format is one of the formats used by @code{print},
-@samp{s} (null-terminated string), or @samp{i} (machine instruction).
-The default is @samp{x} (hexadecimal) initially.
-The default changes each time you use either @code{x} or @code{print}.
+The display format is one of the formats used by @code{print}
+(@samp{x}, @samp{d}, @samp{u}, @samp{o}, @samp{t}, @samp{a}, @samp{c},
+@samp{f}), and in addition @samp{s} (for null-terminated strings) and
+@samp{i} (for machine instructions). The default is @samp{x}
+(hexadecimal) initially. The default changes each time you use either
+@code{x} or @code{print}.
@item @var{u}, the unit size
The unit size is any of
@table @code
@item set print symbol-filename on
-@cindex closest symbol and offset for an address
+@cindex source file and line of a symbol
+@cindex symbol, source file and line
Tell @value{GDBN} to print the source file name and line number of a
symbol in the symbolic form of an address.
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
Set a limit on how many elements of an array @value{GDBN} will print.
If @value{GDBN} is printing a large array, it stops printing after it has
printed the number of elements set by the @code{set print elements} command.
Display the number of elements of a large array that @value{GDBN} will print.
If the number is 0, then the printing is unlimited.
+@item set print repeats
+@cindex repeated array elements
+Set the threshold for suppressing display of repeated array
+elelments. When the number of consecutive identical elements of an
+array exceeds the threshold, @value{GDBN} prints the string
+@code{"<repeats @var{n} times>"}, where @var{n} is the number of
+identical repetitions, instead of displaying the identical elements
+themselves. Setting the threshold to zero will cause all elements to
+be individually printed. The default threshold is 10.
+
+@item show print repeats
+Display the current threshold for printing repeated identical
+elements.
+
@item set print null-stop
@cindex @sc{null} elements in arrays
Cause @value{GDBN} to stop printing the characters of an array when the first
contain only short strings.
The default is off.
+@item show print null-stop
+Show whether @value{GDBN} stops printing an array on the first
+@sc{null} character.
+
@item set print pretty on
+@cindex print structures in indented form
+@cindex indentation in structure display
Cause @value{GDBN} to print structures in an indented format with one member
per line, like this:
@item set print union on
@cindex unions in structures, printing
-Tell @value{GDBN} to print unions which are contained in structures. This
-is the default setting.
+Tell @value{GDBN} to print unions which are contained in structures
+and other unions. This is the default setting.
@item set print union off
-Tell @value{GDBN} not to print unions which are contained in structures.
+Tell @value{GDBN} not to print unions which are contained in
+structures and other unions. @value{GDBN} will print @code{"@{...@}"}
+instead.
@item show print union
Ask @value{GDBN} whether or not it will print unions which are contained in
-structures.
+structures and other unions.
For example, given the declarations
@smallexample
$1 = @{it = Tree, form = @{...@}@}
@end smallexample
+
+@noindent
+@code{set print union} affects programs written in C-like languages
+and in Pascal.
@end table
@need 1000
@item set print object
@itemx set print object on
@cindex derived type of an object, printing
+@cindex display derived types
When displaying a pointer to an object, identify the @emph{actual}
(derived) type of the object rather than the @emph{declared} type, using
the virtual function table.
Do not print static members when displaying a C@t{++} object.
@item show print static-members
-Show whether C@t{++} static members are printed, or not.
+Show whether C@t{++} static members are printed or not.
+
+@item set print pascal_static-members
+@itemx set print pascal_static-members on
+@cindex static members of Pacal objects
+@cindex Pacal objects, static members display
+Print static members when displaying a Pascal object. The default is on.
+
+@item set print pascal_static-members off
+Do not print static members when displaying a Pascal object.
+
+@item show print pascal_static-members
+Show whether Pascal static members are printed or not.
@c These don't work with HP ANSI C++ yet.
@item set print vtbl
@itemx set print vtbl on
@cindex pretty print C@t{++} virtual function tables
+@cindex virtual functions (C@t{++}) display
+@cindex VTBL display
Pretty print C@t{++} virtual function tables. The default is off.
(The @code{vtbl} commands do not work on programs compiled with the HP
ANSI C@t{++} compiler (@code{aCC}).)
@section Value history
@cindex value history
+@cindex history of values printed by @value{GDBN}
Values printed by the @code{print} command are saved in the @value{GDBN}
@dfn{value history}. This allows you to refer to them in other expressions.
Values are kept until the symbol table is re-read or discarded
@section Convenience variables
@cindex convenience variables
+@cindex user-defined variables
@value{GDBN} provides @dfn{convenience variables} that you can use within
@value{GDBN} to hold on to a value and refer to it later. These variables
exist entirely within @value{GDBN}; they are not part of your program, and
@table @code
@kindex show convenience
+@cindex show all user variables
@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
the machine you are using, with or without the initial @samp{$}.
@end table
+@cindex stack pointer register
+@cindex program counter register
+@cindex process status register
+@cindex frame pointer register
+@cindex standard registers
@value{GDBN} has four ``standard'' register names that are available (in
expressions) on most machines---whenever they do not conflict with an
architecture's canonical mnemonics for registers. The register names
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
layout vary depending on the hardware.
@end table
-@node Auxiliary Vector
-@section Operating system auxiliary vector
+@node OS Information
+@section Operating system auxiliary information
+@cindex OS information
+
+@value{GDBN} provides interfaces to useful OS facilities that can help
+you debug your program.
+
+@cindex @code{ptrace} system call
+@cindex @code{struct user} contents
+When @value{GDBN} runs on a @dfn{Posix system} (such as GNU or Unix
+machines), it interfaces with the inferior via the @code{ptrace}
+system call. The operating system creates a special sata structure,
+called @code{struct user}, for this interface. You can use the
+command @code{info udot} to display the contents of this data
+structure.
+
+@table @code
+@item info udot
+@kindex info udot
+Display the contents of the @code{struct user} maintained by the OS
+kernel for the program being debugged. @value{GDBN} displays the
+contents of @code{struct user} as a list of hex numbers, similar to
+the @code{examine} command.
+@end table
+
@cindex auxiliary vector
@cindex vector, auxiliary
-
Some operating systems supply an @dfn{auxiliary vector} to programs at
startup. This is akin to the arguments and environment that you
specify for a program, but contains a system-dependent variety of
hardware, operating system, and process. Each value's purpose is
identified by an integer tag; the meanings are well-known but system-specific.
Depending on the configuration and operating system facilities,
-@value{GDBN} may be able to show you this information.
+@value{GDBN} may be able to show you this information. For remote
+targets, this functionality may further depend on the remote stub's
+support of the @samp{qPart:auxv:read} packet, see @ref{Remote
+configuration, auxiliary vector}.
@table @code
@kindex info auxv
an unrecognized tag.
@end table
+
@node Memory Region Attributes
@section Memory region attributes
@cindex memory region attributes
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.
* Setting:: Switching between source languages
* Show:: Displaying the language
* Checks:: Type and range checks
-* Support:: Supported languages
+* Supported languages:: Supported languages
* Unsupported languages:: Unsupported languages
@end menu
The following commands help you find out which language is the
working language, and also what language source files were written in.
-@kindex show language
@table @code
@item show language
+@kindex show language
Display the current working language. This is the
language you can use with commands such as @code{print} to
build and compute expressions that may involve variables in your program.
not in the standard list. You can then set the extension associated
with a language explicitly:
-@kindex set extension-language
-@kindex info extensions
@table @code
@item set extension-language @var{ext} @var{language}
+@kindex set extension-language
Tell @value{GDBN} that source files with extension @var{ext} are to be
assumed as written in the source language @var{language}.
@item info extensions
+@kindex info extensions
List all the filename extensions and the associated languages.
@end table
errors when your program is running.
@value{GDBN} can check for conditions like the above if you wish.
-Although @value{GDBN} does not check the statements in your program, it
-can check expressions entered directly into @value{GDBN} for evaluation via
-the @code{print} command, for example. As with the working language,
-@value{GDBN} can also decide whether or not to check automatically based on
-your program's source language. @xref{Support, ,Supported languages},
-for the default settings of supported languages.
+Although @value{GDBN} does not check the statements in your program,
+it can check expressions entered directly into @value{GDBN} for
+evaluation via the @code{print} command, for example. As with the
+working language, @value{GDBN} can also decide whether or not to check
+automatically based on your program's source language.
+@xref{Supported languages, ,Supported languages}, for the default
+settings of supported languages.
@menu
* Type Checking:: An overview of type checking
instance, both Modula-2 and C require the arguments to arithmetical
operators to be numbers. In C, enumerated types and pointers can be
represented as numbers, so that they are valid arguments to mathematical
-operators. @xref{Support, ,Supported languages}, for further
+operators. @xref{Supported languages, ,Supported languages}, for further
details on specific languages.
@value{GDBN} provides some additional commands for controlling the type checker:
@table @code
@item set check type auto
Set type checking on or off based on the current working language.
-@xref{Support, ,Supported languages}, for the default settings for
+@xref{Supported languages, ,Supported languages}, for the default settings for
each language.
@item set check type on
@end smallexample
This, too, is specific to individual languages, and in some cases
-specific to individual compilers or machines. @xref{Support, ,
+specific to individual compilers or machines. @xref{Supported languages, ,
Supported languages}, for further details on specific languages.
@value{GDBN} provides some additional commands for controlling the range checker:
@table @code
@item set check range auto
Set range checking on or off based on the current working language.
-@xref{Support, ,Supported languages}, for the default settings for
+@xref{Supported languages, ,Supported languages}, for the default settings for
each language.
@item set check range on
being set automatically by @value{GDBN}.
@end table
-@node Support
+@node Supported languages
@section Supported languages
-@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, assembly, Modula-2, and Ada.
+@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, Pascal,
+assembly, Modula-2, and Ada.
@c This is false ...
Some @value{GDBN} features may be used in expressions regardless of the
language you use: the @value{GDBN} @code{@@} and @code{::} operators,
* C:: C and C@t{++}
* Objective-C:: Objective-C
* Fortran:: Fortran
+* Pascal:: Pascal
* Modula-2:: Modula-2
* Ada:: Ada
@end menu
searches for a function whose signature @emph{exactly} matches the
argument types.
+@kindex show overload-resolution
+@item show overload-resolution
+Show the current setting of overload resolution.
+
@item @r{Overloaded symbol names}
You can specify a particular definition of an overloaded symbol, using
the same notation that is used to declare such symbols in C@t{++}: type
@cindex Objective-C
This section provides information about some commands and command
-options that are useful for debugging Objective-C code.
+options that are useful for debugging Objective-C code. See also
+@ref{Symbols, info classes}, and @ref{Symbols, info selectors}, for a
+few more commands specific to Objective-C support.
@menu
* Method Names in Commands::
@node The Print Command with Objective-C
@subsubsection The Print Command With Objective-C
+@cindex Objective-C, print objects
@kindex print-object
@kindex po @r{(@code{print-object})}
@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
+
+@cindex Pascal support in @value{GDBN}, limitations
+Debugging Pascal programs which use sets, subranges, file variables, or
+nested functions does not currently work. @value{GDBN} does not support
+entering expressions, printing values, or similar features using Pascal
+syntax.
+
+The Pascal-specific command @code{set print pascal_static-members}
+controls whether static members of Pascal objects are displayed.
+@xref{Print Settings, pascal_static-members}.
@node Modula-2
@subsection Modula-2
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.
matches for all languages except for Fortran, for which the default is
case-insensitive matches.
-@kindex show case-insensitive
-@item show case-insensitive
+@kindex show case-sensitive
+@item show case-sensitive
This command shows the current setting of case sensitivity for symbols
lookups.
@kindex info symbol
@cindex symbol from address
+@cindex closest symbol and offset for an address
@item info symbol @var{addr}
Print the name of a symbol which is stored at the address @var{addr}.
If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the
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
+ (gdb) 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
@var{regexp}.
@kindex info classes
+@cindex Objective-C, classes and selectors
@item info classes
@itemx info classes @var{regexp}
Display all Objective-C classes in your program, or
Show the current @code{on} or @code{off} setting.
@end table
+@cindex opaque data types
@kindex set opaque-type-resolution
@item set opaque-type-resolution on
Tell @value{GDBN} to resolve opaque types. An opaque type is a type
@c @group
@node Signaling
@section Giving your program a signal
+@cindex deliver a signal to a program
@table @code
@kindex signal
@cindex calling functions
@cindex inferior functions, calling
@item print @var{expr}
-Evaluate the expression @var{expr} and displaying the resuling value.
+Evaluate the expression @var{expr} and display the resuling value.
@var{expr} may include calls to functions in the program being
debugged.
value history.
@end table
-@cindex weak alias functions
-Sometimes, a function you wish to call is actually a @dfn{weak alias}
-for another function. In such case, @value{GDBN} might not pick up
+It is possible for the function you call via the @code{print} or
+@code{call} command to generate a signal (e.g., if there's a bug in
+the function, or if you passed it incorrect arguments). What happens
+in that case is controlled by the @code{set unwindonsignal} command.
+
+@table @code
+@item set unwindonsignal
+@kindex set unwindonsignal
+@cindex unwind stack in called functions
+@cindex call dummy stack unwinding
+Set unwinding of the stack if a signal is received while in a function
+that @value{GDBN} called in the program being debugged. If set to on,
+@value{GDBN} unwinds the stack it created for the call and restores
+the context to what it was before the call. If set to off (the
+default), @value{GDBN} stops in the frame where the signal was
+received.
+
+@item show unwindonsignal
+@kindex show unwindonsignal
+Show the current setting of stack unwinding in the functions called by
+@value{GDBN}.
+@end table
+
+@cindex weak alias functions
+Sometimes, a function you wish to call is actually a @dfn{weak alias}
+for another function. In such case, @value{GDBN} might not pick up
the type information, including the types of the function arguments,
which causes @value{GDBN} to call the inferior function incorrectly.
As a result, the called function will function erroneously and may
Out of @value{GDBN}}).
Occasionally it is necessary to change to a different file during a
-@value{GDBN} session. Or you may run @value{GDBN} and forget to specify
-a file you want to use. In these situations the @value{GDBN} commands
-to specify new files are useful.
+@value{GDBN} session. Or you may run @value{GDBN} and forget to
+specify a file you want to use. Or you are debugging a remote target
+via @code{gdbserver} (@pxref{Server, file}). In these situations the
+@value{GDBN} commands to specify new files are useful.
@table @code
@cindex executable file
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
+the @code{file} command. You will not be able to ``run'' an object
+file, but you can disassemble functions and inspect variables. Also,
+if the underlying BFD functionality supports it, you could use
+@kbd{gdb -write} to patch object files using this technique. Note
+that @value{GDBN} can neither interpret nor modify relocations in this
+case, so branches and some initialized variables will appear to go to
+the wrong place. But this feature is still handy from time to time.
@item file
@code{file} with no argument makes @value{GDBN} discard any information it
@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
+@item add-symbol-file-from-memory @var{address}
+Load symbols from the given @var{address} in a dynamically loaded
+object file whose image is mapped directly into the inferior's memory.
+For example, the Linux kernel maps a @code{syscall DSO} into each
+process's address space; this DSO provides kernel-specific code for
+some system calls. The argument can be any expression whose
+evaluation yields the address of the file's shared object file header.
+For this command to work, you must have used @code{symbol-file} or
+@code{exec-file} commands in advance.
@kindex add-shared-symbol-files
@kindex assf
@end table
@end table
@kindex set trust-readonly-sections
+@cindex read-only sections
@item set trust-readonly-sections on
Tell @value{GDBN} that readonly sections in your object file
really are read-only (i.e.@: that their contents will not change).
Tell @value{GDBN} not to trust readonly sections. This means that
the contents of the section might change while the program is running,
and must therefore be fetched from the target when needed.
+
+@item show trust-readonly-sections
+Show the current setting of trusting readonly sections.
@end table
All file-specifying commands allow both absolute and relative file names
name and remembers it that way.
@cindex shared libraries
-@value{GDBN} supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix
-5, and IBM RS/6000 shared libraries.
+@value{GDBN} supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix,
+and IBM RS/6000 AIX shared libraries.
@value{GDBN} automatically loads symbol definitions from shared libraries
when you use the @code{run} command, or when you examine a core file.
Display the current autoloading mode.
@end table
+@cindex load shared library
To explicitly load shared library symbols, use the @code{sharedlibrary}
command:
required by your program for a core file or after typing @code{run}. If
@var{regex} is omitted all shared libraries required by your program are
loaded.
-@end table
-On some systems, such as HP-UX systems, @value{GDBN} supports
-autoloading shared library symbols until a limiting threshold size is
-reached. This provides the benefit of allowing autoloading to remain on
-by default, but avoids autoloading excessively large shared libraries,
-up to a threshold that is initially set, but which you can modify if you
-wish.
-
-Beyond that threshold, symbols from shared libraries must be explicitly
-loaded. To load these symbols, use the command @code{sharedlibrary
-@var{filename}}. The base address of the shared library is determined
-automatically by @value{GDBN} and need not be specified.
+@item nosharedlibrary
+@kindex nosharedlibrary
+@cindex unload symbols from shared libraries
+Unload all shared object library symbols. This discards all symbols
+that have been loaded from all shared libraries. Symbols from shared
+libraries that were loaded by explicit user requests are not
+discarded.
+@end table
-To display or set the threshold, use the commands:
+Sometimes you may wish that @value{GDBN} stops and gives you control
+when any of shared library events happen. Use the @code{set
+stop-on-solib-events} command for this:
@table @code
-@kindex set auto-solib-limit
-@item set auto-solib-limit @var{threshold}
-Set the autoloading size threshold, in an integral number of megabytes.
-If @var{threshold} is nonzero and shared library autoloading is enabled,
-symbols from all shared object libraries will be loaded until the total
-size of the loaded shared library symbols exceeds this threshold.
-Otherwise, symbols must be loaded manually, using the
-@code{sharedlibrary} command. The default threshold is 100 (i.e.@: 100
-Mb).
+@item set stop-on-solib-events
+@kindex set stop-on-solib-events
+This command controls whether @value{GDBN} should give you control
+when the dynamic linker notifies it about some shared library event.
+The most common event of interest is loading or unloading of a new
+shared library.
-@kindex show auto-solib-limit
-@item show auto-solib-limit
-Display the current autoloading size threshold, in megabytes.
+@item show stop-on-solib-events
+@kindex show stop-on-solib-events
+Show whether @value{GDBN} stops and gives you control when shared
+library events happen.
@end table
Shared libraries are also supported in many cross or remote debugging
copies on the target can be stripped as long as the copies on the host are
not.
-You need to tell @value{GDBN} where the target libraries are, so that it can
-load the correct copies---otherwise, it may try to load the host's libraries.
-@value{GDBN} has two variables to specify the search directories for target
-libraries.
+@cindex where to look for shared libraries
+For remote debugging, you need to tell @value{GDBN} where the target
+libraries are, so that it can load the correct copies---otherwise, it
+may try to load the host's libraries. @value{GDBN} has two variables
+to specify the search directories for target libraries.
@table @code
+@cindex prefix for shared library file names
@kindex set solib-absolute-prefix
@item set solib-absolute-prefix @var{path}
If this variable is set, @var{path} will be used as a prefix for any
out in the same way that they are on the target, with e.g.@: a
@file{/usr/lib} hierarchy under @var{path}.
+@cindex default value of @samp{solib-absolute-prefix}
+@cindex @samp{--with-sysroot}
You can set the default value of @samp{solib-absolute-prefix} by using the
configure-time @samp{--with-sysroot} option.
@item show architecture
Show the current target architecture.
+
+@item set processor
+@itemx processor
+@kindex set processor
+@kindex show processor
+These are alias commands for, respectively, @code{set architecture}
+and @code{show architecture}.
@end table
@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
Different targets are available on different configurations of @value{GDBN};
your configuration may have more or fewer targets.
-Many remote targets require you to download the executable's code
-once you've successfully established a connection. You may wish to
-control the size of the data chunks used by @value{GDBN} to download
-program parts to the remote 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.
@table @code
@kindex set download-write-size
@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}
+@cindex hash mark while downloading
+This command controls whether a hash mark @samp{#} is displayed while
+downloading a file to the remote monitor. If on, a hash mark is
+displayed after each S-record is successfully downloaded to the
+monitor.
+
+@item show hash
+@kindex show hash@r{, for remote monitors}
+Show the current status of displaying the hash mark.
+
+@item set debug monitor
+@kindex set debug monitor
+@cindex display remote monitor communications
+Enable or disable display of communications messages between
+@value{GDBN} and the remote monitor.
+
+@item show debug monitor
+@kindex show debug monitor
+Show the current status of displaying communications between
+@value{GDBN} and the remote monitor.
@end table
@table @code
Other remote targets may be available in your
configuration of @value{GDBN}; use @code{help target} to list them.
+Once you've connected to the remote target, @value{GDBN} allows you to
+send arbitrary commands to the remote monitor:
+
+@table @code
+@item remote @var{command}
+@kindex remote@r{, a command}
+@cindex send command to remote monitor
+Send an arbitrary @var{command} string to the remote monitor.
+@end table
+
+
@node KOD
@section Kernel Object Display
@cindex kernel object display
@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
-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:
+
+@table @code
-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}:
+@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
the @code{target remote} command. Otherwise you may get an error whose
text depends on the host system, but which usually looks something like
@samp{Connection refused}. You don't need to use the @code{load}
-command in @value{GDBN} when using gdbserver, since the program is
-already on the target.
+command in @value{GDBN} when using @code{gdbserver}, since the program is
+already on the target. However, if you want to load the symbols (as
+you normally would), do that with the @code{file} command, and issue
+it @emph{before} connecting to the server; otherwise, you will get an
+error message saying @code{"Program is already running"}, since the
+program is considered running after the connection.
@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}.
+@node Remote configuration
+@section Remote configuration
-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:
+@kindex set remote
+@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,
+system-call-allowed}.
-@smallexample
-load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
-@end smallexample
+@table @code
+@item set remoteaddresssize @var{bits}
+@cindex adress size for remote targets
+@cindex bits in remote address
+Set the maximum size of address in a memory packet to the specified
+number of bits. @value{GDBN} will mask off the address bits above
+that number, when it passes addresses to the remote target. The
+default value is the number of bits in the target's address.
+
+@item show remoteaddresssize
+Show the current value of remote address size in bits.
+
+@item set remotebaud @var{n}
+@cindex baud rate for remote targets
+Set the baud rate for the remote serial I/O to @var{n} baud. The
+value is used to set the speed of the serial port used for debugging
+remote targets.
+
+@item show remotebaud
+Show the current speed of the remote connection.
+
+@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{Ctrl-C}
+character instead. The default is off, since most remote systems
+expect to see @samp{Ctrl-C} as the interrupt signal.
+
+@item show remotebreak
+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
+remote target to @var{device}. This is the device used by
+@value{GDBN} to open the serial communications line to the remote
+target. There's no default, so you must set a valid port name for the
+remote serial communications to work. (Some varieties of the
+@code{target} command accept the port name as part of their
+arguments.)
+
+@item show remotedevice
+Show the current name of the serial port.
+
+@item set remotelogbase @var{base}
+Set the base (a.k.a.@: radix) of logging serial protocol
+communications to @var{base}. Supported values of @var{base} are:
+@code{ascii}, @code{octal}, and @code{hex}. The default is
+@code{ascii}.
+
+@item show remotelogbase
+Show the current setting of the radix for logging remote serial
+protocol.
-@item
-On the @value{GDBN} host machine, connect to your target (@pxref{Connecting,,
-Connecting to a remote target}).
+@item set remotelogfile @var{file}
+@cindex record serial communications on file
+Record remote serial communications on the named @var{file}. The
+default is not to record at all.
-@end table
+@item show remotelogfile.
+Show the current setting of the file name on which to record the
+serial communications.
-@node Remote configuration
-@section Remote configuration
+@item set remotetimeout @var{num}
+@cindex timeout for serial communications
+@cindex remote timeout
+Set the timeout limit to wait for the remote target to respond to
+@var{num} seconds. The default is 2 seconds.
-The following configuration options are available when debugging remote
-programs:
+@item show remotetimeout
+Show the current number of seconds to wait for the remote target
+responses.
-@table @code
-@kindex set remote hardware-watchpoint-limit
-@kindex set remote hardware-breakpoint-limit
+@cindex limit hardware breakpoints and watchpoints
+@cindex remote target, limit break- and watchpoints
@anchor{set remote hardware-watchpoint-limit}
@anchor{set remote hardware-breakpoint-limit}
@item set remote hardware-watchpoint-limit @var{limit}
@itemx set remote hardware-breakpoint-limit @var{limit}
Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
watchpoints. A limit of -1, the default, is treated as unlimited.
+
+@item set remote fetch-register-packet
+@itemx set remote set-register-packet
+@itemx set remote P-packet
+@itemx set remote p-packet
+@cindex P-packet
+@cindex fetch registers from remote targets
+@cindex set registers in remote targets
+Determine whether @value{GDBN} can set and fetch registers from the
+remote target using the @samp{P} packets. The default depends on the
+remote stub's support of the @samp{P} packets (@value{GDBN} queries
+the stub when this packet is first required).
+
+@item show remote fetch-register-packet
+@itemx show remote set-register-packet
+@itemx show remote P-packet
+@itemx show remote p-packet
+Show the current setting of using the @samp{P} packets for setting and
+fetching registers from the remote target.
+
+@cindex binary downloads
+@cindex X-packet
+@item set remote binary-download-packet
+@itemx set remote X-packet
+Determine whether @value{GDBN} sends downloads in binary mode using
+the @samp{X} packets. The default is on.
+
+@item show remote binary-download-packet
+@itemx show remote X-packet
+Show the current setting of using the @samp{X} packets for binary
+downloads.
+
+@item set remote read-aux-vector-packet
+@cindex auxiliary vector of remote target
+@cindex @code{auxv}, and remote targets
+Set the use of the remote protocol's @samp{qPart:auxv:read} (target
+auxiliary vector read) request. This request is used to fetch the
+remote target's @dfn{auxiliary vector}, see @ref{OS Information,
+Auxiliary Vector}. The default setting depends on the remote stub's
+support of this request (@value{GDBN} queries the stub when this
+request is first required). @xref{General Query Packets, qPart}, for
+more information about this request.
+
+@item show remote read-aux-vector-packet
+Show the current setting of use of the @samp{qPart:auxv:read} request.
+
+@item set remote symbol-lookup-packet
+@cindex remote symbol lookup request
+Set the use of the remote protocol's @samp{qSymbol} (target symbol
+lookup) request. This request is used to communicate symbol
+information to the remote target, e.g., whenever a new shared library
+is loaded by the remote (@pxref{Files, shared libraries}). The
+default setting depends on the remote stub's support of this request
+(@value{GDBN} queries the stub when this request is first required).
+@xref{General Query Packets, qSymbol}, for more information about this
+request.
+
+@item show remote symbol-lookup-packet
+Show the current setting of use of the @samp{qSymbol} request.
+
+@item set remote verbose-resume-packet
+@cindex resume remote target
+@cindex signal thread, and remote targets
+@cindex single-step thread, and remote targets
+@cindex thread-specific operations on remote targets
+Set the use of the remote protocol's @samp{vCont} (descriptive resume)
+request. This request is used to resume specific threads in the
+remote target, and to single-step or signal them. The default setting
+depends on the remote stub's support of this request (@value{GDBN}
+queries the stub when this request is first required). This setting
+affects debugging of multithreaded programs: if @samp{vCont} cannot be
+used, @value{GDBN} might be unable to single-step a specific thread,
+especially under @code{set scheduler-locking off}; it is also
+impossible to pause a specific thread. @xref{Packets, vCont}, for
+more details.
+
+@item show remote verbose-resume-packet
+Show the current setting of use of the @samp{vCont} request
+
+@item set remote software-breakpoint-packet
+@itemx set remote hardware-breakpoint-packet
+@itemx set remote write-watchpoint-packet
+@itemx set remote read-watchpoint-packet
+@itemx set remote access-watchpoint-packet
+@itemx set remote Z-packet
+@cindex Z-packet
+@cindex remote hardware breakpoints and watchpoints
+These commands enable or disable the use of @samp{Z} packets for
+setting breakpoints and watchpoints in the remote target. The default
+depends on the remote stub's support of the @samp{Z} packets
+(@value{GDBN} queries the stub when each packet is first required).
+The command @code{set remote Z-packet}, kept for back-compatibility,
+turns on or off all the features that require the use of @samp{Z}
+packets.
+
+@item show remote software-breakpoint-packet
+@itemx show remote hardware-breakpoint-packet
+@itemx show remote write-watchpoint-packet
+@itemx show remote read-watchpoint-packet
+@itemx show remote access-watchpoint-packet
+@itemx show remote Z-packet
+Show the current setting of @samp{Z} packets usage.
+
+@item set remote get-thread-local-storage-address
+@kindex set remote get-thread-local-storage-address
+@cindex thread local storage of remote targets
+This command enables or disables the use of the @samp{qGetTLSAddr}
+(Get Thread Local Storage Address) request packet. The default
+depends on whether the remote stub supports this request.
+@xref{General Query Packets, qGetTLSAddr}, for more details about this
+packet.
+
+@item show remote get-thread-local-storage-address
+@kindex show remote get-thread-local-storage-address
+Show the current setting of @samp{qGetTLSAddr} packet usage.
@end table
@node remote stub
* SVR4 Process Information:: SVR4 process information
* DJGPP Native:: Features specific to the DJGPP port
* Cygwin Native:: Features specific to the Cygwin port
+* Hurd Native:: Features specific to @sc{gnu} Hurd
+* Neutrino:: Features specific to QNX Neutrino
@end menu
@node HP-UX
begins with a dollar sign, @value{GDBN} searches for a user or system
name first, before it searches for a convenience variable.
+
@node BSD libkvm Interface
@subsection BSD libkvm Interface
@table @code
@kindex kvm
@item kvm pcb
-Set current context from pcb address.
+Set current context from the @dfn{Process Control Block} (PCB) address.
@item kvm proc
Set current context from proc address. This command isn't available on
how many threads are there in the process; its virtual memory usage;
the signals that are pending, blocked, and ignored; its TTY; its
consumption of system and user time; its stack size; its @samp{nice}
-value; etc. For more information, see the @samp{proc(5)} man page
+value; etc. For more information, see the @samp{proc} man page
(type @kbd{man 5 proc} from your shell prompt).
@item info proc all
Report on the process IDs related to your program: its own process ID,
the ID of its parent, the process group ID, and the session ID.
@end ignore
+
+@item set procfs-trace
+@kindex set procfs-trace
+@cindex @code{procfs} API calls
+This command enables and disables tracing of @code{procfs} API calls.
+
+@item show procfs-trace
+@kindex show procfs-trace
+Show the current state of @code{procfs} API call tracing.
+
+@item set procfs-file @var{file}
+@kindex set procfs-file
+Tell @value{GDBN} to write @code{procfs} API trace to the named
+@var{file}. @value{GDBN} appends the trace info to the previous
+contents of the file. The default is to display the trace on the
+standard output.
+
+@item show procfs-file
+@kindex show procfs-file
+Show the file to which @code{procfs} API trace is written.
+
+@item proc-trace-entry
+@itemx proc-trace-exit
+@itemx proc-untrace-entry
+@itemx proc-untrace-exit
+@kindex proc-trace-entry
+@kindex proc-trace-exit
+@kindex proc-untrace-entry
+@kindex proc-untrace-exit
+These commands enable and disable tracing of entries into and exits
+from the @code{syscall} interface.
+
+@item info pidlist
+@kindex info pidlist
+@cindex process list, QNX Neutrino
+For QNX Neutrino only, this command displays the list of all the
+processes and all the threads within each process.
+
+@item info meminfo
+@kindex info meminfo
+@cindex mapinfo list, QNX Neutrino
+For QNX Neutrino only, this command displays the list of all mapinfos.
@end table
@node DJGPP Native
@cindex native @sc{djgpp} debugging
@cindex MS-DOS-specific commands
-@sc{djgpp} is the port of @sc{gnu} development tools to MS-DOS and
+@cindex DPMI
+@sc{djgpp} is a port of the @sc{gnu} development tools to MS-DOS and
MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs
that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on
top of real-mode DOS systems and their emulations.
@cindex physical address from linear address
@item info dos address-pte @var{addr}
This command displays the Page Table entry for a specified linear
-address. The argument linear address @var{addr} should already have the
-appropriate segment's base address added to it, because this command
-accepts addresses which may belong to @emph{any} segment. For
-example, here's how to display the Page Table entry for the page where
-the variable @code{i} is stored:
+address. The argument @var{addr} is a linear address which should
+already have the appropriate segment's base address added to it,
+because this command accepts addresses which may belong to @emph{any}
+segment. For example, here's how to display the Page Table entry for
+the page where a variable @code{i} is stored:
@smallexample
@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i}
@noindent
This says that @code{i} is stored at offset @code{0xd30} from the page
-whose physical base address is @code{0x02698000}, and prints all the
+whose physical base address is @code{0x02698000}, and shows all the
attributes of that page.
Note that you must cast the addresses of variables to a @code{char *},
@noindent
(The @code{+ 3} offset is because the transfer buffer's address is the
-3rd member of the @code{_go32_info_block} structure.) The output of
-this command clearly shows that addresses in conventional memory are
-mapped 1:1, i.e.@: the physical and linear addresses are identical.
+3rd member of the @code{_go32_info_block} structure.) The output
+clearly shows that this DPMI server maps the addresses in conventional
+memory 1:1, i.e.@: the physical (@code{0x00029000} + @code{0x110}) and
+linear (@code{0x29110}) addresses are identical.
This command is supported only with some DPMI servers.
@end table
+@cindex DOS serial data link, remote debugging
In addition to native debugging, the DJGPP port supports remote
debugging via a serial data link. The following commands are specific
to remote serial debugging in the DJGPP port of @value{GDBN}.
The related commands @samp{show com1base}, @samp{show com1irq} etc.@:
display the current settings of the base address and the @code{IRQ}
lines used by the COM ports.
+
+@item info serial
+@kindex info serial
+@cindex DOS serial port status
+This command prints the status of the 4 DOS serial ports. For each
+port, it prints whether it's active or not, its I/O base address and
+IRQ number, whether it uses a 16550-style FIFO, its baudrate, and the
+counts of various errors encountered so far.
@end table
@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
break point within a shared DLL like @file{kernel32.dll} is completely
safe.
+@node Hurd Native
+@subsection Commands specific to @sc{gnu} Hurd systems
+@cindex @sc{gnu} Hurd debugging
+
+This subsection describes @value{GDBN} commands specific to the
+@sc{gnu} Hurd native debugging.
+
+@table @code
+@item set signals
+@itemx set sigs
+@kindex set signals@r{, Hurd command}
+@kindex set sigs@r{, Hurd command}
+This command toggles the state of inferior signal interception by
+@value{GDBN}. Mach exceptions, such as breakpoint traps, are not
+affected by this command. @code{sigs} is a shorthand alias for
+@code{signals}.
+
+@item show signals
+@itemx show sigs
+@kindex show signals@r{, Hurd command}
+@kindex show sigs@r{, Hurd command}
+Show the current state of intercepting inferior's signals.
+
+@item set signal-thread
+@itemx set sigthread
+@kindex set signal-thread
+@kindex set sigthread
+This command tells @value{GDBN} which thread is the @code{libc} signal
+thread. That thread is run when a signal is delivered to a running
+process. @code{set sigthread} is the shorthand alias of @code{set
+signal-thread}.
+
+@item show signal-thread
+@itemx show sigthread
+@kindex show signal-thread
+@kindex show sigthread
+These two commands show which thread will run when the inferior is
+delivered a signal.
+
+@item set stopped
+@kindex set stopped@r{, Hurd command}
+This commands tells @value{GDBN} that the inferior process is stopped,
+as with the @code{SIGSTOP} signal. The stopped process can be
+continued by delivering a signal to it.
+
+@item show stopped
+@kindex show stopped@r{, Hurd command}
+This command shows whether @value{GDBN} thinks the debuggee is
+stopped.
+
+@item set exceptions
+@kindex set exceptions@r{, Hurd command}
+Use this command to turn off trapping of exceptions in the inferior.
+When exception trapping is off, neither breakpoints nor
+single-stepping will work. To restore the default, set exception
+trapping on.
+
+@item show exceptions
+@kindex show exceptions@r{, Hurd command}
+Show the current state of trapping exceptions in the inferior.
+
+@item set task pause
+@kindex set task@r{, Hurd commands}
+@cindex task attributes (@sc{gnu} Hurd)
+@cindex pause current task (@sc{gnu} Hurd)
+This command toggles task suspension when @value{GDBN} has control.
+Setting it to on takes effect immediately, and the task is suspended
+whenever @value{GDBN} gets control. Setting it to off will take
+effect the next time the inferior is continued. If this option is set
+to off, you can use @code{set thread default pause on} or @code{set
+thread pause on} (see below) to pause individual threads.
+
+@item show task pause
+@kindex show task@r{, Hurd commands}
+Show the current state of task suspension.
+
+@item set task detach-suspend-count
+@cindex task suspend count
+@cindex detach from task, @sc{gnu} Hurd
+This command sets the suspend count the task will be left with when
+@value{GDBN} detaches from it.
+
+@item show task detach-suspend-count
+Show the suspend count the task will be left with when detaching.
+
+@item set task exception-port
+@itemx set task excp
+@cindex task exception port, @sc{gnu} Hurd
+This command sets the task exception port to which @value{GDBN} will
+forward exceptions. The argument should be the value of the @dfn{send
+rights} of the task. @code{set task excp} is a shorthand alias.
+
+@item set noninvasive
+@cindex noninvasive task options
+This command switches @value{GDBN} to a mode that is the least
+invasive as far as interfering with the inferior is concerned. This
+is the same as using @code{set task pause}, @code{set exceptions}, and
+@code{set signals} to values opposite to the defaults.
+
+@item info send-rights
+@itemx info receive-rights
+@itemx info port-rights
+@itemx info port-sets
+@itemx info dead-names
+@itemx info ports
+@itemx info psets
+@cindex send rights, @sc{gnu} Hurd
+@cindex receive rights, @sc{gnu} Hurd
+@cindex port rights, @sc{gnu} Hurd
+@cindex port sets, @sc{gnu} Hurd
+@cindex dead names, @sc{gnu} Hurd
+These commands display information about, respectively, send rights,
+receive rights, port rights, port sets, and dead names of a task.
+There are also shorthand aliases: @code{info ports} for @code{info
+port-rights} and @code{info psets} for @code{info port-sets}.
+
+@item set thread pause
+@kindex set thread@r{, Hurd command}
+@cindex thread properties, @sc{gnu} Hurd
+@cindex pause current thread (@sc{gnu} Hurd)
+This command toggles current thread suspension when @value{GDBN} has
+control. Setting it to on takes effect immediately, and the current
+thread is suspended whenever @value{GDBN} gets control. Setting it to
+off will take effect the next time the inferior is continued.
+Normally, this command has no effect, since when @value{GDBN} has
+control, the whole task is suspended. However, if you used @code{set
+task pause off} (see above), this command comes in handy to suspend
+only the current thread.
+
+@item show thread pause
+@kindex show thread@r{, Hurd command}
+This command shows the state of current thread suspension.
+
+@item set thread run
+This comamnd sets whether the current thread is allowed to run.
+
+@item show thread run
+Show whether the current thread is allowed to run.
+
+@item set thread detach-suspend-count
+@cindex thread suspend count, @sc{gnu} Hurd
+@cindex detach from thread, @sc{gnu} Hurd
+This command sets the suspend count @value{GDBN} will leave on a
+thread when detaching. This number is relative to the suspend count
+found by @value{GDBN} when it notices the thread; use @code{set thread
+takeover-suspend-count} to force it to an absolute value.
+
+@item show thread detach-suspend-count
+Show the suspend count @value{GDBN} will leave on the thread when
+detaching.
+
+@item set thread exception-port
+@itemx set thread excp
+Set the thread exception port to which to forward exceptions. This
+overrides the port set by @code{set task exception-port} (see above).
+@code{set thread excp} is the shorthand alias.
+
+@item set thread takeover-suspend-count
+Normally, @value{GDBN}'s thread suspend counts are relative to the
+value @value{GDBN} finds when it notices each thread. This command
+changes the suspend counts to be absolute instead.
+
+@item set thread default
+@itemx show thread default
+@cindex thread default settings, @sc{gnu} Hurd
+Each of the above @code{set thread} commands has a @code{set thread
+default} counterpart (e.g., @code{set thread default pause}, @code{set
+thread default exception-port}, etc.). The @code{thread default}
+variety of commands sets the default thread properties for all
+threads; you can then change the properties of individual threads with
+the non-default commands.
+@end table
+
+
+@node Neutrino
+@subsection QNX Neutrino
+@cindex QNX Neutrino
+
+@value{GDBN} provides the following commands specific to the QNX
+Neutrino target:
+
+@table @code
+@item set debug nto-debug
+@kindex set debug nto-debug
+When set to on, enables debugging messages specific to the QNX
+Neutrino support.
+
+@item show debug nto-debug
+@kindex show debug nto-debug
+Show the current state of QNX Neutrino messages.
+@end table
+
+
@node Embedded OS
@section Embedded Operating Systems
This section goes into details specific to particular embedded
configurations.
+@cindex send command to simulator
+Whenever a specific embedded processor has a simulator, @value{GDBN}
+allows to send an arbitrary command to the simulator.
+
+@table @code
+@item sim @var{command}
+@kindex sim@r{, a command}
+Send an arbitrary @var{command} string to the simulator. Consult the
+documentation for the specific simulator in use for information about
+acceptable commands.
+@end table
+
@menu
-* ARM:: ARM
+* ARM:: ARM RDI
* H8/300:: Renesas H8/300
* H8/500:: Renesas H8/500
* M32R/D:: Renesas M32R/D
* Sparclite:: Fujitsu Sparclite
* ST2000:: Tandem ST2000
* Z8000:: Zilog Z8000
+* AVR:: Atmel AVR
+* CRIS:: CRIS
+* Super-H:: Renesas Super-H
+* WinCE:: Windows CE child processes
@end menu
@node ARM
@subsection ARM
+@cindex ARM RDI
@table @code
-
@kindex target rdi
@item target rdi @var{dev}
ARM Angel monitor, via RDI library interface to ADP protocol. You may
@end table
+@value{GDBN} provides the following ARM-specific commands:
+
+@table @code
+@item set arm disassembler
+@kindex set arm
+This commands selects from a list of disassembly styles. The
+@code{"std"} style is the standard style.
+
+@item show arm disassembler
+@kindex show arm
+Show the current disassembly style.
+
+@item set arm apcs32
+@cindex ARM 32-bit mode
+This command toggles ARM operation mode between 32-bit and 26-bit.
+
+@item show arm apcs32
+Display the current usage of the ARM 32-bit mode.
+
+@item set arm fpu @var{fputype}
+This command sets the ARM floating-point unit (FPU) type. The
+argument @var{fputype} can be one of these:
+
+@table @code
+@item auto
+Determine the FPU type by querying the OS ABI.
+@item softfpa
+Software FPU, with mixed-endian doubles on little-endian ARM
+processors.
+@item fpa
+GCC-compiled FPA co-processor.
+@item softvfp
+Software FPU with pure-endian doubles.
+@item vfp
+VFP co-processor.
+@end table
+
+@item show arm fpu
+Show the current type of the FPU.
+
+@item set arm abi
+This command forces @value{GDBN} to use the specified ABI.
+
+@item show arm abi
+Show the currently used ABI.
+
+@item set debug arm
+Toggle whether to display ARM-specific debugging messages from the ARM
+target support subsystem.
+
+@item show debug arm
+Show whether ARM-specific debugging messages are enabled.
+@end table
+
+The following commands are available when an ARM target is debugged
+using the RDI interface:
+
+@table @code
+@item rdilogfile @r{[}@var{file}@r{]}
+@kindex rdilogfile
+@cindex ADP (Angel Debugger Protocol) logging
+Set the filename for the ADP (Angel Debugger Protocol) packet log.
+With an argument, sets the log file to the specified @var{file}. With
+no argument, show the current log file name. The default log file is
+@file{rdi.log}.
+
+@item rdilogenable @r{[}@var{arg}@r{]}
+@kindex rdilogenable
+Control logging of ADP packets. With an argument of 1 or @code{"yes"}
+enables logging, with an argument 0 or @code{"no"} disables it. With
+no arguments displays the current setting. When logging is enabled,
+ADP packets exchanged between @value{GDBN} and the RDI target device
+are logged to a file.
+
+@item set rdiromatzero
+@kindex set rdiromatzero
+@cindex ROM at zero address, RDI
+Tell @value{GDBN} whether the target has ROM at address 0. If on,
+vector catching is disabled, so that zero address can be used. If off
+(the default), vector catching is enabled. For this command to take
+effect, it needs to be invoked prior to the @code{target rdi} command.
+
+@item show rdiromatzero
+@kindex show rdiromatzero
+Show the current setting of ROM at zero address.
+
+@item set rdiheartbeat
+@kindex set rdiheartbeat
+@cindex RDI heartbeat
+Enable or disable RDI heartbeat packets. It is not recommended to
+turn on this option, since it confuses ARM and EPI JTAG interface, as
+well as the Angel monitor.
+
+@item show rdiheartbeat
+@kindex show rdiheartbeat
+Show the setting of RDI heartbeat packets.
+@end table
+
+
@node H8/300
@subsection Renesas H8/300
@kindex target hms@r{, and serial protocol}
Now that serial communications are set up, and the development board is
-connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
+connected, you can start up @value{GDBN}. Call @code{@value{GDBN}} with
the name of your program as the argument. @code{@value{GDBN}} prompts
you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
commands to begin your debugging session: @samp{target hms} to specify
specify its hostname; @value{GDBN} uses @code{telnet} to connect.
@end table
+The following special commands are available when debugging with the
+Renesas E7000 ICE:
+
+@table @code
+@item e7000 @var{command}
+@kindex e7000
+@cindex send command to E7000 monitor
+This sends the specified @var{command} to the E7000 monitor.
+
+@item ftplogin @var{machine} @var{username} @var{password} @var{dir}
+@kindex ftplogin@r{, E7000}
+This command records information for subsequent interface with the
+E7000 monitor via the FTP protocol: @value{GDBN} will log into the
+named @var{machine} using specified @var{username} and @var{password},
+and then chdir to the named directory @var{dir}.
+
+@item ftpload @var{file}
+@kindex ftpload@r{, E7000}
+This command uses credentials recorded by @code{ftplogin} to fetch and
+load the named @var{file} from the E7000 monitor.
+
+@item drain
+@kindex drain@r{, E7000}
+This command drains any pending text buffers stored on the E7000.
+
+@item set usehardbreakpoints
+@itemx show usehardbreakpoints
+@kindex set usehardbreakpoints@r{, E7000}
+@kindex show usehardbreakpoints@r{, E7000}
+@cindex hardware breakpoints, and E7000
+These commands set and show the use of hardware breakpoints for all
+breakpoints. @xref{Set Breaks, hardware-assisted breakpoint}, for
+more information about using hardware breakpoints selectively.
+@end table
+
@node Renesas Special
@subsubsection Special @value{GDBN} commands for Renesas micros
@end table
@node M32R/D
-@subsection Renesas M32R/D
+@subsection Renesas M32R/D and M32R/SDI
@table @code
-
@kindex target m32r
@item target m32r @var{dev}
Renesas M32R/D ROM monitor.
@kindex target m32rsdi
@item target m32rsdi @var{dev}
Renesas M32R SDI server, connected via parallel port to the board.
+@end table
+
+The following @value{GDBN} commands are specific to the M32R monitor:
+
+@table @code
+@item set download-path @var{path}
+@kindex set download-path
+@cindex find downloadable @sc{srec} files (M32R)
+Set the default path for finding donwloadable @sc{srec} files.
+
+@item show download-path
+@kindex show download-path
+Show the default path for downloadable @sc{srec} files.
+@item set board-address @var{addr}
+@kindex set board-address
+@cindex M32-EVA target board address
+Set the IP address for the M32R-EVA target board.
+
+@item show board-address
+@kindex show board-address
+Show the current IP address of the target board.
+
+@item set server-address @var{addr}
+@kindex set server-address
+@cindex download server address (M32R)
+Set the IP address for the download server, which is the @value{GDBN}'s
+host machine.
+
+@item show server-address
+@kindex show server-address
+Display the IP address of the download server.
+
+@item upload @r{[}@var{file}@r{]}
+@kindex upload@r{, M32R}
+Upload the specified @sc{srec} @var{file} via the monitor's Ethernet
+upload capability. If no @var{file} argument is given, the current
+executable file is uploaded.
+
+@item tload @r{[}@var{file}@r{]}
+@kindex tload@r{, M32R}
+Test the @code{upload} command.
+@end table
+
+The following commands are available for M32R/SDI:
+
+@table @code
+@item sdireset
+@kindex sdireset
+@cindex reset SDI connection, M32R
+This command resets the SDI connection.
+
+@item sdistatus
+@kindex sdistatus
+This command shows the SDI connection status.
+
+@item debug_chaos
+@kindex debug_chaos
+@cindex M32R/Chaos debugging
+Instructs the remote that M32R/Chaos debugging is to be used.
+
+@item use_debug_dma
+@kindex use_debug_dma
+Instructs the remote to use the DEBUG_DMA method of accessing memory.
+
+@item use_mon_code
+@kindex use_mon_code
+Instructs the remote to use the MON_CODE method of accessing memory.
+
+@item use_ib_break
+@kindex use_ib_break
+Instructs the remote to set breakpoints by IB break.
+
+@item use_dbt_break
+@kindex use_dbt_break
+Instructs the remote to set breakpoints by DBT.
@end table
@node M68K
@value{GDBN} also supports these special commands for MIPS targets:
@table @code
-@item set processor @var{args}
-@itemx show processor
-@kindex set processor @var{args}
-@kindex show processor
-Use the @code{set processor} command to set the type of MIPS
-processor when you want to access processor-type-specific registers.
-For example, @code{set processor @var{r3041}} tells @value{GDBN}
-to use the CPU registers appropriate for the 3041 chip.
-Use the @code{show processor} command to see what MIPS processor @value{GDBN}
-is using. Use the @code{info reg} command to see what registers
-@value{GDBN} is using.
-
@item set mipsfpu double
@itemx set mipsfpu single
@itemx set mipsfpu none
+@itemx set mipsfpu auto
@itemx show mipsfpu
@kindex set mipsfpu
@kindex show mipsfpu
As usual, you can inquire about the @code{mipsfpu} variable with
@samp{show mipsfpu}.
-@item set remotedebug @var{n}
-@itemx show remotedebug
-@kindex set remotedebug@r{, MIPS protocol}
-@kindex show remotedebug@r{, MIPS protocol}
-@cindex @code{remotedebug}, MIPS protocol
-@cindex MIPS @code{remotedebug} protocol
-@c FIXME! For this to be useful, you must know something about the MIPS
-@c FIXME...protocol. Where is it described?
-You can see some debugging information about communications with the board
-by setting the @code{remotedebug} variable. If you set it to @code{1} using
-@samp{set remotedebug 1}, every packet is displayed. If you set it
-to @code{2}, every character is displayed. You can check the current value
-at any time with the command @samp{show remotedebug}.
-
@item set timeout @var{seconds}
@itemx set retransmit-timeout @var{seconds}
@itemx show timeout
is waiting for your program to stop. In that case, @value{GDBN} waits
forever because it has no way of knowing how long the program is going
to run before stopping.
+
+@item set syn-garbage-limit @var{num}
+@kindex set syn-garbage-limit@r{, MIPS remote}
+@cindex synchronize with remote MIPS target
+Limit the maximum number of characters @value{GDBN} should ignore when
+it tries to synchronize with the remote target. The default is 10
+characters. Setting the limit to -1 means there's no limit.
+
+@item show syn-garbage-limit
+@kindex show syn-garbage-limit@r{, MIPS remote}
+Show the current limit on the number of characters to ignore when
+trying to synchronize with the remote system.
+
+@item set monitor-prompt @var{prompt}
+@kindex set monitor-prompt@r{, MIPS remote}
+@cindex remote monitor prompt
+Tell @value{GDBN} to expect the specified @var{prompt} string from the
+remote monitor. The default depends on the target:
+@table @asis
+@item pmon target
+@samp{PMON}
+@item ddb target
+@samp{NEC010}
+@item lsi target
+@samp{PMON>}
+@end table
+
+@item show monitor-prompt
+@kindex show monitor-prompt@r{, MIPS remote}
+Show the current strings @value{GDBN} expects as the prompt from the
+remote monitor.
+
+@item set monitor-warnings
+@kindex set monitor-warnings@r{, MIPS remote}
+Enable or disable monitor warnings about hardware breakpoints. This
+has effect only for the @code{lsi} target. When on, @value{GDBN} will
+display warning messages whose codes are returned by the @code{lsi}
+PMON monitor for breakpoint commands.
+
+@item show monitor-warnings
+@kindex show monitor-warnings@r{, MIPS remote}
+Show the current setting of printing monitor warnings.
+
+@item pmon @var{command}
+@kindex pmon@r{, MIPS remote}
+@cindex send PMON command
+This command allows sending an arbitrary @var{command} string to the
+monitor. The monitor must be in debug mode for this to work.
@end table
@node OpenRISC 1000
@subsection PowerPC
@table @code
-
@kindex target dink32
@item target dink32 @var{dev}
DINK32 ROM monitor.
@kindex target sds
@item target sds @var{dev}
SDS monitor, running on a PowerPC board (such as Motorola's ADS).
+@end table
+
+@cindex SDS protocol
+The following commands specifi to the SDS protocol are supported
+by@value{GDBN}:
+@table @code
+@item set sdstimeout @var{nsec}
+@kindex set sdstimeout
+Set the timeout for SDS protocol reads to be @var{nsec} seconds. The
+default is 2 seconds.
+
+@item show sdstimeout
+@kindex show sdstimeout
+Show the current value of the SDS timeout.
+
+@item sds @var{command}
+@kindex sds@r{, a command}
+Send the specified @var{command} string to the SDS monitor.
@end table
+
@node PA
@subsection HP PA Embedded
conditional breakpoint that suspends only after at least 5000
simulated clock ticks.
+@node AVR
+@subsection Atmel AVR
+@cindex AVR
+
+When configured for debugging the Atmel AVR, @value{GDBN} supports the
+following AVR-specific commands:
+
+@table @code
+@item info io_registers
+@kindex info io_registers@r{, AVR}
+@cindex I/O registers (Atmel AVR)
+This command displays information about the AVR I/O registers. For
+each register, @value{GDBN} prints its number and value.
+@end table
+
+@node CRIS
+@subsection CRIS
+@cindex CRIS
+
+When configured for debugging CRIS, @value{GDBN} provides the
+following CRIS-specific commands:
+
+@table @code
+@item set cris-version @var{ver}
+@cindex CRIS version
+Set the current CRIS version to @var{ver}, either @samp{10} or @samp{32}.
+The CRIS version affects register names and sizes. This command is useful in
+case autodetection of the CRIS version fails.
+
+@item show cris-version
+Show the current CRIS version.
+
+@item set cris-dwarf2-cfi
+@cindex DWARF-2 CFI and CRIS
+Set the usage of DWARF-2 CFI for CRIS debugging. The default is @samp{on}.
+Change to @samp{off} when using @code{gcc-cris} whose version is below
+@code{R59}.
+
+@item show cris-dwarf2-cfi
+Show the current state of using DWARF-2 CFI.
+
+@item set cris-mode @var{mode}
+@cindex CRIS mode
+Set the current CRIS mode to @var{mode}. It should only be changed when
+debugging in guru mode, in which case it should be set to
+@samp{guru} (the default is @samp{normal}).
+
+@item show cris-mode
+Show the current CRIS mode.
+@end table
+
+@node Super-H
+@subsection Renesas Super-H
+@cindex Super-H
+
+For the Renesas Super-H processor, @value{GDBN} provides these
+commands:
+
+@table @code
+@item regs
+@kindex regs@r{, Super-H}
+Show the values of all Super-H registers.
+@end table
+
+@node WinCE
+@subsection Windows CE
+@cindex Windows CE
+
+The following commands are available for Windows CE:
+
+@table @code
+@item set remotedirectory @var{dir}
+@kindex set remotedirectory
+Tell @value{GDBN} to upload files from the named directory @var{dir}.
+The default is @file{/gdb}, i.e.@: the root directory on the current
+drive.
+
+@item show remotedirectory
+@kindex show remotedirectory
+Show the current value of the upload directory.
+
+@item set remoteupload @var{method}
+@kindex set remoteupload
+Set the method used to upload files to remote device. Valid values
+for @var{method} are @samp{always}, @samp{newer}, and @samp{never}.
+The default is @samp{newer}.
+
+@item show remoteupload
+@kindex show remoteupload
+Show the current setting of the upload method.
+
+@item set remoteaddhost
+@kindex set remoteaddhost
+Tell @value{GDBN} whether to add this host to the remote stub's
+arguments when you debug over a network.
+
+@item show remoteaddhost
+@kindex show remoteaddhost
+Show whether to add this host to remote stub's arguments when
+debugging over a network.
+@end table
+
+
@node Architectures
@section Architectures
all uses of @value{GDBN} with the architecture, both native and cross.
@menu
+* i386::
* A29K::
* Alpha::
* MIPS::
+* HPPA:: HP PA architecture
@end menu
+@node i386
+@subsection x86 Architecture-specific issues.
+
+@table @code
+@item set struct-convention @var{mode}
+@kindex set struct-convention
+@cindex struct return convention
+@cindex struct/union returned in registers
+Set the convention used by the inferior to return @code{struct}s and
+@code{union}s from functions to @var{mode}. Possible values of
+@var{mode} are @code{"pcc"}, @code{"reg"}, and @code{"default"} (the
+default). @code{"default"} or @code{"pcc"} means that @code{struct}s
+are returned on the stack, while @code{"reg"} means that a
+@code{struct} or a @code{union} whose size is 1, 2, 4, or 8 bytes will
+be returned in a register.
+
+@item show struct-convention
+@kindex show struct-convention
+Show the current setting of the convention to return @code{struct}s
+from functions.
+@end table
+
@node A29K
@subsection A29K
search for the beginning of a function. A value of @var{0} (the
default) means there is no limit. However, except for @var{0}, the
larger the limit the more bytes @code{heuristic-fence-post} must search
-and therefore the longer it takes to run.
+and therefore the longer it takes to run. You should only need to use
+this command when debugging a stripped executable.
@item show heuristic-fence-post
Display the current limit.
These commands are available @emph{only} when @value{GDBN} is configured
for debugging programs on Alpha or MIPS processors.
+Several MIPS-specific commands are available when debugging MIPS
+programs:
+
+@table @code
+@item set mips saved-gpreg-size @var{size}
+@kindex set mips saved-gpreg-size
+@cindex MIPS GP register size on stack
+Set the size of MIPS general-purpose registers saved on the stack.
+The argument @var{size} can be one of the following:
+
+@table @samp
+@item 32
+32-bit GP registers
+@item 64
+64-bit GP registers
+@item auto
+Use the target's default setting or autodetect the saved size from the
+information contained in the executable. This is the default
+@end table
+
+@item show mips saved-gpreg-size
+@kindex show mips saved-gpreg-size
+Show the current size of MIPS GP registers on the stack.
+
+@item set mips stack-arg-size @var{size}
+@kindex set mips stack-arg-size
+@cindex MIPS stack space for arguments
+Set the amount of stack space reserved for arguments to functions.
+The argument can be one of @code{"32"}, @code{"64"} or @code{"auto"}
+(the default).
+
+@item set mips abi @var{arg}
+@kindex set mips abi
+@cindex set ABI for MIPS
+Tell @value{GDBN} which MIPS ABI is used by the inferior. Possible
+values of @var{arg} are:
+
+@table @samp
+@item auto
+The default ABI associated with the current binary (this is the
+default).
+@item o32
+@item o64
+@item n32
+@item n64
+@item eabi32
+@item eabi64
+@item auto
+@end table
+
+@item show mips abi
+@kindex show mips abi
+Show the MIPS ABI used by @value{GDBN} to debug the inferior.
+
+@item set mipsfpu
+@itemx show mipsfpu
+@xref{MIPS Embedded, set mipsfpu}.
+
+@item set mips mask-address @var{arg}
+@kindex set mips mask-address
+@cindex MIPS addresses, masking
+This command determines whether the most-significant 32 bits of 64-bit
+MIPS addresses are masked off. The argument @var{arg} can be
+@samp{on}, @samp{off}, or @samp{auto}. The latter is the default
+setting, which lets @value{GDBN} determine the correct value.
+
+@item show mips mask-address
+@kindex show mips mask-address
+Show whether the upper 32 bits of MIPS addresses are masked off or
+not.
+
+@item set remote-mips64-transfers-32bit-regs
+@kindex set remote-mips64-transfers-32bit-regs
+This command controls compatibility with 64-bit MIPS targets that
+transfer data in 32-bit quantities. If you have an old MIPS 64 target
+that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr},
+and 64 bits for other registers, set this option to @samp{on}.
+
+@item show remote-mips64-transfers-32bit-regs
+@kindex show remote-mips64-transfers-32bit-regs
+Show the current setting of compatibility with older MIPS 64 targets.
+
+@item set debug mips
+@kindex set debug mips
+This command turns on and off debugging messages for the MIPS-specific
+target code in @value{GDBN}.
+
+@item show debug mips
+@kindex show debug mips
+Show the current setting of MIPS debugging messages.
+@end table
+
+
+@node HPPA
+@subsection HPPA
+@cindex HPPA support
+
+When @value{GDBN} is debugging te HP PA architecture, it provides the
+following special commands:
+
+@table @code
+@item set debug hppa
+@kindex set debug hppa
+THis command determines whether HPPA architecture specific debugging
+messages are to be displayed.
+
+@item show debug hppa
+Show whether HPPA debugging messages are displayed.
+
+@item maint print unwind @var{address}
+@kindex maint print unwind@r{, HPPA}
+This command displays the contents of the unwind table entry at the
+given @var{address}.
+
+@end table
+
@node Controlling GDB
@chapter Controlling @value{GDBN}
@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.
@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable
is not set.
-@cindex history save
-@kindex set history
+@cindex save command history
+@kindex set history save
@item set history save
@itemx set history save on
Record command history in a file, whose name may be specified with the
Stop recording command history in a file.
@cindex history size
+@kindex set history size
+@cindex @env{HISTSIZE}, environment variable
@item set history size @var{size}
Set the number of commands which @value{GDBN} keeps in its history list.
This defaults to the value of the environment variable
@end table
@table @code
-@kindex shows
+@kindex show commands
+@cindex show last commands
+@cindex display command history
@item show commands
Display the last ten commands in the command history.
Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
from wrapping its output.
+
+@item set pagination on
+@itemx set pagination off
+@kindex set pagination
+Turn the output pagination on or off; the default is on. Turning
+pagination off is the alternative to @code{set height 0}.
+
+@item show pagination
+@kindex show pagination
+Show the current pagination mode.
@end table
@node Numbers
You can always enter numbers in octal, decimal, or hexadecimal in
@value{GDBN} by the usual conventions: octal numbers begin with
@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers
-begin with @samp{0x}. Numbers that begin with none of these are, by
-default, entered in base 10; likewise, the default display for
-numbers---when no particular format is specified---is base 10. You can
-change the default base for both input and output with the @code{set
-radix} command.
+begin with @samp{0x}. Numbers that neither begin with @samp{0} or
+@samp{0x}, nor end with a @samp{.} are, by default, entered in base
+10; likewise, the default display for numbers---when no particular
+format is specified---is base 10. You can change the default base for
+both input and output with the commands described below.
@table @code
@kindex set input-radix
@item set input-radix @var{base}
Set the default base for numeric input. Supported choices
for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
-specified either unambiguously or using the current default radix; for
+specified either unambiguously or using the current input radix; for
example, any of
@smallexample
-set radix 012
-set radix 10.
-set radix 0xa
+set input-radix 012
+set input-radix 10.
+set input-radix 0xa
@end smallexample
@noindent
-sets the base to decimal. On the other hand, @samp{set radix 10}
-leaves the radix unchanged no matter what it was.
+sets the input base to decimal. On the other hand, @samp{set input-radix 10}
+leaves the input radix unchanged, no matter what it was, since
+@samp{10}, being without any leading or trailing signs of its base, is
+interpreted in the current radix. Thus, if the current radix is 16,
+@samp{10} is interpreted in hex, i.e.@: as 16 decimal, which doesn't
+change the radix.
@kindex set output-radix
@item set output-radix @var{base}
Set the default base for numeric display. Supported choices
for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
-specified either unambiguously or using the current default radix.
+specified either unambiguously or using the current input radix.
@kindex show input-radix
@item show input-radix
@kindex show output-radix
@item show output-radix
Display the current default base for numeric display.
+
+@item set radix @r{[}@var{base}@r{]}
+@itemx show radix
+@kindex set radix
+@kindex show radix
+These commands set and show the default base for both input and output
+of numbers. @code{set radix} sets the radix of input and output to
+the same base; without an argument, it resets the radix back to its
+default value of 10.
+
@end table
@node ABI
@item set coerce-float-to-double off
Arguments of type @code{float} will be passed directly to unprototyped
functions.
+
+@kindex show coerce-float-to-double
+@item show coerce-float-to-double
+Show the current setting of promoting @code{float} to @code{double}.
@end table
@kindex set cp-abi
@node Messages/Warnings
@section Optional warnings and messages
+@cindex verbose operation
+@cindex optional warnings
By default, @value{GDBN} is silent about its inner workings. If you are
running on a slow machine, you may want to use the @code{set verbose}
command. This makes @value{GDBN} tell you when it does a lengthy
@section Optional messages about internal happenings
@cindex optional debugging messages
+@value{GDBN} has commands that enable optional debugging messages from
+various @value{GDBN} subsystems; normally these commands are of
+interest to @value{GDBN} maintainers, or when reporting a bug. This
+section documents those commands.
+
@table @code
@kindex set exec-done-display
@item set exec-done-display
@kindex show debug
@item show debug arch
Displays the current state of displaying gdbarch debugging info.
+@item set debug aix-thread
+@cindex AIX threads
+Display debugging messages about inner workings of the AIX thread
+module.
+@item show debug aix-thread
+Show the current state of AIX thread debugging info display.
@item set debug event
@cindex event debugging info
Turns on or off display of @value{GDBN} event debugging info. The
info.
@item set debug expression
@cindex expression debugging info
-Turns on or off display of @value{GDBN} expression debugging info. The
-default is off.
+Turns on or off display of debugging info about @value{GDBN}
+expression parsing. The default is off.
@item show debug expression
-Displays the current state of displaying @value{GDBN} expression
-debugging info.
+Displays the current state of displaying debugging info about
+@value{GDBN} expression parsing.
@item set debug frame
@cindex frame debugging info
Turns on or off display of @value{GDBN} frame debugging info. The
for implementing operations such as single-stepping the inferior.
@item show debug infrun
Displays the current state of @value{GDBN} inferior debugging.
+@item set debug lin-lwp
+@cindex @sc{gnu}/Linux LWP debug messages
+@cindex Linux lightweight processes
+Turns on or off debugging messages from the Linux LWP debug support.
+@item show debug lin-lwp
+Show the current state of Linux LWP debugging messages.
@item set debug observer
@cindex observer debugging info
Turns on or off display of @value{GDBN} observer debugging. This
@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
@item show debug serial
Displays the current state of displaying @value{GDBN} serial debugging
info.
+@item set debug solib-frv
+@cindex FR-V shared-library debugging
+Turns on or off debugging messages for FR-V shared-library code.
+@item show debug solib-frv
+Display the current state of FR-V shared-library code debugging
+messages.
@item set debug target
@cindex target debugging info
Turns on or off display of @value{GDBN} target debugging info. This info
@item show debug target
Displays the current state of displaying @value{GDBN} target debugging
info.
-@item set debug varobj
+@item set debugvarobj
@cindex variable object debugging info
Turns on or off display of @value{GDBN} variable object debugging
info. The default is off.
-@item show debug varobj
+@item show debugvarobj
Displays the current state of displaying @value{GDBN} variable object
debugging info.
@end table
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.
-@table @code
+@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.
-@kindex define
-@item define @var{commandname}
-Define a command named @var{commandname}. If there is already a command
-by that name, you are asked to confirm that you want to redefine it.
+@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
+@item define @var{commandname}
+Define a command named @var{commandname}. If there is already a command
+by that name, you are asked to confirm that you want to redefine it.
The definition of the command is made up of other @value{GDBN} command lines,
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
documentation of a command. Redefining the command with @code{define}
does not change the documentation.
+@kindex dont-repeat
+@cindex don't repeat command
+@item dont-repeat
+Used inside a user-defined command, this tells @value{GDBN} that this
+command should not be repeated when the user hits @key{RET}
+(@pxref{Command Syntax, repeat last command}).
+
@kindex help user-defined
@item help user-defined
List all user-defined commands, with the first line of the documentation
not its documentation). If no @var{commandname} is given, display the
definitions for all 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
-A command file for @value{GDBN} is a file 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 does not mean to repeat
-the last command, as it would from the terminal.
-
-@cindex init file
-@cindex @file{.gdbinit}
-@cindex @file{gdb.ini}
-When you start @value{GDBN}, it automatically executes commands from its
-@dfn{init files}, normally called @file{.gdbinit}@footnote{The DJGPP
-port of @value{GDBN} uses the name @file{gdb.ini} instead, due to the
-limitations of file names imposed by DOS filesystems.}.
-During startup, @value{GDBN} does the following:
-
-@enumerate
-@item
-Reads the init file (if any) in your home directory@footnote{On
-DOS/Windows systems, the home directory is the one pointed to by the
-@code{HOME} environment variable.}.
-
-@item
-Processes command line options and operands.
-
-@item
-Reads the init file (if any) in the current working directory.
-
-@item
-Reads command files specified by the @samp{-x} option.
-@end enumerate
-
-The init file in your home directory can set options (such as @samp{set
-complaints}) that affect subsequent processing of command line options
-and operands. Init files are not executed if you use the @samp{-nx}
-option (@pxref{Mode Options, ,Choosing modes}).
-
-@cindex init file name
-On some configurations of @value{GDBN}, the init file is known by a
-different name (these are typically environments where a specialized
-form of @value{GDBN} may need to coexist with other forms, hence a
-different name for the specialized version's init file). These are the
-environments with special init file names:
-
-@cindex @file{.vxgdbinit}
-@itemize @bullet
-@item
-VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
-
-@cindex @file{.os68gdbinit}
-@item
-OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
-
-@cindex @file{.esgdbinit}
-@item
-ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
-@end itemize
+@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
+does not mean to repeat the last command, as it would from the
+terminal.
-You can also request the execution of a command file with the
-@code{source} command:
+You can request the execution of a command file with the @code{source}
+command:
@table @code
@kindex source
+@cindex execute commands from a file
@item source @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).
+
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
@value{GDBN} also accepts command input from standard input. In this
mode, normal output goes to standard output and error output goes to
standard error. Errors in a command file supplied on standard input do
-not terminate execution of the command file --- execution continues with
+not terminate execution of the command file---execution continues with
the next command.
@smallexample
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
lines. Positive counts increase the height, while negative counts
decrease it.
+@item tabset
+@kindex tabset @var{nchars}
+Set the width of tab stops to be @var{nchars} characters.
+
@end table
@node TUI Configuration
@unnumberedsec Function and Purpose
@cindex @sc{gdb/mi}, its purpose
-@sc{gdb/mi} is a line based machine oriented text interface to @value{GDBN}. It is
-specifically intended to support the development of systems which use
-the debugger as just one small component of a larger system.
+@sc{gdb/mi} is a line based machine oriented text interface to
+@value{GDBN} and is activated by specifying using the
+@option{--interpreter} command line option (@pxref{Mode Options}). It
+is specifically intended to support the development of systems which
+use the debugger as just one small component of a larger system.
This chapter is a specification of the @sc{gdb/mi} interface. It is written
in the form of a reference manual.
target activity (e.g., target stopped).
The following is a preliminary list of possible out-of-band records.
+In particular, the @var{exec-async-output} records.
+
+@table @code
+@item *stopped,reason="@var{reason}"
+@end table
+
+@var{reason} can be one of the following:
@table @code
-@item "*" "stop"
+@item breakpoint-hit
+A breakpoint was reached.
+@item watchpoint-trigger
+A watchpoint was triggered.
+@item read-watchpoint-trigger
+A read watchpoint was triggered.
+@item access-watchpoint-trigger
+An access watchpoint was triggered.
+@item function-finished
+An -exec-finish or similar CLI command was accomplished.
+@item location-reached
+An -exec-until or similar CLI command was accomplished.
+@item watchpoint-scope
+A watchpoint has gone out of scope.
+@item end-stepping-range
+An -exec-next, -exec-next-instruction, -exec-step, -exec-step-instruction or
+similar CLI command was accomplished.
+@item exited-signalled
+The inferior exited because of a signal.
+@item exited
+The inferior exited.
+@item exited-normally
+The inferior exited normally.
+@item signal-received
+A signal was received by the inferior.
@end table
-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
-
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Breakpoint Table Commands
@section @sc{gdb/mi} Breakpoint table commands
@smallexample
(@value{GDBP})
-break-insert main
-^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@}
+^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",
+fullname="/home/foo/hello.c",line="5",times="0"@}
(@value{GDBP})
-break-after 1 3
~
@{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"@}]@}
+addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
+line="5",times="0",ignore="3"@}]@}
(@value{GDBP})
@end smallexample
@{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"@}]@}
+addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
+line="5",cond="1",times="0",ignore="3"@}]@}
(@value{GDBP})
@end smallexample
@{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"@}]@}
+addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
+line="5",times="0"@}]@}
(@value{GDBP})
@end smallexample
@{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"@}]@}
+addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
+line="5",times="0"@}]@}
(@value{GDBP})
@end smallexample
@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}",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?
@smallexample
(@value{GDBP})
-break-insert main
-^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
+^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",
+fullname="/home/foo/recursive2.c,line="4",times="0"@}
(@value{GDBP})
-break-insert -t foo
-^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@}
+^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",
+fullname="/home/foo/recursive2.c,line="11",times="0"@}
(@value{GDBP})
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
@{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"@}]@}
+addr="0x00010774",func="foo",file="recursive2.c",
+fullname="/home/foo/recursive2.c",line="11",times="0"@}]@}
(@value{GDBP})
-break-insert -r foo.*
~int foo(int, int);
-^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@}
+^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c,
+"fullname="/home/foo/recursive2.c",line="11",times="0"@}
(@value{GDBP})
@end smallexample
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"@}]@}
+addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
+line="13",times="0"@}]@}
(@value{GDBP})
@end smallexample
^running
^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
value=@{old="-268439212",new="55"@},
-frame=@{func="main",args=[],file="recursive2.c",line="5"@}
+frame=@{func="main",args=[],file="recursive2.c",
+fullname="/home/foo/bar/recursive2.c",line="5"@}
(@value{GDBP})
@end smallexample
^done,reason="watchpoint-trigger",
wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
frame=@{func="callee4",args=[],
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
(@value{GDBP})
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="5",
frame=@{func="callee3",args=[@{name="strarg",
value="0x11940 \"A string argument.\""@}],
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
(@value{GDBP})
@end smallexample
@{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})
^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
value=@{old="-276895068",new="3"@},
frame=@{func="callee4",args=[],
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
(@value{GDBP})
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
@{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})
^done,reason="watchpoint-scope",wpnum="2",
frame=@{func="callee3",args=[@{name="strarg",
value="0x11940 \"A string argument.\""@}],
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
(@value{GDBP})
-break-list
^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
@{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"@}]@}
(@value{GDBP})
@end smallexample
(@value{GDBP})
*stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
-args=[],file="try.c",line="5"@}
+args=[],file="try.c",fullname="/home/foo/bar/try.c",line="5"@}
(@value{GDBP})
-data-list-changed-registers
^done,changed-registers=["0","1","2","4","5","6","7","8","9",
(@value{GDBP})
@@Hello world
*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
-file="hello.c",line="13"@}
+file="hello.c",fullname="/home/foo/bar/hello.c",line="13"@}
(@value{GDBP})
@end smallexample
(@value{GDBP})
@@hello from foo
*stopped,reason="function-finished",frame=@{func="main",args=[],
-file="hello.c",line="7"@}
+file="hello.c",fullname="/home/foo/bar/hello.c",line="7"@}
(@value{GDBP})
@end smallexample
(@value{GDBP})
*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
args=[@{name="a",value="1"],@{name="b",value="9"@}@},
-file="recursive2.c",line="14"@},
+file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
gdb-result-var="$1",return-value="0"
(@value{GDBP})
@end smallexample
222^done
(@value{GDBP})
111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
-frame=@{addr="0x00010140",func="foo",args=[],file="try.c",line="13"@}
+frame=@{addr="0x00010140",func="foo",args=[],file="try.c",
+fullname="/home/foo/bar/try.c",line="13"@}
(@value{GDBP})
(@value{GDBP})
(@value{GDBP})
000*stopped,reason="breakpoint-hit",bkptno="1",
frame=@{func="callee4",args=[],
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
+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
111^done,frame=@{level="0",func="callee3",
args=[@{name="strarg",
value="0x11940 \"A string argument.\""@}],
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
(@value{GDBP})
@end smallexample
^running
(@value{GDBP})
*stopped,reason="breakpoint-hit",bkptno="1",
-frame=@{func="main",args=[],file="recursive2.c",line="4"@}
+frame=@{func="main",args=[],file="recursive2.c",
+fullname="/home/foo/bar/recursive2.c",line="4"@}
(@value{GDBP})
@end smallexample
(@value{GDBP})
*stopped,reason="end-stepping-range",
frame=@{func="foo",args=[@{name="a",value="10"@},
-@{name="b",value="0"@}],file="recursive2.c",line="11"@}
+@{name="b",value="0"@}],file="recursive2.c",
+fullname="/home/foo/bar/recursive2.c",line="11"@}
(@value{GDBP})
@end smallexample
(@value{GDBP})
*stopped,reason="end-stepping-range",
-frame=@{func="foo",args=[],file="try.c",line="10"@}
+frame=@{func="foo",args=[],file="try.c",
+fullname="/home/foo/bar/try.c",line="10"@}
(@value{GDBP})
-exec-step-instruction
^running
(@value{GDBP})
*stopped,reason="end-stepping-range",
-frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@}
+frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",
+fullname="/home/foo/bar/try.c",line="10"@}
(@value{GDBP})
@end smallexample
(@value{GDBP})
x = 55
*stopped,reason="location-reached",frame=@{func="main",args=[],
-file="recursive2.c",line="6"@}
+file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"@}
(@value{GDBP})
@end smallexample
(@value{GDBP})
@end smallexample
+@subheading The @code{-inferior-tty-set} Command
+@findex -inferior-tty-set
+
+@subheading Synopsis
+
+@smallexample
+-inferior-tty-set /dev/pts/1
+@end smallexample
+
+Set terminal for future runs of the program being debugged.
+
+@subheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{set inferior-tty /dev/pts/1}.
+
+@subheading Example
+
+@smallexample
+(@value{GDBP})
+-inferior-tty-set /dev/pts/1
+^done
+(@value{GDBP})
+@end smallexample
+
+@subheading The @code{-inferior-tty-show} Command
+@findex -inferior-tty-show
+
+@subheading Synopsis
+
+@smallexample
+-inferior-tty-show
+@end smallexample
+
+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
+(@value{GDBP})
+-inferior-tty-set /dev/pts/1
+^done
+(@value{GDBP})
+-inferior-tty-show
+^done,inferior_tty_terminal="/dev/pts/1"
+(@value{GDBP})
+@end smallexample
+
@ignore
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Kod Commands
-stack-info-frame
@end smallexample
-Get info on the current frame.
+Get info on the selected frame.
@subsubheading @value{GDBN} Command
(without arguments).
@subsubheading Example
-N.A.
+
+@smallexample
+(@value{GDBP})
+-stack-info-frame
+^done,frame=@{level="1",addr="0x0001076c",func="callee3",
+file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}
+(@value{GDBP})
+@end smallexample
@subheading The @code{-stack-info-depth} Command
@findex -stack-info-depth
^done,
stack=[
frame=@{level="0",addr="0x00010734",func="callee4",
-file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
+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",line="17"@},
+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",line="22"@},
+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",line="27"@},
+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",line="32"@}]
+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-list-frames
^done,stack=
[frame=@{level="0",addr="0x0001076c",func="foo",
- file="recursive2.c",line="11"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"@},
frame=@{level="1",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
frame=@{level="2",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
frame=@{level="6",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
frame=@{level="7",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
frame=@{level="8",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
frame=@{level="9",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
frame=@{level="10",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
frame=@{level="11",addr="0x00010738",func="main",
- file="recursive2.c",line="4"@}]
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"@}]
(@value{GDBP})
@end smallexample
-stack-list-frames 3 5
^done,stack=
[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@}]
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
(@value{GDBP})
@end smallexample
-stack-list-frames 3 3
^done,stack=
[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",line="14"@}]
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
(@value{GDBP})
@end smallexample
-stack-list-locals @var{print-values}
@end smallexample
-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
+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
-stack-select-frame @var{framenum}
@end smallexample
-Change the current frame. Select a different frame @var{framenum} on
+Change the selected frame. Select a different frame @var{framenum} on
the stack.
@subsubheading @value{GDBN} Command
@smallexample
-var-list-children [@var{print-values}] @var{name}
@end smallexample
+@anchor{-var-list-children}
-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.
+Return a list of the children of the specified variable object and
+create variable objects for them, if they do not already exist. With
+a single argument or if @var{print-values} has a value for of 0 or
+@code{--no-values}, print only the names of the variables; if
+@var{print-values} is 1 or @code{--all-values}, also print their
+values; and if it is 2 or @code{--simple-values} print the name and
+value for simple data types and just the name for arrays, structures
+and unions.
@subsubheading Example
@smallexample
(@value{GDBP})
-var-list-children n
- numchild=@var{n},children=[@{name=@var{name},
+ ^done,numchild=@var{n},children=[@{name=@var{name},
numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
(@value{GDBP})
-var-list-children --all-values n
- numchild=@var{n},children=[@{name=@var{name},
+ ^done,numchild=@var{n},children=[@{name=@var{name},
numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
@end smallexample
@subsubheading Synopsis
@smallexample
- -var-update @{@var{name} | "*"@}
+ -var-update [@var{print-values}] @{@var{name} | "*"@}
@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.
+A @samp{*} causes all existing variable objects to be updated. The
+option @var{print-values} determines whether names both and values, or
+just names are printed in the manner described for
+@code{-var-list-children} (@pxref{-var-list-children}).
+
+@subsubheading Example
+@smallexample
+(@value{GDBP})
+-var-assign var1 3
+^done,value="3"
+(@value{GDBP})
+-var-update --all-values var1
+^done,changelist=[@{name="var1",value="3",in_scope="true",
+type_changed="false"@}]
+(@value{GDBP})
+@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.
@table @code
@kindex set annotate
@item set annotate @var{level}
-The @value{GDB} command @code{set annotate} sets the level of
+The @value{GDBN} command @code{set annotate} sets the level of
annotations to the specified @var{level}.
+
+@item show annotate
+@kindex show annotate
+Show the current annotation level.
@end table
This chapter describes level 3 annotations.
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.
In addition to commands intended for @value{GDBN} users, @value{GDBN}
includes a number of commands intended for @value{GDBN} developers,
that are not documented elsewhere in this manual. These commands are
-provided here for reference.
+provided here for reference. (For commands that turn on debugging
+messages, see @ref{Debugging Output}.)
@table @code
@kindex maint agent
@kindex maint dump-me
@item maint dump-me
+@cindex @code{SIGQUIT} signal, dump core of @value{GDBN}
Cause a fatal signal in the debugger and force it to dump its core.
+This is supported only on systems which support aborting a program
+with the @code{SIGQUIT} signal.
@kindex maint internal-error
@kindex maint internal-warning
@kindex maint print dummy-frames
@item maint print dummy-frames
-
Prints the contents of @value{GDBN}'s internal dummy-frame stack.
@smallexample
@end table
+The following command is useful for non-interactive invocations of
+@value{GDBN}, such as in the test suite.
+
+@table @code
+@item set watchdog @var{nsec}
+@kindex set watchdog
+@cindex watchdog timer
+@cindex timeout for commands
+Set the maximum number of seconds @value{GDBN} will wait for the
+target operation to finish. If this time expires, @value{GDBN}
+reports and error and the command is aborted.
+
+@item show watchdog
+Show the current setting of the target wait timeout.
+@end table
@node Remote Protocol
@appendix @value{GDBN} Remote Serial Protocol
* Stop Reply Packets::
* General Query Packets::
* Register Packet Format::
+* Tracepoint Packets::
+* Interrupts::
* Examples::
* File-I/O remote protocol extension::
@end menu
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
The following table provides a complete list of all currently defined
@var{command}s and their corresponding response @var{data}.
+@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.
+
+Here are the packet descriptions.
-@item @code{!} --- extended mode
-@cindex @code{!} packet
+@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 @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 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{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
+@item I
+@cindex @samp{I} packet
+Signal, then cycle step. @xref{step with signal packet}. @xref{cycle
+step packet}.
-@xref{step with signal packet}. @xref{cycle step packet}.
-
-@item @code{j} --- reserved
-
-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. The bytes @code{0x23}
+(@sc{ascii} @samp{#}), @code{0x24} (@sc{ascii} @samp{$}), and
+@code{0x7d} (@sc{ascii} @samp{@}}) are escaped using @code{0x7d}
+(@sc{ascii} @samp{@}}), and then XORed with @code{0x20}. For example,
+the byte @code{0x7d} would be transmitted as the two bytes @code{0x7d
+0x5d}.
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
+@table @samp
-@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.
+@item S @var{AA}
+The program received signal number @var{AA} (a two-digit hexidecimal
+number).
-@item W@var{AA}
+@item T @var{AA} @var{n1}:@var{r1};@var{n2}:@var{r2};@dots{}
+@cindex @samp{T} packet reply
+The program received signal number @var{AA} (a two-digit hexidecimal
+number). Single-step and breakpoint traps are reported this way. The
+@samp{@var{n}:@var{r}} pairs give the values of important registers or
+other information:
+@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
@node General Query Packets
@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:
-@item @code{q}@code{C} --- current thread
+@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
+
+A query or set packet may optionally be followed by a @samp{,} or
+@samp{;} separated list. Stubs must be careful to match the full
+packet name, in case packet names have common prefixes.
+
+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 @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
-
-@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
+@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}.
-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''.
+@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
-
-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 @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 @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.
-Reply:
-@table @samp
-@item *
-@end table
-
-See @code{remote.c:remote_unpack_thread_info_response()}.
-
-@item @code{q}@code{Rcmd,}@var{command} --- remote command
-
-@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}.
-
-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.
-@end table
+Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
-@item @code{qSymbol::} --- symbol lookup
+@item qPart:@var{object}:read:@var{annex}:@var{offset},@var{length}
+@cindex read special object, remote request
+@cindex @samp{qPart} packet
+Read uninterpreted bytes from the target's special data area
+identified by the keyword @var{object}. Request @var{length} bytes
+starting at @var{offset} bytes into the data. The content and
+encoding of @var{annex} is specific to the object; it can supply
+additional details about what data to access.
-Notify the target that @value{GDBN} is prepared to serve symbol lookup
-requests. Accept requests from the target for the values of symbols.
+Here are the specific requests of this form defined so far. All
+@samp{qPart:@var{object}:read:@dots{}} requests use the same reply
+formats, listed below.
-Reply:
@table @samp
-@item @code{OK}
-The target does not need to look up any (more) symbols.
-@item @code{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.
+@item qPart:auxv:read::@var{offset},@var{length}
+Access the target's @dfn{auxiliary vector}. @xref{OS Information,
+auxiliary vector}, and see @ref{Remote configuration,
+read-aux-vector-packet}. Note @var{annex} must be empty.
@end table
-@item @code{qSymbol:}@var{sym_value}:@var{sym_name} --- symbol value
-
-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
-target has previously requested.
-
-@var{sym_value} (hex) is the value for symbol @var{sym_name}. If
-@value{GDBN} cannot supply a value for @var{sym_name}, then this field
-will be empty.
-
Reply:
@table @samp
-@item @code{OK}
-The target does not need to look up any (more) symbols.
-@item @code{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
-
-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.
-
-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.
-
-@table @asis
-@item @code{qPart}:@code{auxv}:@code{read}::@var{offset},@var{length}
-Access the target's @dfn{auxiliary vector}. @xref{Auxiliary Vector}.
-Note @var{annex} must be empty.
-@end table
-
-Reply:
-@table @asis
-@item @code{OK}
+@item OK
The @var{offset} in the request is at the end of the data.
There is no more data to be read.
-@item @var{XX@dots{}}
+@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)
+@item
An empty reply indicates the @var{object} or @var{annex} string was not
recognized by the stub.
@end table
-@item @code{qPart}:@var{object}:@code{write}:@var{annex}:@var{offset}:@var{data@dots{}}
-
+@item qPart:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
+@cindex write data into object, remote request
Write uninterpreted bytes into the target's special data area
-identified by the keyword @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 hex-encoded data to be
+written. The content and encoding of @var{annex} is specific to the
+object; it can supply additional details about what data to access.
No requests of this form are presently in use. This specification
serves as a placeholder to document the common format that new
specific request specifications ought to use.
Reply:
-@table @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)
+@item
An empty reply indicates the @var{object} or @var{annex} string was not
recognized by the stub, or that the object does not support writing.
@end table
-@item @code{qPart}:@var{object}:@var{operation}:@dots{}
+@item qPart:@var{object}:@var{operation}:@dots{}
Requests of this form may be added in the future. When a stub does
not recognize the @var{object} keyword, or its support for
-@var{object} does not recognize the @var{operation} keyword,
-the stub must respond with an empty packet.
+@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
+@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}.
-Fetch the address associated with thread local storage specified
-by @var{thread-id}, @var{offset}, and @var{lm}.
+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 E @var{NN}
+Indicate a badly formed request.
+@item
+An empty reply indicates that @samp{qRcmd} is not recognized.
+@end table
-@var{thread-id} is the (big endian, hex encoded) thread id associated with the
-thread for which to fetch the TLS address.
+@item qSymbol::
+@cindex symbol lookup, remote request
+@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.
-@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.)
+Reply:
+@table @samp
+@item OK
+The target does not need to look up any (more) symbols.
+@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
+@samp{qSymbol:@var{sym_value}:@var{sym_name}} message, described
+below.
+@end table
-@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.
+@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
+target has previously requested.
+
+@var{sym_value} (hex) is the value for symbol @var{sym_name}. If
+@value{GDBN} cannot supply a value for @var{sym_name}, then this field
+will be empty.
Reply:
-@table @asis
-@item @var{XX@dots{}}
-Hex encoded (big endian) bytes representing the address of the thread
-local storage requested.
+@table @samp
+@item OK
+The target does not need to look up any (more) symbols.
+@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{E}@var{nn} (where @var{nn} are hex digits)
-An error occurred.
+@item QTDP
+@itemx QTFrame
+@xref{Tracepoint Packets}.
-@item @code{""} (empty)
-An empty reply indicates that @code{qGetTLSAddr} is not supported by the stub.
+@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
+@item QTStart
+@itemx QTStop
+@itemx QTinit
+@itemx QTro
+@itemx qTStatus
+@xref{Tracepoint Packets}.
+
@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
@subsection File-I/O Overview
@cindex file-i/o overview
-The File I/O remote protocol extension (short: File-I/O) allows the
-target to use the hosts file system and console I/O when calling various
+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
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.
This simulates file system operations even on targets that lack file systems.
The protocol is defined host- and target-system independent. It uses
-it's own independent representation of datatypes and values. Both,
+its own independent 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.
is stopped on users request.
@node The isatty call
-@subsection The isatty(3) 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 it's own call inside of this protocol. It returns
+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 system(3) 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 it's own call, too. @value{GDBN} is taking over the full
+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 refused to be called
-by @value{GDBN} by default. The user has to allow this call explicitly by
-entering
-
-@table @samp
-@kindex set remote system-call-allowed 1
-@item @code{set remote system-call-allowed 1}
-@end table
+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.
-Disabling the @code{system} call is done by
-
-@table @samp
-@kindex set remote system-call-allowed 0
-@item @code{set remote system-call-allowed 0}
-@end table
-
-The current setting is shown by typing
+@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).
-@table @samp
+@item show remote system-call-allowed
@kindex show remote system-call-allowed
-@item @code{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
projects / deliverable / binutils-gdb.git / blobdiff