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.''
+(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 ifinfo
@titlepage
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.''
+(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.''
+@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
+software in general. We will miss him.
@end titlepage
@page
Copyright (C) 1988-2006 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
+software in general. We will miss him.
+
@menu
* Summary:: Summary of @value{GDBN}
* Sample Session:: A sample @value{GDBN} session
@end itemize
You can use @value{GDBN} to debug programs written in C and C@t{++}.
-For more information, see @ref{Supported languages,,Supported languages}.
+For more information, see @ref{Supported Languages,,Supported Languages}.
For more information, see @ref{C,,C and C++}.
@cindex Modula-2
@end menu
@node Free Software
-@unnumberedsec Free software
+@unnumberedsec Free Software
@value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
General Public License
frame IDs, independent frame sniffers, and the sentinel frame. Mark
Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the
libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and
-trad unwinders. The architecture specific changes, each involving a
+trad unwinders. The architecture-specific changes, each involving a
complete rewrite of the architecture's frame code, were carried out by
Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane
Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel
* Invoking GDB:: How to start @value{GDBN}
* Quitting GDB:: How to quit @value{GDBN}
* Shell Commands:: How to use shell commands inside @value{GDBN}
-* Logging output:: How to log @value{GDBN}'s output to a file
+* Logging Output:: How to log @value{GDBN}'s output to a file
@end menu
@node Invoking GDB
@end menu
@node File Options
-@subsection Choosing files
+@subsection Choosing Files
When @value{GDBN} starts, it reads any arguments other than options as
specifying an executable file and core file (or process ID). This is
@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}
@end table
@node Mode Options
-@subsection Choosing modes
+@subsection Choosing Modes
You can run @value{GDBN} in various alternative modes---for example, in
batch mode or quiet mode.
Do not execute commands found in any initialization files. Normally,
@value{GDBN} executes the commands in these files after all the command
options and arguments have been processed. @xref{Command Files,,Command
-files}.
+Files}.
@item -quiet
@itemx -silent
source, assembly, registers and @value{GDBN} command outputs
(@pxref{TUI, ,@value{GDBN} Text User Interface}). Alternatively, the
Text User Interface can be enabled by invoking the program
-@samp{gdbtui}. Do not use this option if you run @value{GDBN} from
+@samp{@value{GDBTUI}}. Do not use this option if you run @value{GDBN} from
Emacs (@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}).
@c @item -xdb
@end table
@node Startup
-@subsection What @value{GDBN} does during startup
+@subsection What @value{GDBN} Does During Startup
@cindex @value{GDBN} startup
Here's the description of what @value{GDBN} does during session startup:
file in your home directory can set options (such as @samp{set
complaints}) that affect subsequent processing of command line options
and operands. Init files are not executed if you use the @samp{-nx}
-option (@pxref{Mode Options, ,Choosing modes}).
+option (@pxref{Mode Options, ,Choosing Modes}).
@cindex init file name
@cindex @file{.gdbinit}
If you have been using @value{GDBN} to control an attached process or
device, you can release it with the @code{detach} command
-(@pxref{Attach, ,Debugging an already-running process}).
+(@pxref{Attach, ,Debugging an Already-running Process}).
@node Shell Commands
-@section Shell commands
+@section Shell Commands
If you need to execute occasional shell commands during your
debugging session, there is no need to leave or suspend @value{GDBN}; you can
arguments. This is equivalent to @samp{shell make @var{make-args}}.
@end table
-@node Logging output
-@section Logging output
+@node Logging Output
+@section Logging Output
@cindex logging @value{GDBN} output
@cindex save @value{GDBN} output to a file
@end menu
@node Command Syntax
-@section Command syntax
+@section Command Syntax
A @value{GDBN} command is a single line of input. There is no limit on
how long it can be. It starts with a command name, which is followed by
@value{GDBN} can also use @key{RET} in another way: to partition lengthy
output, in a way similar to the common utility @code{more}
-(@pxref{Screen Size,,Screen size}). Since it is easy to press one
+(@pxref{Screen Size,,Screen Size}). Since it is easy to press one
@key{RET} too many in this situation, @value{GDBN} disables command
repetition after any command that generates this sort of display.
@cindex comment
Any text from a @kbd{#} to the end of the line is a comment; it does
nothing. This is useful mainly in command files (@pxref{Command
-Files,,Command files}).
+Files,,Command Files}).
@cindex repeating command sequences
@kindex Ctrl-o @r{(operate-and-get-next)}
for editing.
@node Completion
-@section Command completion
+@section Command Completion
@cindex completion
@cindex word completion
you have not yet started typing the argument list when you ask for
completion on an overloaded symbol.
-For more information about overloaded functions, see @ref{C plus plus
-expressions, ,C@t{++} expressions}. You can use the command @code{set
+For more information about overloaded functions, see @ref{C Plus Plus
+Expressions, ,C@t{++} Expressions}. You can use the command @code{set
overload-resolution off} to disable overload resolution;
-see @ref{Debugging C plus plus, ,@value{GDBN} features for C@t{++}}.
+see @ref{Debugging C Plus Plus, ,@value{GDBN} Features for C@t{++}}.
@node Help
-@section Getting help
+@section Getting Help
@cindex online documentation
@kindex 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
@end menu
@node Compilation
-@section Compiling for debugging
+@section Compiling for Debugging
In order to debug a program effectively, you need to generate
debugging information when you compile it. This debugging information
@need 2000
@node Starting
-@section Starting your program
+@section Starting your Program
@cindex starting
@cindex running
You must first specify the program name (except on VxWorks) with an
argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of
@value{GDBN}}), or by using the @code{file} or @code{exec-file} command
-(@pxref{Files, ,Commands to specify files}).
+(@pxref{Files, ,Commands to Specify Files}).
@end table
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
the arguments.
In Unix systems, you can control which shell is used with the
@code{SHELL} environment variable.
-@xref{Arguments, ,Your program's arguments}.
+@xref{Arguments, ,Your Program's Arguments}.
@item The @emph{environment.}
Your program normally inherits its environment from @value{GDBN}, but you can
use the @value{GDBN} commands @code{set environment} and @code{unset
environment} to change parts of the environment that affect
-your program. @xref{Environment, ,Your program's environment}.
+your program. @xref{Environment, ,Your Program's Environment}.
@item The @emph{working directory.}
Your program inherits its working directory from @value{GDBN}. You can set
the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}.
-@xref{Working Directory, ,Your program's working directory}.
+@xref{Working Directory, ,Your Program's Working Directory}.
@item The @emph{standard input and output.}
Your program normally uses the same device for standard input and
standard output as @value{GDBN} is using. You can redirect input and output
in the @code{run} command line, or you can use the @code{tty} command to
set a different device for your program.
-@xref{Input/Output, ,Your program's input and output}.
+@xref{Input/Output, ,Your Program's Input and Output}.
@cindex pipes
@emph{Warning:} While input and output redirection work, you cannot use
@end table
When you issue the @code{run} command, your program begins to execute
-immediately. @xref{Stopping, ,Stopping and continuing}, for discussion
+immediately. @xref{Stopping, ,Stopping and Continuing}, for discussion
of how to arrange for your program to stop. Once your program has
stopped, you may call functions in your program, using the @code{print}
or @code{call} commands. @xref{Data, ,Examining Data}.
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.
+
@end table
@node Arguments
-@section Your program's arguments
+@section Your Program's Arguments
@cindex arguments (to your program)
The arguments to your program can be specified by the arguments of the
@end table
@node Environment
-@section Your program's environment
+@section Your Program's Environment
@cindex environment (of your program)
The @dfn{environment} consists of a set of environment variables and
@file{.profile}.
@node Working Directory
-@section Your program's working directory
+@section Your Program's Working Directory
@cindex working directory (of your program)
Each time you start your program with @code{run}, it inherits its
The @value{GDBN} working directory also serves as a default for the commands
that specify files for @value{GDBN} to operate on. @xref{Files, ,Commands to
-specify files}.
+Specify Files}.
@table @code
@kindex cd
current working directory of the debuggee.
@node Input/Output
-@section Your program's input and output
+@section Your Program's Input and Output
@cindex redirection
@cindex i/o
@end table
@node Attach
-@section Debugging an already-running process
+@section Debugging an Already-running Process
@kindex attach
@cindex attach
When you use @code{attach}, the debugger finds the program running in
the process first by looking in the current working directory, then (if
the program is not found) by using the source file search path
-(@pxref{Source Path, ,Specifying source directories}). You can also use
+(@pxref{Source Path, ,Specifying Source Directories}). You can also use
the @code{file} command to load the program. @xref{Files, ,Commands to
Specify Files}.
executing the command.
@end table
-If you exit @value{GDBN} or use the @code{run} command while you have an
-attached process, you kill that process. By default, @value{GDBN} asks
-for confirmation if you try to do either of these things; you can
-control whether or not you need to confirm by using the @code{set
-confirm} command (@pxref{Messages/Warnings, ,Optional warnings and
-messages}).
+If you exit @value{GDBN} while you have an attached process, you detach
+that process. If you use the @code{run} command, you kill that process.
+By default, @value{GDBN} asks for confirmation if you try to do either of these
+things; you can control whether or not you need to confirm by using the
+@code{set confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and
+Messages}).
@node Kill Process
-@section Killing the child process
+@section Killing the Child Process
@table @code
@kindex kill
breakpoint settings).
@node Threads
-@section Debugging programs with multiple threads
+@section Debugging Programs with Multiple Threads
@cindex threads of execution
@cindex 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}}.
+
+@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
@cindex automatic thread selection
message of the form @samp{[Switching to @var{systag}]} to identify the
thread.
-@xref{Thread Stops,,Stopping and starting multi-thread programs}, for
+@xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for
more information about how @value{GDBN} behaves when you stop and start
programs with multiple threads.
-@xref{Set Watchpoints,,Setting watchpoints}, for information about
+@xref{Set Watchpoints,,Setting Watchpoints}, for information about
watchpoints in programs with multiple threads.
@node Processes
-@section Debugging programs with multiple processes
+@section Debugging Programs with Multiple Processes
@cindex fork, debugging programs which call
@cindex multiple processes
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
You can use the @code{catch} command to make @value{GDBN} stop whenever
a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
-Catchpoints, ,Setting catchpoints}.
+Catchpoints, ,Setting Catchpoints}.
@node Checkpoint/Restart
-@section Setting a @emph{bookmark} to return to later
+@section Setting a @emph{Bookmark} to Return to Later
@cindex checkpoint
@cindex restart
If your program has saved a local copy of its process id, this could
potentially pose a problem.
-@subsection A non-obvious benefit of using checkpoints
+@subsection A Non-obvious Benefit of Using Checkpoints
On some systems such as @sc{gnu}/Linux, address space randomization
is performed on new processes for security reasons. This makes it
@end menu
@node Breakpoints
-@section Breakpoints, watchpoints, and catchpoints
+@section Breakpoints, Watchpoints, and Catchpoints
@cindex breakpoints
A @dfn{breakpoint} makes your program stop whenever a certain point in
the program is reached. For each breakpoint, you can add conditions to
control in finer detail whether your program stops. You can set
breakpoints with the @code{break} command and its variants (@pxref{Set
-Breaks, ,Setting breakpoints}), to specify the place where your program
+Breaks, ,Setting Breakpoints}), to specify the place where your program
should stop by line number, function name or exact address in the
program.
of a variable, or it could involve values of one or more variables
combined by operators, such as @samp{a + b}. This is sometimes called
@dfn{data breakpoints}. You must use a different command to set
-watchpoints (@pxref{Set Watchpoints, ,Setting watchpoints}), but aside
+watchpoints (@pxref{Set Watchpoints, ,Setting Watchpoints}), but aside
from that, you can manage a watchpoint like any other breakpoint: you
enable, disable, and delete both breakpoints and watchpoints using the
same commands.
You can arrange to have values from your program displayed automatically
whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,,
-Automatic display}.
+Automatic Display}.
@cindex catchpoints
@cindex breakpoint on events
when a certain kind of event occurs, such as the throwing of a C@t{++}
exception or the loading of a library. As with watchpoints, you use a
different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting
-catchpoints}), but aside from that, you can manage a catchpoint like any
+Catchpoints}), but aside from that, you can manage a catchpoint like any
other breakpoint. (To stop when your program receives a signal, use the
@code{handle} command; see @ref{Signals, ,Signals}.)
* 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...''
+* Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
@end menu
@node Set Breaks
-@subsection Setting breakpoints
+@subsection Setting Breakpoints
@c FIXME LMB what does GDB do if no code on line of breakpt?
@c consider in particular declaration with/without initialization.
Breakpoints are set with the @code{break} command (abbreviated
@code{b}). The debugger convenience variable @samp{$bpnum} records the
number of the breakpoint you've set most recently; see @ref{Convenience
-Vars,, Convenience variables}, for a discussion of what you can do with
+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
value is nonzero---that is, if @var{cond} evaluates as true.
@samp{@dots{}} stands for one of the possible arguments described
above (or no argument) specifying where to break. @xref{Conditions,
-,Break conditions}, for more information on breakpoint conditions.
+,Break Conditions}, for more information on breakpoint conditions.
@kindex tbreak
@item tbreak @var{args}
Set a breakpoint enabled only for one stop. @var{args} are the
same as for the @code{break} command, and the breakpoint is set in the same
way, but the breakpoint is automatically deleted after the first time your
-program stops there. @xref{Disabling, ,Disabling breakpoints}.
+program stops there. @xref{Disabling, ,Disabling Breakpoints}.
@kindex hbreak
@cindex hardware breakpoints
example, on the DSU, only two data breakpoints can be set at a time, and
@value{GDBN} will reject this command if more than two are used. Delete
or disable unused hardware breakpoints before setting new ones
-(@pxref{Disabling, ,Disabling}). @xref{Conditions, ,Break conditions}.
+(@pxref{Disabling, ,Disabling Breakpoints}).
+@xref{Conditions, ,Break Conditions}.
For remote targets, you can restrict the number of hardware
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}
the breakpoint is automatically deleted after the
first time your program stops there. Also, like the @code{hbreak}
command, the breakpoint requires hardware support and some target hardware
-may not have this support. @xref{Disabling, ,Disabling breakpoints}.
-See also @ref{Conditions, ,Break conditions}.
+may not have this support. @xref{Disabling, ,Disabling Breakpoints}.
+See also @ref{Conditions, ,Break Conditions}.
@kindex rbreak
@cindex regular expression
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
number @var{n} as argument lists only that breakpoint. The
convenience variable @code{$_} and the default examining-address for
the @code{x} command are set to the address of the last breakpoint
-listed (@pxref{Memory, ,Examining memory}).
+listed (@pxref{Memory, ,Examining Memory}).
@noindent
@code{info break} displays a count of the number of times the breakpoint
@value{GDBN} allows you to set any number of breakpoints at the same place in
your program. There is nothing silly or meaningless about this. When
the breakpoints are conditional, this is even useful
-(@pxref{Conditions, ,Break conditions}).
+(@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
+This is the default behaviour. 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.
+@end table
@cindex negative breakpoint numbers
@cindex internal @value{GDBN} breakpoints
@node Set Watchpoints
-@subsection Setting watchpoints
+@subsection Setting Watchpoints
@cindex setting watchpoints
You can use a watchpoint to stop execution whenever the value of an
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
@xref{set remote hardware-watchpoint-limit}.
@node Set Catchpoints
-@subsection Setting catchpoints
+@subsection Setting Catchpoints
@cindex catchpoints, setting
@cindex exception handlers
@cindex event handling
@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.
+A call to @code{vfork}. This is currently only available for HP-UX
+and @sc{gnu}/Linux.
@item load
@itemx load @var{libname}
@noindent
To make the debugger catch all exceptions before any stack
unwinding takes place, set a breakpoint on @code{__raise_exception}
-(@pxref{Breakpoints, ,Breakpoints; watchpoints; and exceptions}).
+(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Exceptions}).
-With a conditional breakpoint (@pxref{Conditions, ,Break conditions})
+With a conditional breakpoint (@pxref{Conditions, ,Break Conditions})
that depends on the value of @var{id}, you can stop your program when
a specific exception is raised. You can use multiple conditional
breakpoints to stop your program when any of a number of exceptions are
@node Delete Breaks
-@subsection Deleting breakpoints
+@subsection Deleting Breakpoints
@cindex clearing breakpoints, watchpoints, catchpoints
@cindex deleting breakpoints, watchpoints, catchpoints
@kindex clear
@item clear
Delete any breakpoints at the next instruction to be executed in the
-selected stack frame (@pxref{Selection, ,Selecting a frame}). When
+selected stack frame (@pxref{Selection, ,Selecting a Frame}). When
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
@end table
@node Disabling
-@subsection Disabling breakpoints
+@subsection Disabling Breakpoints
@cindex enable/disable a breakpoint
Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
@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:
@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is
@c confusing: tbreak is also initially enabled.
Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks,
-,Setting breakpoints}), breakpoints that you set are initially enabled;
+,Setting Breakpoints}), breakpoints that you set are initially enabled;
subsequently, they become disabled or enabled only when you use one of
the commands above. (The command @code{until} can set and delete a
breakpoint of its own, but it does not change the state of your other
breakpoints; see @ref{Continuing and Stepping, ,Continuing and
-stepping}.)
+Stepping}.)
@node Conditions
-@subsection Break conditions
+@subsection Break Conditions
@cindex conditional breakpoints
@cindex breakpoint conditions
breakpoint commands are usually more convenient and flexible than break
conditions for the
purpose of performing side effects when a breakpoint is reached
-(@pxref{Break Commands, ,Breakpoint command lists}).
+(@pxref{Break Commands, ,Breakpoint Command Lists}).
Break conditions can be specified when a breakpoint is set, by using
@samp{if} in the arguments to the @code{break} command. @xref{Set
-Breaks, ,Setting breakpoints}. They can also be changed at any time
+Breaks, ,Setting Breakpoints}. They can also be changed at any time
with the @code{condition} command.
You can also use the @code{if} keyword with the @code{watch} command.
When you use @code{continue} to resume execution of your program from a
breakpoint, you can specify an ignore count directly as an argument to
@code{continue}, rather than using @code{ignore}. @xref{Continuing and
-Stepping,,Continuing and stepping}.
+Stepping,,Continuing and Stepping}.
If a breakpoint has a positive ignore count and a condition, the
condition is not checked. Once the ignore count reaches zero,
You could achieve the effect of the ignore count with a condition such
as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that
is decremented each time. @xref{Convenience Vars, ,Convenience
-variables}.
+Variables}.
@end table
Ignore counts apply to breakpoints, watchpoints, and catchpoints.
@node Break Commands
-@subsection Breakpoint command lists
+@subsection Breakpoint Command Lists
@cindex breakpoint commands
You can give any breakpoint (or watchpoint or catchpoint) a series of
The commands @code{echo}, @code{output}, and @code{printf} allow you to
print precisely controlled output, and are often useful in silent
-breakpoints. @xref{Output, ,Commands for controlled output}.
+breakpoints. @xref{Output, ,Commands for Controlled Output}.
For example, here is how you could use breakpoint commands to print the
value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
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''
When this message is printed, you need to disable or remove some of the
hardware-assisted breakpoints and watchpoints, and then continue.
-@node Breakpoint related warnings
+@node Breakpoint-related Warnings
@subsection ``Breakpoint address adjusted...''
@cindex breakpoint address adjusted
frequently than expected.
@node Continuing and Stepping
-@section Continuing and stepping
+@section Continuing and Stepping
@cindex stepping
@cindex continuing
any breakpoints set at that address are bypassed. The optional argument
@var{ignore-count} allows you to specify a further number of times to
ignore a breakpoint at this location; its effect is like that of
-@code{ignore} (@pxref{Conditions, ,Break conditions}).
+@code{ignore} (@pxref{Conditions, ,Break Conditions}).
The argument @var{ignore-count} is meaningful only when your program
stopped due to a breakpoint. At other times, the argument to
@end table
To resume execution at a different place, you can use @code{return}
-(@pxref{Returning, ,Returning from a function}) to go back to the
+(@pxref{Returning, ,Returning from a Function}) to go back to the
calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a
-different address}) to go to an arbitrary location in your program.
+Different Address}) to go to an arbitrary location in your program.
A typical technique for using stepping is to set a breakpoint
-(@pxref{Breakpoints, ,Breakpoints; watchpoints; and catchpoints}) at the
+(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Catchpoints}) at the
beginning of the function or the section of your program where a problem
is believed to lie, run your program until it stops at that breakpoint,
and then step through the suspect area, examining the variables that are
returns. Print the returned value (if any).
Contrast this with the @code{return} command (@pxref{Returning,
-,Returning from a function}).
+,Returning from a Function}).
@kindex until
@kindex u @r{(@code{until})}
@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
invocations. For instance in the code below, if the current location is
line @code{96}, issuing @code{until 99} will execute the program up to
-line @code{99} in the same invocation of factorial, i.e. after the inner
+line @code{99} in the same invocation of factorial, i.e., after the inner
invocations have returned.
@smallexample
@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.
It is often useful to do @samp{display/i $pc} when stepping by machine
instructions. This makes @value{GDBN} automatically display the next
instruction to be executed, each time your program stops. @xref{Auto
-Display,, Automatic display}.
+Display,, Automatic Display}.
An argument is a repeat count, as in @code{step}.
execution; but your program would probably terminate immediately as
a result of the fatal signal once it saw the signal. To prevent this,
you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
-program a signal}.
+Program a Signal}.
@node Thread Stops
-@section Stopping and starting multi-thread programs
+@section Stopping and Starting Multi-thread Programs
When your program has multiple threads (@pxref{Threads,, Debugging
-programs with multiple threads}), you can choose whether to set
+Programs with Multiple Threads}), you can choose whether to set
breakpoints on all threads, or on a particular thread.
@table @code
@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
particular, whenever you ask @value{GDBN} for the value of a variable in
your program, the value is found in the selected frame. There are
special @value{GDBN} commands to select whichever frame you are
-interested in. @xref{Selection, ,Selecting a frame}.
+interested in. @xref{Selection, ,Selecting a Frame}.
When your program stops, @value{GDBN} automatically selects the
currently executing frame and describes it briefly, similar to the
-@code{frame} command (@pxref{Frame Info, ,Information about a frame}).
+@code{frame} command (@pxref{Frame Info, ,Information about a Frame}).
@menu
* Frames:: Stack frames
@end menu
@node Frames
-@section Stack frames
+@section Stack Frames
@cindex frame, definition
@cindex stack frame
@end table
@node Selection
-@section Selecting a frame
+@section Selecting a Frame
Most commands for examining the stack and other data in your program work on
whichever stack frame is selected at the moment. Here are the commands for
prints ten lines centered on the point of execution in the frame.
You can also edit the program at the point of execution with your favorite
editing program by typing @code{edit}.
-@xref{List, ,Printing source lines},
+@xref{List, ,Printing Source Lines},
for details.
@table @code
@end table
@node Frame Info
-@section Information about a frame
+@section Information About a Frame
There are several other commands to print information about the selected
stack frame.
frame is selected, but prints a brief description of the currently
selected stack frame. It can be abbreviated @code{f}. With an
argument, this command is used to select a stack frame.
-@xref{Selection, ,Selecting a frame}.
+@xref{Selection, ,Selecting a Frame}.
@kindex info frame
@kindex info f @r{(@code{info frame})}
selecting that frame. The selected frame remains unchanged by this
command. This requires the same kind of address (more than one for some
architectures) that you specify in the @code{frame} command.
-@xref{Selection, ,Selecting a frame}.
+@xref{Selection, ,Selecting a Frame}.
@kindex info args
@item info args
current stack frame at the current point of execution. To see other
exception handlers, visit the associated frame (using the @code{up},
@code{down}, or @code{frame} commands); then type @code{info catch}.
-@xref{Set Catchpoints, , Setting catchpoints}.
+@xref{Set Catchpoints, , Setting Catchpoints}.
@end table
information recorded in the program tells @value{GDBN} what source files were
used to build it. When your program stops, @value{GDBN} spontaneously prints
the line where it stopped. Likewise, when you select a stack frame
-(@pxref{Selection, ,Selecting a frame}), @value{GDBN} prints the line where
+(@pxref{Selection, ,Selecting a Frame}), @value{GDBN} prints the line where
execution in that frame has stopped. You can print other portions of
source files by explicit command.
@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
@end menu
@node List
-@section Printing source lines
+@section Printing Source Lines
@kindex list
@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
+@section Editing Source Files
@cindex editing source files
@kindex edit
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
+@subsection Choosing your Editor
You can customize @value{GDBN} to use any editor you want
@footnote{
The only restriction is that your editor (say @code{ex}), recognizes the
@end smallexample
@node Search
-@section Searching source files
+@section Searching Source Files
@cindex searching source files
There are two commands for searching through the current source file for a
@end table
@node Source Path
-@section Specifying source directories
+@section Specifying Source Directories
@cindex source path
@cindex directories for source files
@end enumerate
@node Machine Code
-@section Source and machine code
+@section Source and Machine Code
@cindex source line and its code address
You can use the command @code{info line} to map source lines to program
@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
After @code{info line}, the default address for the @code{x} command
is changed to the starting address of the line, so that @samp{x/i} is
sufficient to begin examining the machine code (@pxref{Memory,
-,Examining memory}). Also, this address is saved as the value of the
+,Examining Memory}). Also, this address is saved as the value of the
convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience
-variables}).
+Variables}).
@table @code
@kindex disassemble
value of @var{expr} is printed in a format appropriate to its data type;
you can choose a different format by specifying @samp{/@var{f}}, where
@var{f} is a letter specifying the format; see @ref{Output Formats,,Output
-formats}.
+Formats}.
@item print
@itemx print /@var{f}
@cindex reprint the last value
If you omit @var{expr}, @value{GDBN} displays the last value again (from the
-@dfn{value history}; @pxref{Value History, ,Value history}). This allows you to
+@dfn{value history}; @pxref{Value History, ,Value History}). This allows you to
conveniently inspect the same value in an alternative format.
@end table
A more low-level way of examining data is with the @code{x} command.
It examines data in memory at a specified address and prints it in a
-specified format. @xref{Memory, ,Examining memory}.
+specified format. @xref{Memory, ,Examining Memory}.
If you are interested in information about types, or about how the
fields of a struct or a class are declared, use the @code{ptype @var{exp}}
@menu
* Expressions:: Expressions
+* Ambiguous Expressions:: Ambiguous Expressions
* Variables:: Program variables
* Arrays:: Artificial arrays
* Output Formats:: Output formats
@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
@table @code
@item @@
@samp{@@} is a binary operator for treating parts of memory as arrays.
-@xref{Arrays, ,Artificial arrays}, for more information.
+@xref{Arrays, ,Artificial Arrays}, for more information.
@item ::
@samp{::} allows you to specify a variable in terms of the file or
-function where it is defined. @xref{Variables, ,Program variables}.
+function where it is defined. @xref{Variables, ,Program Variables}.
@cindex @{@var{type}@}
@cindex type casting memory
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
+@section Program Variables
The most common kind of expression to use is the name of a variable
in your program.
Variables in expressions are understood in the selected stack frame
-(@pxref{Selection, ,Selecting a frame}); they must be either:
+(@pxref{Selection, ,Selecting a Frame}); they must be either:
@itemize @bullet
@item
an effective form for debug info. @xref{Debugging Options,,Options
for Debugging Your Program or GCC, gcc.info, Using the @sc{gnu}
Compiler Collection (GCC)}.
-@xref{C, , Debugging C++}, for more information about debug info formats
+@xref{C, ,C and C@t{++}}, for more information about debug info formats
that are best suited to C@t{++} programs.
If you ask to print an object whose contents are unknown to
@end smallexample
@node Arrays
-@section Artificial arrays
+@section Artificial Arrays
@cindex artificial array
@cindex arrays
with @samp{@@} in this way behave just like other arrays in terms of
subscripting, and are coerced to pointers when used in expressions.
Artificial arrays most often appear in expressions via the value history
-(@pxref{Value History, ,Value history}), after printing one out.
+(@pxref{Value History, ,Value History}), after printing one out.
Another way to create an artificial array is to use a cast.
This re-interprets a value as if it were an array.
actually be adjacent---for example, if you are interested in the values
of pointers in an array. One useful work-around in this situation is
to use a convenience variable (@pxref{Convenience Vars, ,Convenience
-variables}) as a counter in an expression that prints the first
+Variables}) as a counter in an expression that prints the first
interesting value, and then repeat that expression via @key{RET}. For
instance, suppose you have an array @code{dtab} of pointers to
structures, and you are interested in the values of a field @code{fv}
@end smallexample
@node Output Formats
-@section Output formats
+@section Output Formats
@cindex formatted output
@cindex output formats
Print as integer in binary. The letter @samp{t} stands for ``two''.
@footnote{@samp{b} cannot be used because these format letters are also
used with the @code{x} command, where @samp{b} stands for ``byte'';
-see @ref{Memory,,Examining memory}.}
+see @ref{Memory,,Examining Memory}.}
@item a
@cindex unknown address, locating
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
expression. For example, @samp{p/x} reprints the last value in hex.
@node Memory
-@section Examining memory
+@section Examining Memory
You can use the command @code{x} (for ``examine'') to examine memory in
any of several formats, independently of your program's data types.
@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
Even though the unit size @var{u} is ignored for the formats @samp{s}
and @samp{i}, you might still want to use a count @var{n}; for example,
@samp{3i} specifies that you want to see three machine instructions,
-including any operands. The command @code{disassemble} gives an
-alternative way of inspecting machine instructions; see @ref{Machine
-Code,,Source and machine code}.
+including any operands. For convenience, especially when used with
+the @code{display} command, the @samp{i} format also prints branch delay
+slot instructions, if any, beyond the count specified, which immediately
+follow the last instruction that is within the count. The command
+@code{disassemble} gives an alternative way of inspecting machine
+instructions; see @ref{Machine Code,,Source and Machine Code}.
All the defaults for the arguments to @code{x} are designed to make it
easy to continue scanning memory with minimal specifications each time
@cindex remote memory comparison
@cindex verify remote memory image
When you are debugging a program running on a remote target machine
-(@pxref{Remote}), you may wish to verify the program's image in the
+(@pxref{Remote Debugging}), you may wish to verify the program's image in the
remote machine's memory against the executable file you downloaded to
the target. The @code{compare-sections} command is provided for such
situations.
@end table
@node Auto Display
-@section Automatic display
+@section Automatic Display
@cindex automatic display
@cindex display of expressions
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
For @var{fmt} specifying only a display format and not a size or
count, add the expression @var{expr} to the auto-display list but
arrange to display it each time in the specified format @var{fmt}.
-@xref{Output Formats,,Output formats}.
+@xref{Output Formats,,Output Formats}.
@item display/@var{fmt} @var{addr}
For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
number of units, add the expression @var{addr} as a memory address to
be examined each time your program stops. Examining means in effect
-doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining memory}.
+doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining Memory}.
@end table
For example, @samp{display/i $pc} can be helpful, to see the machine
is meaningful, you can enable the display expression once again.
@node Print Settings
-@section Print settings
+@section Print Settings
@cindex format options
@cindex print settings
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
@end table
@node Value History
-@section Value history
+@section Value History
@cindex value history
@cindex history of values printed by @value{GDBN}
same effect as @samp{show values +}.
@node Convenience Vars
-@section Convenience variables
+@section Convenience Variables
@cindex convenience variables
@cindex user-defined variables
@samp{$} can be used for a convenience variable, unless it is one of
the predefined machine-specific register names (@pxref{Registers, ,Registers}).
(Value history references, in contrast, are @emph{numbers} preceded
-by @samp{$}. @xref{Value History, ,Value history}.)
+by @samp{$}. @xref{Value History, ,Value History}.)
You can save a value in a convenience variable with an assignment
expression, just as you would set a variable in your program.
@vindex $_@r{, convenience variable}
@item $_
The variable @code{$_} is automatically set by the @code{x} command to
-the last address examined (@pxref{Memory, ,Examining memory}). Other
+the last address examined (@pxref{Memory, ,Examining Memory}). Other
commands which provide a default address for @code{x} to examine also
set @code{$_} to that address; these commands include @code{info line}
and @code{info breakpoint}. The type of @code{$_} is @code{void *}
stack frame is selected; setting @code{$sp} is not allowed when other
stack frames are selected. To pop entire frames off the stack,
regardless of machine architecture, use @code{return};
-see @ref{Returning, ,Returning from a function}.} with
+see @ref{Returning, ,Returning from a Function}.} with
@smallexample
set $sp += 4
@end smallexample
Normally, register values are relative to the selected stack frame
-(@pxref{Selection, ,Selecting a frame}). This means that you get the
+(@pxref{Selection, ,Selecting a Frame}). This means that you get the
value that the register would contain if all stack frames farther in
were exited and their saved registers restored. In order to see the
true contents of hardware registers, you must select the innermost
frame makes no difference.
@node Floating Point Hardware
-@section Floating point hardware
+@section Floating Point Hardware
@cindex floating point
Depending on the configuration, @value{GDBN} may be able to give
@end table
@node OS Information
-@section Operating system auxiliary information
+@section Operating System Auxiliary Information
@cindex OS information
@value{GDBN} provides interfaces to useful OS facilities that can help
@node Memory Region Attributes
-@section Memory region attributes
+@section Memory Region Attributes
@cindex memory region attributes
@dfn{Memory region attributes} allow you to describe special handling
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.
@c @end table
@node Dump/Restore Files
-@section Copy between memory and a file
+@section Copy Between Memory and a File
@cindex dump/restore files
@cindex append data to a file
@cindex dump data to a file
For example, if you are running @value{GDBN} on a @sc{gnu}/Linux system, which
uses the ISO Latin 1 character set, but you are using @value{GDBN}'s
-remote protocol (@pxref{Remote,Remote Debugging}) to debug a program
+remote protocol (@pxref{Remote Debugging}) to debug a program
running on an IBM mainframe, which uses the @sc{ebcdic} character set,
then the host character set is Latin-1, and the target character set is
@sc{ebcdic}. If you give @value{GDBN} the command @code{set
@cindex caching data of remote targets
@value{GDBN} can cache data exchanged between the debugger and a
-remote target (@pxref{Remote}). Such caching generally improves
+remote target (@pxref{Remote Debugging}). Such caching generally improves
performance, because it reduces the overhead of the remote protocol by
bundling memory reads and writes into large chunks. Unfortunately,
@value{GDBN} does not currently know anything about volatile
* Tracepoint Passcounts::
* Tracepoint Actions::
* Listing Tracepoints::
-* Starting and Stopping Trace Experiment::
+* Starting and Stopping Trace Experiments::
@end menu
@node Create and Delete Tracepoints
This command can be abbreviated @code{info tp}.
@end table
-@node Starting and Stopping Trace Experiment
-@subsection Starting and Stopping Trace Experiment
+@node Starting and Stopping Trace Experiments
+@subsection Starting and Stopping Trace Experiments
@table @code
@kindex tstart
@node Analyze Collected Data
-@section Using the collected data
+@section Using the Collected Data
After the tracepoint experiment ends, you use @value{GDBN} commands
for examining the trace data. The basic idea is that each tracepoint
* Setting:: Switching between source languages
* Show:: Displaying the language
* Checks:: Type and range checks
-* Supported languages:: Supported languages
-* Unsupported languages:: Unsupported languages
+* Supported Languages:: Supported languages
+* Unsupported Languages:: Unsupported languages
@end menu
@node Setting
-@section Switching between source languages
+@section Switching Between Source Languages
There are two ways to control the working language---either have @value{GDBN}
set it automatically, or select it manually yourself. You can use the
show each frame appropriately for its own language. There is no way to
set the language of a source file from within @value{GDBN}, but you can
set the language associated with a filename extension. @xref{Show, ,
-Displaying the language}.
+Displaying the Language}.
This is most commonly a problem when you use a program, such
as @code{cfront} or @code{f2c}, that generates C but is written in
@end menu
@node Filenames
-@subsection List of filename extensions and languages
+@subsection List of Filename Extensions and Languages
If a source file name ends in one of the following extensions, then
@value{GDBN} infers that its language is the one indicated.
@end table
In addition, you may set the language associated with a filename
-extension. @xref{Show, , Displaying the language}.
+extension. @xref{Show, , Displaying the Language}.
@node Manually
-@subsection Setting the working language
+@subsection Setting the Working Language
If you allow @value{GDBN} to set the language automatically,
expressions are interpreted the same way in your debugging session and
@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value.
@node Automatically
-@subsection Having @value{GDBN} infer the source language
+@subsection Having @value{GDBN} Infer the Source Language
To have @value{GDBN} set the working language automatically, use
@samp{set language local} or @samp{set language auto}. @value{GDBN}
case frees you from having to set the working language manually.
@node Show
-@section Displaying the language
+@section Displaying the Language
The following commands help you find out which language is the
working language, and also what language source files were written in.
@kindex info frame@r{, show the source language}
Display the source language for this frame. This language becomes the
working language if you use an identifier from this frame.
-@xref{Frame Info, ,Information about a frame}, to identify the other
+@xref{Frame Info, ,Information about a Frame}, to identify the other
information listed here.
@item info source
@end table
@node Checks
-@section Type and range checking
+@section Type and Range Checking
@quotation
@emph{Warning:} In this release, the @value{GDBN} commands for type and range
evaluation via the @code{print} command, for example. As with the
working language, @value{GDBN} can also decide whether or not to check
automatically based on your program's source language.
-@xref{Supported languages, ,Supported languages}, for the default
+@xref{Supported Languages, ,Supported Languages}, for the default
settings of supported languages.
@menu
@cindex type checking
@cindex checks, type
@node Type Checking
-@subsection An overview of type checking
+@subsection An Overview of Type Checking
Some languages, such as Modula-2, are strongly typed, meaning that the
arguments to operators and functions have to be of the correct type,
instance, both Modula-2 and C require the arguments to arithmetical
operators to be numbers. In C, enumerated types and pointers can be
represented as numbers, so that they are valid arguments to mathematical
-operators. @xref{Supported languages, ,Supported languages}, for further
+operators. @xref{Supported Languages, ,Supported Languages}, for further
details on specific languages.
@value{GDBN} provides some additional commands for controlling the type checker:
@table @code
@item set check type auto
Set type checking on or off based on the current working language.
-@xref{Supported languages, ,Supported languages}, for the default settings for
+@xref{Supported Languages, ,Supported Languages}, for the default settings for
each language.
@item set check type on
@cindex range checking
@cindex checks, range
@node Range Checking
-@subsection An overview of range checking
+@subsection An Overview of Range Checking
In some languages (such as Modula-2), it is an error to exceed the
bounds of a type; this is enforced with run-time checks. Such range
@end smallexample
This, too, is specific to individual languages, and in some cases
-specific to individual compilers or machines. @xref{Supported languages, ,
-Supported languages}, for further details on specific languages.
+specific to individual compilers or machines. @xref{Supported Languages, ,
+Supported Languages}, for further details on specific languages.
@value{GDBN} provides some additional commands for controlling the range checker:
@table @code
@item set check range auto
Set range checking on or off based on the current working language.
-@xref{Supported languages, ,Supported languages}, for the default settings for
+@xref{Supported Languages, ,Supported Languages}, for the default settings for
each language.
@item set check range on
being set automatically by @value{GDBN}.
@end table
-@node Supported languages
-@section Supported languages
+@node Supported Languages
+@section Supported Languages
@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, Pascal,
assembly, Modula-2, and Ada.
@menu
* C Operators:: C and C@t{++} operators
* C Constants:: C and C@t{++} constants
-* C plus plus expressions:: C@t{++} expressions
+* C Plus Plus Expressions:: C@t{++} expressions
* C Defaults:: Default settings for C and C@t{++}
* 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{++}
+* Debugging C Plus Plus:: @value{GDBN} features for C@t{++}
+* Decimal Floating Point:: Numbers in Decimal Floating Point format
@end menu
@node C Operators
-@subsubsection C and C@t{++} operators
+@subsubsection C and C@t{++} Operators
@cindex C and C@t{++} 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.
predefined meaning.
@node C Constants
-@subsubsection C and C@t{++} constants
+@subsubsection C and C@t{++} Constants
@cindex C and C@t{++} constants
and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
@end itemize
-@node C plus plus expressions
-@subsubsection C@t{++} expressions
+@node C Plus Plus Expressions
+@subsubsection C@t{++} Expressions
@cindex expressions in C@t{++}
@value{GDBN} expression handling can interpret most C@t{++} expressions.
number of function arguments.
Overload resolution is always performed, unless you have specified
-@code{set overload-resolution off}. @xref{Debugging C plus plus,
-,@value{GDBN} features for C@t{++}}.
+@code{set overload-resolution off}. @xref{Debugging C Plus Plus,
+,@value{GDBN} Features for C@t{++}}.
You must specify @code{set overload-resolution off} in order to use an
explicit function signature to call an overloaded function, as in
@end smallexample
The @value{GDBN} command-completion facility can simplify this;
-see @ref{Completion, ,Command completion}.
+see @ref{Completion, ,Command Completion}.
@cindex reference declarations
@item
necessary, for example in an expression like
@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows
resolving name scope by reference to source files, in both C and C@t{++}
-debugging (@pxref{Variables, ,Program variables}).
+debugging (@pxref{Variables, ,Program Variables}).
@end enumerate
In addition, when used with HP's C@t{++} compiler, @value{GDBN} supports
invoking user-defined operators.
@node C Defaults
-@subsubsection C and C@t{++} defaults
+@subsubsection C and C@t{++} Defaults
@cindex C and C@t{++} defaults
recognizes source files whose names end with @file{.c}, @file{.C}, or
@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of
these files, it sets the working language to C or C@t{++}.
-@xref{Automatically, ,Having @value{GDBN} infer the source language},
+@xref{Automatically, ,Having @value{GDBN} Infer the Source Language},
for further details.
@c Type checking is (a) primarily motivated by Modula-2, and (b)
@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
@node C Checks
-@subsubsection C and C@t{++} type and range checks
+@subsubsection C and C@t{++} Type and Range Checks
@cindex C and C@t{++} checks
with pointers and a memory allocation function. @xref{Expressions,
,Expressions}.
-@node Debugging C plus plus
-@subsubsection @value{GDBN} features for C@t{++}
+@node Debugging C Plus Plus
+@subsubsection @value{GDBN} Features for C@t{++}
@cindex commands for C@t{++}
@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}
Setting breakpoints using regular expressions is helpful for setting
breakpoints on overloaded functions that are not members of any special
classes.
-@xref{Set Breaks, ,Setting breakpoints}.
+@xref{Set Breaks, ,Setting Breakpoints}.
@cindex C@t{++} exception handling
@item catch throw
@itemx catch catch
Debug C@t{++} exception handling using these commands. @xref{Set
-Catchpoints, , Setting catchpoints}.
+Catchpoints, , Setting Catchpoints}.
@cindex inheritance
@item ptype @var{typename}
@itemx show print asm-demangle
Control whether C@t{++} symbols display in their source form, both when
displaying code as C@t{++} source and when displaying disassemblies.
-@xref{Print Settings, ,Print settings}.
+@xref{Print Settings, ,Print Settings}.
@item set print object
@itemx show print object
Choose whether to print derived (actual) or declared types of objects.
-@xref{Print Settings, ,Print settings}.
+@xref{Print Settings, ,Print Settings}.
@item set print vtbl
@itemx show print vtbl
Control the format for printing virtual function tables.
-@xref{Print Settings, ,Print settings}.
+@xref{Print Settings, ,Print Settings}.
(The @code{vtbl} commands do not work on programs compiled with the HP
ANSI C@t{++} compiler (@code{aCC}).)
Enable overload resolution for C@t{++} expression evaluation. The default
is on. For overloaded functions, @value{GDBN} evaluates the arguments
and searches for a function whose signature matches the argument types,
-using the standard C@t{++} conversion rules (see @ref{C plus plus expressions, ,C@t{++}
-expressions}, for details). If it cannot find a match, it emits a
-message.
+using the standard C@t{++} conversion rules (see @ref{C Plus Plus
+Expressions, ,C@t{++} Expressions}, for details).
+If it cannot find a match, it emits a message.
@item set overload-resolution off
Disable overload resolution for C@t{++} expression evaluation. For
@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
also use the @value{GDBN} command-line word completion facilities to list the
available choices, or to finish the type list for you.
-@xref{Completion,, Command completion}, for details on how to do this.
+@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
@menu
* Fortran Operators:: Fortran operators and expressions
* Fortran Defaults:: Default settings for Fortran
-* Special Fortran commands:: Special @value{GDBN} commands for Fortran
+* Special Fortran Commands:: Special @value{GDBN} commands for Fortran
@end menu
@node Fortran Operators
-@subsubsection Fortran operators and expressions
+@subsubsection Fortran Operators and Expressions
@cindex Fortran operators and expressions
@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
change that with the @samp{set case-insensitive} command, see
@ref{Symbols}, for the details.
-@node Special Fortran commands
-@subsubsection Special Fortran commands
+@node Special Fortran Commands
+@subsubsection Special Fortran Commands
@cindex Special Fortran commands
-@value{GDBN} had some commands to support Fortran specific feature,
-such as common block displaying.
+@value{GDBN} has some commands to support Fortran-specific features,
+such as displaying common blocks.
@table @code
@cindex @code{COMMON} blocks, Fortran
@node Built-In Func/Proc
-@subsubsection Built-in functions and procedures
+@subsubsection Built-in Functions and Procedures
@cindex Modula-2 built-ins
Modula-2 also makes available several built-in procedures and functions.
@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
String constants consist of a sequence of characters enclosed by a
pair of like quotes, either single (@code{'}) or double (@code{"}).
Escape sequences in the style of C are also allowed. @xref{C
-Constants, ,C and C@t{++} constants}, for a brief explanation of escape
+Constants, ,C and C@t{++} Constants}, for a brief explanation of escape
sequences.
@item
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:
@end smallexample
@node M2 Defaults
-@subsubsection Modula-2 defaults
+@subsubsection Modula-2 Defaults
@cindex Modula-2 defaults
If type and range checking are set automatically by @value{GDBN}, they
If you allow @value{GDBN} to set the language automatically, then entering
code compiled from a file whose name ends with @file{.mod} sets the
-working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set
-the language automatically}, for further details.
+working language to Modula-2. @xref{Automatically, ,Having @value{GDBN}
+Infer the Source Language}, for further details.
@node Deviations
-@subsubsection Deviations from standard Modula-2
+@subsubsection Deviations from Standard Modula-2
@cindex Modula-2, deviations from
A few changes have been made to make Modula-2 programs easier to debug.
@end itemize
@node M2 Checks
-@subsubsection Modula-2 type and range checks
+@subsubsection Modula-2 Type and Range Checks
@cindex Modula-2 checks
@quotation
index bounds, and all built-in functions and procedures.
@node M2 Scope
-@subsubsection The scope operators @code{::} and @code{.}
+@subsubsection The Scope Operators @code{::} and @code{.}
@cindex scope
@cindex @code{.}, Modula-2 scope operator
@cindex colon, doubled as scope operator
@code{Standard} explicitly.
@end itemize
-@node Unsupported languages
-@section Unsupported languages
+@node Unsupported Languages
+@section Unsupported Languages
@cindex unsupported languages
@cindex minimal language
program. This information is inherent in the text of your program and
does not change as your program executes. @value{GDBN} finds it in your
program's symbol table, in the file indicated when you started @value{GDBN}
-(@pxref{File Options, ,Choosing files}), or by one of the
-file-management commands (@pxref{Files, ,Commands to specify files}).
+(@pxref{File Options, ,Choosing Files}), or by one of the
+file-management commands (@pxref{Files, ,Commands to Specify Files}).
@cindex symbol names
@cindex names of symbols
Occasionally, you may need to refer to symbols that contain unusual
characters, which @value{GDBN} ordinarily treats as word delimiters. The
most frequent case is in referring to static variables in other
-source files (@pxref{Variables,,Program variables}). File names
+source files (@pxref{Variables,,Program Variables}). File names
are recorded in object files as debugging symbols, but @value{GDBN} would
ordinarily parse a typical file name, like @file{foo.c}, as the three words
@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize
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}
files that @value{GDBN} has skimmed, but not yet read completely. Finally,
@samp{maint print msymbols} dumps just the minimal symbol information
required for each object file from which @value{GDBN} has read some symbols.
-@xref{Files, ,Commands to specify files}, for a discussion of how
+@xref{Files, ,Commands to Specify Files}, for a discussion of how
@value{GDBN} reads symbols (in the description of @code{symbol-file}).
@kindex maint info symtabs
dirname (null)
fullname (null)
blockvector ((struct blockvector *) 0x86c1bd0) (primary)
+ linetable ((struct linetable *) 0x8370fa0)
debugformat DWARF 2
@}
@}
@end menu
@node Assignment
-@section Assignment to variables
+@section Assignment to Variables
@cindex assignment
@cindex setting variables
@code{set} command instead of the @code{print} command. @code{set} is
really the same as @code{print} except that the expression's value is
not printed and is not put in the value history (@pxref{Value History,
-,Value history}). The expression is evaluated only for its effects.
+,Value History}). The expression is evaluated only for its effects.
If the beginning of the argument string of the @code{set} command
appears identical to a @code{set} subcommand, use the @code{set
stores the value 4 into that memory location.
@node Jumping
-@section Continuing at a different address
+@section Continuing at a Different Address
Ordinarily, when you continue your program, you do so at the place where
it stopped, with the @code{continue} command. You can instead continue at
@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.
@noindent
makes the next @code{continue} command or stepping command execute at
address @code{0x485}, rather than at the address where your program stopped.
-@xref{Continuing and Stepping, ,Continuing and stepping}.
+@xref{Continuing and Stepping, ,Continuing and Stepping}.
The most common occasion to use the @code{jump} command is to back
up---perhaps with more breakpoints set---over a portion of a program
@c @group
@node Signaling
-@section Giving your program a signal
+@section Giving your Program a Signal
@cindex deliver a signal to a program
@table @code
@node Returning
-@section Returning from a function
+@section Returning from a Function
@table @code
@cindex returning from a function
be returned, give that value as the argument to @code{return}.
This pops the selected stack frame (@pxref{Selection, ,Selecting a
-frame}), and any other frames inside of it, leaving its caller as the
+Frame}), and any other frames inside of it, leaving its caller as the
innermost remaining frame. That frame becomes selected. The
specified value is stored in the registers used for returning values
of functions.
The @code{return} command does not resume execution; it leaves the
program stopped in the state that would exist if the function had just
returned. In contrast, the @code{finish} command (@pxref{Continuing
-and Stepping, ,Continuing and stepping}) resumes execution until the
+and Stepping, ,Continuing and Stepping}) resumes execution until the
selected stack frame returns naturally.
@node Calling
-@section Calling program functions
+@section Calling Program Functions
@table @code
@cindex calling functions
function instead.
@node Patching
-@section Patching programs
+@section Patching Programs
@cindex patching binaries
@cindex writing into executables
@end menu
@node Files
-@section Commands to specify files
+@section Commands to Specify Files
@cindex symbol table
@cindex core dump file
Occasionally it is necessary to change to a different file during a
@value{GDBN} session. Or you may run @value{GDBN} and forget to
specify a file you want to use. Or you are debugging a remote target
-via @code{gdbserver} (@pxref{Server, file, Using the gdbserver
-program}). In these situations the @value{GDBN} commands to specify
+via @code{gdbserver} (@pxref{Server, file, Using the @code{gdbserver}
+Program}). In these situations the @value{GDBN} commands to specify
new files are useful.
@table @code
occasional pauses while the symbol table details for a particular source
file are being read. (The @code{set verbose} command can turn these
pauses into messages if desired. @xref{Messages/Warnings, ,Optional
-warnings and messages}.)
+Warnings and Messages}.)
We have not implemented the two-stage strategy for COFF yet. When the
symbol table is stored in COFF format, @code{symbol-file} reads the
under @value{GDBN}. So, if you have been running your program and you
wish to debug a core file instead, you must kill the subprocess in which
the program is running. To do this, use the @code{kill} command
-(@pxref{Kill Process, ,Killing the child process}).
+(@pxref{Kill Process, ,Killing the Child Process}).
@kindex add-symbol-file
@cindex dynamic linking
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
@cindex @file{.debug} subdirectories
@cindex debugging information directory, global
@cindex global debugging information directory
+@cindex build ID, and separate debugging files
+@cindex @file{.build-id} directory
@value{GDBN} allows you to put a program's debugging information in a
file separate from the executable itself, in a way that allows
@value{GDBN} to find and load the debugging information automatically.
-Since debugging information can be very large --- sometimes larger
-than the executable code itself --- some systems distribute debugging
+Since debugging information can be very large---sometimes larger
+than the executable code itself---some systems distribute debugging
information for their executables in separate files, which users can
install only when they need to debug a problem.
-If an executable's debugging information has been extracted to a
-separate file, the executable should contain a @dfn{debug link} giving
-the name of the debugging information file (with no directory
-components), and a checksum of its contents. (The exact form of a
-debug link is described below.) If the full name of the directory
-containing the executable is @var{execdir}, and the executable has a
-debug link that specifies the name @var{debugfile}, then @value{GDBN}
-will automatically search for the debugging information file in three
-places:
+@value{GDBN} supports two ways of specifying the separate debug info
+file:
@itemize @bullet
@item
-the directory containing the executable file (that is, it will look
-for a file named @file{@var{execdir}/@var{debugfile}},
+The executable contains a @dfn{debug link} that specifies the name of
+the separate debug info file. The separate debug file's name is
+usually @file{@var{executable}.debug}, where @var{executable} is the
+name of the corresponding executable file without leading directories
+(e.g., @file{ls.debug} for @file{/usr/bin/ls}). In addition, the
+debug link specifies a CRC32 checksum for the debug file, which
+@value{GDBN} uses to validate that the executable and the debug file
+came from the same build.
+
+@item
+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 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}
+uses two different methods of looking for the debug file:
+
+@itemize @bullet
@item
-a subdirectory of that directory named @file{.debug} (that is, the
-file @file{@var{execdir}/.debug/@var{debugfile}}, and
+For the ``debug link'' method, @value{GDBN} looks up the named file in
+the directory of the executable file, then in a subdirectory of that
+directory named @file{.debug}, and finally under the global debug
+directory, in a subdirectory whose name is identical to the leading
+directories of the executable's absolute file name.
+
@item
-a subdirectory of the global debug file directory that includes the
-executable's full path, and the name from the link (that is, the file
-@file{@var{globaldebugdir}/@var{execdir}/@var{debugfile}}, where
-@var{globaldebugdir} is the global debug file directory, and
-@var{execdir} has been turned into a relative path).
+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 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
-@noindent
-@value{GDBN} checks under each of these names for a debugging
-information file whose checksum matches that given in the link, and
-reads the debugging information from the first one it finds.
-
-So, for example, if you ask @value{GDBN} to debug @file{/usr/bin/ls},
-which has a link containing the name @file{ls.debug}, and the global
-debug directory is @file{/usr/lib/debug}, then @value{GDBN} will look
-for debug information in @file{/usr/bin/ls.debug},
-@file{/usr/bin/.debug/ls.debug}, and
+
+So, for example, suppose you ask @value{GDBN} to debug
+@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:
+
+@itemize @minus
+@item
+@file{/usr/lib/debug/.build-id/ab/cdef1234.debug}
+@item
+@file{/usr/bin/ls.debug}
+@item
+@file{/usr/bin/.debug/ls.debug}
+@item
@file{/usr/lib/debug/usr/bin/ls.debug}.
+@end itemize
You can set the global debugging info directory's name, and view the
name @value{GDBN} is currently using.
@end table
@cindex @code{.gnu_debuglink} sections
-@cindex debug links
+@cindex debug link sections
A debug link is a special section of the executable file named
@code{.gnu_debuglink}. The section must contain:
contain a section named @code{.gnu_debuglink} with the contents
described above.
+@cindex @code{.note.gnu.build-id} sections
+@cindex build ID sections
+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
debugging information. The sections of the debugging information file
-should have the same names, addresses and sizes as the original file,
-but they need not contain any data --- much like a @code{.bss} section
+should have the same names, addresses, and sizes as the original file,
+but they need not contain any data---much like a @code{.bss} section
in an ordinary executable.
-As of December 2002, there is no standard GNU utility to produce
-separated executable / debugging information file pairs. 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} removes the debugging information from
-the executable file @file{foo}, places it in the file
-@file{foo.debug}, and leaves behind a debug link in @file{foo}.
+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}
+@end smallexample
+
+@noindent
+These commands remove the debugging
+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 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 (different
-polynomials, reversals, byte ordering, etc.), the simplest way to
-describe the CRC used in @code{.gnu_debuglink} sections is to give the
-complete code for a function that computes it:
+Since there are many different ways to compute CRC's for the debug
+link (different polynomials, reversals, byte ordering, etc.), the
+simplest way to describe the CRC used in @code{.gnu_debuglink}
+sections is to give the complete code for a function that computes it:
@kindex gnu_debuglink_crc32
@smallexample
@}
@end smallexample
+@noindent
+This computation does not apply to the ``build ID'' method.
+
@node Symbol Errors
-@section Errors reading symbol files
+@section Errors Reading Symbol Files
While reading a symbol file, @value{GDBN} occasionally encounters problems,
such as symbol types it does not recognize, or known bugs in compiler
only one message about each such type of problem, no matter how many
times the problem occurs; or you can ask @value{GDBN} to print more messages,
to see how many times the problems occur, with the @code{set
-complaints} command (@pxref{Messages/Warnings, ,Optional warnings and
-messages}).
+complaints} command (@pxref{Messages/Warnings, ,Optional Warnings and
+Messages}).
The messages currently printed, and their meanings, include:
@value{GDBN} does not circumvent this problem, and has trouble
locating symbols in the source file whose symbols it is reading. (You
can often determine what source file is affected by specifying
-@code{set verbose on}. @xref{Messages/Warnings, ,Optional warnings and
-messages}.)
+@code{set verbose on}. @xref{Messages/Warnings, ,Optional Warnings and
+Messages}.)
@item bad block start address patched
host, or controlling a standalone system over a serial port or a
realtime system over a TCP/IP connection---you can use the @code{target}
command to specify one of the target types configured for @value{GDBN}
-(@pxref{Target Commands, ,Commands for managing targets}).
+(@pxref{Target Commands, ,Commands for Managing Targets}).
@cindex target architecture
It is possible to build @value{GDBN} for several different @dfn{target
* Active Targets:: Active targets
* Target Commands:: Commands for managing targets
* Byte Order:: Choosing target byte order
-* Remote:: Remote debugging
-
@end menu
@node Active Targets
-@section Active targets
+@section Active Targets
@cindex stacking targets
@cindex active targets
process target is active.
Use the @code{core-file} and @code{exec-file} commands to select a new
-core file or executable target (@pxref{Files, ,Commands to specify
-files}). To specify as a target a process that is already running, use
-the @code{attach} command (@pxref{Attach, ,Debugging an already-running
-process}).
+core file or executable target (@pxref{Files, ,Commands to Specify
+Files}). To specify as a target a process that is already running, use
+the @code{attach} command (@pxref{Attach, ,Debugging an Already-running
+Process}).
@node Target Commands
-@section Commands for managing targets
+@section Commands for Managing Targets
@table @code
@item target @var{type} @var{parameters}
@item help target
Displays the names of all targets available. To display targets
currently selected, use either @code{info target} or @code{info files}
-(@pxref{Files, ,Commands to specify files}).
+(@pxref{Files, ,Commands to Specify Files}).
@item help target @var{name}
Describe a particular target, including any parameters necessary to
@end quotation
@noindent
-@xref{Files, , Commands to specify files}.
+@xref{Files, , Commands to Specify Files}.
@kindex show gnutarget
@item show gnutarget
@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
@end table
@node Byte Order
-@section Choosing target byte order
+@section Choosing Target Byte Order
@cindex choosing target byte order
@cindex target byte order
data on the host, and that they have absolutely no effect on the
target system.
-@node Remote
-@section Remote debugging
+
+@node Remote Debugging
+@chapter Debugging Remote Programs
@cindex remote debugging
If you are trying to debug a program running on a machine that cannot run
Other remote targets may be available in your
configuration of @value{GDBN}; use @code{help target} to list them.
-Once you've connected to the remote target, @value{GDBN} allows you to
-send arbitrary commands to the remote monitor:
-
-@table @code
-@item remote @var{command}
-@kindex remote@r{, a command}
-@cindex send command to remote monitor
-Send an arbitrary @var{command} string to the remote monitor.
-@end table
-
-
-@node Remote Debugging
-@chapter Debugging remote programs
-
@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
+* Remote Configuration:: Remote configuration
+* Remote Stub:: Implementing a remote stub
@end menu
@node Connecting
-@section Connecting to a remote target
+@section Connecting to a Remote Target
On the @value{GDBN} host machine, you will need an unstripped copy of
your program, since @value{GDBN} needs symbol and debugging information.
If you're using a serial line, you may want to give @value{GDBN} the
@w{@samp{--baud}} option, or use the @code{set remotebaud} command
-(@pxref{Remote configuration, set remotebaud}) before the
+(@pxref{Remote Configuration, set remotebaud}) before the
@code{target} command.
@item target remote @code{@var{host}:@var{port}}
@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
+@section Using the @code{gdbserver} Program
@kindex gdbserver
@cindex remote connection without stubs
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}
+
+You can include @option{--debug} on the @code{gdbserver} command line.
+@code{gdbserver} will display extra status information about the debugging
+process. This option is 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
files may also prevent @code{gdbserver} from debugging multi-threaded
programs.
-Connect to your target (@pxref{Connecting,,Connecting to a remote target}).
+Connect to your target (@pxref{Connecting,,Connecting to a Remote Target}).
For TCP connections, you must start up @code{gdbserver} prior to using
the @code{target remote} command. Otherwise you may get an error whose
text depends on the host system, but which usually looks something like
-@samp{Connection refused}. You don't need to use the @code{load}
+@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}
+@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
-@section Remote configuration
+@node Remote Configuration
+@section Remote Configuration
@kindex set remote
@kindex show remote
Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to
interrupt the remote program.
-@item set remotedevice @var{device}
-@cindex serial port name
-Set the name of the serial port through which to communicate to the
-remote target to @var{device}. This is the device used by
-@value{GDBN} to open the serial communications line to the remote
-target. There's no default, so you must set a valid port name for the
-remote serial communications to work. (Some varieties of the
-@code{target} command accept the port name as part of their
-arguments.)
+@item set remoteflow on
+@itemx set remoteflow off
+@kindex set remoteflow
+Enable or disable hardware flow control (@code{RTS}/@code{CTS})
+on the serial port used to communicate to the remote target.
-@item show remotedevice
-Show the current name of the serial port.
+@item show remoteflow
+@kindex show remoteflow
+Show the current setting of hardware flow control.
@item set remotelogbase @var{base}
Set the base (a.k.a.@: radix) of logging serial protocol
@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).
@end table
@cindex remote packets, enabling and disabling
in @value{GDBN}. You may want to report the problem to the
@value{GDBN} developers.
-The available settings are:
+For each packet @var{name}, the command to enable or disable the
+packet is @code{set remote @var{name}-packet}. The available settings
+are:
-@multitable @columnfractions 0.3 0.2 0.35
+@multitable @columnfractions 0.28 0.32 0.25
@item Command Name
@tab Remote Packet
@tab Related Features
-@item @code{fetch-register-packet}
+@item @code{fetch-register}
@tab @code{p}
@tab @code{info registers}
-@item @code{set-register-packet}
+@item @code{set-register}
@tab @code{P}
@tab @code{set}
-@item @code{binary-download-packet}
+@item @code{binary-download}
@tab @code{X}
@tab @code{load}, @code{set}
-@item @code{read-aux-vector-packet}
+@item @code{read-aux-vector}
@tab @code{qXfer:auxv:read}
@tab @code{info auxv}
-@item @code{symbol-lookup-packet}
+@item @code{symbol-lookup}
@tab @code{qSymbol}
@tab Detecting multiple threads
-@item @code{verbose-resume-packet}
+@item @code{attach}
+@tab @code{vAttach}
+@tab @code{attach}
+
+@item @code{verbose-resume}
@tab @code{vCont}
@tab Stepping or resuming multiple threads
-@item @code{software-breakpoint-packet}
+@item @code{run}
+@tab @code{vRun}
+@tab @code{run}
+
+@item @code{software-breakpoint}
@tab @code{Z0}
@tab @code{break}
-@item @code{hardware-breakpoint-packet}
+@item @code{hardware-breakpoint}
@tab @code{Z1}
@tab @code{hbreak}
-@item @code{write-watchpoint-packet}
+@item @code{write-watchpoint}
@tab @code{Z2}
@tab @code{watch}
-@item @code{read-watchpoint-packet}
+@item @code{read-watchpoint}
@tab @code{Z3}
@tab @code{rwatch}
-@item @code{access-watchpoint-packet}
+@item @code{access-watchpoint}
@tab @code{Z4}
@tab @code{awatch}
-@item @code{get-thread-local-storage-address-packet}
+@item @code{target-features}
+@tab @code{qXfer:features:read}
+@tab @code{set architecture}
+
+@item @code{library-info}
+@tab @code{qXfer:libraries:read}
+@tab @code{info sharedlibrary}
+
+@item @code{memory-map}
+@tab @code{qXfer:memory-map:read}
+@tab @code{info mem}
+
+@item @code{read-spu-object}
+@tab @code{qXfer:spu:read}
+@tab @code{info spu}
+
+@item @code{write-spu-object}
+@tab @code{qXfer:spu:write}
+@tab @code{info spu}
+
+@item @code{get-thread-local-@*storage-address}
@tab @code{qGetTLSAddr}
@tab Displaying @code{__thread} variables
@tab @code{qSupported}
@tab Remote communications parameters
-@item @code{pass-signals-packet}
+@item @code{pass-signals}
@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}
@end multitable
-@node remote stub
-@section Implementing a remote stub
+@node Remote Stub
+@section Implementing a Remote Stub
@cindex debugging stub, example
@cindex remote stub, example
On certain remote targets, you can use an auxiliary program
@code{gdbserver} instead of linking a stub into your program.
-@xref{Server,,Using the @code{gdbserver} program}, for details.
+@xref{Server,,Using the @code{gdbserver} Program}, for details.
@end table
The debugging stub is specific to the architecture of the remote
@end menu
@node Stub Contents
-@subsection What the stub can do for you
+@subsection What the Stub Can Do for You
@cindex remote serial stub
The debugging stub for your architecture supplies these three
@end table
@node Bootstrapping
-@subsection What you must do for the stub
+@subsection What You Must Do for the Stub
@cindex remote stub, support routines
The debugging stubs that come with @value{GDBN} are set up for a particular
@node Debug Session
-@subsection Putting it all together
+@subsection Putting it All Together
@cindex remote serial debugging summary
In summary, when your program is ready to debug, you must follow these
@enumerate
@item
Make sure you have defined the supporting low-level routines
-(@pxref{Bootstrapping,,What you must do for the stub}):
+(@pxref{Bootstrapping,,What You Must Do for the Stub}):
@display
@code{getDebugChar}, @code{putDebugChar},
@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}.
@item
Start @value{GDBN} on the host, and connect to the target
-(@pxref{Connecting,,Connecting to a remote target}).
+(@pxref{Connecting,,Connecting to a Remote Target}).
@end enumerate
@end table
@node SVR4 Process Information
-@subsection SVR4 process information
+@subsection SVR4 Process Information
@cindex /proc
@cindex examine process image
@cindex process info via @file{/proc}
@node Cygwin Native
-@subsection Features for Debugging MS Windows PE executables
+@subsection Features for Debugging MS Windows PE Executables
@cindex MS Windows debugging
@cindex native Cygwin debugging
@cindex Cygwin-specific commands
@value{GDBN} supports native debugging of MS Windows programs, including
-DLLs with and without symbolic debugging information. There are various
-additional Cygwin-specific commands, described in this subsection. The
-subsubsection @pxref{Non-debug DLL symbols} describes working with DLLs
-that have no debugging symbols.
-
+DLLs with and without symbolic debugging information. There are various
+additional Cygwin-specific commands, described in this section.
+Working with DLLs that have no debugging symbols is described in
+@ref{Non-debug DLL Symbols}.
@table @code
@kindex info w32
@item info w32
-This is a prefix of MS Windows specific commands which print
+This is a prefix of MS Windows-specific commands which print
information about the target system and important OS structures.
@item info w32 selector
@kindex info dll
@item info dll
-This is a Cygwin specific alias of info shared.
+This is a Cygwin-specific alias of @code{info shared}.
@kindex dll-symbols
@item dll-symbols
@end table
@menu
-* Non-debug DLL symbols:: Support for DLLs without debugging symbols
+* Non-debug DLL Symbols:: Support for DLLs without debugging symbols
@end menu
-@node Non-debug DLL symbols
-@subsubsection Support for DLLs without debugging symbols
+@node Non-debug DLL Symbols
+@subsubsection Support for DLLs without Debugging Symbols
@cindex DLLs with no debugging symbols
@cindex Minimal symbols and DLLs
Very often on windows, some of the DLLs that your program relies on do
not include symbolic debugging information (for example,
-@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging
+@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging
symbols in a DLL, it relies on the minimal amount of symbolic
-information contained in the DLL's export table. This subsubsection
+information contained in the DLL's export table. This section
describes working with such symbols, known internally to @value{GDBN} as
``minimal symbols''.
Note that before the debugged program has started execution, no DLLs
-will have been loaded. The easiest way around this problem is simply to
+will have been loaded. The easiest way around this problem is simply to
start the program --- either by setting a breakpoint or letting the
-program run once to completion. It is also possible to force
+program run once to completion. It is also possible to force
@value{GDBN} to load a particular DLL before starting the executable ---
see the shared library information in @ref{Files}, or the
-@code{dll-symbols} command in @ref{Cygwin Native}. Currently,
+@code{dll-symbols} command in @ref{Cygwin Native}. Currently,
explicitly loading symbols from a DLL with no debugging information will
cause the symbol names to be duplicated in @value{GDBN}'s lookup table,
which may adversely affect symbol lookup performance.
-@subsubsection DLL name prefixes
+@subsubsection DLL Name Prefixes
In keeping with the naming conventions used by the Microsoft debugging
tools, DLL export symbols are made available with a prefix based on the
[etc...]
@end smallexample
-@subsubsection Working with minimal symbols
+@subsubsection Working with Minimal Symbols
Symbols extracted from a DLL's export table do not contain very much
type information. All that @value{GDBN} can do is guess whether a symbol
safe.
@node Hurd Native
-@subsection Commands specific to @sc{gnu} Hurd systems
+@subsection Commands Specific to @sc{gnu} Hurd Systems
@cindex @sc{gnu} Hurd debugging
This subsection describes @value{GDBN} commands specific to the
@value{GDBN} then attempts to read the symbol tables of any object modules
loaded into the VxWorks target since it was last booted. @value{GDBN} locates
these files by searching the directories listed in the command search
-path (@pxref{Environment, ,Your program's environment}); if it fails
+path (@pxref{Environment, ,Your Program's Environment}); if it fails
to find an object file, it displays a message such as:
@smallexample
command again.
@node VxWorks Download
-@subsubsection VxWorks download
+@subsubsection VxWorks Download
@cindex download to VxWorks
If you have connected to the VxWorks target and you want to debug an
table.)
@node VxWorks Attach
-@subsubsection Running tasks
+@subsubsection Running Tasks
@cindex running VxWorks tasks
You can also attach to an existing task using the @code{attach} command as
@menu
* ARM:: ARM RDI
-* H8/300:: Renesas H8/300
-* H8/500:: Renesas H8/500
* M32R/D:: Renesas M32R/D
* M68K:: Motorola M68K
* MIPS Embedded:: MIPS Embedded
* OpenRISC 1000:: OpenRisc 1000
* PA:: HP PA Embedded
-* PowerPC:: PowerPC
-* SH:: Renesas SH
+* PowerPC Embedded:: PowerPC Embedded
* Sparclet:: Tsqware Sparclet
* Sparclite:: Fujitsu Sparclite
* Z8000:: Zilog Z8000
* AVR:: Atmel AVR
* CRIS:: CRIS
* Super-H:: Renesas Super-H
-* WinCE:: Windows CE child processes
@end menu
@node ARM
@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.
@end table
-@node H8/300
-@subsection Renesas H8/300
-
-@table @code
-
-@kindex target hms@r{, with H8/300}
-@item target hms @var{dev}
-A Renesas SH, H8/300, or H8/500 board, attached via serial line to your host.
-Use special commands @code{device} and @code{speed} to control the serial
-line and the communications speed used.
-
-@kindex target e7000@r{, with H8/300}
-@item target e7000 @var{dev}
-E7000 emulator for Renesas H8 and SH.
-
-@kindex target sh3@r{, with H8/300}
-@kindex target sh3e@r{, with H8/300}
-@item target sh3 @var{dev}
-@itemx target sh3e @var{dev}
-Renesas SH-3 and SH-3E target systems.
-
-@end table
-
-@cindex download to H8/300 or H8/500
-@cindex H8/300 or H8/500 download
-@cindex download to Renesas SH
-@cindex Renesas SH download
-When you select remote debugging to a Renesas SH, H8/300, or H8/500
-board, the @code{load} command downloads your program to the Renesas
-board and also opens it as the current executable target for
-@value{GDBN} on your host (like the @code{file} command).
-
-@value{GDBN} needs to know these things to talk to your
-Renesas SH, H8/300, or H8/500:
-
-@enumerate
-@item
-that you want to use @samp{target hms}, the remote debugging interface
-for Renesas microprocessors, or @samp{target e7000}, the in-circuit
-emulator for the Renesas SH and the Renesas 300H. (@samp{target hms} is
-the default when @value{GDBN} is configured specifically for the Renesas SH,
-H8/300, or H8/500.)
-
-@item
-what serial device connects your host to your Renesas board (the first
-serial device available on your host is the default).
-
-@item
-what speed to use over the serial device.
-@end enumerate
-
-@menu
-* Renesas Boards:: Connecting to Renesas boards.
-* Renesas ICE:: Using the E7000 In-Circuit Emulator.
-* Renesas Special:: Special @value{GDBN} commands for Renesas micros.
-@end menu
-
-@node Renesas Boards
-@subsubsection Connecting to Renesas boards
-
-@c only for Unix hosts
-@kindex device
-@cindex serial device, Renesas micros
-Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you
-need to explicitly set the serial device. The default @var{port} is the
-first available port on your host. This is only necessary on Unix
-hosts, where it is typically something like @file{/dev/ttya}.
-
-@kindex speed
-@cindex serial line speed, Renesas micros
-@code{@value{GDBN}} has another special command to set the communications
-speed: @samp{speed @var{bps}}. This command also is only used from Unix
-hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with
-the DOS @code{mode} command (for instance,
-@w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection).
-
-The @samp{device} and @samp{speed} commands are available only when you
-use a Unix host to debug your Renesas microprocessor programs. If you
-use a DOS host,
-@value{GDBN} depends on an auxiliary terminate-and-stay-resident program
-called @code{asynctsr} to communicate with the development board
-through a PC serial port. You must also use the DOS @code{mode} command
-to set up the serial port on the DOS side.
-
-The following sample session illustrates the steps needed to start a
-program under @value{GDBN} control on an H8/300. The example uses a
-sample H8/300 program called @file{t.x}. The procedure is the same for
-the Renesas SH and the H8/500.
-
-First hook up your development board. In this example, we use a
-board attached to serial port @code{COM2}; if you use a different serial
-port, substitute its name in the argument of the @code{mode} command.
-When you call @code{asynctsr}, the auxiliary comms program used by the
-debugger, you give it just the numeric part of the serial port's name;
-for example, @samp{asyncstr 2} below runs @code{asyncstr} on
-@code{COM2}.
-
-@smallexample
-C:\H8300\TEST> asynctsr 2
-C:\H8300\TEST> mode com2:9600,n,8,1,p
-
-Resident portion of MODE loaded
-
-COM2: 9600, n, 8, 1, p
-
-@end smallexample
-
-@quotation
-@emph{Warning:} We have noticed a bug in PC-NFS that conflicts with
-@code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to
-disable it, or even boot without it, to use @code{asynctsr} to control
-your development board.
-@end quotation
-
-@kindex target hms@r{, and serial protocol}
-Now that serial communications are set up, and the development board is
-connected, you can start up @value{GDBN}. Call @code{@value{GDBN}} with
-the name of your program as the argument. @code{@value{GDBN}} prompts
-you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
-commands to begin your debugging session: @samp{target hms} to specify
-cross-debugging to the Renesas board, and the @code{load} command to
-download your program to the board. @code{load} displays the names of
-the program's sections, and a @samp{*} for each 2K of data downloaded.
-(If you want to refresh @value{GDBN} data on symbols or on the
-executable file without downloading, use the @value{GDBN} commands
-@code{file} or @code{symbol-file}. These commands, and @code{load}
-itself, are described in @ref{Files,,Commands to specify files}.)
-
-@smallexample
-(eg-C:\H8300\TEST) @value{GDBP} t.x
-@value{GDBN} is free software and you are welcome to distribute copies
- of it under certain conditions; type "show copying" to see
- the conditions.
-There is absolutely no warranty for @value{GDBN}; type "show warranty"
-for details.
-@value{GDBN} @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
-(@value{GDBP}) target hms
-Connected to remote H8/300 HMS system.
-(@value{GDBP}) load t.x
-.text : 0x8000 .. 0xabde ***********
-.data : 0xabde .. 0xad30 *
-.stack : 0xf000 .. 0xf014 *
-@end smallexample
-
-At this point, you're ready to run or debug your program. From here on,
-you can use all the usual @value{GDBN} commands. The @code{break} command
-sets breakpoints; the @code{run} command starts your program;
-@code{print} or @code{x} display data; the @code{continue} command
-resumes execution after stopping at a breakpoint. You can use the
-@code{help} command at any time to find out more about @value{GDBN} commands.
-
-Remember, however, that @emph{operating system} facilities aren't
-available on your development board; for example, if your program hangs,
-you can't send an interrupt---but you can press the @sc{reset} switch!
-
-Use the @sc{reset} button on the development board
-@itemize @bullet
-@item
-to interrupt your program (don't use @kbd{Ctrl-c} on the DOS host---it has
-no way to pass an interrupt signal to the development board); and
-
-@item
-to return to the @value{GDBN} command prompt after your program finishes
-normally. The communications protocol provides no other way for @value{GDBN}
-to detect program completion.
-@end itemize
-
-In either case, @value{GDBN} sees the effect of a @sc{reset} on the
-development board as a ``normal exit'' of your program.
-
-@node Renesas ICE
-@subsubsection Using the E7000 in-circuit emulator
-
-@kindex target e7000@r{, with Renesas ICE}
-You can use the E7000 in-circuit emulator to develop code for either the
-Renesas SH or the H8/300H. Use one of these forms of the @samp{target
-e7000} command to connect @value{GDBN} to your E7000:
-
-@table @code
-@item target e7000 @var{port} @var{speed}
-Use this form if your E7000 is connected to a serial port. The
-@var{port} argument identifies what serial port to use (for example,
-@samp{com2}). The third argument is the line speed in bits per second
-(for example, @samp{9600}).
-
-@item target e7000 @var{hostname}
-If your E7000 is installed as a host on a TCP/IP network, you can just
-specify its hostname; @value{GDBN} uses @code{telnet} to connect.
-@end table
-
-The following special commands are available when debugging with the
-Renesas E7000 ICE:
-
-@table @code
-@item e7000 @var{command}
-@kindex e7000
-@cindex send command to E7000 monitor
-This sends the specified @var{command} to the E7000 monitor.
-
-@item ftplogin @var{machine} @var{username} @var{password} @var{dir}
-@kindex ftplogin@r{, E7000}
-This command records information for subsequent interface with the
-E7000 monitor via the FTP protocol: @value{GDBN} will log into the
-named @var{machine} using specified @var{username} and @var{password},
-and then chdir to the named directory @var{dir}.
-
-@item ftpload @var{file}
-@kindex ftpload@r{, E7000}
-This command uses credentials recorded by @code{ftplogin} to fetch and
-load the named @var{file} from the E7000 monitor.
-
-@item drain
-@kindex drain@r{, E7000}
-This command drains any pending text buffers stored on the E7000.
-
-@item set usehardbreakpoints
-@itemx show usehardbreakpoints
-@kindex set usehardbreakpoints@r{, E7000}
-@kindex show usehardbreakpoints@r{, E7000}
-@cindex hardware breakpoints, and E7000
-These commands set and show the use of hardware breakpoints for all
-breakpoints. @xref{Set Breaks, hardware-assisted breakpoint}, for
-more information about using hardware breakpoints selectively.
-@end table
-
-@node Renesas Special
-@subsubsection Special @value{GDBN} commands for Renesas micros
-
-Some @value{GDBN} commands are available only for the H8/300:
-
-@table @code
-
-@kindex set machine
-@kindex show machine
-@item set machine h8300
-@itemx set machine h8300h
-Condition @value{GDBN} for one of the two variants of the H8/300
-architecture with @samp{set machine}. You can use @samp{show machine}
-to check which variant is currently in effect.
-
-@end table
-
-@node H8/500
-@subsection H8/500
-
-@table @code
-
-@kindex set memory @var{mod}
-@cindex memory models, H8/500
-@item set memory @var{mod}
-@itemx show memory
-Specify which H8/500 memory model (@var{mod}) you are using with
-@samp{set memory}; check which memory model is in effect with @samp{show
-memory}. The accepted values for @var{mod} are @code{small},
-@code{big}, @code{medium}, and @code{compact}.
-
-@end table
-
@node M32R/D
@subsection Renesas M32R/D and M32R/SDI
@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}
@end table
-@node SH
-@subsection Renesas SH
-
-@table @code
-
-@kindex target hms@r{, with Renesas SH}
-@item target hms @var{dev}
-A Renesas SH board attached via serial line to your host. Use special
-commands @code{device} and @code{speed} to control the serial line and
-the communications speed used.
-
-@kindex target e7000@r{, with Renesas SH}
-@item target e7000 @var{dev}
-E7000 emulator for Renesas SH.
-
-@kindex target sh3@r{, with SH}
-@kindex target sh3e@r{, with SH}
-@item target sh3 @var{dev}
-@item target sh3e @var{dev}
-Renesas SH-3 and SH-3E target systems.
-
-@end table
-
@node Sparclet
@subsection Tsqware Sparclet
@end menu
@node Sparclet File
-@subsubsection Setting file to debug
+@subsubsection Setting File to Debug
The @value{GDBN} command @code{file} lets you choose with program to debug.
files will be searched as well.
@value{GDBN} locates
the source files by searching the directories listed in the directory search
-path (@pxref{Environment, ,Your program's environment}).
+path (@pxref{Environment, ,Your Program's Environment}).
If it fails
to find a file, it displays a message such as:
@end smallexample
@node Sparclet Download
-@subsubsection Sparclet download
+@subsubsection Sparclet Download
@cindex download to Sparclet
Once connected to the Sparclet target,
to tell @value{GDBN} where to map the symbol table.
@node Sparclet Execution
-@subsubsection Running and debugging
+@subsubsection Running and Debugging
@cindex running and debugging Sparclet programs
You can now begin debugging the task using @value{GDBN}'s execution control
@item regs
@kindex regs@r{, Super-H}
Show the values of all Super-H registers.
-@end table
-
-@node WinCE
-@subsection Windows CE
-@cindex Windows CE
-
-The following commands are available for Windows CE:
-
-@table @code
-@item set remotedirectory @var{dir}
-@kindex set remotedirectory
-Tell @value{GDBN} to upload files from the named directory @var{dir}.
-The default is @file{/gdb}, i.e.@: the root directory on the current
-drive.
-@item show remotedirectory
-@kindex show remotedirectory
-Show the current value of the upload directory.
+@item set 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 set remoteupload @var{method}
-@kindex set remoteupload
-Set the method used to upload files to remote device. Valid values
-for @var{method} are @samp{always}, @samp{newer}, and @samp{never}.
-The default is @samp{newer}.
+@item show sh calling-convention
+@kindex show sh calling-convention
+Show the current calling convention setting.
-@item show remoteupload
-@kindex show remoteupload
-Show the current setting of the upload method.
-
-@item set remoteaddhost
-@kindex set remoteaddhost
-Tell @value{GDBN} whether to add this host to the remote stub's
-arguments when you debug over a network.
-
-@item show remoteaddhost
-@kindex show remoteaddhost
-Show whether to add this host to remote stub's arguments when
-debugging over a network.
@end table
* Alpha::
* MIPS::
* HPPA:: HP PA architecture
+* SPU:: Cell Broadband Engine SPU architecture
+* PowerPC::
@end menu
@node i386
-@subsection x86 Architecture-specific issues.
+@subsection x86 Architecture-specific Issues
@table @code
@item set struct-convention @var{mode}
programs:
@table @code
-@item set mips saved-gpreg-size @var{size}
-@kindex set mips saved-gpreg-size
-@cindex MIPS GP register size on stack
-Set the size of MIPS general-purpose registers saved on the stack.
-The argument @var{size} can be one of the following:
-
-@table @samp
-@item 32
-32-bit GP registers
-@item 64
-64-bit GP registers
-@item auto
-Use the target's default setting or autodetect the saved size from the
-information contained in the executable. This is the default
-@end table
-
-@item show mips saved-gpreg-size
-@kindex show mips saved-gpreg-size
-Show the current size of MIPS GP registers on the stack.
-
-@item set mips stack-arg-size @var{size}
-@kindex set mips stack-arg-size
-@cindex MIPS stack space for arguments
-Set the amount of stack space reserved for arguments to functions.
-The argument can be one of @code{"32"}, @code{"64"} or @code{"auto"}
-(the default).
-
@item set mips abi @var{arg}
@kindex set mips abi
@cindex set ABI for MIPS
@table @code
@item set debug hppa
@kindex set debug hppa
-This command determines whether HPPA architecture specific debugging
+This command determines whether HPPA architecture-specific debugging
messages are to be displayed.
@item show debug hppa
@end table
+@node SPU
+@subsection Cell Broadband Engine SPU architecture
+@cindex Cell Broadband Engine
+@cindex SPU
+
+When @value{GDBN} is debugging the Cell Broadband Engine SPU architecture,
+it provides the following special commands:
+
+@table @code
+@item info spu event
+@kindex info spu
+Display SPU event facility status. Shows current event mask
+and pending event status.
+
+@item info spu signal
+Display SPU signal notification facility status. Shows pending
+signal-control word and signal notification mode of both signal
+notification channels.
+
+@item info spu mailbox
+Display SPU mailbox facility status. Shows all pending entries,
+in order of processing, in each of the SPU Write Outbound,
+SPU Write Outbound Interrupt, and SPU Read Inbound mailboxes.
+
+@item info spu dma
+Display MFC DMA status. Shows all pending commands in the MFC
+DMA queue. For each entry, opcode, tag, class IDs, effective
+and local store addresses and transfer size are shown.
+
+@item info spu proxydma
+Display MFC Proxy-DMA status. Shows all pending commands in the MFC
+Proxy-DMA queue. For each entry, opcode, tag, class IDs, effective
+and local store addresses and transfer size are shown.
+
+@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.
+
+
@node Controlling GDB
@chapter Controlling @value{GDBN}
You can alter the way @value{GDBN} interacts with you by using the
@code{set} command. For commands controlling how @value{GDBN} displays
-data, see @ref{Print Settings, ,Print settings}. Other settings are
+data, see @ref{Print Settings, ,Print Settings}. Other settings are
described here.
@menu
@end table
@node Editing
-@section Command editing
+@section Command Editing
@cindex readline
@cindex command line editing
encouraged to read that chapter.
@node Command History
-@section Command history
+@section Command History
@cindex command history
@value{GDBN} can keep track of the commands you type during your
Interactively}, for the detailed description of the History library.
To issue a command to @value{GDBN} without affecting certain aspects of
-the state which is seen by users, prefix it with @samp{server }. This
+the state which is seen by users, prefix it with @samp{server }
+(@pxref{Server Prefix}). This
means that this command will not affect the command history, nor will it
affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
pressed on a line by itself.
@end table
@node Screen Size
-@section Screen size
+@section Screen Size
@cindex size of screen
@cindex pauses in output
@end table
@node ABI
-@section Configuring the current ABI
+@section Configuring the Current ABI
@value{GDBN} can determine the @dfn{ABI} (Application Binary Interface) of your
application automatically. However, sometimes you need to override its
@end table
@node Messages/Warnings
-@section Optional warnings and messages
+@section Optional Warnings and Messages
@cindex verbose operation
@cindex optional warnings
Currently, the messages controlled by @code{set verbose} are those
which announce that the symbol table for a source file is being read;
-see @code{symbol-file} in @ref{Files, ,Commands to specify files}.
+see @code{symbol-file} in @ref{Files, ,Commands to Specify Files}.
@table @code
@kindex set verbose
By default, if @value{GDBN} encounters bugs in the symbol table of an
object file, it is silent; but if you are debugging a compiler, you may
-find this information useful (@pxref{Symbol Errors, ,Errors reading
-symbol files}).
+find this information useful (@pxref{Symbol Errors, ,Errors Reading
+Symbol Files}).
@table @code
@end table
@node Debugging Output
-@section Optional messages about internal happenings
+@section Optional Messages about Internal Happenings
@cindex optional debugging messages
@value{GDBN} has commands that enable optional debugging messages from
module.
@item show debug aix-thread
Show the current state of AIX thread debugging info display.
+@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
@chapter Canned Sequences of Commands
Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
-command lists}), @value{GDBN} provides two ways to store sequences of
+Command Lists}), @value{GDBN} provides two ways to store sequences of
commands for execution as a unit: user-defined commands and command
files.
@end menu
@node Define
-@section User-defined commands
+@section User-defined Commands
@cindex user-defined command
@cindex arguments, to user-defined commands
messages when used in a user-defined command.
@node Hooks
-@section User-defined command hooks
+@section User-defined Command Hooks
@cindex command hooks
@cindex hooks, for commands
@cindex hooks, pre-command
get a warning from the @code{define} command.
@node Command Files
-@section Command files
+@section Command Files
@cindex command files
@cindex scripting commands
@node Output
-@section Commands for controlled output
+@section 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
@item output/@var{fmt} @var{expression}
Print the value of @var{expression} in format @var{fmt}. You can use
the same formats as for @code{print}. @xref{Output Formats,,Output
-formats}, for more information.
+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 Interpreters
* TUI Overview:: TUI overview
* TUI Keys:: TUI key bindings
* TUI Single Key Mode:: TUI single key mode
-* TUI Commands:: TUI specific commands
+* TUI Commands:: TUI-specific commands
* TUI Configuration:: TUI configuration variables
@end menu
-The @value{GDBN} Text User Interface, TUI in short, is a terminal
+The @value{GDBN} Text User Interface (TUI) is a terminal
interface which uses the @code{curses} library to show the source
file, the assembly output, the program registers and @value{GDBN}
-commands in separate text windows.
+commands in separate text windows. The TUI mode is supported only
+on platforms where a suitable version of the @code{curses} library
+is available.
-The TUI is enabled by invoking @value{GDBN} using either
-@pindex gdbtui
-@samp{gdbtui} or @samp{gdb -tui}.
+@pindex @value{GDBTUI}
+The TUI mode is enabled by default when you invoke @value{GDBN} as
+either @samp{@value{GDBTUI}} or @samp{@value{GDBP} -tui}.
+You can also switch in and out of TUI mode while @value{GDBN} runs by
+using various TUI commands and key bindings, such as @kbd{C-x C-a}.
+@xref{TUI Keys, ,TUI Key Bindings}.
@node TUI Overview
-@section TUI overview
-
-The TUI has two display modes that can be switched while
-@value{GDBN} runs:
-
-@itemize @bullet
-@item
-A curses (or TUI) mode in which it displays several text
-windows on the terminal.
-
-@item
-A standard mode which corresponds to the @value{GDBN} configured without
-the TUI.
-@end itemize
+@section TUI Overview
-In the TUI mode, @value{GDBN} can display several text window
-on the terminal:
+In TUI mode, @value{GDBN} can display several text windows:
@table @emph
@item command
This window is the @value{GDBN} command window with the @value{GDBN}
-prompt and the @value{GDBN} outputs. The @value{GDBN} input is still
-managed using readline but through the TUI. The @emph{command}
-window is always visible.
+prompt and the @value{GDBN} output. The @value{GDBN} input is still
+managed using readline.
@item source
The source window shows the source file of the program. The current
-line as well as active breakpoints are displayed in this window.
+line and active breakpoints are displayed in this window.
@item assembly
The assembly window shows the disassembly output of the program.
@item register
-This window shows the processor registers. It detects when
-a register is changed and when this is the case, registers that have
-changed are highlighted.
-
+This window shows the processor registers. Registers are highlighted
+when their values change.
@end table
The source and assembly windows show the current program position
-by highlighting the current line and marking them with the @samp{>} marker.
-Breakpoints are also indicated with two markers. A first one
+by highlighting the current line and marking it with a @samp{>} marker.
+Breakpoints are indicated with two markers. The first marker
indicates the breakpoint type:
@table @code
@item h
Hardware breakpoint which was never hit.
-
@end table
The second marker indicates whether the breakpoint is enabled or not:
@item -
Breakpoint is disabled.
-
@end table
-The source, assembly and register windows are attached to the thread
-and the frame position. They are updated when the current thread
-changes, when the frame changes or when the program counter changes.
-These three windows are arranged by the TUI according to several
-layouts. The layout defines which of these three windows are visible.
-The following layouts are available:
+The source, assembly and register windows are updated when the current
+thread changes, when the frame changes, or when the program counter
+changes.
+
+These windows are not all visible at the same time. The command
+window is always visible. The others can be arranged in several
+layouts:
@itemize @bullet
@item
-source
+source only,
@item
-assembly
+assembly only,
@item
-source and assembly
+source and assembly,
@item
-source and registers
+source and registers, or
@item
-assembly and registers
-
+assembly and registers.
@end itemize
-On top of the command window a status line gives various information
-concerning the current process begin debugged. The status line is
-updated when the information it shows changes. The following fields
-are displayed:
+A status line above the command window shows the following information:
@table @emph
@item target
-Indicates the current gdb target
+Indicates the current @value{GDBN} target.
(@pxref{Targets, ,Specifying a Debugging Target}).
@item process
-Gives information about the current process or thread number.
+Gives the current process or thread number.
When no process is being debugged, this field is set to @code{No process}.
@item function
Gives the current function name for the selected frame.
The name is demangled if demangling is turned on (@pxref{Print Settings}).
-When there is no symbol corresponding to the current program counter
+When there is no symbol corresponding to the current program counter,
the string @code{??} is displayed.
@item line
Indicates the current line number for the selected frame.
-When the current line number is not known the string @code{??} is displayed.
+When the current line number is not known, the string @code{??} is displayed.
@item pc
Indicates the current program counter address.
-
@end table
@node TUI Keys
@cindex TUI key bindings
The TUI installs several key bindings in the readline keymaps
-(@pxref{Command Line Editing}).
-They allow to leave or enter in the TUI mode or they operate
-directly on the TUI layout and windows. The TUI also provides
-a @emph{SingleKey} keymap which binds several keys directly to
-@value{GDBN} commands. The following key bindings
+(@pxref{Command Line Editing}). The following key bindings
are installed for both TUI mode and the @value{GDBN} standard mode.
@table @kbd
@itemx C-x a
@kindex C-x A
@itemx C-x A
-Enter or leave the TUI mode. When the TUI mode is left,
-the curses window management is left and @value{GDBN} operates using
-its standard mode writing on the terminal directly. When the TUI
-mode is entered, the control is given back to the curses windows.
+Enter or leave the TUI mode. When leaving the TUI mode,
+the curses window management stops and @value{GDBN} operates using
+its standard mode, writing on the terminal directly. When reentering
+the TUI mode, control is given back to the curses windows.
The screen is then refreshed.
@kindex C-x 1
@kindex C-x 2
@item C-x 2
Use a TUI layout with at least two windows. When the current
-layout shows already two windows, a next layout with two windows is used.
+layout already has two windows, the next layout with two windows is used.
When a new layout is chosen, one window will always be common to the
previous layout and the new one.
@kindex C-x o
@item C-x o
Change the active window. The TUI associates several key bindings
-(like scrolling and arrow keys) to the active window. This command
+(like scrolling and arrow keys) with the active window. This command
gives the focus to the next TUI window.
Think of it as the Emacs @kbd{C-x o} binding.
@kindex C-x s
@item C-x s
-Use the TUI @emph{SingleKey} keymap that binds single key to gdb commands
-(@pxref{TUI Single Key Mode}).
-
+Switch in and out of the TUI SingleKey mode that binds single
+keys to @value{GDBN} commands (@pxref{TUI Single Key Mode}).
@end table
-The following key bindings are handled only by the TUI mode:
+The following key bindings only work in the TUI mode:
-@table @key
+@table @asis
@kindex PgUp
-@item PgUp
+@item @key{PgUp}
Scroll the active window one page up.
@kindex PgDn
-@item PgDn
+@item @key{PgDn}
Scroll the active window one page down.
@kindex Up
-@item Up
+@item @key{Up}
Scroll the active window one line up.
@kindex Down
-@item Down
+@item @key{Down}
Scroll the active window one line down.
@kindex Left
-@item Left
+@item @key{Left}
Scroll the active window one column left.
@kindex Right
-@item Right
+@item @key{Right}
Scroll the active window one column right.
@kindex C-L
-@item C-L
+@item @kbd{C-L}
Refresh the screen.
-
@end table
-In the TUI mode, the arrow keys are used by the active window
-for scrolling. This means they are available for readline when the
-active window is the command window. When the command window
-does not have the focus, it is necessary to use other readline
-key bindings such as @kbd{C-p}, @kbd{C-n}, @kbd{C-b} and @kbd{C-f}.
+Because the arrow keys scroll the active window in the TUI mode, they
+are not available for their normal use by readline unless the command
+window has the focus. When another window is active, you must use
+other readline key bindings such as @kbd{C-p}, @kbd{C-n}, @kbd{C-b}
+and @kbd{C-f} to control the command window.
@node TUI Single Key Mode
@section TUI Single Key Mode
@cindex TUI single key mode
-The TUI provides a @emph{SingleKey} mode in which it installs a particular
-key binding in the readline keymaps to connect single keys to
-some gdb commands.
+The TUI also provides a @dfn{SingleKey} mode, which binds several
+frequently used @value{GDBN} commands to single keys. Type @kbd{C-x s} to
+switch into this mode, where the following key bindings are used:
@table @kbd
@kindex c @r{(SingleKey TUI key)}
@kindex q @r{(SingleKey TUI key)}
@item q
-exit the @emph{SingleKey} mode.
+exit the SingleKey mode.
@kindex r @r{(SingleKey TUI key)}
@item r
@kindex w @r{(SingleKey TUI key)}
@item w
where
-
@end table
Other keys temporarily switch to the @value{GDBN} command prompt.
The key that was pressed is inserted in the editing buffer so that
it is possible to type most @value{GDBN} commands without interaction
-with the TUI @emph{SingleKey} mode. Once the command is entered the TUI
-@emph{SingleKey} mode is restored. The only way to permanently leave
+with the TUI SingleKey mode. Once the command is entered the TUI
+SingleKey mode is restored. The only way to permanently leave
this mode is by typing @kbd{q} or @kbd{C-x s}.
@node TUI Commands
-@section TUI specific commands
+@section TUI-specific Commands
@cindex TUI commands
The TUI has specific commands to control the text windows.
-These commands are always available, that is they do not depend on
-the current terminal mode in which @value{GDBN} runs. When @value{GDBN}
-is in the standard mode, using these commands will automatically switch
-in the TUI mode.
+These commands are always available, even when @value{GDBN} is not in
+the TUI mode. When @value{GDBN} is in the standard mode, most
+of these commands will automatically switch to the TUI mode.
@table @code
@item info win
@item layout regs
Display the register window together with the source or assembly window.
-@item focus next | prev | src | asm | regs | split
+@item focus next
@kindex focus
-Set the focus to the named window.
-This command allows to change the active window so that scrolling keys
-can be affected to another window.
+Make the next window active for scrolling.
+
+@item focus prev
+Make the previous window active for scrolling.
+
+@item focus src
+Make the source window active for scrolling.
+
+@item focus asm
+Make the assembly window active for scrolling.
+
+@item focus regs
+Make the register window active for scrolling.
+
+@item focus cmd
+Make the command window active for scrolling.
@item refresh
@kindex refresh
lines. Positive counts increase the height, while negative counts
decrease it.
-@item tabset
-@kindex tabset @var{nchars}
+@item tabset @var{nchars}
+@kindex tabset
Set the width of tab stops to be @var{nchars} characters.
-
@end table
@node TUI Configuration
-@section TUI configuration variables
+@section TUI Configuration Variables
@cindex TUI configuration variables
-The TUI has several configuration variables that control the
-appearance of windows on the terminal.
+Several configuration variables control the appearance of TUI windows.
@table @code
@item set tui border-kind @var{kind}
Use a space character to draw the border.
@item ascii
-Use ascii characters + - and | to draw the border.
+Use @sc{ascii} characters @samp{+}, @samp{-} and @samp{|} to draw the border.
@item acs
Use the Alternate Character Set to draw the border. The border is
drawn using character line graphics if the terminal supports them.
-
@end table
-@item set tui active-border-mode @var{mode}
-@kindex set tui active-border-mode
-Select the attributes to display the border of the active window.
-The possible values are @code{normal}, @code{standout}, @code{reverse},
-@code{half}, @code{half-standout}, @code{bold} and @code{bold-standout}.
-
@item set tui border-mode @var{mode}
@kindex set tui border-mode
-Select the attributes to display the border of other windows.
-The @var{mode} can be one of the following:
+@itemx set tui active-border-mode @var{mode}
+@kindex set tui active-border-mode
+Select the display attributes for the borders of the inactive windows
+or the active window. The @var{mode} can be one of the following:
@table @code
@item normal
Use normal attributes to display the border.
@item bold-standout
Use extra bright or bold and standout mode.
-
@end table
-
@end table
@node Emacs
created Emacs buffer.
@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
-Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
+Running @value{GDBN} under Emacs can be just like running @value{GDBN} normally except for two
things:
@itemize @bullet
@item
-All ``terminal'' input and output goes through the Emacs buffer.
-@end itemize
+All ``terminal'' input and output goes through an Emacs buffer, called
+the GUD buffer.
This applies both to @value{GDBN} commands and their output, and to the input
and output done by the program you are debugging.
way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
stop.
-@itemize @bullet
@item
@value{GDBN} displays source code through Emacs.
-@end itemize
Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
source file for that frame and puts an arrow (@samp{=>}) at the
Explicit @value{GDBN} @code{list} or search commands still produce output as
usual, but you probably have no reason to use them from Emacs.
+@end itemize
+
+We call this @dfn{text command mode}. Emacs 22.1, and later, also uses
+a graphical mode, enabled by default, which provides further buffers
+that can control the execution and describe the state of your program.
+@xref{GDB Graphical Interface,,, Emacs, The @sc{gnu} Emacs Manual}.
If you specify an absolute file name when prompted for the @kbd{M-x
gdb} argument, then Emacs sets your current working directory to where
buffer does not display the current source and line of execution.
The initial working directory of @value{GDBN} is printed on the top
-line of the @value{GDBN} I/O buffer and this serves as a default for
-the commands that specify files for @value{GDBN} to operate
-on. @xref{Files, ,Commands to specify files}.
+line of the GUD buffer and this serves as a default for the commands
+that specify files for @value{GDBN} to operate on. @xref{Files,
+,Commands to Specify Files}.
By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you
need to call @value{GDBN} by a different name (for example, if you
customize the Emacs variable @code{gud-gdb-command-name} to run the
one you want.
-In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
+In the GUD buffer, you can use these special Emacs commands in
addition to the standard Shell mode commands:
@table @kbd
@item C-h m
-Describe the features of Emacs' @value{GDBN} Mode.
+Describe the features of Emacs' GUD Mode.
@item C-c C-s
Execute to another source line, like the @value{GDBN} @code{step} command; also
In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break})
tells @value{GDBN} to set a breakpoint on the source line point is on.
-If you type @kbd{M-x speedbar}, then Emacs displays a separate frame which
-shows a backtrace when the @value{GDBN} I/O buffer is current. Move
-point to any frame in the stack and type @key{RET} to make it become the
-current frame and display the associated source in the source buffer.
-Alternatively, click @kbd{Mouse-2} to make the selected frame become the
-current one.
+In text command mode, if you type @kbd{M-x speedbar}, Emacs displays a
+separate frame which shows a backtrace when the GUD buffer is current.
+Move point to any frame in the stack and type @key{RET} to make it
+become the current frame and display the associated source in the
+source buffer. Alternatively, click @kbd{Mouse-2} to make the
+selected frame become the current one. In graphical mode, the
+speedbar displays watch expressions.
If you accidentally delete the source-display buffer, an easy way to get
it back is to type the command @code{f} in the @value{GDBN} buffer, to
delete lines from the text, the line numbers that @value{GDBN} knows cease
to correspond properly with the code.
-The description given here is for GNU Emacs version 21.3 and a more
-detailed description of its interaction with @value{GDBN} is given in
-the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} Emacs Manual}).
+A more detailed description of Emacs' interaction with @value{GDBN} is
+given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu}
+Emacs Manual}).
@c The following dropped because Epoch is nonstandard. Reactivate
@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
* GDB/MI Signal Handling Commands::
@end ignore
* GDB/MI Target Manipulation::
+* GDB/MI File Transfer Commands::
* GDB/MI Miscellaneous Commands::
@end menu
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}
Note the line breaks shown in the examples are here only for
readability, they don't appear in the real output.
-@subheading Setting a breakpoint
+@subheading Setting a Breakpoint
Setting a breakpoint generates synchronous output which contains detailed
information of the breakpoint.
-> -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
Delete the breakpoint(s) whose number(s) are specified in the argument
list. This is obviously reflected in the breakpoint list.
-@subsubheading @value{GDBN} command
+@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{delete}.
@c REDUNDANT???
Get information about a single breakpoint.
-@subsubheading @value{GDBN} command
+@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
@subsubheading Synopsis
@smallexample
- -break-insert [ -t ] [ -h ] [ -r ]
+ -break-insert [ -t ] [ -h ] [ -f ]
[ -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.
@end table
@subsubheading Result
trigger only when the memory location is accessed for reading. Without
either of the options, the watchpoint created is a regular watchpoint,
i.e., it will trigger when the memory location is accessed for writing.
-@xref{Set Watchpoints, , Setting watchpoints}.
+@xref{Set Watchpoints, , Setting Watchpoints}.
Note that @samp{-break-list} will report a single list of watchpoints and
breakpoints inserted.
Show the current working directory.
-@subsubheading @value{GDBN} command
+@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{pwd}.
@subsubheading Synopsis
@smallexample
- -thread-info
+ -thread-info [ @var{thread-id} ]
@end smallexample
-@subsubheading @value{GDBN} command
-
-No equivalent.
-
-@subsubheading Example
-N.A.
-
-
-@subheading The @code{-thread-list-all-threads} Command
-@findex -thread-list-all-threads
-
-@subsubheading Synopsis
-
-@smallexample
- -thread-list-all-threads
-@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
-The equivalent @value{GDBN} command is @samp{info threads}.
+The @samp{info thread} command prints the same information
+about all threads.
@subsubheading Example
-N.A.
+@smallexample
+-thread-info
+^done,threads=[
+@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
+ frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},
+@{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"@}@}],
+current-thread-id="1"
+(gdb)
+@end smallexample
@subheading The @code{-thread-list-ids} Command
@findex -thread-list-ids
^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
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)
a number of child variable objects, for example corresponding to each
element of a structure. A child variable object can itself have
children, recursively. Recursion ends when we reach
-leaf variable objects, which always have built-in types.
+leaf variable objects, which always have built-in types. Child variable
+objects are created only by explicit request, so if a frontend
+is not interested in the children of a particular variable object, no
+child will be created.
For a leaf variable object it is possible to obtain its value as a
string, or set the value from a string. String value can be also
the program stops. Instead, MI provides an update command that lists all
variable objects whose values has changed since the last update
operation. This considerably reduces the amount of data that must
-be transferred to the frontend.
+be transferred to the frontend. As noted above, children variable
+objects are created on demand, and only leaf variable objects have a
+real value. As result, gdb will read target memory only for leaf
+variables that frontend has created.
+
+The automatic update is not always desirable. For example, a frontend
+might want to keep a value of some expression for future reference,
+and never update it. For another example, fetching memory is
+relatively slow for embedded targets, so a frontend might want
+to disable automatic update for the variables that are either not
+visible on the screen, or ``closed''. This is possible using so
+called ``frozen variable objects''. Such variable objects are never
+implicitly updated.
The following is the complete set of @sc{gdb/mi} operations defined to
access this functionality:
@item @code{-var-info-type}
@tab show the type of this variable object
@item @code{-var-info-expression}
-@tab print what this variable object represents
+@tab print parent-relative expression that this variable object represents
+@item @code{-var-info-path-expression}
+@tab print full expression that this variable object represents
@item @code{-var-show-attributes}
@tab is this variable editable? does it exist here?
@item @code{-var-evaluate-expression}
@tab set the value of this variable
@item @code{-var-update}
@tab update the variable and its children
+@item @code{-var-set-frozen}
+@tab set frozeness attribute
@end multitable
In the next subsection we describe each operation in detail and suggest
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
-var-info-expression @var{name}
@end smallexample
-Returns what is represented by the variable object @var{name}:
+Returns a string that is suitable for presenting this
+variable object in user interface. The string is generally
+not valid expression in the current language, and cannot be evaluated.
+
+For example, if @code{a} is an array, and variable object
+@code{A} was created for @code{a}, then we'll get this output:
@smallexample
- lang=@var{lang-spec},exp=@var{expression}
+(gdb) -var-info-expression A.1
+^done,lang="C",exp="1"
@end smallexample
@noindent
-where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
+Here, the values of @code{lang} can be @code{@{"C" | "C++" | "Java"@}}.
+
+Note that the output of the @code{-var-list-children} command also
+includes those expressions, so the @code{-var-info-expression} command
+is of limited use.
+
+@subheading The @code{-var-info-path-expression} Command
+@findex -var-info-path-expression
+
+@subsubheading Synopsis
+
+@smallexample
+ -var-info-path-expression @var{name}
+@end smallexample
+
+Returns an expression that can be evaluated in the current
+context and will yield the same value that a variable object has.
+Compare this with the @code{-var-info-expression} command, which
+result can be used only for UI presentation. Typical use of
+the @code{-var-info-path-expression} command is creating a
+watchpoint from a variable object.
+
+For example, suppose @code{C} is a C@t{++} class, derived from class
+@code{Base}, and that the @code{Base} class has a member called
+@code{m_size}. Assume a variable @code{c} is has the type of
+@code{C} and a variable object @code{C} was created for variable
+@code{c}. Then, we'll get this output:
+@smallexample
+(gdb) -var-info-path-expression C.Base.public.m_size
+^done,path_expr=((Base)c).m_size)
+@end smallexample
@subheading The @code{-var-show-attributes} Command
@findex -var-show-attributes
@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}
be a root variable object. Here, ``changed'' means that the result of
@code{-var-evaluate-expression} before and after the
@code{-var-update} is different. If @samp{*} is used as the variable
-object names, all existing variable objects are updated. The option
+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.
(gdb)
@end smallexample
-@anchor{-var-update}
+@anchor{-var-update}
The field in_scope may take three values:
@table @code
In the future new values may be added to this list so the front should
be prepared for this possibility. @xref{GDB/MI Development and Front Ends, ,@sc{GDB/MI} Development and Front Ends}.
+@subheading The @code{-var-set-frozen} Command
+@findex -var-set-frozen
+@anchor{-var-set-frozen}
+
+@subsubheading Synopsis
+
+@smallexample
+ -var-set-frozen @var{name} @var{flag}
+@end smallexample
+
+Set the frozenness flag on the variable object @var{name}. The
+@var{flag} parameter should be either @samp{1} to make the variable
+frozen or @samp{0} to make it unfrozen. If a variable object is
+frozen, then neither itself, nor any of its children, are
+implicitly updated by @code{-var-update} of
+a parent variable or by @code{-var-update *}. Only
+@code{-var-update} of the variable itself will update its value and
+values of its children. After a variable object is unfrozen, it is
+implicitly updated by all subsequent @code{-var-update} operations.
+Unfreezing a variable does not update it, only subsequent
+@code{-var-update} does.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-var-set-frozen V 1
+^done
+(gdb)
+@end smallexample
+
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Data Manipulation
@section @sc{gdb/mi} Data Manipulation
@c REMOVED FROM THE INTERFACE.
@c @subheading -data-assign
@c Change the value of a program variable. Plenty of side effects.
-@c @subsubheading GDB command
+@c @subsubheading GDB Command
@c set variable
@c @subsubheading Example
@c N.A.
^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",
@item @var{word-format}
The format to be used to print the memory words. The notation is the
same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
-,Output formats}).
+,Output Formats}).
@item @var{word-size}
The size of each memory word in bytes.
@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
Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
-@subsubheading @value{GDBN} command
+@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{attach}.
Detach from the remote target which normally resumes its execution.
There's no output.
-@subsubheading @value{GDBN} command
+@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{detach}.
Disconnect from the remote target. There's no output and the target is
generally not resumed.
-@subsubheading @value{GDBN} command
+@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{disconnect}.
The type of target, for instance @samp{async}, @samp{remote}, etc.
@item @var{parameters}
Device names, host names and the like. @xref{Target Commands, ,
-Commands for managing targets}, for more details.
+Commands for Managing Targets}, for more details.
@end table
The output is a connection notification, followed by the address at
(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-put} 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{remote delete}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-target-file-delete remotefile
+^done
+(gdb)
+@end smallexample
+
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Miscellaneous Commands
@section Miscellaneous @sc{gdb/mi} Commands
Show the current value of a @value{GDBN} variable.
-@subsubheading @value{GDBN} command
+@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{show}.
(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:
+
+@itemize @minus
+@item
+@samp{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
+@samp{pending-breakpoints}---indicates presence of the @code{-f}
+option to the @code{-break-insert} command.
+@item
+@samp{thread-info}---indicates presence of the @code{-thread-info} command.
+
+@end itemize
+
@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"@}
@menu
* Annotations Overview:: What annotations are; the general syntax.
+* Server Prefix:: Issuing a command without affecting user state.
* Prompting:: Annotations marking @value{GDBN}'s need for input.
* Errors:: Annotations for error messages.
* Invalidation:: Some annotations describe things now invalid.
denotes a @samp{control-z} character) are annotations; the rest is
output from @value{GDBN}.
+@node Server Prefix
+@section The Server Prefix
+@cindex server prefix
+
+If you prefix a command with @samp{server } then it will not affect
+the command history, nor will it affect @value{GDBN}'s notion of which
+command to repeat if @key{RET} is pressed on a line by itself. This
+means that commands can be run behind a user's back by a front-end in
+a transparent manner.
+
+The server prefix does not affect the recording of values into the value
+history; to print a value without recording it into the value history,
+use the @code{output} command instead of the @code{print} command.
+
@node Prompting
@section Annotation for @value{GDBN} Input
@end menu
@node Bug Criteria
-@section Have you found a bug?
+@section Have You Found a Bug?
@cindex bug criteria
If you are not sure whether you have found a bug, here are some guidelines:
@end itemize
@node Bug Reporting
-@section How to report bugs
+@section How to Report Bugs
@cindex bug reports
@cindex @value{GDBN} bugs, reporting
@menu
* Requirements:: Requirements for building @value{GDBN}
-* Running Configure:: Invoking the @value{GDBN} @code{configure} script
+* Running Configure:: Invoking the @value{GDBN} @file{configure} script
* Separate Objdir:: Compiling @value{GDBN} in another directory
* Config Names:: Specifying names for hosts and targets
* Configure Options:: Summary of options for configure
@end menu
@node Requirements
-@section Requirements for building @value{GDBN}
+@section Requirements for Building @value{GDBN}
@cindex building @value{GDBN}, requirements for
Building @value{GDBN} requires various tools and packages to be available.
Other packages will be used only if they are found.
-@heading Tools/packages necessary for building @value{GDBN}
+@heading Tools/Packages Necessary for Building @value{GDBN}
@table @asis
@item ISO C90 compiler
@value{GDBN} is written in ISO C90. It should be buildable with any
@end table
-@heading Tools/packages optional for building @value{GDBN}
+@heading Tools/Packages Optional for Building @value{GDBN}
@table @asis
@item Expat
@anchor{Expat}
@value{GDBN} can use the Expat XML parsing library. This library may be
included with your operating system distribution; if it is not, you
can get the latest version from @url{http://expat.sourceforge.net}.
-The @code{configure} script will search for this library in several
+The @file{configure} script will search for this library in several
standard locations; if it is installed in an unusual path, you can
use the @option{--with-libexpat-prefix} option to specify its location.
-Expat is used for remote protocol memory maps (@pxref{Memory map format})
-and for target descriptions (@pxref{Target Descriptions}).
+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
@node Running Configure
-@section Invoking the @value{GDBN} @code{configure} script
+@section Invoking the @value{GDBN} @file{configure} Script
@cindex configuring @value{GDBN}
-@value{GDBN} comes with a @code{configure} script that automates the process
+@value{GDBN} comes with a @file{configure} script that automates the process
of preparing @value{GDBN} for installation; you can then use @code{make} to
build the @code{gdb} program.
@iftex
source for the @sc{gnu} memory-mapped malloc package
@end table
-The simplest way to configure and build @value{GDBN} is to run @code{configure}
+The simplest way to configure and build @value{GDBN} is to run @file{configure}
from the @file{gdb-@var{version-number}} source directory, which in
this example is the @file{gdb-@value{GDBVN}} directory.
First switch to the @file{gdb-@var{version-number}} source directory
-if you are not already in it; then run @code{configure}. Pass the
+if you are not already in it; then run @file{configure}. Pass the
identifier for the platform on which @value{GDBN} will run as an
argument.
@noindent
where @var{host} is an identifier such as @samp{sun4} or
@samp{decstation}, that identifies the platform where @value{GDBN} will run.
-(You can often leave off @var{host}; @code{configure} tries to guess the
+(You can often leave off @var{host}; @file{configure} tries to guess the
correct value by examining your system.)
Running @samp{configure @var{host}} and then running @code{make} builds the
binaries, are left in the corresponding source directories.
@need 750
-@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
+@file{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
system does not recognize this automatically when you run a different
shell, you may need to run @code{sh} on it explicitly:
sh configure @var{host}
@end smallexample
-If you run @code{configure} from a directory that contains source
+If you run @file{configure} from a directory that contains source
directories for multiple libraries or programs, such as the
-@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure}
+@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN},
+@file{configure}
creates configuration files for every directory level underneath (unless
you tell it not to, with the @samp{--norecursion} option).
-You should run the @code{configure} script from the top directory in the
+You should run the @file{configure} script from the top directory in the
source tree, the @file{gdb-@var{version-number}} directory. If you run
-@code{configure} from one of the subdirectories, you will configure only
+@file{configure} from one of the subdirectories, you will configure only
that subdirectory. That is usually not what you want. In particular,
-if you run the first @code{configure} from the @file{gdb} subdirectory
+if you run the first @file{configure} from the @file{gdb} subdirectory
of the @file{gdb-@var{version-number}} directory, you will omit the
configuration of @file{bfd}, @file{readline}, and other sibling
directories of the @file{gdb} subdirectory. This leads to build errors
let @value{GDBN} debug child processes whose programs are not readable.
@node Separate Objdir
-@section Compiling @value{GDBN} in another directory
+@section Compiling @value{GDBN} in Another Directory
If you want to run @value{GDBN} versions for several host or target machines,
you need a different @code{gdb} compiled for each combination of
-host and target. @code{configure} is designed to make this easy by
+host and target. @file{configure} is designed to make this easy by
allowing you to generate each configuration in a separate subdirectory,
rather than in the source directory. If your @code{make} program
handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
@code{make} in each of these directories builds the @code{gdb}
program specified there.
-To build @code{gdb} in a separate directory, run @code{configure}
+To build @code{gdb} in a separate directory, run @file{configure}
with the @samp{--srcdir} option to specify where to find the source.
-(You also need to specify a path to find @code{configure}
-itself from your working directory. If the path to @code{configure}
+(You also need to specify a path to find @file{configure}
+itself from your working directory. If the path to @file{configure}
would be the same as the argument to @samp{--srcdir}, you can leave out
the @samp{--srcdir} option; it is assumed.)
@end group
@end smallexample
-When @code{configure} builds a configuration using a remote source
+When @file{configure} builds a configuration using a remote source
directory, it creates a tree for the binaries with the same structure
(and using the same names) as the tree under the source directory. In
the example, you'd find the Sun 4 library @file{libiberty.a} in the
@value{GDBN} runs on one machine---the @dfn{host}---while debugging
programs that run on another machine---the @dfn{target}).
You specify a cross-debugging target by
-giving the @samp{--target=@var{target}} option to @code{configure}.
+giving the @samp{--target=@var{target}} option to @file{configure}.
When you run @code{make} to build a program or library, you must run
it in a configured directory---whatever directory you were in when you
-called @code{configure} (or one of its subdirectories).
+called @file{configure} (or one of its subdirectories).
-The @code{Makefile} that @code{configure} generates in each source
+The @code{Makefile} that @file{configure} generates in each source
directory also runs recursively. If you type @code{make} in a source
directory such as @file{gdb-@value{GDBVN}} (or in a separate configured
directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you
with each other.
@node Config Names
-@section Specifying names for hosts and targets
+@section Specifying Names for Hosts and Targets
-The specifications used for hosts and targets in the @code{configure}
+The specifications used for hosts and targets in the @file{configure}
script are based on a three-part naming scheme, but some short predefined
aliases are also supported. The full naming scheme encodes three pieces
of information in the following pattern:
or as the value for @var{target} in a @code{--target=@var{target}}
option. The equivalent full name is @samp{sparc-sun-sunos4}.
-The @code{configure} script accompanying @value{GDBN} does not provide
+The @file{configure} script accompanying @value{GDBN} does not provide
any query facility to list all supported host and target names or
-aliases. @code{configure} calls the Bourne shell script
+aliases. @file{configure} calls the Bourne shell script
@code{config.sub} to map abbreviations to full names; you can read the
script, if you wish, or you can use it to test your guesses on
abbreviations---for example:
directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
@node Configure Options
-@section @code{configure} options
+@section @file{configure} Options
-Here is a summary of the @code{configure} options and arguments that
-are most often useful for building @value{GDBN}. @code{configure} also has
+Here is a summary of the @file{configure} options and arguments that
+are most often useful for building @value{GDBN}. @file{configure} also has
several other options not listed here. @inforef{What Configure
-Does,,configure.info}, for a full explanation of @code{configure}.
+Does,,configure.info}, for a full explanation of @file{configure}.
@smallexample
configure @r{[}--help@r{]}
@table @code
@item --help
-Display a quick summary of how to invoke @code{configure}.
+Display a quick summary of how to invoke @file{configure}.
@item --prefix=@var{dir}
Configure the source to install programs and files under directory
Use this option to make configurations in directories separate from the
@value{GDBN} source directories. Among other things, you can use this to
build (or maintain) several configurations simultaneously, in separate
-directories. @code{configure} writes configuration specific files in
+directories. @file{configure} writes configuration-specific files in
the current directory, but arranges for them to use the source in the
-directory @var{dirname}. @code{configure} creates directories under
+directory @var{dirname}. @file{configure} creates directories under
the working directory in parallel to the source directories below
@var{dirname}.
@item --norecursion
-Configure only the directory level where @code{configure} is executed; do not
+Configure only the directory level where @file{configure} is executed; do not
propagate configuration to subdirectories.
@item --target=@var{target}
@end table
+@kindex maint set can-use-displaced-stepping
+@kindex maint show can-use-displaced-stepping
+@cindex displaced stepping support
+@cindex out-of-line single-stepping
+@item maint set can-use-displaced-stepping
+@itemx maint show can-use-displaced-stepping
+Control whether or not @value{GDBN} will do @dfn{displaced stepping}
+if the target supports it. The default is on. 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.
+
@kindex maint check-symtabs
@item maint check-symtabs
Check the consistency of psymtabs and symtabs.
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 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 show-debug-regs
@cindex x86 hardware debug registers
@item maint show-debug-regs
* General Query Packets::
* Register Packet Format::
* Tracepoint Packets::
+* Host I/O Packets::
* Interrupts::
* Examples::
-* File-I/O remote protocol extension::
-* Memory map format::
+* File-I/O Remote Protocol Extension::
+* Library List Format::
+* Memory Map Format::
@end menu
@node Overview
recognizes a packet meant for @value{GDBN}.
In the examples below, @samp{->} and @samp{<-} are used to indicate
-transmitted and received data respectfully.
+transmitted and received data, respectively.
@cindex protocol, @value{GDBN} remote serial
@cindex serial protocol, @value{GDBN} remote
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.
The following table provides a complete list of all currently defined
@var{command}s and their corresponding response @var{data}.
-@xref{File-I/O remote protocol extension}, for details about the File
+@xref{File-I/O Remote Protocol Extension}, for details about the File
I/O extension of the remote protocol.
Each packet's description has a template showing the packet's overall
@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.
@cindex @samp{F} packet
A reply from @value{GDBN} to an @samp{F} packet sent by the target.
This is part of the File-I/O protocol extension. @xref{File-I/O
-remote protocol extension}, for the specification.
+Remote Protocol Extension}, for the specification.
@item g
@anchor{read registers packet}
Each byte of register data is described by two hex digits. The bytes
with the register are transmitted in target byte order. The size of
each register and their position within the @samp{g} packet are
-determined by the @value{GDBN} internal macros
-@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{REGISTER_NAME} macros. The
+determined by the @value{GDBN} internal gdbarch functions
+@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}. The
specification of several standard @samp{g} packets is specified below.
@item E @var{NN}
for an error.
@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.
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 vAttach;@var{pid}
+@cindex @samp{vAttach} packet
+Attach to a new process with the specified process ID. @var{pid} is a
+hexadecimal integer identifying the process. If the stub is currently
+controlling a process, it is killed. The attached process is stopped.
+
+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 vCont@r{[};@var{action}@r{[}:@var{tid}@r{]]}@dots{}
@cindex @samp{vCont} packet
Resume the inferior, specifying different actions for each thread.
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
@var{addr}. The region may enclose any number of flash blocks, but
its start and end must fall on block boundaries, as indicated by the
-flash block size appearing in the memory map (@pxref{Memory map
-format}). @value{GDBN} groups flash memory programming operations
+flash block size appearing in the memory map (@pxref{Memory Map
+Format}). @value{GDBN} groups flash memory programming operations
together, and sends a @samp{vFlashDone} request after each group; the
stub is allowed to delay erase operation until the @samp{vFlashDone}
packet is received.
regions of flash memory are unpredictable until the @samp{vFlashDone}
request is completed.
+@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. If the stub is currently controlling a process, it is killed.
+
+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 X @var{addr},@var{length}:@var{XX@dots{}}
@anchor{X packet}
@cindex @samp{X} packet
and other information directly in the stop reply packet, reducing
round-trip latency. Single-step and breakpoint traps are reported
this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows:
-@enumerate
+
+@itemize @bullet
@item
If @var{n} is a hexadecimal number, it is a register number, and the
corresponding @var{r} gives that register's value. @var{r} is a
series of bytes in target byte order, with each byte given by a
two-digit hex number.
+
@item
If @var{n} is @samp{thread}, then @var{r} is the thread process ID, in
hex.
+
@item
-If @var{n} is @samp{watch}, @samp{rwatch}, or @samp{awatch}, then the
-packet indicates a watchpoint hit, and @var{r} is the data address, in
-hex.
+If @var{n} is a recognized @dfn{stop reason}, it describes a more
+specific event that stopped the target. The currently defined stop
+reasons are listed below. @var{aa} should be @samp{05}, the trap
+signal. At most one stop reason should be present.
+
@item
Otherwise, @value{GDBN} should ignore this @samp{@var{n}:@var{r}} pair
and go on to the next; this allows us to extend the protocol in the
future.
-@end enumerate
+@end itemize
+
+The currently defined stop reasons are:
+
+@table @samp
+@item watch
+@itemx rwatch
+@itemx awatch
+The packet indicates a watchpoint hit, and @var{r} is the data address, in
+hex.
+
+@cindex shared library events, remote reply
+@item library
+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.
+@end table
@item W @var{AA}
The process exited, and @var{AA} is the exit status. This is only
@var{call-id} is the identifier which says which host system call should
be called. This is just the name of the function. Translation into the
correct system call is only applicable as it's defined in @value{GDBN}.
-@xref{File-I/O remote protocol extension}, for a list of implemented
+@xref{File-I/O Remote Protocol Extension}, for a list of implemented
system calls.
@samp{@var{parameter}@dots{}} is a list of parameters as defined for
call a host system call on behalf of the target. @value{GDBN} replies
with an appropriate @samp{F} packet and keeps up waiting for the next
reply packet from the target. The latest @samp{C}, @samp{c}, @samp{S}
-or @samp{s} action is expected to be continued. @xref{File-I/O remote
-protocol extension}, for more details.
+or @samp{s} action is expected to be continued. @xref{File-I/O Remote
+Protocol Extension}, for more details.
@end table
thread local variable. (This offset is obtained from the debug
information associated with the variable.)
-@var{lm} is the (big endian, hex encoded) OS/ABI specific encoding of the
+@var{lm} is the (big endian, hex encoded) OS/ABI-specific encoding of the
the load module associated with the thread local storage. For example,
a @sc{gnu}/Linux system will pass the link map address of the shared
object associated with the thread local storage under consideration.
@item qOffsets
@cindex section offsets, remote request
@cindex @samp{qOffsets} packet
-Get section offsets that the target used when re-locating the downloaded
-image. @emph{Note: while a @code{Bss} offset is included in the
-response, @value{GDBN} ignores this and instead applies the @code{Data}
-offset to the @code{Bss} section.}
+Get section offsets that the target used when relocating the downloaded
+image.
Reply:
@table @samp
-@item Text=@var{xxx};Data=@var{yyy};Bss=@var{zzz}
+@item Text=@var{xxx};Data=@var{yyy}@r{[};Bss=@var{zzz}@r{]}
+Relocate the @code{Text} section by @var{xxx} from its original address.
+Relocate the @code{Data} section by @var{yyy} from its original address.
+If the object file format provides segment information (e.g.@: @sc{elf}
+@samp{PT_LOAD} program headers), @value{GDBN} will relocate entire
+segments by the supplied offsets.
+
+@emph{Note: while a @code{Bss} offset may be included in the response,
+@value{GDBN} ignores this and instead applies the @code{Data} offset
+to the @code{Bss} section.}
+
+@item TextSeg=@var{xxx}@r{[};DataSeg=@var{yyy}@r{]}
+Relocate the first segment of the object file, which conventionally
+contains program code, to a starting address of @var{xxx}. If
+@samp{DataSeg} is specified, relocate the second segment, which
+conventionally contains modifiable data, to a starting address of
+@var{yyy}. @value{GDBN} will report an error if the object file
+does not contain segment information, or does not contain at least
+as many segments as mentioned in the reply. Extra segments are
+kept at fixed offsets relative to the last relocated segment.
@end table
@item qP @var{mode} @var{threadid}
@end table
Use of this packet is controlled by the @code{set remote pass-signals}
-command (@pxref{Remote configuration, set remote pass-signals}).
+command (@pxref{Remote Configuration, set remote pass-signals}).
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
These are the currently defined stub features and their properties:
-@multitable @columnfractions 0.25 0.2 0.2 0.2
+@multitable @columnfractions 0.35 0.2 0.12 0.2
@c NOTE: The first row should be @headitem, but we do not yet require
@c a new enough version of Texinfo (4.7) to use @headitem.
@item Feature Name
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:libraries:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{qXfer:memory-map:read}
@tab No
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:spu:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@item @samp{qXfer:spu:write}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{QPassSignals}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:features:read} packet
(@pxref{qXfer target description read}).
+@item qXfer:libraries:read
+The remote stub understands the @samp{qXfer:libraries:read} packet
+(@pxref{qXfer library list read}).
+
@item qXfer:memory-map:read
The remote stub understands the @samp{qXfer:memory-map:read} packet
(@pxref{qXfer memory map read}).
+@item qXfer:spu:read
+The remote stub understands the @samp{qXfer:spu:read} packet
+(@pxref{qXfer spu read}).
+
+@item qXfer:spu:write
+The remote stub understands the @samp{qXfer:spu:write} packet
+(@pxref{qXfer spu write}).
+
@item QPassSignals
The remote stub understands the @samp{QPassSignals} packet
(@pxref{QPassSignals}).
Read uninterpreted bytes from the target's special data area
identified by the keyword @var{object}. Request @var{length} bytes
starting at @var{offset} bytes into the data. The content and
-encoding of @var{annex} is specific to the object; it can supply
+encoding of @var{annex} is specific to @var{object}; it can supply
additional details about what data to access.
Here are the specific requests of this form defined so far. All
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@item qXfer:libraries:read:@var{annex}:@var{offset},@var{length}
+@anchor{qXfer library list read}
+Access the target's list of loaded libraries. @xref{Library List Format}.
+The annex part of the generic @samp{qXfer} packet must be empty
+(@pxref{qXfer read}).
+
+Targets which maintain a list of libraries in the program's memory do
+not need to implement this packet; it is designed for platforms where
+the operating system manages the list of loaded libraries.
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
@item qXfer:memory-map:read::@var{offset},@var{length}
@anchor{qXfer memory map read}
-Access the target's @dfn{memory-map}. @xref{Memory map format}. The
+Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The
annex part of the generic @samp{qXfer} packet must be empty
(@pxref{qXfer read}).
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
+@item qXfer:spu:read:@var{annex}:@var{offset},@var{length}
+@anchor{qXfer spu read}
+Read contents of an @code{spufs} file on the target system. The
+annex specifies which file to read; it must be of the form
+@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
+in the target process, and @var{name} identifes the @code{spufs} file
+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}).
@end table
@cindex write data into object, remote request
Write uninterpreted bytes into the target's special data area
identified by the keyword @var{object}, starting at @var{offset} bytes
-into the data. @samp{@var{data}@dots{}} is the binary-encoded data
+into the data. @var{data}@dots{} is the binary-encoded data
(@pxref{Binary Data}) to be written. The content and encoding of @var{annex}
-is specific to the object; it can supply additional details about what data
+is specific to @var{object}; it can supply additional details about what data
to access.
-No requests of this form are presently in use. This specification
-serves as a placeholder to document the common format that new
-specific request specifications ought to use.
+Here are the specific requests of this form defined so far. All
+@samp{qXfer:@var{object}:write:@dots{}} requests use the same reply
+formats, listed below.
+
+@table @samp
+@item qXfer:@var{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
+@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
+in the target process, and @var{name} identifes the @code{spufs} file
+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}).
+@end table
Reply:
@table @samp
@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)
-> @code{+}
@end smallexample
-@node File-I/O remote protocol extension
-@section File-I/O remote protocol extension
+@node File-I/O Remote Protocol Extension
+@section File-I/O Remote Protocol Extension
@cindex File-I/O remote protocol extension
@menu
* File-I/O Overview::
-* Protocol basics::
-* The F request packet::
-* The F reply packet::
-* The Ctrl-C message::
+* Protocol Basics::
+* The F Request Packet::
+* The F Reply Packet::
+* The Ctrl-C Message::
* Console I/O::
-* List of supported calls::
-* Protocol specific representation of datatypes::
+* List of Supported Calls::
+* Protocol-specific Representation of Datatypes::
* Constants::
* File-I/O Examples::
@end menu
named pipes, sockets or any other communication method on the host
system are not supported by this protocol.
-@node Protocol basics
-@subsection Protocol basics
+@node Protocol Basics
+@subsection Protocol Basics
@cindex protocol basics, file-i/o
The File-I/O protocol uses the @code{F} packet as the request as well
All parameters to the system call. Pointers are given as addresses
in the target memory address space. Pointers to strings are given as
pointer/length pair. Numerical values are given as they are.
-Numerical control flags are given in a protocol specific representation.
+Numerical control flags are given in a protocol-specific representation.
@end itemize
After having done the needed type and value coercion, the target continues
the latest continue or step action.
-@node The F request packet
-@subsection The @code{F} request packet
+@node The F Request Packet
+@subsection The @code{F} Request Packet
@cindex file-i/o request packet
@cindex @code{F} request packet
-@node The F reply packet
-@subsection The @code{F} reply packet
+@node The F Reply Packet
+@subsection The @code{F} Reply Packet
@cindex file-i/o reply packet
@cindex @code{F} reply packet
@table @samp
-@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call specific attachment}
+@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific attachment}
@var{retcode} is the return code of the system call as hexadecimal value.
-@var{errno} is the @code{errno} set by the call, in protocol specific representation.
+@var{errno} is the @code{errno} set by the call, in protocol-specific
+representation.
This parameter can be omitted if the call was successful.
@var{Ctrl-C flag} is only sent if the user requested a break. In this
@end smallexample
@noindent
-assuming 4 is the protocol specific representation of @code{EINTR}.
+assuming 4 is the protocol-specific representation of @code{EINTR}.
@end table
-@node The Ctrl-C message
-@subsection The @samp{Ctrl-C} message
+@node The Ctrl-C Message
+@subsection The @samp{Ctrl-C} Message
@cindex ctrl-c message, in file-i/o protocol
If the @samp{Ctrl-C} flag is set in the @value{GDBN}
-reply packet (@pxref{The F reply packet}),
+reply packet (@pxref{The F Reply Packet}),
the target should behave as if it had
gotten a break message. The meaning for the target is ``system call
interrupted by @code{SIGINT}''. Consequentially, the target should actually stop
is stopped at the user's request.
-@node List of supported calls
-@subsection List of supported calls
+@node List of Supported Calls
+@subsection List of Supported Calls
@cindex list of supported file-i/o calls
@menu
@item EFBIG
An attempt was made to write a file that exceeds the
-host specific maximum file size allowed.
+host-specific maximum file size allowed.
@item ENOSPC
No space on device to write the data.
protocol.
@end table
-@node Protocol specific representation of datatypes
-@subsection Protocol specific representation of datatypes
-@cindex protocol specific representation of datatypes, in file-i/o protocol
+@node Protocol-specific Representation of Datatypes
+@subsection Protocol-specific Representation of Datatypes
+@cindex protocol-specific representation of datatypes, in file-i/o protocol
@menu
-* Integral datatypes::
-* Pointer values::
-* Memory transfer::
+* Integral Datatypes::
+* Pointer Values::
+* Memory Transfer::
* struct stat::
* struct timeval::
@end menu
-@node Integral datatypes
-@unnumberedsubsubsec Integral datatypes
+@node Integral Datatypes
+@unnumberedsubsubsec Integral Datatypes
@cindex integral datatypes, in file-i/o protocol
The integral datatypes used in the system calls are @code{int},
structured datatype e.g.@: a @code{struct stat} have to be given in big endian
byte order.
-@node Pointer values
-@unnumberedsubsubsec Pointer values
+@node Pointer Values
+@unnumberedsubsubsec Pointer Values
@cindex pointer values, in file-i/o protocol
Pointers to target data are transmitted as they are. An exception
@code{123456/d}
@end smallexample
-@node Memory transfer
-@unnumberedsubsubsec Memory transfer
+@node Memory Transfer
+@unnumberedsubsubsec Memory Transfer
@cindex memory transfer, in file-i/o protocol
Structured data which is transferred using a memory read or write (for
-example, a @code{struct stat}) is expected to be in a protocol specific format
+example, a @code{struct stat}) is expected to be in a protocol-specific format
with all scalar multibyte datatypes being big endian. Translation to
this representation needs to be done both by the target before the @code{F}
packet is sent, and by @value{GDBN} before
@end smallexample
The integral datatypes conform to the definitions given in the
-appropriate section (see @ref{Integral datatypes}, for details) so this
+appropriate section (see @ref{Integral Datatypes}, for details) so this
structure is of size 64 bytes.
The values of several fields have a restricted meaning and/or
@end smallexample
The integral datatypes conform to the definitions given in the
-appropriate section (see @ref{Integral datatypes}, for details) so this
+appropriate section (see @ref{Integral Datatypes}, for details) so this
structure is of size 8 bytes.
@node Constants
values before and after the call as needed.
@menu
-* Open flags::
-* mode_t values::
-* Errno values::
-* Lseek flags::
+* Open Flags::
+* mode_t Values::
+* Errno Values::
+* Lseek Flags::
* Limits::
@end menu
-@node Open flags
-@unnumberedsubsubsec Open flags
+@node Open Flags
+@unnumberedsubsubsec Open Flags
@cindex open flags, in file-i/o protocol
All values are given in hexadecimal representation.
O_EXCL 0x800
@end smallexample
-@node mode_t values
-@unnumberedsubsubsec mode_t values
+@node mode_t Values
+@unnumberedsubsubsec mode_t Values
@cindex mode_t values, in file-i/o protocol
All values are given in octal representation.
S_IXOTH 01
@end smallexample
-@node Errno values
-@unnumberedsubsubsec Errno values
+@node Errno Values
+@unnumberedsubsubsec Errno Values
@cindex errno values, in file-i/o protocol
All values are given in decimal representation.
@code{EUNKNOWN} is used as a fallback error value if a host system returns
any error value not in the list of supported error numbers.
-@node Lseek flags
-@unnumberedsubsubsec Lseek flags
+@node Lseek Flags
+@unnumberedsubsubsec Lseek Flags
@cindex lseek flags, in file-i/o protocol
@smallexample
<- @code{T02}
@end smallexample
-@node Memory map format
-@section Memory map format
+@node Library List Format
+@section Library List Format
+@cindex library list format, remote protocol
+
+On some platforms, a dynamic loader (e.g.@: @file{ld.so}) runs in the
+same process as your application to manage libraries. In this case,
+@value{GDBN} can use the loader's symbol table and normal memory
+operations to maintain a list of shared libraries. On other
+platforms, the operating system manages loaded libraries.
+@value{GDBN} can not retrieve the list of currently loaded libraries
+through memory operations, so it uses the @samp{qXfer:libraries:read}
+packet (@pxref{qXfer library list read}) instead. The remote stub
+queries the target's operating system and reports which libraries
+are loaded.
+
+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 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:
+
+@smallexample
+<library-list>
+ <library name="/lib/libc.so.6">
+ <segment address="0x10000000"/>
+ </library>
+</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*, 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
To be able to write into flash memory, @value{GDBN} needs to obtain a
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.
Here is a simple target description:
@smallexample
-<target>
+<target version="1.0">
<architecture>i386:x86-64</architecture>
</target>
@end smallexample
@smallexample
<?xml version="1.0"?>
<!DOCTYPE target SYSTEM "gdb-target.dtd">
-<target>
+<target version="1.0">
@r{[}@var{architecture}@r{]}
@r{[}@var{feature}@dots{}@r{]}
</target>
breaks, under the usual common-sense rules. The XML version
declaration and document type declaration can generally be omitted
(@value{GDBN} does not require them), but specifying them may be
-useful for XML validation tools.
+useful for XML validation tools. The @samp{version} attribute for
+@samp{<target>} may also be omitted, but we recommend
+including it; if future versions of @value{GDBN} use an incompatible
+revision of @file{gdb-target.dtd}, they will detect and report
+the version mismatch.
@subsection Inclusion
@cindex target descriptions, inclusion
@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
address. The stack pointer and any dedicated address registers
may be marked as data pointers.
+@item ieee_single
+Single precision IEEE floating point.
+
+@item ieee_double
+Double precision IEEE floating point.
+
@item arm_fpa_ext
The 12-byte extended precision format used by ARM FPA registers.
of recognizing standard features, but @value{GDBN} will only display
registers using the capitalization used in the description.
+@menu
+* ARM Features::
+* MIPS Features::
+* M68K Features::
+* PowerPC Features::
+@end menu
+
+
+@node ARM Features
@subsection ARM Features
@cindex target descriptions, ARM features
@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
+
+The @samp{org.gnu.gdb.mips.cpu} feature is required for MIPS targets.
+It should contain registers @samp{r0} through @samp{r31}, @samp{lo},
+@samp{hi}, and @samp{pc}. They may be 32-bit or 64-bit depending
+on the target.
+
+The @samp{org.gnu.gdb.mips.cp0} feature is also required. It should
+contain at least the @samp{status}, @samp{badvaddr}, and @samp{cause}
+registers. They may be 32-bit or 64-bit depending on the target.
+
+The @samp{org.gnu.gdb.mips.fpu} feature is currently required, though
+it may be optional in a future version of @value{GDBN}. It should
+contain registers @samp{f0} through @samp{f31}, @samp{fcsr}, and
+@samp{fir}. They may be 32-bit or 64-bit depending on the target.
+
+The @samp{org.gnu.gdb.mips.linux} feature is optional. It should
+contain a single register, @samp{restart}, which is used by the
+Linux kernel to control restartable syscalls.
+
+@node M68K Features
+@subsection M68K Features
+@cindex target descriptions, M68K features
+
+@table @code
+@item @samp{org.gnu.gdb.m68k.core}
+@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
+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}.
+
+@item @samp{org.gnu.gdb.coldfire.fp}
+This feature is optional. If present, it should contain registers
+@samp{fp0} through @samp{fp7}, @samp{fpcontrol}, @samp{fpstatus} and
+@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.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.
+
@include gpl.texi
@raisesections
projects / deliverable / binutils-gdb.git / blobdiff