@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
* 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''
source line debug information.
@kindex finish
+@kindex fin @r{(@code{finish})}
@item finish
Continue running until just after function in the selected stack frame
-returns. Print the returned value (if any).
+returns. Print the returned value (if any). This command can be
+abbreviated as @code{fin}.
Contrast this with the @code{return} command (@pxref{Returning,
,Returning from a Function}).
@cindex machine instructions
@cindex listing machine instructions
@item disassemble
+@itemx disassemble /m
This specialized command dumps a range of memory as machine
-instructions. The default memory range is the function surrounding the
+instructions. It can also print mixed source+disassembly by specifying
+the @code{/m} modifier.
+The default memory range is the function surrounding the
program counter of the selected frame. A single argument to this
command is a program counter value; @value{GDBN} dumps the function
surrounding this value. Two arguments specify a range of addresses
End of assembler dump.
@end smallexample
+Here is an example showing mixed source+assembly for Intel x86:
+
+@smallexample
+(@value{GDBP}) disas /m main
+Dump of assembler code for function main:
+5 @{
+0x08048330 <main+0>: push %ebp
+0x08048331 <main+1>: mov %esp,%ebp
+0x08048333 <main+3>: sub $0x8,%esp
+0x08048336 <main+6>: and $0xfffffff0,%esp
+0x08048339 <main+9>: sub $0x10,%esp
+
+6 printf ("Hello.\n");
+0x0804833c <main+12>: movl $0x8048440,(%esp)
+0x08048343 <main+19>: call 0x8048284 <puts@@plt>
+
+7 return 0;
+8 @}
+0x08048348 <main+24>: mov $0x0,%eax
+0x0804834d <main+29>: leave
+0x0804834e <main+30>: ret
+
+End of assembler dump.
+@end smallexample
+
Some architectures have more than one commonly-used set of instruction
mnemonics or other syntax.
@menu
* Expressions:: Expressions
+* Ambiguous Expressions:: Ambiguous Expressions
* Variables:: Program variables
* Arrays:: Artificial arrays
* Output Formats:: Output formats
* Character Sets:: Debugging programs that use a different
character set than GDB does
* Caching Remote Data:: Data caching for remote targets
+* Searching Memory:: Searching memory for a sequence of bytes
@end menu
@node Expressions
@cindex arrays in expressions
@value{GDBN} supports array constants in expressions input by
the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example,
-you can use the command @code{print @{1, 2, 3@}} to build up an array in
-memory that is @code{malloc}ed in the target program.
+you can use the command @code{print @{1, 2, 3@}} to create an array
+of three integers. If you pass an array to a function or assign it
+to a program variable, @value{GDBN} copies the array to memory that
+is @code{malloc}ed in the target program.
Because C is so widespread, most of the expressions shown in examples in
this manual are in C. @xref{Languages, , Using @value{GDBN} with Different
normally supposed to reside at @var{addr}.
@end table
+@node Ambiguous Expressions
+@section Ambiguous Expressions
+@cindex ambiguous expressions
+
+Expressions can sometimes contain some ambiguous elements. For instance,
+some programming languages (notably Ada, C@t{++} and Objective-C) permit
+a single function name to be defined several times, for application in
+different contexts. This is called @dfn{overloading}. Another example
+involving Ada is generics. A @dfn{generic package} is similar to C@t{++}
+templates and is typically instantiated several times, resulting in
+the same function name being defined in different contexts.
+
+In some cases and depending on the language, it is possible to adjust
+the expression to remove the ambiguity. For instance in C@t{++}, you
+can specify the signature of the function you want to break on, as in
+@kbd{break @var{function}(@var{types})}. In Ada, using the fully
+qualified name of your function often makes the expression unambiguous
+as well.
+
+When an ambiguity that needs to be resolved is detected, the debugger
+has the capability to display a menu of numbered choices for each
+possibility, and then waits for the selection with the prompt @samp{>}.
+The first option is always @samp{[0] cancel}, and typing @kbd{0 @key{RET}}
+aborts the current command. If the command in which the expression was
+used allows more than one choice to be selected, the next option in the
+menu is @samp{[1] all}, and typing @kbd{1 @key{RET}} selects all possible
+choices.
+
+For example, the following session excerpt shows an attempt to set a
+breakpoint at the overloaded symbol @code{String::after}.
+We choose three particular definitions of that function name:
+
+@c FIXME! This is likely to change to show arg type lists, at least
+@smallexample
+@group
+(@value{GDBP}) b String::after
+[0] cancel
+[1] all
+[2] file:String.cc; line number:867
+[3] file:String.cc; line number:860
+[4] file:String.cc; line number:875
+[5] file:String.cc; line number:853
+[6] file:String.cc; line number:846
+[7] file:String.cc; line number:735
+> 2 4 6
+Breakpoint 1 at 0xb26c: file String.cc, line 867.
+Breakpoint 2 at 0xb344: file String.cc, line 875.
+Breakpoint 3 at 0xafcc: file String.cc, line 846.
+Multiple breakpoints were set.
+Use the "delete" command to delete unwanted
+ breakpoints.
+(@value{GDBP})
+@end group
+@end smallexample
+
+@table @code
+@kindex set multiple-symbols
+@item set multiple-symbols @var{mode}
+@cindex multiple-symbols menu
+
+This option allows you to adjust the debugger behavior when an expression
+is ambiguous.
+
+By default, @var{mode} is set to @code{all}. If the command with which
+the expression is used allows more than one choice, then @value{GDBN}
+automatically selects all possible choices. For instance, inserting
+a breakpoint on a function using an ambiguous name results in a breakpoint
+inserted on each possible match. However, if a unique choice must be made,
+then @value{GDBN} uses the menu to help you disambiguate the expression.
+For instance, printing the address of an overloaded function will result
+in the use of the menu.
+
+When @var{mode} is set to @code{ask}, the debugger always uses the menu
+when an ambiguity is detected.
+
+Finally, when @var{mode} is set to @code{cancel}, the debugger reports
+an error due to the ambiguity and the command is aborted.
+
+@kindex show multiple-symbols
+@item show multiple-symbols
+Show the current value of the @code{multiple-symbols} setting.
+@end table
+
@node Variables
@section Program Variables
the data cache operation.
@end table
+@node Searching Memory
+@section Search Memory
+@cindex searching memory
+
+Memory can be searched for a particular sequence of bytes with the
+@code{find} command.
+
+@table @code
+@kindex find
+@item find @r{[}/@var{sn}@r{]} @var{start_addr}, +@var{len}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]}
+@itemx find @r{[}/@var{sn}@r{]} @var{start_addr}, @var{end_addr}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]}
+Search memory for the sequence of bytes specified by @var{val1}, @var{val2},
+etc. The search begins at address @var{start_addr} and continues for either
+@var{len} bytes or through to @var{end_addr} inclusive.
+@end table
+
+@var{s} and @var{n} are optional parameters.
+They may be specified in either order, apart or together.
+
+@table @r
+@item @var{s}, search query size
+The size of each search query value.
+
+@table @code
+@item b
+bytes
+@item h
+halfwords (two bytes)
+@item w
+words (four bytes)
+@item g
+giant words (eight bytes)
+@end table
+
+All values are interpreted in the current language.
+This means, for example, that if the current source language is C/C@t{++}
+then searching for the string ``hello'' includes the trailing '\0'.
+
+If the value size is not specified, it is taken from the
+value's type in the current language.
+This is useful when one wants to specify the search
+pattern as a mixture of types.
+Note that this means, for example, that in the case of C-like languages
+a search for an untyped 0x42 will search for @samp{(int) 0x42}
+which is typically four bytes.
+
+@item @var{n}, maximum number of finds
+The maximum number of matches to print. The default is to print all finds.
+@end table
+
+You can use strings as search values. Quote them with double-quotes
+ (@code{"}).
+The string value is copied into the search pattern byte by byte,
+regardless of the endianness of the target and the size specification.
+
+The address of each match found is printed as well as a count of the
+number of matches found.
+
+The address of the last value found is stored in convenience variable
+@samp{$_}.
+A count of the number of matches is stored in @samp{$numfound}.
+
+For example, if stopped at the @code{printf} in this function:
+
+@smallexample
+void
+hello ()
+@{
+ static char hello[] = "hello-hello";
+ static struct @{ char c; short s; int i; @}
+ __attribute__ ((packed)) mixed
+ = @{ 'c', 0x1234, 0x87654321 @};
+ printf ("%s\n", hello);
+@}
+@end smallexample
+
+@noindent
+you get during debugging:
+
+@smallexample
+(gdb) find &hello[0], +sizeof(hello), "hello"
+0x804956d <hello.1620+6>
+1 pattern found
+(gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
+0x8049567 <hello.1620>
+0x804956d <hello.1620+6>
+2 patterns found
+(gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
+0x8049567 <hello.1620>
+1 pattern found
+(gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
+0x8049560 <mixed.1625>
+1 pattern found
+(gdb) print $numfound
+$1 = 1
+(gdb) print $_
+$2 = (void *) 0x8049560
+@end smallexample
@node Macros
@chapter C Preprocessor Macros
@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
program exits, or you detach from it, @value{GDBN} closes the connection
and @code{gdbserver} exits.
-If you connect using @code{target extended-remote}, @code{gdbserver}
+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}
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 @code{target extended-remote} and start
+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.
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.
@tab @code{qGetTLSAddr}
@tab Displaying @code{__thread} variables
+@item @code{search-memory}
+@tab @code{qSearch:memory}
+@tab @code{find}
+
@item @code{supported-packets}
@tab @code{qSupported}
@tab Remote communications parameters
* 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}
The best way to avoid unexpected changes in MI that might break your front
end is to make your project known to @value{GDBN} developers and
follow development on @email{gdb@@sourceware.org} and
-@email{gdb-patches@@sourceware.org}. There is also the mailing list
-@email{dmi-discuss@@lists.freestandards.org}, hosted by the Free Standards
-Group, which has the aim of creating a more general MI protocol
-called Debugger Machine Interface (DMI) that will become a standard
-for all debuggers, not just @value{GDBN}.
+@email{gdb-patches@@sourceware.org}.
@cindex mailing lists
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@menu
* GDB/MI Result Records::
* GDB/MI Stream Records::
-* GDB/MI Out-of-band Records::
+* GDB/MI Async Records::
@end menu
@node GDB/MI Result Records
internals.
@end table
-@node GDB/MI Out-of-band Records
-@subsection @sc{gdb/mi} Out-of-band Records
+@node GDB/MI Async Records
+@subsection @sc{gdb/mi} Async Records
-@cindex out-of-band records in @sc{gdb/mi}
-@cindex @sc{gdb/mi}, out-of-band records
-@dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of
+@cindex async records in @sc{gdb/mi}
+@cindex @sc{gdb/mi}, async records
+@dfn{Async} records are used to notify the @sc{gdb/mi} client of
additional changes that have occurred. Those changes can either be a
-consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
+consequence of @sc{gdb/mi} commands (e.g., a breakpoint modified) or a result of
target activity (e.g., target stopped).
-The following is a preliminary list of possible out-of-band records.
-In particular, the @var{exec-async-output} records.
+The following is the list of possible async records:
@table @code
-@item *stopped,reason="@var{reason}"
-@end table
-@var{reason} can be one of the following:
+@item *stopped,reason="@var{reason}"
+The target has stopped. The @var{reason} field can have one of the
+following values:
@table @code
@item breakpoint-hit
A signal was received by the inferior.
@end table
+@item =thread-created,id="@var{id}"
+@itemx =thread-exited,id="@var{id}"
+A thread either was created, or has exited. The @var{id} field
+contains the @value{GDBN} identifier of the thread.
+@end table
+
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Simple Examples
-> -exec-run
<- ^running
<- (gdb)
-<- *stopped,reason="breakpoint-hit",bkptno="1",thread-id="0",
+<- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
frame=@{addr="0x08048564",func="main",
args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}],
file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"@}
@smallexample
(gdb)
-break-insert main
-^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",
+^done,bkpt=@{number="1",type="breakpoint",disp="keep",
+enabled="y",addr="0x000100d0",func="main",file="hello.c",
fullname="/home/foo/hello.c",line="5",times="0"@}
(gdb)
-break-after 1 3
@subsubheading Synopsis
@smallexample
- -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
@end smallexample
-@subheading The @code{-target-file-put} Command
+@subheading The @code{-target-file-get} Command
@findex -target-file-get
@subsubheading Synopsis
@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
Control whether to display the execution time for each command. If
set to a nonzero value, @value{GDBN} will display how much time it
took to execute each command, following the command's own output.
+The time is not printed for the commands that run the target, since
+there's no mechanism currently to compute how much time was spend
+by @value{GDBN} and how much time was spend by the program been debugged.
+it's not possibly currently
This can also be requested by invoking @value{GDBN} with the
@option{--statistics} command-line switch (@pxref{Mode Options}).
@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.
+hexadecimal integer identifying the process. The attached process is
+stopped.
This packet is only available in extended mode (@pxref{extended mode}).
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.
+state.
This packet is only available in extended mode (@pxref{extended mode}).
conventions above. Please don't use this packet as a model for new
packets.)
+@item qSearch:memory:@var{address};@var{length};@var{search-pattern}
+@cindex searching memory, in remote debugging
+@cindex @samp{qSearch:memory} packet
+@anchor{qSearch memory}
+Search @var{length} bytes at @var{address} for @var{search-pattern}.
+@var{address} and @var{length} are encoded in hex.
+@var{search-pattern} is a sequence of bytes, hex encoded.
+
+Reply:
+@table @samp
+@item 0
+The pattern was not found.
+@item 1,address
+The pattern was found at @var{address}.
+@item E @var{NN}
+A badly formed request or an error was encountered while searching memory.
+@item
+An empty reply indicates that @samp{qSearch:memory} is not recognized.
+@end table
+
@item qSupported @r{[}:@var{gdbfeature} @r{[};@var{gdbfeature}@r{]}@dots{} @r{]}
@cindex supported packets, remote query
@cindex features of the remote protocol
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