@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
If you are running your program in an execution environment that
supports processes, @code{run} creates an inferior process and makes
-that process run your program. (In environments without processes,
-@code{run} jumps to the start of your program.)
+that process run your program. In some environments without processes,
+@code{run} jumps to the start of your program. Other targets,
+like @samp{remote}, are always running. If you get an error
+message like this one:
+
+@smallexample
+The "remote" target does not support "run".
+Try "help target" or "continue".
+@end smallexample
+
+@noindent
+then use @code{continue} to run your program. You may need @code{load}
+first (@pxref{load}).
The execution of a program is affected by certain information it
receives from its superior. @value{GDBN} provides ways to specify this
your program too late, as the program would have already completed the
elaboration phase. Under these circumstances, insert breakpoints in your
elaboration code before running your program.
+
+@kindex set exec-wrapper
+@item set exec-wrapper @var{wrapper}
+@itemx show exec-wrapper
+@itemx unset exec-wrapper
+When @samp{exec-wrapper} is set, the specified wrapper is used to
+launch programs for debugging. @value{GDBN} starts your program
+with a shell command of the form @kbd{exec @var{wrapper}
+@var{program}}. Quoting is added to @var{program} and its
+arguments, but not to @var{wrapper}, so you should add quotes if
+appropriate for your shell. The wrapper runs until it executes
+your program, and then @value{GDBN} takes control.
+
+You can use any program that eventually calls @code{execve} with
+its arguments as a wrapper. Several standard Unix utilities do
+this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending
+with @code{exec "$@@"} will also work.
+
+For example, you can use @code{env} to pass an environment variable to
+the debugged program, without setting the variable in your shell's
+environment:
+
+@smallexample
+(@value{GDBP}) set exec-wrapper env 'LD_PRELOAD=libtest.so'
+(@value{GDBP}) run
+@end smallexample
+
+This command is available when debugging locally on most targets, excluding
+@sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino.
+
@end table
@node Arguments
@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
@end table
-@kindex show detach-on-follow
-@item show detach-on-follow
-Show whether detach-on-follow mode is on/off.
+@kindex show detach-on-fork
+@item show detach-on-fork
+Show whether detach-on-fork mode is on/off.
@end table
-If you choose to set @var{detach-on-follow} mode off, then
+If you choose to set @samp{detach-on-fork} mode off, then
@value{GDBN} will retain control of all forked processes (including
nested forks). You can list the forked processes under the control of
@value{GDBN} by using the @w{@code{info forks}} command, and switch
The listing will include a fork id, a process id, and the current
position (program counter) of the process.
-
@kindex fork @var{fork-id}
@item fork @var{fork-id}
Make fork number @var{fork-id} the current process. The argument
@var{fork-id} is the internal fork number assigned by @value{GDBN},
as shown in the first field of the @samp{info forks} display.
+@kindex process @var{process-id}
+@item process @var{process-id}
+Make process number @var{process-id} the current process. The
+argument @var{process-id} must be one that is listed in the output of
+@samp{info forks}.
+
@end table
To quit debugging one of the forked processes, you can either detach
* Disabling:: Disabling breakpoints
* Conditions:: Break conditions
* Break Commands:: Breakpoint command lists
-* Breakpoint Menus:: Breakpoint menus
* Error in Breakpoints:: ``Cannot insert breakpoints''
* Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
@end menu
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{Breakpoint Menus,,Breakpoint Menus}, for a discussion of that situation.
+@xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
+that situation.
@item break
When called without any arguments, @code{break} sets a breakpoint at
Whether the breakpoint is marked to be disabled or deleted when hit.
@item Enabled or Disabled
Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
-that are not enabled. An optional @samp{(p)} suffix marks pending
-breakpoints---breakpoints for which address is either not yet
-resolved, pending load of a shared library, or for which address was
-in a shared library that was since unloaded. Such breakpoint won't
-fire until a shared library that has the symbol or line referred by
-breakpoint is loaded. See below for details.
+that are not enabled.
@item Address
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>}. A breakpoint with several locations will
+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
the breakpoints are conditional, this is even useful
(@pxref{Conditions, ,Break Conditions}).
+@cindex multiple locations, breakpoints
+@cindex breakpoints, multiple locations
It is possible that a breakpoint corresponds to several locations
in your program. Examples of this situation are:
@itemize @bullet
-
@item
For a C@t{++} constructor, the @value{NGCC} compiler generates several
instances of the function body, used in different cases.
@item
For 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.
+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
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
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
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.
@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}
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. You can use explicit signature of the function, as in
-@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''
Here @var{address} may be any expression valid in the current working
language (@pxref{Languages, working language}) that specifies a code
-address. 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}:
+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}
@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
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
@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}
point computations, error checking in decimal float operations ignores
underflow, overflow and divide by zero exceptions.
+In the PowerPC architecture, @value{GDBN} provides a set of pseudo-registers
+to inspect @code{_Decimal128} values stored in floating point registers. See
+@ref{PowerPC,,PowerPC} for more details.
+
@node Objective-C
@subsection Objective-C
@item :
The range operator. Normally used in the form of array(low:high) to
represent a section of array.
+
+@item %
+The access component operator. Normally used to access elements in derived
+types. Also suitable for unions. As unions aren't part of regular Fortran,
+this can only happen when accessing a register that uses a gdbarch-defined
+union type.
@end table
@node Fortran Defaults
@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
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
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
For TCP connections, you must start up @code{gdbserver} prior to using
the @code{target remote} command. Otherwise you may get an error whose
text depends on the host system, but which usually looks something like
-@samp{Connection refused}. You don't need to use the @code{load}
+@samp{Connection refused}. Don't use the @code{load}
command in @value{GDBN} when using @code{gdbserver}, since the program is
already on the target.
-@end table
-
@subsection Monitor Commands for @code{gdbserver}
@cindex monitor commands, for @code{gdbserver}
+@anchor{Monitor Commands for gdbserver}
During a @value{GDBN} session using @code{gdbserver}, you can use the
@code{monitor} command to send special requests to @code{gdbserver}.
-Here are the available commands; they are only of interest when
-debugging @value{GDBN} or @code{gdbserver}.
+Here are the available commands.
@table @code
@item monitor help
Disable or enable specific debugging messages associated with the remote
protocol (@pxref{Remote Protocol}).
+@item monitor exit
+Tell gdbserver to exit immediately. This command should be followed by
+@code{disconnect} to close the debugging session. @code{gdbserver} will
+detach from any attached processes and kill any processes it created.
+Use @code{monitor exit} to terminate @code{gdbserver} at the end
+of a multi-process mode debug session.
+
@end table
@node Remote Configuration
@itemx set remote hardware-breakpoint-limit @var{limit}
Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
watchpoints. A limit of -1, the default, is treated as unlimited.
+
+@item set remote exec-file @var{filename}
+@itemx show remote exec-file
+@anchor{set remote exec-file}
+@cindex executable file, for remote target
+Select the file used for @code{run} with @code{target
+extended-remote}. This should be set to a filename valid on the
+target system. If it is not set, the target will use a default
+filename (e.g.@: the last program run).
@end table
@cindex remote packets, enabling and disabling
@tab @code{qSymbol}
@tab Detecting multiple threads
+@item @code{attach}
+@tab @code{vAttach}
+@tab @code{attach}
+
@item @code{verbose-resume}
@tab @code{vCont}
@tab Stepping or resuming multiple threads
+@item @code{run}
+@tab @code{vRun}
+@tab @code{run}
+
@item @code{software-breakpoint}
@tab @code{Z0}
@tab @code{break}
* MIPS Embedded:: MIPS Embedded
* OpenRISC 1000:: OpenRisc 1000
* PA:: HP PA Embedded
-* PowerPC:: PowerPC
+* PowerPC Embedded:: PowerPC Embedded
* Sparclet:: Tsqware Sparclet
* Sparclite:: Fujitsu Sparclite
* Z8000:: Zilog Z8000
@item show arm abi
Show the currently used ABI.
+@item set arm fallback-mode (arm|thumb|auto)
+@value{GDBN} uses the symbol table, when available, to determine
+whether instructions are ARM or Thumb. This command controls
+@value{GDBN}'s default behavior when the symbol table is not
+available. The default is @samp{auto}, which causes @value{GDBN} to
+use the current execution mode (from the @code{T} bit in the @code{CPSR}
+register).
+
+@item show arm fallback-mode
+Show the current fallback instruction mode.
+
+@item set arm force-mode (arm|thumb|auto)
+This command overrides use of the symbol table to determine whether
+instructions are ARM or Thumb. The default is @samp{auto}, which
+causes @value{GDBN} to use the symbol table and then the setting
+of @samp{set arm fallback-mode}.
+
+@item show arm force-mode
+Show the current forced instruction mode.
+
@item set debug arm
Toggle whether to display ARM-specific debugging messages from the ARM
target support subsystem.
@end table
-@node PowerPC
-@subsection PowerPC
+@node PowerPC Embedded
+@subsection PowerPC Embedded
@value{GDBN} provides the following PowerPC-specific commands:
@item regs
@kindex regs@r{, Super-H}
Show the values of all Super-H registers.
+
+@item set sh calling-convention @var{convention}
+@kindex set sh calling-convention
+Set the calling-convention used when calling functions from @value{GDBN}.
+Allowed values are @samp{gcc}, which is the default setting, and @samp{renesas}.
+With the @samp{gcc} setting, functions are called using the @value{NGCC} calling
+convention. If the DWARF-2 information of the called function specifies
+that the function follows the Renesas calling convention, the function
+is called using the Renesas calling convention. If the calling convention
+is set to @samp{renesas}, the Renesas calling convention is always used,
+regardless of the DWARF-2 information. This can be used to override the
+default of @samp{gcc} if debug information is missing, or the compiler
+does not emit the DWARF-2 calling convention entry for a function.
+
+@item show sh calling-convention
+@kindex show sh calling-convention
+Show the current calling convention setting.
+
@end table
* MIPS::
* HPPA:: HP PA architecture
* SPU:: Cell Broadband Engine SPU architecture
+* PowerPC::
@end menu
@node i386
@end table
+@node PowerPC
+@subsection PowerPC
+@cindex PowerPC architecture
+
+When @value{GDBN} is debugging the PowerPC architecture, it provides a set of
+pseudo-registers to enable inspection of 128-bit wide Decimal Floating Point
+numbers stored in the floating point registers. These values must be stored
+in two consecutive registers, always starting at an even register like
+@code{f0} or @code{f2}.
+
+The pseudo-registers go from @code{$dl0} through @code{$dl15}, and are formed
+by joining the even/odd register pairs @code{f0} and @code{f1} for @code{$dl0},
+@code{f2} and @code{f3} for @code{$dl1} and so on.
+
@node Controlling GDB
@chapter Controlling @value{GDBN}
module.
@item show debug aix-thread
Show the current state of AIX thread debugging info display.
+@item set debug 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
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}
-> -exec-run
<- ^running
<- (gdb)
-<- *stopped,reason="breakpoint-hit",bkptno="1",thread-id="0",
+<- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
frame=@{addr="0x08048564",func="main",
args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}],
file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"@}
@smallexample
(gdb)
-break-insert main
-^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",
+^done,bkpt=@{number="1",type="breakpoint",disp="keep",
+enabled="y",addr="0x000100d0",func="main",file="hello.c",
fullname="/home/foo/hello.c",line="5",times="0"@}
(gdb)
-break-after 1 3
@subsubheading Synopsis
@smallexample
- -thread-info
+ -thread-info [ @var{thread-id} ]
@end smallexample
+Reports information about either a specific thread, if
+the @var{thread-id} parameter is present, or about all
+threads. When printing information about all threads,
+also reports the current thread.
+
@subsubheading @value{GDBN} Command
-No equivalent.
+The @samp{info thread} command prints the same information
+about all threads.
@subsubheading Example
-N.A.
-
-
-@subheading The @code{-thread-list-all-threads} Command
-@findex -thread-list-all-threads
-
-@subsubheading Synopsis
@smallexample
- -thread-list-all-threads
+-thread-info
+^done,threads=[
+@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
+ frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},
+@{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
-@subsubheading @value{GDBN} Command
-
-The equivalent @value{GDBN} command is @samp{info threads}.
-
-@subsubheading Example
-N.A.
-
-
@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)
Sets the output format for the value of the object @var{name} to be
@var{format-spec}.
+@anchor{-var-set-format}
The syntax for the @var{format-spec} is as follows:
@smallexample
@subsubheading Synopsis
@smallexample
- -var-evaluate-expression @var{name}
+ -var-evaluate-expression [-f @var{format-spec}] @var{name}
@end smallexample
Evaluates the expression that is represented by the specified variable
-object and returns its value as a string. The format of the
-string can be changed using the @code{-var-set-format} command.
+object and returns its value as a string. The format of the string
+can be specified with the @samp{-f} option. The possible values of
+this option are the same as for @code{-var-set-format}
+(@pxref{-var-set-format}). If the @samp{-f} option is not specified,
+the current display format will be used. The current display format
+can be changed using the @code{-var-set-format} command.
@smallexample
value=@var{value}
object names, all existing variable objects are updated, except
for frozen ones (@pxref{-var-set-frozen}). The option
@var{print-values} determines whether both names and values, or just
-names are printed. The possible values of this options are the same
+names are printed. The possible values of this option are the same
as for @code{-var-list-children} (@pxref{-var-list-children}). It is
recommended to use the @samp{--all-values} option, to reduce the
number of MI commands needed on each program stop.
^running
(gdb)
-*stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
-args=[],file="try.c",fullname="/home/foo/bar/try.c",line="5"@}
+*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame=@{
+func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c",
+line="5"@}
(gdb)
-data-list-changed-registers
^done,changed-registers=["0","1","2","4","5","6","7","8","9",
@end smallexample
List the line number, the current source file, and the absolute path
-to the current source file for the current executable.
+to the current source file for the current executable. The macro
+information field has a value of @samp{1} or @samp{0} depending on
+whether or not the file includes preprocessor macro information.
@subsubheading @value{GDBN} Command
@smallexample
(gdb)
123-file-list-exec-source-file
-123^done,line="1",file="foo.c",fullname="/home/bar/foo.c"
+123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"
(gdb)
@end smallexample
@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
-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"@}
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
@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.
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
@item !
@cindex @samp{!} packet
+@anchor{extended mode}
Enable extended mode. In extended mode, the remote server is made
persistent. The @samp{R} packet is used to restart the program being
debugged.
@item 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.
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
The @samp{qXfer:libraries:read} packet returns an XML document which
lists loaded libraries and their offsets. Each library has an
-associated name and one or more segment base addresses, which report
-where the library was loaded in memory. The segment bases are start
-addresses, not relocation offsets; they do not depend on the library's
-link-time base addresses.
+associated name and one or more segment or section base addresses,
+which report where the library was loaded in memory.
+
+For the common case of libraries that are fully linked binaries, the
+library should have a list of segments. If the target supports
+dynamic linking of a relocatable object file, its library XML element
+should instead include a list of allocated sections. The segment or
+section bases are start addresses, not relocation offsets; they do not
+depend on the library's link-time base addresses.
@value{GDBN} must be linked with the Expat library to support XML
library lists. @xref{Expat}.
</library-list>
@end smallexample
+Another simple memory map, with one loaded library with three
+allocated sections (.text, .data, .bss), looks like this:
+
+@smallexample
+<library-list>
+ <library name="sharedlib.o">
+ <section address="0x10000000"/>
+ <section address="0x20000000"/>
+ <section address="0x30000000"/>
+ </library>
+</library-list>
+@end smallexample
+
The format of a library list is described by this DTD:
@smallexample
<!-- library-list: Root element with versioning -->
<!ELEMENT library-list (library)*>
<!ATTLIST library-list version CDATA #FIXED "1.0">
-<!ELEMENT library (segment)*>
+<!ELEMENT library (segment*, section*)>
<!ATTLIST library name CDATA #REQUIRED>
<!ELEMENT segment EMPTY>
<!ATTLIST segment address CDATA #REQUIRED>
+<!ELEMENT section EMPTY>
+<!ATTLIST section address CDATA #REQUIRED>
@end smallexample
+In addition, segments and section descriptors cannot be mixed within a
+single library element, and you must supply at least one segment or
+section for each library.
+
@node Memory Map Format
@section Memory Map Format
@cindex memory map format
@menu
* ARM Features::
+* MIPS Features::
* M68K Features::
+* PowerPC Features::
@end menu
@samp{wCGR0} through @samp{wCGR3}. The @samp{wCID}, @samp{wCon},
@samp{wCSSF}, and @samp{wCASF} registers are optional.
+@node MIPS Features
@subsection MIPS Features
@cindex target descriptions, MIPS features
@samp{fpiaddr}.
@end table
+@node PowerPC Features
@subsection PowerPC Features
@cindex target descriptions, PowerPC features
projects / deliverable / binutils-gdb.git / blobdiff