@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}
@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
@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
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}.
+@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}.
+
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.
+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.
-@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{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.
-
@item break
When called without any arguments, @code{break} sets a breakpoint at
the next instruction to be executed in the selected stack frame
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}
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
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.
@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}
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
@itemx u @var{location}
Continue running your program until either the specified location is
reached, or the current stack frame returns. @var{location} is any of
-the forms of argument acceptable to @code{break} (@pxref{Set Breaks,
-,Setting Breakpoints}). This form of the command uses breakpoints, and
+the forms described in @ref{Specify Location}.
+This form of the command uses temporary breakpoints, and
hence is quicker than @code{until} without an argument. The specified
location is actually reached only if it is in the current frame. This
implies that @code{until} can be used to skip over recursive function
@kindex advance @var{location}
@itemx advance @var{location}
Continue running the program up to the given @var{location}. An argument is
-required, which should be of the same form as arguments for the @code{break}
-command. Execution will also stop upon exit from the current stack
+required, which should be of one of the forms described in
+@ref{Specify Location}.
+Execution will also stop upon exit from the current stack
frame. This command is similar to @code{until}, but @code{advance} will
not skip over recursive function calls, and the target location doesn't
have to be in the same frame as the current one.
@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
@menu
* List:: Printing source lines
+* Specify Location:: How to specify code locations
* Edit:: Editing source files
* Search:: Searching source files
* Source Path:: Specifying source directories
@kindex l @r{(@code{list})}
To print lines from a source file, use the @code{list} command
(abbreviated @code{l}). By default, ten lines are printed.
-There are several ways to specify what part of the file you want to print.
+There are several ways to specify what part of the file you want to
+print; see @ref{Specify Location}, for the full list.
Here are the forms of the @code{list} command most commonly used:
argument of @samp{-}; that argument is preserved in repetition so that
each repetition moves up in the source file.
-@cindex linespec
In general, the @code{list} command expects you to supply zero, one or two
@dfn{linespecs}. Linespecs specify source lines; there are several ways
-of writing them, but the effect is always to specify some source line.
+of writing them (@pxref{Specify Location}), but the effect is always
+to specify some source line.
+
Here is a complete description of the possible arguments for @code{list}:
@table @code
@item list @var{first},@var{last}
Print lines from @var{first} to @var{last}. Both arguments are
-linespecs.
+linespecs. When a @code{list} command has two linespecs, and the
+source file of the second linespec is omitted, this refers to
+the same source file as the first linespec.
@item list ,@var{last}
Print lines ending with @var{last}.
As described in the preceding table.
@end table
-Here are the ways of specifying a single source line---all the
-kinds of linespec.
+@node Specify Location
+@section Specifying a Location
+@cindex specifying location
+@cindex linespec
-@table @code
-@item @var{number}
-Specifies line @var{number} of the current source file.
-When a @code{list} command has two linespecs, this refers to
-the same source file as the first linespec.
+Several @value{GDBN} commands accept arguments that specify a location
+of your program's code. Since @value{GDBN} is a source-level
+debugger, a location usually specifies some line in the source code;
+for that reason, locations are also known as @dfn{linespecs}.
-@item +@var{offset}
-Specifies the line @var{offset} lines after the last line printed.
-When used as the second linespec in a @code{list} command that has
-two, this specifies the line @var{offset} lines down from the
-first linespec.
+Here are all the different ways of specifying a code location that
+@value{GDBN} understands:
-@item -@var{offset}
-Specifies the line @var{offset} lines before the last line printed.
+@table @code
+@item @var{linenum}
+Specifies the line number @var{linenum} of the current source file.
-@item @var{filename}:@var{number}
-Specifies line @var{number} in the source file @var{filename}.
+@item -@var{offset}
+@itemx +@var{offset}
+Specifies the line @var{offset} lines before or after the @dfn{current
+line}. For the @code{list} command, the current line is the last one
+printed; for the breakpoint commands, this is the line at which
+execution stopped in the currently selected @dfn{stack frame}
+(@pxref{Frames, ,Frames}, for a description of stack frames.) When
+used as the second of the two linespecs in a @code{list} command,
+this specifies the line @var{offset} lines up or down from the first
+linespec.
+
+@item @var{filename}:@var{linenum}
+Specifies the line @var{linenum} in the source file @var{filename}.
@item @var{function}
Specifies the line that begins the body of the function @var{function}.
-For example: in C, this is the line with the open brace.
+For example, in C, this is the line with the open brace.
@item @var{filename}:@var{function}
-Specifies the line of the open-brace that begins the body of the
-function @var{function} in the file @var{filename}. You only need the
-file name with a function name to avoid ambiguity when there are
-identically named functions in different source files.
+Specifies the line that begins the body of the function @var{function}
+in the file @var{filename}. You only need the file name with a
+function name to avoid ambiguity when there are identically named
+functions in different source files.
@item *@var{address}
-Specifies the line containing the program address @var{address}.
-@var{address} may be any expression.
+Specifies the program address @var{address}. For line-oriented
+commands, such as @code{list} and @code{edit}, this specifies a source
+line that contains @var{address}. For @code{break} and other
+breakpoint oriented commands, this can be used to set breakpoints in
+parts of your program which do not have debugging information or
+source files.
+
+Here @var{address} may be any expression valid in the current working
+language (@pxref{Languages, working language}) that specifies a code
+address. In addition, as a convenience, @value{GDBN} extends the
+semantics of expressions used in locations to cover the situations
+that frequently happen during debugging. Here are the various forms
+of @var{address}:
+
+@table @code
+@item @var{expression}
+Any expression valid in the current working language.
+
+@item @var{funcaddr}
+An address of a function or procedure derived from its name. In C,
+C@t{++}, Java, Objective-C, Fortran, minimal, and assembly, this is
+simply the function's name @var{function} (and actually a special case
+of a valid expression). In Pascal and Modula-2, this is
+@code{&@var{function}}. In Ada, this is @code{@var{function}'Address}
+(although the Pascal form also works).
+
+This form specifies the address of the function's first instruction,
+before the stack frame and arguments have been set up.
+
+@item '@var{filename}'::@var{funcaddr}
+Like @var{funcaddr} above, but also specifies the name of the source
+file explicitly. This is useful if the name of the function does not
+specify the function unambiguously, e.g., if there are several
+functions with identical names in different source files.
@end table
+@end table
+
+
@node Edit
@section Editing Source Files
@cindex editing source files
is invoked with the current line set to
the active line in the program.
Alternatively, there are several ways to specify what part of the file you
-want to print if you want to see other parts of the program.
-
-Here are the forms of the @code{edit} command most commonly used:
+want to print if you want to see other parts of the program:
@table @code
-@item edit
-Edit the current source file at the active line number in the program.
+@item edit @var{location}
+Edit the source file specified by @code{location}. Editing starts at
+that @var{location}, e.g., at the specified source line of the
+specified file. @xref{Specify Location}, for all the possible forms
+of the @var{location} argument; here are the forms of the @code{edit}
+command most commonly used:
+@table @code
@item edit @var{number}
Edit the current source file with @var{number} as the active line number.
@item edit @var{function}
Edit the file containing @var{function} at the beginning of its definition.
+@end table
-@item edit @var{filename}:@var{number}
-Specifies line @var{number} in the source file @var{filename}.
-
-@item edit @var{filename}:@var{function}
-Specifies the line that begins the body of the
-function @var{function} in the file @var{filename}. You only need the
-file name with a function name to avoid ambiguity when there are
-identically named functions in different source files.
-
-@item edit *@var{address}
-Specifies the line containing the program address @var{address}.
-@var{address} may be any expression.
@end table
@subsection Choosing your Editor
@item info line @var{linespec}
Print the starting and ending addresses of the compiled code for
source line @var{linespec}. You can specify source lines in any of
-the ways understood by the @code{list} command (@pxref{List, ,Printing
-Source Lines}).
+the ways documented in @ref{Specify Location}.
@end table
For example, we can use @code{info line} to discover the location of
* C Checks:: C and C@t{++} type and range checks
* Debugging C:: @value{GDBN} and C
* Debugging C Plus Plus:: @value{GDBN} features for C@t{++}
+* Decimal Floating Point:: Numbers in Decimal Floating Point format
@end menu
@node C Operators
For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is
allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})}
-(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address
+to examine the address
where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is
stored.
@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
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}
@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.
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.
+
+@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
@end table
-@node PowerPC
-@subsection PowerPC
+@node PowerPC Embedded
+@subsection PowerPC Embedded
@value{GDBN} provides the following PowerPC-specific commands:
* 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}
@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
supported.
Additionally, @code{printf} supports conversion specifications for DFP
-(@dfn{Decimal Floating Point}) types using the following conversion
+(@dfn{Decimal Floating Point}) types using the following length modifiers
+together with a floating point specifier.
letters:
@itemize @bullet
@end itemize
If the underlying @code{C} implementation used to build @value{GDBN} has
-support for the three conversion letters for DFP types, other modifiers
+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
Here's an example of printing DFP types using the above conversion letters:
@smallexample
-printf "D32: %H - D64: %D - D128: %DD\n",1.2345df,1.2E10dd,1.2E1dl
+printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl
@end smallexample
@end table
@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
@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.
+
@end itemize
@subheading The @code{-interpreter-exec} Command
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.
@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. 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.
+
+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
@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.
+@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
projects / deliverable / binutils-gdb.git / blobdiff