\input texinfo @c -*-texinfo-*-
@c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
+@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
@c Free Software Foundation, Inc.
@c
@c %**start of header
* Gdb: (gdb). The GNU debugger.
@end direntry
-@ifinfo
-This file documents the @sc{gnu} debugger @value{GDBN}.
-
-
-This is the @value{EDITION} Edition, of @cite{Debugging with
-@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN}
-Version @value{GDBVN}.
-
-Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
- 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006@*
- Free Software Foundation, Inc.
+@copying
+Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
+1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.
-(a) The Free Software Foundation's Back-Cover Text is: ``You have
-freedom to copy and modify this GNU Manual, like GNU software. Copies
-published by the Free Software Foundation raise funds for GNU
-development.''
-@end ifinfo
+(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
+this GNU Manual. Buying copies from GNU Press supports the FSF in
+developing GNU and promoting software freedom.''
+@end copying
+
+@ifnottex
+This file documents the @sc{gnu} debugger @value{GDBN}.
+
+This is the @value{EDITION} Edition, of @cite{Debugging with
+@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN}
+@ifset VERSION_PACKAGE
+@value{VERSION_PACKAGE}
+@end ifset
+Version @value{GDBVN}.
+
+@insertcopying
+@end ifnottex
@titlepage
@title Debugging with @value{GDBN}
@subtitle The @sc{gnu} Source-Level Debugger
@sp 1
@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN}
+@ifset VERSION_PACKAGE
+@sp 1
+@subtitle @value{VERSION_PACKAGE}
+@end ifset
@author Richard Stallman, Roland Pesch, Stan Shebs, et al.
@page
@tex
{\parskip=0pt
-\hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@gnu.org.)\par
+\hfill (Send bugs and comments on @value{GDBN} to @value{BUGURL}.)\par
\hfill {\it Debugging with @value{GDBN}}\par
\hfill \TeX{}info \texinfoversion\par
}
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
-1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2006
-Free Software Foundation, Inc.
-@sp 2
Published by the Free Software Foundation @*
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
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``Free Software'' and ``Free Software Needs
-Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
-and with the Back-Cover Texts as in (a) below.
-
-(a) The Free Software Foundation's Back-Cover Text is: ``You have
-freedom to copy and modify this GNU Manual, like GNU software. Copies
-published by the Free Software Foundation raise funds for GNU
-development.''
+@insertcopying
@page
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
-This is the @value{EDITION} Edition, for @value{GDBN} Version
-@value{GDBVN}.
+This is the @value{EDITION} Edition, for @value{GDBN}
+@ifset VERSION_PACKAGE
+@value{VERSION_PACKAGE}
+@end ifset
+Version @value{GDBVN}.
-Copyright (C) 1988-2006 Free Software Foundation, Inc.
+Copyright (C) 1988-2009 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
* Commands:: @value{GDBN} commands
* Running:: Running programs under @value{GDBN}
* Stopping:: Stopping and continuing
+* Reverse Execution:: Running programs backward
* Stack:: Examining the stack
* Source:: Examining source files
* Data:: Examining data
* Remote Debugging:: Debugging remote programs
* Configurations:: Configuration-specific information
* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
+* Extending GDB:: Extending @value{GDBN}
* Interpreters:: Command Interpreters
* TUI:: @value{GDBN} Text User Interface
* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
* Agent Expressions:: The GDB Agent Expression Mechanism
* Target Descriptions:: How targets can describe themselves to
@value{GDBN}
+* Operating System Information:: Getting additional information from
+ the operating system
* Copying:: GNU General Public License says
how you can copy and share GDB
* GNU Free Documentation License:: The license for this documentation
@cindex @code{-c}
Use file @var{file} as a core dump to examine.
-@item -c @var{number}
@item -pid @var{number}
@itemx -p @var{number}
@cindex @code{--pid}
@cindex @code{-p}
Connect to process ID @var{number}, as with the @code{attach} command.
-If there is no such process, @value{GDBN} will attempt to open a core
-file named @var{number}.
@item -command @var{file}
@itemx -x @var{file}
@item
@cindex init file
-Reads the @dfn{init file} (if any) in your home directory@footnote{On
+Reads the system-wide @dfn{init file} (if @option{--with-system-gdbinit} was
+used when building @value{GDBN}; @pxref{System-wide configuration,
+ ,System-wide configuration and settings}) and executes all the commands in
+that file.
+
+@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.} and executes all the commands in
that file.
and operands. Init files are not executed if you use the @samp{-nx}
option (@pxref{Mode Options, ,Choosing Modes}).
+To display the list of init files loaded by gdb at startup, you
+can use @kbd{gdb --help}.
+
@cindex init file name
@cindex @file{.gdbinit}
@cindex @file{gdb.ini}
overload-resolution off} to disable overload resolution;
see @ref{Debugging C Plus Plus, ,@value{GDBN} Features for C@t{++}}.
+@cindex completion of structure field names
+@cindex structure field name completion
+@cindex completion of union field names
+@cindex union field name completion
+When completing in an expression which looks up a field in a
+structure, @value{GDBN} also tries@footnote{The completer can be
+confused by certain kinds of invalid expressions. Also, it only
+examines the static type of the expression, not the dynamic type.} to
+limit completions to the field names available in the type of the
+left-hand-side:
+
+@smallexample
+(@value{GDBP}) p gdb_stdout.@kbd{M-?}
+magic to_delete to_fputs to_put to_rewind
+to_data to_flush to_isatty to_read to_write
+@end smallexample
+
+@noindent
+This is because the @code{gdb_stdout} is a variable of the type
+@code{struct ui_file} that is defined in @value{GDBN} sources as
+follows:
+
+@smallexample
+struct ui_file
+@{
+ int *magic;
+ ui_file_flush_ftype *to_flush;
+ ui_file_write_ftype *to_write;
+ ui_file_fputs_ftype *to_fputs;
+ ui_file_read_ftype *to_read;
+ ui_file_delete_ftype *to_delete;
+ ui_file_isatty_ftype *to_isatty;
+ ui_file_rewind_ftype *to_rewind;
+ ui_file_put_ftype *to_put;
+ void *to_data;
+@}
+@end smallexample
+
@node Help
@section Getting Help
@kindex i @r{(@code{info})}
@item info
This command (abbreviated @code{i}) is for describing the state of your
-program. For example, you can list the arguments given to your program
+program. For example, you can show the arguments passed to a function
with @code{info args}, list the registers currently in use with @code{info
registers}, or list the breakpoints you have set with @code{info breakpoints}.
You can get a complete list of the @code{info} sub-commands with
* Attach:: Debugging an already-running process
* Kill Process:: Killing the child process
+* Inferiors:: Debugging multiple inferiors
* Threads:: Debugging programs with multiple threads
* Processes:: Debugging programs with multiple processes
* Checkpoint/Restart:: Setting a @emph{bookmark} to return to later
If you are running your program in an execution environment that
supports processes, @code{run} creates an inferior process and makes
-that process run your program. (In environments without processes,
-@code{run} jumps to the start of your program.)
+that process run your program. In some environments without processes,
+@code{run} jumps to the start of your program. Other targets,
+like @samp{remote}, are always running. If you get an error
+message like this one:
+
+@smallexample
+The "remote" target does not support "run".
+Try "help target" or "continue".
+@end smallexample
+
+@noindent
+then use @code{continue} to run your program. You may need @code{load}
+first (@pxref{load}).
The execution of a program is affected by certain information it
receives from its superior. @value{GDBN} provides ways to specify this
your program too late, as the program would have already completed the
elaboration phase. Under these circumstances, insert breakpoints in your
elaboration code before running your program.
+
+@kindex set exec-wrapper
+@item set exec-wrapper @var{wrapper}
+@itemx show exec-wrapper
+@itemx unset exec-wrapper
+When @samp{exec-wrapper} is set, the specified wrapper is used to
+launch programs for debugging. @value{GDBN} starts your program
+with a shell command of the form @kbd{exec @var{wrapper}
+@var{program}}. Quoting is added to @var{program} and its
+arguments, but not to @var{wrapper}, so you should add quotes if
+appropriate for your shell. The wrapper runs until it executes
+your program, and then @value{GDBN} takes control.
+
+You can use any program that eventually calls @code{execve} with
+its arguments as a wrapper. Several standard Unix utilities do
+this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending
+with @code{exec "$@@"} will also work.
+
+For example, you can use @code{env} to pass an environment variable to
+the debugged program, without setting the variable in your shell's
+environment:
+
+@smallexample
+(@value{GDBP}) set exec-wrapper env 'LD_PRELOAD=libtest.so'
+(@value{GDBP}) run
+@end smallexample
+
+This command is available when debugging locally on most targets, excluding
+@sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino.
+
+@kindex set disable-randomization
+@item set disable-randomization
+@itemx set disable-randomization on
+This option (enabled by default in @value{GDBN}) will turn off the native
+randomization of the virtual address space of the started program. This option
+is useful for multiple debugging sessions to make the execution better
+reproducible and memory addresses reusable across debugging sessions.
+
+This feature is implemented only on @sc{gnu}/Linux. You can get the same
+behavior using
+
+@smallexample
+(@value{GDBP}) set exec-wrapper setarch `uname -m` -R
+@end smallexample
+
+@item set disable-randomization off
+Leave the behavior of the started executable unchanged. Some bugs rear their
+ugly heads only when the program is loaded at certain addresses. If your bug
+disappears when you run the program under @value{GDBN}, that might be because
+@value{GDBN} by default disables the address randomization on platforms, such
+as @sc{gnu}/Linux, which do that for stand-alone programs. Use @kbd{set
+disable-randomization off} to try to reproduce such elusive bugs.
+
+The virtual address space randomization is implemented only on @sc{gnu}/Linux.
+It protects the programs against some kinds of security attacks. In these
+cases the attacker needs to know the exact location of a concrete executable
+code. Randomizing its location makes it impossible to inject jumps misusing
+a code at its expected addresses.
+
+Prelinking shared libraries provides a startup performance advantage but it
+makes addresses in these libraries predictable for privileged processes by
+having just unprivileged access at the target system. Reading the shared
+library binary gives enough information for assembling the malicious code
+misusing it. Still even a prelinked shared library can get loaded at a new
+random address just requiring the regular relocation process during the
+startup. Shared libraries not already prelinked are always loaded at
+a randomly chosen address.
+
+Position independent executables (PIE) contain position independent code
+similar to the shared libraries and therefore such executables get loaded at
+a randomly chosen address upon startup. PIE executables always load even
+already prelinked shared libraries at a random address. You can build such
+executable using @command{gcc -fPIE -pie}.
+
+Heap (malloc storage), stack and custom mmap areas are always placed randomly
+(as long as the randomization is enabled).
+
+@item show disable-randomization
+Show the current setting of the explicit disable of the native randomization of
+the virtual address space of the started program.
+
@end table
@node Arguments
reads the symbol table again (while trying to preserve your current
breakpoint settings).
+@node Inferiors
+@section Debugging Multiple Inferiors
+
+Some @value{GDBN} targets are able to run multiple processes created
+from a single executable. This can happen, for instance, with an
+embedded system reporting back several processes via the remote
+protocol.
+
+@cindex inferior
+@value{GDBN} represents the state of each program execution with an
+object called an @dfn{inferior}. An inferior typically corresponds to
+a process, but is more general and applies also to targets that do not
+have processes. Inferiors may be created before a process runs, and
+may (in future) be retained after a process exits. Each run of an
+executable creates a new inferior, as does each attachment to an
+existing process. Inferiors have unique identifiers that are
+different from process ids, and may optionally be named as well.
+Usually each inferior will also have its own distinct address space,
+although some embedded targets may have several inferiors running in
+different parts of a single space.
+
+Each inferior may in turn have multiple threads running in it.
+
+To find out what inferiors exist at any moment, use @code{info inferiors}:
+
+@table @code
+@kindex info inferiors
+@item info inferiors
+Print a list of all inferiors currently being managed by @value{GDBN}.
+
+@kindex set print inferior-events
+@cindex print messages on inferior start and exit
+@item set print inferior-events
+@itemx set print inferior-events on
+@itemx set print inferior-events off
+The @code{set print inferior-events} command allows you to enable or
+disable printing of messages when @value{GDBN} notices that new
+inferiors have started or that inferiors have exited or have been
+detached. By default, these messages will not be printed.
+
+@kindex show print inferior-events
+@item show print inferior-events
+Show whether messages will be printed when @value{GDBN} detects that
+inferiors have started, exited or have been detached.
+@end table
+
@node Threads
@section Debugging Programs with Multiple Threads
@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
a command to apply a command to a list of threads
@item thread-specific breakpoints
+@item @samp{set print thread-events}, which controls printing of
+messages on thread start and exit.
@end itemize
@quotation
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
-@cindex switching threads automatically
-@cindex threads, automatic switching
-Whenever @value{GDBN} stops your program, due to a breakpoint or a
-signal, it automatically selects the thread where that breakpoint or
-signal happened. @value{GDBN} alerts you to the context switch with a
-message of the form @samp{[Switching to @var{systag}]} to identify the
-thread.
+@kindex set print thread-events
+@cindex print messages on thread start and exit
+@item set print thread-events
+@itemx set print thread-events on
+@itemx set print thread-events off
+The @code{set print thread-events} command allows you to enable or
+disable printing of messages when @value{GDBN} notices that new threads have
+started or that threads have exited. By default, these messages will
+be printed if detection of these events is supported by the target.
+Note that these messages cannot be disabled on all targets.
+
+@kindex show print thread-events
+@item show print thread-events
+Show whether messages will be printed when @value{GDBN} detects that threads
+have started and exited.
+@end table
@xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for
more information about how @value{GDBN} behaves when you stop and start
On some systems, @value{GDBN} provides support for debugging programs that
create additional processes using the @code{fork} or @code{vfork} functions.
Currently, the only platforms with this feature are HP-UX (11.x and later
-only?) and GNU/Linux (kernel version 2.5.60 and later).
+only?) and @sc{gnu}/Linux (kernel version 2.5.60 and later).
By default, when a program forks, @value{GDBN} will continue to debug
the parent process and the child process will run unimpeded.
@end table
-@kindex show detach-on-follow
-@item show detach-on-follow
-Show whether detach-on-follow mode is on/off.
+@kindex show detach-on-fork
+@item show detach-on-fork
+Show whether detach-on-fork mode is on/off.
@end table
-If you choose to set @var{detach-on-follow} mode off, then
+If you choose to set @samp{detach-on-fork} 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
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.
+@kindex process @var{process-id}
+@item process @var{process-id}
+Make process number @var{process-id} the current process. The
+argument @var{process-id} must be one that is listed in the output of
+@samp{info forks}.
+
@end table
To quit debugging one of the forked processes, you can either detach
* Disabling:: Disabling breakpoints
* Conditions:: Break conditions
* Break Commands:: Breakpoint command lists
-* Breakpoint Menus:: Breakpoint menus
* Error in Breakpoints:: ``Cannot insert breakpoints''
* Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
@end menu
Vars,, Convenience Variables}, for a discussion of what you can do with
convenience variables.
-You have several ways to say where the breakpoint should go.
-
@table @code
-@item break @var{function}
-Set a breakpoint at entry to function @var{function}.
-When using source languages that permit overloading of symbols, such as
-C@t{++}, @var{function} may refer to more than one possible place to break.
-@xref{Breakpoint Menus,,Breakpoint Menus}, for a discussion of that situation.
-
-@item break +@var{offset}
-@itemx break -@var{offset}
-Set a breakpoint some number of lines forward or back from the position
-at which execution stopped in the currently selected @dfn{stack frame}.
-(@xref{Frames, ,Frames}, for a description of stack frames.)
-
-@item break @var{linenum}
-Set a breakpoint at line @var{linenum} in the current source file.
-The current source file is the last file whose source text was printed.
-The breakpoint will stop your program just before it executes any of the
-code on that line.
-
-@item break @var{filename}:@var{linenum}
-Set a breakpoint at line @var{linenum} in source file @var{filename}.
-
-@item break @var{filename}:@var{function}
-Set a breakpoint at entry to function @var{function} found in file
-@var{filename}. Specifying a file name as well as a function name is
-superfluous except when multiple files contain similarly named
-functions.
+@item break @var{location}
+Set a breakpoint at the given @var{location}, which can specify a
+function name, a line number, or an address of an instruction.
+(@xref{Specify Location}, for a list of all the possible ways to
+specify a @var{location}.) The breakpoint will stop your program just
+before it executes any of the code in the specified @var{location}.
-@item break *@var{address}
-Set a breakpoint at address @var{address}. You can use this to set
-breakpoints in parts of your program which do not have debugging
-information or source files.
+When using source languages that permit overloading of symbols, such as
+C@t{++}, a function name may refer to more than one possible place to break.
+@xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
+that situation.
@item break
When called without any arguments, @code{break} sets a breakpoint at
breakpoints @value{GDBN} will use, see @ref{set remote
hardware-breakpoint-limit}.
-
@kindex thbreak
@item thbreak @var{args}
Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
that are not enabled.
@item Address
-Where the breakpoint is in your program, as a memory address. If the
-breakpoint is pending (see below for details) on a future load of a shared library, the address
-will be listed as @samp{<PENDING>}.
+Where the breakpoint is in your program, as a memory address. For a
+pending breakpoint whose address is not yet known, this field will
+contain @samp{<PENDING>}. Such breakpoint won't fire until a shared
+library that has the symbol or line referred by breakpoint is loaded.
+See below for details. A breakpoint with several locations will
+have @samp{<MULTIPLE>} in this field---see below for details.
@item What
Where the breakpoint is in the source for your program, as a file and
line number. For a pending breakpoint, the original string passed to
the breakpoints are conditional, this is even useful
(@pxref{Conditions, ,Break Conditions}).
+@cindex multiple locations, breakpoints
+@cindex breakpoints, multiple locations
+It is possible that a breakpoint corresponds to several locations
+in your program. Examples of this situation are:
+
+@itemize @bullet
+@item
+For a C@t{++} constructor, the @value{NGCC} compiler generates several
+instances of the function body, used in different cases.
+
+@item
+For a C@t{++} template function, a given line in the function can
+correspond to any number of instantiations.
+
+@item
+For an inlined function, a given source line can correspond to
+several places where that function is inlined.
+@end itemize
+
+In all those cases, @value{GDBN} will insert a breakpoint at all
+the relevant locations@footnote{
+As of this writing, multiple-location breakpoints work only if there's
+line number information for all the locations. This means that they
+will generally not work in system libraries, unless you have debug
+info with line numbers for them.}.
+
+A breakpoint with multiple locations is displayed in the breakpoint
+table using several rows---one header row, followed by one row for
+each breakpoint location. The header row has @samp{<MULTIPLE>} in the
+address column. The rows for individual locations contain the actual
+addresses for locations, and show the functions to which those
+locations belong. The number column for a location is of the form
+@var{breakpoint-number}.@var{location-number}.
+
+For example:
+
+@smallexample
+Num Type Disp Enb Address What
+1 breakpoint keep y <MULTIPLE>
+ stop only if i==1
+ breakpoint already hit 1 time
+1.1 y 0x080486a2 in void foo<int>() at t.cc:8
+1.2 y 0x080486ca in void foo<double>() at t.cc:8
+@end smallexample
+
+Each location can be individually enabled or disabled by passing
+@var{breakpoint-number}.@var{location-number} as argument to the
+@code{enable} and @code{disable} commands. Note that you cannot
+delete the individual locations from the list, you can only delete the
+entire list of locations that belong to their parent breakpoint (with
+the @kbd{delete @var{num}} command, where @var{num} is the number of
+the parent breakpoint, 1 in the above example). Disabling or enabling
+the parent breakpoint (@pxref{Disabling}) affects all of the locations
+that belong to that breakpoint.
+
@cindex pending breakpoints
-If a specified breakpoint location cannot be found, it may be due to the fact
-that the location is in a shared library that is yet to be loaded. In such
-a case, you may want @value{GDBN} to create a special breakpoint (known as
-a @dfn{pending breakpoint}) that
-attempts to resolve itself in the future when an appropriate shared library
-gets loaded.
-
-Pending breakpoints are useful to set at the start of your
-@value{GDBN} session for locations that you know will be dynamically loaded
-later by the program being debugged. When shared libraries are loaded,
-a check is made to see if the load resolves any pending breakpoint locations.
-If a pending breakpoint location gets resolved,
-a regular breakpoint is created and the original pending breakpoint is removed.
-
-@value{GDBN} provides some additional commands for controlling pending
-breakpoint support:
+It's quite common to have a breakpoint inside a shared library.
+Shared libraries can be loaded and unloaded explicitly,
+and possibly repeatedly, as the program is executed. To support
+this use case, @value{GDBN} updates breakpoint locations whenever
+any shared library is loaded or unloaded. Typically, you would
+set a breakpoint in a shared library at the beginning of your
+debugging session, when the library is not loaded, and when the
+symbols from the library are not available. When you try to set
+breakpoint, @value{GDBN} will ask you if you want to set
+a so called @dfn{pending breakpoint}---breakpoint whose address
+is not yet resolved.
+
+After the program is run, whenever a new shared library is loaded,
+@value{GDBN} reevaluates all the breakpoints. When a newly loaded
+shared library contains the symbol or line referred to by some
+pending breakpoint, that breakpoint is resolved and becomes an
+ordinary breakpoint. When a library is unloaded, all breakpoints
+that refer to its symbols or source lines become pending again.
+
+This logic works for breakpoints with multiple locations, too. For
+example, if you have a breakpoint in a C@t{++} template function, and
+a newly loaded shared library has an instantiation of that template,
+a new location is added to the list of locations for the breakpoint.
+
+Except for having unresolved address, pending breakpoints do not
+differ from regular breakpoints. You can set conditions or commands,
+enable and disable them and perform other breakpoint operations.
+
+@value{GDBN} provides some additional commands for controlling what
+happens when the @samp{break} command cannot resolve breakpoint
+address specification to an address:
@kindex set breakpoint pending
@kindex show breakpoint pending
Show the current behavior setting for creating pending breakpoints.
@end table
-@cindex operations allowed on pending breakpoints
-Normal breakpoint operations apply to pending breakpoints as well. You may
-specify a condition for a pending breakpoint and/or commands to run when the
-breakpoint is reached. You can also enable or disable
-the pending breakpoint. When you specify a condition for a pending breakpoint,
-the parsing of the condition will be deferred until the point where the
-pending breakpoint location is resolved. Disabling a pending breakpoint
-tells @value{GDBN} to not attempt to resolve the breakpoint on any subsequent
-shared library load. When a pending breakpoint is re-enabled,
-@value{GDBN} checks to see if the location is already resolved.
-This is done because any number of shared library loads could have
-occurred since the time the breakpoint was disabled and one or more
-of these loads could resolve the location.
+The settings above only affect the @code{break} command and its
+variants. Once breakpoint is set, it will be automatically updated
+as shared libraries are loaded and unloaded.
@cindex automatic hardware breakpoints
For some targets, @value{GDBN} can automatically decide if hardware or
breakpoint address is read-only or read-write. This applies to
breakpoints set with the @code{break} command as well as to internal
breakpoints set by commands like @code{next} and @code{finish}. For
-breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
+breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
breakpoints.
You can control this automatic behaviour with the following commands::
trying to set software breakpoint at a read-only address.
@end table
+@value{GDBN} normally implements breakpoints by replacing the program code
+at the breakpoint address with a special instruction, which, when
+executed, given control to the debugger. By default, the program
+code is so modified only when the program is resumed. As soon as
+the program stops, @value{GDBN} restores the original instructions. This
+behaviour guards against leaving breakpoints inserted in the
+target should gdb abrubptly disconnect. However, with slow remote
+targets, inserting and removing breakpoint can reduce the performance.
+This behavior can be controlled with the following commands::
+
+@kindex set breakpoint always-inserted
+@kindex show breakpoint always-inserted
+@table @code
+@item set breakpoint always-inserted off
+All breakpoints, including newly added by the user, are inserted in
+the target only when the target is resumed. All breakpoints are
+removed from the target when it stops.
+
+@item set breakpoint always-inserted on
+Causes all breakpoints to be inserted in the target at all times. If
+the user adds a new breakpoint, or changes an existing breakpoint, the
+breakpoints in the target are updated immediately. A breakpoint is
+removed from the target only when breakpoint itself is removed.
+
+@cindex non-stop mode, and @code{breakpoint always-inserted}
+@item set breakpoint always-inserted auto
+This is the default mode. If @value{GDBN} is controlling the inferior
+in non-stop mode (@pxref{Non-Stop Mode}), gdb behaves as if
+@code{breakpoint always-inserted} mode is on. If @value{GDBN} is
+controlling the inferior in all-stop mode, @value{GDBN} behaves as if
+@code{breakpoint always-inserted} mode is off.
+@end table
@cindex negative breakpoint numbers
@cindex internal @value{GDBN} breakpoints
language (@pxref{Languages}).
@end itemize
+You can set a watchpoint on an expression even if the expression can
+not be evaluated yet. For instance, you can set a watchpoint on
+@samp{*global_ptr} before @samp{global_ptr} is initialized.
+@value{GDBN} will stop when your program sets @samp{global_ptr} and
+the expression produces a valid value. If the expression becomes
+valid in some other way than changing a variable (e.g.@: if the memory
+pointed to by @samp{*global_ptr} becomes readable as the result of a
+@code{malloc} call), @value{GDBN} may not stop until the next time
+the expression changes.
+
@cindex software watchpoints
@cindex hardware watchpoints
Depending on your system, watchpoints may be implemented in software or
catch errors where you have no clue what part of your program is the
culprit.)
-On some systems, such as HP-UX, @sc{gnu}/Linux and most other
+On some systems, such as HP-UX, PowerPC, @sc{gnu}/Linux and most other
x86-based targets, @value{GDBN} includes support for hardware
watchpoints, which do not slow down the running of your program.
@table @code
@kindex watch
-@item watch @var{expr}
+@item watch @var{expr} @r{[}thread @var{threadnum}@r{]}
Set a watchpoint for an expression. @value{GDBN} will break when the
expression @var{expr} is written into by the program and its value
changes. The simplest (and the most popular) use of this command is
(@value{GDBP}) watch foo
@end smallexample
+If the command includes a @code{@r{[}thread @var{threadnum}@r{]}}
+clause, @value{GDBN} breaks only when the thread identified by
+@var{threadnum} changes the value of @var{expr}. If any other threads
+change the value of @var{expr}, @value{GDBN} will not break. Note
+that watchpoints restricted to a single thread in this way only work
+with Hardware Watchpoints.
+
@kindex rwatch
-@item rwatch @var{expr}
+@item rwatch @var{expr} @r{[}thread @var{threadnum}@r{]}
Set a watchpoint that will break when the value of @var{expr} is read
by the program.
@kindex awatch
-@item awatch @var{expr}
+@item awatch @var{expr} @r{[}thread @var{threadnum}@r{]}
Set a watchpoint that will break when @var{expr} is either read from
or written into by the program.
That's because @value{GDBN} needs to watch every variable in the
expression with separately allocated resources.
-The SPARClite DSU will generate traps when a program accesses some data
-or instruction address that is assigned to the debug registers. For the
-data addresses, DSU facilitates the @code{watch} command. However the
-hardware breakpoint registers can only take two data watchpoints, and
-both watchpoints must be the same kind. For example, you can set two
-watchpoints with @code{watch} commands, two with @code{rwatch} commands,
-@strong{or} two with @code{awatch} commands, but you cannot set one
-watchpoint with one command and the other with a different command.
-@value{GDBN} will reject the command if you try to mix watchpoints.
-Delete or disable unused watchpoint commands before setting new ones.
-
If you call a function interactively using @code{print} or @code{call},
any watchpoints you have set will be inactive until @value{GDBN} reaches another
kind of breakpoint or the call completes.
way of doing that would be to set a code breakpoint at the entry to the
@code{main} function and when it breaks, set all the watchpoints.
-@quotation
@cindex watchpoints and threads
@cindex threads and watchpoints
-@emph{Warning:} In multi-thread programs, watchpoints have only limited
-usefulness. With the current watchpoint implementation, @value{GDBN}
-can only watch the value of an expression @emph{in a single thread}. If
-you are confident that the expression can only change due to the current
-thread's activity (and if you are also confident that no other thread
-can become current), then you can use watchpoints as usual. However,
-@value{GDBN} may not notice when a non-current thread's activity changes
-the expression.
-
-@c FIXME: this is almost identical to the previous paragraph.
-@emph{HP-UX Warning:} In multi-thread programs, software watchpoints
+In multi-threaded programs, watchpoints will detect changes to the
+watched expression from every thread.
+
+@quotation
+@emph{Warning:} In multi-threaded programs, software watchpoints
have only limited usefulness. If @value{GDBN} creates a software
watchpoint, it can only watch the value of an expression @emph{in a
single thread}. If you are confident that the expression can only
the debugger will stop only when this specific exception is raised.
Otherwise, the debugger stops execution when any Ada exception is raised.
+When inserting an exception catchpoint on a user-defined exception whose
+name is identical to one of the exceptions defined by the language, the
+fully qualified name must be used as the exception name. Otherwise,
+@value{GDBN} will assume that it should stop on the pre-defined exception
+rather than the user-defined one. For instance, assuming an exception
+called @code{Constraint_Error} is defined in package @code{Pck}, then
+the command to use to catch such exceptions is @kbd{catch exception
+Pck.Constraint_Error}.
+
@item exception unhandled
An exception that was raised but is not handled by the program.
@item exec
@cindex break on fork/exec
-A call to @code{exec}. This is currently only available for HP-UX.
+A call to @code{exec}. This is currently only available for HP-UX
+and @sc{gnu}/Linux.
@item fork
-A call to @code{fork}. This is currently only available for HP-UX.
+A call to @code{fork}. This is currently only available for HP-UX
+and @sc{gnu}/Linux.
@item vfork
-A call to @code{vfork}. This is currently only available for HP-UX.
-
-@item load
-@itemx load @var{libname}
-@cindex break on load/unload of shared library
-The dynamic loading of any shared library, or the loading of the library
-@var{libname}. This is currently only available for HP-UX.
+A call to @code{vfork}. This is currently only available for HP-UX
+and @sc{gnu}/Linux.
-@item unload
-@itemx unload @var{libname}
-The unloading of any dynamically loaded shared library, or the unloading
-of the library @var{libname}. This is currently only available for HP-UX.
@end table
@item tcatch @var{event}
the innermost frame is selected, this is a good way to delete a
breakpoint where your program just stopped.
+@item clear @var{location}
+Delete any breakpoints set at the specified @var{location}.
+@xref{Specify Location}, for the various forms of @var{location}; the
+most useful ones are listed below:
+
+@table @code
@item clear @var{function}
@itemx clear @var{filename}:@var{function}
Delete any breakpoints set at entry to the named @var{function}.
@itemx clear @var{filename}:@var{linenum}
Delete any breakpoints set at or within the code of the specified
@var{linenum} of the specified @var{filename}.
+@end table
@cindex delete breakpoints
@kindex delete
@code{info watch} to print a list of breakpoints, watchpoints, and
catchpoints if you do not know which numbers to use.
+Disabling and enabling a breakpoint that has multiple locations
+affects all of its locations.
+
A breakpoint, watchpoint, or catchpoint can have any of four different
states of enablement:
end
@end smallexample
-@node Breakpoint Menus
-@subsection Breakpoint Menus
-@cindex overloading
-@cindex symbol overloading
-
-Some programming languages (notably C@t{++} and Objective-C) permit a
-single function name
-to be defined several times, for application in different contexts.
-This is called @dfn{overloading}. When a function name is overloaded,
-@samp{break @var{function}} is not enough to tell @value{GDBN} where you want
-a breakpoint. If you realize this is a problem, you can use
-something like @samp{break @var{function}(@var{types})} to specify which
-particular version of the function you want. Otherwise, @value{GDBN} offers
-you a menu of numbered choices for different possible breakpoints, and
-waits for your selection with the prompt @samp{>}. The first two
-options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1}
-sets a breakpoint at each definition of @var{function}, and typing
-@kbd{0} aborts the @code{break} command without setting any new
-breakpoints.
-
-For example, the following session excerpt shows an attempt to set a
-breakpoint at the overloaded symbol @code{String::after}.
-We choose three particular definitions of that function name:
-
-@c FIXME! This is likely to change to show arg type lists, at least
-@smallexample
-@group
-(@value{GDBP}) b String::after
-[0] cancel
-[1] all
-[2] file:String.cc; line number:867
-[3] file:String.cc; line number:860
-[4] file:String.cc; line number:875
-[5] file:String.cc; line number:853
-[6] file:String.cc; line number:846
-[7] file:String.cc; line number:735
-> 2 4 6
-Breakpoint 1 at 0xb26c: file String.cc, line 867.
-Breakpoint 2 at 0xb344: file String.cc, line 875.
-Breakpoint 3 at 0xafcc: file String.cc, line 846.
-Multiple breakpoints were set.
-Use the "delete" command to delete unwanted
- breakpoints.
-(@value{GDBP})
-@end group
-@end smallexample
-
@c @ifclear BARETARGET
@node Error in Breakpoints
@subsection ``Cannot insert breakpoints''
-@c
-@c FIXME!! 14/6/95 Is there a real example of this? Let's use it.
-@c
-Under some operating systems, breakpoints cannot be used in a program if
-any other process is running that program. In this situation,
-attempting to run or continue a program with a breakpoint causes
-@value{GDBN} to print an error message:
-
-@smallexample
-Cannot insert breakpoints.
-The same program may be running in another process.
-@end smallexample
-When this happens, you have three ways to proceed:
-
-@enumerate
-@item
-Remove or disable the breakpoints, then continue.
-
-@item
-Suspend @value{GDBN}, and copy the file containing your program to a new
-name. Resume @value{GDBN} and use the @code{exec-file} command to specify
-that @value{GDBN} should run your program under that name.
-Then start your program again.
-
-@item
-Relink your program so that the text segment is nonsharable, using the
-linker option @samp{-N}. The operating system limitation may not apply
-to nonsharable executables.
-@end enumerate
-@c @end ifclear
-
-A similar message can be printed if you request too many active
-hardware-assisted breakpoints and watchpoints:
+If you request too many active hardware-assisted breakpoints and
+watchpoints, you will see this error message:
@c FIXME: the precise wording of this message may change; the relevant
@c source change is not committed yet (Sep 3, 1999).
source line debug information.
@kindex finish
+@kindex fin @r{(@code{finish})}
@item finish
Continue running until just after function in the selected stack frame
-returns. Print the returned value (if any).
+returns. Print the returned value (if any). This command can be
+abbreviated as @code{fin}.
Contrast this with the @code{return} command (@pxref{Returning,
,Returning from a Function}).
@itemx u @var{location}
Continue running your program until either the specified location is
reached, or the current stack frame returns. @var{location} is any of
-the forms of argument acceptable to @code{break} (@pxref{Set Breaks,
-,Setting Breakpoints}). This form of the command uses breakpoints, and
+the forms described in @ref{Specify Location}.
+This form of the command uses temporary breakpoints, and
hence is quicker than @code{until} without an argument. The specified
location is actually reached only if it is in the current frame. This
implies that @code{until} can be used to skip over recursive function
@kindex advance @var{location}
@itemx advance @var{location}
Continue running the program up to the given @var{location}. An argument is
-required, which should be of the same form as arguments for the @code{break}
-command. Execution will also stop upon exit from the current stack
+required, which should be of one of the forms described in
+@ref{Specify Location}.
+Execution will also stop upon exit from the current stack
frame. This command is similar to @code{until}, but @code{advance} will
not skip over recursive function calls, and the target location doesn't
have to be in the same frame as the current one.
@node Thread Stops
@section Stopping and Starting Multi-thread Programs
+@cindex stopped threads
+@cindex threads, stopped
+
+@cindex continuing threads
+@cindex threads, continuing
+
+@value{GDBN} supports debugging programs with multiple threads
+(@pxref{Threads,, Debugging Programs with Multiple Threads}). There
+are two modes of controlling execution of your program within the
+debugger. In the default mode, referred to as @dfn{all-stop mode},
+when any thread in your program stops (for example, at a breakpoint
+or while being stepped), all other threads in the program are also stopped by
+@value{GDBN}. On some targets, @value{GDBN} also supports
+@dfn{non-stop mode}, in which other threads can continue to run freely while
+you examine the stopped thread in the debugger.
+
+@menu
+* All-Stop Mode:: All threads stop when GDB takes control
+* Non-Stop Mode:: Other threads continue to execute
+* Background Execution:: Running your program asynchronously
+* Thread-Specific Breakpoints:: Controlling breakpoints
+* Interrupted System Calls:: GDB may interfere with system calls
+@end menu
+
+@node All-Stop Mode
+@subsection All-Stop Mode
+
+@cindex all-stop mode
+
+In all-stop mode, whenever your program stops under @value{GDBN} for any reason,
+@emph{all} threads of execution stop, not just the current thread. This
+allows you to examine the overall state of the program, including
+switching between threads, without worrying that things may change
+underfoot.
+
+Conversely, whenever you restart the program, @emph{all} threads start
+executing. @emph{This is true even when single-stepping} with commands
+like @code{step} or @code{next}.
+
+In particular, @value{GDBN} cannot single-step all threads in lockstep.
+Since thread scheduling is up to your debugging target's operating
+system (not controlled by @value{GDBN}), other threads may
+execute more than one statement while the current thread completes a
+single step. Moreover, in general other threads stop in the middle of a
+statement, rather than at a clean statement boundary, when the program
+stops.
+
+You might even find your program stopped in another thread after
+continuing or even single-stepping. This happens whenever some other
+thread runs into a breakpoint, a signal, or an exception before the
+first thread completes whatever you requested.
+
+@cindex automatic thread selection
+@cindex switching threads automatically
+@cindex threads, automatic switching
+Whenever @value{GDBN} stops your program, due to a breakpoint or a
+signal, it automatically selects the thread where that breakpoint or
+signal happened. @value{GDBN} alerts you to the context switch with a
+message such as @samp{[Switching to Thread @var{n}]} to identify the
+thread.
+
+On some OSes, you can modify @value{GDBN}'s default behavior by
+locking the OS scheduler to allow only a single thread to run.
+
+@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}
+mode optimizes for single-stepping; it prevents other threads
+from preempting the current thread while you are stepping, so that
+the focus of debugging does not change unexpectedly.
+Other threads only rarely (or never) get a chance to run
+when you step. They are more likely to run when you @samp{next} over a
+function call, and they are completely free to run when you use commands
+like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another
+thread hits a breakpoint during its timeslice, @value{GDBN} does not change
+the current thread away from the thread that you are debugging.
+
+@item show scheduler-locking
+Display the current scheduler locking mode.
+@end table
+
+@node Non-Stop Mode
+@subsection Non-Stop Mode
+
+@cindex non-stop mode
+
+@c This section is really only a place-holder, and needs to be expanded
+@c with more details.
+
+For some multi-threaded targets, @value{GDBN} supports an optional
+mode of operation in which you can examine stopped program threads in
+the debugger while other threads continue to execute freely. This
+minimizes intrusion when debugging live systems, such as programs
+where some threads have real-time constraints or must continue to
+respond to external events. This is referred to as @dfn{non-stop} mode.
+
+In non-stop mode, when a thread stops to report a debugging event,
+@emph{only} that thread is stopped; @value{GDBN} does not stop other
+threads as well, in contrast to the all-stop mode behavior. Additionally,
+execution commands such as @code{continue} and @code{step} apply by default
+only to the current thread in non-stop mode, rather than all threads as
+in all-stop mode. This allows you to control threads explicitly in
+ways that are not possible in all-stop mode --- for example, stepping
+one thread while allowing others to run freely, stepping
+one thread while holding all others stopped, or stepping several threads
+independently and simultaneously.
+
+To enter non-stop mode, use this sequence of commands before you run
+or attach to your program:
+
+@smallexample
+# Enable the async interface.
+set target-async 1
+
+# If using the CLI, pagination breaks non-stop.
+set pagination off
+
+# Finally, turn it on!
+set non-stop on
+@end smallexample
+
+You can use these commands to manipulate the non-stop mode setting:
+
+@table @code
+@kindex set non-stop
+@item set non-stop on
+Enable selection of non-stop mode.
+@item set non-stop off
+Disable selection of non-stop mode.
+@kindex show non-stop
+@item show non-stop
+Show the current non-stop enablement setting.
+@end table
+
+Note these commands only reflect whether non-stop mode is enabled,
+not whether the currently-executing program is being run in non-stop mode.
+In particular, the @code{set non-stop} preference is only consulted when
+@value{GDBN} starts or connects to the target program, and it is generally
+not possible to switch modes once debugging has started. Furthermore,
+since not all targets support non-stop mode, even when you have enabled
+non-stop mode, @value{GDBN} may still fall back to all-stop operation by
+default.
+
+In non-stop mode, all execution commands apply only to the current thread
+by default. That is, @code{continue} only continues one thread.
+To continue all threads, issue @code{continue -a} or @code{c -a}.
+
+You can use @value{GDBN}'s background execution commands
+(@pxref{Background Execution}) to run some threads in the background
+while you continue to examine or step others from @value{GDBN}.
+The MI execution commands (@pxref{GDB/MI Program Execution}) are
+always executed asynchronously in non-stop mode.
+
+Suspending execution is done with the @code{interrupt} command when
+running in the background, or @kbd{Ctrl-c} during foreground execution.
+In all-stop mode, this stops the whole process;
+but in non-stop mode the interrupt applies only to the current thread.
+To stop the whole program, use @code{interrupt -a}.
+
+Other execution commands do not currently support the @code{-a} option.
+
+In non-stop mode, when a thread stops, @value{GDBN} doesn't automatically make
+that thread current, as it does in all-stop mode. This is because the
+thread stop notifications are asynchronous with respect to @value{GDBN}'s
+command interpreter, and it would be confusing if @value{GDBN} unexpectedly
+changed to a different thread just as you entered a command to operate on the
+previously current thread.
+
+@node Background Execution
+@subsection Background Execution
+
+@cindex foreground execution
+@cindex background execution
+@cindex asynchronous execution
+@cindex execution, foreground, background and asynchronous
+
+@value{GDBN}'s execution commands have two variants: the normal
+foreground (synchronous) behavior, and a background
+(asynchronous) behavior. In foreground execution, @value{GDBN} waits for
+the program to report that some thread has stopped before prompting for
+another command. In background execution, @value{GDBN} immediately gives
+a command prompt so that you can issue other commands while your program runs.
+
+To specify background execution, add a @code{&} to the command. For example,
+the background form of the @code{continue} command is @code{continue&}, or
+just @code{c&}. The execution commands that accept background execution
+are:
+
+@table @code
+@kindex run&
+@item run
+@xref{Starting, , Starting your Program}.
+
+@item attach
+@kindex attach&
+@xref{Attach, , Debugging an Already-running Process}.
+
+@item step
+@kindex step&
+@xref{Continuing and Stepping, step}.
+
+@item stepi
+@kindex stepi&
+@xref{Continuing and Stepping, stepi}.
+
+@item next
+@kindex next&
+@xref{Continuing and Stepping, next}.
+
+@item nexti
+@kindex nexti&
+@xref{Continuing and Stepping, nexti}.
+
+@item continue
+@kindex continue&
+@xref{Continuing and Stepping, continue}.
+
+@item finish
+@kindex finish&
+@xref{Continuing and Stepping, finish}.
+
+@item until
+@kindex until&
+@xref{Continuing and Stepping, until}.
+
+@end table
+
+Background execution is especially useful in conjunction with non-stop
+mode for debugging programs with multiple threads; see @ref{Non-Stop Mode}.
+However, you can also use these commands in the normal all-stop mode with
+the restriction that you cannot issue another execution command until the
+previous one finishes. Examples of commands that are valid in all-stop
+mode while the program is running include @code{help} and @code{info break}.
+
+You can interrupt your program while it is running in the background by
+using the @code{interrupt} command.
+
+@table @code
+@kindex interrupt
+@item interrupt
+@itemx interrupt -a
+
+Suspend execution of the running program. In all-stop mode,
+@code{interrupt} stops the whole process, but in non-stop mode, it stops
+only the current thread. To stop the whole program in non-stop mode,
+use @code{interrupt -a}.
+@end table
+
+You may need to explicitly enable async mode before you can use background
+execution commands, with the @code{set target-async 1} command. If the
+target doesn't support async mode, @value{GDBN} issues an error message
+if you attempt to use the background execution commands.
+
+@node Thread-Specific Breakpoints
+@subsection Thread-Specific Breakpoints
+
When your program has multiple threads (@pxref{Threads,, Debugging
Programs with Multiple Threads}), you can choose whether to set
breakpoints on all threads, or on a particular thread.
@item break @var{linespec} thread @var{threadno}
@itemx break @var{linespec} thread @var{threadno} if @dots{}
@var{linespec} specifies source lines; there are several ways of
-writing them, but the effect is always to specify some source line.
+writing them (@pxref{Specify Location}), but the effect is always to
+specify some source line.
Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
to specify that you only want @value{GDBN} to stop the program when a
@end table
-@cindex stopped threads
-@cindex threads, stopped
-Whenever your program stops under @value{GDBN} for any reason,
-@emph{all} threads of execution stop, not just the current thread. This
-allows you to examine the overall state of the program, including
-switching between threads, without worrying that things may change
-underfoot.
+@node Interrupted System Calls
+@subsection Interrupted System Calls
@cindex thread breakpoints and system calls
@cindex system calls and thread breakpoints
@cindex premature return from system calls
-There is an unfortunate side effect. If one thread stops for a
+There is an unfortunate side effect when using @value{GDBN} to debug
+multi-threaded programs. If one thread stops for a
breakpoint, or for some other reason, and another thread is blocked in a
system call, then the system call may return prematurely. This is a
consequence of the interaction between multiple threads and the signals
When such an event happens, a system call in another thread may return
prematurely, even though your program does not appear to stop.
-@cindex continuing threads
-@cindex threads, continuing
-Conversely, whenever you restart the program, @emph{all} threads start
-executing. @emph{This is true even when single-stepping} with commands
-like @code{step} or @code{next}.
-
-In particular, @value{GDBN} cannot single-step all threads in lockstep.
-Since thread scheduling is up to your debugging target's operating
-system (not controlled by @value{GDBN}), other threads may
-execute more than one statement while the current thread completes a
-single step. Moreover, in general other threads stop in the middle of a
-statement, rather than at a clean statement boundary, when the program
-stops.
-
-You might even find your program stopped in another thread after
-continuing or even single-stepping. This happens whenever some other
-thread runs into a breakpoint, a signal, or an exception before the
-first thread completes whatever you requested.
-On some OSes, you can lock the OS scheduler and thus allow only a single
-thread to run.
+@node Reverse Execution
+@chapter Running programs backward
+@cindex reverse execution
+@cindex running programs backward
+
+When you are debugging a program, it is not unusual to realize that
+you have gone too far, and some event of interest has already happened.
+If the target environment supports it, @value{GDBN} can allow you to
+``rewind'' the program by running it backward.
+
+A target environment that supports reverse execution should be able
+to ``undo'' the changes in machine state that have taken place as the
+program was executing normally. Variables, registers etc.@: should
+revert to their previous values. Obviously this requires a great
+deal of sophistication on the part of the target environment; not
+all target environments can support reverse execution.
+
+When a program is executed in reverse, the instructions that
+have most recently been executed are ``un-executed'', in reverse
+order. The program counter runs backward, following the previous
+thread of execution in reverse. As each instruction is ``un-executed'',
+the values of memory and/or registers that were changed by that
+instruction are reverted to their previous states. After executing
+a piece of source code in reverse, all side effects of that code
+should be ``undone'', and all variables should be returned to their
+prior values@footnote{
+Note that some side effects are easier to undo than others. For instance,
+memory and registers are relatively easy, but device I/O is hard. Some
+targets may be able undo things like device I/O, and some may not.
+
+The contract between @value{GDBN} and the reverse executing target
+requires only that the target do something reasonable when
+@value{GDBN} tells it to execute backwards, and then report the
+results back to @value{GDBN}. Whatever the target reports back to
+@value{GDBN}, @value{GDBN} will report back to the user. @value{GDBN}
+assumes that the memory and registers that the target reports are in a
+consistant state, but @value{GDBN} accepts whatever it is given.
+}.
+
+If you are debugging in a target environment that supports
+reverse execution, @value{GDBN} provides the following commands.
@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}
-mode optimizes for single-stepping. It stops other threads from
-``seizing the prompt'' by preempting the current thread while you are
-stepping. Other threads will only rarely (or never) get a chance to run
-when you step. They are more likely to run when you @samp{next} over a
-function call, and they are completely free to run when you use commands
-like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another
-thread hits a breakpoint during its timeslice, they will never steal the
-@value{GDBN} prompt away from the thread that you are debugging.
-
-@item show scheduler-locking
-Display the current scheduler locking mode.
+@kindex reverse-continue
+@kindex rc @r{(@code{reverse-continue})}
+@item reverse-continue @r{[}@var{ignore-count}@r{]}
+@itemx rc @r{[}@var{ignore-count}@r{]}
+Beginning at the point where your program last stopped, start executing
+in reverse. Reverse execution will stop for breakpoints and synchronous
+exceptions (signals), just like normal execution. Behavior of
+asynchronous signals depends on the target environment.
+
+@kindex reverse-step
+@kindex rs @r{(@code{step})}
+@item reverse-step @r{[}@var{count}@r{]}
+Run the program backward until control reaches the start of a
+different source line; then stop it, and return control to @value{GDBN}.
+
+Like the @code{step} command, @code{reverse-step} will only stop
+at the beginning of a source line. It ``un-executes'' the previously
+executed source line. If the previous source line included calls to
+debuggable functions, @code{reverse-step} will step (backward) into
+the called function, stopping at the beginning of the @emph{last}
+statement in the called function (typically a return statement).
+
+Also, as with the @code{step} command, if non-debuggable functions are
+called, @code{reverse-step} will run thru them backward without stopping.
+
+@kindex reverse-stepi
+@kindex rsi @r{(@code{reverse-stepi})}
+@item reverse-stepi @r{[}@var{count}@r{]}
+Reverse-execute one machine instruction. Note that the instruction
+to be reverse-executed is @emph{not} the one pointed to by the program
+counter, but the instruction executed prior to that one. For instance,
+if the last instruction was a jump, @code{reverse-stepi} will take you
+back from the destination of the jump to the jump instruction itself.
+
+@kindex reverse-next
+@kindex rn @r{(@code{reverse-next})}
+@item reverse-next @r{[}@var{count}@r{]}
+Run backward to the beginning of the previous line executed in
+the current (innermost) stack frame. If the line contains function
+calls, they will be ``un-executed'' without stopping. Starting from
+the first line of a function, @code{reverse-next} will take you back
+to the caller of that function, @emph{before} the function was called,
+just as the normal @code{next} command would take you from the last
+line of a function back to its return to its caller
+@footnote{Unles the code is too heavily optimized.}.
+
+@kindex reverse-nexti
+@kindex rni @r{(@code{reverse-nexti})}
+@item reverse-nexti @r{[}@var{count}@r{]}
+Like @code{nexti}, @code{reverse-nexti} executes a single instruction
+in reverse, except that called functions are ``un-executed'' atomically.
+That is, if the previously executed instruction was a return from
+another instruction, @code{reverse-nexti} will continue to execute
+in reverse until the call to that function (from the current stack
+frame) is reached.
+
+@kindex reverse-finish
+@item reverse-finish
+Just as the @code{finish} command takes you to the point where the
+current function returns, @code{reverse-finish} takes you to the point
+where it was called. Instead of ending up at the end of the current
+function invocation, you end up at the beginning.
+
+@kindex set exec-direction
+@item set exec-direction
+Set the direction of target execution.
+@itemx set exec-direction reverse
+@cindex execute forward or backward in time
+@value{GDBN} will perform all execution commands in reverse, until the
+exec-direction mode is changed to ``forward''. Affected commands include
+@code{step, stepi, next, nexti, continue, and finish}. The @code{return}
+command cannot be used in reverse mode.
+@item set exec-direction forward
+@value{GDBN} will perform all execution commands in the normal fashion.
+This is the default.
@end table
@menu
* List:: Printing source lines
+* Specify Location:: How to specify code locations
* Edit:: Editing source files
* Search:: Searching source files
* Source Path:: Specifying source directories
@kindex l @r{(@code{list})}
To print lines from a source file, use the @code{list} command
(abbreviated @code{l}). By default, ten lines are printed.
-There are several ways to specify what part of the file you want to print.
+There are several ways to specify what part of the file you want to
+print; see @ref{Specify Location}, for the full list.
Here are the forms of the @code{list} command most commonly used:
argument of @samp{-}; that argument is preserved in repetition so that
each repetition moves up in the source file.
-@cindex linespec
In general, the @code{list} command expects you to supply zero, one or two
@dfn{linespecs}. Linespecs specify source lines; there are several ways
-of writing them, but the effect is always to specify some source line.
+of writing them (@pxref{Specify Location}), but the effect is always
+to specify some source line.
+
Here is a complete description of the possible arguments for @code{list}:
@table @code
@item list @var{first},@var{last}
Print lines from @var{first} to @var{last}. Both arguments are
-linespecs.
+linespecs. When a @code{list} command has two linespecs, and the
+source file of the second linespec is omitted, this refers to
+the same source file as the first linespec.
@item list ,@var{last}
Print lines ending with @var{last}.
As described in the preceding table.
@end table
-Here are the ways of specifying a single source line---all the
-kinds of linespec.
+@node Specify Location
+@section Specifying a Location
+@cindex specifying location
+@cindex linespec
-@table @code
-@item @var{number}
-Specifies line @var{number} of the current source file.
-When a @code{list} command has two linespecs, this refers to
-the same source file as the first linespec.
+Several @value{GDBN} commands accept arguments that specify a location
+of your program's code. Since @value{GDBN} is a source-level
+debugger, a location usually specifies some line in the source code;
+for that reason, locations are also known as @dfn{linespecs}.
-@item +@var{offset}
-Specifies the line @var{offset} lines after the last line printed.
-When used as the second linespec in a @code{list} command that has
-two, this specifies the line @var{offset} lines down from the
-first linespec.
+Here are all the different ways of specifying a code location that
+@value{GDBN} understands:
-@item -@var{offset}
-Specifies the line @var{offset} lines before the last line printed.
+@table @code
+@item @var{linenum}
+Specifies the line number @var{linenum} of the current source file.
-@item @var{filename}:@var{number}
-Specifies line @var{number} in the source file @var{filename}.
+@item -@var{offset}
+@itemx +@var{offset}
+Specifies the line @var{offset} lines before or after the @dfn{current
+line}. For the @code{list} command, the current line is the last one
+printed; for the breakpoint commands, this is the line at which
+execution stopped in the currently selected @dfn{stack frame}
+(@pxref{Frames, ,Frames}, for a description of stack frames.) When
+used as the second of the two linespecs in a @code{list} command,
+this specifies the line @var{offset} lines up or down from the first
+linespec.
+
+@item @var{filename}:@var{linenum}
+Specifies the line @var{linenum} in the source file @var{filename}.
@item @var{function}
Specifies the line that begins the body of the function @var{function}.
-For example: in C, this is the line with the open brace.
+For example, in C, this is the line with the open brace.
@item @var{filename}:@var{function}
-Specifies the line of the open-brace that begins the body of the
-function @var{function} in the file @var{filename}. You only need the
-file name with a function name to avoid ambiguity when there are
-identically named functions in different source files.
+Specifies the line that begins the body of the function @var{function}
+in the file @var{filename}. You only need the file name with a
+function name to avoid ambiguity when there are identically named
+functions in different source files.
@item *@var{address}
-Specifies the line containing the program address @var{address}.
-@var{address} may be any expression.
+Specifies the program address @var{address}. For line-oriented
+commands, such as @code{list} and @code{edit}, this specifies a source
+line that contains @var{address}. For @code{break} and other
+breakpoint oriented commands, this can be used to set breakpoints in
+parts of your program which do not have debugging information or
+source files.
+
+Here @var{address} may be any expression valid in the current working
+language (@pxref{Languages, working language}) that specifies a code
+address. In addition, as a convenience, @value{GDBN} extends the
+semantics of expressions used in locations to cover the situations
+that frequently happen during debugging. Here are the various forms
+of @var{address}:
+
+@table @code
+@item @var{expression}
+Any expression valid in the current working language.
+
+@item @var{funcaddr}
+An address of a function or procedure derived from its name. In C,
+C@t{++}, Java, Objective-C, Fortran, minimal, and assembly, this is
+simply the function's name @var{function} (and actually a special case
+of a valid expression). In Pascal and Modula-2, this is
+@code{&@var{function}}. In Ada, this is @code{@var{function}'Address}
+(although the Pascal form also works).
+
+This form specifies the address of the function's first instruction,
+before the stack frame and arguments have been set up.
+
+@item '@var{filename}'::@var{funcaddr}
+Like @var{funcaddr} above, but also specifies the name of the source
+file explicitly. This is useful if the name of the function does not
+specify the function unambiguously, e.g., if there are several
+functions with identical names in different source files.
+@end table
+
@end table
+
@node Edit
@section Editing Source Files
@cindex editing source files
is invoked with the current line set to
the active line in the program.
Alternatively, there are several ways to specify what part of the file you
-want to print if you want to see other parts of the program.
-
-Here are the forms of the @code{edit} command most commonly used:
+want to print if you want to see other parts of the program:
@table @code
-@item edit
-Edit the current source file at the active line number in the program.
+@item edit @var{location}
+Edit the source file specified by @code{location}. Editing starts at
+that @var{location}, e.g., at the specified source line of the
+specified file. @xref{Specify Location}, for all the possible forms
+of the @var{location} argument; here are the forms of the @code{edit}
+command most commonly used:
+@table @code
@item edit @var{number}
Edit the current source file with @var{number} as the active line number.
@item edit @var{function}
Edit the file containing @var{function} at the beginning of its definition.
+@end table
-@item edit @var{filename}:@var{number}
-Specifies line @var{number} in the source file @var{filename}.
-
-@item edit @var{filename}:@var{function}
-Specifies the line that begins the body of the
-function @var{function} in the file @var{filename}. You only need the
-file name with a function name to avoid ambiguity when there are
-identically named functions in different source files.
-
-@item edit *@var{address}
-Specifies the line containing the program address @var{address}.
-@var{address} may be any expression.
@end table
@subsection Choosing your Editor
@item info line @var{linespec}
Print the starting and ending addresses of the compiled code for
source line @var{linespec}. You can specify source lines in any of
-the ways understood by the @code{list} command (@pxref{List, ,Printing
-Source Lines}).
+the ways documented in @ref{Specify Location}.
@end table
For example, we can use @code{info line} to discover the location of
@cindex machine instructions
@cindex listing machine instructions
@item disassemble
+@itemx disassemble /m
This specialized command dumps a range of memory as machine
-instructions. The default memory range is the function surrounding the
+instructions. It can also print mixed source+disassembly by specifying
+the @code{/m} modifier.
+The default memory range is the function surrounding the
program counter of the selected frame. A single argument to this
command is a program counter value; @value{GDBN} dumps the function
surrounding this value. Two arguments specify a range of addresses
End of assembler dump.
@end smallexample
+Here is an example showing mixed source+assembly for Intel x86:
+
+@smallexample
+(@value{GDBP}) disas /m main
+Dump of assembler code for function main:
+5 @{
+0x08048330 <main+0>: push %ebp
+0x08048331 <main+1>: mov %esp,%ebp
+0x08048333 <main+3>: sub $0x8,%esp
+0x08048336 <main+6>: and $0xfffffff0,%esp
+0x08048339 <main+9>: sub $0x10,%esp
+
+6 printf ("Hello.\n");
+0x0804833c <main+12>: movl $0x8048440,(%esp)
+0x08048343 <main+19>: call 0x8048284 <puts@@plt>
+
+7 return 0;
+8 @}
+0x08048348 <main+24>: mov $0x0,%eax
+0x0804834d <main+29>: leave
+0x0804834e <main+30>: ret
+
+End of assembler dump.
+@end smallexample
+
Some architectures have more than one commonly-used set of instruction
mnemonics or other syntax.
@menu
* Expressions:: Expressions
+* Ambiguous Expressions:: Ambiguous Expressions
* Variables:: Program variables
* Arrays:: Artificial arrays
* Output Formats:: Output formats
* Character Sets:: Debugging programs that use a different
character set than GDB does
* Caching Remote Data:: Data caching for remote targets
+* Searching Memory:: Searching memory for a sequence of bytes
@end menu
@node Expressions
@cindex arrays in expressions
@value{GDBN} supports array constants in expressions input by
the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example,
-you can use the command @code{print @{1, 2, 3@}} to build up an array in
-memory that is @code{malloc}ed in the target program.
+you can use the command @code{print @{1, 2, 3@}} to create an array
+of three integers. If you pass an array to a function or assign it
+to a program variable, @value{GDBN} copies the array to memory that
+is @code{malloc}ed in the target program.
Because C is so widespread, most of the expressions shown in examples in
this manual are in C. @xref{Languages, , Using @value{GDBN} with Different
normally supposed to reside at @var{addr}.
@end table
+@node Ambiguous Expressions
+@section Ambiguous Expressions
+@cindex ambiguous expressions
+
+Expressions can sometimes contain some ambiguous elements. For instance,
+some programming languages (notably Ada, C@t{++} and Objective-C) permit
+a single function name to be defined several times, for application in
+different contexts. This is called @dfn{overloading}. Another example
+involving Ada is generics. A @dfn{generic package} is similar to C@t{++}
+templates and is typically instantiated several times, resulting in
+the same function name being defined in different contexts.
+
+In some cases and depending on the language, it is possible to adjust
+the expression to remove the ambiguity. For instance in C@t{++}, you
+can specify the signature of the function you want to break on, as in
+@kbd{break @var{function}(@var{types})}. In Ada, using the fully
+qualified name of your function often makes the expression unambiguous
+as well.
+
+When an ambiguity that needs to be resolved is detected, the debugger
+has the capability to display a menu of numbered choices for each
+possibility, and then waits for the selection with the prompt @samp{>}.
+The first option is always @samp{[0] cancel}, and typing @kbd{0 @key{RET}}
+aborts the current command. If the command in which the expression was
+used allows more than one choice to be selected, the next option in the
+menu is @samp{[1] all}, and typing @kbd{1 @key{RET}} selects all possible
+choices.
+
+For example, the following session excerpt shows an attempt to set a
+breakpoint at the overloaded symbol @code{String::after}.
+We choose three particular definitions of that function name:
+
+@c FIXME! This is likely to change to show arg type lists, at least
+@smallexample
+@group
+(@value{GDBP}) b String::after
+[0] cancel
+[1] all
+[2] file:String.cc; line number:867
+[3] file:String.cc; line number:860
+[4] file:String.cc; line number:875
+[5] file:String.cc; line number:853
+[6] file:String.cc; line number:846
+[7] file:String.cc; line number:735
+> 2 4 6
+Breakpoint 1 at 0xb26c: file String.cc, line 867.
+Breakpoint 2 at 0xb344: file String.cc, line 875.
+Breakpoint 3 at 0xafcc: file String.cc, line 846.
+Multiple breakpoints were set.
+Use the "delete" command to delete unwanted
+ breakpoints.
+(@value{GDBP})
+@end group
+@end smallexample
+
+@table @code
+@kindex set multiple-symbols
+@item set multiple-symbols @var{mode}
+@cindex multiple-symbols menu
+
+This option allows you to adjust the debugger behavior when an expression
+is ambiguous.
+
+By default, @var{mode} is set to @code{all}. If the command with which
+the expression is used allows more than one choice, then @value{GDBN}
+automatically selects all possible choices. For instance, inserting
+a breakpoint on a function using an ambiguous name results in a breakpoint
+inserted on each possible match. However, if a unique choice must be made,
+then @value{GDBN} uses the menu to help you disambiguate the expression.
+For instance, printing the address of an overloaded function will result
+in the use of the menu.
+
+When @var{mode} is set to @code{ask}, the debugger always uses the menu
+when an ambiguity is detected.
+
+Finally, when @var{mode} is set to @code{cancel}, the debugger reports
+an error due to the ambiguity and the command is aborted.
+
+@kindex show multiple-symbols
+@item show multiple-symbols
+Show the current value of the @code{multiple-symbols} setting.
+@end table
+
@node Variables
@section Program Variables
character representation is replaced with the octal escape @samp{\nnn}
for characters outside the 7-bit @sc{ascii} range.
+Without this format, @value{GDBN} displays @code{char},
+@w{@code{unsigned char}}, and @w{@code{signed char}} data as character
+constants. Single-byte members of vectors are displayed as integer
+data.
+
@item f
Regard the bits of the value as a floating point number and print
using typical floating point syntax.
+
+@item s
+@cindex printing strings
+@cindex printing byte arrays
+Regard as a string, if possible. With this format, pointers to single-byte
+data are displayed as null-terminated strings and arrays of single-byte data
+are displayed as fixed-length strings. Other values are displayed in their
+natural types.
+
+Without this format, @value{GDBN} displays pointers to and arrays of
+@code{char}, @w{@code{unsigned char}}, and @w{@code{signed char}} as
+strings. Single-byte members of a vector are displayed as an integer
+array.
@end table
For example, to print the program counter in hex (@pxref{Registers}), type
@item @var{f}, the display format
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}.
+@samp{f}, @samp{s}), and in addition @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
This display shows item numbers, expressions and their current values. As with
displays you request manually using @code{x} or @code{print}, you can
specify the output format you prefer; in fact, @code{display} decides
-whether to use @code{print} or @code{x} depending on how elaborate your
-format specification is---it uses @code{x} if you specify a unit size,
-or one of the two formats (@samp{i} and @samp{s}) that are only
-supported by @code{x}; otherwise it uses @code{print}.
+whether to use @code{print} or @code{x} depending your format
+specification---it uses @code{x} if you specify either the @samp{i}
+or @samp{s} format, or a unit size; otherwise it uses @code{print}.
@table @code
@kindex display
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 frame-arguments @var{value}
+@cindex printing frame argument values
+@cindex print all frame argument values
+@cindex print frame argument values for scalars only
+@cindex do not print frame argument values
+This command allows to control how the values of arguments are printed
+when the debugger prints a frame (@pxref{Frames}). The possible
+values are:
+
+@table @code
+@item all
+The values of all arguments are printed. This is the default.
+
+@item scalars
+Print the value of an argument only if it is a scalar. The value of more
+complex arguments such as arrays, structures, unions, etc, is replaced
+by @code{@dots{}}. Here is an example where only scalar arguments are shown:
+
+@smallexample
+#1 0x08048361 in call_me (i=3, s=@dots{}, ss=0xbf8d508c, u=@dots{}, e=green)
+ at frame-args.c:23
+@end smallexample
+
+@item none
+None of the argument values are printed. Instead, the value of each argument
+is replaced by @code{@dots{}}. In this case, the example above now becomes:
+
+@smallexample
+#1 0x08048361 in call_me (i=@dots{}, s=@dots{}, ss=@dots{}, u=@dots{}, e=@dots{})
+ at frame-args.c:23
+@end smallexample
+@end table
+
+By default, all argument values are always printed. But this command
+can be useful in several cases. For instance, it can be used to reduce
+the amount of information printed in each frame, making the backtrace
+more readable. Also, this command can be used to improve performance
+when displaying Ada frames, because the computation of large arguments
+can sometimes be CPU-intensive, especiallly in large applications.
+Setting @code{print frame-arguments} to @code{scalars} or @code{none}
+avoids this computation, thus speeding up the display of each Ada frame.
+
+@item show print frame-arguments
+Show how the value of arguments should be displayed when printing a frame.
+
@item set print repeats
@cindex repeated array elements
Set the threshold for suppressing display of repeated array
an unrecognized tag.
@end table
+On some targets, @value{GDBN} can access operating-system-specific information
+and display it to user, without interpretation. For remote targets,
+this functionality depends on the remote stub's support of the
+@samp{qXfer:osdata:read} packet, see @ref{qXfer osdata read}.
+
+@table @code
+@kindex info os processes
+@item info os processes
+Display the list of processes on the target. For each process,
+@value{GDBN} prints the process identifier, the name of the user, and
+the command corresponding to the process.
+@end table
@node Memory Region Attributes
@section Memory Region Attributes
to such memory. The checks are only performed if there's at least one
memory range defined. If @code{off} is specified, make @value{GDBN}
treat the memory not explicitly described by the memory ranges as RAM.
-The default value is @code{off}.
+The default value is @code{on}.
@kindex show mem inaccessible-by-default
@item show mem inaccessible-by-default
Show the current handling of accesses to unknown memory.
Print the information about the data cache performance. The
information displayed includes: the dcache width and depth; and for
each cache line, how many times it was referenced, and its data and
-state (dirty, bad, ok, etc.). This command is useful for debugging
+state (invalid, dirty, valid). This command is useful for debugging
the data cache operation.
@end table
+@node Searching Memory
+@section Search Memory
+@cindex searching memory
+
+Memory can be searched for a particular sequence of bytes with the
+@code{find} command.
+
+@table @code
+@kindex find
+@item find @r{[}/@var{sn}@r{]} @var{start_addr}, +@var{len}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]}
+@itemx find @r{[}/@var{sn}@r{]} @var{start_addr}, @var{end_addr}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]}
+Search memory for the sequence of bytes specified by @var{val1}, @var{val2},
+etc. The search begins at address @var{start_addr} and continues for either
+@var{len} bytes or through to @var{end_addr} inclusive.
+@end table
+
+@var{s} and @var{n} are optional parameters.
+They may be specified in either order, apart or together.
+
+@table @r
+@item @var{s}, search query size
+The size of each search query value.
+
+@table @code
+@item b
+bytes
+@item h
+halfwords (two bytes)
+@item w
+words (four bytes)
+@item g
+giant words (eight bytes)
+@end table
+
+All values are interpreted in the current language.
+This means, for example, that if the current source language is C/C@t{++}
+then searching for the string ``hello'' includes the trailing '\0'.
+
+If the value size is not specified, it is taken from the
+value's type in the current language.
+This is useful when one wants to specify the search
+pattern as a mixture of types.
+Note that this means, for example, that in the case of C-like languages
+a search for an untyped 0x42 will search for @samp{(int) 0x42}
+which is typically four bytes.
+
+@item @var{n}, maximum number of finds
+The maximum number of matches to print. The default is to print all finds.
+@end table
+
+You can use strings as search values. Quote them with double-quotes
+ (@code{"}).
+The string value is copied into the search pattern byte by byte,
+regardless of the endianness of the target and the size specification.
+
+The address of each match found is printed as well as a count of the
+number of matches found.
+
+The address of the last value found is stored in convenience variable
+@samp{$_}.
+A count of the number of matches is stored in @samp{$numfound}.
+
+For example, if stopped at the @code{printf} in this function:
+
+@smallexample
+void
+hello ()
+@{
+ static char hello[] = "hello-hello";
+ static struct @{ char c; short s; int i; @}
+ __attribute__ ((packed)) mixed
+ = @{ 'c', 0x1234, 0x87654321 @};
+ printf ("%s\n", hello);
+@}
+@end smallexample
+
+@noindent
+you get during debugging:
+
+@smallexample
+(gdb) find &hello[0], +sizeof(hello), "hello"
+0x804956d <hello.1620+6>
+1 pattern found
+(gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
+0x8049567 <hello.1620>
+0x804956d <hello.1620+6>
+2 patterns found
+(gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
+0x8049567 <hello.1620>
+1 pattern found
+(gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
+0x8049560 <mixed.1625>
+1 pattern found
+(gdb) print $numfound
+$1 = 1
+(gdb) print $_
+$2 = (void *) 0x8049560
+@end smallexample
@node Macros
@chapter C Preprocessor Macros
@value{GDBN} uses the macros in scope at the current listing location;
see @ref{List}.
-At the moment, @value{GDBN} does not support the @code{##}
-token-splicing operator, the @code{#} stringification operator, or
-variable-arity macros.
-
Whenever @value{GDBN} evaluates an expression, it always expands any
macro invocations present in the expression. @value{GDBN} also provides
the following commands for working with macros explicitly.
@cindex macros, user-defined
@item macro define @var{macro} @var{replacement-list}
@itemx macro define @var{macro}(@var{arglist}) @var{replacement-list}
-@i{(This command is not yet implemented.)} Introduce a definition for a
-preprocessor macro named @var{macro}, invocations of which are replaced
-by the tokens given in @var{replacement-list}. The first form of this
-command defines an ``object-like'' macro, which takes no arguments; the
-second form defines a ``function-like'' macro, which takes the arguments
-given in @var{arglist}.
-
-A definition introduced by this command is in scope in every expression
-evaluated in @value{GDBN}, until it is removed with the @command{macro
-undef} command, described below. The definition overrides all
-definitions for @var{macro} present in the program being debugged, as
-well as any previous user-supplied definition.
+Introduce a definition for a preprocessor macro named @var{macro},
+invocations of which are replaced by the tokens given in
+@var{replacement-list}. The first form of this command defines an
+``object-like'' macro, which takes no arguments; the second form
+defines a ``function-like'' macro, which takes the arguments given in
+@var{arglist}.
+
+A definition introduced by this command is in scope in every
+expression evaluated in @value{GDBN}, until it is removed with the
+@code{macro undef} command, described below. The definition overrides
+all definitions for @var{macro} present in the program being debugged,
+as well as any previous user-supplied definition.
@kindex macro undef
@item macro undef @var{macro}
-@i{(This command is not yet implemented.)} Remove any user-supplied
-definition for the macro named @var{macro}. This command only affects
-definitions provided with the @command{macro define} command, described
-above; it cannot remove definitions present in the program being
-debugged.
+Remove any user-supplied definition for the macro named @var{macro}.
+This command only affects definitions provided with the @code{macro
+define} command, described above; it cannot remove definitions present
+in the program being debugged.
@kindex macro list
@item macro list
-@i{(This command is not yet implemented.)} List all the macros
-defined using the @code{macro define} command.
+List all the macros defined using the @code{macro define} command.
@end table
@cindex macros, example of debugging with
(@value{GDBP})
@end smallexample
-In the example above, note that @command{macro expand-once} expands only
+In the example above, note that @code{macro expand-once} expands only
the macro invocation explicit in the original text --- the invocation of
@code{ADD} --- but does not expand the invocation of the macro @code{M},
which was introduced by @code{ADD}.
* C Checks:: C and C@t{++} type and range checks
* Debugging C:: @value{GDBN} and C
* Debugging C Plus Plus:: @value{GDBN} features for C@t{++}
+* Decimal Floating Point:: Numbers in Decimal Floating Point format
@end menu
@node C Operators
For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is
allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})}
-(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address
+to examine the address
where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is
stored.
@cindex break in overloaded functions
@item @r{breakpoint menus}
When you want a breakpoint in a function whose name is overloaded,
-@value{GDBN} breakpoint menus help you specify which function definition
-you want. @xref{Breakpoint Menus,,Breakpoint Menus}.
+@value{GDBN} has the capability to display a menu of possible breakpoint
+locations to help you specify which function definition you want.
+@xref{Ambiguous Expressions,,Ambiguous Expressions}.
@cindex overloading in C@t{++}
@item rbreak @var{regex}
@xref{Completion,, Command Completion}, for details on how to do this.
@end table
+@node Decimal Floating Point
+@subsubsection Decimal Floating Point format
+@cindex decimal floating point format
+
+@value{GDBN} can examine, set and perform computations with numbers in
+decimal floating point format, which in the C language correspond to the
+@code{_Decimal32}, @code{_Decimal64} and @code{_Decimal128} types as
+specified by the extension to support decimal floating-point arithmetic.
+
+There are two encodings in use, depending on the architecture: BID (Binary
+Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for
+PowerPC. @value{GDBN} will use the appropriate encoding for the configured
+target.
+
+Because of a limitation in @file{libdecnumber}, the library used by @value{GDBN}
+to manipulate decimal floating point numbers, it is not possible to convert
+(using a cast, for example) integers wider than 32-bit to decimal float.
+
+In addition, in order to imitate @value{GDBN}'s behaviour with binary floating
+point computations, error checking in decimal float operations ignores
+underflow, overflow and divide by zero exceptions.
+
+In the PowerPC architecture, @value{GDBN} provides a set of pseudo-registers
+to inspect @code{_Decimal128} values stored in floating point registers. See
+@ref{PowerPC,,PowerPC} for more details.
+
@node Objective-C
@subsection Objective-C
@item :
The range operator. Normally used in the form of array(low:high) to
represent a section of array.
+
+@item %
+The access component operator. Normally used to access elements in derived
+types. Also suitable for unions. As unions aren't part of regular Fortran,
+this can only happen when accessing a register that uses a gdbarch-defined
+union type.
@end table
@node Fortran Defaults
@item TRUNC(@var{r})
Returns the integral part of @var{r}.
+@item TSIZE(@var{x})
+Returns the size of its argument. @var{x} can be a variable or a type.
+
@item VAL(@var{t},@var{i})
Returns the member of the type @var{t} whose ordinal value is @var{i}.
@end table
Note that the array handling is not yet complete and although the type
is printed correctly, expression handling still assumes that all
arrays have a lower bound of zero and not @code{-10} as in the example
-above. Unbounded arrays are also not yet recognized in @value{GDBN}.
+above.
Here are some more type related Modula-2 examples:
@vindex colon-colon@r{, in Modula-2}
@c Info cannot handle :: but TeX can.
@end ifinfo
-@iftex
+@ifnotinfo
@vindex ::@r{, in Modula-2}
-@end iftex
+@end ifnotinfo
There are a few subtle differences between the Modula-2 scope operator
(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have
* Omissions from Ada:: Restrictions on the Ada expression syntax.
* Additions to Ada:: Extensions of the Ada expression syntax.
* Stopping Before Main Program:: Debugging the program during elaboration.
+* Ada Tasks:: Listing and setting breakpoints in tasks.
+* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files
* Ada Glitches:: Known peculiarities of Ada mode.
@end menu
That brevity is important to the @value{GDBN} user.
@end itemize
-Thus, for brevity, the debugger acts as if there were
-implicit @code{with} and @code{use} clauses in effect for all user-written
-packages, making it unnecessary to fully qualify most names with
-their packages, regardless of context. Where this causes ambiguity,
-@value{GDBN} asks the user's intent.
+Thus, for brevity, the debugger acts as if all names declared in
+user-written packages are directly visible, even if they are not visible
+according to Ada rules, thus making it unnecessary to fully qualify most
+names with their packages, regardless of context. Where this causes
+ambiguity, @value{GDBN} asks the user's intent.
The debugger will start in Ada mode if it detects an Ada main program.
As for other languages, it will enter Ada mode when stopped in a program that
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)
+(@value{GDBP}) set An_Array := (1, 2, 3, 4, 5, 6)
+(@value{GDBP}) set An_Array := (1, others => 0)
+(@value{GDBP}) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)
+(@value{GDBP}) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))
+(@value{GDBP}) set A_Record := (1, "Peter", True);
+(@value{GDBP}) set A_Record := (Name => "Peter", Id => 1, Alive => True)
@end smallexample
Changing a
assignments:
@smallexample
-set A_Rec.Len := 4
-set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))
+(@value{GDBP}) set A_Rec.Len := 4
+(@value{GDBP}) 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
@item
It is not possible to slice a packed array.
+
+@item
+The names @code{True} and @code{False}, when not part of a qualified name,
+are interpreted as if implicitly prefixed by @code{Standard}, regardless of
+context.
+Should your program
+redefine these names in a package or procedure (at best a dubious practice),
+you will have to use fully qualified names to access their new definitions.
@end itemize
@node Additions to Ada
its right-hand operand as its value. Thus, you may enter
@smallexample
-set x := y + 3
-print A(tmp := y + 1)
+(@value{GDBP}) set x := y + 3
+(@value{GDBP}) print A(tmp := y + 1)
@end smallexample
@item
complex conditional breaks:
@smallexample
-break f
-condition 1 (report(i); k += 1; A(k) > 100)
+(@value{GDBP}) break f
+(@value{GDBP}) condition 1 (report(i); k += 1; A(k) > 100)
@end smallexample
@item
to write
@smallexample
-print 'max(x, y)
+(@value{GDBP}) print 'max(x, y)
@end smallexample
@item
enclose them in angle brackets to avoid the lower-case mapping.
For example,
@smallexample
-@value{GDBP} print <JMPBUF_SAVE>[0]
+(@value{GDBP}) print <JMPBUF_SAVE>[0]
@end smallexample
@item
elaboration, simply use the following two commands:
@code{tbreak adainit} and @code{run}.
+@node Ada Tasks
+@subsubsection Extensions for Ada Tasks
+@cindex Ada, tasking
+
+Support for Ada tasks is analogous to that for threads (@pxref{Threads}).
+@value{GDBN} provides the following task-related commands:
+
+@table @code
+@kindex info tasks
+@item info tasks
+This command shows a list of current Ada tasks, as in the following example:
+
+
+@smallexample
+@iftex
+@leftskip=0.5cm
+@end iftex
+(@value{GDBP}) info tasks
+ ID TID P-ID Pri State Name
+ 1 8088000 0 15 Child Activation Wait main_task
+ 2 80a4000 1 15 Accept Statement b
+ 3 809a800 1 15 Child Activation Wait a
+* 4 80ae800 3 15 Running c
+
+@end smallexample
+
+@noindent
+In this listing, the asterisk before the last task indicates it to be the
+task currently being inspected.
+
+@table @asis
+@item ID
+Represents @value{GDBN}'s internal task number.
+
+@item TID
+The Ada task ID.
+
+@item P-ID
+The parent's task ID (@value{GDBN}'s internal task number).
+
+@item Pri
+The base priority of the task.
+
+@item State
+Current state of the task.
+
+@table @code
+@item Unactivated
+The task has been created but has not been activated. It cannot be
+executing.
+
+@item Running
+The task currently running.
+
+@item Runnable
+The task is not blocked for any reason known to Ada. (It may be waiting
+for a mutex, though.) It is conceptually "executing" in normal mode.
+
+@item Terminated
+The task is terminated, in the sense of ARM 9.3 (5). Any dependents
+that were waiting on terminate alternatives have been awakened and have
+terminated themselves.
+
+@item Child Activation Wait
+The task is waiting for created tasks to complete activation.
+
+@item Accept Statement
+The task is waiting on an accept or selective wait statement.
+
+@item Waiting on entry call
+The task is waiting on an entry call.
+
+@item Async Select Wait
+The task is waiting to start the abortable part of an asynchronous
+select statement.
+
+@item Delay Sleep
+The task is waiting on a select statement with only a delay
+alternative open.
+
+@item Child Termination Wait
+The task is sleeping having completed a master within itself, and is
+waiting for the tasks dependent on that master to become terminated or
+waiting on a terminate Phase.
+
+@item Wait Child in Term Alt
+The task is sleeping waiting for tasks on terminate alternatives to
+finish terminating.
+
+@item Accepting RV with @var{taskno}
+The task is accepting a rendez-vous with the task @var{taskno}.
+@end table
+
+@item Name
+Name of the task in the program.
+
+@end table
+
+@kindex info task @var{taskno}
+@item info task @var{taskno}
+This command shows detailled informations on the specified task, as in
+the following example:
+@smallexample
+@iftex
+@leftskip=0.5cm
+@end iftex
+(@value{GDBP}) info tasks
+ ID TID P-ID Pri State Name
+ 1 8077880 0 15 Child Activation Wait main_task
+* 2 807c468 1 15 Running task_1
+(@value{GDBP}) info task 2
+Ada Task: 0x807c468
+Name: task_1
+Thread: 0x807f378
+Parent: 1 (main_task)
+Base Priority: 15
+State: Runnable
+@end smallexample
+
+@item task
+@kindex task@r{ (Ada)}
+@cindex current Ada task ID
+This command prints the ID of the current task.
+
+@smallexample
+@iftex
+@leftskip=0.5cm
+@end iftex
+(@value{GDBP}) info tasks
+ ID TID P-ID Pri State Name
+ 1 8077870 0 15 Child Activation Wait main_task
+* 2 807c458 1 15 Running t
+(@value{GDBP}) task
+[Current task is 2]
+@end smallexample
+
+@item task @var{taskno}
+@cindex Ada task switching
+This command is like the @code{thread @var{threadno}}
+command (@pxref{Threads}). It switches the context of debugging
+from the current task to the given task.
+
+@smallexample
+@iftex
+@leftskip=0.5cm
+@end iftex
+(@value{GDBP}) info tasks
+ ID TID P-ID Pri State Name
+ 1 8077870 0 15 Child Activation Wait main_task
+* 2 807c458 1 15 Running t
+(@value{GDBP}) task 1
+[Switching to task 1]
+#0 0x8067726 in pthread_cond_wait ()
+(@value{GDBP}) bt
+#0 0x8067726 in pthread_cond_wait ()
+#1 0x8056714 in system.os_interface.pthread_cond_wait ()
+#2 0x805cb63 in system.task_primitives.operations.sleep ()
+#3 0x806153e in system.tasking.stages.activate_tasks ()
+#4 0x804aacc in un () at un.adb:5
+@end smallexample
+
+@end table
+
+@node Ada Tasks and Core Files
+@subsubsection Tasking Support when Debugging Core Files
+@cindex Ada tasking and core file debugging
+
+When inspecting a core file, as opposed to debugging a live program,
+tasking support may be limited or even unavailable, depending on
+the platform being used.
+For instance, on x86-linux, the list of tasks is available, but task
+switching is not supported. On Tru64, however, task switching will work
+as usual.
+
+On certain platforms, including Tru64, the debugger needs to perform some
+memory writes in order to provide Ada tasking support. When inspecting
+a core file, this means that the core file must be opened with read-write
+privileges, using the command @samp{"set write on"} (@pxref{Patching}).
+Under these circumstances, you should make a backup copy of the core
+file before inspecting it with @value{GDBN}.
+
@node Ada Glitches
@subsubsection Known Peculiarities of Ada Mode
@cindex Ada, problems
floating-point arithmetic, and may give results that only approximate those on
the host machine.
-@item
-The type of the @t{'Address} attribute may not be @code{System.Address}.
-
@item
The GNAT compiler never generates the prefix @code{Standard} for any of
the standard symbols defined by the Ada language. @value{GDBN} knows about
This is the opposite of the @code{info address} command. You can use
it to find out the name of a variable or a function given its address.
+For dynamically linked executables, the name of executable or shared
+library containing the symbol is also printed:
+
+@smallexample
+(@value{GDBP}) info symbol 0x400225
+_start + 5 in section .text of /tmp/a.out
+(@value{GDBP}) info symbol 0x2aaaac2811cf
+__read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
+@end smallexample
+
@kindex whatis
@item whatis [@var{arg}]
Print the data type of @var{arg}, which can be either an expression or
List all the variables local to a particular scope. This command
accepts a @var{location} argument---a function name, a source line, or
an address preceded by a @samp{*}, and prints all the variables local
-to the scope defined by that location. For example:
+to the scope defined by that location. (@xref{Specify Location}, for
+details about supported forms of @var{location}.) For example:
@smallexample
(@value{GDBP}) @b{info scope command_line_handler}
@item show opaque-type-resolution
Show whether opaque types are resolved or not.
+@kindex set print symbol-loading
+@cindex print messages when symbols are loaded
+@item set print symbol-loading
+@itemx set print symbol-loading on
+@itemx set print symbol-loading off
+The @code{set print symbol-loading} command allows you to enable or
+disable printing of messages when @value{GDBN} loads symbols.
+By default, these messages will be printed, and normally this is what
+you want. Disabling these messages is useful when debugging applications
+with lots of shared libraries where the quantity of output can be more
+annoying than useful.
+
+@kindex show print symbol-loading
+@item show print symbol-loading
+Show whether messages will be printed when @value{GDBN} loads symbols.
+
@kindex maint print symbols
@cindex symbol dump
@kindex maint print psymbols
dirname (null)
fullname (null)
blockvector ((struct blockvector *) 0x86c1bd0) (primary)
+ linetable ((struct linetable *) 0x8370fa0)
debugformat DWARF 2
@}
@}
@table @code
@kindex jump
@item jump @var{linespec}
-Resume execution at line @var{linespec}. Execution stops again
-immediately if there is a breakpoint there. @xref{List, ,Printing
-Source Lines}, for a description of the different forms of
-@var{linespec}. It is common practice to use the @code{tbreak} command
-in conjunction with @code{jump}. @xref{Set Breaks, ,Setting
-Breakpoints}.
+@itemx jump @var{location}
+Resume execution at line @var{linespec} or at address given by
+@var{location}. Execution stops again immediately if there is a
+breakpoint there. @xref{Specify Location}, for a description of the
+different forms of @var{linespec} and @var{location}. It is common
+practice to use the @code{tbreak} command in conjunction with
+@code{jump}. @xref{Set Breaks, ,Setting Breakpoints}.
The @code{jump} command does not change the current stack frame, or
the stack pointer, or the contents of any memory location or any
confirmation if the specified line is not in the function currently
executing. However, even bizarre results are predictable if you are
well acquainted with the machine-language code of your program.
-
-@item jump *@var{address}
-Resume execution at the instruction at address @var{address}.
@end table
@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt.
@item set write on
@itemx set write off
If you specify @samp{set write on}, @value{GDBN} opens executable and
-core files for both reading and writing; if you specify @samp{set write
+core files for both reading and writing; if you specify @kbd{set write
off} (the default), @value{GDBN} opens them read-only.
If you have already loaded a file, you must load it again (using the
name and remembers it that way.
@cindex shared libraries
-@value{GDBN} supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix,
+@anchor{Shared Libraries}
+@value{GDBN} supports @sc{gnu}/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix,
and IBM RS/6000 AIX shared libraries.
+On MS-Windows @value{GDBN} must be linked with the Expat library to support
+shared libraries. @xref{Expat}.
+
@value{GDBN} automatically loads symbol definitions from shared libraries
when you use the @code{run} command, or when you examine a core file.
(Before you issue the @code{run} command, @value{GDBN} does not understand
@end table
Shared libraries are also supported in many cross or remote debugging
-configurations. A copy of the target's libraries need to be present on the
-host system; they need to be the same as the target libraries, although the
+configurations. @value{GDBN} needs to have access to the target's libraries;
+this can be accomplished either by providing copies of the libraries
+on the host system, or by asking @value{GDBN} to automatically retrieve the
+libraries from the target. If copies of the target libraries are
+provided, they need to be the same as the target libraries, although the
copies on the target can be stripped as long as the copies on the host are
not.
the target, with e.g.@: a @file{/lib} and @file{/usr/lib} hierarchy
under @var{path}.
+If @var{path} starts with the sequence @file{remote:}, @value{GDBN} will
+retrieve the target libraries from the remote system. This is only
+supported when using a remote target that supports the @code{remote get}
+command (@pxref{File Transfer,,Sending files to a remote system}).
+The part of @var{path} following the initial @file{remote:}
+(if present) is used as system root prefix on the remote file system.
+@footnote{If you want to specify a local system root using a directory
+that happens to be named @file{remote:}, you need to use some equivalent
+variant of the name like @file{./remote:}.}
+
The @code{set solib-absolute-prefix} command is an alias for @code{set
sysroot}.
came from the same build.
@item
-The executable contains a @dfn{build ID}, a unique signature that is
+The executable contains a @dfn{build ID}, a unique bit string that is
also present in the corresponding debug info file. (This is supported
-only on some operating systems, notably on @sc{gnu}/Linux. For more
-details about this feature, see
-@uref{http://fedoraproject.org/wiki/Releases/FeatureBuildId, the
-Fedora Project's description of the buid ID feature}.) The debug info
-file's name is not specified explicitly by the debug ID, but can be
-computed from the build ID, see below.
+only on some operating systems, notably those which use the ELF format
+for binary files and the @sc{gnu} Binutils.) For more details about
+this feature, see the description of the @option{--build-id}
+command-line option in @ref{Options, , Command Line Options, ld.info,
+The GNU Linker}. The debug info file's name is not specified
+explicitly by the build ID, but can be computed from the build ID, see
+below.
@end itemize
Depending on the way the debug info file is specified, @value{GDBN}
directories of the executable's absolute file name.
@item
-For the ``debug ID'' method, @value{GDBN} looks in the
+For the ``build ID'' method, @value{GDBN} looks in the
@file{.build-id} subdirectory of the global debug directory for a file
named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the
-first 2 hex characters of the debug ID signature, and @var{nnnnnnnn}
-are the rest of the signature. (Real signatures are 32 or more
-characters, not 10.)
+first 2 hex characters of the build ID bit string, and @var{nnnnnnnn}
+are the rest of the bit string. (Real build ID strings are 32 or more
+hex characters, not 10.)
@end itemize
So, for example, suppose you ask @value{GDBN} to debug
-@file{/usr/bin/ls}, which has a @dfn{debug link} that specifies the
-file @file{ls.debug}, and a @dfn{build id} whose value in hex is
+@file{/usr/bin/ls}, which has a debug link that specifies the
+file @file{ls.debug}, and a build ID whose value in hex is
@code{abcdef1234}. If the global debug directory is
@file{/usr/lib/debug}, then @value{GDBN} will look for the following
debug information files, in the indicated order:
@cindex @code{.note.gnu.build-id} sections
@cindex build ID sections
-A build ID is a special section of the executable file named
-@code{.note.gnu.build-id}. This section contains unique
-identification for the built files---it remains the same across
-multiple builds of the same build tree. The default algorithm SHA1
-produces 160 bits (40 hexadecimal characters) of the content. The
-same section with an identical value is present in the original built
-binary with symbols, in its stripped variant, and in the separate
-debugging information file.
+The build ID is a special section in the executable file (and in other
+ELF binary files that @value{GDBN} may consider). This section is
+often named @code{.note.gnu.build-id}, but that name is not mandatory.
+It contains unique identification for the built files---the ID remains
+the same across multiple builds of the same build tree. The default
+algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the
+content for the build ID string. The same section with an identical
+value is present in the original built binary with symbols, in its
+stripped variant, and in the separate debugging information file.
The debugging information file itself should be an ordinary
executable, containing a full set of linker symbols, sections, and
but they need not contain any data---much like a @code{.bss} section
in an ordinary executable.
-@sc{gnu} binary utilities (Binutils) package includes the
+The @sc{gnu} binary utilities (Binutils) package includes the
@samp{objcopy} utility that can produce
the separated executable / debugging information file pairs using the
following commands:
@smallexample
@kbd{objcopy --only-keep-debug foo foo.debug}
@kbd{strip -g foo}
-@kbd{objcopy --add-gnu-debuglink="foo.debug" "foo"}
@end smallexample
@noindent
These commands remove the debugging
-information from the executable file @file{foo}, place it in the file
-@file{foo.debug}, and leave behind a debug link in @file{foo}. Ulrich
-Drepper's @file{elfutils} package, starting with version 0.53, contains
+information from the executable file @file{foo} and place it in the file
+@file{foo.debug}. You can use the first, second or both methods to link the
+two files:
+
+@itemize @bullet
+@item
+The debug link method needs the following additional command to also leave
+behind a debug link in @file{foo}:
+
+@smallexample
+@kbd{objcopy --add-gnu-debuglink=foo.debug foo}
+@end smallexample
+
+Ulrich Drepper's @file{elfutils} package, starting with version 0.53, contains
a version of the @code{strip} command such that the command @kbd{strip foo -f
-foo.debug} has the same functionality as the three commands above.
+foo.debug} has the same functionality as the two @code{objcopy} commands and
+the @code{ln -s} command above, together.
+
+@item
+Build ID gets embedded into the main executable using @code{ld --build-id} or
+the @value{NGCC} counterpart @code{gcc -Wl,--build-id}. Build ID support plus
+compatibility fixes for debug files separation are present in @sc{gnu} binary
+utilities (Binutils) package since version 2.18.
+@end itemize
+
+@noindent
Since there are many different ways to compute CRC's for the debug
link (different polynomials, reversals, byte ordering, etc.), the
@kindex load @var{filename}
@item load @var{filename}
+@anchor{load}
Depending on what remote debugging facilities are configured into
@value{GDBN}, the @code{load} command may be available. Where it exists, it
is meant to make @var{filename} (an executable) available for debugging
@menu
* Connecting:: Connecting to a remote target
+* File Transfer:: Sending files to a remote system
* Server:: Using the gdbserver program
* Remote Configuration:: Remote configuration
* Remote Stub:: Implementing a remote stub
@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.
+commands to examine and change data. The remote program is already
+running; you can use @kbd{step} and @kbd{continue}, and you do not
+need to use @kbd{run}.
@cindex interrupting remote programs
@cindex remote programs, interrupting
and implement.
@end table
+@node File Transfer
+@section Sending files to a remote system
+@cindex remote target, file transfer
+@cindex file transfer
+@cindex sending files to remote systems
+
+Some remote targets offer the ability to transfer files over the same
+connection used to communicate with @value{GDBN}. This is convenient
+for targets accessible through other means, e.g.@: @sc{gnu}/Linux systems
+running @code{gdbserver} over a network interface. For other targets,
+e.g.@: embedded devices with only a single serial port, this may be
+the only way to upload or download files.
+
+Not all remote targets support these commands.
+
+@table @code
+@kindex remote put
+@item remote put @var{hostfile} @var{targetfile}
+Copy file @var{hostfile} from the host system (the machine running
+@value{GDBN}) to @var{targetfile} on the target system.
+
+@kindex remote get
+@item remote get @var{targetfile} @var{hostfile}
+Copy file @var{targetfile} from the target system to @var{hostfile}
+on the host system.
+
+@kindex remote delete
+@item remote delete @var{targetfile}
+Delete @var{targetfile} from the target system.
+
+@end table
+
@node Server
@section Using the @code{gdbserver} Program
or a TCP connection, 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.
+@quotation
+@emph{Warning:} @code{gdbserver} does not have any built-in security.
+Do not run @code{gdbserver} connected to any public network; a
+@value{GDBN} connection to @code{gdbserver} provides access to the
+target system with the same privileges as the user running
+@code{gdbserver}.
+@end quotation
+
+@subsection Running @code{gdbserver}
+@cindex arguments, to @code{gdbserver}
+
+Run @code{gdbserver} on the target system. You need a copy of the
+program you want to debug, including any libraries it requires.
@code{gdbserver} 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.
and exits.} You must use the same port number with the host @value{GDBN}
@code{target remote} command.
+@subsubsection Attaching to a Running Program
+
On some targets, @code{gdbserver} can also attach to running programs.
This is accomplished via the @code{--attach} argument. The syntax is:
@smallexample
-target> gdbserver @var{comm} --attach @var{pid}
+target> gdbserver --attach @var{comm} @var{pid}
@end smallexample
@var{pid} is the process ID of a currently running process. It isn't necessary
@code{pidof} utility:
@smallexample
-target> gdbserver @var{comm} --attach `pidof @var{program}`
+target> gdbserver --attach @var{comm} `pidof @var{program}`
@end smallexample
In case more than one copy of @var{program} is running, or @var{program}
has multiple threads, most versions of @code{pidof} support the
@code{-s} option to only return the first process ID.
-@item On the host machine,
-first make sure you have the necessary symbol files. Load symbols for
+@subsubsection Multi-Process Mode for @code{gdbserver}
+@cindex gdbserver, multiple processes
+@cindex multiple processes with gdbserver
+
+When you connect to @code{gdbserver} using @code{target remote},
+@code{gdbserver} debugs the specified program only once. When the
+program exits, or you detach from it, @value{GDBN} closes the connection
+and @code{gdbserver} exits.
+
+If you connect using @kbd{target extended-remote}, @code{gdbserver}
+enters multi-process mode. When the debugged program exits, or you
+detach from it, @value{GDBN} stays connected to @code{gdbserver} even
+though no program is running. The @code{run} and @code{attach}
+commands instruct @code{gdbserver} to run or attach to a new program.
+The @code{run} command uses @code{set remote exec-file} (@pxref{set
+remote exec-file}) to select the program to run. Command line
+arguments are supported, except for wildcard expansion and I/O
+redirection (@pxref{Arguments}).
+
+To start @code{gdbserver} without supplying an initial command to run
+or process ID to attach, use the @option{--multi} command line option.
+Then you can connect using @kbd{target extended-remote} and start
+the program you want to debug.
+
+@code{gdbserver} does not automatically exit in multi-process mode.
+You can terminate it by using @code{monitor exit}
+(@pxref{Monitor Commands for gdbserver}).
+
+@subsubsection Other Command-Line Arguments for @code{gdbserver}
+
+The @option{--debug} option tells @code{gdbserver} to display extra
+status information about the debugging process. The
+@option{--remote-debug} option tells @code{gdbserver} to display
+remote protocol debug output. These options are intended for
+@code{gdbserver} development and for bug reports to the developers.
+
+The @option{--wrapper} option specifies a wrapper to launch programs
+for debugging. The option should be followed by the name of the
+wrapper, then any command-line arguments to pass to the wrapper, then
+@kbd{--} indicating the end of the wrapper arguments.
+
+@code{gdbserver} runs the specified wrapper program with a combined
+command line including the wrapper arguments, then the name of the
+program to debug, then any arguments to the program. The wrapper
+runs until it executes your program, and then @value{GDBN} gains control.
+
+You can use any program that eventually calls @code{execve} with
+its arguments as a wrapper. Several standard Unix utilities do
+this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending
+with @code{exec "$@@"} will also work.
+
+For example, you can use @code{env} to pass an environment variable to
+the debugged program, without setting the variable in @code{gdbserver}'s
+environment:
+
+@smallexample
+$ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
+@end smallexample
+
+@subsection Connecting to @code{gdbserver}
+
+Run @value{GDBN} on the host system.
+
+First make sure you have the necessary symbol files. Load symbols for
your application using the @code{file} command before you connect. Use
@code{set sysroot} to locate target libraries (unless your @value{GDBN}
-was compiled with the correct sysroot using @code{--with-system-root}).
+was compiled with the correct sysroot using @code{--with-sysroot}).
The symbol file and target libraries must exactly match the executable
and libraries on the target, with one exception: the files on the host
For TCP connections, you must start up @code{gdbserver} prior to using
the @code{target remote} command. Otherwise you may get an error whose
text depends on the host system, but which usually looks something like
-@samp{Connection refused}. You don't need to use the @code{load}
+@samp{Connection refused}. Don't use the @code{load}
command in @value{GDBN} when using @code{gdbserver}, since the program is
already on the target.
-@end table
-
@subsection Monitor Commands for @code{gdbserver}
@cindex monitor commands, for @code{gdbserver}
+@anchor{Monitor Commands for gdbserver}
During a @value{GDBN} session using @code{gdbserver}, you can use the
@code{monitor} command to send special requests to @code{gdbserver}.
-Here are the available commands; they are only of interest when
-debugging @value{GDBN} or @code{gdbserver}.
+Here are the available commands.
@table @code
@item monitor help
Disable or enable specific debugging messages associated with the remote
protocol (@pxref{Remote Protocol}).
+@item monitor exit
+Tell gdbserver to exit immediately. This command should be followed by
+@code{disconnect} to close the debugging session. @code{gdbserver} will
+detach from any attached processes and kill any processes it created.
+Use @code{monitor exit} to terminate @code{gdbserver} at the end
+of a multi-process mode debug session.
+
@end table
@node Remote Configuration
@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 exec-file @var{filename}
+@itemx show remote exec-file
+@anchor{set remote exec-file}
+@cindex executable file, for remote target
+Select the file used for @code{run} with @code{target
+extended-remote}. This should be set to a filename valid on the
+target system. If it is not set, the target will use a default
+filename (e.g.@: the last program run).
+
+@kindex set tcp
+@kindex show tcp
+@item set tcp auto-retry on
+@cindex auto-retry, for remote TCP target
+Enable auto-retry for remote TCP connections. This is useful if the remote
+debugging agent is launched in parallel with @value{GDBN}; there is a race
+condition because the agent may not become ready to accept the connection
+before @value{GDBN} attempts to connect. When auto-retry is
+enabled, if the initial attempt to connect fails, @value{GDBN} reattempts
+to establish the connection using the timeout specified by
+@code{set tcp connect-timeout}.
+
+@item set tcp auto-retry off
+Do not auto-retry failed TCP connections.
+
+@item show tcp auto-retry
+Show the current auto-retry setting.
+
+@item set tcp connect-timeout @var{seconds}
+@cindex connection timeout, for remote TCP target
+@cindex timeout, for remote target connection
+Set the timeout for establishing a TCP connection to the remote target to
+@var{seconds}. The timeout affects both polling to retry failed connections
+(enabled by @code{set tcp auto-retry on}) and waiting for connections
+that are merely slow to complete, and represents an approximate cumulative
+value.
+
+@item show tcp connect-timeout
+Show the current connection timeout setting.
@end table
@cindex remote packets, enabling and disabling
@tab @code{qSymbol}
@tab Detecting multiple threads
+@item @code{attach}
+@tab @code{vAttach}
+@tab @code{attach}
+
@item @code{verbose-resume}
@tab @code{vCont}
@tab Stepping or resuming multiple threads
+@item @code{run}
+@tab @code{vRun}
+@tab @code{run}
+
@item @code{software-breakpoint}
@tab @code{Z0}
@tab @code{break}
@tab @code{qGetTLSAddr}
@tab Displaying @code{__thread} variables
+@item @code{search-memory}
+@tab @code{qSearch:memory}
+@tab @code{find}
+
@item @code{supported-packets}
@tab @code{qSupported}
@tab Remote communications parameters
@tab @code{QPassSignals}
@tab @code{handle @var{signal}}
+@item @code{hostio-close-packet}
+@tab @code{vFile:close}
+@tab @code{remote get}, @code{remote put}
+
+@item @code{hostio-open-packet}
+@tab @code{vFile:open}
+@tab @code{remote get}, @code{remote put}
+
+@item @code{hostio-pread-packet}
+@tab @code{vFile:pread}
+@tab @code{remote get}, @code{remote put}
+
+@item @code{hostio-pwrite-packet}
+@tab @code{vFile:pwrite}
+@tab @code{remote get}, @code{remote put}
+
+@item @code{hostio-unlink-packet}
+@tab @code{vFile:unlink}
+@tab @code{remote delete}
+
+@item @code{noack-packet}
+@tab @code{QStartNoAckMode}
+@tab Packet acknowledgment
+
+@item @code{osdata}
+@tab @code{qXfer:osdata:read}
+@tab @code{info os}
@end multitable
@node Remote Stub
* Cygwin Native:: Features specific to the Cygwin port
* Hurd Native:: Features specific to @sc{gnu} Hurd
* Neutrino:: Features specific to QNX Neutrino
+* Darwin:: Features specific to Darwin
@end menu
@node HP-UX
Show the current state of QNX Neutrino messages.
@end table
+@node Darwin
+@subsection Darwin
+@cindex Darwin
+
+@value{GDBN} provides the following commands specific to the Darwin target:
+
+@table @code
+@item set debug darwin @var{num}
+@kindex set debug darwin
+When set to a non zero value, enables debugging messages specific to
+the Darwin support. Higher values produce more verbose output.
+
+@item show debug darwin
+@kindex show debug darwin
+Show the current state of Darwin messages.
+
+@item set debug mach-o @var{num}
+@kindex set debug mach-o
+When set to a non zero value, enables debugging messages while
+@value{GDBN} is reading Darwin object files. (@dfn{Mach-O} is the
+file format used on Darwin for object and executable files.) Higher
+values produce more verbose output. This is a command to diagnose
+problems internal to @value{GDBN} and should not be needed in normal
+usage.
+
+@item show debug mach-o
+@kindex show debug mach-o
+Show the current state of Mach-O file messages.
+
+@item set mach-exceptions on
+@itemx set mach-exceptions off
+@kindex set mach-exceptions
+On Darwin, faults are first reported as a Mach exception and are then
+mapped to a Posix signal. Use this command to turn on trapping of
+Mach exceptions in the inferior. This might be sometimes useful to
+better understand the cause of a fault. The default is off.
+
+@item show mach-exceptions
+@kindex show mach-exceptions
+Show the current state of exceptions trapping.
+@end table
+
@node Embedded OS
@section Embedded Operating Systems
* MIPS Embedded:: MIPS Embedded
* OpenRISC 1000:: OpenRisc 1000
* PA:: HP PA Embedded
-* PowerPC:: PowerPC
+* PowerPC Embedded:: PowerPC Embedded
* Sparclet:: Tsqware Sparclet
* Sparclite:: Fujitsu Sparclite
* Z8000:: Zilog Z8000
@item show arm abi
Show the currently used ABI.
+@item set arm fallback-mode (arm|thumb|auto)
+@value{GDBN} uses the symbol table, when available, to determine
+whether instructions are ARM or Thumb. This command controls
+@value{GDBN}'s default behavior when the symbol table is not
+available. The default is @samp{auto}, which causes @value{GDBN} to
+use the current execution mode (from the @code{T} bit in the @code{CPSR}
+register).
+
+@item show arm fallback-mode
+Show the current fallback instruction mode.
+
+@item set arm force-mode (arm|thumb|auto)
+This command overrides use of the symbol table to determine whether
+instructions are ARM or Thumb. The default is @samp{auto}, which
+causes @value{GDBN} to use the symbol table and then the setting
+of @samp{set arm fallback-mode}.
+
+@item show arm force-mode
+Show the current forced instruction mode.
+
@item set debug arm
Toggle whether to display ARM-specific debugging messages from the ARM
target support subsystem.
You can control the timeout used while waiting for a packet, in the MIPS
remote protocol, with the @code{set timeout @var{seconds}} command. The
default is 5 seconds. Similarly, you can control the timeout used while
-waiting for an acknowledgement of a packet with the @code{set
+waiting for an acknowledgment of a packet with the @code{set
retransmit-timeout @var{seconds}} command. The default is 3 seconds.
You can inspect both values with @code{show timeout} and @code{show
retransmit-timeout}. (These commands are @emph{only} available when
@end table
-@node PowerPC
-@subsection PowerPC
+@node PowerPC Embedded
+@subsection PowerPC Embedded
+
+@value{GDBN} provides the following PowerPC-specific commands:
@table @code
+@kindex set powerpc
+@item set powerpc soft-float
+@itemx show powerpc soft-float
+Force @value{GDBN} to use (or not use) a software floating point calling
+convention. By default, @value{GDBN} selects the calling convention based
+on the selected architecture and the provided executable file.
+
+@item set powerpc vector-abi
+@itemx show powerpc vector-abi
+Force @value{GDBN} to use the specified calling convention for vector
+arguments and return values. The valid options are @samp{auto};
+@samp{generic}, to avoid vector registers even if they are present;
+@samp{altivec}, to use AltiVec registers; and @samp{spe} to use SPE
+registers. By default, @value{GDBN} selects the calling convention
+based on the selected architecture and the provided executable file.
+
@kindex target dink32
@item target dink32 @var{dev}
DINK32 ROM monitor.
@cindex SDS protocol
The following commands specific to the SDS protocol are supported
-by@value{GDBN}:
+by @value{GDBN}:
@table @code
@item set sdstimeout @var{nsec}
@item regs
@kindex regs@r{, Super-H}
Show the values of all Super-H registers.
+
+@item set sh calling-convention @var{convention}
+@kindex set sh calling-convention
+Set the calling-convention used when calling functions from @value{GDBN}.
+Allowed values are @samp{gcc}, which is the default setting, and @samp{renesas}.
+With the @samp{gcc} setting, functions are called using the @value{NGCC} calling
+convention. If the DWARF-2 information of the called function specifies
+that the function follows the Renesas calling convention, the function
+is called using the Renesas calling convention. If the calling convention
+is set to @samp{renesas}, the Renesas calling convention is always used,
+regardless of the DWARF-2 information. This can be used to override the
+default of @samp{gcc} if debug information is missing, or the compiler
+does not emit the DWARF-2 calling convention entry for a function.
+
+@item show sh calling-convention
+@kindex show sh calling-convention
+Show the current calling convention setting.
+
@end table
* MIPS::
* HPPA:: HP PA architecture
* SPU:: Cell Broadband Engine SPU architecture
+* PowerPC::
@end menu
@node i386
@end table
+@node PowerPC
+@subsection PowerPC
+@cindex PowerPC architecture
+
+When @value{GDBN} is debugging the PowerPC architecture, it provides a set of
+pseudo-registers to enable inspection of 128-bit wide Decimal Floating Point
+numbers stored in the floating point registers. These values must be stored
+in two consecutive registers, always starting at an even register like
+@code{f0} or @code{f2}.
+
+The pseudo-registers go from @code{$dl0} through @code{$dl15}, and are formed
+by joining the even/odd register pairs @code{f0} and @code{f1} for @code{$dl0},
+@code{f2} and @code{f3} for @code{$dl1} and so on.
+
+For POWER7 processors, @value{GDBN} provides a set of pseudo-registers, the 64-bit
+wide Extended Floating Point Registers (@samp{f32} through @samp{f63}).
+
@node Controlling GDB
@chapter Controlling @value{GDBN}
module.
@item show debug aix-thread
Show the current state of AIX thread debugging info display.
+@item set debug dwarf2-die
+@cindex DWARF2 DIEs
+Dump DWARF2 DIEs after they are read in.
+The value is the number of nesting levels to print.
+A value of zero turns off the display.
+@item show debug dwarf2-die
+Show the current state of DWARF2 DIE debugging.
+@item set debug displaced
+@cindex displaced stepping debugging info
+Turns on or off display of @value{GDBN} debugging info for the
+displaced stepping support. The default is off.
+@item show debug displaced
+Displays the current state of displaying @value{GDBN} debugging info
+related to displaced stepping.
@item set debug event
@cindex event debugging info
Turns on or off display of @value{GDBN} event debugging info. The
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 lin-lwp-async
+@cindex @sc{gnu}/Linux LWP async debug messages
+@cindex Linux lightweight processes
+Turns on or off debugging messages from the Linux LWP async debug support.
+@item show debug lin-lwp-async
+Show the current state of Linux LWP async debugging messages.
@item set debug observer
@cindex observer debugging info
Turns on or off display of @value{GDBN} observer debugging. This
@item show debug target
Displays the current state of displaying @value{GDBN} target debugging
info.
+@item set debug timestamp
+@cindex timestampping debugging info
+Turns on or off display of timestamps with @value{GDBN} debugging info.
+When enabled, seconds and microseconds are displayed before each debugging
+message.
+@item show debug timestamp
+Displays the current state of displaying timestamps with @value{GDBN}
+debugging info.
@item set debugvarobj
@cindex variable object debugging info
Turns on or off display of @value{GDBN} variable object debugging
Displays the current state of XML debugging messages.
@end table
+@node Extending GDB
+@chapter Extending @value{GDBN}
+@cindex extending GDB
+
+@value{GDBN} provides two mechanisms for extension. The first is based
+on composition of @value{GDBN} commands, and the second is based on the
+Python scripting language.
+
+@menu
+* Sequences:: Canned Sequences of Commands
+* Python:: Scripting @value{GDBN} using Python
+@end menu
+
@node Sequences
-@chapter Canned Sequences of Commands
+@section Canned Sequences of Commands
Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
Command Lists}), @value{GDBN} provides two ways to store sequences of
@end menu
@node Define
-@section User-defined Commands
+@subsection User-defined Commands
@cindex user-defined command
@cindex arguments, to user-defined commands
@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.
+@var{commandname} may be a bare command name consisting of letters,
+numbers, dashes, and underscores. It may also start with any predefined
+prefix command. For example, @samp{define target my-target} creates
+a user-defined @samp{target my-target} command.
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
messages when used in a user-defined command.
@node Hooks
-@section User-defined Command Hooks
+@subsection User-defined Command Hooks
@cindex command hooks
@cindex hooks, for commands
@cindex hooks, pre-command
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?
+You can hook a multi-word command by adding @code{hook-} or
+@code{hookpost-} to the last word of the command, e.g.@:
+@samp{define target hook-remote} to add a hook to @samp{target remote}.
+
If an error occurs during the execution of your hook, execution of
@value{GDBN} commands stops and @value{GDBN} issues a prompt
(before the command that you actually typed had a chance to run).
get a warning from the @code{define} command.
@node Command Files
-@section Command Files
+@subsection Command Files
@cindex command files
@cindex scripting commands
@node Output
-@section Commands for Controlled Output
+@subsection Commands for Controlled Output
During the execution of a command file or a user-defined command, normal
@value{GDBN} output is suppressed; the only output that appears is what is
Formats}, for more information.
@kindex printf
-@item printf @var{string}, @var{expressions}@dots{}
-Print the values of the @var{expressions} under the control of
-@var{string}. The @var{expressions} are separated by commas and may be
-either numbers or pointers. Their values are printed as specified by
-@var{string}, exactly as if your program were to execute the C
-subroutine
-@c FIXME: the above implies that at least all ANSI C formats are
-@c supported, but it isn't true: %E and %G don't work (or so it seems).
-@c Either this is a bug, or the manual should document what formats are
-@c supported.
+@item printf @var{template}, @var{expressions}@dots{}
+Print the values of one or more @var{expressions} under the control of
+the string @var{template}. To print several values, make
+@var{expressions} be a comma-separated list of individual expressions,
+which may be either numbers or pointers. Their values are printed as
+specified by @var{template}, exactly as a C program would do by
+executing the code below:
@smallexample
-printf (@var{string}, @var{expressions}@dots{});
+printf (@var{template}, @var{expressions}@dots{});
@end smallexample
+As in @code{C} @code{printf}, ordinary characters in @var{template}
+are printed verbatim, while @dfn{conversion specification} introduced
+by the @samp{%} character cause subsequent @var{expressions} to be
+evaluated, their values converted and formatted according to type and
+style information encoded in the conversion specifications, and then
+printed.
+
For example, you can print two values in hex like this:
@smallexample
printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
@end smallexample
-The only backslash-escape sequences that you can use in the format
-string are the simple ones that consist of backslash followed by a
-letter.
+@code{printf} supports all the standard @code{C} conversion
+specifications, including the flags and modifiers between the @samp{%}
+character and the conversion letter, with the following exceptions:
+
+@itemize @bullet
+@item
+The argument-ordering modifiers, such as @samp{2$}, are not supported.
+
+@item
+The modifier @samp{*} is not supported for specifying precision or
+width.
+
+@item
+The @samp{'} flag (for separation of digits into groups according to
+@code{LC_NUMERIC'}) is not supported.
+
+@item
+The type modifiers @samp{hh}, @samp{j}, @samp{t}, and @samp{z} are not
+supported.
+
+@item
+The conversion letter @samp{n} (as in @samp{%n}) is not supported.
+
+@item
+The conversion letters @samp{a} and @samp{A} are not supported.
+@end itemize
+
+@noindent
+Note that the @samp{ll} type modifier is supported only if the
+underlying @code{C} implementation used to build @value{GDBN} supports
+the @code{long long int} type, and the @samp{L} type modifier is
+supported only if @code{long double} type is available.
+
+As in @code{C}, @code{printf} supports simple backslash-escape
+sequences, such as @code{\n}, @samp{\t}, @samp{\\}, @samp{\"},
+@samp{\a}, and @samp{\f}, that consist of backslash followed by a
+single character. Octal and hexadecimal escape sequences are not
+supported.
+
+Additionally, @code{printf} supports conversion specifications for DFP
+(@dfn{Decimal Floating Point}) types using the following length modifiers
+together with a floating point specifier.
+letters:
+
+@itemize @bullet
+@item
+@samp{H} for printing @code{Decimal32} types.
+
+@item
+@samp{D} for printing @code{Decimal64} types.
+
+@item
+@samp{DD} for printing @code{Decimal128} types.
+@end itemize
+
+If the underlying @code{C} implementation used to build @value{GDBN} has
+support for the three length modifiers for DFP types, other modifiers
+such as width and precision will also be available for @value{GDBN} to use.
+
+In case there is no such @code{C} support, no additional modifiers will be
+available and the value will be printed in the standard way.
+
+Here's an example of printing DFP types using the above conversion letters:
+@smallexample
+printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl
+@end smallexample
+
+@end table
+
+@node Python
+@section Scripting @value{GDBN} using Python
+@cindex python scripting
+@cindex scripting with python
+
+You can script @value{GDBN} using the @uref{http://www.python.org/,
+Python programming language}. This feature is available only if
+@value{GDBN} was configured using @option{--with-python}.
+
+@menu
+* Python Commands:: Accessing Python from @value{GDBN}.
+* Python API:: Accessing @value{GDBN} from Python.
+@end menu
+
+@node Python Commands
+@subsection Python Commands
+@cindex python commands
+@cindex commands to access python
+
+@value{GDBN} provides one command for accessing the Python interpreter,
+and one related setting:
+
+@table @code
+@kindex python
+@item python @r{[}@var{code}@r{]}
+The @code{python} command can be used to evaluate Python code.
+
+If given an argument, the @code{python} command will evaluate the
+argument as a Python command. For example:
+
+@smallexample
+(@value{GDBP}) python print 23
+23
+@end smallexample
+
+If you do not provide an argument to @code{python}, it will act as a
+multi-line command, like @code{define}. In this case, the Python
+script is made up of subsequent command lines, given after the
+@code{python} command. This command list is terminated using a line
+containing @code{end}. For example:
+
+@smallexample
+(@value{GDBP}) python
+Type python script
+End with a line saying just "end".
+>print 23
+>end
+23
+@end smallexample
+
+@kindex maint set python print-stack
+@item maint set python print-stack
+By default, @value{GDBN} will print a stack trace when an error occurs
+in a Python script. This can be controlled using @code{maint set
+python print-stack}: if @code{on}, the default, then Python stack
+printing is enabled; if @code{off}, then Python stack printing is
+disabled.
@end table
+@node Python API
+@subsection Python API
+@cindex python api
+@cindex programming in python
+
+@cindex python stdout
+@cindex python pagination
+At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
+@code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
+A Python program which outputs to one of these streams may have its
+output interrupted by the user (@pxref{Screen Size}). In this
+situation, a Python @code{KeyboardInterrupt} exception is thrown.
+
+@menu
+* Basic Python:: Basic Python Functions.
+* Exception Handling::
+* Values From Inferior::
+@end menu
+
+@node Basic Python
+@subsubsection Basic Python
+
+@cindex python functions
+@cindex python module
+@cindex gdb module
+@value{GDBN} introduces a new Python module, named @code{gdb}. All
+methods and classes added by @value{GDBN} are placed in this module.
+@value{GDBN} automatically @code{import}s the @code{gdb} module for
+use in all scripts evaluated by the @code{python} command.
+
+@findex gdb.execute
+@defun execute command [from_tty]
+Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
+If a GDB exception happens while @var{command} runs, it is
+translated as described in @ref{Exception Handling,,Exception Handling}.
+If no exceptions occur, this function returns @code{None}.
+
+@var{from_tty} specifies whether @value{GDBN} ought to consider this
+command as having originated from the user invoking it interactively.
+It must be a boolean value. If omitted, it defaults to @code{False}.
+@end defun
+
+@findex gdb.get_parameter
+@defun get_parameter parameter
+Return the value of a @value{GDBN} parameter. @var{parameter} is a
+string naming the parameter to look up; @var{parameter} may contain
+spaces if the parameter has a multi-part name. For example,
+@samp{print object} is a valid parameter name.
+
+If the named parameter does not exist, this function throws a
+@code{RuntimeError}. Otherwise, the parameter's value is converted to
+a Python value of the appropriate type, and returned.
+@end defun
+
+@findex gdb.history
+@defun history number
+Return a value from @value{GDBN}'s value history (@pxref{Value
+History}). @var{number} indicates which history element to return.
+If @var{number} is negative, then @value{GDBN} will take its absolute value
+and count backward from the last element (i.e., the most recent element) to
+find the value to return. If @var{number} is zero, then @value{GDBN} will
+return the most recent element. If the element specified by @value{number}
+doesn't exist in the value history, a @code{RuntimeError} exception will be
+raised.
+
+If no exception is raised, the return value is always an instance of
+@code{gdb.Value} (@pxref{Values From Inferior}).
+@end defun
+
+@findex gdb.write
+@defun write string
+Print a string to @value{GDBN}'s paginated standard output stream.
+Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
+call this function.
+@end defun
+
+@findex gdb.flush
+@defun flush
+Flush @value{GDBN}'s paginated standard output stream. Flushing
+@code{sys.stdout} or @code{sys.stderr} will automatically call this
+function.
+@end defun
+
+@node Exception Handling
+@subsubsection Exception Handling
+@cindex python exceptions
+@cindex exceptions, python
+
+When executing the @code{python} command, Python exceptions
+uncaught within the Python code are translated to calls to
+@value{GDBN} error-reporting mechanism. If the command that called
+@code{python} does not handle the error, @value{GDBN} will
+terminate it and print an error message containing the Python
+exception name, the associated value, and the Python call stack
+backtrace at the point where the exception was raised. Example:
+
+@smallexample
+(@value{GDBP}) python print foo
+Traceback (most recent call last):
+ File "<string>", line 1, in <module>
+NameError: name 'foo' is not defined
+@end smallexample
+
+@value{GDBN} errors that happen in @value{GDBN} commands invoked by Python
+code are converted to Python @code{RuntimeError} exceptions. User
+interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
+prompt) is translated to a Python @code{KeyboardInterrupt}
+exception. If you catch these exceptions in your Python code, your
+exception handler will see @code{RuntimeError} or
+@code{KeyboardInterrupt} as the exception type, the @value{GDBN} error
+message as its value, and the Python call stack backtrace at the
+Python statement closest to where the @value{GDBN} error occured as the
+traceback.
+
+@node Values From Inferior
+@subsubsection Values From Inferior
+@cindex values from inferior, with Python
+@cindex python, working with values from inferior
+
+@cindex @code{gdb.Value}
+@value{GDBN} provides values it obtains from the inferior program in
+an object of type @code{gdb.Value}. @value{GDBN} uses this object
+for its internal bookkeeping of the inferior's values, and for
+fetching values when necessary.
+
+Inferior values that are simple scalars can be used directly in
+Python expressions that are valid for the value's data type. Here's
+an example for an integer or floating-point value @code{some_val}:
+
+@smallexample
+bar = some_val + 2
+@end smallexample
+
+@noindent
+As result of this, @code{bar} will also be a @code{gdb.Value} object
+whose values are of the same type as those of @code{some_val}.
+
+Inferior values that are structures or instances of some class can
+be accessed using the Python @dfn{dictionary syntax}. For example, if
+@code{some_val} is a @code{gdb.Value} instance holding a structure, you
+can access its @code{foo} element with:
+
+@smallexample
+bar = some_val['foo']
+@end smallexample
+
+Again, @code{bar} will also be a @code{gdb.Value} object.
+
+For pointer data types, @code{gdb.Value} provides a method for
+dereferencing the pointer to obtain the object it points to.
+
+@defmethod Value dereference
+This method returns a new @code{gdb.Value} object whose contents is
+the object pointed to by the pointer. For example, if @code{foo} is
+a C pointer to an @code{int}, declared in your C program as
+
+@smallexample
+int *foo;
+@end smallexample
+
+@noindent
+then you can use the corresponding @code{gdb.Value} to access what
+@code{foo} points to like this:
+
+@smallexample
+bar = foo.dereference ()
+@end smallexample
+
+The result @code{bar} will be a @code{gdb.Value} object holding the
+value pointed to by @code{foo}.
+@end defmethod
+
@node Interpreters
@chapter Command Interpreters
@cindex command interpreters
@end ignore
@menu
+* GDB/MI General Design::
* GDB/MI Command Syntax::
* GDB/MI Compatibility with CLI::
* GDB/MI Development and Front Ends::
* GDB/MI Signal Handling Commands::
@end ignore
* GDB/MI Target Manipulation::
+* GDB/MI File Transfer Commands::
* GDB/MI Miscellaneous Commands::
@end menu
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI General Design
+@section @sc{gdb/mi} General Design
+@cindex GDB/MI General Design
+
+Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three
+parts---commands sent to @value{GDBN}, responses to those commands
+and notifications. Each command results in exactly one response,
+indicating either successful completion of the command, or an error.
+For the commands that do not resume the target, the response contains the
+requested information. For the commands that resume the target, the
+response only indicates whether the target was successfully resumed.
+Notifications is the mechanism for reporting changes in the state of the
+target, or in @value{GDBN} state, that cannot conveniently be associated with
+a command and reported as part of that command response.
+
+The important examples of notifications are:
+@itemize @bullet
+
+@item
+Exec notifications. These are used to report changes in
+target state---when a target is resumed, or stopped. It would not
+be feasible to include this information in response of resuming
+commands, because one resume commands can result in multiple events in
+different threads. Also, quite some time may pass before any event
+happens in the target, while a frontend needs to know whether the resuming
+command itself was successfully executed.
+
+@item
+Console output, and status notifications. Console output
+notifications are used to report output of CLI commands, as well as
+diagnostics for other commands. Status notifications are used to
+report the progress of a long-running operation. Naturally, including
+this information in command response would mean no output is produced
+until the command is finished, which is undesirable.
+
+@item
+General notifications. Commands may have various side effects on
+the @value{GDBN} or target state beyond their official purpose. For example,
+a command may change the selected thread. Although such changes can
+be included in command response, using notification allows for more
+orthogonal frontend design.
+
+@end itemize
+
+There's no guarantee that whenever an MI command reports an error,
+@value{GDBN} or the target are in any specific state, and especially,
+the state is not reverted to the state before the MI command was
+processed. Therefore, whenever an MI command results in an error,
+we recommend that the frontend refreshes all the information shown in
+the user interface.
+
+@subsection Context management
+
+In most cases when @value{GDBN} accesses the target, this access is
+done in context of a specific thread and frame (@pxref{Frames}).
+Often, even when accessing global data, the target requires that a thread
+be specified. The CLI interface maintains the selected thread and frame,
+and supplies them to target on each command. This is convenient,
+because a command line user would not want to specify that information
+explicitly on each command, and because user interacts with
+@value{GDBN} via a single terminal, so no confusion is possible as
+to what thread and frame are the current ones.
+
+In the case of MI, the concept of selected thread and frame is less
+useful. First, a frontend can easily remember this information
+itself. Second, a graphical frontend can have more than one window,
+each one used for debugging a different thread, and the frontend might
+want to access additional threads for internal purposes. This
+increases the risk that by relying on implicitly selected thread, the
+frontend may be operating on a wrong one. Therefore, each MI command
+should explicitly specify which thread and frame to operate on. To
+make it possible, each MI command accepts the @samp{--thread} and
+@samp{--frame} options, the value to each is @value{GDBN} identifier
+for thread and frame to operate on.
+
+Usually, each top-level window in a frontend allows the user to select
+a thread and a frame, and remembers the user selection for further
+operations. However, in some cases @value{GDBN} may suggest that the
+current thread be changed. For example, when stopping on a breakpoint
+it is reasonable to switch to the thread where breakpoint is hit. For
+another example, if the user issues the CLI @samp{thread} command via
+the frontend, it is desirable to change the frontend's selected thread to the
+one specified by user. @value{GDBN} communicates the suggestion to
+change current thread using the @samp{=thread-selected} notification.
+No such notification is available for the selected frame at the moment.
+
+Note that historically, MI shares the selected thread with CLI, so
+frontends used the @code{-thread-select} to execute commands in the
+right context. However, getting this to work right is cumbersome. The
+simplest way is for frontend to emit @code{-thread-select} command
+before every command. This doubles the number of commands that need
+to be sent. The alternative approach is to suppress @code{-thread-select}
+if the selected thread in @value{GDBN} is supposed to be identical to the
+thread the frontend wants to operate on. However, getting this
+optimization right can be tricky. In particular, if the frontend
+sends several commands to @value{GDBN}, and one of the commands changes the
+selected thread, then the behaviour of subsequent commands will
+change. So, a frontend should either wait for response from such
+problematic commands, or explicitly add @code{-thread-select} for
+all subsequent commands. No frontend is known to do this exactly
+right, so it is suggested to just always pass the @samp{--thread} and
+@samp{--frame} options.
+
+@subsection Asynchronous command execution and non-stop mode
+
+On some targets, @value{GDBN} is capable of processing MI commands
+even while the target is running. This is called @dfn{asynchronous
+command execution} (@pxref{Background Execution}). The frontend may
+specify a preferrence for asynchronous execution using the
+@code{-gdb-set target-async 1} command, which should be emitted before
+either running the executable or attaching to the target. After the
+frontend has started the executable or attached to the target, it can
+find if asynchronous execution is enabled using the
+@code{-list-target-features} command.
+
+Even if @value{GDBN} can accept a command while target is running,
+many commands that access the target do not work when the target is
+running. Therefore, asynchronous command execution is most useful
+when combined with non-stop mode (@pxref{Non-Stop Mode}). Then,
+it is possible to examine the state of one thread, while other threads
+are running.
+
+When a given thread is running, MI commands that try to access the
+target in the context of that thread may not work, or may work only on
+some targets. In particular, commands that try to operate on thread's
+stack will not work, on any target. Commands that read memory, or
+modify breakpoints, may work or not work, depending on the target. Note
+that even commands that operate on global state, such as @code{print},
+@code{set}, and breakpoint commands, still access the target in the
+context of a specific thread, so frontend should try to find a
+stopped thread and perform the operation on that thread (using the
+@samp{--thread} option).
+
+Which commands will work in the context of a running thread is
+highly target dependent. However, the two commands
+@code{-exec-interrupt}, to stop a thread, and @code{-thread-info},
+to find the state of a thread, will always work.
+
+@subsection Thread groups
+@value{GDBN} may be used to debug several processes at the same time.
+On some platfroms, @value{GDBN} may support debugging of several
+hardware systems, each one having several cores with several different
+processes running on each core. This section describes the MI
+mechanism to support such debugging scenarios.
+
+The key observation is that regardless of the structure of the
+target, MI can have a global list of threads, because most commands that
+accept the @samp{--thread} option do not need to know what process that
+thread belongs to. Therefore, it is not necessary to introduce
+neither additional @samp{--process} option, nor an notion of the
+current process in the MI interface. The only strictly new feature
+that is required is the ability to find how the threads are grouped
+into processes.
+
+To allow the user to discover such grouping, and to support arbitrary
+hierarchy of machines/cores/processes, MI introduces the concept of a
+@dfn{thread group}. Thread group is a collection of threads and other
+thread groups. A thread group always has a string identifier, a type,
+and may have additional attributes specific to the type. A new
+command, @code{-list-thread-groups}, returns the list of top-level
+thread groups, which correspond to processes that @value{GDBN} is
+debugging at the moment. By passing an identifier of a thread group
+to the @code{-list-thread-groups} command, it is possible to obtain
+the members of specific thread group.
+
+To allow the user to easily discover processes, and other objects, he
+wishes to debug, a concept of @dfn{available thread group} is
+introduced. Available thread group is an thread group that
+@value{GDBN} is not debugging, but that can be attached to, using the
+@code{-target-attach} command. The list of available top-level thread
+groups can be obtained using @samp{-list-thread-groups --available}.
+In general, the content of a thread group may be only retrieved only
+after attaching to that thread group.
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Command Syntax
@section @sc{gdb/mi} Command Syntax
All output sequences end in a single line containing a period.
@item
-The @code{@var{token}} is from the corresponding request. If an execution
-command is interrupted by the @samp{-exec-interrupt} command, the
-@var{token} associated with the @samp{*stopped} message is the one of the
-original execution command, not the one of the interrupt command.
+The @code{@var{token}} is from the corresponding request. Note that
+for all async output, while the token is allowed by the grammar and
+may be output by future versions of @value{GDBN} for select async
+output messages, it is generally omitted. Frontends should treat
+all async output as reporting general changes in the state of the
+target and there should be no need to associate async output to any
+prior command.
@item
@cindex status output in @sc{gdb/mi}
The best way to avoid unexpected changes in MI that might break your front
end is to make your project known to @value{GDBN} developers and
follow development on @email{gdb@@sourceware.org} and
-@email{gdb-patches@@sourceware.org}. There is also the mailing list
-@email{dmi-discuss@@lists.freestandards.org}, hosted by the Free Standards
-Group, which has the aim of creating a more general MI protocol
-called Debugger Machine Interface (DMI) that will become a standard
-for all debuggers, not just @value{GDBN}.
+@email{gdb-patches@@sourceware.org}.
@cindex mailing lists
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@menu
* GDB/MI Result Records::
* GDB/MI Stream Records::
-* GDB/MI Out-of-band Records::
+* GDB/MI Async Records::
+* GDB/MI Frame Information::
@end menu
@node GDB/MI Result Records
internals.
@end table
-@node GDB/MI Out-of-band Records
-@subsection @sc{gdb/mi} Out-of-band Records
+@node GDB/MI Async Records
+@subsection @sc{gdb/mi} Async Records
-@cindex out-of-band records in @sc{gdb/mi}
-@cindex @sc{gdb/mi}, out-of-band records
-@dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of
+@cindex async records in @sc{gdb/mi}
+@cindex @sc{gdb/mi}, async records
+@dfn{Async} records are used to notify the @sc{gdb/mi} client of
additional changes that have occurred. Those changes can either be a
-consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
+consequence of @sc{gdb/mi} commands (e.g., a breakpoint modified) or a result of
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.
+The following is the list of possible async records:
@table @code
-@item *stopped,reason="@var{reason}"
-@end table
-@var{reason} can be one of the following:
+@item *running,thread-id="@var{thread}"
+The target is now running. The @var{thread} field tells which
+specific thread is now running, and can be @samp{all} if all threads
+are running. The frontend should assume that no interaction with a
+running thread is possible after this notification is produced.
+The frontend should not assume that this notification is output
+only once for any command. @value{GDBN} may emit this notification
+several times, either for different threads, because it cannot resume
+all threads together, or even for a single thread, if the thread must
+be stepped though some code before letting it run freely.
+
+@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}"
+The target has stopped. The @var{reason} field can have one of the
+following values:
@table @code
@item breakpoint-hit
A signal was received by the inferior.
@end table
+The @var{id} field identifies the thread that directly caused the stop
+-- for example by hitting a breakpoint. Depending on whether all-stop
+mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either
+stop all threads, or only the thread that directly triggered the stop.
+If all threads are stopped, the @var{stopped} field will have the
+value of @code{"all"}. Otherwise, the value of the @var{stopped}
+field will be a list of thread identifiers. Presently, this list will
+always include a single thread, but frontend should be prepared to see
+several threads in the list.
+
+@item =thread-group-created,id="@var{id}"
+@itemx =thread-group-exited,id="@var{id}"
+A thread thread group either was attached to, or has exited/detached
+from. The @var{id} field contains the @value{GDBN} identifier of the
+thread group.
+
+@item =thread-created,id="@var{id}",group-id="@var{gid}"
+@itemx =thread-exited,id="@var{id}",group-id="@var{gid}"
+A thread either was created, or has exited. The @var{id} field
+contains the @value{GDBN} identifier of the thread. The @var{gid}
+field identifies the thread group this thread belongs to.
+
+@item =thread-selected,id="@var{id}"
+Informs that the selected thread was changed as result of the last
+command. This notification is not emitted as result of @code{-thread-select}
+command but is emitted whenever an MI command that is not documented
+to change the selected thread actually changes it. In particular,
+invoking, directly or indirectly (via user-defined command), the CLI
+@code{thread} command, will generate this notification.
+
+We suggest that in response to this notification, front ends
+highlight the selected thread and cause subsequent commands to apply to
+that thread.
+
+@end table
+
+@node GDB/MI Frame Information
+@subsection @sc{gdb/mi} Frame Information
+
+Response from many MI commands includes an information about stack
+frame. This information is a tuple that may have the following
+fields:
+
+@table @code
+@item level
+The level of the stack frame. The innermost frame has the level of
+zero. This field is always present.
+
+@item func
+The name of the function corresponding to the frame. This field may
+be absent if @value{GDBN} is unable to determine the function name.
+
+@item addr
+The code address for the frame. This field is always present.
+
+@item file
+The name of the source files that correspond to the frame's code
+address. This field may be absent.
+
+@item line
+The source line corresponding to the frames' code address. This field
+may be absent.
+
+@item from
+The name of the binary file (either executable or shared library) the
+corresponds to the frame's code address. This field may be absent.
+
+@end table
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Simple Examples
-> -exec-run
<- ^running
<- (gdb)
-<- *stopped,reason="breakpoint-hit",bkptno="1",thread-id="0",
+<- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
frame=@{addr="0x08048564",func="main",
args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}],
file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"@}
@smallexample
(gdb)
-break-insert main
-^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",
+^done,bkpt=@{number="1",type="breakpoint",disp="keep",
+enabled="y",addr="0x000100d0",func="main",file="hello.c",
fullname="/home/foo/hello.c",line="5",times="0"@}
(gdb)
-break-after 1 3
@subsubheading Synopsis
@smallexample
- -break-insert [ -t ] [ -h ] [ -r ]
+ -break-insert [ -t ] [ -h ] [ -f ] [ -d ]
[ -c @var{condition} ] [ -i @var{ignore-count} ]
- [ -p @var{thread} ] [ @var{line} | @var{addr} ]
+ [ -p @var{thread} ] [ @var{location} ]
@end smallexample
@noindent
-If specified, @var{line}, can be one of:
+If specified, @var{location}, can be one of:
@itemize @bullet
@item function
Make the breakpoint conditional on @var{condition}.
@item -i @var{ignore-count}
Initialize the @var{ignore-count}.
-@item -r
-Insert a regular breakpoint in all the functions whose names match the
-given regular expression. Other flags are not applicable to regular
-expressions.
+@item -f
+If @var{location} cannot be parsed (for example if it
+refers to unknown files or functions), create a pending
+breakpoint. Without this flag, @value{GDBN} will report
+an error, and won't create a breakpoint, if @var{location}
+cannot be parsed.
+@item -d
+Create a disabled breakpoint.
@end table
@subsubheading Result
@subsubheading Example
-@c FIXME!
-Don't have one around.
+@smallexample
+(gdb)
+-exec-arguments -v word
+^done
+(gdb)
+@end smallexample
@subheading The @code{-exec-show-arguments} Command
@subsubheading Synopsis
@smallexample
- -thread-info
+ -thread-info [ @var{thread-id} ]
@end smallexample
+Reports information about either a specific thread, if
+the @var{thread-id} parameter is present, or about all
+threads. When printing information about all threads,
+also reports the current thread.
+
@subsubheading @value{GDBN} Command
-No equivalent.
+The @samp{info thread} command prints the same information
+about all threads.
@subsubheading Example
-N.A.
-
-
-@subheading The @code{-thread-list-all-threads} Command
-@findex -thread-list-all-threads
-
-@subsubheading Synopsis
@smallexample
- -thread-list-all-threads
+-thread-info
+^done,threads=[
+@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
+ frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@},
+@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
+ frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
+ file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}],
+current-thread-id="1"
+(gdb)
@end smallexample
-@subsubheading @value{GDBN} Command
+The @samp{state} field may have the following values:
-The equivalent @value{GDBN} command is @samp{info threads}.
+@table @code
+@item stopped
+The thread is stopped. Frame information is available for stopped
+threads.
-@subsubheading Example
-N.A.
+@item running
+The thread is running. There's no frame information for running
+threads.
+@end table
@subheading The @code{-thread-list-ids} Command
@findex -thread-list-ids
Produces a list of the currently known @value{GDBN} thread ids. At the
end of the list it also prints the total number of such threads.
+This command is retained for historical reasons, the
+@code{-thread-info} command should be used instead.
+
@subsubheading @value{GDBN} Command
Part of @samp{info threads} supplies the same information.
@subsubheading Example
-No threads present, besides the main process:
-
-@smallexample
-(gdb)
--thread-list-ids
-^done,thread-ids=@{@},number-of-threads="0"
-(gdb)
-@end smallexample
-
-
-Several threads:
-
@smallexample
(gdb)
-thread-list-ids
^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
-number-of-threads="3"
+current-thread-id="1",number-of-threads="3"
(gdb)
@end smallexample
Make @var{threadnum} the current thread. It prints the number of the new
current thread, and the topmost frame for that thread.
+This command is deprecated in favor of explicitly using the
+@samp{--thread} option to each command.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{thread}.
@subsubheading Synopsis
@smallexample
- -exec-continue
+ -exec-continue [--all|--thread-group N]
@end smallexample
Resumes the execution of the inferior program until a breakpoint is
-encountered, or until the inferior exits.
+encountered, or until the inferior exits. In all-stop mode
+(@pxref{All-Stop Mode}), may resume only one thread, or all threads,
+depending on the value of the @samp{scheduler-locking} variable. In
+non-stop mode (@pxref{Non-Stop Mode}), if the @samp{--all} is not
+specified, only the thread specified with the @samp{--thread} option
+(or current thread, if no @samp{--thread} is provided) is resumed. If
+@samp{--all} is specified, all threads will be resumed. The
+@samp{--all} option is ignored in all-stop mode. If the
+@samp{--thread-group} options is specified, then all threads in that
+thread group are resumed.
@subsubheading @value{GDBN} Command
^running
(gdb)
@@Hello world
-*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
-file="hello.c",fullname="/home/foo/bar/hello.c",line="13"@}
+*stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame=@{
+func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c",
+line="13"@}
(gdb)
@end smallexample
@subsubheading Synopsis
@smallexample
- -exec-interrupt
+ -exec-interrupt [--all|--thread-group N]
@end smallexample
Interrupts the background execution of the target. Note how the token
appears in the @samp{^done} output. If the user is trying to
interrupt a non-running program, an error message will be printed.
+Note that when asynchronous execution is enabled, this command is
+asynchronous just like other execution commands. That is, first the
+@samp{^done} response will be printed, and the target stop will be
+reported after that using the @samp{*stopped} notification.
+
+In non-stop mode, only the context thread is interrupted by default.
+All threads will be interrupted if the @samp{--all} option is
+specified. If the @samp{--thread-group} option is specified, all
+threads in that group will be interrupted.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{interrupt}.
000-exec-run
000^running
(gdb)
-000*stopped,reason="breakpoint-hit",bkptno="1",
+000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
-exec-run
^running
(gdb)
-*stopped,reason="breakpoint-hit",bkptno="1",
+*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
frame=@{func="main",args=[],file="recursive2.c",
fullname="/home/foo/bar/recursive2.c",line="4"@}
(gdb)
Change the selected frame. Select a different frame @var{framenum} on
the stack.
+This command in deprecated in favor of passing the @samp{--frame}
+option to every command.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
called ``frozen variable objects''. Such variable objects are never
implicitly updated.
+Variable objects can be either @dfn{fixed} or @dfn{floating}. For the
+fixed variable object, the expression is parsed when the variable
+object is created, including associating identifiers to specific
+variables. The meaning of expression never changes. For a floating
+variable object the values of variables whose names appear in the
+expressions are re-evaluated every time in the context of the current
+frame. Consider this example:
+
+@smallexample
+void do_work(...)
+@{
+ struct work_state state;
+
+ if (...)
+ do_work(...);
+@}
+@end smallexample
+
+If a fixed variable object for the @code{state} variable is created in
+this function, and we enter the recursive call, the the variable
+object will report the value of @code{state} in the top-level
+@code{do_work} invocation. On the other hand, a floating variable
+object will report the value of @code{state} in the current frame.
+
+If an expression specified when creating a fixed variable object
+refers to a local variable, the variable object becomes bound to the
+thread and frame in which the variable object is created. When such
+variable object is updated, @value{GDBN} makes sure that the
+thread/frame combination the variable object is bound to still exists,
+and re-evaluates the variable object in context of that thread/frame.
+
The following is the complete set of @sc{gdb/mi} operations defined to
access this functionality:
@smallexample
-var-create @{@var{name} | "-"@}
- @{@var{frame-addr} | "*"@} @var{expression}
+ @{@var{frame-addr} | "*" | "@@"@} @var{expression}
@end smallexample
This operation creates a variable object, which allows the monitoring of
The @var{name} parameter is the string by which the object can be
referenced. It must be unique. If @samp{-} is specified, the varobj
system will generate a string ``varNNNNNN'' automatically. It will be
-unique provided that one does not specify @var{name} on that format.
+unique provided that one does not specify @var{name} of that format.
The command fails if a duplicate name is found.
The frame under which the expression should be evaluated can be
specified by @var{frame-addr}. A @samp{*} indicates that the current
-frame should be used.
+frame should be used. A @samp{@@} indicates that a floating variable
+object must be created.
@var{expression} is any expression valid on the current language set (must not
begin with a @samp{*}), or one of the following:
This operation returns the name, number of children and the type of the
object created. Type is returned as a string as the ones generated by
-the @value{GDBN} CLI:
+the @value{GDBN} CLI. If a fixed variable object is bound to a
+specific thread, the thread is is also printed:
@smallexample
- name="@var{name}",numchild="N",type="@var{type}"
+ name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}"
@end smallexample
Sets the output format for the value of the object @var{name} to be
@var{format-spec}.
+@anchor{-var-set-format}
The syntax for the @var{format-spec} is as follows:
@smallexample
@subsubheading Synopsis
@smallexample
- -var-evaluate-expression @var{name}
+ -var-evaluate-expression [-f @var{format-spec}] @var{name}
@end smallexample
Evaluates the expression that is represented by the specified variable
-object and returns its value as a string. The format of the
-string can be changed using the @code{-var-set-format} command.
+object and returns its value as a string. The format of the string
+can be specified with the @samp{-f} option. The possible values of
+this option are the same as for @code{-var-set-format}
+(@pxref{-var-set-format}). If the @samp{-f} option is not specified,
+the current display format will be used. The current display format
+can be changed using the @code{-var-set-format} command.
@smallexample
value=@var{value}
object names, all existing variable objects are updated, except
for frozen ones (@pxref{-var-set-frozen}). The option
@var{print-values} determines whether both names and values, or just
-names are printed. The possible values of this options are the same
+names are printed. The possible values of this option are the same
as for @code{-var-list-children} (@pxref{-var-list-children}). It is
recommended to use the @samp{--all-values} option, to reduce the
number of MI commands needed on each program stop.
+With the @samp{*} parameter, if a variable object is bound to a
+currently running thread, it will not be updated, without any
+diagnostic.
@subsubheading Example
^running
(gdb)
-*stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
-args=[],file="try.c",fullname="/home/foo/bar/try.c",line="5"@}
+*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame=@{
+func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c",
+line="5"@}
(gdb)
-data-list-changed-registers
^done,changed-registers=["0","1","2","4","5","6","7","8","9",
@end smallexample
List the line number, the current source file, and the absolute path
-to the current source file for the current executable.
+to the current source file for the current executable. The macro
+information field has a value of @samp{1} or @samp{0} depending on
+whether or not the file includes preprocessor macro information.
@subsubheading @value{GDBN} Command
@smallexample
(gdb)
123-file-list-exec-source-file
-123^done,line="1",file="foo.c",fullname="/home/bar/foo.c"
+123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"
(gdb)
@end smallexample
@subsubheading Synopsis
@smallexample
- -target-attach @var{pid} | @var{file}
+ -target-attach @var{pid} | @var{gid} | @var{file}
@end smallexample
-Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
+Attach to a process @var{pid} or a file @var{file} outside of
+@value{GDBN}, or a thread group @var{gid}. If attaching to a thread
+group, the id previously returned by
+@samp{-list-thread-groups --available} must be used.
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{attach}.
@subsubheading Example
-N.A.
-
+@smallexample
+(gdb)
+-target-attach 34
+=thread-created,id="1"
+*stopped,thread-id="1",frame=@{addr="0xb7f7e410",func="bar",args=[]@}
+^done
+(gdb)
+@end smallexample
@subheading The @code{-target-compare-sections} Command
@findex -target-compare-sections
@subsubheading Synopsis
@smallexample
- -target-detach
+ -target-detach [ @var{pid} | @var{gid} ]
@end smallexample
Detach from the remote target which normally resumes its execution.
-There's no output.
+If either @var{pid} or @var{gid} is specified, detaches from either
+the specified process, or specified thread group. There's no output.
@subsubheading @value{GDBN} Command
@table @samp
@item @var{type}
-The type of target, for instance @samp{async}, @samp{remote}, etc.
+The type of target, for instance @samp{remote}, etc.
@item @var{parameters}
Device names, host names and the like. @xref{Target Commands, ,
Commands for Managing Targets}, for more details.
which the target program is, in the following form:
@smallexample
-^connected,addr="@var{address}",func="@var{function name}",
- args=[@var{arg list}]
+^connected,addr="@var{address}",func="@var{function name}",
+ args=[@var{arg list}]
+@end smallexample
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{target}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-target-select remote /dev/ttya
+^connected,addr="0xfe00a300",func="??",args=[]
+(gdb)
+@end smallexample
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI File Transfer Commands
+@section @sc{gdb/mi} File Transfer Commands
+
+
+@subheading The @code{-target-file-put} Command
+@findex -target-file-put
+
+@subsubheading Synopsis
+
+@smallexample
+ -target-file-put @var{hostfile} @var{targetfile}
+@end smallexample
+
+Copy file @var{hostfile} from the host system (the machine running
+@value{GDBN}) to @var{targetfile} on the target system.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{remote put}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-target-file-put localfile remotefile
+^done
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-target-file-get} Command
+@findex -target-file-get
+
+@subsubheading Synopsis
+
+@smallexample
+ -target-file-get @var{targetfile} @var{hostfile}
+@end smallexample
+
+Copy file @var{targetfile} from the target system to @var{hostfile}
+on the host system.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{remote get}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-target-file-get remotefile localfile
+^done
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-target-file-delete} Command
+@findex -target-file-delete
+
+@subsubheading Synopsis
+
+@smallexample
+ -target-file-delete @var{targetfile}
@end smallexample
+Delete @var{targetfile} from the target system.
+
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{target}.
+The corresponding @value{GDBN} command is @samp{remote delete}.
@subsubheading Example
@smallexample
(gdb)
--target-select async /dev/ttya
-^connected,addr="0xfe00a300",func="??",args=[]
+-target-file-delete remotefile
+^done
(gdb)
@end smallexample
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Miscellaneous Commands
@section Miscellaneous @sc{gdb/mi} Commands
(gdb)
@end smallexample
+@subheading The @code{-list-features} Command
+@findex -list-features
+
+Returns a list of particular features of the MI protocol that
+this version of gdb implements. A feature can be a command,
+or a new field in an output of some command, or even an
+important bugfix. While a frontend can sometimes detect presence
+of a feature at runtime, it is easier to perform detection at debugger
+startup.
+
+The command returns a list of strings, with each string naming an
+available feature. Each returned string is just a name, it does not
+have any internal structure. The list of possible feature names
+is given below.
+
+Example output:
+
+@smallexample
+(gdb) -list-features
+^done,result=["feature1","feature2"]
+@end smallexample
+
+The current list of features is:
+
+@table @samp
+@item frozen-varobjs
+Indicates presence of the @code{-var-set-frozen} command, as well
+as possible presense of the @code{frozen} field in the output
+of @code{-varobj-create}.
+@item pending-breakpoints
+Indicates presence of the @option{-f} option to the @code{-break-insert} command.
+@item thread-info
+Indicates presence of the @code{-thread-info} command.
+
+@end table
+
+@subheading The @code{-list-target-features} Command
+@findex -list-target-features
+
+Returns a list of particular features that are supported by the
+target. Those features affect the permitted MI commands, but
+unlike the features reported by the @code{-list-features} command, the
+features depend on which target GDB is using at the moment. Whenever
+a target can change, due to commands such as @code{-target-select},
+@code{-target-attach} or @code{-exec-run}, the list of target features
+may change, and the frontend should obtain it again.
+Example output:
+
+@smallexample
+(gdb) -list-features
+^done,result=["async"]
+@end smallexample
+
+The current list of features is:
+
+@table @samp
+@item async
+Indicates that the target is capable of asynchronous command
+execution, which means that @value{GDBN} will accept further commands
+while the target is running.
+
+@end table
+
+@subheading The @code{-list-thread-groups} Command
+@findex -list-thread-groups
+
+@subheading Synopsis
+
+@smallexample
+-list-thread-groups [ --available ] [ @var{group} ]
+@end smallexample
+
+When used without the @var{group} parameter, lists top-level thread
+groups that are being debugged. When used with the @var{group}
+parameter, the children of the specified group are listed. The
+children can be either threads, or other groups. At present,
+@value{GDBN} will not report both threads and groups as children at
+the same time, but it may change in future.
+
+With the @samp{--available} option, instead of reporting groups that
+are been debugged, GDB will report all thread groups available on the
+target. Using the @samp{--available} option together with @var{group}
+is not allowed.
+
+@subheading Example
+
+@smallexample
+@value{GDBP}
+-list-thread-groups
+^done,groups=[@{id="17",type="process",pid="yyy",num_children="2"@}]
+-list-thread-groups 17
+^done,threads=[@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
+ frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@},
+@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
+ frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
+ file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}]]
+@end smallexample
+
@subheading The @code{-interpreter-exec} Command
@findex -interpreter-exec
-exec-run
^running
(gdb)
-*stopped,reason="breakpoint-hit",bkptno="1",thread-id="0",
+*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
frame=@{addr="0x080484ed",func="main",args=[@{name="argc",value="1"@},
@{name="argv",value="0xbfb60364"@}],file="myprog.c",
fullname="/home/nickrob/myprog.c",line="73"@}
distribution.
@c should add a web page ref...
+@ifset BUGURL
+@ifset BUGURL_DEFAULT
In any event, we also recommend that you submit bug reports for
@value{GDBN}. The preferred method is to submit them directly using
@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web
path back to the sender. Thus, if we need to ask for more information,
we may be unable to reach you. For this reason, it is better to send
bug reports to the mailing list.
+@end ifset
+@ifclear BUGURL_DEFAULT
+In any event, we also recommend that you submit bug reports for
+@value{GDBN} to @value{BUGURL}.
+@end ifclear
+@end ifset
The fundamental principle of reporting bugs usefully is this:
@strong{report all the facts}. If you are not sure whether to state a
* Separate Objdir:: Compiling @value{GDBN} in another directory
* Config Names:: Specifying names for hosts and targets
* Configure Options:: Summary of options for configure
+* System-wide configuration:: Having a system-wide init file
@end menu
@node Requirements
standard locations; if it is installed in an unusual path, you can
use the @option{--with-libexpat-prefix} option to specify its location.
-Expat is used for remote protocol memory maps (@pxref{Memory Map Format})
-and for target descriptions (@pxref{Target Descriptions}).
+Expat is used for:
+
+@itemize @bullet
+@item
+Remote protocol memory maps (@pxref{Memory Map Format})
+@item
+Target descriptions (@pxref{Target Descriptions})
+@item
+Remote shared library lists (@pxref{Library List Format})
+@item
+MS-Windows shared libraries (@pxref{Shared Libraries})
+@end itemize
+
+@item zlib
+@cindex compressed debug sections
+@value{GDBN} will use the @samp{zlib} library, if available, to read
+compressed debug sections. Some linkers, such as GNU gold, are capable
+of producing binaries with compressed debug sections. If @value{GDBN}
+is compiled with @samp{zlib}, it will be able to read the debug
+information in such binaries.
+
+The @samp{zlib} library is likely included with your operating system
+distribution; if it is not, you can get the latest version from
+@url{http://zlib.net}.
@end table
There are many other options available as well, but they are generally
needed for special purposes only.
+@node System-wide configuration
+@section System-wide configuration and settings
+@cindex system-wide init file
+
+@value{GDBN} can be configured to have a system-wide init file;
+this file will be read and executed at startup (@pxref{Startup, , What
+@value{GDBN} does during startup}).
+
+Here is the corresponding configure option:
+
+@table @code
+@item --with-system-gdbinit=@var{file}
+Specify that the default location of the system-wide init file is
+@var{file}.
+@end table
+
+If @value{GDBN} has been configured with the option @option{--prefix=$prefix},
+it may be subject to relocation. Two possible cases:
+
+@itemize @bullet
+@item
+If the default location of this init file contains @file{$prefix},
+it will be subject to relocation. Suppose that the configure options
+are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit};
+if @value{GDBN} is moved from @file{$prefix} to @file{$install}, the system
+init file is looked for as @file{$install/etc/gdbinit} instead of
+@file{$prefix/etc/gdbinit}.
+
+@item
+By contrast, if the default location does not contain the prefix,
+it will not be relocated. E.g.@: if @value{GDBN} has been configured with
+@option{--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit},
+then @value{GDBN} will always look for @file{/usr/share/gdb/gdbinit},
+wherever @value{GDBN} is installed.
+@end itemize
+
@node Maintenance Commands
@appendix Maintenance Commands
@cindex maintenance commands
@end table
+@kindex set displaced-stepping
+@kindex show displaced-stepping
+@cindex displaced stepping support
+@cindex out-of-line single-stepping
+@item set displaced-stepping
+@itemx show displaced-stepping
+Control whether or not @value{GDBN} will do @dfn{displaced stepping}
+if the target supports it. Displaced stepping is a way to single-step
+over breakpoints without removing them from the inferior, by executing
+an out-of-line copy of the instruction that was originally at the
+breakpoint location. It is also known as out-of-line single-stepping.
+
+@table @code
+@item set displaced-stepping on
+If the target architecture supports it, @value{GDBN} will use
+displaced stepping to step over breakpoints.
+
+@item set displaced-stepping off
+@value{GDBN} will not use displaced stepping to step over breakpoints,
+even if such is supported by the target architecture.
+
+@cindex non-stop mode, and @samp{set displaced-stepping}
+@item set displaced-stepping auto
+This is the default mode. @value{GDBN} will use displaced stepping
+only if non-stop mode is active (@pxref{Non-Stop Mode}) and the target
+architecture supports displaced stepping.
+@end table
+
@kindex maint check-symtabs
@item maint check-symtabs
Check the consistency of psymtabs and symtabs.
(@value{GDBP})
@end smallexample
+@cindex @value{GDBN} internal error
+@cindex internal errors, control of @value{GDBN} behavior
+
+@kindex maint set internal-error
+@kindex maint show internal-error
+@kindex maint set internal-warning
+@kindex maint show internal-warning
+@item maint set internal-error @var{action} [ask|yes|no]
+@itemx maint show internal-error @var{action}
+@itemx maint set internal-warning @var{action} [ask|yes|no]
+@itemx maint show internal-warning @var{action}
+When @value{GDBN} reports an internal problem (error or warning) it
+gives the user the opportunity to both quit @value{GDBN} and create a
+core file of the current @value{GDBN} session. These commands let you
+override the default behaviour for each particular @var{action},
+described in the table below.
+
+@table @samp
+@item quit
+You can specify that @value{GDBN} should always (yes) or never (no)
+quit. The default is to ask the user what to do.
+
+@item corefile
+You can specify that @value{GDBN} should always (yes) or never (no)
+create a core file. The default is to ask the user what to do.
+@end table
+
@kindex maint packet
@item maint packet @var{text}
If @value{GDBN} is talking to an inferior via the serial protocol,
Print the entire architecture configuration. The optional argument
@var{file} names the file where the output goes.
+@kindex maint print c-tdesc
+@item maint print c-tdesc
+Print the current target description (@pxref{Target Descriptions}) as
+a C source file. The created source file can be used in @value{GDBN}
+when an XML parser is not available to parse the description.
+
@kindex maint print dummy-frames
@item maint print dummy-frames
Prints the contents of @value{GDBN}'s internal dummy-frame stack.
Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be
compiled with the @samp{-pg} compiler option.
+@kindex maint set linux-async
+@kindex maint show linux-async
+@cindex asynchronous support
+@item maint set linux-async
+@itemx maint show linux-async
+Control the GNU/Linux native asynchronous support
+(@pxref{Background Execution}) of @value{GDBN}.
+
+GNU/Linux native asynchronous support will be disabled until you use
+the @samp{maint set linux-async} command to enable it.
+
+@kindex maint set remote-async
+@kindex maint show remote-async
+@cindex asynchronous support
+@item maint set remote-async
+@itemx maint show remote-async
+Control the remote asynchronous support
+(@pxref{Background Execution}) of @value{GDBN}.
+
+Remote asynchronous support will be disabled until you use
+the @samp{maint set remote-async} command to enable it.
+
@kindex maint show-debug-regs
@cindex x86 hardware debug registers
@item maint show-debug-regs
Control whether to display the execution time for each command. If
set to a nonzero value, @value{GDBN} will display how much time it
took to execute each command, following the command's own output.
+The time is not printed for the commands that run the target, since
+there's no mechanism currently to compute how much time was spend
+by @value{GDBN} and how much time was spend by the program been debugged.
+it's not possibly currently
This can also be requested by invoking @value{GDBN} with the
@option{--statistics} command-line switch (@pxref{Mode Options}).
the @code{info address} command (@pxref{Symbols}), except that this
command also allows to find symbols in other sections.
+If section was not specified, the section in which the symbol was found
+is also printed. For dynamically linked executables, the name of
+executable or shared library containing the symbol is printed as well.
+
@end table
The following command is useful for non-interactive invocations of
* General Query Packets::
* Register Packet Format::
* Tracepoint Packets::
+* Host I/O Packets::
* Interrupts::
+* Notification Packets::
+* Remote Non-Stop::
+* Packet Acknowledgment::
* Examples::
* File-I/O Remote Protocol Extension::
* Library List Format::
@cindex protocol, @value{GDBN} remote serial
@cindex serial protocol, @value{GDBN} remote
@cindex remote serial protocol
-All @value{GDBN} commands and responses (other than acknowledgments) are
-sent as a @var{packet}. A @var{packet} is introduced with the character
+All @value{GDBN} commands and responses (other than acknowledgments
+and notifications, see @ref{Notification Packets}) are sent as a
+@var{packet}. A @var{packet} is introduced with the character
@samp{$}, the actual @var{packet-data}, and the terminating character
@samp{#} followed by a two-digit @var{checksum}:
has never output @var{sequence-id}s. Stubs that handle packets added
since @value{GDBN} 5.0 must not accept @var{sequence-id}.
-@cindex acknowledgment, for @value{GDBN} remote
When either the host or the target machine receives a packet, the first
response expected is an acknowledgment: either @samp{+} (to indicate
the package was received correctly) or @samp{-} (to request
@end smallexample
@noindent
+The @samp{+}/@samp{-} acknowledgments can be disabled
+once a connection is established.
+@xref{Packet Acknowledgment}, for details.
+
The host (@value{GDBN}) sends @var{command}s, and the target (the
debugging stub incorporated in your program) sends a @var{response}. In
the case of step and continue @var{command}s, the response is only sent
-when the operation has completed (the target has again stopped).
+when the operation has completed, and the target has again stopped all
+threads in all attached processes. This is the default all-stop mode
+behavior, but the remote protocol also supports @value{GDBN}'s non-stop
+execution mode; see @ref{Remote Non-Stop}, for details.
@var{packet-data} consists of a sequence of characters with the
exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
is not interpreted as the start of a run-length encoded sequence
(described next).
-Response @var{data} can be run-length encoded to save space. A @samp{*}
-means that the next character is an @sc{ascii} encoding giving a repeat count
-which stands for that many repetitions of the character preceding the
-@samp{*}. The encoding is @code{n+29}, yielding a printable character
-where @code{n >=3} (which is where rle starts to win). The printable
-characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
-value greater than 126 should not be used.
-
-So:
-@smallexample
-"@code{0* }"
-@end smallexample
-@noindent
-means the same as "0000".
+Response @var{data} can be run-length encoded to save space.
+Run-length encoding replaces runs of identical characters with one
+instance of the repeated character, followed by a @samp{*} and a
+repeat count. The repeat count is itself sent encoded, to avoid
+binary characters in @var{data}: a value of @var{n} is sent as
+@code{@var{n}+29}. For a repeat count greater or equal to 3, this
+produces a printable @sc{ascii} character, e.g.@: a space (@sc{ascii}
+code 32) for a repeat count of 3. (This is because run-length
+encoding starts to win for counts 3 or more.) Thus, for example,
+@samp{0* } is a run-length encoding of ``0000'': the space character
+after @samp{*} means repeat the leading @code{0} @w{@code{32 - 29 =
+3}} more times.
+
+The printable characters @samp{#} and @samp{$} or with a numeric value
+greater than 126 must not be used. Runs of six repeats (@samp{#}) or
+seven repeats (@samp{$}) can be expanded using a repeat count of only
+five (@samp{"}). For example, @samp{00000000} can be encoded as
+@samp{0*"00}.
The error response returned for some packets includes a two character
error number. That number is not well defined.
@samp{foo} and the @var{bar}, or between the @var{bar} and the
@var{baz}.
+@cindex @var{thread-id}, in remote protocol
+@anchor{thread-id syntax}
+Several packets and replies include a @var{thread-id} field to identify
+a thread. Normally these are positive numbers with a target-specific
+interpretation, formatted as big-endian hex strings. A @var{thread-id}
+can also be a literal @samp{-1} to indicate all threads, or @samp{0} to
+pick any thread.
+
+In addition, the remote protocol supports a multiprocess feature in
+which the @var{thread-id} syntax is extended to optionally include both
+process and thread ID fields, as @samp{p@var{pid}.@var{tid}}.
+The @var{pid} (process) and @var{tid} (thread) components each have the
+format described above: a positive number with target-specific
+interpretation formatted as a big-endian hex string, literal @samp{-1}
+to indicate all processes or threads (respectively), or @samp{0} to
+indicate an arbitrary process or thread. Specifying just a process, as
+@samp{p@var{pid}}, is equivalent to @samp{p@var{pid}.-1}. It is an
+error to specify all processes but a specific thread, such as
+@samp{p-1.@var{tid}}. Note that the @samp{p} prefix is @emph{not} used
+for those packets and replies explicitly documented to include a process
+ID, rather than a @var{thread-id}.
+
+The multiprocess @var{thread-id} syntax extensions are only used if both
+@value{GDBN} and the stub report support for the @samp{multiprocess}
+feature using @samp{qSupported}. @xref{multiprocess extensions}, for
+more information.
+
Note that all packet forms beginning with an upper- or lower-case
letter, other than those described here, are reserved for future use.
@item !
@cindex @samp{!} packet
+@anchor{extended mode}
Enable extended mode. In extended mode, the remote server is made
persistent. The @samp{R} packet is used to restart the program being
debugged.
@item ?
@cindex @samp{?} packet
Indicate the reason the target halted. The reply is the same as for
-step and continue.
+step and continue. This packet has a special interpretation when the
+target is in non-stop mode; see @ref{Remote Non-Stop}.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
Don't use this packet. Use the @samp{Z} and @samp{z} packets instead
(@pxref{insert breakpoint or watchpoint packet}).
+@item bc
+@cindex @samp{bc} packet
+Backward continue. Execute the target system in reverse. No parameter.
+@xref{Reverse Execution}, for more information.
+
+Reply:
+@xref{Stop Reply Packets}, for the reply specifications.
+
+@item bs
+@cindex @samp{bs} packet
+Backward single step. Execute one instruction in reverse. No parameter.
+@xref{Reverse Execution}, for more information.
+
+Reply:
+@xref{Stop Reply Packets}, for the reply specifications.
+
@item c @r{[}@var{addr}@r{]}
@cindex @samp{c} packet
Continue. @var{addr} is address to resume. If @var{addr} is omitted,
(@pxref{General Query Packets}).
@item D
+@itemx D;@var{pid}
@cindex @samp{D} packet
-Detach @value{GDBN} from the remote system. Sent to the remote target
+The first form of the packet is used to detach @value{GDBN} from the
+remote system. It is sent to the remote target
before @value{GDBN} disconnects via the @code{detach} command.
+The second form, including a process ID, is used when multiprocess
+protocol extensions are enabled (@pxref{multiprocess extensions}), to
+detach only a specific process. The @var{pid} is specified as a
+big-endian hex string.
+
Reply:
@table @samp
@item OK
for an error
@end table
-@item H @var{c} @var{t}
+@item H @var{c} @var{thread-id}
@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} may be @samp{-1}, meaning all
-the threads, a thread number, or @samp{0} which means pick any thread.
+operations. The thread designator @var{thread-id} has the format and
+interpretation described in @ref{thread-id syntax}.
Reply:
@table @samp
@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.
+This packet is only available in extended mode (@pxref{extended mode}).
The @samp{R} packet has no reply.
@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes.
@var{addr} must be at least 3 digits.
-@item T @var{XX}
+@item T @var{thread-id}
@cindex @samp{T} packet
-Find out if the thread XX is alive.
+Find out if the thread @var{thread-id} is alive. @xref{thread-id syntax}.
Reply:
@table @samp
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).
-@item vCont@r{[};@var{action}@r{[}:@var{tid}@r{]]}@dots{}
+@item vAttach;@var{pid}
+@cindex @samp{vAttach} packet
+Attach to a new process with the specified process ID @var{pid}.
+The process ID is a
+hexadecimal integer identifying the process. In all-stop mode, all
+threads in the attached process are stopped; in non-stop mode, it may be
+attached without being stopped if that is supported by the target.
+
+@c In non-stop mode, on a successful vAttach, the stub should set the
+@c current thread to a thread of the newly-attached process. After
+@c attaching, GDB queries for the attached process's thread ID with qC.
+@c Also note that, from a user perspective, whether or not the
+@c target is stopped on attach in non-stop mode depends on whether you
+@c use the foreground or background version of the attach command, not
+@c on what vAttach does; GDB does the right thing with respect to either
+@c stopping or restarting threads.
+
+This packet is only available in extended mode (@pxref{extended mode}).
+
+Reply:
+@table @samp
+@item E @var{nn}
+for an error
+@item @r{Any stop packet}
+for success in all-stop mode (@pxref{Stop Reply Packets})
+@item OK
+for success in non-stop mode (@pxref{Remote Non-Stop})
+@end table
+
+@item vCont@r{[};@var{action}@r{[}:@var{thread-id}@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
+If an action is specified with no @var{thread-id}, 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
+specified then other threads should remain stopped in all-stop mode and
+in their current state in non-stop mode.
+Specifying multiple
default actions is an error; specifying no actions is also an error.
-Thread IDs are specified in hexadecimal. Currently supported actions are:
+Thread IDs are specified using the syntax described in @ref{thread-id syntax}.
+
+Currently supported actions are:
@table @samp
@item c
Continue.
@item C @var{sig}
-Continue with signal @var{sig}. @var{sig} should be two hex digits.
+Continue with signal @var{sig}. The signal @var{sig} should be two hex digits.
@item s
Step.
@item S @var{sig}
-Step with signal @var{sig}. @var{sig} should be two hex digits.
+Step with signal @var{sig}. The signal @var{sig} should be two hex digits.
+@item t
+Stop.
+@item T @var{sig}
+Stop with signal @var{sig}. The signal @var{sig} should be two hex digits.
@end table
-The optional @var{addr} argument normally associated with these packets is
+The optional argument @var{addr} normally associated with the
+@samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is
not supported in @samp{vCont}.
+The @samp{t} and @samp{T} actions are only relevant in non-stop mode
+(@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise.
+A stop reply should be generated for any affected thread not already stopped.
+When a thread is stopped by means of a @samp{t} action,
+the corresponding stop reply should indicate that the thread has stopped with
+signal @samp{0}, regardless of whether the target uses some other signal
+as an implementation detail.
+
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
The @samp{vCont} packet is not supported.
@end table
+@item vFile:@var{operation}:@var{parameter}@dots{}
+@cindex @samp{vFile} packet
+Perform a file operation on the target system. For details,
+see @ref{Host I/O Packets}.
+
@item vFlashErase:@var{addr},@var{length}
@cindex @samp{vFlashErase} packet
Direct the stub to erase @var{length} bytes of flash starting at
stub is allowed to delay erase operation until the @samp{vFlashDone}
packet is received.
+The stub must support @samp{vCont} if it reports support for
+multiprocess extensions (@pxref{multiprocess extensions}). Note that in
+this case @samp{vCont} actions can be specified to apply to all threads
+in a process by using the @samp{p@var{pid}.-1} form of the
+@var{thread-id}.
+
Reply:
@table @samp
@item OK
regions of flash memory are unpredictable until the @samp{vFlashDone}
request is completed.
+@item vKill;@var{pid}
+@cindex @samp{vKill} packet
+Kill the process with the specified process ID. @var{pid} is a
+hexadecimal integer identifying the process. This packet is used in
+preference to @samp{k} when multiprocess protocol extensions are
+supported; see @ref{multiprocess extensions}.
+
+Reply:
+@table @samp
+@item E @var{nn}
+for an error
+@item OK
+for success
+@end table
+
+@item vRun;@var{filename}@r{[};@var{argument}@r{]}@dots{}
+@cindex @samp{vRun} packet
+Run the program @var{filename}, passing it each @var{argument} on its
+command line. The file and arguments are hex-encoded strings. If
+@var{filename} is an empty string, the stub may use a default program
+(e.g.@: the last program run). The program is created in the stopped
+state.
+
+@c FIXME: What about non-stop mode?
+
+This packet is only available in extended mode (@pxref{extended mode}).
+
+Reply:
+@table @samp
+@item E @var{nn}
+for an error
+@item @r{Any stop packet}
+for success (@pxref{Stop Reply Packets})
+@end table
+
+@item vStopped
+@anchor{vStopped packet}
+@cindex @samp{vStopped} packet
+
+In non-stop mode (@pxref{Remote Non-Stop}), acknowledge a previous stop
+reply and prompt for the stub to report another one.
+
+Reply:
+@table @samp
+@item @r{Any stop packet}
+if there is another unreported stop event (@pxref{Stop Reply Packets})
+@item OK
+if there are no unreported stop events
+@end table
+
@item X @var{addr},@var{length}:@var{XX@dots{}}
@anchor{X packet}
@cindex @samp{X} packet
@section Stop Reply Packets
@cindex stop reply packets
-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
+The @samp{C}, @samp{c}, @samp{S}, @samp{s}, @samp{vCont},
+@samp{vAttach}, @samp{vRun}, @samp{vStopped}, and @samp{?} packets can
+receive any of the below as a reply. Except for @samp{?}
+and @samp{vStopped}, that reply is only returned
when the target halts. In the below the exact meaning of @dfn{signal
number} is defined by the header @file{include/gdb/signals.h} in the
@value{GDBN} source code.
two-digit hex number.
@item
-If @var{n} is @samp{thread}, then @var{r} is the thread process ID, in
-hex.
+If @var{n} is @samp{thread}, then @var{r} is the @var{thread-id} of
+the stopped thread, as specified in @ref{thread-id syntax}.
@item
If @var{n} is a recognized @dfn{stop reason}, it describes a more
The packet indicates that the loaded libraries have changed.
@value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new
list of loaded libraries. @var{r} is ignored.
+
+@cindex replay log events, remote reply
+@item replaylog
+The packet indicates that the target cannot continue replaying
+logged execution events, because it has reached the end (or the
+beginning when executing backward) of the log. The value of @var{r}
+will be either @samp{begin} or @samp{end}. @xref{Reverse Execution},
+for more information.
+
+
@end table
@item W @var{AA}
+@itemx W @var{AA} ; process:@var{pid}
The process exited, and @var{AA} is the exit status. This is only
applicable to certain targets.
+The second form of the response, including the process ID of the exited
+process, can be used only when @value{GDBN} has reported support for
+multiprocess protocol extensions; see @ref{multiprocess extensions}.
+The @var{pid} is formatted as a big-endian hex string.
+
@item X @var{AA}
+@itemx X @var{AA} ; process:@var{pid}
The process terminated with signal @var{AA}.
+The second form of the response, including the process ID of the
+terminated process, can be used only when @value{GDBN} has reported
+support for multiprocess protocol extensions; see @ref{multiprocess
+extensions}. The @var{pid} is formatted as a big-endian hex string.
+
@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.
+for @samp{W}, @samp{T}, etc. This reply is not permitted in non-stop mode.
@item F @var{call-id},@var{parameter}@dots{}
@var{call-id} is the identifier which says which host system call should
@item qC
@cindex current thread, remote request
@cindex @samp{qC} packet
-Return the current thread id.
+Return the current thread ID.
Reply:
@table @samp
-@item QC @var{pid}
-Where @var{pid} is an unsigned hexadecimal process id.
+@item QC @var{thread-id}
+Where @var{thread-id} is a thread ID as documented in
+@ref{thread-id syntax}.
@item @r{(anything else)}
-Any other reply implies the old pid.
+Any other reply implies the old thread ID.
@end table
@item qCRC:@var{addr},@var{length}
@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
+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
Reply:
@table @samp
-@item m @var{id}
-A single thread id
-@item m @var{id},@var{id}@dots{}
-a comma-separated list of thread ids
+@item m @var{thread-id}
+A single thread ID
+@item m @var{thread-id},@var{thread-id}@dots{}
+a comma-separated list of thread IDs
@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.
+more thread IDs, separated by commas.
@value{GDBN} will respond to each reply with a request for more thread
ids (using the @samp{qs} form of the query), until the target responds
-with @samp{l} (lower-case el, for @dfn{last}).
+with @samp{l} (lower-case el, for @dfn{last}).
+Refer to @ref{thread-id syntax}, for the format of the @var{thread-id}
+fields.
@item qGetTLSAddr:@var{thread-id},@var{offset},@var{lm}
@cindex get thread-local storage address, remote request
Fetch the address associated with thread local storage specified
by @var{thread-id}, @var{offset}, and @var{lm}.
-@var{thread-id} is the (big endian, hex encoded) thread id associated with the
-thread for which to fetch the TLS address.
+@var{thread-id} is the thread ID associated with the
+thread for which to fetch the TLS address. @xref{thread-id syntax}.
@var{offset} is the (big endian, hex encoded) offset associated with the
thread local variable. (This offset is obtained from the debug
kept at fixed offsets relative to the last relocated segment.
@end table
-@item qP @var{mode} @var{threadid}
+@item qP @var{mode} @var{thread-id}
@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.
+Returns information on @var{thread-id}. Where: @var{mode} is a hex
+encoded 32 bit mode; @var{thread-id} is a thread ID
+(@pxref{thread-id syntax}).
Don't use this packet; use the @samp{qThreadExtraInfo} query instead
(see below).
Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
+@item QNonStop:1
+@item QNonStop:0
+@cindex non-stop mode, remote request
+@cindex @samp{QNonStop} packet
+@anchor{QNonStop}
+Enter non-stop (@samp{QNonStop:1}) or all-stop (@samp{QNonStop:0}) mode.
+@xref{Remote Non-Stop}, for more information.
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+
+@item E @var{nn}
+An error occurred. @var{nn} are hex digits.
+
+@item
+An empty reply indicates that @samp{QNonStop} is not supported by
+the stub.
+@end table
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+Use of this packet is controlled by the @code{set non-stop} command;
+@pxref{Non-Stop Mode}.
+
@item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{}
@cindex pass signals to inferior, remote request
@cindex @samp{QPassSignals} packet
conventions above. Please don't use this packet as a model for new
packets.)
+@item qSearch:memory:@var{address};@var{length};@var{search-pattern}
+@cindex searching memory, in remote debugging
+@cindex @samp{qSearch:memory} packet
+@anchor{qSearch memory}
+Search @var{length} bytes at @var{address} for @var{search-pattern}.
+@var{address} and @var{length} are encoded in hex.
+@var{search-pattern} is a sequence of bytes, hex encoded.
+
+Reply:
+@table @samp
+@item 0
+The pattern was not found.
+@item 1,address
+The pattern was found at @var{address}.
+@item E @var{NN}
+A badly formed request or an error was encountered while searching memory.
+@item
+An empty reply indicates that @samp{qSearch:memory} is not recognized.
+@end table
+
+@item QStartNoAckMode
+@cindex @samp{QStartNoAckMode} packet
+@anchor{QStartNoAckMode}
+Request that the remote stub disable the normal @samp{+}/@samp{-}
+protocol acknowledgments (@pxref{Packet Acknowledgment}).
+
+Reply:
+@table @samp
+@item OK
+The stub has switched to no-acknowledgment mode.
+@value{GDBN} acknowledges this reponse,
+but neither the stub nor @value{GDBN} shall send or expect further
+@samp{+}/@samp{-} acknowledgments in the current connection.
+@item
+An empty reply indicates that the stub does not support no-acknowledgment mode.
+@end table
+
@item qSupported @r{[}:@var{gdbfeature} @r{[};@var{gdbfeature}@r{]}@dots{} @r{]}
@cindex supported packets, remote query
@cindex features of the remote protocol
state, even if the stub had previously been communicating with
a different version of @value{GDBN}.
-No values of @var{gdbfeature} (for the packet sent by @value{GDBN})
-are defined yet. Stubs should ignore any unknown values for
+The following values of @var{gdbfeature} (for the packet sent by @value{GDBN})
+are defined:
+
+@table @samp
+@item multiprocess
+This feature indicates whether @value{GDBN} supports multiprocess
+extensions to the remote protocol. @value{GDBN} does not use such
+extensions unless the stub also reports that it supports them by
+including @samp{multiprocess+} in its @samp{qSupported} reply.
+@xref{multiprocess extensions}, for details.
+@end table
+
+Stubs should ignore any unknown values for
@var{gdbfeature}. Any @value{GDBN} which sends a @samp{qSupported}
packet supports receiving packets of unlimited length (earlier
-versions of @value{GDBN} may reject overly long responses). Values
+versions of @value{GDBN} may reject overly long responses). Additional values
for @var{gdbfeature} may be defined in the future to let the stub take
advantage of new features in @value{GDBN}, e.g.@: incompatible
-improvements in the remote protocol---support for unlimited length
-responses would be a @var{gdbfeature} example, if it were not implied by
-the @samp{qSupported} query. The stub's reply should be independent
+improvements in the remote protocol---the @samp{multiprocess} feature is
+an example of such a feature. The stub's reply should be independent
of the @var{gdbfeature} entries sent by @value{GDBN}; first @value{GDBN}
describes all the features it supports, and then the stub replies with
all the features it supports.
@tab @samp{-}
@tab Yes
+@item @samp{QNonStop}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{QPassSignals}
@tab No
@tab @samp{-}
@tab Yes
+@item @samp{QStartNoAckMode}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@item @samp{multiprocess}
+@tab No
+@tab @samp{-}
+@tab No
+
@end multitable
These are the currently defined stub features, in more detail:
The remote stub understands the @samp{qXfer:spu:write} packet
(@pxref{qXfer spu write}).
+@item QNonStop
+The remote stub understands the @samp{QNonStop} packet
+(@pxref{QNonStop}).
+
@item QPassSignals
The remote stub understands the @samp{QPassSignals} packet
(@pxref{QPassSignals}).
+@item QStartNoAckMode
+The remote stub understands the @samp{QStartNoAckMode} packet and
+prefers to operate in no-acknowledgment mode. @xref{Packet Acknowledgment}.
+
+@item multiprocess
+@anchor{multiprocess extensions}
+@cindex multiprocess extensions, in remote protocol
+The remote stub understands the multiprocess extensions to the remote
+protocol syntax. The multiprocess extensions affect the syntax of
+thread IDs in both packets and replies (@pxref{thread-id syntax}), and
+add process IDs to the @samp{D} packet and @samp{W} and @samp{X}
+replies. Note that reporting this feature indicates support for the
+syntactic extensions only, not that the stub necessarily supports
+debugging of more than one process at a time. The stub must not use
+multiprocess extensions in packet replies unless @value{GDBN} has also
+indicated it supports them in its @samp{qSupported} request.
+
+@item qXfer:osdata:read
+The remote stub understands the @samp{qXfer:osdata:read} packet
+((@pxref{qXfer osdata read}).
+
@end table
@item qSymbol::
@itemx QTFrame
@xref{Tracepoint Packets}.
-@item qThreadExtraInfo,@var{id}
+@item qThreadExtraInfo,@var{thread-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
+the target OS. @var{thread-id} is a thread ID;
+see @ref{thread-id syntax}. 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
in that context to be accessed.
This packet is not probed by default; the remote stub must request it,
-by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}).
+
+@item qXfer:osdata:read::@var{offset},@var{length}
+@anchor{qXfer osdata read}
+Access the target's @dfn{operating system information}.
+@xref{Operating System Information}.
+
@end table
Reply:
formats, listed below.
@table @samp
-@item qXfer:@var{spu}:write:@var{annex}:@var{offset}:@var{data}@dots{}
+@item qXfer:spu:write:@var{annex}:@var{offset}:@var{data}@dots{}
@anchor{qXfer spu write}
Write @var{data} to an @code{spufs} file on the target system. The
annex specifies which file to write; it must be of the form
@end table
+@node Host I/O Packets
+@section Host I/O Packets
+@cindex Host I/O, remote protocol
+@cindex file transfer, remote protocol
+
+The @dfn{Host I/O} packets allow @value{GDBN} to perform I/O
+operations on the far side of a remote link. For example, Host I/O is
+used to upload and download files to a remote target with its own
+filesystem. Host I/O uses the same constant values and data structure
+layout as the target-initiated File-I/O protocol. However, the
+Host I/O packets are structured differently. The target-initiated
+protocol relies on target memory to store parameters and buffers.
+Host I/O requests are initiated by @value{GDBN}, and the
+target's memory is not involved. @xref{File-I/O Remote Protocol
+Extension}, for more details on the target-initiated protocol.
+
+The Host I/O request packets all encode a single operation along with
+its arguments. They have this format:
+
+@table @samp
+
+@item vFile:@var{operation}: @var{parameter}@dots{}
+@var{operation} is the name of the particular request; the target
+should compare the entire packet name up to the second colon when checking
+for a supported operation. The format of @var{parameter} depends on
+the operation. Numbers are always passed in hexadecimal. Negative
+numbers have an explicit minus sign (i.e.@: two's complement is not
+used). Strings (e.g.@: filenames) are encoded as a series of
+hexadecimal bytes. The last argument to a system call may be a
+buffer of escaped binary data (@pxref{Binary Data}).
+
+@end table
+
+The valid responses to Host I/O packets are:
+
+@table @samp
+
+@item F @var{result} [, @var{errno}] [; @var{attachment}]
+@var{result} is the integer value returned by this operation, usually
+non-negative for success and -1 for errors. If an error has occured,
+@var{errno} will be included in the result. @var{errno} will have a
+value defined by the File-I/O protocol (@pxref{Errno Values}). For
+operations which return data, @var{attachment} supplies the data as a
+binary buffer. Binary buffers in response packets are escaped in the
+normal way (@pxref{Binary Data}). See the individual packet
+documentation for the interpretation of @var{result} and
+@var{attachment}.
+
+@item
+An empty response indicates that this operation is not recognized.
+
+@end table
+
+These are the supported Host I/O operations:
+
+@table @samp
+@item vFile:open: @var{pathname}, @var{flags}, @var{mode}
+Open a file at @var{pathname} and return a file descriptor for it, or
+return -1 if an error occurs. @var{pathname} is a string,
+@var{flags} is an integer indicating a mask of open flags
+(@pxref{Open Flags}), and @var{mode} is an integer indicating a mask
+of mode bits to use if the file is created (@pxref{mode_t Values}).
+@xref{open}, for details of the open flags and mode values.
+
+@item vFile:close: @var{fd}
+Close the open file corresponding to @var{fd} and return 0, or
+-1 if an error occurs.
+
+@item vFile:pread: @var{fd}, @var{count}, @var{offset}
+Read data from the open file corresponding to @var{fd}. Up to
+@var{count} bytes will be read from the file, starting at @var{offset}
+relative to the start of the file. The target may read fewer bytes;
+common reasons include packet size limits and an end-of-file
+condition. The number of bytes read is returned. Zero should only be
+returned for a successful read at the end of the file, or if
+@var{count} was zero.
+
+The data read should be returned as a binary attachment on success.
+If zero bytes were read, the response should include an empty binary
+attachment (i.e.@: a trailing semicolon). The return value is the
+number of target bytes read; the binary attachment may be longer if
+some characters were escaped.
+
+@item vFile:pwrite: @var{fd}, @var{offset}, @var{data}
+Write @var{data} (a binary buffer) to the open file corresponding
+to @var{fd}. Start the write at @var{offset} from the start of the
+file. Unlike many @code{write} system calls, there is no
+separate @var{count} argument; the length of @var{data} in the
+packet is used. @samp{vFile:write} returns the number of bytes written,
+which may be shorter than the length of @var{data}, or -1 if an
+error occurred.
+
+@item vFile:unlink: @var{pathname}
+Delete the file at @var{pathname} on the target. Return 0,
+or -1 if an error occurs. @var{pathname} is a string.
+
+@end table
+
@node Interrupts
@section Interrupts
@cindex interrupts (remote protocol)
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.
+mechanism and may, in fact, be undefined. @value{GDBN} does not
+currently define a @code{BREAK} mechanism for any of the network
+interfaces except for TCP, in which case @value{GDBN} sends the
+@code{telnet} BREAK sequence.
@samp{Ctrl-C}, on the other hand, is defined and implemented for all
transport mechanisms. It is represented by sending the single byte
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.
+implementation defined. If the target supports debugging of multiple
+threads and/or processes, it should attempt to interrupt all
+currently-executing threads and processes.
+If the stub is successful at interrupting the
+running program, it should send one of the stop
+reply packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result
+of successfully stopping the program in all-stop mode, and a stop reply
+for each stopped thread in non-stop mode.
+Interrupts received while the
+program is stopped are discarded.
+
+@node Notification Packets
+@section Notification Packets
+@cindex notification packets
+@cindex packets, notification
+
+The @value{GDBN} remote serial protocol includes @dfn{notifications},
+packets that require no acknowledgment. Both the GDB and the stub
+may send notifications (although the only notifications defined at
+present are sent by the stub). Notifications carry information
+without incurring the round-trip latency of an acknowledgment, and so
+are useful for low-impact communications where occasional packet loss
+is not a problem.
+
+A notification packet has the form @samp{% @var{data} #
+@var{checksum}}, where @var{data} is the content of the notification,
+and @var{checksum} is a checksum of @var{data}, computed and formatted
+as for ordinary @value{GDBN} packets. A notification's @var{data}
+never contains @samp{$}, @samp{%} or @samp{#} characters. Upon
+receiving a notification, the recipient sends no @samp{+} or @samp{-}
+to acknowledge the notification's receipt or to report its corruption.
+
+Every notification's @var{data} begins with a name, which contains no
+colon characters, followed by a colon character.
+
+Recipients should silently ignore corrupted notifications and
+notifications they do not understand. Recipients should restart
+timeout periods on receipt of a well-formed notification, whether or
+not they understand it.
+
+Senders should only send the notifications described here when this
+protocol description specifies that they are permitted. In the
+future, we may extend the protocol to permit existing notifications in
+new contexts; this rule helps older senders avoid confusing newer
+recipients.
+
+(Older versions of @value{GDBN} ignore bytes received until they see
+the @samp{$} byte that begins an ordinary packet, so new stubs may
+transmit notifications without fear of confusing older clients. There
+are no notifications defined for @value{GDBN} to send at the moment, but we
+assume that most older stubs would ignore them, as well.)
+
+The following notification packets from the stub to @value{GDBN} are
+defined:
+
+@table @samp
+@item Stop: @var{reply}
+Report an asynchronous stop event in non-stop mode.
+The @var{reply} has the form of a stop reply, as
+described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop},
+for information on how these notifications are acknowledged by
+@value{GDBN}.
+@end table
+
+@node Remote Non-Stop
+@section Remote Protocol Support for Non-Stop Mode
+
+@value{GDBN}'s remote protocol supports non-stop debugging of
+multi-threaded programs, as described in @ref{Non-Stop Mode}. If the stub
+supports non-stop mode, it should report that to @value{GDBN} by including
+@samp{QNonStop+} in its @samp{qSupported} response (@pxref{qSupported}).
+
+@value{GDBN} typically sends a @samp{QNonStop} packet only when
+establishing a new connection with the stub. Entering non-stop mode
+does not alter the state of any currently-running threads, but targets
+must stop all threads in any already-attached processes when entering
+all-stop mode. @value{GDBN} uses the @samp{?} packet as necessary to
+probe the target state after a mode change.
+
+In non-stop mode, when an attached process encounters an event that
+would otherwise be reported with a stop reply, it uses the
+asynchronous notification mechanism (@pxref{Notification Packets}) to
+inform @value{GDBN}. In contrast to all-stop mode, where all threads
+in all processes are stopped when a stop reply is sent, in non-stop
+mode only the thread reporting the stop event is stopped. That is,
+when reporting a @samp{S} or @samp{T} response to indicate completion
+of a step operation, hitting a breakpoint, or a fault, only the
+affected thread is stopped; any other still-running threads continue
+to run. When reporting a @samp{W} or @samp{X} response, all running
+threads belonging to other attached processes continue to run.
+
+Only one stop reply notification at a time may be pending; if
+additional stop events occur before @value{GDBN} has acknowledged the
+previous notification, they must be queued by the stub for later
+synchronous transmission in response to @samp{vStopped} packets from
+@value{GDBN}. Because the notification mechanism is unreliable,
+the stub is permitted to resend a stop reply notification
+if it believes @value{GDBN} may not have received it. @value{GDBN}
+ignores additional stop reply notifications received before it has
+finished processing a previous notification and the stub has completed
+sending any queued stop events.
+
+Otherwise, @value{GDBN} must be prepared to receive a stop reply
+notification at any time. Specifically, they may appear when
+@value{GDBN} is not otherwise reading input from the stub, or when
+@value{GDBN} is expecting to read a normal synchronous response or a
+@samp{+}/@samp{-} acknowledgment to a packet it has sent.
+Notification packets are distinct from any other communication from
+the stub so there is no ambiguity.
+
+After receiving a stop reply notification, @value{GDBN} shall
+acknowledge it by sending a @samp{vStopped} packet (@pxref{vStopped packet})
+as a regular, synchronous request to the stub. Such acknowledgment
+is not required to happen immediately, as @value{GDBN} is permitted to
+send other, unrelated packets to the stub first, which the stub should
+process normally.
+
+Upon receiving a @samp{vStopped} packet, if the stub has other queued
+stop events to report to @value{GDBN}, it shall respond by sending a
+normal stop reply response. @value{GDBN} shall then send another
+@samp{vStopped} packet to solicit further responses; again, it is
+permitted to send other, unrelated packets as well which the stub
+should process normally.
+
+If the stub receives a @samp{vStopped} packet and there are no
+additional stop events to report, the stub shall return an @samp{OK}
+response. At this point, if further stop events occur, the stub shall
+send a new stop reply notification, @value{GDBN} shall accept the
+notification, and the process shall be repeated.
+
+In non-stop mode, the target shall respond to the @samp{?} packet as
+follows. First, any incomplete stop reply notification/@samp{vStopped}
+sequence in progress is abandoned. The target must begin a new
+sequence reporting stop events for all stopped threads, whether or not
+it has previously reported those events to @value{GDBN}. The first
+stop reply is sent as a synchronous reply to the @samp{?} packet, and
+subsequent stop replies are sent as responses to @samp{vStopped} packets
+using the mechanism described above. The target must not send
+asynchronous stop reply notifications until the sequence is complete.
+If all threads are running when the target receives the @samp{?} packet,
+or if the target is not attached to any process, it shall respond
+@samp{OK}.
+
+@node Packet Acknowledgment
+@section Packet Acknowledgment
+
+@cindex acknowledgment, for @value{GDBN} remote
+@cindex packet acknowledgment, for @value{GDBN} remote
+By default, when either the host or the target machine receives a packet,
+the first response expected is an acknowledgment: either @samp{+} (to indicate
+the package was received correctly) or @samp{-} (to request retransmission).
+This mechanism allows the @value{GDBN} remote protocol to operate over
+unreliable transport mechanisms, such as a serial line.
+
+In cases where the transport mechanism is itself reliable (such as a pipe or
+TCP connection), the @samp{+}/@samp{-} acknowledgments are redundant.
+It may be desirable to disable them in that case to reduce communication
+overhead, or for other reasons. This can be accomplished by means of the
+@samp{QStartNoAckMode} packet; @pxref{QStartNoAckMode}.
+
+When in no-acknowledgment mode, neither the stub nor @value{GDBN} shall send or
+expect @samp{+}/@samp{-} protocol acknowledgments. The packet
+and response format still includes the normal checksum, as described in
+@ref{Overview}, but the checksum may be ignored by the receiver.
+
+If the stub supports @samp{QStartNoAckMode} and prefers to operate in
+no-acknowledgment mode, it should report that to @value{GDBN}
+by including @samp{QStartNoAckMode+} in its response to @samp{qSupported};
+@pxref{qSupported}.
+If @value{GDBN} also supports @samp{QStartNoAckMode} and it has not been
+disabled via the @code{set remote noack-packet off} command
+(@pxref{Remote Configuration}),
+@value{GDBN} may then send a @samp{QStartNoAckMode} packet to the stub.
+Only then may the stub actually turn off packet acknowledgments.
+@value{GDBN} sends a final @samp{+} acknowledgment of the stub's @samp{OK}
+response, which can be safely ignored by the stub.
+
+Note that @code{set remote noack-packet} command only affects negotiation
+between @value{GDBN} and the stub when subsequent connections are made;
+it does not affect the protocol acknowledgment state for any current
+connection.
+Since @samp{+}/@samp{-} acknowledgments are enabled by default when a
+new connection is established,
+there is also no protocol request to re-enable the acknowledgments
+for the current connection, once disabled.
@node Examples
@section Examples
named pipes, sockets or any other communication method on the host
system are not supported by this protocol.
+File I/O is not supported in non-stop mode.
+
@node Protocol Basics
@subsection Protocol Basics
@cindex protocol basics, file-i/o
The @samp{qXfer:libraries:read} packet returns an XML document which
lists loaded libraries and their offsets. Each library has an
-associated name and one or more segment base addresses, which report
-where the library was loaded in memory. The segment bases are start
-addresses, not relocation offsets; they do not depend on the library's
-link-time base addresses.
+associated name and one or more segment or section base addresses,
+which report where the library was loaded in memory.
+
+For the common case of libraries that are fully linked binaries, the
+library should have a list of segments. If the target supports
+dynamic linking of a relocatable object file, its library XML element
+should instead include a list of allocated sections. The segment or
+section bases are start addresses, not relocation offsets; they do not
+depend on the library's link-time base addresses.
+
+@value{GDBN} must be linked with the Expat library to support XML
+library lists. @xref{Expat}.
A simple memory map, with one loaded library relocated by a single
offset, looks like this:
</library-list>
@end smallexample
+Another simple memory map, with one loaded library with three
+allocated sections (.text, .data, .bss), looks like this:
+
+@smallexample
+<library-list>
+ <library name="sharedlib.o">
+ <section address="0x10000000"/>
+ <section address="0x20000000"/>
+ <section address="0x30000000"/>
+ </library>
+</library-list>
+@end smallexample
+
The format of a library list is described by this DTD:
@smallexample
<!-- library-list: Root element with versioning -->
<!ELEMENT library-list (library)*>
<!ATTLIST library-list version CDATA #FIXED "1.0">
-<!ELEMENT library (segment)*>
+<!ELEMENT library (segment*, section*)>
<!ATTLIST library name CDATA #REQUIRED>
<!ELEMENT segment EMPTY>
<!ATTLIST segment address CDATA #REQUIRED>
+<!ELEMENT section EMPTY>
+<!ATTLIST section address CDATA #REQUIRED>
@end smallexample
+In addition, segments and section descriptors cannot be mixed within a
+single library element, and you must supply at least one segment or
+section for each library.
+
@node Memory Map Format
@section Memory Map Format
@cindex memory map format
The memory map is obtained using the @samp{qXfer:memory-map:read}
(@pxref{qXfer memory map read}) packet and is an XML document that
-lists memory regions. The top-level structure of the document is shown below:
+lists memory regions.
+
+@value{GDBN} must be linked with the Expat library to support XML
+memory maps. @xref{Expat}.
+
+The top-level structure of the document is shown below:
@smallexample
<?xml version="1.0"?>
processor variants it has never seen before --- to the extent that the
descriptions are accurate, and that @value{GDBN} understands them.
-@value{GDBN} must be compiled with Expat support to support XML target
-descriptions. @xref{Expat}.
+@value{GDBN} must be linked with the Expat library to support XML
+target descriptions. @xref{Expat}.
@menu
* Retrieving Descriptions:: How descriptions are fetched from a target.
@itemx int16
@itemx int32
@itemx int64
+@itemx int128
Signed integer types holding the specified number of bits.
@item uint8
@itemx uint16
@itemx uint32
@itemx uint64
+@itemx uint128
Unsigned integer types holding the specified number of bits.
@item code_ptr
@menu
* ARM Features::
+* MIPS Features::
* M68K Features::
+* PowerPC Features::
@end menu
@samp{wCGR0} through @samp{wCGR3}. The @samp{wCID}, @samp{wCon},
@samp{wCSSF}, and @samp{wCASF} registers are optional.
+@node MIPS Features
@subsection MIPS Features
@cindex target descriptions, MIPS features
@itemx @samp{org.gnu.gdb.coldfire.core}
@itemx @samp{org.gnu.gdb.fido.core}
One of those features must be always present.
-The feature that is present determines which flavor of m86k is
+The feature that is present determines which flavor of m68k is
used. The feature that is present should contain registers
@samp{d0} through @samp{d7}, @samp{a0} through @samp{a5}, @samp{fp},
@samp{sp}, @samp{ps} and @samp{pc}.
@samp{fpiaddr}.
@end table
+@node PowerPC Features
+@subsection PowerPC Features
+@cindex target descriptions, PowerPC features
+
+The @samp{org.gnu.gdb.power.core} feature is required for PowerPC
+targets. It should contain registers @samp{r0} through @samp{r31},
+@samp{pc}, @samp{msr}, @samp{cr}, @samp{lr}, @samp{ctr}, and
+@samp{xer}. They may be 32-bit or 64-bit depending on the target.
+
+The @samp{org.gnu.gdb.power.fpu} feature is optional. It should
+contain registers @samp{f0} through @samp{f31} and @samp{fpscr}.
+
+The @samp{org.gnu.gdb.power.altivec} feature is optional. It should
+contain registers @samp{vr0} through @samp{vr31}, @samp{vscr},
+and @samp{vrsave}.
+
+The @samp{org.gnu.gdb.power.vsx} feature is optional. It should
+contain registers @samp{vs0h} through @samp{vs31h}. @value{GDBN}
+will combine these registers with the floating point registers
+(@samp{f0} through @samp{f31}) and the altivec registers (@samp{vr0}
+through @samp{vr31}) to present the 128-bit wide registers @samp{vs0}
+through @samp{vs63}, the set of vector registers for POWER7.
+
+The @samp{org.gnu.gdb.power.spe} feature is optional. It should
+contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and
+@samp{spefscr}. SPE targets should provide 32-bit registers in
+@samp{org.gnu.gdb.power.core} and provide the upper halves in
+@samp{ev0h} through @samp{ev31h}. @value{GDBN} will combine
+these to present registers @samp{ev0} through @samp{ev31} to the
+user.
+
+@node Operating System Information
+@appendix Operating System Information
+@cindex operating system information
+
+@menu
+* Process list::
+@end menu
+
+Users of @value{GDBN} often wish to obtain information about the state of
+the operating system running on the target---for example the list of
+processes, or the list of open files. This section describes the
+mechanism that makes it possible. This mechanism is similar to the
+target features mechanism (@pxref{Target Descriptions}), but focuses
+on a different aspect of target.
+
+Operating system information is retrived from the target via the
+remote protocol, using @samp{qXfer} requests (@pxref{qXfer osdata
+read}). The object name in the request should be @samp{osdata}, and
+the @var{annex} identifies the data to be fetched.
+
+@node Process list
+@appendixsection Process list
+@cindex operating system information, process list
+
+When requesting the process list, the @var{annex} field in the
+@samp{qXfer} request should be @samp{processes}. The returned data is
+an XML document. The formal syntax of this document is defined in
+@file{gdb/features/osdata.dtd}.
+
+An example document is:
+
+@smallexample
+<?xml version="1.0"?>
+<!DOCTYPE target SYSTEM "osdata.dtd">
+<osdata type="processes">
+ <item>
+ <column name="pid">1</column>
+ <column name="user">root</column>
+ <column name="command">/sbin/init</column>
+ </item>
+</osdata>
+@end smallexample
+
+Each item should include a column whose name is @samp{pid}. The value
+of that column should identify the process on the target. The
+@samp{user} and @samp{command} columns are optional, and will be
+displayed by @value{GDBN}. Target may provide additional columns,
+which @value{GDBN} currently ignores.
+
@include gpl.texi
@raisesections
projects / deliverable / binutils-gdb.git / blobdiff