\input texinfo @c -*-texinfo-*-
@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 1999, 2000, 2001, 2002, 2003
+@c 1999, 2000, 2001, 2002, 2003, 2004, 2005
@c Free Software Foundation, Inc.
@c
@c %**start of header
@c This is a dir.info fragment to support semi-automated addition of
@c manuals to an info tree.
-@dircategory Programming & development tools.
+@dircategory Software development
@direntry
-* Gdb: (gdb). The @sc{gnu} debugger.
+* Gdb: (gdb). The GNU debugger.
@end direntry
@ifinfo
Version @value{GDBVN}.
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
- 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
+ 1999, 2000, 2001, 2002, 2003, 2004, 2005@*
+ Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
@vskip 0pt plus 1filll
Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
-1996, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
+1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005
+Free Software Foundation, Inc.
@sp 2
Published by the Free Software Foundation @*
59 Temple Place - Suite 330, @*
This is the @value{EDITION} Edition, for @value{GDBN} Version
@value{GDBVN}.
-Copyright (C) 1988-2003 Free Software Foundation, Inc.
+Copyright (C) 1988-2005 Free Software Foundation, Inc.
@menu
* Summary:: Summary of @value{GDBN}
* Installing GDB:: Installing GDB
* Maintenance Commands:: Maintenance Commands
* Remote Protocol:: GDB Remote Serial Protocol
+* Agent Expressions:: The GDB Agent Expression Mechanism
* Copying:: GNU General Public License says
how you can copy and share GDB
* GNU Free Documentation License:: The license for this documentation
effects of one bug and go on to learn about another.
@end itemize
-You can use @value{GDBN} to debug programs written in C and C++.
-For more information, see @ref{Support,,Supported languages}.
+You can use @value{GDBN} to debug programs written in C and C@t{++}.
+For more information, see @ref{Supported languages,,Supported languages}.
For more information, see @ref{C,,C and C++}.
@cindex Modula-2
it may be necessary to refer to some variables with a trailing
underscore.
+@value{GDBN} can be used to debug programs written in Objective-C,
+using either the Apple/NeXT or the GNU Objective-C runtime.
+
@menu
* Free Software:: Freely redistributable software
* Contributors:: Contributors to GDB
So that they may not regard their many labors as thankless, we
particularly thank those who shepherded @value{GDBN} through major
releases:
-Andrew Cagney (releases 5.3, 5.2, 5.1 and 5.0);
+Andrew Cagney (releases 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0);
Jim Blandy (release 4.18);
Jason Molenda (release 4.17);
Stan Shebs (release 4.14);
He also enhanced the command-completion support to cover C@t{++} overloaded
symbols.
-Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and
-Super-H processors.
+Hitachi America (now Renesas America), Ltd. sponsored the support for
+H8/300, H8/500, and Super-H processors.
NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.
-Mitsubishi sponsored the support for D10V, D30V, and M32R/D processors.
+Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D
+processors.
Toshiba sponsored the support for the TX39 Mips processor.
The following people at the Hewlett-Packard Company contributed
support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
(narrow mode), HP's implementation of kernel threads, HP's aC@t{++}
-compiler, and the terminal user interface: Ben Krepp, Richard Title,
-John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve
-Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific
-information in this manual.
+compiler, and the Text User Interface (nee Terminal User Interface):
+Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann,
+Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase
+provided HP-specific information in this manual.
DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project.
Robert Hoehne made significant contributions to the DJGPP port.
* Invoking GDB:: How to start @value{GDBN}
* Quitting GDB:: How to quit @value{GDBN}
* Shell Commands:: How to use shell commands inside @value{GDBN}
+* Logging output:: How to log @value{GDBN}'s output to a file
@end menu
@node Invoking GDB
If the second argument begins with a decimal digit, @value{GDBN} will
first attempt to attach to it as a process, and if that fails, attempt
to open it as a corefile. If you have a corefile whose name begins with
-a digit, you can prevent @value{GDBN} from treating it as a pid by
+a digit, you can prevent @value{GDBN} from treating it as a pid by
prefixing it with @file{./}, eg. @file{./12345}.
If @value{GDBN} has not been configured to included core file support,
@itemx -c @var{file}
@cindex @code{--core}
@cindex @code{-c}
-Use file @var{file} as a core dump to examine.
+Use file @var{file} as a core dump to examine.
@item -c @var{number}
@item -pid @var{number}
@cindex @code{--annotate}
This option sets the @dfn{annotation level} inside @value{GDBN}. Its
effect is identical to using @samp{set annotate @var{level}}
-(@pxref{Annotations}).
-Annotation level controls how much information does @value{GDBN} print
-together with its prompt, values of expressions, source lines, and other
-types of output. Level 0 is the normal, level 1 is for use when
-@value{GDBN} is run as a subprocess of @sc{gnu} Emacs, level 2 is the
-maximum annotation suitable for programs that control @value{GDBN}.
-
-@item -async
-@cindex @code{--async}
-Use the asynchronous event loop for the command-line interface.
-@value{GDBN} processes all events, such as user keyboard input, via a
-special event loop. This allows @value{GDBN} to accept and process user
-commands in parallel with the debugged process being
-run@footnote{@value{GDBN} built with @sc{djgpp} tools for
-MS-DOS/MS-Windows supports this mode of operation, but the event loop is
-suspended when the debuggee runs.}, so you don't need to wait for
-control to return to @value{GDBN} before you type the next command.
-(@emph{Note:} as of version 5.1, the target side of the asynchronous
-operation is not yet in place, so @samp{-async} does not work fully
-yet.)
-@c FIXME: when the target side of the event loop is done, the above NOTE
-@c should be removed.
-
-When the standard input is connected to a terminal device, @value{GDBN}
-uses the asynchronous event loop by default, unless disabled by the
-@samp{-noasync} option.
-
-@item -noasync
-@cindex @code{--noasync}
-Disable the asynchronous event loop for the command-line interface.
+(@pxref{Annotations}). The annotation @var{level} controls how much
+information @value{GDBN} prints together with its prompt, values of
+expressions, source lines, and other types of output. Level 0 is the
+normal, level 1 is for use when @value{GDBN} is run as a subprocess of
+@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs
+that control @value{GDBN}, and level 2 has been deprecated.
+
+The annotation mechanism has largely been superseeded by @sc{gdb/mi}
+(@pxref{GDB/MI}).
@item --args
@cindex @code{--args}
Set the line speed (baud rate or bits per second) of any serial
interface used by @value{GDBN} for remote debugging.
+@item -l @var{timeout}
+@cindex @code{-l}
+Set the timeout (in seconds) of any communication used by @value{GDBN}
+for remote debugging.
+
@item -tty @var{device}
@itemx -t @var{device}
@cindex @code{--tty}
@c resolve the situation of these eventually
@item -tui
@cindex @code{--tui}
-Activate the Terminal User Interface when starting.
-The Terminal User Interface manages several text windows on the terminal,
-showing source, assembly, registers and @value{GDBN} command outputs
-(@pxref{TUI, ,@value{GDBN} Text User Interface}).
-Do not use this option if you run @value{GDBN} from Emacs
-(@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}).
+Activate the @dfn{Text User Interface} when starting. The Text User
+Interface manages several text windows on the terminal, showing
+source, assembly, registers and @value{GDBN} command outputs
+(@pxref{TUI, ,@value{GDBN} Text User Interface}). Alternatively, the
+Text User Interface can be enabled by invoking the program
+@samp{gdbtui}. Do not use this option if you run @value{GDBN} from
+Emacs (@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}).
@c @item -xdb
@c @cindex @code{--xdb}
@xref{Interpreters, , Command Interpreters}.
@samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes
-@value{GDBN} to use the current @dfn{@sc{gdb/mi} interface}
-(@pxref{GDB/MI, , The @sc{gdb/mi} Interface}). The previous @sc{gdb/mi}
-interface, included in @value{GDBN} version 5.3, can be selected with
-@samp{--interpreter=mi1}. Earlier @sc{gdb/mi} interfaces
-are not supported.
+@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, ,
+The @sc{gdb/mi} Interface}) included since @var{GDBN} version 6.0. The
+previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and
+selected with @samp{--interpreter=mi1}, is deprecated. Earlier
+@sc{gdb/mi} interfaces are no longer supported.
@item -write
@cindex @code{--write}
arguments. This is equivalent to @samp{shell make @var{make-args}}.
@end table
+@node Logging output
+@section Logging output
+@cindex logging @value{GDBN} output
+@cindex save @value{GDBN} output to a file
+
+You may want to save the output of @value{GDBN} commands to a file.
+There are several commands to control @value{GDBN}'s logging.
+
+@table @code
+@kindex set logging
+@item set logging on
+Enable logging.
+@item set logging off
+Disable logging.
+@cindex logging file name
+@item set logging file @var{file}
+Change the name of the current logfile. The default logfile is @file{gdb.txt}.
+@item set logging overwrite [on|off]
+By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if
+you want @code{set logging on} to overwrite the logfile instead.
+@item set logging redirect [on|off]
+By default, @value{GDBN} output will go to both the terminal and the logfile.
+Set @code{redirect} if you want output to go only to the log file.
+@kindex show logging
+@item show logging
+Show the current values of the logging settings.
+@end table
+
@node Commands
@chapter @value{GDBN} Commands
@kindex apropos
@item apropos @var{args}
-The @code{apropos @var{args}} command searches through all of the @value{GDBN}
+The @code{apropos} command searches through all of the @value{GDBN}
commands, and their documentation, for the regular expression specified in
@var{args}. It prints out all matches found. For example:
@table @code
@kindex show version
-@cindex version number
+@cindex @value{GDBN} version number
@item show version
Show what version of @value{GDBN} is running. You should include this
information in @value{GDBN} bug-reports. If multiple versions of
@value{GDBN}.
@kindex show copying
+@kindex info copying
+@cindex display @value{GDBN} copyright
@item show copying
+@itemx info copying
Display information about permission for copying @value{GDBN}.
@kindex show warranty
+@kindex info warranty
@item show warranty
+@itemx info warranty
Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
if your version of @value{GDBN} comes with one.
@samp{-g}, particularly on machines with instruction scheduling. If in
doubt, recompile with @samp{-g} alone, and if this fixes the problem,
please report it to us as a bug (including a test case!).
+@xref{Variables}, for more information about debugging optimized code.
Older versions of the @sc{gnu} C compiler permitted a variant option
@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this
table, and reads it again. When it does this, @value{GDBN} tries to retain
your current breakpoints.
+@table @code
+@kindex start
+@item start
+@cindex run to main procedure
+The name of the main procedure can vary from language to language.
+With C or C@t{++}, the main procedure name is always @code{main}, but
+other languages such as Ada do not require a specific name for their
+main procedure. The debugger provides a convenient way to start the
+execution of the program and to stop at the beginning of the main
+procedure, depending on the language used.
+
+The @samp{start} command does the equivalent of setting a temporary
+breakpoint at the beginning of the main procedure and then invoking
+the @samp{run} command.
+
+@cindex elaboration phase
+Some programs contain an @dfn{elaboration} phase where some startup code is
+executed before the main procedure is called. This depends on the
+languages used to write your program. In C@t{++}, for instance,
+constructors for static and global objects are executed before
+@code{main} is called. It is therefore possible that the debugger stops
+before reaching the main procedure. However, the temporary breakpoint
+will remain to halt execution.
+
+Specify the arguments to give to your program as arguments to the
+@samp{start} command. These arguments will be given verbatim to the
+underlying @samp{run} command. Note that the same arguments will be
+reused if no argument is provided during subsequent calls to
+@samp{start} or @samp{run}.
+
+It is sometimes necessary to debug the program during elaboration. In
+these cases, using the @code{start} command would stop the execution of
+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.
+@end table
+
@node Arguments
@section Your program's arguments
@table @code
@kindex cd
+@cindex change working directory
@item cd @var{directory}
Set the @value{GDBN} working directory to @var{directory}.
Print the @value{GDBN} working directory.
@end table
+It is generally impossible to find the current working directory of
+the process being debugged (since a program can change its directory
+during its run). If you work on a system where @value{GDBN} is
+configured with the @file{/proc} support, you can use the @code{info
+proc} command (@pxref{SVR4 Process Information}) to find out the
+current working directory of the debuggee.
+
@node Input/Output
@section Your program's input and output
This command attaches to a running process---one that was started
outside @value{GDBN}. (@code{info files} shows your active
targets.) The command takes as argument a process ID. The usual way to
-find out the process-id of a Unix process is with the @code{ps} utility,
+find out the @var{process-id} of a Unix process is with the @code{ps} utility,
or with the @samp{jobs -l} shell command.
@code{attach} does not repeat if you press @key{RET} a second time after
program. @value{GDBN} displays for each thread (in this order):
@enumerate
-@item the thread number assigned by @value{GDBN}
+@item
+the thread number assigned by @value{GDBN}
-@item the target system's thread identifier (@var{systag})
+@item
+the target system's thread identifier (@var{systag})
-@item the current stack frame summary for that thread
+@item
+the current stack frame summary for that thread
@end enumerate
@noindent
On HP-UX systems:
-@cindex thread number
-@cindex thread identifier (GDB)
+@cindex debugging multithreaded programs (on HP-UX)
+@cindex thread identifier (GDB), on HP-UX
For debugging purposes, @value{GDBN} associates its own thread
number---a small integer assigned in thread-creation order---with each
thread in your program.
when @value{GDBN} notices a new thread.
@table @code
-@kindex info threads
+@kindex info threads (HP-UX)
@item info threads
Display a summary of all threads currently in your
program. @value{GDBN} displays for each thread (in this order):
the child process (@pxref{Attach}). From that point on you can debug
the child process just like any other process which you attached to.
-On HP-UX (11.x and later only?), @value{GDBN} provides support for
-debugging programs that create additional processes using the
-@code{fork} or @code{vfork} function.
+On some systems, @value{GDBN} provides support for debugging programs that
+create additional processes using the @code{fork} or @code{vfork} functions.
+Currently, the only platforms with this feature are HP-UX (11.x and later
+only?) and GNU/Linux (kernel version 2.5.60 and later).
By default, when a program forks, @value{GDBN} will continue to debug
the parent process and the child process will run unimpeded.
@item set follow-fork-mode @var{mode}
Set the debugger response to a program call of @code{fork} or
@code{vfork}. A call to @code{fork} or @code{vfork} creates a new
-process. The @var{mode} can be:
+process. The @var{mode} argument can be:
@table @code
@item parent
The new process is debugged after a fork. The parent process runs
unimpeded.
-@item ask
-The debugger will ask for one of the above choices.
@end table
+@kindex show follow-fork-mode
@item show follow-fork-mode
Display the current debugger response to a @code{fork} or @code{vfork} call.
@end table
should stop by line number, function name or exact address in the
program.
-In HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can set
-breakpoints in shared libraries before the executable is run. There is
-a minor limitation on HP-UX systems: you must wait until the executable
-is run in order to set breakpoints in shared library routines that are
-not called directly by the program (for example, routines that are
-arguments in a @code{pthread_create} call).
+On some systems, you can set breakpoints in shared libraries before
+the executable is run. There is a minor limitation on HP-UX systems:
+you must wait until the executable is run in order to set breakpoints
+in shared library routines that are not called directly by the program
+(for example, routines that are arguments in a @code{pthread_create}
+call).
@cindex watchpoints
@cindex memory tracing
* Break Commands:: Breakpoint command lists
* Breakpoint Menus:: Breakpoint menus
* Error in Breakpoints:: ``Cannot insert breakpoints''
+* Breakpoint related warnings:: ``Breakpoint address adjusted...''
@end menu
@node Set Breaks
have this support. The main purpose of this is EPROM/ROM code
debugging, so you can set a breakpoint at an instruction without
changing the instruction. This can be used with the new trap-generation
-provided by SPARClite DSU and some x86-based targets. These targets
+provided by SPARClite DSU and most x86-based targets. These targets
will generate traps when a program accesses some data or instruction
address that is assigned to the debug registers. However the hardware
breakpoint registers can take a limited number of breakpoints. For
@value{GDBN} will reject this command if more than two are used. Delete
or disable unused hardware breakpoints before setting new ones
(@pxref{Disabling, ,Disabling}). @xref{Conditions, ,Break conditions}.
-@xref{set remote hardware-breakpoint-limit}.
+For remote targets, you can restrict the number of hardware
+breakpoints @value{GDBN} will use, see @ref{set remote
+hardware-breakpoint-limit}.
@kindex thbreak
@code{.*} leading and trailing the regular expression you supply, so to
match only functions that begin with @code{foo}, use @code{^foo}.
+@cindex non-member C@t{++} functions, set breakpoint in
When debugging C@t{++} programs, @code{rbreak} is useful for setting
breakpoints on overloaded functions that are not members of any special
classes.
+@cindex set breakpoints on all functions
+The @code{rbreak} command can be used to set breakpoints in
+@strong{all} the functions in a program, like this:
+
+@smallexample
+(@value{GDBP}) rbreak .
+@end smallexample
+
@kindex info breakpoints
@cindex @code{$_} and @code{info breakpoints}
@item info breakpoints @r{[}@var{n}@r{]}
Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
that are not enabled.
@item Address
-Where the breakpoint is in your program, as a memory address.
+Where the breakpoint is in your program, as a memory address. If the
+breakpoint is pending (see below for details) on a future load of a shared library, the address
+will be listed as @samp{<PENDING>}.
@item What
Where the breakpoint is in the source for your program, as a file and
-line number.
+line number. For a pending breakpoint, the original string passed to
+the breakpoint command will be listed as it cannot be resolved until
+the appropriate shared library is loaded in the future.
@end table
@noindent
If a breakpoint is conditional, @code{info break} shows the condition on
the line following the affected breakpoint; breakpoint commands, if any,
-are listed after that.
+are listed after that. A pending breakpoint is allowed to have a condition
+specified for it. The condition is not parsed for validity until a shared
+library is loaded that allows the pending breakpoint to resolve to a
+valid location.
@noindent
@code{info break} with a breakpoint
the breakpoints are conditional, this is even useful
(@pxref{Conditions, ,Break conditions}).
+@cindex pending breakpoints
+If a specified breakpoint location cannot be found, it may be due to the fact
+that the location is in a shared library that is yet to be loaded. In such
+a case, you may want @value{GDBN} to create a special breakpoint (known as
+a @dfn{pending breakpoint}) that
+attempts to resolve itself in the future when an appropriate shared library
+gets loaded.
+
+Pending breakpoints are useful to set at the start of your
+@value{GDBN} session for locations that you know will be dynamically loaded
+later by the program being debugged. When shared libraries are loaded,
+a check is made to see if the load resolves any pending breakpoint locations.
+If a pending breakpoint location gets resolved,
+a regular breakpoint is created and the original pending breakpoint is removed.
+
+@value{GDBN} provides some additional commands for controlling pending
+breakpoint support:
+
+@kindex set breakpoint pending
+@kindex show breakpoint pending
+@table @code
+@item set breakpoint pending auto
+This is the default behavior. When @value{GDBN} cannot find the breakpoint
+location, it queries you whether a pending breakpoint should be created.
+
+@item set breakpoint pending on
+This indicates that an unrecognized breakpoint location should automatically
+result in a pending breakpoint being created.
+
+@item set breakpoint pending off
+This indicates that pending breakpoints are not to be created. Any
+unrecognized breakpoint location results in an error. This setting does
+not affect any pending breakpoints previously created.
+
+@item show breakpoint pending
+Show the current behavior setting for creating pending breakpoints.
+@end table
+
+@cindex operations allowed on pending breakpoints
+Normal breakpoint operations apply to pending breakpoints as well. You may
+specify a condition for a pending breakpoint and/or commands to run when the
+breakpoint is reached. You can also enable or disable
+the pending breakpoint. When you specify a condition for a pending breakpoint,
+the parsing of the condition will be deferred until the point where the
+pending breakpoint location is resolved. Disabling a pending breakpoint
+tells @value{GDBN} to not attempt to resolve the breakpoint on any subsequent
+shared library load. When a pending breakpoint is re-enabled,
+@value{GDBN} checks to see if the location is already resolved.
+This is done because any number of shared library loads could have
+occurred since the time the breakpoint was disabled and one or more
+of these loads could resolve the location.
+
@cindex negative breakpoint numbers
@cindex internal @value{GDBN} breakpoints
@value{GDBN} itself sometimes sets breakpoints in your program for
@subsection Setting watchpoints
@cindex setting watchpoints
-@cindex software watchpoints
-@cindex hardware watchpoints
You can use a watchpoint to stop execution whenever the value of an
expression changes, without having to predict a particular place where
this may happen.
+@cindex software watchpoints
+@cindex hardware watchpoints
Depending on your system, watchpoints may be implemented in software or
hardware. @value{GDBN} does software watchpointing by single-stepping your
program and testing the variable's value each time, which is hundreds of
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 some other x86-based targets,
-@value{GDBN} includes support for
-hardware watchpoints, which do not slow down the running of your
-program.
+On some systems, such as HP-UX, @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
@kindex rwatch
@item rwatch @var{expr}
-Set a watchpoint that will break when watch @var{expr} is read by the program.
+Set a watchpoint that will break when the value of @var{expr} is read
+by the program.
@kindex awatch
@item awatch @var{expr}
-Set a watchpoint that will break when @var{expr} is either read or written into
-by the program.
+Set a watchpoint that will break when @var{expr} is either read from
+or written into by the program.
@kindex info watchpoints
@item info watchpoints
This command prints a list of watchpoints, breakpoints, and catchpoints;
-it is the same as @code{info break}.
+it is the same as @code{info break} (@pxref{Set Breaks}).
@end table
@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware
value at the exact instruction where the change occurs. If @value{GDBN}
cannot set a hardware watchpoint, it sets a software watchpoint, which
executes more slowly and reports the change in value at the next
-statement, not the instruction, after the change occurs.
+@emph{statement}, not the instruction, after the change occurs.
+
+@vindex can-use-hw-watchpoints
+@cindex use only software watchpoints
+You can force @value{GDBN} to use only software watchpoints with the
+@kbd{set can-use-hw-watchpoints 0} command. With this variable set to
+zero, @value{GDBN} will never try to use hardware watchpoints, even if
+the underlying system supports them. (Note that hardware-assisted
+watchpoints that were set @emph{before} setting
+@code{can-use-hw-watchpoints} to zero will still use the hardware
+mechanism of watching expressiion values.)
+
+@table @code
+@item set can-use-hw-watchpoints
+@kindex set can-use-hw-watchpoints
+Set whether or not to use hardware watchpoints.
+
+@item show can-use-hw-watchpoints
+@kindex show can-use-hw-watchpoints
+Show the current mode of using hardware watchpoints.
+@end table
+
+For remote targets, you can restrict the number of hardware
+watchpoints @value{GDBN} will use, see @ref{set remote
+hardware-breakpoint-limit}.
When you issue the @code{watch} command, @value{GDBN} reports
Stop when @var{event} occurs. @var{event} can be any of the following:
@table @code
@item throw
-@kindex catch throw
+@cindex stop on C@t{++} exceptions
The throwing of a C@t{++} exception.
@item catch
-@kindex catch catch
The catching of a C@t{++} exception.
@item exec
-@kindex catch exec
+@cindex break on fork/exec
A call to @code{exec}. This is currently only available for HP-UX.
@item fork
-@kindex catch fork
A call to @code{fork}. This is currently only available for HP-UX.
@item vfork
-@kindex catch vfork
A call to @code{vfork}. This is currently only available for HP-UX.
@item load
@itemx load @var{libname}
-@kindex catch load
+@cindex break on load/unload of shared library
The dynamic loading of any shared library, or the loading of the library
@var{libname}. This is currently only available for HP-UX.
@item unload
@itemx unload @var{libname}
-@kindex catch unload
The unloading of any dynamically loaded shared library, or the unloading
of the library @var{libname}. This is currently only available for HP-UX.
@end table
@item clear @var{function}
@itemx clear @var{filename}:@var{function}
-Delete any breakpoints set at entry to the function @var{function}.
+Delete any breakpoints set at entry to the named @var{function}.
@item clear @var{linenum}
@itemx clear @var{filename}:@var{linenum}
-Delete any breakpoints set at or within the code of the specified line.
+Delete any breakpoints set at or within the code of the specified
+@var{linenum} of the specified @var{filename}.
@cindex delete breakpoints
@kindex delete
@node Disabling
@subsection Disabling breakpoints
-@kindex disable breakpoints
-@kindex enable breakpoints
+@cindex enable/disable a breakpoint
Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
prefer to @dfn{disable} it. This makes the breakpoint inoperative as if
it had been deleted, but remembers the information on the breakpoint so
watchpoints, and catchpoints:
@table @code
-@kindex disable breakpoints
@kindex disable
@kindex dis @r{(@code{disable})}
@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
case the breakpoint is enabled again later. You may abbreviate
@code{disable} as @code{dis}.
-@kindex enable breakpoints
@kindex enable
@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
Enable the specified breakpoints (or all defined breakpoints). They
@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
Enable the specified breakpoints to work once, then die. @value{GDBN}
deletes any of these breakpoints as soon as your program stops there.
+Breakpoints set by the @code{tbreak} command start out in this state.
@end table
@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is
@cindex overloading
@cindex symbol overloading
-Some programming languages (notably C@t{++}) permit a single function name
+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
When this message is printed, you need to disable or remove some of the
hardware-assisted breakpoints and watchpoints, and then continue.
+@node Breakpoint related warnings
+@subsection ``Breakpoint address adjusted...''
+@cindex breakpoint address adjusted
+
+Some processor architectures place constraints on the addresses at
+which breakpoints may be placed. For architectures thus constrained,
+@value{GDBN} will attempt to adjust the breakpoint's address to comply
+with the constraints dictated by the architecture.
+
+One example of such an architecture is the Fujitsu FR-V. The FR-V is
+a VLIW architecture in which a number of RISC-like instructions may be
+bundled together for parallel execution. The FR-V architecture
+constrains the location of a breakpoint instruction within such a
+bundle to the instruction with the lowest address. @value{GDBN}
+honors this constraint by adjusting a breakpoint's address to the
+first in the bundle.
+
+It is not uncommon for optimized code to have bundles which contain
+instructions from different source statements, thus it may happen that
+a breakpoint's address will be adjusted from one source statement to
+another. Since this adjustment may significantly alter @value{GDBN}'s
+breakpoint related behavior from what the user expects, a warning is
+printed when the breakpoint is first set and also when the breakpoint
+is hit.
+
+A warning like the one below is printed when setting a breakpoint
+that's been subject to address adjustment:
+
+@smallexample
+warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.
+@end smallexample
+
+Such warnings are printed both for user settable and @value{GDBN}'s
+internal breakpoints. If you see one of these warnings, you should
+verify that a breakpoint set at the adjusted address will have the
+desired affect. If not, the breakpoint in question may be removed and
+other breakpoints may be set which will have the desired behavior.
+E.g., it may be sufficient to place the breakpoint at a later
+instruction. A conditional breakpoint may also be useful in some
+cases to prevent the breakpoint from triggering too often.
+
+@value{GDBN} will also issue a warning when stopping at one of these
+adjusted breakpoints:
+
+@smallexample
+warning: Breakpoint 1 address previously adjusted from 0x00010414
+to 0x00010410.
+@end smallexample
+
+When this warning is encountered, it may be too late to take remedial
+action except in cases where the breakpoint is hit earlier or more
+frequently than expected.
@node Continuing and Stepping
@section Continuing and stepping
Causes the @code{step} command to step over any functions which contains no
debug information. This is the default.
+@item show step-mode
+Show whether @value{GDBN} will stop in or step over functions without
+source line debug information.
+
@kindex finish
@item finish
Continue running until just after function in the selected stack frame
@kindex until
@kindex u @r{(@code{until})}
+@cindex run until specified location
@item until
@itemx u
Continue running until a source line past the current line, in the
@kindex advance @var{location}
@itemx advance @var{location}
-Continue running the program up to the given location. An argument is
-required, anything of the same form as arguments for the @code{break}
+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
frame. This command is similar to @code{until}, but @code{advance} will
not skip over recursive function calls, and the target location doesn't
@table @code
@kindex info signals
+@kindex info handle
@item info signals
@itemx info handle
Print a table of all the kinds of signals and how @value{GDBN} has been told to
switching between threads, without worrying that things may change
underfoot.
+@cindex thread breakpoints and system calls
+@cindex system calls and thread breakpoints
+@cindex premature return from system calls
+There is an unfortunate side effect. If one thread stops for a
+breakpoint, or for some other reason, and another thread is blocked in a
+system call, then the system call may return prematurely. This is a
+consequence of the interaction between multiple threads and the signals
+that @value{GDBN} uses to implement breakpoints and other events that
+stop execution.
+
+To handle this problem, your program should check the return value of
+each system call and react appropriately. This is good programming
+style anyways.
+
+For example, do not write code like this:
+
+@smallexample
+ sleep (10);
+@end smallexample
+
+The call to @code{sleep} will return early if a different thread stops
+at a breakpoint or for some other reason.
+
+Instead, write this:
+
+@smallexample
+ int unslept = 10;
+ while (unslept > 0)
+ unslept = sleep (unslept);
+@end smallexample
+
+A system call is allowed to return early, so the system is still
+conforming to its specification. But @value{GDBN} does cause your
+multi-threaded program to behave differently than it would without
+@value{GDBN}.
+
+Also, @value{GDBN} uses internal breakpoints in the thread library to
+monitor certain events such as thread creation and thread destruction.
+When such an event happens, a system call in another thread may return
+prematurely, even though your program does not appear to stop.
+
@cindex continuing threads
@cindex threads, continuing
Conversely, whenever you restart the program, @emph{all} threads start
@table @code
@item set scheduler-locking @var{mode}
+@cindex scheduler locking mode
+@cindex lock scheduler
Set the scheduler locking mode. If it is @code{off}, then there is no
locking and any thread may run at any time. If @code{on}, then only the
current thread may run when the inferior is resumed. The @code{step}
@node Backtrace
@section Backtraces
-@cindex backtraces
-@cindex tracebacks
-@cindex stack traces
+@cindex traceback
+@cindex call stack traces
A backtrace is a summary of how your program got where it is. It shows one
line per frame, for many frames, starting with the currently executing
frame (frame zero), followed by its caller (frame one), and on up the
@kindex where
@kindex info stack
-@kindex info s @r{(@code{info stack})}
The names @code{where} and @code{info stack} (abbreviated @code{info s})
are additional aliases for @code{backtrace}.
value, indicating that your program has stopped at the beginning of the
code for line @code{993} of @code{builtin.c}.
-@kindex set backtrace-below-main
-@kindex show backtrace-below-main
+@cindex backtrace beyond @code{main} function
+@cindex program entry point
+@cindex startup code, and backtrace
+Most programs have a standard user entry point---a place where system
+libraries and startup code transition into user code. For C this is
+@code{main}. When @value{GDBN} finds the entry function in a backtrace
+it will terminate the backtrace, to avoid tracing into highly
+system-specific (and generally uninteresting) code.
-Most programs have a standard entry point---a place where system libraries
-and startup code transition into user code. For C this is @code{main}.
-When @value{GDBN} finds the entry function in a backtrace it will terminate
-the backtrace, to avoid tracing into highly system-specific (and generally
-uninteresting) code. If you need to examine the startup code, then you can
-change this behavior.
+If you need to examine the startup code, or limit the number of levels
+in a backtrace, you can change this behavior:
@table @code
-@item set backtrace-below-main off
+@item set backtrace past-main
+@itemx set backtrace past-main on
+@kindex set backtrace
+Backtraces will continue past the user entry point.
+
+@item set backtrace past-main off
Backtraces will stop when they encounter the user entry point. This is the
default.
-@item set backtrace-below-main
-@itemx set backtrace-below-main on
-Backtraces will continue past the user entry point to the top of the stack.
+@item show backtrace past-main
+@kindex show backtrace
+Display the current user entry point backtrace policy.
+
+@item set backtrace past-entry
+@itemx set backtrace past-entry on
+Backtraces will continue past the internal entry point of an application.
+This entry point is encoded by the linker when the application is built,
+and is likely before the user entry point @code{main} (or equivalent) is called.
+
+@item set backtrace past-entry off
+Backtraces will stop when they encouter the internal entry point of an
+application. This is the default.
-@item show backtrace-below-main
-Display the current backtrace policy.
+@item show backtrace past-entry
+Display the current internal entry point backtrace policy.
+
+@item set backtrace limit @var{n}
+@itemx set backtrace limit 0
+@cindex backtrace limit
+Limit the backtrace to @var{n} levels. A value of zero means
+unlimited.
+
+@item show backtrace limit
+Display the current limit on backtrace levels.
@end table
@node Selection
Print lines just before the lines last printed.
@end table
+@cindex @code{list}, how many lines to display
By default, @value{GDBN} prints ten source lines with any of these forms of
the @code{list} command. You can change this using @code{set listsize}:
@smallexample
ex +@var{number} file
@end smallexample
-The optional numeric value +@var{number} designates the active line in
-the file.}. By default, it is @value{EDITOR}, but you can change this
+The optional numeric value +@var{number} specifies the number of the line in
+the file where to start editing.}.
+By default, it is @file{@value{EDITOR}}, but you can change this
by setting the environment variable @code{EDITOR} before using
@value{GDBN}. For example, to configure @value{GDBN} to use the
@code{vi} editor, you could use these commands with the @code{sh} shell:
@smallexample
EDITOR=/usr/bin/vi
export EDITOR
-gdb ...
+gdb @dots{}
@end smallexample
or in the @code{csh} shell,
@smallexample
setenv EDITOR /usr/bin/vi
-gdb ...
+gdb @dots{}
@end smallexample
@node Search
@section Searching source files
-@cindex searching
-@kindex reverse-search
+@cindex searching source files
There are two commands for searching through the current source file for a
regular expression.
synonym @samp{search @var{regexp}} or abbreviate the command name as
@code{fo}.
+@kindex reverse-search
@item reverse-search @var{regexp}
The command @samp{reverse-search @var{regexp}} checks each line, starting
with the one before the last line listed and going backward, for a match
session. @value{GDBN} has a list of directories to search for source files;
this is called the @dfn{source path}. Each time @value{GDBN} wants a source file,
it tries all the directories in the list, in the order they are present
-in the list, until it finds a file with the desired name. Note that
-the executable search path is @emph{not} used for this purpose. Neither is
-the current working directory, unless it happens to be in the source
-path.
-
-If @value{GDBN} cannot find a source file in the source path, and the
-object program records a directory, @value{GDBN} tries that directory
-too. If the source path is empty, and there is no record of the
-compilation directory, @value{GDBN} looks in the current directory as a
-last resort.
+in the list, until it finds a file with the desired name.
+
+For example, suppose an executable references the file
+@file{/usr/src/foo-1.0/lib/foo.c}, and our source path is
+@file{/mnt/cross}. The file is first looked up literally; if this
+fails, @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} is tried; if this
+fails, @file{/mnt/cross/foo.c} is opened; if this fails, an error
+message is printed. @value{GDBN} does not look up the parts of the
+source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}.
+Likewise, the subdirectories of the source path are not searched: if
+the source path is @file{/mnt/cross}, and the binary refers to
+@file{foo.c}, @value{GDBN} would not find it under
+@file{/mnt/cross/usr/src/foo-1.0/lib}.
+
+Plain file names, relative file names with leading directories, file
+names containing dots, etc.@: are all treated as described above; for
+instance, if the source path is @file{/mnt/cross}, and the source file
+is recorded as @file{../lib/foo.c}, @value{GDBN} would first try
+@file{../lib/foo.c}, then @file{/mnt/cross/../lib/foo.c}, and after
+that---@file{/mnt/cross/foo.c}.
+
+Note that the executable search path is @emph{not} used to locate the
+source files. Neither is the current working directory, unless it
+happens to be in the source path.
Whenever you reset or rearrange the source path, @value{GDBN} clears out
any information it has cached about where source files are found and where
@node Machine Code
@section Source and machine code
+@cindex source line and its code address
You can use the command @code{info line} to map source lines to program
addresses (and vice versa), and the command @code{disassemble} to display
@end smallexample
@noindent
+@cindex code address and its source line
We can also inquire (using @code{*@var{addr}} as the form for
@var{linespec}) what source line covers a particular address:
@smallexample
@end smallexample
@cindex @code{$_} and @code{info line}
+@cindex @code{x} command, default address
@kindex x@r{(examine), and} info line
After @code{info line}, the default address for the @code{x} command
is changed to the starting address of the line, so that @samp{x/i} is
@table @code
@kindex set disassembly-flavor
-@cindex assembly instructions
-@cindex instructions, assembly
-@cindex machine instructions
-@cindex listing machine instructions
@cindex Intel disassembly flavor
@cindex AT&T disassembly flavor
@item set disassembly-flavor @var{instruction-set}
can set @var{instruction-set} to either @code{intel} or @code{att}.
The default is @code{att}, the AT&T flavor used by default by Unix
assemblers for x86-based targets.
+
+@kindex show disassembly-flavor
+@item show disassembly-flavor
+Show the current setting of the disassembly flavor.
@end table
@item print
@itemx print /@var{f}
+@cindex reprint the last value
If you omit @var{expr}, @value{GDBN} displays the last value again (from the
@dfn{value history}; @pxref{Value History, ,Value history}). This allows you to
conveniently inspect the same value in an alternative format.
* Registers:: Registers
* Floating Point Hardware:: Floating point hardware
* Vector Unit:: Vector Unit
+* OS Information:: Auxiliary data provided by operating system
* Memory Region Attributes:: Memory region attributes
* Dump/Restore Files:: Copy between memory and a file
+* Core File Generation:: Cause a program dump its core
* Character Sets:: Debugging programs that use a different
character set than GDB does
+* Caching Remote Data:: Data caching for remote targets
@end menu
@node Expressions
you compiled your program to include this information; see
@ref{Compilation}.
+@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
In this section, we discuss operators that you can use in @value{GDBN}
expressions regardless of your programming language.
+@cindex casts, in expressions
Casts are supported in all languages, not just in C, because it is so
useful to cast a number into a pointer in order to examine a structure
at that address in memory.
function with the same name (in different source files). If that
happens, referring to that name has unpredictable effects. If you wish,
you can specify a static variable in a particular function or file,
-using the colon-colon notation:
+using the colon-colon (@code{::}) notation:
@cindex colon-colon, context for variables/functions
@iftex
@cindex wrong values
@cindex variable values, wrong
+@cindex function entry/exit, wrong values of variables
+@cindex optimized code, wrong values of variables
@quotation
@emph{Warning:} Occasionally, a local variable may appear to have the
wrong value at certain points in a function---just after entry to a new
To solve such problems, either recompile without optimizations, or use a
different debug info format, if the compiler supports several such
-formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler
+formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler,
usually supports the @option{-gstabs+} option. @option{-gstabs+}
produces debug info in a format that is superior to formats such as
COFF. You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also
an effective form for debug info. @xref{Debugging Options,,Options
for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}.
-
+@xref{C, , Debugging C++}, for more info about debug info formats
+that are best suited to C@t{++} programs.
@node Arrays
@section Artificial arrays
@cindex artificial array
+@cindex arrays
@kindex @@@r{, referencing memory as an array}
It is often useful to print out several successive objects of the
same type in memory; a section of an array, or an array of
are from the last memory unit printed; this is not the same as the last
address printed if several units were printed on the last line of output.
+@cindex remote memory comparison
+@cindex verify remote memory image
+When you are debugging a program running on a remote target machine
+(@pxref{Remote}), you may wish to verify the program's image in the
+remote machine's memory against the executable file you downloaded to
+the target. The @code{compare-sections} command is provided for such
+situations.
+
+@table @code
+@kindex compare-sections
+@item compare-sections @r{[}@var{section-name}@r{]}
+Compare the data of a loadable section @var{section-name} in the
+executable file of the program being debugged with the same section in
+the remote machine's memory, and report any mismatches. With no
+arguments, compares all loadable sections. This command's
+availability depends on the target's support for the @code{"qCRC"}
+remote request.
+@end table
+
@node Auto Display
@section Automatic display
@cindex automatic display
because they refer to automatic variables not currently available.
@end table
+@cindex display disabled out of scope
If a display expression refers to local variables, then it does not make
sense outside the lexical context for which it was set up. Such an
expression is disabled when execution enters a context where one of its
These settings are useful for debugging programs in any language:
@table @code
-@kindex set print address
+@kindex set print
@item set print address
@itemx set print address on
+@cindex print/don't print memory addresses
@value{GDBN} prints memory addresses showing the location of stack
traces, structure values, pointer values, breakpoints, and so forth,
even when it also displays the contents of those addresses. The default
@code{print address off}, you should get the same text for backtraces on
all machines---whether or not they involve pointer arguments.
-@kindex show print address
+@kindex show print
@item show print address
Show whether or not addresses are to be printed.
@end table
it prints a symbolic address:
@table @code
-@kindex set print symbol-filename
@item set print symbol-filename on
+@cindex source file and line of a symbol
+@cindex symbol, source file and line
Tell @value{GDBN} to print the source file name and line number of a
symbol in the symbolic form of an address.
Do not print source file name and line number of a symbol. This is the
default.
-@kindex show print symbol-filename
@item show print symbol-filename
Show whether or not @value{GDBN} will print the source file name and
line number of a symbol in the symbolic form of an address.
printed is reasonably close to the closest earlier symbol:
@table @code
-@kindex set print max-symbolic-offset
@item set print max-symbolic-offset @var{max-offset}
+@cindex maximum value for offset of closest symbol
Tell @value{GDBN} to only display the symbolic form of an address if the
offset between the closest earlier symbol and the address is less than
@var{max-offset}. The default is 0, which tells @value{GDBN}
to always print the symbolic form of an address if any symbol precedes it.
-@kindex show print max-symbolic-offset
@item show print max-symbolic-offset
Ask how large the maximum offset is that @value{GDBN} prints in a
symbolic address.
Other settings control how different kinds of objects are printed:
@table @code
-@kindex set print array
@item set print array
@itemx set print array on
+@cindex pretty print arrays
Pretty print arrays. This format is more convenient to read,
but uses more space. The default is off.
@item set print array off
Return to compressed format for arrays.
-@kindex show print array
@item show print array
Show whether compressed or pretty format is selected for displaying
arrays.
-@kindex set print elements
@item set print elements @var{number-of-elements}
+@cindex number of array elements to print
+@cindex limit on number of printed array elements
Set a limit on how many elements of an array @value{GDBN} will print.
If @value{GDBN} is printing a large array, it stops printing after it has
printed the number of elements set by the @code{set print elements} command.
When @value{GDBN} starts, this limit is set to 200.
Setting @var{number-of-elements} to zero means that the printing is unlimited.
-@kindex show print elements
@item show print elements
Display the number of elements of a large array that @value{GDBN} will print.
If the number is 0, then the printing is unlimited.
-@kindex set print null-stop
+@item set print repeats
+@cindex repeated array elements
+Set the threshold for suppressing display of repeated array
+elelments. When the number of consecutive identical elements of an
+array exceeds the threshold, @value{GDBN} prints the string
+@code{"<repeats @var{n} times>"}, where @var{n} is the number of
+identical repetitions, instead of displaying the identical elements
+themselves. Setting the threshold to zero will cause all elements to
+be individually printed. The default threshold is 10.
+
+@item show print repeats
+Display the current threshold for printing repeated identical
+elements.
+
@item set print null-stop
+@cindex @sc{null} elements in arrays
Cause @value{GDBN} to stop printing the characters of an array when the first
@sc{null} is encountered. This is useful when large arrays actually
contain only short strings.
The default is off.
-@kindex set print pretty
+@item show print null-stop
+Show whether @value{GDBN} stops printing an array on the first
+@sc{null} character.
+
@item set print pretty on
+@cindex print structures in indented form
+@cindex indentation in structure display
Cause @value{GDBN} to print structures in an indented format with one member
per line, like this:
@noindent
This is the default format.
-@kindex show print pretty
@item show print pretty
Show which format @value{GDBN} is using to print structures.
-@kindex set print sevenbit-strings
@item set print sevenbit-strings on
+@cindex eight-bit characters in strings
+@cindex octal escapes in strings
Print using only seven-bit characters; if this option is set,
@value{GDBN} displays any eight-bit characters (in strings or
character values) using the notation @code{\}@var{nnn}. This setting is
Print full eight-bit characters. This allows the use of more
international character sets, and is the default.
-@kindex show print sevenbit-strings
@item show print sevenbit-strings
Show whether or not @value{GDBN} is printing only seven-bit characters.
-@kindex set print union
@item set print union on
-Tell @value{GDBN} to print unions which are contained in structures. This
-is the default setting.
+@cindex unions in structures, printing
+Tell @value{GDBN} to print unions which are contained in structures
+and other unions. This is the default setting.
@item set print union off
-Tell @value{GDBN} not to print unions which are contained in structures.
+Tell @value{GDBN} not to print unions which are contained in
+structures and other unions. @value{GDBN} will print @code{"@{...@}"}
+instead.
-@kindex show print union
@item show print union
Ask @value{GDBN} whether or not it will print unions which are contained in
-structures.
+structures and other unions.
For example, given the declarations
@smallexample
$1 = @{it = Tree, form = @{...@}@}
@end smallexample
+
+@noindent
+@code{set print union} affects programs written in C-like languages
+and in Pascal.
@end table
@need 1000
These settings are of interest when debugging C@t{++} programs:
@table @code
-@cindex demangling
-@kindex set print demangle
+@cindex demangling C@t{++} names
@item set print demangle
@itemx set print demangle on
Print C@t{++} names in their source form rather than in the encoded
(``mangled'') form passed to the assembler and linker for type-safe
linkage. The default is on.
-@kindex show print demangle
@item show print demangle
Show whether C@t{++} names are printed in mangled or demangled form.
-@kindex set print asm-demangle
@item set print asm-demangle
@itemx set print asm-demangle on
Print C@t{++} names in their source form rather than their mangled form, even
in assembler code printouts such as instruction disassemblies.
The default is off.
-@kindex show print asm-demangle
@item show print asm-demangle
Show whether C@t{++} names in assembly listings are printed in mangled
or demangled form.
-@kindex set demangle-style
@cindex C@t{++} symbol decoding style
@cindex symbol decoding style, C@t{++}
+@kindex set demangle-style
@item set demangle-style @var{style}
Choose among several encoding schemes used by different compilers to
represent C@t{++} names. The choices for @var{style} are currently:
@end table
If you omit @var{style}, you will see a list of possible formats.
-@kindex show demangle-style
@item show demangle-style
Display the encoding style currently in use for decoding C@t{++} symbols.
-@kindex set print object
@item set print object
@itemx set print object on
+@cindex derived type of an object, printing
+@cindex display derived types
When displaying a pointer to an object, identify the @emph{actual}
(derived) type of the object rather than the @emph{declared} type, using
the virtual function table.
Display only the declared type of objects, without reference to the
virtual function table. This is the default setting.
-@kindex show print object
@item show print object
Show whether actual, or declared, object types are displayed.
-@kindex set print static-members
@item set print static-members
@itemx set print static-members on
+@cindex static members of C@t{++} objects
Print static members when displaying a C@t{++} object. The default is on.
@item set print static-members off
Do not print static members when displaying a C@t{++} object.
-@kindex show print static-members
@item show print static-members
-Show whether C@t{++} static members are printed, or not.
+Show whether C@t{++} static members are printed or not.
+
+@item set print pascal_static-members
+@itemx set print pascal_static-members on
+@cindex static members of Pacal objects
+@cindex Pacal objects, static members display
+Print static members when displaying a Pascal object. The default is on.
+
+@item set print pascal_static-members off
+Do not print static members when displaying a Pascal object.
+
+@item show print pascal_static-members
+Show whether Pascal static members are printed or not.
@c These don't work with HP ANSI C++ yet.
-@kindex set print vtbl
@item set print vtbl
@itemx set print vtbl on
+@cindex pretty print C@t{++} virtual function tables
+@cindex virtual functions (C@t{++}) display
+@cindex VTBL display
Pretty print C@t{++} virtual function tables. The default is off.
(The @code{vtbl} commands do not work on programs compiled with the HP
ANSI C@t{++} compiler (@code{aCC}).)
@item set print vtbl off
Do not pretty print C@t{++} virtual function tables.
-@kindex show print vtbl
@item show print vtbl
Show whether C@t{++} virtual function tables are pretty printed, or not.
@end table
@section Value history
@cindex value history
+@cindex history of values printed by @value{GDBN}
Values printed by the @code{print} command are saved in the @value{GDBN}
@dfn{value history}. This allows you to refer to them in other expressions.
Values are kept until the symbol table is re-read or discarded
@section Convenience variables
@cindex convenience variables
+@cindex user-defined variables
@value{GDBN} provides @dfn{convenience variables} that you can use within
@value{GDBN} to hold on to a value and refer to it later. These variables
exist entirely within @value{GDBN}; they are not part of your program, and
@table @code
@kindex show convenience
+@cindex show all user variables
@item show convenience
Print a list of convenience variables used so far, and their values.
Abbreviated @code{show conv}.
layout vary depending on the hardware.
@end table
+@node OS Information
+@section Operating system auxiliary information
+@cindex OS information
+
+@value{GDBN} provides interfaces to useful OS facilities that can help
+you debug your program.
+
+@cindex @code{ptrace} system call
+@cindex @code{struct user} contents
+When @value{GDBN} runs on a @dfn{Posix system} (such as GNU or Unix
+machines), it interfaces with the inferior via the @code{ptrace}
+system call. The operating system creates a special sata structure,
+called @code{struct user}, for this interface. You can use the
+command @code{info udot} to display the contents of this data
+structure.
+
+@table @code
+@item info udot
+@kindex info udot
+Display the contents of the @code{struct user} maintained by the OS
+kernel for the program being debugged. @value{GDBN} displays the
+contents of @code{struct user} as a list of hex numbers, similar to
+the @code{examine} command.
+@end table
+
+@cindex auxiliary vector
+@cindex vector, auxiliary
+Some operating systems supply an @dfn{auxiliary vector} to programs at
+startup. This is akin to the arguments and environment that you
+specify for a program, but contains a system-dependent variety of
+binary values that tell system libraries important details about the
+hardware, operating system, and process. Each value's purpose is
+identified by an integer tag; the meanings are well-known but system-specific.
+Depending on the configuration and operating system facilities,
+@value{GDBN} may be able to show you this information. For remote
+targets, this functionality may further depend on the remote stub's
+support of the @samp{qPart:auxv:read} packet, see @ref{Remote
+configuration, auxiliary vector}.
+
+@table @code
+@kindex info auxv
+@item info auxv
+Display the auxiliary vector of the inferior, which can be either a
+live process or a core dump file. @value{GDBN} prints each tag value
+numerically, and also shows names and text descriptions for recognized
+tags. Some values in the vector are numbers, some bit masks, and some
+pointers to strings or other data. @value{GDBN} displays each value in the
+most appropriate form for a recognized tag, and in hexadecimal for
+an unrecognized tag.
+@end table
+
+
@node Memory Region Attributes
-@section Memory region attributes
+@section Memory region attributes
@cindex memory region attributes
-@dfn{Memory region attributes} allow you to describe special handling
-required by regions of your target's memory. @value{GDBN} uses attributes
+@dfn{Memory region attributes} allow you to describe special handling
+required by regions of your target's memory. @value{GDBN} uses attributes
to determine whether to allow certain types of memory accesses; whether to
use specific width accesses; and whether to cache target memory.
been defined, @value{GDBN} uses the default attributes when accessing
all memory.
-When a memory region is defined, it is given a number to identify it;
+When a memory region is defined, it is given a number to identify it;
to enable, disable, or remove a memory region, you specify that number.
@table @code
@kindex mem
@item mem @var{lower} @var{upper} @var{attributes}@dots{}
-Define memory region bounded by @var{lower} and @var{upper} with
-attributes @var{attributes}@dots{}. Note that @var{upper} == 0 is a
-special case: it is treated as the the target's maximum memory address.
+Define a memory region bounded by @var{lower} and @var{upper} with
+attributes @var{attributes}@dots{}, and add it to the list of regions
+monitored by @value{GDBN}. Note that @var{upper} == 0 is a special
+case: it is treated as the the target's maximum memory address.
(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.)
@kindex delete mem
@item delete mem @var{nums}@dots{}
-Remove memory regions @var{nums}@dots{}.
+Remove memory regions @var{nums}@dots{} from the list of regions
+monitored by @value{GDBN}.
@kindex disable mem
@item disable mem @var{nums}@dots{}
-Disable memory regions @var{nums}@dots{}.
-A disabled memory region is not forgotten.
+Disable monitoring of memory regions @var{nums}@dots{}.
+A disabled memory region is not forgotten.
It may be enabled again later.
@kindex enable mem
@item enable mem @var{nums}@dots{}
-Enable memory regions @var{nums}@dots{}.
+Enable monitoring of memory regions @var{nums}@dots{}.
@kindex info mem
@item info mem
Print a table of all defined memory regions, with the following columns
-for each region.
+for each region:
@table @emph
@item Memory Region Number
@item Enabled or Disabled.
-Enabled memory regions are marked with @samp{y}.
+Enabled memory regions are marked with @samp{y}.
Disabled memory regions are marked with @samp{n}.
@item Lo Address
@subsection Attributes
-@subsubsection Memory Access Mode
+@subsubsection Memory Access Mode
The access mode attributes set whether @value{GDBN} may make read or
write accesses to a memory region.
@c
@c @table @code
@c @item hwbreak
-@c Always use hardware breakpoints
+@c Always use hardware breakpoints
@c @item swbreak (default)
@c @end table
@table @code
@item cache
-Enable @value{GDBN} to cache target memory.
+Enable @value{GDBN} to cache target memory.
@item nocache
Disable @value{GDBN} from caching target memory. This is the default.
@end table
@c @subsubsection Memory Write Verification
-@c The memory write verification attributes set whether @value{GDBN}
+@c The memory write verification attributes set whether @value{GDBN}
@c will re-reads data after each write to verify the write was successful.
@c
@c @table @code
@cindex append data to a file
@cindex dump data to a file
@cindex restore data from a file
-@kindex dump
-@kindex append
-@kindex restore
-The commands @code{dump}, @code{append}, and @code{restore} are used
-for copying data between target memory and a file. Data is written
-into a file using @code{dump} or @code{append}, and restored from a
-file into memory by using @code{restore}. Files may be binary, srec,
-intel hex, or tekhex (but only binary files can be appended).
+You can use the commands @code{dump}, @code{append}, and
+@code{restore} to copy data between target memory and a file. The
+@code{dump} and @code{append} commands write data to a file, and the
+@code{restore} command reads data from a file back into the inferior's
+memory. Files may be in binary, Motorola S-record, Intel hex, or
+Tektronix Hex format; however, @value{GDBN} can only append to binary
+files.
@table @code
-@kindex dump binary
-@kindex append binary
-@item dump binary memory @var{filename} @var{start_addr} @var{end_addr}
-Dump contents of memory from @var{start_addr} to @var{end_addr} into
-raw binary format file @var{filename}.
-
-@item append binary memory @var{filename} @var{start_addr} @var{end_addr}
-Append contents of memory from @var{start_addr} to @var{end_addr} to
-raw binary format file @var{filename}.
-@item dump binary value @var{filename} @var{expression}
-Dump value of @var{expression} into raw binary format file @var{filename}.
-
-@item append binary memory @var{filename} @var{expression}
-Append value of @var{expression} to raw binary format file @var{filename}.
-
-@kindex dump ihex
-@item dump ihex memory @var{filename} @var{start_addr} @var{end_addr}
-Dump contents of memory from @var{start_addr} to @var{end_addr} into
-intel hex format file @var{filename}.
-
-@item dump ihex value @var{filename} @var{expression}
-Dump value of @var{expression} into intel hex format file @var{filename}.
-
-@kindex dump srec
-@item dump srec memory @var{filename} @var{start_addr} @var{end_addr}
-Dump contents of memory from @var{start_addr} to @var{end_addr} into
-srec format file @var{filename}.
+@kindex dump
+@item dump @r{[}@var{format}@r{]} memory @var{filename} @var{start_addr} @var{end_addr}
+@itemx dump @r{[}@var{format}@r{]} value @var{filename} @var{expr}
+Dump the contents of memory from @var{start_addr} to @var{end_addr},
+or the value of @var{expr}, to @var{filename} in the given format.
-@item dump srec value @var{filename} @var{expression}
-Dump value of @var{expression} into srec format file @var{filename}.
+The @var{format} parameter may be any one of:
+@table @code
+@item binary
+Raw binary form.
+@item ihex
+Intel hex format.
+@item srec
+Motorola S-record format.
+@item tekhex
+Tektronix Hex format.
+@end table
-@kindex dump tekhex
-@item dump tekhex memory @var{filename} @var{start_addr} @var{end_addr}
-Dump contents of memory from @var{start_addr} to @var{end_addr} into
-tekhex format file @var{filename}.
+@value{GDBN} uses the same definitions of these formats as the
+@sc{gnu} binary utilities, like @samp{objdump} and @samp{objcopy}. If
+@var{format} is omitted, @value{GDBN} dumps the data in raw binary
+form.
-@item dump tekhex value @var{filename} @var{expression}
-Dump value of @var{expression} into tekhex format file @var{filename}.
+@kindex append
+@item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr}
+@itemx append @r{[}binary@r{]} value @var{filename} @var{expr}
+Append the contents of memory from @var{start_addr} to @var{end_addr},
+or the value of @var{expr}, to the file @var{filename}, in raw binary form.
+(@value{GDBN} can only append data to files in raw binary form.)
-@item restore @var{filename} [@var{binary}] @var{bias} @var{start} @var{end}
-Restore the contents of file @var{filename} into memory. The @code{restore}
-command can automatically recognize any known bfd file format, except for
-raw binary. To restore a raw binary file you must use the optional argument
-@var{binary} after the filename.
+@kindex restore
+@item restore @var{filename} @r{[}binary@r{]} @var{bias} @var{start} @var{end}
+Restore the contents of file @var{filename} into memory. The
+@code{restore} command can automatically recognize any known @sc{bfd}
+file format, except for raw binary. To restore a raw binary file you
+must specify the optional keyword @code{binary} after the filename.
-If @var{bias} is non-zero, its value will be added to the addresses
+If @var{bias} is non-zero, its value will be added to the addresses
contained in the file. Binary files always start at address zero, so
they will be restored at address @var{bias}. Other bfd files have
a built-in location; they will be restored at offset @var{bias}
If @var{start} and/or @var{end} are non-zero, then only data between
file offset @var{start} and file offset @var{end} will be restored.
-These offsets are relative to the addresses in the file, before
+These offsets are relative to the addresses in the file, before
the @var{bias} argument is applied.
@end table
+@node Core File Generation
+@section How to Produce a Core File from Your Program
+@cindex dump core from inferior
+
+A @dfn{core file} or @dfn{core dump} is a file that records the memory
+image of a running process and its process status (register values
+etc.). Its primary use is post-mortem debugging of a program that
+crashed while it ran outside a debugger. A program that crashes
+automatically produces a core file, unless this feature is disabled by
+the user. @xref{Files}, for information on invoking @value{GDBN} in
+the post-mortem debugging mode.
+
+Occasionally, you may wish to produce a core file of the program you
+are debugging in order to preserve a snapshot of its state.
+@value{GDBN} has a special command for that.
+
+@table @code
+@kindex gcore
+@kindex generate-core-file
+@item generate-core-file [@var{file}]
+@itemx gcore [@var{file}]
+Produce a core dump of the inferior process. The optional argument
+@var{file} specifies the file name where to put the core dump. If not
+specified, the file name defaults to @file{core.@var{pid}}, where
+@var{pid} is the inferior process ID.
+
+Note that this command is implemented only for some systems (as of
+this writing, @sc{gnu}/Linux, FreeBSD, Solaris, Unixware, and S390).
+@end table
+
@node Character Sets
@section Character Sets
@cindex character sets
@item show charset
@kindex show charset
-Show the names of the current host and target charsets.
+Show the names of the current host and target charsets.
@itemx show host-charset
@kindex show host-charset
-Show the name of the current host charset.
+Show the name of the current host charset.
@itemx show target-charset
@kindex show target-charset
-Show the name of the current target charset.
+Show the name of the current target charset.
@end table
GNU gdb 2001-12-19-cvs
Copyright 2001 Free Software Foundation, Inc.
@dots{}
-(gdb)
+(@value{GDBP})
@end smallexample
We can use the @code{show charset} command to see what character sets
strings:
@smallexample
-(gdb) show charset
+(@value{GDBP}) show charset
The current host and target character set is `ISO-8859-1'.
-(gdb)
+(@value{GDBP})
@end smallexample
For the sake of printing this manual, let's use @sc{ascii} as our
initial character set:
@smallexample
-(gdb) set charset ASCII
-(gdb) show charset
+(@value{GDBP}) set charset ASCII
+(@value{GDBP}) show charset
The current host and target character set is `ASCII'.
-(gdb)
+(@value{GDBP})
@end smallexample
Let's assume that @sc{ascii} is indeed the correct character set for our
@sc{ascii}, the contents of @code{ascii_hello} print legibly:
@smallexample
-(gdb) print ascii_hello
+(@value{GDBP}) print ascii_hello
$1 = 0x401698 "Hello, world!\n"
-(gdb) print ascii_hello[0]
+(@value{GDBP}) print ascii_hello[0]
$2 = 72 'H'
-(gdb)
+(@value{GDBP})
@end smallexample
@value{GDBN} uses the target character set for character and string
literals you use in expressions:
@smallexample
-(gdb) print '+'
+(@value{GDBP}) print '+'
$3 = 43 '+'
-(gdb)
+(@value{GDBP})
@end smallexample
The @sc{ascii} character set uses the number 43 to encode the @samp{+}
character set is still @sc{ascii}, we get jibberish:
@smallexample
-(gdb) print ibm1047_hello
+(@value{GDBP}) print ibm1047_hello
$4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%"
-(gdb) print ibm1047_hello[0]
+(@value{GDBP}) print ibm1047_hello[0]
$5 = 200 '\310'
-(gdb)
+(@value{GDBP})
@end smallexample
If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB},
@value{GDBN} tells us the character sets it supports:
@smallexample
-(gdb) set target-charset
-ASCII EBCDIC-US IBM1047 ISO-8859-1
-(gdb) set target-charset
+(@value{GDBP}) set target-charset
+ASCII EBCDIC-US IBM1047 ISO-8859-1
+(@value{GDBP}) set target-charset
@end smallexample
We can select @sc{ibm1047} as our target character set, and examine the
@sc{ascii}, and they display correctly:
@smallexample
-(gdb) set target-charset IBM1047
-(gdb) show charset
+(@value{GDBP}) set target-charset IBM1047
+(@value{GDBP}) show charset
The current host character set is `ASCII'.
The current target character set is `IBM1047'.
-(gdb) print ascii_hello
+(@value{GDBP}) print ascii_hello
$6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012"
-(gdb) print ascii_hello[0]
+(@value{GDBP}) print ascii_hello[0]
$7 = 72 '\110'
-(gdb) print ibm1047_hello
+(@value{GDBP}) print ibm1047_hello
$8 = 0x4016a8 "Hello, world!\n"
-(gdb) print ibm1047_hello[0]
+(@value{GDBP}) print ibm1047_hello[0]
$9 = 200 'H'
-(gdb)
+(@value{GDBP})
@end smallexample
As above, @value{GDBN} uses the target character set for character and
string literals you use in expressions:
@smallexample
-(gdb) print '+'
+(@value{GDBP}) print '+'
$10 = 78 '+'
-(gdb)
+(@value{GDBP})
@end smallexample
The @sc{ibm1047} character set uses the number 78 to encode the @samp{+}
character.
+@node Caching Remote Data
+@section Caching Data of Remote Targets
+@cindex caching data of remote targets
+
+@value{GDBN} can cache data exchanged between the debugger and a
+remote target (@pxref{Remote}). Such caching generally improves
+performance, because it reduces the overhead of the remote protocol by
+bundling memory reads and writes into large chunks. Unfortunately,
+@value{GDBN} does not currently know anything about volatile
+registers, and thus data caching will produce incorrect results when
+volatile registers are in use.
+
+@table @code
+@kindex set remotecache
+@item set remotecache on
+@itemx set remotecache off
+Set caching state for remote targets. When @code{ON}, use data
+caching. By default, this option is @code{OFF}.
+
+@kindex show remotecache
+@item show remotecache
+Show the current state of data caching for remote targets.
+
+@kindex info dcache
+@item info dcache
+Print the information about the data cache performance. The
+information displayed includes: the dcache width and depth; and for
+each cache line, how many times it was referenced, and its data and
+state (dirty, bad, ok, etc.). This command is useful for debugging
+the data cache operation.
+@end table
+
@node Macros
@chapter C Preprocessor Macros
-Some languages, such as C and C++, provide a way to define and invoke
+Some languages, such as C and C@t{++}, provide a way to define and invoke
``preprocessor macros'' which expand into strings of tokens.
@value{GDBN} can evaluate expressions containing macro invocations, show
the result of macro expansion, and show a macro's definition, including
not parse the result, @var{expression} need not be a valid expression;
it can be any string of tokens.
-@kindex macro expand-once
+@kindex macro exp1
@item macro expand-once @var{expression}
@itemx macro exp1 @var{expression}
+@cindex expand macro once
@i{(This command is not yet implemented.)} Show the results of
expanding those preprocessor macro invocations that appear explicitly in
@var{expression}. Macro invocations appearing in that expansion are
above; it cannot remove definitions present in the program being
debugged.
+@kindex macro list
+@item macro list
+@i{(This command is not yet implemented.)} List all the macros
+defined using the @code{macro define} command.
@end table
@cindex macros, example of debugging with
GNU gdb 2002-05-06-cvs
Copyright 2002 Free Software Foundation, Inc.
GDB is free software, @dots{}
-(gdb)
+(@value{GDBP})
@end smallexample
We can expand macros and examine their definitions, even when the
to decide which macro definitions are in scope:
@smallexample
-(gdb) list main
+(@value{GDBP}) list main
3
4 #define M 42
5 #define ADD(x) (M + x)
10 printf ("Hello, world!\n");
11 #undef N
12 printf ("We're so creative.\n");
-(gdb) info macro ADD
+(@value{GDBP}) info macro ADD
Defined at /home/jimb/gdb/macros/play/sample.c:5
#define ADD(x) (M + x)
-(gdb) info macro Q
+(@value{GDBP}) info macro Q
Defined at /home/jimb/gdb/macros/play/sample.h:1
included at /home/jimb/gdb/macros/play/sample.c:2
#define Q <
-(gdb) macro expand ADD(1)
+(@value{GDBP}) macro expand ADD(1)
expands to: (42 + 1)
-(gdb) macro expand-once ADD(1)
+(@value{GDBP}) macro expand-once ADD(1)
expands to: once (M + 1)
-(gdb)
+(@value{GDBP})
@end smallexample
In the example above, note that @command{macro expand-once} expands only
the source line of the current stack frame:
@smallexample
-(gdb) break main
+(@value{GDBP}) break main
Breakpoint 1 at 0x8048370: file sample.c, line 10.
-(gdb) run
-Starting program: /home/jimb/gdb/macros/play/sample
+(@value{GDBP}) run
+Starting program: /home/jimb/gdb/macros/play/sample
Breakpoint 1, main () at sample.c:10
10 printf ("Hello, world!\n");
-(gdb)
+(@value{GDBP})
@end smallexample
At line 10, the definition of the macro @code{N} at line 9 is in force:
@smallexample
-(gdb) info macro N
+(@value{GDBP}) info macro N
Defined at /home/jimb/gdb/macros/play/sample.c:9
#define N 28
-(gdb) macro expand N Q M
+(@value{GDBP}) macro expand N Q M
expands to: 28 < 42
-(gdb) print N Q M
+(@value{GDBP}) print N Q M
$1 = 1
-(gdb)
+(@value{GDBP})
@end smallexample
As we step over directives that remove @code{N}'s definition, and then
thereof) in force at each point:
@smallexample
-(gdb) next
+(@value{GDBP}) next
Hello, world!
12 printf ("We're so creative.\n");
-(gdb) info macro N
+(@value{GDBP}) info macro N
The symbol `N' has no definition as a C/C++ preprocessor macro
at /home/jimb/gdb/macros/play/sample.c:12
-(gdb) next
+(@value{GDBP}) next
We're so creative.
14 printf ("Goodbye, world!\n");
-(gdb) info macro N
+(@value{GDBP}) info macro N
Defined at /home/jimb/gdb/macros/play/sample.c:13
#define N 1729
-(gdb) macro expand N Q M
+(@value{GDBP}) macro expand N Q M
expands to: 1729 < 42
-(gdb) print N Q M
+(@value{GDBP}) print N Q M
$2 = 0
-(gdb)
+(@value{GDBP})
@end smallexample
This chapter describes the tracepoint commands and features.
@menu
-* Set Tracepoints::
-* Analyze Collected Data::
-* Tracepoint Variables::
+* Set Tracepoints::
+* Analyze Collected Data::
+* Tracepoint Variables::
@end menu
@node Set Tracepoints
conditions and actions.
@menu
-* Create and Delete Tracepoints::
-* Enable and Disable Tracepoints::
-* Tracepoint Passcounts::
-* Tracepoint Actions::
-* Listing Tracepoints::
-* Starting and Stopping Trace Experiment::
+* Create and Delete Tracepoints::
+* Enable and Disable Tracepoints::
+* Tracepoint Passcounts::
+* Tracepoint Actions::
+* Listing Tracepoints::
+* Starting and Stopping Trace Experiment::
@end menu
@node Create and Delete Tracepoints
Examples:
@smallexample
-(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of
+(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of
@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2}
(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the
@table @code
@kindex info tracepoints
+@kindex info tp
@cindex information about tracepoints
@item info tracepoints @r{[}@var{num}@r{]}
Display information about the tracepoint @var{num}. If you don't specify
This command takes no arguments. It ends the trace experiment, and
stops collecting data.
-@strong{Note:} a trace experiment and data collection may stop
+@strong{Note}: a trace experiment and data collection may stop
automatically if any tracepoint's passcount is reached
(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full.
@table @code
@item overlay off
-@kindex overlay off
+@kindex overlay
Disable @value{GDBN}'s overlay support. When overlay support is
disabled, @value{GDBN} assumes that all functions and variables are
always present at their mapped addresses. By default, @value{GDBN}'s
overlay support is disabled.
@item overlay manual
-@kindex overlay manual
@cindex manual overlay debugging
Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN}
relies on you to tell it which overlays are mapped, and which are not,
@item overlay map-overlay @var{overlay}
@itemx overlay map @var{overlay}
-@kindex overlay map-overlay
@cindex map an overlay
Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must
be the name of the object file section containing the overlay. When an
@item overlay unmap-overlay @var{overlay}
@itemx overlay unmap @var{overlay}
-@kindex overlay unmap-overlay
@cindex unmap an overlay
Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay}
must be the name of the object file section containing the overlay.
overlay's functions and variables at their load addresses.
@item overlay auto
-@kindex overlay auto
Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN}
consults a data structure the overlay manager maintains in the inferior
to see which overlays are mapped. For details, see @ref{Automatic
@item overlay load-target
@itemx overlay load
-@kindex overlay load-target
@cindex reloading the overlay table
Re-read the overlay table from the inferior. Normally, @value{GDBN}
re-reads the table @value{GDBN} automatically each time the inferior
of the function the address falls in:
@smallexample
-(gdb) print main
+(@value{GDBP}) print main
$3 = @{int ()@} 0x11a0 <main>
@end smallexample
@noindent
unmapped overlay, @value{GDBN} prints it this way:
@smallexample
-(gdb) overlay list
+(@value{GDBP}) overlay list
No sections are mapped.
-(gdb) print foo
+(@value{GDBP}) print foo
$5 = @{int (int)@} 0x100000 <*foo*>
@end smallexample
@noindent
name normally:
@smallexample
-(gdb) overlay list
-Section .ov.foo.text, loaded at 0x100000 - 0x100034,
+(@value{GDBP}) overlay list
+Section .ov.foo.text, loaded at 0x100000 - 0x100034,
mapped at 0x1016 - 0x104a
-(gdb) print foo
+(@value{GDBP}) print foo
$6 = @{int (int)@} 0x1016 <foo>
@end smallexample
calls this function whenever it has changed the overlay table, this
will enable @value{GDBN} to accurately keep track of which overlays
are in program memory, and update any breakpoints that may be set
-in overlays. This will allow breakpoints to work even if the
+in overlays. This will allow breakpoints to work even if the
overlays are kept in ROM or other non-writable memory while they
are not being executed.
* Setting:: Switching between source languages
* Show:: Displaying the language
* Checks:: Type and range checks
-* Support:: Supported languages
+* Supported languages:: Supported languages
+* Unsupported languages:: Unsupported languages
@end menu
@node Setting
@value{GDBN} infers that its language is the one indicated.
@table @file
+@item .ada
+@itemx .ads
+@itemx .adb
+@itemx .a
+Ada source file.
@item .c
C source file
@itemx .c++
C@t{++} source file
+@item .m
+Objective-C source file
+
@item .f
@itemx .F
Fortran source file
The following commands help you find out which language is the
working language, and also what language source files were written in.
-@kindex show language
-@kindex info frame@r{, show the source language}
-@kindex info source@r{, show the source language}
@table @code
@item show language
+@kindex show language
Display the current working language. This is the
language you can use with commands such as @code{print} to
build and compute expressions that may involve variables in your program.
@item info frame
+@kindex info frame@r{, show the source language}
Display the source language for this frame. This language becomes the
working language if you use an identifier from this frame.
@xref{Frame Info, ,Information about a frame}, to identify the other
information listed here.
@item info source
+@kindex info source@r{, show the source language}
Display the source language of this source file.
@xref{Symbols, ,Examining the Symbol Table}, to identify the other
information listed here.
not in the standard list. You can then set the extension associated
with a language explicitly:
-@kindex set extension-language
-@kindex info extensions
@table @code
-@item set extension-language @var{.ext} @var{language}
-Set source files with extension @var{.ext} to be assumed to be in
-the source language @var{language}.
+@item set extension-language @var{ext} @var{language}
+@kindex set extension-language
+Tell @value{GDBN} that source files with extension @var{ext} are to be
+assumed as written in the source language @var{language}.
@item info extensions
+@kindex info extensions
List all the filename extensions and the associated languages.
@end table
errors when your program is running.
@value{GDBN} can check for conditions like the above if you wish.
-Although @value{GDBN} does not check the statements in your program, it
-can check expressions entered directly into @value{GDBN} for evaluation via
-the @code{print} command, for example. As with the working language,
-@value{GDBN} can also decide whether or not to check automatically based on
-your program's source language. @xref{Support, ,Supported languages},
-for the default settings of supported languages.
+Although @value{GDBN} does not check the statements in your program,
+it can check expressions entered directly into @value{GDBN} for
+evaluation via the @code{print} command, for example. As with the
+working language, @value{GDBN} can also decide whether or not to check
+automatically based on your program's source language.
+@xref{Supported languages, ,Supported languages}, for the default
+settings of supported languages.
@menu
* Type Checking:: An overview of type checking
instance, both Modula-2 and C require the arguments to arithmetical
operators to be numbers. In C, enumerated types and pointers can be
represented as numbers, so that they are valid arguments to mathematical
-operators. @xref{Support, ,Supported languages}, for further
+operators. @xref{Supported languages, ,Supported languages}, for further
details on specific languages.
@value{GDBN} provides some additional commands for controlling the type checker:
-@kindex set check@r{, type}
@kindex set check type
@kindex show check type
@table @code
@item set check type auto
Set type checking on or off based on the current working language.
-@xref{Support, ,Supported languages}, for the default settings for
+@xref{Supported languages, ,Supported languages}, for the default settings for
each language.
@item set check type on
@end smallexample
This, too, is specific to individual languages, and in some cases
-specific to individual compilers or machines. @xref{Support, ,
+specific to individual compilers or machines. @xref{Supported languages, ,
Supported languages}, for further details on specific languages.
@value{GDBN} provides some additional commands for controlling the range checker:
-@kindex set check@r{, range}
@kindex set check range
@kindex show check range
@table @code
@item set check range auto
Set range checking on or off based on the current working language.
-@xref{Support, ,Supported languages}, for the default settings for
+@xref{Supported languages, ,Supported languages}, for the default settings for
each language.
@item set check range on
being set automatically by @value{GDBN}.
@end table
-@node Support
+@node Supported languages
@section Supported languages
-@value{GDBN} supports C, C@t{++}, Fortran, Java, assembly, and Modula-2.
+@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, Pascal,
+assembly, Modula-2, and Ada.
@c This is false ...
Some @value{GDBN} features may be used in expressions regardless of the
language you use: the @value{GDBN} @code{@@} and @code{::} operators,
language reference or tutorial.
@menu
-* C:: C and C@t{++}
-* Modula-2:: Modula-2
+* C:: C and C@t{++}
+* Objective-C:: Objective-C
+* Fortran:: Fortran
+* Pascal:: Pascal
+* Modula-2:: Modula-2
+* Ada:: Ada
@end menu
@node C
searches for a function whose signature @emph{exactly} matches the
argument types.
+@kindex show overload-resolution
+@item show overload-resolution
+Show the current setting of overload resolution.
+
@item @r{Overloaded symbol names}
You can specify a particular definition of an overloaded symbol, using
the same notation that is used to declare such symbols in C@t{++}: type
@xref{Completion,, Command completion}, for details on how to do this.
@end table
+@node Objective-C
+@subsection Objective-C
+
+@cindex Objective-C
+This section provides information about some commands and command
+options that are useful for debugging Objective-C code. See also
+@ref{Symbols, info classes}, and @ref{Symbols, info selectors}, for a
+few more commands specific to Objective-C support.
+
+@menu
+* Method Names in Commands::
+* The Print Command with Objective-C::
+@end menu
+
+@node Method Names in Commands, The Print Command with Objective-C, Objective-C, Objective-C
+@subsubsection Method Names in Commands
+
+The following commands have been extended to accept Objective-C method
+names as line specifications:
+
+@kindex clear@r{, and Objective-C}
+@kindex break@r{, and Objective-C}
+@kindex info line@r{, and Objective-C}
+@kindex jump@r{, and Objective-C}
+@kindex list@r{, and Objective-C}
+@itemize
+@item @code{clear}
+@item @code{break}
+@item @code{info line}
+@item @code{jump}
+@item @code{list}
+@end itemize
+
+A fully qualified Objective-C method name is specified as
+
+@smallexample
+-[@var{Class} @var{methodName}]
+@end smallexample
+
+where the minus sign is used to indicate an instance method and a
+plus sign (not shown) is used to indicate a class method. The class
+name @var{Class} and method name @var{methodName} are enclosed in
+brackets, similar to the way messages are specified in Objective-C
+source code. For example, to set a breakpoint at the @code{create}
+instance method of class @code{Fruit} in the program currently being
+debugged, enter:
+
+@smallexample
+break -[Fruit create]
+@end smallexample
+
+To list ten program lines around the @code{initialize} class method,
+enter:
+
+@smallexample
+list +[NSText initialize]
+@end smallexample
+
+In the current version of @value{GDBN}, the plus or minus sign is
+required. In future versions of @value{GDBN}, the plus or minus
+sign will be optional, but you can use it to narrow the search. It
+is also possible to specify just a method name:
+
+@smallexample
+break create
+@end smallexample
+
+You must specify the complete method name, including any colons. If
+your program's source files contain more than one @code{create} method,
+you'll be presented with a numbered list of classes that implement that
+method. Indicate your choice by number, or type @samp{0} to exit if
+none apply.
+
+As another example, to clear a breakpoint established at the
+@code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter:
+
+@smallexample
+clear -[NSWindow makeKeyAndOrderFront:]
+@end smallexample
+
+@node The Print Command with Objective-C
+@subsubsection The Print Command With Objective-C
+@cindex Objective-C, print objects
+@kindex print-object
+@kindex po @r{(@code{print-object})}
+
+The print command has also been extended to accept methods. For example:
+
+@smallexample
+print -[@var{object} hash]
+@end smallexample
+
+@cindex print an Objective-C object description
+@cindex @code{_NSPrintForDebugger}, and printing Objective-C objects
+@noindent
+will tell @value{GDBN} to send the @code{hash} message to @var{object}
+and print the result. Also, an additional command has been added,
+@code{print-object} or @code{po} for short, which is meant to print
+the description of an object. However, this command may only work
+with certain Objective-C libraries that have a particular hook
+function, @code{_NSPrintForDebugger}, defined.
+
+@node Fortran
+@subsection Fortran
+@cindex Fortran-specific support in @value{GDBN}
+
+@table @code
+@cindex @code{COMMON} blocks, Fortran
+@kindex info common
+@item info common @r{[}@var{common-name}@r{]}
+This command prints the values contained in the Fortran @code{COMMON}
+block whose name is @var{common-name}. With no argument, the names of
+all @code{COMMON} blocks visible at current program location are
+printed.
+@end table
+
+Fortran symbols are usually case-insensitive, so @value{GDBN} by
+default uses case-insensitive matches for Fortran symbols. You can
+change that with the @samp{set case-insensitive} command, see
+@ref{Symbols}, for the details.
+
+@node Pascal
+@subsection Pascal
+
+@cindex Pascal support in @value{GDBN}, limitations
+Debugging Pascal programs which use sets, subranges, file variables, or
+nested functions does not currently work. @value{GDBN} does not support
+entering expressions, printing values, or similar features using Pascal
+syntax.
+
+The Pascal-specific command @code{set print pascal_static-members}
+controls whether static members of Pascal objects are displayed.
+@xref{Print Settings, pascal_static-members}.
+
@node Modula-2
@subsection Modula-2
In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is
interpreted as the beginning of a comment. Use @code{<>} instead.
-@node Symbols
-@chapter Examining the Symbol Table
+@node Ada
+@subsection Ada
+@cindex Ada
-The commands described in this chapter allow you to inquire about the
-symbols (names of variables, functions and types) defined in your
-program. This information is inherent in the text of your program and
-does not change as your program executes. @value{GDBN} finds it in your
-program's symbol table, in the file indicated when you started @value{GDBN}
-(@pxref{File Options, ,Choosing files}), or by one of the
-file-management commands (@pxref{Files, ,Commands to specify files}).
+The extensions made to @value{GDBN} for Ada only support
+output from the @sc{gnu} Ada (GNAT) compiler.
+Other Ada compilers are not currently supported, and
+attempting to debug executables produced by them is most likely
+to be difficult.
-@cindex symbol names
-@cindex names of symbols
-@cindex quoting names
-Occasionally, you may need to refer to symbols that contain unusual
-characters, which @value{GDBN} ordinarily treats as word delimiters. The
-most frequent case is in referring to static variables in other
-source files (@pxref{Variables,,Program variables}). File names
-are recorded in object files as debugging symbols, but @value{GDBN} would
-ordinarily parse a typical file name, like @file{foo.c}, as the three words
-@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize
-@samp{foo.c} as a single symbol, enclose it in single quotes; for example,
-@smallexample
-p 'foo.c'::x
-@end smallexample
+@cindex expressions in Ada
+@menu
+* Ada Mode Intro:: General remarks on the Ada syntax
+ and semantics supported by Ada mode
+ in @value{GDBN}.
+* Omissions from Ada:: Restrictions on the Ada expression syntax.
+* Additions to Ada:: Extensions of the Ada expression syntax.
+* Stopping Before Main Program:: Debugging the program during elaboration.
+* Ada Glitches:: Known peculiarities of Ada mode.
+@end menu
-@noindent
-looks up the value of @code{x} in the scope of the file @file{foo.c}.
+@node Ada Mode Intro
+@subsubsection Introduction
+@cindex Ada mode, general
-@table @code
-@kindex info address
-@cindex address of a symbol
-@item info address @var{symbol}
-Describe where the data for @var{symbol} is stored. For a register
-variable, this says which register it is kept in. For a non-register
-local variable, this prints the stack-frame offset at which the variable
-is always stored.
+The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression
+syntax, with some extensions.
+The philosophy behind the design of this subset is
-Note the contrast with @samp{print &@var{symbol}}, which does not work
-at all for a register variable, and for a stack local variable prints
-the exact address of the current instantiation of the variable.
+@itemize @bullet
+@item
+That @value{GDBN} should provide basic literals and access to operations for
+arithmetic, dereferencing, field selection, indexing, and subprogram calls,
+leaving more sophisticated computations to subprograms written into the
+program (which therefore may be called from @value{GDBN}).
-@kindex info symbol
-@cindex symbol from address
-@item info symbol @var{addr}
-Print the name of a symbol which is stored at the address @var{addr}.
+@item
+That type safety and strict adherence to Ada language restrictions
+are not particularly important to the @value{GDBN} user.
+
+@item
+That brevity is important to the @value{GDBN} user.
+@end itemize
+
+Thus, for brevity, the debugger acts as if there were
+implicit @code{with} and @code{use} clauses in effect for all user-written
+packages, making it unnecessary to fully qualify most names with
+their packages, regardless of context. Where this causes ambiguity,
+@value{GDBN} asks the user's intent.
+
+The debugger will start in Ada mode if it detects an Ada main program.
+As for other languages, it will enter Ada mode when stopped in a program that
+was translated from an Ada source file.
+
+While in Ada mode, you may use `@t{--}' for comments. This is useful
+mostly for documenting command files. The standard @value{GDBN} comment
+(@samp{#}) still works at the beginning of a line in Ada mode, but not in the
+middle (to allow based literals).
+
+The debugger supports limited overloading. Given a subprogram call in which
+the function symbol has multiple definitions, it will use the number of
+actual parameters and some information about their types to attempt to narrow
+the set of definitions. It also makes very limited use of context, preferring
+procedures to functions in the context of the @code{call} command, and
+functions to procedures elsewhere.
+
+@node Omissions from Ada
+@subsubsection Omissions from Ada
+@cindex Ada, omissions from
+
+Here are the notable omissions from the subset:
+
+@itemize @bullet
+@item
+Only a subset of the attributes are supported:
+
+@itemize @minus
+@item
+@t{'First}, @t{'Last}, and @t{'Length}
+ on array objects (not on types and subtypes).
+
+@item
+@t{'Min} and @t{'Max}.
+
+@item
+@t{'Pos} and @t{'Val}.
+
+@item
+@t{'Tag}.
+
+@item
+@t{'Range} on array objects (not subtypes), but only as the right
+operand of the membership (@code{in}) operator.
+
+@item
+@t{'Access}, @t{'Unchecked_Access}, and
+@t{'Unrestricted_Access} (a GNAT extension).
+
+@item
+@t{'Address}.
+@end itemize
+
+@item
+The names in
+@code{Characters.Latin_1} are not available and
+concatenation is not implemented. Thus, escape characters in strings are
+not currently available.
+
+@item
+Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise
+equality of representations. They will generally work correctly
+for strings and arrays whose elements have integer or enumeration types.
+They may not work correctly for arrays whose element
+types have user-defined equality, for arrays of real values
+(in particular, IEEE-conformant floating point, because of negative
+zeroes and NaNs), and for arrays whose elements contain unused bits with
+indeterminate values.
+
+@item
+The other component-by-component array operations (@code{and}, @code{or},
+@code{xor}, @code{not}, and relational tests other than equality)
+are not implemented.
+
+@item
+There are no record or array aggregates.
+
+@item
+Calls to dispatching subprograms are not implemented.
+
+@item
+The overloading algorithm is much more limited (i.e., less selective)
+than that of real Ada. It makes only limited use of the context in which a subexpression
+appears to resolve its meaning, and it is much looser in its rules for allowing
+type matches. As a result, some function calls will be ambiguous, and the user
+will be asked to choose the proper resolution.
+
+@item
+The @code{new} operator is not implemented.
+
+@item
+Entry calls are not implemented.
+
+@item
+Aside from printing, arithmetic operations on the native VAX floating-point
+formats are not supported.
+
+@item
+It is not possible to slice a packed array.
+@end itemize
+
+@node Additions to Ada
+@subsubsection Additions to Ada
+@cindex Ada, deviations from
+
+As it does for other languages, @value{GDBN} makes certain generic
+extensions to Ada (@pxref{Expressions}):
+
+@itemize @bullet
+@item
+If the expression @var{E} is a variable residing in memory
+(typically a local variable or array element) and @var{N} is
+a positive integer, then @code{@var{E}@@@var{N}} displays the values of
+@var{E} and the @var{N}-1 adjacent variables following it in memory as an array.
+In Ada, this operator is generally not necessary, since its prime use
+is in displaying parts of an array, and slicing will usually do this in Ada.
+However, there are occasional uses when debugging programs
+in which certain debugging information has been optimized away.
+
+@item
+@code{@var{B}::@var{var}} means ``the variable named @var{var} that appears
+in function or file @var{B}.'' When @var{B} is a file name, you must typically
+surround it in single quotes.
+
+@item
+The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type
+@var{type} that appears at address @var{addr}.''
+
+@item
+A name starting with @samp{$} is a convenience variable
+(@pxref{Convenience Vars}) or a machine register (@pxref{Registers}).
+@end itemize
+
+In addition, @value{GDBN} provides a few other shortcuts and outright additions specific
+to Ada:
+
+@itemize @bullet
+@item
+The assignment statement is allowed as an expression, returning
+its right-hand operand as its value. Thus, you may enter
+
+@smallexample
+set x := y + 3
+print A(tmp := y + 1)
+@end smallexample
+
+@item
+The semicolon is allowed as an ``operator,'' returning as its value
+the value of its right-hand operand.
+This allows, for example,
+complex conditional breaks:
+
+@smallexample
+break f
+condition 1 (report(i); k += 1; A(k) > 100)
+@end smallexample
+
+@item
+Rather than use catenation and symbolic character names to introduce special
+characters into strings, one may instead use a special bracket notation,
+which is also used to print strings. A sequence of characters of the form
+@samp{["@var{XX}"]} within a string or character literal denotes the
+(single) character whose numeric encoding is @var{XX} in hexadecimal. The
+sequence of characters @samp{["""]} also denotes a single quotation mark
+in strings. For example,
+@smallexample
+ "One line.["0a"]Next line.["0a"]"
+@end smallexample
+@noindent
+contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF}) after each
+period.
+
+@item
+The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and
+@t{'Max} is optional (and is ignored in any case). For example, it is valid
+to write
+
+@smallexample
+print 'max(x, y)
+@end smallexample
+
+@item
+When printing arrays, @value{GDBN} uses positional notation when the
+array has a lower bound of 1, and uses a modified named notation otherwise.
+For example, a one-dimensional array of three integers with a lower bound of 3 might print as
+
+@smallexample
+(3 => 10, 17, 1)
+@end smallexample
+
+@noindent
+That is, in contrast to valid Ada, only the first component has a @code{=>}
+clause.
+
+@item
+You may abbreviate attributes in expressions with any unique,
+multi-character subsequence of
+their names (an exact match gets preference).
+For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh}
+in place of @t{a'length}.
+
+@item
+@cindex quoting Ada internal identifiers
+Since Ada is case-insensitive, the debugger normally maps identifiers you type
+to lower case. The GNAT compiler uses upper-case characters for
+some of its internal identifiers, which are normally of no interest to users.
+For the rare occasions when you actually have to look at them,
+enclose them in angle brackets to avoid the lower-case mapping.
+For example,
+@smallexample
+@value{GDBP} print <JMPBUF_SAVE>[0]
+@end smallexample
+
+@item
+Printing an object of class-wide type or dereferencing an
+access-to-class-wide value will display all the components of the object's
+specific type (as indicated by its run-time tag). Likewise, component
+selection on such a value will operate on the specific type of the
+object.
+
+@end itemize
+
+@node Stopping Before Main Program
+@subsubsection Stopping at the Very Beginning
+
+@cindex breakpointing Ada elaboration code
+It is sometimes necessary to debug the program during elaboration, and
+before reaching the main procedure.
+As defined in the Ada Reference
+Manual, the elaboration code is invoked from a procedure called
+@code{adainit}. To run your program up to the beginning of
+elaboration, simply use the following two commands:
+@code{tbreak adainit} and @code{run}.
+
+@node Ada Glitches
+@subsubsection Known Peculiarities of Ada Mode
+@cindex Ada, problems
+
+Besides the omissions listed previously (@pxref{Omissions from Ada}),
+we know of several problems with and limitations of Ada mode in
+@value{GDBN},
+some of which will be fixed with planned future releases of the debugger
+and the GNU Ada compiler.
+
+@itemize @bullet
+@item
+Currently, the debugger
+has insufficient information to determine whether certain pointers represent
+pointers to objects or the objects themselves.
+Thus, the user may have to tack an extra @code{.all} after an expression
+to get it printed properly.
+
+@item
+Static constants that the compiler chooses not to materialize as objects in
+storage are invisible to the debugger.
+
+@item
+Named parameter associations in function argument lists are ignored (the
+argument lists are treated as positional).
+
+@item
+Many useful library packages are currently invisible to the debugger.
+
+@item
+Fixed-point arithmetic, conversions, input, and output is carried out using
+floating-point arithmetic, and may give results that only approximate those on
+the host machine.
+
+@item
+The type of the @t{'Address} attribute may not be @code{System.Address}.
+
+@item
+The GNAT compiler never generates the prefix @code{Standard} for any of
+the standard symbols defined by the Ada language. @value{GDBN} knows about
+this: it will strip the prefix from names when you use it, and will never
+look for a name you have so qualified among local symbols, nor match against
+symbols in other packages or subprograms. If you have
+defined entities anywhere in your program other than parameters and
+local variables whose simple names match names in @code{Standard},
+GNAT's lack of qualification here can cause confusion. When this happens,
+you can usually resolve the confusion
+by qualifying the problematic names with package
+@code{Standard} explicitly.
+@end itemize
+
+@node Unsupported languages
+@section Unsupported languages
+
+@cindex unsupported languages
+@cindex minimal language
+In addition to the other fully-supported programming languages,
+@value{GDBN} also provides a pseudo-language, called @code{minimal}.
+It does not represent a real programming language, but provides a set
+of capabilities close to what the C or assembly languages provide.
+This should allow most simple operations to be performed while debugging
+an application that uses a language currently not supported by @value{GDBN}.
+
+If the language is set to @code{auto}, @value{GDBN} will automatically
+select this language if the current frame corresponds to an unsupported
+language.
+
+@node Symbols
+@chapter Examining the Symbol Table
+
+The commands described in this chapter allow you to inquire about the
+symbols (names of variables, functions and types) defined in your
+program. This information is inherent in the text of your program and
+does not change as your program executes. @value{GDBN} finds it in your
+program's symbol table, in the file indicated when you started @value{GDBN}
+(@pxref{File Options, ,Choosing files}), or by one of the
+file-management commands (@pxref{Files, ,Commands to specify files}).
+
+@cindex symbol names
+@cindex names of symbols
+@cindex quoting names
+Occasionally, you may need to refer to symbols that contain unusual
+characters, which @value{GDBN} ordinarily treats as word delimiters. The
+most frequent case is in referring to static variables in other
+source files (@pxref{Variables,,Program variables}). File names
+are recorded in object files as debugging symbols, but @value{GDBN} would
+ordinarily parse a typical file name, like @file{foo.c}, as the three words
+@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize
+@samp{foo.c} as a single symbol, enclose it in single quotes; for example,
+
+@smallexample
+p 'foo.c'::x
+@end smallexample
+
+@noindent
+looks up the value of @code{x} in the scope of the file @file{foo.c}.
+
+@table @code
+@cindex case-insensitive symbol names
+@cindex case sensitivity in symbol names
+@kindex set case-sensitive
+@item set case-sensitive on
+@itemx set case-sensitive off
+@itemx set case-sensitive auto
+Normally, when @value{GDBN} looks up symbols, it matches their names
+with case sensitivity determined by the current source language.
+Occasionally, you may wish to control that. The command @code{set
+case-sensitive} lets you do that by specifying @code{on} for
+case-sensitive matches or @code{off} for case-insensitive ones. If
+you specify @code{auto}, case sensitivity is reset to the default
+suitable for the source language. The default is case-sensitive
+matches for all languages except for Fortran, for which the default is
+case-insensitive matches.
+
+@kindex show case-sensitive
+@item show case-sensitive
+This command shows the current setting of case sensitivity for symbols
+lookups.
+
+@kindex info address
+@cindex address of a symbol
+@item info address @var{symbol}
+Describe where the data for @var{symbol} is stored. For a register
+variable, this says which register it is kept in. For a non-register
+local variable, this prints the stack-frame offset at which the variable
+is always stored.
+
+Note the contrast with @samp{print &@var{symbol}}, which does not work
+at all for a register variable, and for a stack local variable prints
+the exact address of the current instantiation of the variable.
+
+@kindex info symbol
+@cindex symbol from address
+@cindex closest symbol and offset for an address
+@item info symbol @var{addr}
+Print the name of a symbol which is stored at the address @var{addr}.
If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the
nearest symbol and an offset from it:
@kindex info types
@item info types @var{regexp}
@itemx info types
-Print a brief description of all types whose names match @var{regexp}
-(or all types in your program, if you supply no argument). Each
-complete typename is matched as though it were a complete line; thus,
-@samp{i type value} gives information on all types in your program whose
-names include the string @code{value}, but @samp{i type ^value$} gives
-information only on types whose complete name is @code{value}.
+Print a brief description of all types whose names match the regular
+expression @var{regexp} (or all types in your program, if you supply
+no argument). Each complete typename is matched as though it were a
+complete line; thus, @samp{i type value} gives information on all
+types in your program whose names include the string @code{value}, but
+@samp{i type ^value$} gives information only on types whose complete
+name is @code{value}.
This command differs from @code{ptype} in two ways: first, like
@code{whatis}, it does not print a detailed description; second, it
@kindex info scope
@cindex local variables
-@item info scope @var{addr}
+@item info scope @var{location}
List all the variables local to a particular scope. This command
-accepts a location---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:
+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:
@smallexample
(@value{GDBP}) @b{info scope command_line_handler}
whose names contain a match for regular expression @var{regexp}.
Thus, @samp{info fun step} finds all functions whose names
include @code{step}; @samp{info fun ^step} finds those whose names
-start with @code{step}. If a function name contains characters
-that conflict with the regular expression language (eg.
+start with @code{step}. If a function name contains characters
+that conflict with the regular expression language (eg.
@samp{operator*()}), they may be quoted with a backslash.
@kindex info variables
variables) whose names contain a match for regular expression
@var{regexp}.
+@kindex info classes
+@cindex Objective-C, classes and selectors
+@item info classes
+@itemx info classes @var{regexp}
+Display all Objective-C classes in your program, or
+(with the @var{regexp} argument) all those matching a particular regular
+expression.
+
+@kindex info selectors
+@item info selectors
+@itemx info selectors @var{regexp}
+Display all Objective-C selectors in your program, or
+(with the @var{regexp} argument) all those matching a particular regular
+expression.
+
@ignore
This was never implemented.
@kindex info methods
Show the current @code{on} or @code{off} setting.
@end table
+@cindex opaque data types
@kindex set opaque-type-resolution
@item set opaque-type-resolution on
Tell @value{GDBN} to resolve opaque types. An opaque type is a type
@xref{Files, ,Commands to specify files}, for a discussion of how
@value{GDBN} reads symbols (in the description of @code{symbol-file}).
-@kindex maint list symtabs
-@kindex maint list psymtabs
+@kindex maint info symtabs
+@kindex maint info psymtabs
@cindex listing @value{GDBN}'s internal symbol tables
@cindex symbol tables, listing @value{GDBN}'s internal
@cindex full symbol tables, listing @value{GDBN}'s internal
@cindex partial symbol tables, listing @value{GDBN}'s internal
-@item maint list symtabs @r{[} @var{regexp} @r{]}
-@itemx maint list psymtabs @r{[} @var{regexp} @r{]}
+@item maint info symtabs @r{[} @var{regexp} @r{]}
+@itemx maint info psymtabs @r{[} @var{regexp} @r{]}
List the @code{struct symtab} or @code{struct partial_symtab}
structures whose names match @var{regexp}. If @var{regexp} is not
structure in more detail. For example:
@smallexample
-(@value{GDBP}) maint list psymtabs dwarf2read
+(@value{GDBP}) maint info psymtabs dwarf2read
@{ objfile /home/gnu/build/gdb/gdb
((struct objfile *) 0x82e69d0)
- @{ psymtab /home/gnu/src/gdb/dwarf2read.c
+ @{ psymtab /home/gnu/src/gdb/dwarf2read.c
((struct partial_symtab *) 0x8474b10)
readin no
fullname (null)
dependencies (none)
@}
@}
-(@value{GDBP}) maint list symtabs
+(@value{GDBP}) maint info symtabs
(@value{GDBP})
@end smallexample
@noindent
(@value{GDBP}) break dwarf2_psymtab_to_symtab
Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,
line 1574.
-(@value{GDBP}) maint list symtabs
-@{ objfile /home/gnu/build/gdb/gdb
+(@value{GDBP}) maint info symtabs
+@{ objfile /home/gnu/build/gdb/gdb
((struct objfile *) 0x82e69d0)
- @{ symtab /home/gnu/src/gdb/dwarf2read.c
+ @{ symtab /home/gnu/src/gdb/dwarf2read.c
((struct symtab *) 0x86c1f38)
dirname (null)
fullname (null)
debugformat DWARF 2
@}
@}
-(@value{GDBP})
+(@value{GDBP})
@end smallexample
@end table
@c @group
@node Signaling
@section Giving your program a signal
+@cindex deliver a signal to a program
@table @code
@kindex signal
@node Calling
@section Calling program functions
+@table @code
@cindex calling functions
+@cindex inferior functions, calling
+@item print @var{expr}
+Evaluate the expression @var{expr} and display the resuling value.
+@var{expr} may include calls to functions in the program being
+debugged.
+
@kindex call
-@table @code
@item call @var{expr}
Evaluate the expression @var{expr} without displaying @code{void}
returned values.
-@end table
You can use this variant of the @code{print} command if you want to
-execute a function from your program, but without cluttering the output
-with @code{void} returned values. If the result is not void, it
-is printed and saved in the value history.
+execute a function from your program that does not return anything
+(a.k.a.@: @dfn{a void function}), but without cluttering the output
+with @code{void} returned values that @value{GDBN} will otherwise
+print. If the result is not void, it is printed and saved in the
+value history.
+@end table
+
+It is possible for the function you call via the @code{print} or
+@code{call} command to generate a signal (e.g., if there's a bug in
+the function, or if you passed it incorrect arguments). What happens
+in that case is controlled by the @code{set unwindonsignal} command.
+
+@table @code
+@item set unwindonsignal
+@kindex set unwindonsignal
+@cindex unwind stack in called functions
+@cindex call dummy stack unwinding
+Set unwinding of the stack if a signal is received while in a function
+that @value{GDBN} called in the program being debugged. If set to on,
+@value{GDBN} unwinds the stack it created for the call and restores
+the context to what it was before the call. If set to off (the
+default), @value{GDBN} stops in the frame where the signal was
+received.
+
+@item show unwindonsignal
+@kindex show unwindonsignal
+Show the current setting of stack unwinding in the functions called by
+@value{GDBN}.
+@end table
+
+@cindex weak alias functions
+Sometimes, a function you wish to call is actually a @dfn{weak alias}
+for another function. In such case, @value{GDBN} might not pick up
+the type information, including the types of the function arguments,
+which causes @value{GDBN} to call the inferior function incorrectly.
+As a result, the called function will function erroneously and may
+even crash. A solution to that is to use the name of the aliased
+function instead.
@node Patching
@section Patching programs
@var{filename}. If so, @value{GDBN} maps in the symbol table from
@file{@var{filename}.syms}, starting up more quickly. See the
descriptions of the file options @samp{-mapped} and @samp{-readnow}
-(available on the command line, and with the commands @code{file},
-@code{symbol-file}, or @code{add-symbol-file}, described below),
-for more information.
+(available on the command line, see @ref{File Options, , -readnow},
+and with the commands @code{file}, @code{symbol-file}, or
+@code{add-symbol-file}, described below), for more information.
@item file
@code{file} with no argument makes @value{GDBN} discard any information it
@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol
@c files.
-@kindex core
@kindex core-file
-@item core-file @r{[} @var{filename} @r{]}
+@item core-file @r{[}@var{filename}@r{]}
+@itemx core
Specify the whereabouts of a core dump file to be used as the ``contents
of memory''. Traditionally, core files contain only some parts of the
address space of the process that generated them; @value{GDBN} can access the
relocatable files into an already running program; such systems
typically make the requirements above easy to meet. However, it's
important to recognize that many native systems use complex link
-procedures (@code{.linkonce} section factoring and C++ constructor table
+procedures (@code{.linkonce} section factoring and C@t{++} constructor table
assembly, for example) that make the requirements difficult to meet. In
general, one cannot assume that using @code{add-symbol-file} to read a
relocatable object file's symbolic information will have the same effect
the @code{symbol-file} command, to change how @value{GDBN} manages the symbol
table information for @var{filename}.
-@kindex add-shared-symbol-file
-@item add-shared-symbol-file
-The @code{add-shared-symbol-file} command can be used only under Harris' CXUX
-operating system for the Motorola 88k. @value{GDBN} automatically looks for
-shared libraries, however if @value{GDBN} does not find yours, you can run
-@code{add-shared-symbol-file}. It takes no arguments.
+@kindex add-shared-symbol-files
+@kindex assf
+@item add-shared-symbol-files @var{library-file}
+@itemx assf @var{library-file}
+The @code{add-shared-symbol-files} command can currently be used only
+in the Cygwin build of @value{GDBN} on MS-Windows OS, where it is an
+alias for the @code{dll-symbols} command (@pxref{Cygwin Native}).
+@value{GDBN} automatically looks for shared libraries, however if
+@value{GDBN} does not find yours, you can invoke
+@code{add-shared-symbol-files}. It takes one argument: the shared
+library's file name. @code{assf} is a shorthand alias for
+@code{add-shared-symbol-files}.
@kindex section
-@item section
-The @code{section} command changes the base address of section SECTION of
-the exec file to ADDR. This can be used if the exec file does not contain
-section addresses, (such as in the a.out format), or when the addresses
-specified in the file itself are wrong. Each section must be changed
-separately. The @code{info files} command, described below, lists all
-the sections and their addresses.
+@item section @var{section} @var{addr}
+The @code{section} command changes the base address of the named
+@var{section} of the exec file to @var{addr}. This can be used if the
+exec file does not contain section addresses, (such as in the
+@code{a.out} format), or when the addresses specified in the file
+itself are wrong. Each section must be changed separately. The
+@code{info files} command, described below, lists all the sections and
+their addresses.
@kindex info files
@kindex info target
@end table
@end table
@kindex set trust-readonly-sections
+@cindex read-only sections
@item set trust-readonly-sections on
Tell @value{GDBN} that readonly sections in your object file
really are read-only (i.e.@: that their contents will not change).
Tell @value{GDBN} not to trust readonly sections. This means that
the contents of the section might change while the program is running,
and must therefore be fetched from the target when needed.
+
+@item show trust-readonly-sections
+Show the current setting of trusting readonly sections.
@end table
All file-specifying commands allow both absolute and relative file names
name and remembers it that way.
@cindex shared libraries
-@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
-libraries.
+@value{GDBN} supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix,
+and IBM RS/6000 AIX shared libraries.
@value{GDBN} automatically loads symbol definitions from shared libraries
when you use the @code{run} command, or when you examine a core file.
is @code{off}, symbols must be loaded manually, using the
@code{sharedlibrary} command. The default value is @code{on}.
+@cindex memory used for symbol tables
+If your program uses lots of shared libraries with debug info that
+takes large amounts of memory, you can decrease the @value{GDBN}
+memory footprint by preventing it from automatically loading the
+symbols from shared libraries. To that end, type @kbd{set
+auto-solib-add off} before running the inferior, then load each
+library whose debug symbols you do need with @kbd{sharedlibrary
+@var{regexp}}, where @var{regexp} is a regular expresion that matches
+the libraries whose symbols you want to be loaded.
+
@kindex show auto-solib-add
@item show auto-solib-add
Display the current autoloading mode.
Display the current autoloading size threshold, in megabytes.
@end table
+Sometimes you may wish that @value{GDBN} stops and gives you control
+when any of shared library events happen. Use the @code{set
+stop-on-solib-events} command for this:
+
+@table @code
+@item set stop-on-solib-events
+@kindex set stop-on-solib-events
+This command controls whether @value{GDBN} should give you control
+when the dynamic linker notifies it about some shared library event.
+The most common event of interest is loading or unloading of a new
+shared library.
+
+@item show stop-on-solib-events
+@kindex show stop-on-solib-events
+Show whether @value{GDBN} stops and gives you control when shared
+library events happen.
+@end table
+
Shared libraries are also supported in many cross or remote debugging
configurations. A copy of the target's libraries need to be present on the
host system; they need to be the same as the target libraries, although the
describe the CRC used in @code{.gnu_debuglink} sections is to give the
complete code for a function that computes it:
-@kindex @code{gnu_debuglink_crc32}
+@kindex gnu_debuglink_crc32
@smallexample
unsigned long
gnu_debuglink_crc32 (unsigned long crc,
crc = ~crc & 0xffffffff;
for (end = buf + len; buf < end; ++buf)
crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
- return ~crc & 0xffffffff;;
+ return ~crc & 0xffffffff;
@}
@end smallexample
@chapter Specifying a Debugging Target
@cindex debugging target
-@kindex target
-
A @dfn{target} is the execution environment occupied by your program.
Often, @value{GDBN} runs in the same host environment as your program;
command to specify one of the target types configured for @value{GDBN}
(@pxref{Target Commands, ,Commands for managing targets}).
+@cindex target architecture
+It is possible to build @value{GDBN} for several different @dfn{target
+architectures}. When @value{GDBN} is built like that, you can choose
+one of the available architectures with the @kbd{set architecture}
+command.
+
+@table @code
+@kindex set architecture
+@kindex show architecture
+@item set architecture @var{arch}
+This command sets the current target architecture to @var{arch}. The
+value of @var{arch} can be @code{"auto"}, in addition to one of the
+supported architectures.
+
+@item show architecture
+Show the current target architecture.
+
+@item set processor
+@itemx processor
+@kindex set processor
+@kindex show processor
+These are alias commands for, respectively, @code{set architecture}
+and @code{show architecture}.
+@end table
+
@menu
* Active Targets:: Active targets
* Target Commands:: Commands for managing targets
and @code{show gnutarget} displays @samp{The current BDF target is "auto"}.
@end table
+@cindex common targets
Here are some common targets (available, or not, depending on the GDB
configuration):
@table @code
-@kindex target exec
+@kindex target
@item target exec @var{program}
+@cindex executable file target
An executable file. @samp{target exec @var{program}} is the same as
@samp{exec-file @var{program}}.
-@kindex target core
@item target core @var{filename}
+@cindex core dump file target
A core dump file. @samp{target core @var{filename}} is the same as
@samp{core-file @var{filename}}.
-@kindex target remote
@item target remote @var{dev}
+@cindex remote target
Remote serial target in GDB-specific protocol. The argument @var{dev}
specifies what serial device to use for the connection (e.g.
@file{/dev/ttya}). @xref{Remote, ,Remote debugging}. @code{target remote}
some other way of getting the stub to the target system, and you can put
it somewhere in memory where it won't get clobbered by the download.
-@kindex target sim
@item target sim
+@cindex built-in simulator target
Builtin CPU simulator. @value{GDBN} includes simulators for most architectures.
In general,
@smallexample
@table @code
-@kindex target nrom
@item target nrom @var{dev}
+@cindex NetROM ROM emulator target
NetROM ROM emulator. This target only supports downloading.
@end table
Different targets are available on different configurations of @value{GDBN};
your configuration may have more or fewer targets.
-Many remote targets require you to download the executable's code
-once you've successfully established a connection.
+Many remote targets require you to download the executable's code once
+you've successfully established a connection. You may wish to control
+various aspects of this process, such as the size of the data chunks
+used by @value{GDBN} to download program parts to the remote target.
+
+@table @code
+@kindex set download-write-size
+@item set download-write-size @var{size}
+Set the write size used when downloading a program. Only used when
+downloading a program onto a remote target. Specify zero or a
+negative value to disable blocked writes. The actual size of each
+transfer is also limited by the size of the target packet and the
+memory cache.
+
+@kindex show download-write-size
+@item show download-write-size
+@kindex show download-write-size
+Show the current value of the write size.
+
+@item set hash
+@kindex set hash@r{, for remote monitors}
+@cindex hash mark while downloading
+This command controls whether a hash mark @samp{#} is displayed while
+downloading a file to the remote monitor. If on, a hash mark is
+displayed after each S-record is successfully downloaded to the
+monitor.
+
+@item show hash
+@kindex show hash@r{, for remote monitors}
+Show the current status of displaying the hash mark.
+
+@item set debug monitor
+@kindex set debug monitor
+@cindex display remote monitor communications
+Enable or disable display of communications messages between
+@value{GDBN} and the remote monitor.
+
+@item show debug monitor
+@kindex show debug monitor
+Show the current status of displaying communications between
+@value{GDBN} and the remote monitor.
+@end table
@table @code
@cindex choosing target byte order
@cindex target byte order
-Some types of processors, such as the MIPS, PowerPC, and Hitachi SH,
+Some types of processors, such as the MIPS, PowerPC, and Renesas SH,
offer the ability to run either big-endian or little-endian byte
orders. Usually the executable or symbol will include a bit to
designate the endian-ness, and you will not need to worry about
@value{GDBN}'s idea of processor endian-ness manually.
@table @code
-@kindex set endian big
+@kindex set endian
@item set endian big
Instruct @value{GDBN} to assume the target is big-endian.
-@kindex set endian little
@item set endian little
Instruct @value{GDBN} to assume the target is little-endian.
-@kindex set endian auto
@item set endian auto
Instruct @value{GDBN} to use the byte order associated with the
executable.
@node KOD
@section Kernel Object Display
-
@cindex kernel object display
-@cindex kernel object
@cindex KOD
Some targets support kernel object display. Using this facility,
mutexes and other synchronization objects. Exactly which objects can be
displayed is determined on a per-OS basis.
+@kindex set os
Use the @code{set os} command to set the operating system. This tells
@value{GDBN} which kernel object display module to initialize:
(@value{GDBP}) set os cisco
@end smallexample
+@kindex show os
+The associated command @code{show os} displays the operating system
+set with the @code{set os} command; if no operating system has been
+set, @code{show os} will display an empty string @samp{""}.
+
If @code{set os} succeeds, @value{GDBN} will display some information
about the operating system, and will create a new @code{info} command
which can be used to query the target. The @code{info} command is named
after the operating system:
+@kindex info cisco
@smallexample
(@value{GDBP}) info cisco
List of Cisco Kernel Objects
Further subcommands can be used to query about particular objects known
by the kernel.
-There is currently no way to determine whether a given operating system
-is supported other than to try it.
+There is currently no way to determine whether a given operating
+system is supported other than to try setting it with @kbd{set os
+@var{name}}, where @var{name} is the name of the operating system you
+want to try.
@node Remote Debugging
@chapter Debugging remote programs
@menu
+* Connecting:: Connecting to a remote target
* Server:: Using the gdbserver program
* NetWare:: Using the gdbserve.nlm program
* Remote configuration:: Remote configuration
* remote stub:: Implementing a remote stub
@end menu
+@node Connecting
+@section Connecting to a remote target
+
+On the @value{GDBN} host machine, you will need an unstripped copy of
+your program, since @value{GDBN} needs symobl and debugging information.
+Start up @value{GDBN} as usual, using the name of the local copy of your
+program as the first argument.
+
+@cindex serial line, @code{target remote}
+If you're using a serial line, you may want to give @value{GDBN} the
+@w{@samp{--baud}} option, or use the @code{set remotebaud} command
+(@pxref{Remote configuration, set remotebaud}) before the
+@code{target} command.
+
+After that, use @code{target remote} to establish communications with
+the target machine. Its argument specifies how to communicate---either
+via a devicename attached to a direct serial line, or a TCP or UDP port
+(possibly to a terminal server which in turn has a serial line to the
+target). For example, to use a serial line connected to the device
+named @file{/dev/ttyb}:
+
+@smallexample
+target remote /dev/ttyb
+@end smallexample
+
+@cindex TCP port, @code{target remote}
+To use a TCP connection, use an argument of the form
+@code{@var{host}:@var{port}} or @code{tcp:@var{host}:@var{port}}.
+For example, to connect to port 2828 on a
+terminal server named @code{manyfarms}:
+
+@smallexample
+target remote manyfarms:2828
+@end smallexample
+
+If your remote target is actually running on the same machine as
+your debugger session (e.g.@: a simulator of your target running on
+the same host), you can omit the hostname. For example, to connect
+to port 1234 on your local machine:
+
+@smallexample
+target remote :1234
+@end smallexample
+@noindent
+
+Note that the colon is still required here.
+
+@cindex UDP port, @code{target remote}
+To use a UDP connection, use an argument of the form
+@code{udp:@var{host}:@var{port}}. For example, to connect to UDP port 2828
+on a terminal server named @code{manyfarms}:
+
+@smallexample
+target remote udp:manyfarms:2828
+@end smallexample
+
+When using a UDP connection for remote debugging, you should keep in mind
+that the `U' stands for ``Unreliable''. UDP can silently drop packets on
+busy or unreliable networks, which will cause havoc with your debugging
+session.
+
+Now you can use all the usual commands to examine and change data and to
+step and continue the remote program.
+
+@cindex interrupting remote programs
+@cindex remote programs, interrupting
+Whenever @value{GDBN} is waiting for the remote program, if you type the
+interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
+program. This may or may not succeed, depending in part on the hardware
+and the serial drivers the remote system uses. If you type the
+interrupt character once again, @value{GDBN} displays this prompt:
+
+@smallexample
+Interrupted while waiting for the program.
+Give up (and stop debugging it)? (y or n)
+@end smallexample
+
+If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
+(If you decide you want to try again later, you can use @samp{target
+remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
+goes back to waiting.
+
+@table @code
+@kindex detach (remote)
+@item detach
+When you have finished debugging the remote program, you can use the
+@code{detach} command to release it from @value{GDBN} control.
+Detaching from the target normally resumes its execution, but the results
+will depend on your particular remote stub. After the @code{detach}
+command, @value{GDBN} is free to connect to another target.
+
+@kindex disconnect
+@item disconnect
+The @code{disconnect} command behaves like @code{detach}, except that
+the target is generally not resumed. It will wait for @value{GDBN}
+(this instance or another one) to connect and continue debugging. After
+the @code{disconnect} command, @value{GDBN} is again free to connect to
+another target.
+
+@cindex send command to remote monitor
+@kindex monitor
+@item monitor @var{cmd}
+This command allows you to send commands directly to the remote
+monitor.
+@end table
+
@node Server
@section Using the @code{gdbserver} program
@var{pid} is the process ID of a currently running process. It isn't necessary
to point @code{gdbserver} at a binary for the running process.
-@item On the @value{GDBN} host machine,
-you need an unstripped copy of your program, since @value{GDBN} needs
-symbols and debugging information. Start up @value{GDBN} as usual,
-using the name of the local copy of your program as the first argument.
-(You may also need the @w{@samp{--baud}} option if the serial line is
-running at anything other than 9600@dmn{bps}.) After that, use @code{target
-remote} to establish communications with @code{gdbserver}. Its argument
-is either a device name (usually a serial device, like
-@file{/dev/ttyb}), or a TCP port descriptor in the form
-@code{@var{host}:@var{PORT}}. For example:
+@pindex pidof
+@cindex attach to a program by name
+You can debug processes by name instead of process ID if your target has the
+@code{pidof} utility:
@smallexample
-(@value{GDBP}) target remote /dev/ttyb
+target> gdbserver @var{comm} --attach `pidof @var{PROGRAM}`
@end smallexample
-@noindent
-communicates with the server via serial line @file{/dev/ttyb}, and
-
-@smallexample
-(@value{GDBP}) target remote the-target:2345
-@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.
-@noindent
-communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
+@item On the host machine,
+connect to your target (@pxref{Connecting,,Connecting to a remote target}).
For TCP connections, you must start up @code{gdbserver} prior to using
the @code{target remote} command. Otherwise you may get an error whose
text depends on the host system, but which usually looks something like
-@samp{Connection refused}.
+@samp{Connection refused}. You don't need to use the @code{load}
+command in @value{GDBN} when using gdbserver, since the program is
+already on the target.
+
@end table
@node NetWare
load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
@end smallexample
-@item On the @value{GDBN} host machine,
-you need an unstripped copy of your program, since @value{GDBN} needs
-symbols and debugging information. Start up @value{GDBN} as usual,
-using the name of the local copy of your program as the first argument.
-(You may also need the @w{@samp{--baud}} option if the serial line is
-running at anything other than 9600@dmn{bps}. After that, use @code{target
-remote} to establish communications with @code{gdbserve.nlm}. Its
-argument is a device name (usually a serial device, like
-@file{/dev/ttyb}). For example:
-
-@smallexample
-(@value{GDBP}) target remote /dev/ttyb
-@end smallexample
+@item
+On the @value{GDBN} host machine, connect to your target (@pxref{Connecting,,
+Connecting to a remote target}).
-@noindent
-communications with the server via serial line @file{/dev/ttyb}.
@end table
@node Remote configuration
@section Remote configuration
-The following configuration options are available when debugging remote
-programs:
+@kindex set remote
+@kindex show remote
+This section documents the configuration options available when
+debugging remote programs. For the options related to the File I/O
+extensions of the remote protocol, see @ref{The system call,
+system-call-allowed}.
@table @code
-@kindex set remote hardware-watchpoint-limit
-@kindex set remote hardware-breakpoint-limit
+@item set remoteaddresssize @var{bits}
+@cindex adress size for remote targets
+@cindex bits in remote address
+Set the maximum size of address in a memory packet to the specified
+number of bits. @value{GDBN} will mask off the address bits above
+that number, when it passes addresses to the remote target. The
+default value is the number of bits in the target's address.
+
+@item show remoteaddresssize
+Show the current value of remote address size in bits.
+
+@item set remotebaud @var{n}
+@cindex baud rate for remote targets
+Set the baud rate for the remote serial I/O to @var{n} baud. The
+value is used to set the speed of the serial port used for debugging
+remote targets.
+
+@item show remotebaud
+Show the current speed of the remote connection.
+
+@item set remotebreak
+@cindex interrupt remote programs
+@cindex BREAK signal instead of Ctrl-C
+If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote
+when you press the @key{Ctrl-C} key to interrupt the program running
+on the remote. If set to off, @value{GDBN} sends the @samp{Strl-C}
+character instead. The default is off, since most remote systems
+expect to see @samp{Ctrl-C} as the interrupt signal.
+
+@item show remotebreak
+Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to
+interrupt the remote program.
+
+@item set remotedebug
+@cindex debug remote protocol
+@cindex remote protocol debugging
+@cindex display remote packets
+Control the debugging of the remote protocol. When enabled, each
+packet sent to or received from the remote target is displayed. The
+defaults is off.
+
+@item show remotedebug
+Show the current setting of the remote protocol debugging.
+
+@item set remotedevice @var{device}
+@cindex serial port name
+Set the name of the serial port through which to communicate to the
+remote target to @var{device}. This is the device used by
+@value{GDBN} to open the serial communications line to the remote
+target. There's no default, so you must set a valid port name for the
+remote serial communications to work. (Some varieties of the
+@code{target} command accept the port name as part of their
+arguments.)
+
+@item show remotedevice
+Show the current name of the serial port.
+
+@item set remotelogbase @var{base}
+Set the base (a.k.a.@: radix) of logging serial protocol
+communications to @var{base}. Supported values of @var{base} are:
+@code{ascii}, @code{octal}, and @code{hex}. The default is
+@code{ascii}.
+
+@item show remotelogbase
+Show the current setting of the radix for logging remote serial
+protocol.
+
+@item set remotelogfile @var{file}
+@cindex record serial communications on file
+Record remote serial communications on the named @var{file}. The
+default is not to record at all.
+
+@item show remotelogfile.
+Show the current setting of the file name on which to record the
+serial communications.
+
+@item set remotetimeout @var{num}
+@cindex timeout for serial communications
+@cindex remote timeout
+Set the timeout limit to wait for the remote target to respond to
+@var{num} seconds. The default is 2 seconds.
+
+@item show remotetimeout
+Show the current number of seconds to wait for the remote target
+responses.
+
+@cindex limit hardware breakpoints and watchpoints
+@cindex remote target, limit break- and watchpoints
@anchor{set remote hardware-watchpoint-limit}
@anchor{set remote hardware-breakpoint-limit}
@item set remote hardware-watchpoint-limit @var{limit}
@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 fetch-register-packet
+@itemx set remote set-register-packet
+@itemx set remote P-packet
+@itemx set remote p-packet
+@cindex P-packet
+@cindex fetch registers from remote targets
+@cindex set registers in remote targets
+Determine whether @value{GDBN} can set and fetch registers from the
+remote target using the @samp{P} packets. The default depends on the
+remote stub's support of the @samp{P} packets (@value{GDBN} queries
+the stub when this packet is first required).
+
+@item show remote fetch-register-packet
+@itemx show remote set-register-packet
+@itemx show remote P-packet
+@itemx show remote p-packet
+Show the current setting of using the @samp{P} packets for setting and
+fetching registers from the remote target.
+
+@cindex binary downloads
+@cindex X-packet
+@item set remote binary-download-packet
+@itemx set remote X-packet
+Determine whether @value{GDBN} sends downloads in binary mode using
+the @samp{X} packets. The default is on.
+
+@item show remote binary-download-packet
+@itemx show remote X-packet
+Show the current setting of using the @samp{X} packets for binary
+downloads.
+
+@item set remote read-aux-vector-packet
+@cindex auxiliary vector of remote target
+@cindex @code{auxv}, and remote targets
+Set the use of the remote protocol's @samp{qPart:auxv:read} (target
+auxiliary vector read) request. This request is used to fetch the
+remote target's @dfn{auxiliary vector}, see @ref{OS Information,
+Auxiliary Vector}. The default setting depends on the remote stub's
+support of this request (@value{GDBN} queries the stub when this
+request is first required). @xref{General Query Packets, qPart}, for
+more information about this request.
+
+@item show remote read-aux-vector-packet
+Show the current setting of use of the @samp{qPart:auxv:read} request.
+
+@item set remote symbol-lookup-packet
+@cindex remote symbol lookup request
+Set the use of the remote protocol's @samp{qSymbol} (target symbol
+lookup) request. This request is used to communicate symbol
+information to the remote target, e.g., whenever a new shared library
+is loaded by the remote (@pxref{Files, shared libraries}). The
+default setting depends on the remote stub's support of this request
+(@value{GDBN} queries the stub when this request is first required).
+@xref{General Query Packets, qSymbol}, for more information about this
+request.
+
+@item show remote symbol-lookup-packet
+Show the current setting of use of the @samp{qSymbol} request.
+
+@item set remote verbose-resume-packet
+@cindex resume remote target
+@cindex signal thread, and remote targets
+@cindex single-step thread, and remote targets
+@cindex thread-specific operations on remote targets
+Set the use of the remote protocol's @samp{vCont} (descriptive resume)
+request. This request is used to resume specific threads in the
+remote target, and to single-step or signal them. The default setting
+depends on the remote stub's support of this request (@value{GDBN}
+queries the stub when this request is first required). This setting
+affects debugging of multithreaded programs: if @samp{vCont} cannot be
+used, @value{GDBN} might be unable to single-step a specific thread,
+especially under @code{set scheduler-locking off}; it is also
+impossible to pause a specific thread. @xref{Packets, vCont}, for
+more details.
+
+@item show remote verbose-resume-packet
+Show the current setting of use of the @samp{vCont} request
+
+@item set remote software-breakpoint-packet
+@itemx set remote hardware-breakpoint-packet
+@itemx set remote write-watchpoint-packet
+@itemx set remote read-watchpoint-packet
+@itemx set remote access-watchpoint-packet
+@itemx set remote Z-packet
+@cindex Z-packet
+@cindex remote hardware breakpoints and watchpoints
+These commands enable or disable the use of @samp{Z} packets for
+setting breakpoints and watchpoints in the remote target. The default
+depends on the remote stub's support of the @samp{Z} packets
+(@value{GDBN} queries the stub when each packet is first required).
+The command @code{set remote Z-packet}, kept for back-compatibility,
+turns on or off all the features that require the use of @samp{Z}
+packets.
+
+@item show remote software-breakpoint-packet
+@itemx show remote hardware-breakpoint-packet
+@itemx show remote write-watchpoint-packet
+@itemx show remote read-watchpoint-packet
+@itemx show remote access-watchpoint-packet
+@itemx show remote Z-packet
+Show the current setting of @samp{Z} packets usage.
@end table
@node remote stub
@item sh-stub.c
@cindex @file{sh-stub.c}
-@cindex Hitachi
+@cindex Renesas
@cindex SH
-For Hitachi SH architectures.
+For Renesas SH architectures.
@item sparc-stub.c
@cindex @file{sparc-stub.c}
@table @code
@item set_debug_traps
-@kindex set_debug_traps
+@findex set_debug_traps
@cindex remote serial stub, initialization
This routine arranges for @code{handle_exception} to run when your
program stops. You must call this subroutine explicitly near the
beginning of your program.
@item handle_exception
-@kindex handle_exception
+@findex handle_exception
@cindex remote serial stub, main routine
This is the central workhorse, but your program never calls it
explicitly---the setup code arranges for @code{handle_exception} to
@table @code
@item int getDebugChar()
-@kindex getDebugChar
+@findex getDebugChar
Write this subroutine to read a single character from the serial port.
It may be identical to @code{getchar} for your target system; a
different name is used to allow you to distinguish the two if you wish.
@item void putDebugChar(int)
-@kindex putDebugChar
+@findex putDebugChar
Write this subroutine to write a single character to the serial port.
It may be identical to @code{putchar} for your target system; a
different name is used to allow you to distinguish the two if you wish.
@table @code
@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
-@kindex exceptionHandler
+@findex exceptionHandler
Write this function to install @var{exception_address} in the exception
handling tables. You need to do this because the stub does not have any
way of knowing what the exception handling tables on your target system
help from @code{exceptionHandler}.
@item void flush_i_cache()
-@kindex flush_i_cache
+@findex flush_i_cache
On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the
instruction cache, if any, on your target machine. If there is no
instruction cache, this subroutine may be a no-op.
@table @code
@item void *memset(void *, int, int)
-@kindex memset
+@findex memset
This is the standard library function @code{memset} that sets an area of
memory to a known value. If you have one of the free versions of
@code{libc.a}, @code{memset} can be found there; otherwise, you must
@end display
@item
-Insert these lines near the top of your program:
-
-@smallexample
-set_debug_traps();
-breakpoint();
-@end smallexample
-
-@item
-For the 680x0 stub only, you need to provide a variable called
-@code{exceptionHook}. Normally you just use:
-
-@smallexample
-void (*exceptionHook)() = 0;
-@end smallexample
-
-@noindent
-but if before calling @code{set_debug_traps}, you set it to point to a
-function in your program, that function is called when
-@code{@value{GDBN}} continues after stopping on a trap (for example, bus
-error). The function indicated by @code{exceptionHook} is called with
-one parameter: an @code{int} which is the exception number.
-
-@item
-Compile and link together: your program, the @value{GDBN} debugging stub for
-your target architecture, and the supporting subroutines.
-
-@item
-Make sure you have a serial connection between your target machine and
-the @value{GDBN} host, and identify the serial port on the host.
-
-@item
-@c The "remote" target now provides a `load' command, so we should
-@c document that. FIXME.
-Download your program to your target machine (or get it there by
-whatever means the manufacturer provides), and start it.
-
-@item
-To start remote debugging, run @value{GDBN} on the host machine, and specify
-as an executable file the program that is running in the remote machine.
-This tells @value{GDBN} how to find your program's symbols and the contents
-of its pure text.
-
-@item
-@cindex serial line, @code{target remote}
-Establish communication using the @code{target remote} command.
-Its argument specifies how to communicate with the target
-machine---either via a devicename attached to a direct serial line, or a
-TCP or UDP port (usually to a terminal server which in turn has a serial line
-to the target). For example, to use a serial line connected to the
-device named @file{/dev/ttyb}:
-
-@smallexample
-target remote /dev/ttyb
-@end smallexample
-
-@cindex TCP port, @code{target remote}
-To use a TCP connection, use an argument of the form
-@code{@var{host}:@var{port}} or @code{tcp:@var{host}:@var{port}}.
-For example, to connect to port 2828 on a
-terminal server named @code{manyfarms}:
-
-@smallexample
-target remote manyfarms:2828
-@end smallexample
-
-If your remote target is actually running on the same machine as
-your debugger session (e.g.@: a simulator of your target running on
-the same host), you can omit the hostname. For example, to connect
-to port 1234 on your local machine:
-
-@smallexample
-target remote :1234
-@end smallexample
-@noindent
-
-Note that the colon is still required here.
-
-@cindex UDP port, @code{target remote}
-To use a UDP connection, use an argument of the form
-@code{udp:@var{host}:@var{port}}. For example, to connect to UDP port 2828
-on a terminal server named @code{manyfarms}:
+Insert these lines near the top of your program:
@smallexample
-target remote udp:manyfarms:2828
+set_debug_traps();
+breakpoint();
@end smallexample
-When using a UDP connection for remote debugging, you should keep in mind
-that the `U' stands for ``Unreliable''. UDP can silently drop packets on
-busy or unreliable networks, which will cause havoc with your debugging
-session.
+@item
+For the 680x0 stub only, you need to provide a variable called
+@code{exceptionHook}. Normally you just use:
-@end enumerate
+@smallexample
+void (*exceptionHook)() = 0;
+@end smallexample
-Now you can use all the usual commands to examine and change data and to
-step and continue the remote program.
+@noindent
+but if before calling @code{set_debug_traps}, you set it to point to a
+function in your program, that function is called when
+@code{@value{GDBN}} continues after stopping on a trap (for example, bus
+error). The function indicated by @code{exceptionHook} is called with
+one parameter: an @code{int} which is the exception number.
-To resume the remote program and stop debugging it, use the @code{detach}
-command.
+@item
+Compile and link together: your program, the @value{GDBN} debugging stub for
+your target architecture, and the supporting subroutines.
-@cindex interrupting remote programs
-@cindex remote programs, interrupting
-Whenever @value{GDBN} is waiting for the remote program, if you type the
-interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
-program. This may or may not succeed, depending in part on the hardware
-and the serial drivers the remote system uses. If you type the
-interrupt character once again, @value{GDBN} displays this prompt:
+@item
+Make sure you have a serial connection between your target machine and
+the @value{GDBN} host, and identify the serial port on the host.
-@smallexample
-Interrupted while waiting for the program.
-Give up (and stop debugging it)? (y or n)
-@end smallexample
+@item
+@c The "remote" target now provides a `load' command, so we should
+@c document that. FIXME.
+Download your program to your target machine (or get it there by
+whatever means the manufacturer provides), and start it.
-If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
-(If you decide you want to try again later, you can use @samp{target
-remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
-goes back to waiting.
+@item
+Start @value{GDBN} on the host, and connect to the target
+(@pxref{Connecting,,Connecting to a remote target}).
+@end enumerate
@node Configurations
@chapter Configuration-Specific Information
@menu
* HP-UX:: HP-UX
+* BSD libkvm Interface:: Debugging BSD kernel memory images
* SVR4 Process Information:: SVR4 process information
* DJGPP Native:: Features specific to the DJGPP port
* Cygwin Native:: Features specific to the Cygwin port
+* Hurd Native:: Features specific to @sc{gnu} Hurd
+* Neutrino:: Features specific to QNX Neutrino
@end menu
@node HP-UX
begins with a dollar sign, @value{GDBN} searches for a user or system
name first, before it searches for a convenience variable.
-@node SVR4 Process Information
-@subsection SVR4 process information
-@kindex /proc
-@cindex process image
+@node BSD libkvm Interface
+@subsection BSD libkvm Interface
+
+@cindex libkvm
+@cindex kernel memory image
+@cindex kernel crash dump
+
+BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory
+interface that provides a uniform interface for accessing kernel virtual
+memory images, including live systems and crash dumps. @value{GDBN}
+uses this interface to allow you to debug live kernels and kernel crash
+dumps on many native BSD configurations. This is implemented as a
+special @code{kvm} debugging target. For debugging a live system, load
+the currently running kernel into @value{GDBN} and connect to the
+@code{kvm} target:
+
+@smallexample
+(@value{GDBP}) @b{target kvm}
+@end smallexample
+
+For debugging crash dumps, provide the file name of the crash dump as an
+argument:
+
+@smallexample
+(@value{GDBP}) @b{target kvm /var/crash/bsd.0}
+@end smallexample
+
+Once connected to the @code{kvm} target, the following commands are
+available:
-Many versions of SVR4 provide a facility called @samp{/proc} that can be
-used to examine the image of a running process using file-system
-subroutines. If @value{GDBN} is configured for an operating system with
-this facility, the command @code{info proc} is available to report on
-several kinds of information about the process running your program.
-@code{info proc} works only on SVR4 systems that include the
-@code{procfs} code. This includes OSF/1 (Digital Unix), Solaris, Irix,
-and Unixware, but not HP-UX or @sc{gnu}/Linux, for example.
+@table @code
+@kindex kvm
+@item kvm pcb
+Set current context from the @dfn{Process Control Block} (PCB) address.
+
+@item kvm proc
+Set current context from proc address. This command isn't available on
+modern FreeBSD systems.
+@end table
+
+@node SVR4 Process Information
+@subsection SVR4 process information
+@cindex /proc
+@cindex examine process image
+@cindex process info via @file{/proc}
+
+Many versions of SVR4 and compatible systems provide a facility called
+@samp{/proc} that can be used to examine the image of a running
+process using file-system subroutines. If @value{GDBN} is configured
+for an operating system with this facility, the command @code{info
+proc} is available to report information about the process running
+your program, or about any process running on your system. @code{info
+proc} works only on SVR4 systems that include the @code{procfs} code.
+This includes, as of this writing, @sc{gnu}/Linux, OSF/1 (Digital
+Unix), Solaris, Irix, and Unixware, but not HP-UX, for example.
@table @code
@kindex info proc
+@cindex process ID
@item info proc
-Summarize available information about the process.
+@itemx info proc @var{process-id}
+Summarize available information about any running process. If a
+process ID is specified by @var{process-id}, display information about
+that process; otherwise display information about the program being
+debugged. The summary includes the debugged process ID, the command
+line used to invoke it, its current working directory, and its
+executable file's absolute file name.
+
+On some systems, @var{process-id} can be of the form
+@samp{[@var{pid}]/@var{tid}} which specifies a certain thread ID
+within a process. If the optional @var{pid} part is missing, it means
+a thread from the process being debugged (the leading @samp{/} still
+needs to be present, or else @value{GDBN} will interpret the number as
+a process ID rather than a thread ID).
-@kindex info proc mappings
@item info proc mappings
-Report on the address ranges accessible in the program, with information
-on whether your program may read, write, or execute each range.
+@cindex memory address space mappings
+Report the memory address space ranges accessible in the program, with
+information on whether the process has read, write, or execute access
+rights to each range. On @sc{gnu}/Linux systems, each memory range
+includes the object file which is mapped to that range, instead of the
+memory access rights to that range.
+
+@item info proc stat
+@itemx info proc status
+@cindex process detailed status information
+These subcommands are specific to @sc{gnu}/Linux systems. They show
+the process-related information, including the user ID and group ID;
+how many threads are there in the process; its virtual memory usage;
+the signals that are pending, blocked, and ignored; its TTY; its
+consumption of system and user time; its stack size; its @samp{nice}
+value; etc. For more information, see the @samp{proc(5)} man page
+(type @kbd{man 5 proc} from your shell prompt).
+
+@item info proc all
+Show all the information about the process described under all of the
+above @code{info proc} subcommands.
+
@ignore
@comment These sub-options of 'info proc' were not included when
@comment procfs.c was re-written. Keep their descriptions around
@item info proc id
Report on the process IDs related to your program: its own process ID,
the ID of its parent, the process group ID, and the session ID.
-
-@kindex info proc status
-@item info proc status
-General information on the state of the process. If the process is
-stopped, this report includes the reason for stopping, and any signal
-received.
-
-@item info proc all
-Show all the above information about the process.
@end ignore
+
+@item set procfs-trace
+@kindex set procfs-trace
+@cindex @code{procfs} API calls
+This command enables and disables tracing of @code{procfs} API calls.
+
+@item show procfs-trace
+@kindex show procfs-trace
+Show the current state of @code{procfs} API call tracing.
+
+@item set procfs-file @var{file}
+@kindex set procfs-file
+Tell @value{GDBN} to write @code{procfs} API trace to the named
+@var{file}. @value{GDBN} appends the trace info to the previous
+contents of the file. The default is to display the trace on the
+standard output.
+
+@item show procfs-file
+@kindex show procfs-file
+Show the file to which @code{procfs} API trace is written.
+
+@item proc-trace-entry
+@itemx proc-trace-exit
+@itemx proc-untrace-entry
+@itemx proc-untrace-exit
+@kindex proc-trace-entry
+@kindex proc-trace-exit
+@kindex proc-untrace-entry
+@kindex proc-untrace-exit
+These commands enable and disable tracing of entries into and exits
+from the @code{syscall} interface.
+
+@item info pidlist
+@kindex info pidlist
+@cindex process list, QNX Neutrino
+For QNX Neutrino only, this command displays the list of all the
+processes and all the threads within each process.
+
+@item info meminfo
+@kindex info meminfo
+@cindex mapinfo list, QNX Neutrino
+For QNX Neutrino only, this command displays the list of all mapinfos.
@end table
@node DJGPP Native
example, here's how to display the Page Table entry for the page where
the variable @code{i} is stored:
-@smallexample
+@smallexample
@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i}
@exdent @code{Page Table entry for address 0x11a00d30:}
-@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30}
+@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30}
@end smallexample
@noindent
This command is supported only with some DPMI servers.
@end table
+In addition to native debugging, the DJGPP port supports remote
+debugging via a serial data link. The following commands are specific
+to remote serial debugging in the DJGPP port of @value{GDBN}.
+
+@table @code
+@kindex set com1base
+@kindex set com1irq
+@kindex set com2base
+@kindex set com2irq
+@kindex set com3base
+@kindex set com3irq
+@kindex set com4base
+@kindex set com4irq
+@item set com1base @var{addr}
+This command sets the base I/O port address of the @file{COM1} serial
+port.
+
+@item set com1irq @var{irq}
+This command sets the @dfn{Interrupt Request} (@code{IRQ}) line to use
+for the @file{COM1} serial port.
+
+There are similar commands @samp{set com2base}, @samp{set com3irq},
+etc.@: for setting the port address and the @code{IRQ} lines for the
+other 3 COM ports.
+
+@kindex show com1base
+@kindex show com1irq
+@kindex show com2base
+@kindex show com2irq
+@kindex show com3base
+@kindex show com3irq
+@kindex show com4base
+@kindex show com4irq
+The related commands @samp{show com1base}, @samp{show com1irq} etc.@:
+display the current settings of the base address and the @code{IRQ}
+lines used by the COM ports.
+@end table
+
+
@node Cygwin Native
@subsection Features for Debugging MS Windows PE executables
@cindex MS Windows debugging
This command loads symbols from a dll similarly to
add-sym command but without the need to specify a base address.
-@kindex set new-console
+@kindex set new-console
@item set new-console @var{mode}
-If @var{mode} is @code{on} the debuggee will
+If @var{mode} is @code{on} the debuggee will
be started in a new console on next start.
If @var{mode} is @code{off}i, the debuggee will
be started in the same console as the debugger.
@kindex set debugexec
@item set debugexec
-This boolean value adds debug output concerning execute events
+This boolean value adds debug output concerning execute events
seen by the debugger.
@kindex set debugexceptions
@item set debugexceptions
-This boolean value adds debug ouptut concerning exception events
+This boolean value adds debug ouptut concerning exception events
seen by the debugger.
@kindex set debugmemory
@item set debugmemory
-This boolean value adds debug ouptut concerning memory events
+This boolean value adds debug ouptut concerning memory events
seen by the debugger.
@kindex set shell
@pxref{Symbols}). Here's an example:
@smallexample
-(gdb) info function CreateFileA
+(@value{GDBP}) info function CreateFileA
All functions matching regular expression "CreateFileA":
Non-debugging symbols:
@end smallexample
@smallexample
-(gdb) info function !
+(@value{GDBP}) info function !
All functions matching regular expression "!":
Non-debugging symbols:
problem:
@smallexample
-(gdb) print 'cygwin1!__argv'
+(@value{GDBP}) print 'cygwin1!__argv'
$1 = 268572168
@end smallexample
@smallexample
-(gdb) x 'cygwin1!__argv'
+(@value{GDBP}) x 'cygwin1!__argv'
0x10021610: "\230y\""
@end smallexample
And two possible solutions:
@smallexample
-(gdb) print ((char **)'cygwin1!__argv')[0]
+(@value{GDBP}) print ((char **)'cygwin1!__argv')[0]
$2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram"
@end smallexample
@smallexample
-(gdb) x/2x &'cygwin1!__argv'
+(@value{GDBP}) x/2x &'cygwin1!__argv'
0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000
-(gdb) x/x 0x10021608
+(@value{GDBP}) x/x 0x10021608
0x10021608: 0x0022fd98
-(gdb) x/s 0x0022fd98
+(@value{GDBP}) x/s 0x0022fd98
0x22fd98: "/cygdrive/c/mydirectory/myprogram"
@end smallexample
to set the breakpoint at a raw memory address:
@smallexample
-(gdb) break *&'python22!PyOS_Readline'
+(@value{GDBP}) break *&'python22!PyOS_Readline'
Breakpoint 1 at 0x1e04eff0
@end smallexample
break point within a shared DLL like @file{kernel32.dll} is completely
safe.
+@node Hurd Native
+@subsection Commands specific to @sc{gnu} Hurd systems
+@cindex @sc{gnu} Hurd debugging
+
+This subsection describes @value{GDBN} commands specific to the
+@sc{gnu} Hurd native debugging.
+
+@table @code
+@item set signals
+@itemx set sigs
+@kindex set signals@r{, Hurd command}
+@kindex set sigs@r{, Hurd command}
+This command toggles the state of inferior signal interception by
+@value{GDBN}. Mach exceptions, such as breakpoint traps, are not
+affected by this command. @code{sigs} is a shorthand alias for
+@code{signals}.
+
+@item show signals
+@itemx show sigs
+@kindex show signals@r{, Hurd command}
+@kindex show sigs@r{, Hurd command}
+Show the current state of intercepting inferior's signals.
+
+@item set signal-thread
+@itemx set sigthread
+@kindex set signal-thread
+@kindex set sigthread
+This command tells @value{GDBN} which thread is the @code{libc} signal
+thread. That thread is run when a signal is delivered to a running
+process. @code{set sigthread} is the shorthand alias of @code{set
+signal-thread}.
+
+@item show signal-thread
+@itemx show sigthread
+@kindex show signal-thread
+@kindex show sigthread
+These two commands show which thread will run when the inferior is
+delivered a signal.
+
+@item set stopped
+@kindex set stopped@r{, Hurd command}
+This commands tells @value{GDBN} that the inferior process is stopped,
+as with the @code{SIGSTOP} signal. The stopped process can be
+continued by delivering a signal to it.
+
+@item show stopped
+@kindex show stopped@r{, Hurd command}
+This command shows whether @value{GDBN} thinks the debuggee is
+stopped.
+
+@item set exceptions
+@kindex set exceptions@r{, Hurd command}
+Use this command to turn off trapping of exceptions in the inferior.
+When exception trapping is off, neither breakpoints nor
+single-stepping will work. To restore the default, set exception
+trapping on.
+
+@item show exceptions
+@kindex show exceptions@r{, Hurd command}
+Show the current state of trapping exceptions in the inferior.
+
+@item set task pause
+@kindex set task@r{, Hurd commands}
+@cindex task attributes (@sc{gnu} Hurd)
+@cindex pause current task (@sc{gnu} Hurd)
+This command toggles task suspension when @value{GDBN} has control.
+Setting it to on takes effect immediately, and the task is suspended
+whenever @value{GDBN} gets control. Setting it to off will take
+effect the next time the inferior is continued. If this option is set
+to off, you can use @code{set thread default pause on} or @code{set
+thread pause on} (see below) to pause individual threads.
+
+@item show task pause
+@kindex show task@r{, Hurd commands}
+Show the current state of task suspension.
+
+@item set task detach-suspend-count
+@cindex task suspend count
+@cindex detach from task, @sc{gnu} Hurd
+This command sets the suspend count the task will be left with when
+@value{GDBN} detaches from it.
+
+@item show task detach-suspend-count
+Show the suspend count the task will be left with when detaching.
+
+@item set task exception-port
+@itemx set task excp
+@cindex task exception port, @sc{gnu} Hurd
+This command sets the task exception port to which @value{GDBN} will
+forward exceptions. The argument should be the value of the @dfn{send
+rights} of the task. @code{set task excp} is a shorthand alias.
+
+@item set noninvasive
+@cindex noninvasive task options
+This command switches @value{GDBN} to a mode that is the least
+invasive as far as interfering with the inferior is concerned. This
+is the same as using @code{set task pause}, @code{set exceptions}, and
+@code{set signals} to values opposite to the defaults.
+
+@item info send-rights
+@itemx info receive-rights
+@itemx info port-rights
+@itemx info port-sets
+@itemx info dead-names
+@itemx info ports
+@itemx info psets
+@cindex send rights, @sc{gnu} Hurd
+@cindex receive rights, @sc{gnu} Hurd
+@cindex port rights, @sc{gnu} Hurd
+@cindex port sets, @sc{gnu} Hurd
+@cindex dead names, @sc{gnu} Hurd
+These commands display information about, respectively, send rights,
+receive rights, port rights, port sets, and dead names of a task.
+There are also shorthand aliases: @code{info ports} for @code{info
+port-rights} and @code{info psets} for @code{info port-sets}.
+
+@item set thread pause
+@kindex set thread@r{, Hurd command}
+@cindex thread properties, @sc{gnu} Hurd
+@cindex pause current thread (@sc{gnu} Hurd)
+This command toggles current thread suspension when @value{GDBN} has
+control. Setting it to on takes effect immediately, and the current
+thread is suspended whenever @value{GDBN} gets control. Setting it to
+off will take effect the next time the inferior is continued.
+Normally, this command has no effect, since when @value{GDBN} has
+control, the whole task is suspended. However, if you used @code{set
+task pause off} (see above), this command comes in handy to suspend
+only the current thread.
+
+@item show thread pause
+@kindex show thread@r{, Hurd command}
+This command shows the state of current thread suspension.
+
+@item set thread run
+This comamnd sets whether the current thread is allowed to run.
+
+@item show thread run
+Show whether the current thread is allowed to run.
+
+@item set thread detach-suspend-count
+@cindex thread suspend count, @sc{gnu} Hurd
+@cindex detach from thread, @sc{gnu} Hurd
+This command sets the suspend count @value{GDBN} will leave on a
+thread when detaching. This number is relative to the suspend count
+found by @value{GDBN} when it notices the thread; use @code{set thread
+takeover-suspend-count} to force it to an absolute value.
+
+@item show thread detach-suspend-count
+Show the suspend count @value{GDBN} will leave on the thread when
+detaching.
+
+@item set thread exception-port
+@itemx set thread excp
+Set the thread exception port to which to forward exceptions. This
+overrides the port set by @code{set task exception-port} (see above).
+@code{set thread excp} is the shorthand alias.
+
+@item set thread takeover-suspend-count
+Normally, @value{GDBN}'s thread suspend counts are relative to the
+value @value{GDBN} finds when it notices each thread. This command
+changes the suspend counts to be absolute instead.
+
+@item set thread default
+@itemx show thread default
+@cindex thread default settings, @sc{gnu} Hurd
+Each of the above @code{set thread} commands has a @code{set thread
+default} counterpart (e.g., @code{set thread default pause}, @code{set
+thread default exception-port}, etc.). The @code{thread default}
+variety of commands sets the default thread properties for all
+threads; you can then change the properties of individual threads with
+the non-default commands.
+@end table
+
+
+@node Neutrino
+@subsection QNX Neutrino
+@cindex QNX Neutrino
+
+@value{GDBN} provides the following commands specific to the QNX
+Neutrino target:
+
+@table @code
+@item set debug nto-debug
+@kindex set debug nto-debug
+When set to on, enables debugging messages specific to the QNX
+Neutrino support.
+
+@item show debug nto-debug
+@kindex show debug nto-debug
+Show the current state of QNX Neutrino messages.
+@end table
+
+
@node Embedded OS
@section Embedded Operating Systems
this manual was produced; newer releases of VxWorks may use revised
procedures.
-@kindex INCLUDE_RDB
+@findex INCLUDE_RDB
To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
to include the remote debugging interface routines in the VxWorks
library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
@menu
* ARM:: ARM
-* H8/300:: Hitachi H8/300
-* H8/500:: Hitachi H8/500
-* M32R/D:: Mitsubishi M32R/D
+* H8/300:: Renesas H8/300
+* H8/500:: Renesas H8/500
+* M32R/D:: Renesas M32R/D
* M68K:: Motorola M68K
* MIPS Embedded:: MIPS Embedded
* OpenRISC 1000:: OpenRisc 1000
* PA:: HP PA Embedded
* PowerPC: PowerPC
-* SH:: Hitachi SH
+* SH:: Renesas SH
* Sparclet:: Tsqware Sparclet
* Sparclite:: Fujitsu Sparclite
* ST2000:: Tandem ST2000
* Z8000:: Zilog Z8000
+* AVR:: Atmel AVR
+* CRIS:: CRIS
+* Super-H:: Renesas Super-H
@end menu
@node ARM
@end table
+@value{GDBN} provides the following ARM-specific commands:
+
+@table @code
+@item set arm disassembler
+@kindex set arm
+This commands selects from a list of disassembly styles. The
+@code{"std"} style is the standard style.
+
+@item show arm disassembler
+@kindex show arm
+Show the current disassembly style.
+
+@item set arm apcs32
+@cindex ARM 32-bit mode
+This command toggles ARM operation mode between 32-bit and 26-bit.
+
+@item show arm apcs32
+Display the current usage of the ARM 32-bit mode.
+
+@item set arm fpu @var{fputype}
+This command sets the ARM floating-point unit (FPU) type. The
+argument @var{fputype} can be one of these:
+
+@table @code
+@item auto
+Determine the FPU type by querying the OS ABI.
+@item softfpa
+Software FPU, with mixed-endian doubles on little-endian ARM
+processors.
+@item fpa
+GCC-compiled FPA co-processor.
+@item softvfp
+Software FPU with pure-endian doubles.
+@item vfp
+VFP co-processor.
+@end table
+
+@item show arm fpu
+Show the current type of the FPU.
+
+@item set arm abi
+This command forces @value{GDBN} to use the specified ABI.
+
+@item show arm abi
+Show the currently used ABI.
+
+@item set debug arm
+Toggle whether to display ARM-specific debugging messages from the ARM
+target support subsystem.
+
+@item show debug arm
+Show whether ARM-specific debugging messages are enabled.
+@end table
+
+
@node H8/300
-@subsection Hitachi H8/300
+@subsection Renesas H8/300
@table @code
@kindex target hms@r{, with H8/300}
@item target hms @var{dev}
-A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host.
+A Renesas SH, H8/300, or H8/500 board, attached via serial line to your host.
Use special commands @code{device} and @code{speed} to control the serial
line and the communications speed used.
@kindex target e7000@r{, with H8/300}
@item target e7000 @var{dev}
-E7000 emulator for Hitachi H8 and SH.
+E7000 emulator for Renesas H8 and SH.
@kindex target sh3@r{, with H8/300}
@kindex target sh3e@r{, with H8/300}
@item target sh3 @var{dev}
@itemx target sh3e @var{dev}
-Hitachi SH-3 and SH-3E target systems.
+Renesas SH-3 and SH-3E target systems.
@end table
@cindex download to H8/300 or H8/500
@cindex H8/300 or H8/500 download
-@cindex download to Hitachi SH
-@cindex Hitachi SH download
-When you select remote debugging to a Hitachi SH, H8/300, or H8/500
-board, the @code{load} command downloads your program to the Hitachi
+@cindex download to Renesas SH
+@cindex Renesas SH download
+When you select remote debugging to a Renesas SH, H8/300, or H8/500
+board, the @code{load} command downloads your program to the Renesas
board and also opens it as the current executable target for
@value{GDBN} on your host (like the @code{file} command).
@value{GDBN} needs to know these things to talk to your
-Hitachi SH, H8/300, or H8/500:
+Renesas SH, H8/300, or H8/500:
@enumerate
@item
that you want to use @samp{target hms}, the remote debugging interface
-for Hitachi microprocessors, or @samp{target e7000}, the in-circuit
-emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is
-the default when @value{GDBN} is configured specifically for the Hitachi SH,
+for Renesas microprocessors, or @samp{target e7000}, the in-circuit
+emulator for the Renesas SH and the Renesas 300H. (@samp{target hms} is
+the default when @value{GDBN} is configured specifically for the Renesas SH,
H8/300, or H8/500.)
@item
-what serial device connects your host to your Hitachi board (the first
+what serial device connects your host to your Renesas board (the first
serial device available on your host is the default).
@item
@end enumerate
@menu
-* Hitachi Boards:: Connecting to Hitachi boards.
-* Hitachi ICE:: Using the E7000 In-Circuit Emulator.
-* Hitachi Special:: Special @value{GDBN} commands for Hitachi micros.
+* Renesas Boards:: Connecting to Renesas boards.
+* Renesas ICE:: Using the E7000 In-Circuit Emulator.
+* Renesas Special:: Special @value{GDBN} commands for Renesas micros.
@end menu
-@node Hitachi Boards
-@subsubsection Connecting to Hitachi boards
+@node Renesas Boards
+@subsubsection Connecting to Renesas boards
@c only for Unix hosts
@kindex device
-@cindex serial device, Hitachi micros
+@cindex serial device, Renesas micros
Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you
need to explicitly set the serial device. The default @var{port} is the
first available port on your host. This is only necessary on Unix
hosts, where it is typically something like @file{/dev/ttya}.
@kindex speed
-@cindex serial line speed, Hitachi micros
+@cindex serial line speed, Renesas micros
@code{@value{GDBN}} has another special command to set the communications
speed: @samp{speed @var{bps}}. This command also is only used from Unix
hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with
@w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection).
The @samp{device} and @samp{speed} commands are available only when you
-use a Unix host to debug your Hitachi microprocessor programs. If you
+use a Unix host to debug your Renesas microprocessor programs. If you
use a DOS host,
@value{GDBN} depends on an auxiliary terminate-and-stay-resident program
called @code{asynctsr} to communicate with the development board
The following sample session illustrates the steps needed to start a
program under @value{GDBN} control on an H8/300. The example uses a
sample H8/300 program called @file{t.x}. The procedure is the same for
-the Hitachi SH and the H8/500.
+the Renesas SH and the H8/500.
First hook up your development board. In this example, we use a
board attached to serial port @code{COM2}; if you use a different serial
@kindex target hms@r{, and serial protocol}
Now that serial communications are set up, and the development board is
-connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
+connected, you can start up @value{GDBN}. Call @code{@value{GDBN}} with
the name of your program as the argument. @code{@value{GDBN}} prompts
you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
commands to begin your debugging session: @samp{target hms} to specify
-cross-debugging to the Hitachi board, and the @code{load} command to
+cross-debugging to the Renesas board, and the @code{load} command to
download your program to the board. @code{load} displays the names of
the program's sections, and a @samp{*} for each 2K of data downloaded.
(If you want to refresh @value{GDBN} data on symbols or on the
In either case, @value{GDBN} sees the effect of a @sc{reset} on the
development board as a ``normal exit'' of your program.
-@node Hitachi ICE
+@node Renesas ICE
@subsubsection Using the E7000 in-circuit emulator
-@kindex target e7000@r{, with Hitachi ICE}
+@kindex target e7000@r{, with Renesas ICE}
You can use the E7000 in-circuit emulator to develop code for either the
-Hitachi SH or the H8/300H. Use one of these forms of the @samp{target
+Renesas SH or the H8/300H. Use one of these forms of the @samp{target
e7000} command to connect @value{GDBN} to your E7000:
@table @code
specify its hostname; @value{GDBN} uses @code{telnet} to connect.
@end table
-@node Hitachi Special
-@subsubsection Special @value{GDBN} commands for Hitachi micros
+@node Renesas Special
+@subsubsection Special @value{GDBN} commands for Renesas micros
Some @value{GDBN} commands are available only for the H8/300:
@end table
@node M32R/D
-@subsection Mitsubishi M32R/D
+@subsection Renesas M32R/D
@table @code
-
@kindex target m32r
@item target m32r @var{dev}
-Mitsubishi M32R/D ROM monitor.
+Renesas M32R/D ROM monitor.
+
+@kindex target m32rsdi
+@item target m32rsdi @var{dev}
+Renesas M32R SDI server, connected via parallel port to the board.
+@end table
+
+The following @value{GDBN} commands are specific to the M32R monitor:
+
+@table @code
+@item set download-path @var{path}
+@kindex set download-path
+@cindex find downloadable @sc{srec} files (M32R)
+Set the default path for finding donwloadable @sc{srec} files.
+
+@item show download-path
+@kindex show download-path
+Show the default path for downloadable @sc{srec} files.
+
+@item set board-address @var{addr}
+@kindex set board-address
+@cindex M32-EVA target board address
+Set the IP address for the M32R-EVA target board.
+@item show board-address
+@kindex show board-address
+Show the current IP address of the target board.
+
+@item set server-address @var{addr}
+@kindex set server-address
+@cindex download server address (M32R)
+Set the IP address for the download server, which is the @value{GDBN}'s
+host machine.
+
+@item show server-address
+@kindex show server-address
+Display the IP address of the download server.
+
+@item upload @r{[}@var{file}@r{]}
+@kindex upload@r{, M32R}
+Upload the specified @sc{srec} @var{file} via the monitor's Ethernet
+upload capability. If no @var{file} argument is given, the current
+executable file is uploaded.
+
+@item tload @r{[}@var{file}@r{]}
+@kindex tload@r{, M32R}
+Test the @code{upload} command.
@end table
@node M68K
@value{GDBN} also supports these special commands for MIPS targets:
@table @code
-@item set processor @var{args}
-@itemx show processor
-@kindex set processor @var{args}
-@kindex show processor
-Use the @code{set processor} command to set the type of MIPS
-processor when you want to access processor-type-specific registers.
-For example, @code{set processor @var{r3041}} tells @value{GDBN}
-to use the CPU registers appropriate for the 3041 chip.
-Use the @code{show processor} command to see what MIPS processor @value{GDBN}
-is using. Use the @code{info reg} command to see what registers
-@value{GDBN} is using.
-
@item set mipsfpu double
@itemx set mipsfpu single
@itemx set mipsfpu none
+@itemx set mipsfpu auto
@itemx show mipsfpu
@kindex set mipsfpu
@kindex show mipsfpu
As usual, you can inquire about the @code{mipsfpu} variable with
@samp{show mipsfpu}.
-@item set remotedebug @var{n}
-@itemx show remotedebug
-@kindex set remotedebug@r{, MIPS protocol}
-@kindex show remotedebug@r{, MIPS protocol}
-@cindex @code{remotedebug}, MIPS protocol
-@cindex MIPS @code{remotedebug} protocol
-@c FIXME! For this to be useful, you must know something about the MIPS
-@c FIXME...protocol. Where is it described?
-You can see some debugging information about communications with the board
-by setting the @code{remotedebug} variable. If you set it to @code{1} using
-@samp{set remotedebug 1}, every packet is displayed. If you set it
-to @code{2}, every character is displayed. You can check the current value
-at any time with the command @samp{show remotedebug}.
-
@item set timeout @var{seconds}
@itemx set retransmit-timeout @var{seconds}
@itemx show timeout
@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
-@kindex htrace info
+@kindex htrace
@item htrace info
Display information about current HW trace configuration.
-@kindex htrace trigger
@item htrace trigger @var{conditional}
Set starting criteria for HW trace.
-@kindex htrace qualifier
@item htrace qualifier @var{conditional}
Set acquisition qualifier for HW trace.
-@kindex htrace stop
@item htrace stop @var{conditional}
Set HW trace stopping criteria.
-@kindex htrace record
@item htrace record [@var{data}]*
Selects the data to be recorded, when qualifier is met and HW trace was
triggered.
-@kindex htrace enable
@item htrace enable
-@kindex htrace disable
@itemx htrace disable
Enables/disables the HW trace.
-@kindex htrace rewind
@item htrace rewind [@var{filename}]
Clears currently recorded trace data.
If filename is specified, new trace file is made and any newly collected data
will be written there.
-@kindex htrace print
@item htrace print [@var{start} [@var{len}]]
Prints trace buffer, using current record configuration.
-@kindex htrace mode continuous
@item htrace mode continuous
Set continuous trace mode.
-@kindex htrace mode suspend
@item htrace mode suspend
Set suspend trace mode.
@end table
@node SH
-@subsection Hitachi SH
+@subsection Renesas SH
@table @code
-@kindex target hms@r{, with Hitachi SH}
+@kindex target hms@r{, with Renesas SH}
@item target hms @var{dev}
-A Hitachi SH board attached via serial line to your host. Use special
+A Renesas SH board attached via serial line to your host. Use special
commands @code{device} and @code{speed} to control the serial line and
the communications speed used.
-@kindex target e7000@r{, with Hitachi SH}
+@kindex target e7000@r{, with Renesas SH}
@item target e7000 @var{dev}
-E7000 emulator for Hitachi SH.
+E7000 emulator for Renesas SH.
@kindex target sh3@r{, with SH}
@kindex target sh3e@r{, with SH}
@item target sh3 @var{dev}
@item target sh3e @var{dev}
-Hitachi SH-3 and SH-3E target systems.
+Renesas SH-3 and SH-3E target systems.
@end table
conditional breakpoint that suspends only after at least 5000
simulated clock ticks.
+@node AVR
+@subsection Atmel AVR
+@cindex AVR
+
+When configured for debugging the Atmel AVR, @value{GDBN} supports the
+following AVR-specific commands:
+
+@table @code
+@item info io_registers
+@kindex info io_registers@r{, AVR}
+@cindex I/O registers (Atmel AVR)
+This command displays information about the AVR I/O registers. For
+each register, @value{GDBN} prints its number and value.
+@end table
+
+@node CRIS
+@subsection CRIS
+@cindex CRIS
+
+When configured for debugging CRIS, @value{GDBN} provides the
+following CRIS-specific commands:
+
+@table @code
+@item set cris-version @var{ver}
+@cindex CRIS version
+Set the current CRIS version to @var{ver}. The CRIS version affects
+register names and sizes. This command is useful in case
+autodetection of the CRIS version fails.
+
+@item show cris-version
+Show the current CRIS version.
+
+@item set cris-dwarf2-cfi
+@cindex DWARF-2 CFI and CRIS
+Set the usage of DWARF-2 CFI for CRIS debugging. The default is off
+if using @code{gcc-cris} whose version is below @code{R59}, otherwise
+on.
+
+@item show cris-dwarf2-cfi
+Show the current state of using DWARF-2 CFI.
+@end table
+
+@node Super-H
+@subsection Renesas Super-H
+@cindex Super-H
+
+For the Renesas Super-H processor, @value{GDBN} provides these
+commands:
+
+@table @code
+@item regs
+@kindex regs@r{, Super-H}
+Show the values of all Super-H registers.
+@end table
+
+
@node Architectures
@section Architectures
all uses of @value{GDBN} with the architecture, both native and cross.
@menu
+* i386::
* A29K::
* Alpha::
* MIPS::
+* HPPA:: HP PA architecture
@end menu
+@node i386
+@subsection x86 Architecture-specific issues.
+
+@table @code
+@item set struct-convention @var{mode}
+@kindex set struct-convention
+@cindex struct return convention
+@cindex struct/union returned in registers
+Set the convention used by the inferior to return @code{struct}s and
+@code{union}s from functions to @var{mode}. Possible values of
+@var{mode} are @code{"pcc"}, @code{"reg"}, and @code{"default"} (the
+default). @code{"default"} or @code{"pcc"} means that @code{struct}s
+are returned on the stack, while @code{"reg"} means that a
+@code{struct} or a @code{union} whose size is 1, 2, 4, or 8 bytes will
+be returned in a register.
+
+@item show struct-convention
+@kindex show struct-convention
+Show the current setting of the convention to return @code{struct}s
+from functions.
+@end table
+
@node A29K
@subsection A29K
search for the beginning of a function. A value of @var{0} (the
default) means there is no limit. However, except for @var{0}, the
larger the limit the more bytes @code{heuristic-fence-post} must search
-and therefore the longer it takes to run.
+and therefore the longer it takes to run. You should only need to use
+this command when debugging a stripped executable.
@item show heuristic-fence-post
Display the current limit.
These commands are available @emph{only} when @value{GDBN} is configured
for debugging programs on Alpha or MIPS processors.
+Several MIPS-specific commands are available when debugging MIPS
+programs:
+
+@table @code
+@item set mips saved-gpreg-size @var{size}
+@kindex set mips saved-gpreg-size
+@cindex MIPS GP register size on stack
+Set the size of MIPS general-purpose registers saved on the stack.
+The argument @var{size} can be one of the following:
+
+@table @samp
+@item 32
+32-bit GP registers
+@item 64
+64-bit GP registers
+@item auto
+Use the target's default setting or autodetect the saved size from the
+information contained in the executable. This is the default
+@end table
+
+@item show mips saved-gpreg-size
+@kindex show mips saved-gpreg-size
+Show the current size of MIPS GP registers on the stack.
+
+@item set mips stack-arg-size @var{size}
+@kindex set mips stack-arg-size
+@cindex MIPS stack space for arguments
+Set the amount of stack space reserved for arguments to functions.
+The argument can be one of @code{"32"}, @code{"64"} or @code{"auto"}
+(the default).
+
+@item set mips abi @var{arg}
+@kindex set mips abi
+@cindex set ABI for MIPS
+Tell @value{GDBN} which MIPS ABI is used by the inferior. Possible
+values of @var{arg} are:
+
+@table @samp
+@item auto
+The default ABI associated with the current binary (this is the
+default).
+@item o32
+@item o64
+@item n32
+@item n64
+@item eabi32
+@item eabi64
+@item auto
+@end table
+
+@item show mips abi
+@kindex show mips abi
+Show the MIPS ABI used by @value{GDBN} to debug the inferior.
+
+@item set mipsfpu
+@itemx show mipsfpu
+@xref{MIPS Embedded, set mipsfpu}.
+
+@item set mips mask-address @var{arg}
+@kindex set mips mask-address
+@cindex MIPS addresses, masking
+This command determines whether the most-significant 32 bits of 64-bit
+MIPS addresses are masked off. The argument @var{arg} can be
+@samp{on}, @samp{off}, or @samp{auto}. The latter is the default
+setting, which lets @value{GDBN} determine the correct value.
+
+@item show mips mask-address
+@kindex show mips mask-address
+Show whether the upper 32 bits of MIPS addresses are masked off or
+not.
+
+@item set remote-mips64-transfers-32bit-regs
+@kindex set remote-mips64-transfers-32bit-regs
+This command controls compatibility with 64-bit MIPS targets that
+transfer data in 32-bit quantities. If you have an old MIPS 64 target
+that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr},
+and 64 bits for other registers, set this option to @samp{on}.
+
+@item show remote-mips64-transfers-32bit-regs
+@kindex show remote-mips64-transfers-32bit-regs
+Show the current setting of compatibility with older MIPS 64 targets.
+
+@item set debug mips
+@kindex set debug mips
+This command turns on and off debugging messages for the MIPS-specific
+target code in @value{GDBN}.
+
+@item show debug mips
+@kindex show debug mips
+Show the current setting of MIPS debugging messages.
+@end table
+
+
+@node HPPA
+@subsection HPPA
+@cindex HPPA support
+
+When @value{GDBN} is debugging te HP PA architecture, it provides the
+following special commands:
+
+@table @code
+@item set debug hppa
+@kindex set debug hppa
+THis command determines whether HPPA architecture specific debugging
+messages are to be displayed.
+
+@item show debug hppa
+Show whether HPPA debugging messages are displayed.
+
+@item maint print unwind @var{address}
+@kindex maint print unwind@r{, HPPA}
+This command displays the contents of the unwind table entry at the
+given @var{address}.
+
+@end table
+
@node Controlling GDB
@chapter Controlling @value{GDBN}
@cindex readline
@cindex command line editing
-@value{GDBN} reads its input commands via the @dfn{readline} interface. This
+@value{GDBN} reads its input commands via the @dfn{Readline} interface. This
@sc{gnu} library provides consistent behavior for programs which provide a
command line interface to the user. Advantages are @sc{gnu} Emacs-style
or @dfn{vi}-style inline editing of commands, @code{csh}-like history
Show whether command line editing is enabled.
@end table
+@xref{Command Line Editing}, for more details about the Readline
+interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
+encouraged to read that chapter.
+
@node History
@section Command history
+@cindex command history
@value{GDBN} can keep track of the commands you type during your
debugging sessions, so that you can be certain of precisely what
happened. Use these commands to manage the @value{GDBN} command
history facility.
+@value{GDBN} uses the @sc{gnu} History library, a part of the Readline
+package, to provide the history facility. @xref{Using History
+Interactively}, for the detailed description of the History library.
+
+Here is the description of @value{GDBN} commands related to command
+history.
+
@table @code
@cindex history substitution
@cindex history file
@kindex set history filename
-@kindex GDBHISTFILE
+@cindex @env{GDBHISTFILE}, environment variable
@item set history filename @var{fname}
Set the name of the @value{GDBN} command history file to @var{fname}.
This is the file where @value{GDBN} reads an initial command history
@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable
is not set.
-@cindex history save
+@cindex save command history
@kindex set history save
@item set history save
@itemx set history save on
@code{HISTSIZE}, or to 256 if this variable is not set.
@end table
-@cindex history expansion
History expansion assigns special meaning to the character @kbd{!}.
-@ifset have-readline-appendices
-@xref{Event Designators}.
-@end ifset
+@xref{Event Designators}, for more details.
+@cindex history expansion, turn on/off
Since @kbd{!} is also the logical not operator in C, history expansion
is off by default. If you decide to enable history expansion with the
@code{set history expansion on} command, you may sometimes need to
The commands to control history expansion are:
@table @code
-@kindex set history expansion
@item set history expansion on
@itemx set history expansion
+@kindex set history expansion
Enable history expansion. History expansion is off by default.
@item set history expansion off
Disable history expansion.
-The readline code comes with more complete documentation of
-editing and history expansion features. Users unfamiliar with @sc{gnu} Emacs
-or @code{vi} may wish to read it.
-@ifset have-readline-appendices
-@xref{Command Line Editing}.
-@end ifset
-
@c @group
@kindex show history
@item show history
@end table
@table @code
-@kindex shows
+@kindex show commands
+@cindex show last commands
+@cindex display command history
@item show commands
Display the last ten commands in the command history.
Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
from wrapping its output.
+
+@item set pagination on
+@itemx set pagination off
+@kindex set pagination
+Turn the output pagination on or off; the default is on. Turning
+pagination off is the alternative to @code{set height 0}.
+
+@item show pagination
+@kindex show pagination
+Show the current pagination mode.
@end table
@node Numbers
example, any of
@smallexample
-set radix 012
-set radix 10.
-set radix 0xa
+set input-radix 012
+set input-radix 10.
+set input-radix 0xa
@end smallexample
@noindent
-sets the base to decimal. On the other hand, @samp{set radix 10}
-leaves the radix unchanged no matter what it was.
+sets the input base to decimal. On the other hand, @samp{set input-radix 10}
+leaves the input radix unchanged, no matter what it was.
@kindex set output-radix
@item set output-radix @var{base}
@kindex show output-radix
@item show output-radix
Display the current default base for numeric display.
+
+@item set radix @r{[}@var{base}@r{]}
+@itemx show radix
+@kindex set radix
+@kindex show radix
+These commands set and show the default base for both input and output
+of numbers. @code{set radix} sets the radix of input and output to
+the same base; without an argument, it resets the radix back to its
+default value of 10.
+
@end table
@node ABI
@kindex show osabi
One @value{GDBN} configuration can debug binaries for multiple operating
-system targets, either via remote debugging or native emulation.
+system targets, either via remote debugging or native emulation.
@value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use,
but you can override its conclusion using the @code{set osabi} command.
One example where this is useful is in debugging of binaries which use
@end table
@cindex float promotion
-@kindex set coerce-float-to-double
Generally, the way that an argument of type @code{float} is passed to a
function depends on whether the function is prototyped. For a prototyped
as prototyped, it consults @kbd{set coerce-float-to-double}.
@table @code
+@kindex set coerce-float-to-double
@item set coerce-float-to-double
@itemx set coerce-float-to-double on
Arguments of type @code{float} will be promoted to @code{double} when passed
@item set coerce-float-to-double off
Arguments of type @code{float} will be passed directly to unprototyped
functions.
+
+@kindex show coerce-float-to-double
+@item show coerce-float-to-double
+Show the current setting of promoting @code{float} to @code{double}.
@end table
@kindex set cp-abi
@node Messages/Warnings
@section Optional warnings and messages
+@cindex verbose operation
+@cindex optional warnings
By default, @value{GDBN} is silent about its inner workings. If you are
running on a slow machine, you may want to use the @code{set verbose}
command. This makes @value{GDBN} tell you when it does a lengthy
@node Debugging Output
@section Optional messages about internal happenings
+@cindex optional debugging messages
+
+@value{GDBN} has commands that enable optional debugging messages from
+various @value{GDBN} subsystems; normally these commands are of
+interest to @value{GDBN} maintainers, or when reporting a bug. This
+section documents those commands.
+
@table @code
-@kindex set debug arch
+@kindex set exec-done-display
+@item set exec-done-display
+Turns on or off the notification of asynchronous commands'
+completion. When on, @value{GDBN} will print a message when an
+asynchronous command finishes its execution. The default is off.
+@kindex show exec-done-display
+@item show exec-done-display
+Displays the current setting of asynchronous command completion
+notification.
+@kindex set debug
+@cindex gdbarch debugging info
+@cindex architecture debugging info
@item set debug arch
-Turns on or off display of gdbarch debugging info. The default is off
-@kindex show debug arch
+Turns on or off display of gdbarch debugging info. The default is off
+@kindex show debug
@item show debug arch
Displays the current state of displaying gdbarch debugging info.
-@kindex set debug event
+@item set debug aix-thread
+@cindex AIX threads
+Display debugging messages about inner workings of the AIX thread
+module.
+@item show debug aix-thread
+Show the current state of AIX thread debugging info display.
@item set debug event
-Turns on or off display of @value{GDBN} event debugging info. The
+@cindex event debugging info
+Turns on or off display of @value{GDBN} event debugging info. The
default is off.
-@kindex show debug event
@item show debug event
Displays the current state of displaying @value{GDBN} event debugging
info.
-@kindex set debug expression
@item set debug expression
-Turns on or off display of @value{GDBN} expression debugging info. The
-default is off.
-@kindex show debug expression
+@cindex expression debugging info
+Turns on or off display of debugging info about @value{GDBN}
+expression parsing. The default is off.
@item show debug expression
-Displays the current state of displaying @value{GDBN} expression
-debugging info.
-@kindex set debug frame
+Displays the current state of displaying debugging info about
+@value{GDBN} expression parsing.
@item set debug frame
+@cindex frame debugging info
Turns on or off display of @value{GDBN} frame debugging info. The
default is off.
-@kindex show debug frame
@item show debug frame
Displays the current state of displaying @value{GDBN} frame debugging
info.
-@kindex set debug overload
+@item set debug infrun
+@cindex inferior debugging info
+Turns on or off display of @value{GDBN} debugging info for running the inferior.
+The default is off. @file{infrun.c} contains GDB's runtime state machine used
+for implementing operations such as single-stepping the inferior.
+@item show debug infrun
+Displays the current state of @value{GDBN} inferior debugging.
+@item set debug lin-lwp
+@cindex @sc{gnu}/Linux LWP debug messages
+@cindex Linux lightweight processes
+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 observer
+@cindex observer debugging info
+Turns on or off display of @value{GDBN} observer debugging. This
+includes info such as the notification of observable events.
+@item show debug observer
+Displays the current state of observer debugging.
@item set debug overload
+@cindex C@t{++} overload debugging info
Turns on or off display of @value{GDBN} C@t{++} overload debugging
info. This includes info such as ranking of functions, etc. The default
is off.
-@kindex show debug overload
@item show debug overload
Displays the current state of displaying @value{GDBN} C@t{++} overload
debugging info.
-@kindex set debug remote
@cindex packets, reporting on stdout
@cindex serial connections, debugging
@item set debug remote
Turns on or off display of reports on all packets sent back and forth across
the serial line to the remote machine. The info is printed on the
@value{GDBN} standard output stream. The default is off.
-@kindex show debug remote
@item show debug remote
Displays the state of display of remote packets.
-@kindex set debug serial
@item set debug serial
Turns on or off display of @value{GDBN} serial debugging info. The
default is off.
-@kindex show debug serial
@item show debug serial
Displays the current state of displaying @value{GDBN} serial debugging
info.
-@kindex set debug target
@item set debug target
+@cindex target debugging info
Turns on or off display of @value{GDBN} target debugging info. This info
includes what is going on at the target level of GDB, as it happens. The
-default is off.
-@kindex show debug target
+default is 0. Set it to 1 to track events, and to 2 to also track the
+value of large memory transfers. Changes to this flag do not take effect
+until the next time you connect to a target or use the @code{run} command.
@item show debug target
Displays the current state of displaying @value{GDBN} target debugging
info.
-@kindex set debug varobj
@item set debug varobj
+@cindex variable object debugging info
Turns on or off display of @value{GDBN} variable object debugging
info. The default is off.
-@kindex show debug varobj
@item show debug varobj
Displays the current state of displaying @value{GDBN} variable object
debugging info.
@kindex if
@kindex else
@item if
+@itemx else
Takes a single argument, which is an expression to evaluate.
It is followed by a series of commands that are executed
only if the expression is true (nonzero).
not its documentation). If no @var{commandname} is given, display the
definitions for all user-defined commands.
+@cindex infinite recusrion in user-defined commands
@kindex show max-user-call-depth
@kindex set max-user-call-depth
@item show max-user-call-depth
@cindex hooks, pre-command
@kindex hook
-@kindex hook-
You may define @dfn{hooks}, which are a special kind of user-defined
command. Whenever you run the command @samp{foo}, if the user-defined
command @samp{hook-foo} exists, it is executed (with no arguments)
@cindex hooks, post-command
@kindex hookpost
-@kindex hookpost-
A hook may also be defined which is run after the command you executed.
Whenever you run the command @samp{foo}, if the user-defined command
@samp{hookpost-foo} exists, it is executed (with no arguments) after
pre-execution hooks, for the same command.
It is valid for a hook to call the command which it hooks. If this
-occurs, the hook is not re-executed, thereby avoiding infinte recursion.
+occurs, the hook is not re-executed, thereby avoiding infinite recursion.
@c It would be nice if hookpost could be passed a parameter indicating
@c if the command it hooks executed properly or not. FIXME!
@end smallexample
As a further example, to hook at the begining and end of the @code{echo}
-command, and to add extra text to the beginning and end of the message,
+command, and to add extra text to the beginning and end of the message,
you could define:
@smallexample
@node TUI
@chapter @value{GDBN} Text User Interface
@cindex TUI
+@cindex Text User Interface
@menu
* TUI Overview:: TUI overview
* TUI Configuration:: TUI configuration variables
@end menu
-The @value{GDBN} Text User Interface, TUI in short,
-is a terminal interface which uses the @code{curses} library
-to show the source file, the assembly output, the program registers
-and @value{GDBN} commands in separate text windows.
-The TUI is available only when @value{GDBN} is configured
-with the @code{--enable-tui} configure option (@pxref{Configure Options}).
+The @value{GDBN} Text User Interface, TUI in short, is a terminal
+interface which uses the @code{curses} library to show the source
+file, the assembly output, the program registers and @value{GDBN}
+commands in separate text windows.
+
+The TUI is enabled by invoking @value{GDBN} using either
+@pindex gdbtui
+@samp{gdbtui} or @samp{gdb -tui}.
@node TUI Overview
@section TUI overview
@item register
This window shows the processor registers. It detects when
a register is changed and when this is the case, registers that have
-changed are highlighted.
+changed are highlighted.
@end table
Think of it as the Emacs @kbd{C-x 2} binding.
+@kindex C-x o
+@item C-x o
+Change the active window. The TUI associates several key bindings
+(like scrolling and arrow keys) to the active window. This command
+gives the focus to the next TUI window.
+
+Think of it as the Emacs @kbd{C-x o} binding.
+
@kindex C-x s
@item C-x s
Use the TUI @emph{SingleKey} keymap that binds single key to gdb commands
@end table
In the TUI mode, the arrow keys are used by the active window
-for scrolling. This means they are not available for readline. It is
-necessary to use other readline key bindings such as @key{C-p}, @key{C-n},
-@key{C-b} and @key{C-f}.
+for scrolling. This means they are available for readline when the
+active window is the command window. When the command window
+does not have the focus, it is necessary to use other readline
+key bindings such as @key{C-p}, @key{C-n}, @key{C-b} and @key{C-f}.
@node TUI Single Key Mode
@section TUI Single Key Mode
The TUI provides a @emph{SingleKey} mode in which it installs a particular
key binding in the readline keymaps to connect single keys to
-some gdb commands.
+some gdb commands.
@table @kbd
@kindex c @r{(SingleKey TUI key)}
List and give the size of all displayed windows.
@item layout next
-@kindex layout next
+@kindex layout
Display the next layout.
@item layout prev
-@kindex layout prev
Display the previous layout.
@item layout src
-@kindex layout src
Display the source window only.
@item layout asm
-@kindex layout asm
Display the assembly window only.
@item layout split
-@kindex layout split
Display the source and assembly window.
@item layout regs
-@kindex layout regs
Display the register window together with the source or assembly window.
@item focus next | prev | src | asm | regs | split
@kindex refresh
Refresh the screen. This is similar to using @key{C-L} key.
+@item tui reg float
+@kindex tui reg
+Show the floating point registers in the register window.
+
+@item tui reg general
+Show the general registers in the register window.
+
+@item tui reg next
+Show the next register group. The list of register groups as well as
+their order is target specific. The predefined register groups are the
+following: @code{general}, @code{float}, @code{system}, @code{vector},
+@code{all}, @code{save}, @code{restore}.
+
+@item tui reg system
+Show the system registers in the register window.
+
@item update
@kindex update
Update the source window and the current execution point.
Explicit @value{GDBN} @code{list} or search commands still produce output as
usual, but you probably have no reason to use them from Emacs.
-@quotation
-@emph{Warning:} If the directory where your program resides is not your
-current directory, it can be easy to confuse Emacs about the location of
-the source files, in which case the auxiliary display buffer does not
-appear to show your source. @value{GDBN} can find programs by searching your
-environment's @code{PATH} variable, so the @value{GDBN} input and output
-session proceeds normally; but Emacs does not get enough information
-back from @value{GDBN} to locate the source files in this situation. To
-avoid this problem, either start @value{GDBN} mode from the directory where
-your program resides, or specify an absolute file name when prompted for the
-@kbd{M-x gdb} argument.
-
-A similar confusion can result if you use the @value{GDBN} @code{file} command to
-switch to debugging a program in some other location, from an existing
-@value{GDBN} buffer in Emacs.
-@end quotation
-
-By default, @kbd{M-x gdb} calls the program called @file{gdb}. If
-you need to call @value{GDBN} by a different name (for example, if you keep
-several configurations around, with different names) you can set the
-Emacs variable @code{gdb-command-name}; for example,
-
-@smallexample
-(setq gdb-command-name "mygdb")
-@end smallexample
-
-@noindent
-(preceded by @kbd{M-:} or @kbd{ESC :}, or typed in the @code{*scratch*} buffer, or
-in your @file{.emacs} file) makes Emacs call the program named
-``@code{mygdb}'' instead.
+If you specify an absolute file name when prompted for the @kbd{M-x
+gdb} argument, then Emacs sets your current working directory to where
+your program resides. If you only specify the file name, then Emacs
+sets your current working directory to to the directory associated
+with the previous buffer. In this case, @value{GDBN} may find your
+program by searching your environment's @code{PATH} variable, but on
+some operating systems it might not find the source. So, although the
+@value{GDBN} input and output session proceeds normally, the auxiliary
+buffer does not display the current source and line of execution.
+
+The initial working directory of @value{GDBN} is printed on the top
+line of the @value{GDBN} I/O buffer and this serves as a default for
+the commands that specify files for @value{GDBN} to operate
+on. @xref{Files, ,Commands to specify files}.
+
+By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you
+need to call @value{GDBN} by a different name (for example, if you
+keep several configurations around, with different names) you can
+customize the Emacs variable @code{gud-gdb-command-name} to run the
+one you want.
In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
addition to the standard Shell mode commands:
@item C-h m
Describe the features of Emacs' @value{GDBN} Mode.
-@item M-s
+@item C-c C-s
Execute to another source line, like the @value{GDBN} @code{step} command; also
update the display window to show the current file and location.
-@item M-n
+@item C-c C-n
Execute to next source line in this function, skipping all function
calls, like the @value{GDBN} @code{next} command. Then update the display window
to show the current file and location.
-@item M-i
+@item C-c C-i
Execute one instruction, like the @value{GDBN} @code{stepi} command; update
display window accordingly.
-@item M-x gdb-nexti
-Execute to next instruction, using the @value{GDBN} @code{nexti} command; update
-display window accordingly.
-
@item C-c C-f
Execute until exit from the selected stack frame, like the @value{GDBN}
@code{finish} command.
-@item M-c
+@item C-c C-r
Continue execution of your program, like the @value{GDBN} @code{continue}
command.
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
-
-@item M-u
+@item C-c <
Go up the number of frames indicated by the numeric argument
(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}),
like the @value{GDBN} @code{up} command.
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
-
-@item M-d
+@item C-c >
Go down the number of frames indicated by the numeric argument, like the
@value{GDBN} @code{down} command.
-
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
-
-@item C-x &
-Read the number where the cursor is positioned, and insert it at the end
-of the @value{GDBN} I/O buffer. For example, if you wish to disassemble code
-around an address that was displayed earlier, type @kbd{disassemble};
-then move the cursor to the address display, and pick up the
-argument for @code{disassemble} by typing @kbd{C-x &}.
-
-You can customize this further by defining elements of the list
-@code{gdb-print-command}; once it is defined, you can format or
-otherwise process numbers picked up by @kbd{C-x &} before they are
-inserted. A numeric argument to @kbd{C-x &} indicates that you
-wish special formatting, and also acts as an index to pick an element of the
-list. If the list element is a string, the number to be inserted is
-formatted using the Emacs function @code{format}; otherwise the number
-is passed as an argument to the corresponding list element.
@end table
-In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
+In any source file, the Emacs command @kbd{C-x SPC} (@code{gud-break})
tells @value{GDBN} to set a breakpoint on the source line point is on.
+If you type @kbd{M-x speedbar}, then Emacs displays a separate frame which
+shows a backtrace when the @value{GDBN} I/O buffer is current. Move
+point to any frame in the stack and type @key{RET} to make it become the
+current frame and display the associated source in the source buffer.
+Alternatively, click @kbd{Mouse-2} to make the selected frame become the
+current one.
+
If you accidentally delete the source-display buffer, an easy way to get
it back is to type the command @code{f} in the @value{GDBN} buffer, to
request a frame display; when you run under Emacs, this recreates
delete lines from the text, the line numbers that @value{GDBN} knows cease
to correspond properly with the code.
+The description given here is for GNU Emacs version 21.3 and a more
+detailed description of its interaction with @value{GDBN} is given in
+the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} Emacs Manual}).
+
@c The following dropped because Epoch is nonstandard. Reactivate
@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
@ignore
@table @code
@item @var{output} @expansion{}
-@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
+@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(@value{GDBP})" @var{nl}}
@item @var{result-record} @expansion{}
@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
Add directories @var{pathdir} to beginning of search path for source files.
If the @samp{-r} option is used, the search path is reset to the default
-search path. If directories @var{pathdir} are supplied in addition to the
+search path. If directories @var{pathdir} are supplied in addition to the
@samp{-r} option, the search path is first reset and then addition
occurs as normal.
-Multiple directories may be specified, separated by blanks. Specifying
+Multiple directories may be specified, separated by blanks. Specifying
multiple directories in a single command
results in the directories added to the beginning of the
search path in the same order they were presented in the command.
If blanks are needed as
part of a directory name, double-quotes should be used around
the name. In the command output, the path will show up separated
-by the system directory-separator character. The directory-seperator
+by the system directory-separator character. The directory-seperator
character must not be used
in any directory name.
If no directories are specified, the current search path is displayed.
Add directories @var{pathdir} to beginning of search path for object files.
If the @samp{-r} option is used, the search path is reset to the original
-search path that existed at gdb start-up. If directories @var{pathdir} are
-supplied in addition to the
+search path that existed at gdb start-up. If directories @var{pathdir} are
+supplied in addition to the
@samp{-r} option, the search path is first reset and then addition
occurs as normal.
-Multiple directories may be specified, separated by blanks. Specifying
+Multiple directories may be specified, separated by blanks. Specifying
multiple directories in a single command
results in the directories added to the beginning of the
search path in the same order they were presented in the command.
If blanks are needed as
part of a directory name, double-quotes should be used around
the name. In the command output, the path will show up separated
-by the system directory-separator character. The directory-seperator
+by the system directory-separator character. The directory-seperator
character must not be used
in any directory name.
If no directories are specified, the current path is displayed.
@smallexample
(@value{GDBP})
--environment-path
+-environment-path
^done,path="/usr/bin"
(@value{GDBP})
-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
-file-list-exec-source-file
@end smallexample
-List the line number, the current source file, and the absolute path
+List the line number, the current source file, and the absolute path
to the current source file for the current executable.
@subsubheading @value{GDBN} Command
List the source files for the current executable.
+It will always output the filename, but only when GDB can find the absolute
+file name of a source file, will it output the fullname.
+
@subsubheading @value{GDBN} Command
There's no @value{GDBN} command which directly corresponds to this one.
@code{gdbtk} has an analogous command @samp{gdb_listfiles}.
@subsubheading Example
-N.A.
-
+@smallexample
+(@value{GDBP})
+-file-list-exec-source-files
+^done,files=[
+@{file=foo.c,fullname=/home/foo.c@},
+@{file=/home/bar.c,fullname=/home/bar.c@},
+@{file=gdb_could_not_find_fullpath.c@}]
+(@value{GDBP})
+@end smallexample
@subheading The @code{-file-list-shared-libraries} Command
@findex -file-list-shared-libraries
~Type "show copying" to see the conditions.
~There is absolutely no warranty for GDB. Type "show warranty" for
~ details.
-~This GDB was configured as
+~This GDB was configured as
"--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
^done
(@value{GDBP})
@end smallexample
Display the local variable names for the current frame. With an
-argument of 0 prints only the names of the variables, with argument of 1
-prints also their values.
+argument of 0 or @code{--no-values}, prints only the names of the variables.
+With argument of 1 or @code{--all-values}, prints also their values. With
+argument of 2 or @code{--simple-values}, prints the name, type and value for
+simple data types and the name and type for arrays, structures and
+unions. In this last case, the idea is that the user can see the
+value of simple data types immediately and he can create variable
+objects for other data types if he wishes to explore their values in
+more detail.
@subsubheading @value{GDBN} Command
-stack-list-locals 0
^done,locals=[name="A",name="B",name="C"]
(@value{GDBP})
--stack-list-locals 1
+-stack-list-locals --all-values
^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
- @{name="C",value="3"@}]
+ @{name="C",value="@{1, 2, 3@}"@}]
+-stack-list-locals --simple-values
+^done,locals=[@{name="A",type="int",value="1"@},
+ @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}]
(@value{GDBP})
@end smallexample
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} comamnd is @samp{info line}.
+The corresponding @value{GDBN} command is @samp{info line}.
@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
@subsubheading Example
@smallexample
(@value{GDBP})
-symbol-list-lines basics.c
-^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}]
+^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}]
(@value{GDBP})
@end smallexample
@subsubheading @value{GDBN} command
-The corresponding @value{GDBN} command is @samp{detach}.
+The corresponding @value{GDBN} command is @samp{detach}.
+
+@subsubheading Example
+
+@smallexample
+(@value{GDBP})
+-target-detach
+^done
+(@value{GDBP})
+@end smallexample
+
+
+@subheading The @code{-target-disconnect} Command
+@findex -target-disconnect
+
+@subsubheading Synopsis
+
+@example
+ -target-disconnect
+@end example
+
+Disconnect from the remote target. There's no output.
+
+@subsubheading @value{GDBN} command
+
+The corresponding @value{GDBN} command is @samp{disconnect}.
@subsubheading Example
@smallexample
(@value{GDBP})
--target-detach
+-target-disconnect
^done
(@value{GDBP})
@end smallexample
@subsubheading Synopsis
@smallexample
- -var-list-children @var{name}
+ -var-list-children [@var{print-values}] @var{name}
@end smallexample
-Returns a list of the children of the specified variable object:
+Returns a list of the children of the specified variable object. With
+just the variable object name as an argument or with an optional
+preceding argument of 0 or @code{--no-values}, prints only the names of the
+variables. With an optional preceding argument of 1 or @code{--all-values},
+also prints their values.
+
+@subsubheading Example
@smallexample
+(@value{GDBP})
+ -var-list-children n
numchild=@var{n},children=[@{name=@var{name},
numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
+(@value{GDBP})
+ -var-list-children --all-values n
+ numchild=@var{n},children=[@{name=@var{name},
+ numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
@end smallexample
Assigns the value of @var{expression} to the variable object specified
by @var{name}. The object must be @samp{editable}. If the variable's
-value is altered by the assign, the variable will show up in any
+value is altered by the assign, the variable will show up in any
subsequent @code{-var-update} list.
@subsubheading Example
@node Annotations
@chapter @value{GDBN} Annotations
-This chapter describes annotations in @value{GDBN}. Annotations are
-designed to interface @value{GDBN} to graphical user interfaces or
-other similar programs which want to interact with @value{GDBN} at a
+This chapter describes annotations in @value{GDBN}. Annotations were
+designed to interface @value{GDBN} to graphical user interfaces or other
+similar programs which want to interact with @value{GDBN} at a
relatively high level.
+The annotation mechanism has largely been superseeded by @sc{gdb/mi}
+(@pxref{GDB/MI}).
+
@ignore
This is Edition @value{EDITION}, @value{DATE}.
@end ignore
@menu
* Annotations Overview:: What annotations are; the general syntax.
* Server Prefix:: Issuing a command without affecting user state.
-* Value Annotations:: Values are marked as such.
-* Frame Annotations:: Stack frames are annotated.
-* Displays:: @value{GDBN} can be told to display something periodically.
* Prompting:: Annotations marking @value{GDBN}'s need for input.
* Errors:: Annotations for error messages.
-* Breakpoint Info:: Information on breakpoints.
* Invalidation:: Some annotations describe things now invalid.
* Annotations for Running::
Whether the program is running, how it stopped, etc.
* Source Annotations:: Annotations describing source code.
-* TODO:: Annotations which might be added in the future.
@end menu
@node Annotations Overview
@section What is an Annotation?
@cindex annotations
-To produce annotations, start @value{GDBN} with the @code{--annotate=2} option.
-
Annotations start with a newline character, two @samp{control-z}
characters, and the name of the annotation. If there is no additional
information associated with this annotation, the name of the annotation
annotations could be extended with an @samp{escape} annotation which
means those three characters as output.
+The annotation @var{level}, which is specified using the
+@option{--annotate} command line option (@pxref{Mode Options}), controls
+how much information @value{GDBN} prints together with its prompt,
+values of expressions, source lines, and other types of output. Level 0
+is for no anntations, level 1 is for use when @value{GDBN} is run as a
+subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable
+for programs that control @value{GDBN}, and level 2 annotations have
+been made obsolete (@pxref{Limitations, , Limitations of the Annotation
+Interface, annotate, GDB's Obsolete Annotations}).
+
+@table @code
+@kindex set annotate
+@item set annotate @var{level}
+The @value{GDB} command @code{set annotate} sets the level of
+annotations to the specified @var{level}.
+
+@item show annotate
+@kindex show annotate
+Show the current annotation level.
+@end table
+
+This chapter describes level 3 annotations.
+
A simple example of starting up @value{GDBN} with annotations is:
@smallexample
-$ gdb --annotate=2
-GNU GDB 5.0
-Copyright 2000 Free Software Foundation, Inc.
+$ @kbd{gdb --annotate=3}
+GNU gdb 6.0
+Copyright 2003 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License,
and you are welcome to change it and/or distribute copies of it
under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty"
for details.
-This GDB was configured as "sparc-sun-sunos4.1.3"
+This GDB was configured as "i386-pc-linux-gnu"
^Z^Zpre-prompt
-(gdb)
+(@value{GDBP})
^Z^Zprompt
-quit
+@kbd{quit}
^Z^Zpost-prompt
-$
+$
@end smallexample
Here @samp{quit} is input to @value{GDBN}; the rest is output from
history; to print a value without recording it into the value history,
use the @code{output} command instead of the @code{print} command.
-@node Value Annotations
-@section Values
-
-@cindex annotations for values
-When a value is printed in various contexts, @value{GDBN} uses
-annotations to delimit the value from the surrounding text.
-
-@findex value-history-begin
-@findex value-history-value
-@findex value-history-end
-If a value is printed using @code{print} and added to the value history,
-the annotation looks like
-
-@smallexample
-^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
-@var{history-string}
-^Z^Zvalue-history-value
-@var{the-value}
-^Z^Zvalue-history-end
-@end smallexample
-
-@noindent
-where @var{history-number} is the number it is getting in the value
-history, @var{history-string} is a string, such as @samp{$5 = }, which
-introduces the value to the user, @var{the-value} is the output
-corresponding to the value itself, and @var{value-flags} is @samp{*} for
-a value which can be dereferenced and @samp{-} for a value which cannot.
-
-@findex value-begin
-@findex value-end
-If the value is not added to the value history (it is an invalid float
-or it is printed with the @code{output} command), the annotation is similar:
-
-@smallexample
-^Z^Zvalue-begin @var{value-flags}
-@var{the-value}
-^Z^Zvalue-end
-@end smallexample
-
-@findex arg-begin
-@findex arg-name-end
-@findex arg-value
-@findex arg-end
-When @value{GDBN} prints an argument to a function (for example, in the output
-from the @code{backtrace} command), it annotates it as follows:
-
-@smallexample
-^Z^Zarg-begin
-@var{argument-name}
-^Z^Zarg-name-end
-@var{separator-string}
-^Z^Zarg-value @var{value-flags}
-@var{the-value}
-^Z^Zarg-end
-@end smallexample
-
-@noindent
-where @var{argument-name} is the name of the argument,
-@var{separator-string} is text which separates the name from the value
-for the user's benefit (such as @samp{=}), and @var{value-flags} and
-@var{the-value} have the same meanings as in a
-@code{value-history-begin} annotation.
-
-@findex field-begin
-@findex field-name-end
-@findex field-value
-@findex field-end
-When printing a structure, @value{GDBN} annotates it as follows:
-
-@smallexample
-^Z^Zfield-begin @var{value-flags}
-@var{field-name}
-^Z^Zfield-name-end
-@var{separator-string}
-^Z^Zfield-value
-@var{the-value}
-^Z^Zfield-end
-@end smallexample
-
-@noindent
-where @var{field-name} is the name of the field, @var{separator-string}
-is text which separates the name from the value for the user's benefit
-(such as @samp{=}), and @var{value-flags} and @var{the-value} have the
-same meanings as in a @code{value-history-begin} annotation.
-
-When printing an array, @value{GDBN} annotates it as follows:
-
-@smallexample
-^Z^Zarray-section-begin @var{array-index} @var{value-flags}
-@end smallexample
-
-@noindent
-where @var{array-index} is the index of the first element being
-annotated and @var{value-flags} has the same meaning as in a
-@code{value-history-begin} annotation. This is followed by any number
-of elements, where is element can be either a single element:
-
-@findex elt
-@smallexample
-@samp{,} @var{whitespace} ; @r{omitted for the first element}
-@var{the-value}
-^Z^Zelt
-@end smallexample
-
-or a repeated element
-
-@findex elt-rep
-@findex elt-rep-end
-@smallexample
-@samp{,} @var{whitespace} ; @r{omitted for the first element}
-@var{the-value}
-^Z^Zelt-rep @var{number-of-repetitions}
-@var{repetition-string}
-^Z^Zelt-rep-end
-@end smallexample
-
-In both cases, @var{the-value} is the output for the value of the
-element and @var{whitespace} can contain spaces, tabs, and newlines. In
-the repeated case, @var{number-of-repetitions} is the number of
-consecutive array elements which contain that value, and
-@var{repetition-string} is a string which is designed to convey to the
-user that repetition is being depicted.
-
-@findex array-section-end
-Once all the array elements have been output, the array annotation is
-ended with
-
-@smallexample
-^Z^Zarray-section-end
-@end smallexample
-
-@node Frame Annotations
-@section Frames
-
-@cindex annotations for frames
-Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies
-to frames printed when @value{GDBN} stops, output from commands such as
-@code{backtrace} or @code{up}, etc.
-
-@findex frame-begin
-The frame annotation begins with
-
-@smallexample
-^Z^Zframe-begin @var{level} @var{address}
-@var{level-string}
-@end smallexample
-
-@noindent
-where @var{level} is the number of the frame (0 is the innermost frame,
-and other frames have positive numbers), @var{address} is the address of
-the code executing in that frame, and @var{level-string} is a string
-designed to convey the level to the user. @var{address} is in the form
-@samp{0x} followed by one or more lowercase hex digits (note that this
-does not depend on the language). The frame ends with
-
-@findex frame-end
-@smallexample
-^Z^Zframe-end
-@end smallexample
-
-Between these annotations is the main body of the frame, which can
-consist of
-
-@itemize @bullet
-@item
-@findex function-call
-@smallexample
-^Z^Zfunction-call
-@var{function-call-string}
-@end smallexample
-
-where @var{function-call-string} is text designed to convey to the user
-that this frame is associated with a function call made by @value{GDBN} to a
-function in the program being debugged.
-
-@item
-@findex signal-handler-caller
-@smallexample
-^Z^Zsignal-handler-caller
-@var{signal-handler-caller-string}
-@end smallexample
-
-where @var{signal-handler-caller-string} is text designed to convey to
-the user that this frame is associated with whatever mechanism is used
-by this operating system to call a signal handler (it is the frame which
-calls the signal handler, not the frame for the signal handler itself).
-
-@item
-A normal frame.
-
-@findex frame-address
-@findex frame-address-end
-This can optionally (depending on whether this is thought of as
-interesting information for the user to see) begin with
-
-@smallexample
-^Z^Zframe-address
-@var{address}
-^Z^Zframe-address-end
-@var{separator-string}
-@end smallexample
-
-where @var{address} is the address executing in the frame (the same
-address as in the @code{frame-begin} annotation, but printed in a form
-which is intended for user consumption---in particular, the syntax varies
-depending on the language), and @var{separator-string} is a string
-intended to separate this address from what follows for the user's
-benefit.
-
-@findex frame-function-name
-@findex frame-args
-Then comes
-
-@smallexample
-^Z^Zframe-function-name
-@var{function-name}
-^Z^Zframe-args
-@var{arguments}
-@end smallexample
-
-where @var{function-name} is the name of the function executing in the
-frame, or @samp{??} if not known, and @var{arguments} are the arguments
-to the frame, with parentheses around them (each argument is annotated
-individually as well, @pxref{Value Annotations}).
-
-@findex frame-source-begin
-@findex frame-source-file
-@findex frame-source-file-end
-@findex frame-source-line
-@findex frame-source-end
-If source information is available, a reference to it is then printed:
-
-@smallexample
-^Z^Zframe-source-begin
-@var{source-intro-string}
-^Z^Zframe-source-file
-@var{filename}
-^Z^Zframe-source-file-end
-:
-^Z^Zframe-source-line
-@var{line-number}
-^Z^Zframe-source-end
-@end smallexample
-
-where @var{source-intro-string} separates for the user's benefit the
-reference from the text which precedes it, @var{filename} is the name of
-the source file, and @var{line-number} is the line number within that
-file (the first line is line 1).
-
-@findex frame-where
-If @value{GDBN} prints some information about where the frame is from (which
-library, which load segment, etc.; currently only done on the RS/6000),
-it is annotated with
-
-@smallexample
-^Z^Zframe-where
-@var{information}
-@end smallexample
-
-Then, if source is to actually be displayed for this frame (for example,
-this is not true for output from the @code{backtrace} command), then a
-@code{source} annotation (@pxref{Source Annotations}) is displayed. Unlike
-most annotations, this is output instead of the normal text which would be
-output, not in addition.
-@end itemize
-
-@node Displays
-@section Displays
-
-@findex display-begin
-@findex display-number-end
-@findex display-format
-@findex display-expression
-@findex display-expression-end
-@findex display-value
-@findex display-end
-@cindex annotations for display
-When @value{GDBN} is told to display something using the @code{display} command,
-the results of the display are annotated:
-
-@smallexample
-^Z^Zdisplay-begin
-@var{number}
-^Z^Zdisplay-number-end
-@var{number-separator}
-^Z^Zdisplay-format
-@var{format}
-^Z^Zdisplay-expression
-@var{expression}
-^Z^Zdisplay-expression-end
-@var{expression-separator}
-^Z^Zdisplay-value
-@var{value}
-^Z^Zdisplay-end
-@end smallexample
-
-@noindent
-where @var{number} is the number of the display, @var{number-separator}
-is intended to separate the number from what follows for the user,
-@var{format} includes information such as the size, format, or other
-information about how the value is being displayed, @var{expression} is
-the expression being displayed, @var{expression-separator} is intended
-to separate the expression from the text that follows for the user,
-and @var{value} is the actual value being displayed.
-
@node Prompting
@section Annotation for @value{GDBN} Input
@c If we want to change that, need to fix warning(), type_error(),
@c range_error(), and possibly other places.
-@node Breakpoint Info
-@section Information on Breakpoints
-
-@cindex annotations for breakpoints
-The output from the @code{info breakpoints} command is annotated as follows:
-
-@findex breakpoints-headers
-@findex breakpoints-table
-@smallexample
-^Z^Zbreakpoints-headers
-@var{header-entry}
-^Z^Zbreakpoints-table
-@end smallexample
-
-@noindent
-where @var{header-entry} has the same syntax as an entry (see below) but
-instead of containing data, it contains strings which are intended to
-convey the meaning of each field to the user. This is followed by any
-number of entries. If a field does not apply for this entry, it is
-omitted. Fields may contain trailing whitespace. Each entry consists
-of:
-
-@findex record
-@findex field
-@smallexample
-^Z^Zrecord
-^Z^Zfield 0
-@var{number}
-^Z^Zfield 1
-@var{type}
-^Z^Zfield 2
-@var{disposition}
-^Z^Zfield 3
-@var{enable}
-^Z^Zfield 4
-@var{address}
-^Z^Zfield 5
-@var{what}
-^Z^Zfield 6
-@var{frame}
-^Z^Zfield 7
-@var{condition}
-^Z^Zfield 8
-@var{ignore-count}
-^Z^Zfield 9
-@var{commands}
-@end smallexample
-
-Note that @var{address} is intended for user consumption---the syntax
-varies depending on the language.
-
-The output ends with
-
-@findex breakpoints-table-end
-@smallexample
-^Z^Zbreakpoints-table-end
-@end smallexample
-
@node Invalidation
@section Invalidation Notices
@findex starting
@findex stopping
When the program starts executing due to a @value{GDBN} command such as
-@code{step} or @code{continue},
+@code{step} or @code{continue},
@smallexample
^Z^Zstarting
@end smallexample
-is output. When the program stops,
+is output. When the program stops,
@smallexample
^Z^Zstopped
followed by one or more lowercase hex digits (note that this does not
depend on the language).
-@node TODO
-@section Annotations We Might Want in the Future
-
-@format
- - target-invalid
- the target might have changed (registers, heap contents, or
- execution status). For performance, we might eventually want
- to hit `registers-invalid' and `all-registers-invalid' with
- greater precision
-
- - systematic annotation for set/show parameters (including
- invalidation notices).
-
- - similarly, `info' returns a list of candidates for invalidation
- notices.
-@end format
-
@node GDB Bugs
@chapter Reporting Bugs in @value{GDBN}
@cindex bugs in @value{GDBN}
us. If you had not told us to expect a crash, then we would not be able
to draw any conclusion from our observations.
+@pindex script
+@cindex recording a session script
+To collect all this information, you can use a session recording program
+such as @command{script}, which is available on many Unix systems.
+Just run your @value{GDBN} session inside @command{script} and then
+include the @file{typescript} file with your bug report.
+
+Another way to record a @value{GDBN} session is to run @value{GDBN}
+inside Emacs and then save the entire buffer to a file.
+
@item
If you wish to suggest changes to the @value{GDBN} source, send us context
diffs. If you even discuss something in the @value{GDBN} source, refer to
@cindex internal commands
In addition to commands intended for @value{GDBN} users, @value{GDBN}
-includes a number of commands intended for @value{GDBN} developers.
-These commands are provided here for reference.
+includes a number of commands intended for @value{GDBN} developers,
+that are not documented elsewhere in this manual. These commands are
+provided here for reference. (For commands that turn on debugging
+messages, see @ref{Debugging Output}.)
@table @code
+@kindex maint agent
+@item maint agent @var{expression}
+Translate the given @var{expression} into remote agent bytecodes.
+This command is useful for debugging the Agent Expression mechanism
+(@pxref{Agent Expressions}).
+
@kindex maint info breakpoints
@item @anchor{maint info breakpoints}maint info breakpoints
Using the same format as @samp{info breakpoints}, display both the
@end table
+@kindex maint check-symtabs
+@item maint check-symtabs
+Check the consistency of psymtabs and symtabs.
+
+@kindex maint cplus first_component
+@item maint cplus first_component @var{name}
+Print the first C@t{++} class/namespace component of @var{name}.
+
+@kindex maint cplus namespace
+@item maint cplus namespace
+Print the list of possible C@t{++} namespaces.
+
+@kindex maint demangle
+@item maint demangle @var{name}
+Demangle a C@t{++} or Objective-C manled @var{name}.
+
+@kindex maint deprecate
+@kindex maint undeprecate
+@cindex deprecated commands
+@item maint deprecate @var{command} @r{[}@var{replacement}@r{]}
+@itemx maint undeprecate @var{command}
+Deprecate or undeprecate the named @var{command}. Deprecated commands
+cause @value{GDBN} to issue a warning when you use them. The optional
+argument @var{replacement} says which newer command should be used in
+favor of the deprecated one; if it is given, @value{GDBN} will mention
+the replacement as part of the warning.
+
+@kindex maint dump-me
+@item maint dump-me
+@cindex @code{SIGQUIT} signal, dump core of @value{GDBN}
+Cause a fatal signal in the debugger and force it to dump its core.
+This is supported only on systems which support aborting a program
+with the @code{SIGQUIT} signal.
+
@kindex maint internal-error
@kindex maint internal-warning
-@item maint internal-error
-@itemx maint internal-warning
+@item maint internal-error @r{[}@var{message-text}@r{]}
+@itemx maint internal-warning @r{[}@var{message-text}@r{]}
Cause @value{GDBN} to call the internal function @code{internal_error}
or @code{internal_warning} and hence behave as though an internal error
or internal warning has been detected. In addition to reporting the
either quit @value{GDBN} or create a core file of the current
@value{GDBN} session.
+These commands take an optional parameter @var{message-text} that is
+used as the text of the error or warning message.
+
+Here's an example of using @code{indernal-error}:
+
@smallexample
-(gdb) @kbd{maint internal-error testing, 1, 2}
+(@value{GDBP}) @kbd{maint internal-error testing, 1, 2}
@dots{}/maint.c:121: internal-error: testing, 1, 2
A problem internal to GDB has been detected. Further
debugging may prove unreliable.
Quit this debugging session? (y or n) @kbd{n}
Create a core file? (y or n) @kbd{n}
-(gdb)
+(@value{GDBP})
+@end smallexample
+
+@kindex maint packet
+@item maint packet @var{text}
+If @value{GDBN} is talking to an inferior via the serial protocol,
+then this command sends the string @var{text} to the inferior, and
+displays the response packet. @value{GDBN} supplies the initial
+@samp{$} character, the terminating @samp{#} character, and the
+checksum.
+
+@kindex maint print architecture
+@item maint print architecture @r{[}@var{file}@r{]}
+Print the entire architecture configuration. The optional argument
+@var{file} names the file where the output goes.
+
+@kindex maint print dummy-frames
+@item maint print dummy-frames
+Prints the contents of @value{GDBN}'s internal dummy-frame stack.
+
+@smallexample
+(@value{GDBP}) @kbd{b add}
+@dots{}
+(@value{GDBP}) @kbd{print add(2,3)}
+Breakpoint 2, add (a=2, b=3) at @dots{}
+58 return (a + b);
+The program being debugged stopped while in a function called from GDB.
+@dots{}
+(@value{GDBP}) @kbd{maint print dummy-frames}
+0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
+ top=0x0200bdd4 id=@{stack=0x200bddc,code=0x101405c@}
+ call_lo=0x01014000 call_hi=0x01014001
+(@value{GDBP})
@end smallexample
-Takes an optional parameter that is used as the text of the error or
-warning message.
+Takes an optional file parameter.
@kindex maint print registers
@kindex maint print raw-registers
@kindex maint print cooked-registers
@kindex maint print register-groups
-@item maint print registers
-@itemx maint print raw-registers
-@itemx maint print cooked-registers
-@itemx maint print register-groups
+@item maint print registers @r{[}@var{file}@r{]}
+@itemx maint print raw-registers @r{[}@var{file}@r{]}
+@itemx maint print cooked-registers @r{[}@var{file}@r{]}
+@itemx maint print register-groups @r{[}@var{file}@r{]}
Print @value{GDBN}'s internal register data structures.
The command @code{maint print raw-registers} includes the contents of
register is a member of. @xref{Registers,, Registers, gdbint,
@value{GDBN} Internals}.
-Takes an optional file parameter.
+These commands take an optional parameter, a file name to which to
+write the information.
@kindex maint print reggroups
-@item maint print reggroups
-Print @value{GDBN}'s internal register group data structures.
-
-Takes an optional file parameter.
+@item maint print reggroups @r{[}@var{file}@r{]}
+Print @value{GDBN}'s internal register group data structures. The
+optional argument @var{file} tells to what file to write the
+information.
-@smallexample
-(gdb) @kbd{maint print reggroups}
- Group Type
- general user
- float user
- all user
- vector user
- system user
- save internal
- restore internal
-@end smallexample
+The register groups info looks like this:
+
+@smallexample
+(@value{GDBP}) @kbd{maint print reggroups}
+ Group Type
+ general user
+ float user
+ all user
+ vector user
+ system user
+ save internal
+ restore internal
+@end smallexample
+
+@kindex flushregs
+@item flushregs
+This command forces @value{GDBN} to flush its internal register cache.
+
+@kindex maint print objfiles
+@cindex info for known object files
+@item maint print objfiles
+Print a dump of all known object files. For each object file, this
+command prints its name, address in memory, and all of its psymtabs
+and symtabs.
+
+@kindex maint print statistics
+@cindex bcache statistics
+@item maint print statistics
+This command prints, for each object file in the program, various data
+about that object file followed by the byte cache (@dfn{bcache})
+statistics for the object file. The objfile data includes the number
+of minimal, partical, full, and stabs symbols, the number of types
+defined by the objfile, the number of as yet unexpanded psym tables,
+the number of line tables and string tables, and the amount of memory
+used by the various tables. The bcache statistics include the counts,
+sizes, and counts of duplicates of all and unique objects, max,
+average, and median entry size, total memory used and its overhead and
+savings, and various measures of the hash table size and chain
+lengths.
+
+@kindex maint print type
+@cindex type chain of a data type
+@item maint print type @var{expr}
+Print the type chain for a type specified by @var{expr}. The argument
+can be either a type name or a symbol. If it is a symbol, the type of
+that symbol is described. The type chain produced by this command is
+a recursive definition of the data type as stored in @value{GDBN}'s
+data structures, including its flags and contained types.
+
+@kindex maint set dwarf2 max-cache-age
+@kindex maint show dwarf2 max-cache-age
+@item maint set dwarf2 max-cache-age
+@itemx maint show dwarf2 max-cache-age
+Control the DWARF 2 compilation unit cache.
+
+@cindex DWARF 2 compilation units cache
+In object files with inter-compilation-unit references, such as those
+produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2
+reader needs to frequently refer to previously read compilation units.
+This setting controls how long a compilation unit will remain in the
+cache if it is not referenced. A higher limit means that cached
+compilation units will be stored in memory longer, and more total
+memory will be used. Setting it to zero disables caching, which will
+slow down @value{GDBN} startup, but reduce memory consumption.
@kindex maint set profile
@kindex maint show profile
data in a @file{gmon.out} file, be sure to move it to a safe location.
Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be
-compiled with the @samp{-pg} compiler option.
+compiled with the @samp{-pg} compiler option.
+
+@kindex maint show-debug-regs
+@cindex x86 hardware debug registers
+@item maint show-debug-regs
+Control whether to show variables that mirror the x86 hardware debug
+registers. Use @code{ON} to enable, @code{OFF} to disable. If
+enabled, the debug registers values are shown when GDB inserts or
+removes a hardware breakpoint or watchpoint, and when the inferior
+triggers a hardware-assisted breakpoint or watchpoint.
+
+@kindex maint space
+@cindex memory used by commands
+@item maint space
+Control whether to display memory usage for each command. If set to a
+nonzero value, @value{GDBN} will display how much memory each command
+took, following the command's own output. This can also be requested
+by invoking @value{GDBN} with the @option{--statistics} command-line
+switch (@pxref{Mode Options}).
+
+@kindex maint time
+@cindex time of command execution
+@item maint time
+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.
+This can also be requested by invoking @value{GDBN} with the
+@option{--statistics} command-line switch (@pxref{Mode Options}).
+
+@kindex maint translate-address
+@item maint translate-address @r{[}@var{section}@r{]} @var{addr}
+Find the symbol stored at the location specified by the address
+@var{addr} and an optional section name @var{section}. If found,
+@value{GDBN} prints the name of the closest symbol and an offset from
+the symbol's location to the specified address. This is similar to
+the @code{info address} command (@pxref{Symbols}), except that this
+command also allows to find symbols in other sections.
+
+@end table
+
+The following command is useful for non-interactive invocations of
+@value{GDBN}, such as in the test suite.
-@end table
+@table @code
+@item set watchdog @var{nsec}
+@kindex set watchdog
+@cindex watchdog timer
+@cindex timeout for commands
+Set the maximum number of seconds @value{GDBN} will wait for the
+target operation to finish. If this time expires, @value{GDBN}
+reports and error and the command is aborted.
+@item show watchdog
+Show the current setting of the target wait timeout.
+@end table
@node Remote Protocol
@appendix @value{GDBN} Remote Serial Protocol
characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
value greater than 126 should not be used.
-Some remote systems have used a different run-length encoding mechanism
-loosely refered to as the cisco encoding. Following the @samp{*}
-character are two hex digits that indicate the size of the packet.
-
So:
@smallexample
"@code{0* }"
protocol. A newer @value{GDBN} can tell if a packet is supported based
on that response.
-A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M},
-@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are
+A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M},
+@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are
optional.
@node Packets
The following table provides a complete list of all currently defined
@var{command}s and their corresponding response @var{data}.
+@xref{File-I/O remote protocol extension}, for details about the File
+I/O extension of the remote protocol.
@table @r
@cindex @code{D} packet
Detach @value{GDBN} from the remote system. Sent to the remote target
-before @value{GDBN} disconnects.
+before @value{GDBN} disconnects via the @code{detach} command.
Reply:
@table @samp
Each byte of register data is described by two hex digits. The bytes
with the register are transmitted in target byte order. The size of
each register and their position within the @samp{g} @var{packet} are
-determined by the @value{GDBN} internal macros @var{REGISTER_RAW_SIZE}
-and @var{REGISTER_NAME} macros. The specification of several standard
-@code{g} packets is specified below.
+determined by the @value{GDBN} internal macros
+@var{DEPRECATED_REGISTER_RAW_SIZE} and @var{REGISTER_NAME} macros. The
+specification of several standard @code{g} packets is specified below.
@item E@var{NN}
for an error.
@end table
Reserved for future use.
-@item @code{H}@var{c}@var{t@dots{}} --- set thread
+@item @code{H}@var{c}@var{t@dots{}} --- set thread
@cindex @code{H} packet
Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
@item @code{O} --- reserved
-Reserved for future use.
-
-@item @code{p}@var{n@dots{}} --- read reg @strong{(reserved)}
+@item @code{p}@var{hex number of register} --- read register packet
@cindex @code{p} packet
-@xref{write register packet}.
+@xref{read registers packet}, for a description of how the returned
+register value is encoded.
Reply:
@table @samp
-@item @var{r@dots{}.}
-The hex encoded value of the register in target byte order.
+@item @var{XX@dots{}}
+the register's value
+@item E@var{NN}
+for an error
+@item
+Indicating an unrecognized @var{query}.
@end table
@item @code{P}@var{n@dots{}}@code{=}@var{r@dots{}} --- write register
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
-@item @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} --- search
+@item @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} --- search
@cindex @code{t} packet
Search backwards starting at address @var{addr} for a match with pattern
Reserved for future use.
-@item @code{v} --- reserved
+@item @code{v} --- verbose packet prefix
-Reserved for future use.
+Packets starting with @code{v} are identified by a multi-letter name,
+up to the first @code{;} or @code{?} (or the end of the packet).
+
+@item @code{vCont}[;@var{action}[@code{:}@var{tid}]]... --- extended resume
+@cindex @code{vCont} packet
+
+Resume the inferior. Different actions may be specified for each thread.
+If an action is specified with no @var{tid}, then it is applied to any
+threads that don't have a specific action specified; if no default action is
+specified then other threads should remain stopped. Specifying multiple
+default actions is an error; specifying no actions is also an error.
+Thread IDs are specified in hexadecimal. Currently supported actions are:
+
+@table @code
+@item c
+Continue.
+@item C@var{sig}
+Continue with signal @var{sig}. @var{sig} should be two hex digits.
+@item s
+Step.
+@item S@var{sig}
+Step with signal @var{sig}. @var{sig} should be two hex digits.
+@end table
+
+The optional @var{addr} argument normally associated with these packets is
+not supported in @code{vCont}.
+
+Reply:
+@xref{Stop Reply Packets}, for the reply specifications.
+
+@item @code{vCont?} --- extended resume query
+@cindex @code{vCont?} packet
+
+Query support for the @code{vCont} packet.
+
+Reply:
+@table @samp
+@item @code{vCont}[;@var{action}]...
+The @code{vCont} packet is supported. Each @var{action} is a supported
+command in the @code{vCont} packet.
+@item
+The @code{vCont} packet is not supported.
+@end table
@item @code{V} --- reserved
@var{addr} is address, @var{length} is number of bytes, @var{XX@dots{}}
is binary data. The characters @code{$}, @code{#}, and @code{0x7d} are
-escaped using @code{0x7d}.
+escaped using @code{0x7d}, and then XORed with @code{0x20}.
+For example, @code{0x7d} would be transmitted as @code{0x7d 0x5d}.
Reply:
@table @samp
@var{AA} = two hex digit signal number; @var{n...} = register number
(hex), @var{r...} = target byte ordered register contents, size defined
-by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} =
-thread process ID, this is a hex integer; @var{n...} = (@samp{watch} |
-@samp{rwatch} | @samp{awatch}, @var{r...} = data address, this is a hex
-integer; @var{n...} = other string not starting with valid hex digit.
-@value{GDBN} should ignore this @var{n...}, @var{r...} pair and go on
-to the next. This way we can extend the protocol.
+by @code{DEPRECATED_REGISTER_RAW_SIZE}; @var{n...} = @samp{thread},
+@var{r...} = thread process ID, this is a hex integer; @var{n...} =
+(@samp{watch} | @samp{rwatch} | @samp{awatch}, @var{r...} = data
+address, this is a hex integer; @var{n...} = other string not starting
+with valid hex digit. @value{GDBN} should ignore this @var{n...},
+@var{r...} pair and go on to the next. This way we can extend the
+protocol.
@item W@var{AA}
The process terminated with signal @var{AA}.
-@item N@var{AA};@var{t@dots{}};@var{d@dots{}};@var{b@dots{}} @strong{(obsolete)}
-
-@var{AA} = signal number; @var{t@dots{}} = address of symbol
-@code{_start}; @var{d@dots{}} = base of data section; @var{b@dots{}} =
-base of bss section. @emph{Note: only used by Cisco Systems targets.
-The difference between this reply and the @samp{qOffsets} query is that
-the @samp{N} packet may arrive spontaneously whereas the @samp{qOffsets}
-is a query initiated by the host debugger.}
-
@item O@var{XX@dots{}}
@var{XX@dots{}} is hex encoding of @sc{ascii} data. This can happen at
@node General Query Packets
@section General Query Packets
+@cindex remote query requests
The following set and query packets have already been defined.
@table @r
@item @code{q}@code{C} --- current thread
-
+@cindex current thread, remote request
+@cindex @code{qC} packet
Return the current thread id.
Reply:
@table @samp
@item @code{QC}@var{pid}
-Where @var{pid} is a HEX encoded 16 bit process id.
+Where @var{pid} is an unsigned hexidecimal process id.
@item *
Any other reply implies the old pid.
@end table
@item @code{q}@code{fThreadInfo} -- all thread ids
-
+@cindex list active threads, remote request
+@cindex @code{qfThreadInfo} packet
@code{q}@code{sThreadInfo}
Obtain a list of active thread ids from the target (OS). Since there
@end table
In response to each query, the target will reply with a list of one or
-more thread ids, in big-endian hex, separated by commas. @value{GDBN}
-will respond to each reply with a request for more thread ids (using the
-@code{qs} form of the query), until the target responds with @code{l}
-(lower-case el, for @code{'last'}).
+more thread ids, in big-endian unsigned hex, separated by commas.
+@value{GDBN} will respond to each reply with a request for more thread
+ids (using the @code{qs} form of the query), until the target responds
+with @code{l} (lower-case el, for @code{'last'}).
@item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info
-
+@cindex thread attributes info, remote request
+@cindex @code{qThreadExtraInfo} packet
Where @var{id} is a thread-id in big-endian hex. Obtain a printable
string description of a thread's attributes from the target OS. This
string may contain anything that the target OS thinks is interesting for
@end table
@item @code{q}@code{CRC:}@var{addr}@code{,}@var{length} --- compute CRC of memory block
-
+@cindex CRC of memory block, remote request
+@cindex @code{qCRC} packet
Reply:
@table @samp
@item @code{E}@var{NN}
@end table
@item @code{q}@code{Offsets} --- query sect offs
-
+@cindex section offsets, remote request
+@cindex @code{qOffsets} packet
Get section offsets that the target used when re-locating the downloaded
image. @emph{Note: while a @code{Bss} offset is included in the
response, @value{GDBN} ignores this and instead applies the @code{Data}
@end table
@item @code{q}@code{P}@var{mode}@var{threadid} --- thread info request
-
+@cindex thread information, remote request
+@cindex @code{qP} packet
Returns information on @var{threadid}. Where: @var{mode} is a hex
encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
See @code{remote.c:remote_unpack_thread_info_response()}.
@item @code{q}@code{Rcmd,}@var{command} --- remote command
-
+@cindex execute remote command, remote request
+@cindex @code{qRcmd} packet
@var{command} (hex encoded) is passed to the local interpreter for
execution. Invalid commands should be reported using the output string.
Before the final result packet, the target may also respond with a
@item @samp{}
When @samp{q}@samp{Rcmd} is not recognized.
@end table
-
+z
@item @code{qSymbol::} --- symbol lookup
-
+@cindex symbol lookup, remote request
+@cindex @code{qSymbol} packet
Notify the target that @value{GDBN} is prepared to serve symbol lookup
requests. Accept requests from the target for the values of symbols.
(if available), until the target ceases to request them.
@end table
+@item @code{qPart}:@var{object}:@code{read}:@var{annex}:@var{offset},@var{length} --- read special data
+@cindex read special object, remote request
+@cindex @code{qPart} packet
+Read uninterpreted bytes from the target's special data area
+identified by the keyword @code{object}.
+Request @var{length} bytes starting at @var{offset} bytes into the data.
+The content and encoding of @var{annex} is specific to the object;
+it can supply additional details about what data to access.
+
+Here are the specific requests of this form defined so far.
+All @samp{@code{qPart}:@var{object}:@code{read}:@dots{}}
+requests use the same reply formats, listed below.
+
+@table @asis
+@item @code{qPart}:@code{auxv}:@code{read}::@var{offset},@var{length}
+Access the target's @dfn{auxiliary vector}. @xref{OS Information,
+auxiliary vector}, and see @ref{Remote configuration,
+read-aux-vector-packet}. Note @var{annex} must be empty.
+@end table
+
+Reply:
+@table @asis
+@item @code{OK}
+The @var{offset} in the request is at the end of the data.
+There is no more data to be read.
+
+@item @var{XX@dots{}}
+Hex encoded data bytes read.
+This may be fewer bytes than the @var{length} in the request.
+
+@item @code{E00}
+The request was malformed, or @var{annex} was invalid.
+
+@item @code{E}@var{nn}
+The offset was invalid, or there was an error encountered reading the data.
+@var{nn} is a hex-encoded @code{errno} value.
+
+@item @code{""} (empty)
+An empty reply indicates the @var{object} or @var{annex} string was not
+recognized by the stub.
+@end table
+
+@item @code{qPart}:@var{object}:@code{write}:@var{annex}:@var{offset}:@var{data@dots{}}
+@cindex write data into object, remote request
+Write uninterpreted bytes into the target's special data area
+identified by the keyword @code{object},
+starting at @var{offset} bytes into the data.
+@var{data@dots{}} is the hex-encoded data to be written.
+The content and encoding of @var{annex} is specific to the object;
+it can supply additional details about what data to access.
+
+No requests of this form are presently in use. This specification
+serves as a placeholder to document the common format that new
+specific request specifications ought to use.
+
+Reply:
+@table @asis
+@item @var{nn}
+@var{nn} (hex encoded) is the number of bytes written.
+This may be fewer bytes than supplied in the request.
+
+@item @code{E00}
+The request was malformed, or @var{annex} was invalid.
+
+@item @code{E}@var{nn}
+The offset was invalid, or there was an error encountered writing the data.
+@var{nn} is a hex-encoded @code{errno} value.
+
+@item @code{""} (empty)
+An empty reply indicates the @var{object} or @var{annex} string was not
+recognized by the stub, or that the object does not support writing.
+@end table
+
+@item @code{qPart}:@var{object}:@var{operation}:@dots{}
+Requests of this form may be added in the future. When a stub does
+not recognize the @var{object} keyword, or its support for
+@var{object} does not recognize the @var{operation} keyword,
+the stub must respond with an empty packet.
+
+@item @code{qGetTLSAddr}:@var{thread-id},@var{offset},@var{lm} --- get thread local storage address
+@cindex get thread-local storage address, remote request
+@cindex @code{qGetTLSAddr} packet
+Fetch the address associated with thread local storage specified
+by @var{thread-id}, @var{offset}, and @var{lm}.
+
+@var{thread-id} is the (big endian, hex encoded) thread id associated with the
+thread for which to fetch the TLS address.
+
+@var{offset} is the (big endian, hex encoded) offset associated with the
+thread local variable. (This offset is obtained from the debug
+information associated with the variable.)
+
+@var{lm} is the (big endian, hex encoded) OS/ABI specific encoding of the
+the load module associated with the thread local storage. For example,
+a @sc{gnu}/Linux system will pass the link map address of the shared
+object associated with the thread local storage under consideration.
+Other operating environments may choose to represent the load module
+differently, so the precise meaning of this parameter will vary.
+
+Reply:
+@table @asis
+@item @var{XX@dots{}}
+Hex encoded (big endian) bytes representing the address of the thread
+local storage requested.
+
+@item @code{E}@var{nn} (where @var{nn} are hex digits)
+An error occurred.
+
+@item @code{""} (empty)
+An empty reply indicates that @code{qGetTLSAddr} is not supported by the stub.
+@end table
+
@end table
@node Register Packet Format
@menu
* File-I/O Overview::
* Protocol basics::
-* The `F' request packet::
-* The `F' reply packet::
+* The F request packet::
+* The F reply packet::
* Memory transfer::
* The Ctrl-C message::
* Console I/O::
@subsection File-I/O Overview
@cindex file-i/o overview
-The File I/O remote protocol extension (short: File-I/O) allows the
-target to use the hosts file system and console I/O when calling various
+The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the
+target to use the host's file system and console I/O when calling various
system calls. System calls on the target system are translated into a
remote protocol packet to the host system which then performs the needed
actions and returns with an adequate response packet to the target system.
This simulates file system operations even on targets that lack file systems.
The protocol is defined host- and target-system independent. It uses
-it's own independent representation of datatypes and values. Both,
+its own independent representation of datatypes and values. Both,
@value{GDBN} and the target's @value{GDBN} stub are responsible for
translating the system dependent values into the unified protocol values
when data is transmitted.
request from @value{GDBN} is required.
@smallexample
-(gdb) continue
+(@value{GDBP}) continue
<- target requests 'system call X'
target is stopped, @value{GDBN} executes system call
-> GDB returns result
The File-I/O protocol uses the @code{F} packet, as request as well
as as reply packet. Since a File-I/O system call can only occur when
-@value{GDBN} is waiting for the continuing or stepping target, the
+@value{GDBN} is waiting for the continuing or stepping target, the
File-I/O request is a reply that @value{GDBN} has to expect as a result
of a former @samp{C}, @samp{c}, @samp{S} or @samp{s} packet.
This @code{F} packet contains all information needed to allow @value{GDBN}
to call the appropriate host system call:
@itemize @bullet
-@item
+@item
A unique identifier for the requested system call.
@item
All parameters to the system call. Pointers are given as addresses
in the target memory address space. Pointers to strings are given as
-pointer/length pair. Numerical values are given as they are.
+pointer/length pair. Numerical values are given as they are.
Numerical control values are given in a protocol specific representation.
@end itemize
At that point @value{GDBN} has to perform the following actions.
@itemize @bullet
-@item
+@item
If parameter pointer values are given, which point to data needed as input
to a system call, @value{GDBN} requests this data from the target with a
standard @code{m} packet request. This additional communication has to be
After having done the needed type and value coercion, the target continues
the latest continue or step action.
-@node The `F' request packet
+@node The F request packet
@subsection The @code{F} request packet
@cindex file-i/o request packet
@cindex @code{F} request packet
@var{parameter@dots{}} are the parameters to the system call.
-@end table
+@end table
Parameters are hexadecimal integer values, either the real values in case
of scalar datatypes, as pointers to target buffer space in case of compound
from its predecessor by a comma. All values are transmitted in ASCII
string representation, pointer/length pairs separated by a slash.
-@node The `F' reply packet
+@node The F reply packet
@subsection The @code{F} reply packet
@cindex file-i/o reply packet
@cindex @code{F} reply packet
gotten a break message. The meaning for the target is ``system call
interupted by @code{SIGINT}''. Consequentially, the target should actually stop
(as with a break message) and return to @value{GDBN} with a @code{T02}
-packet. In this case, it's important for the target to know, in which
+packet. In this case, it's important for the target to know, in which
state the system call was interrupted. Since this action is by design
not an atomic operation, we have to differ between two cases:
@cindex isatty call, file-i/o protocol
A special case in this protocol is the library call @code{isatty} which
-is implemented as it's own call inside of this protocol. It returns
+is implemented as its own call inside of this protocol. It returns
1 to the target if the file descriptor given as parameter is attached
to the @value{GDBN} console, 0 otherwise. Implementing through system calls
would require implementing @code{ioctl} and would be more complex than
@cindex system call, file-i/o protocol
The other special case in this protocol is the @code{system} call which
-is implemented as it's own call, too. @value{GDBN} is taking over the full
+is implemented as its own call, too. @value{GDBN} is taking over the full
task of calling the necessary host calls to perform the @code{system}
call. The return value of @code{system} is simplified before it's returned
to the target. Basically, the only signal transmitted back is @code{EINTR}
in case the user pressed @kbd{Ctrl-C}. Otherwise the return value consists
entirely of the exit status of the called command.
-Due to security concerns, the @code{system} call is refused to be called
-by @value{GDBN} by default. The user has to allow this call explicitly by
-entering
-
-@table @samp
-@kindex set remote system-call-allowed 1
-@item @code{set remote system-call-allowed 1}
-@end table
-
-Disabling the @code{system} call is done by
-
-@table @samp
-@kindex set remote system-call-allowed 0
-@item @code{set remote system-call-allowed 0}
-@end table
+Due to security concerns, the @code{system} call is by default refused
+by @value{GDBN}. The user has to allow this call explicitly with the
+@kbd{set remote system-call-allowed 1} command.
-The current setting is shown by typing
+@table @code
+@item set remote system-call-allowed
+@kindex set remote system-call-allowed
+Control whether to allow the @code{system} calls in the File I/O
+protocol for the remote target. The default is zero (disabled).
-@table @samp
+@item show remote system-call-allowed
@kindex show remote system-call-allowed
-@item @code{show remote system-call-allowed}
+Show the current setting of system calls for the remote File I/O
+protocol.
@end table
@node List of supported calls
int open(const char *pathname, int flags);
int open(const char *pathname, int flags, mode_t mode);
-@exdent Request:
+@exdent Request:
Fopen,pathptr/len,flags,mode
@end smallexample
@code{flags} is the bitwise or of the following values:
@table @code
-@item O_CREAT
+@item O_CREAT
If the file does not exist it will be created. The host
rules apply as far as file ownership and time stamps
are concerned.
-@item O_EXCL
+@item O_EXCL
When used with O_CREAT, if the file already exists it is
an error and open() fails.
-@item O_TRUNC
+@item O_TRUNC
If the file already exists and the open mode allows
writing (O_RDWR or O_WRONLY is given) it will be
truncated to length 0.
-@item O_APPEND
+@item O_APPEND
The file is opened in append mode.
-@item O_RDONLY
+@item O_RDONLY
The file is opened for reading only.
-@item O_WRONLY
+@item O_WRONLY
The file is opened for writing only.
-@item O_RDWR
+@item O_RDWR
The file is opened for reading and writing.
@noindent
@code{mode} is the bitwise or of the following values:
@table @code
-@item S_IRUSR
+@item S_IRUSR
User has read permission.
-@item S_IWUSR
+@item S_IWUSR
User has write permission.
-@item S_IRGRP
+@item S_IRGRP
Group has read permission.
-@item S_IWGRP
+@item S_IWGRP
Group has write permission.
-@item S_IROTH
+@item S_IROTH
Others have read permission.
-@item S_IWOTH
+@item S_IWOTH
Others have write permission.
@noindent
@end smallexample
@table @code
-@item EEXIST
+@item EEXIST
pathname already exists and O_CREAT and O_EXCL were used.
-@item EISDIR
+@item EISDIR
pathname refers to a directory.
-@item EACCES
+@item EACCES
The requested access is not allowed.
@item ENAMETOOLONG
pathname was too long.
-@item ENOENT
+@item ENOENT
A directory component in pathname does not exist.
-@item ENODEV
+@item ENODEV
pathname refers to a device, pipe, named pipe or socket.
-@item EROFS
+@item EROFS
pathname refers to a file on a read-only filesystem and
write access was requested.
-@item EFAULT
+@item EFAULT
pathname is an invalid pointer value.
-@item ENOSPC
+@item ENOSPC
No space on device to create the file.
-@item EMFILE
+@item EMFILE
The process already has the maximum number of files open.
-@item ENFILE
+@item ENFILE
The limit on the total number of files open on the system
has been reached.
-@item EINTR
+@item EINTR
The call was interrupted by the user.
@end table
@cindex close, file-i/o system call
@smallexample
-@exdent Synopsis:
+@exdent Synopsis:
int close(int fd);
-@exdent Request:
+@exdent Request:
Fclose,fd
@exdent Return value:
@end smallexample
@table @code
-@item EBADF
+@item EBADF
fd isn't a valid open file descriptor.
-@item EINTR
+@item EINTR
The call was interrupted by the user.
@end table
@cindex read, file-i/o system call
@smallexample
-@exdent Synopsis:
+@exdent Synopsis:
int read(int fd, void *buf, unsigned int count);
-@exdent Request:
+@exdent Request:
Fread,fd,bufptr,count
@exdent Return value:
On success, the number of bytes read is returned.
Zero indicates end of file. If count is zero, read
-returns zero as well. On error, -1 is returned.
+returns zero as well. On error, -1 is returned.
@exdent Errors:
@end smallexample
@table @code
-@item EBADF
+@item EBADF
fd is not a valid file descriptor or is not open for
reading.
-@item EFAULT
+@item EFAULT
buf is an invalid pointer value.
-@item EINTR
+@item EINTR
The call was interrupted by the user.
@end table
@cindex write, file-i/o system call
@smallexample
-@exdent Synopsis:
+@exdent Synopsis:
int write(int fd, const void *buf, unsigned int count);
-@exdent Request:
+@exdent Request:
Fwrite,fd,bufptr,count
@exdent Return value:
@end smallexample
@table @code
-@item EBADF
+@item EBADF
fd is not a valid file descriptor or is not open for
writing.
-@item EFAULT
+@item EFAULT
buf is an invalid pointer value.
-@item EFBIG
+@item EFBIG
An attempt was made to write a file that exceeds the
host specific maximum file size allowed.
-@item ENOSPC
+@item ENOSPC
No space on device to write the data.
-@item EINTR
+@item EINTR
The call was interrupted by the user.
@end table
@cindex lseek, file-i/o system call
@smallexample
-@exdent Synopsis:
+@exdent Synopsis:
long lseek (int fd, long offset, int flag);
-@exdent Request:
+@exdent Request:
Flseek,fd,offset,flag
@end smallexample
@code{flag} is one of:
@table @code
-@item SEEK_SET
+@item SEEK_SET
The offset is set to offset bytes.
-@item SEEK_CUR
+@item SEEK_CUR
The offset is set to its current location plus offset
bytes.
-@item SEEK_END
+@item SEEK_END
The offset is set to the size of the file plus offset
bytes.
@end table
@end smallexample
@table @code
-@item EBADF
+@item EBADF
fd is not a valid open file descriptor.
-@item ESPIPE
+@item ESPIPE
fd is associated with the @value{GDBN} console.
-@item EINVAL
+@item EINVAL
flag is not a proper value.
-@item EINTR
+@item EINTR
The call was interrupted by the user.
@end table
@cindex rename, file-i/o system call
@smallexample
-@exdent Synopsis:
+@exdent Synopsis:
int rename(const char *oldpath, const char *newpath);
-@exdent Request:
+@exdent Request:
Frename,oldpathptr/len,newpathptr/len
@exdent Return value:
@end smallexample
@table @code
-@item EISDIR
+@item EISDIR
newpath is an existing directory, but oldpath is not a
directory.
-@item EEXIST
+@item EEXIST
newpath is a non-empty directory.
-@item EBUSY
+@item EBUSY
oldpath or newpath is a directory that is in use by some
process.
-@item EINVAL
+@item EINVAL
An attempt was made to make a directory a subdirectory
of itself.
-@item ENOTDIR
+@item ENOTDIR
A component used as a directory in oldpath or new
path is not a directory. Or oldpath is a directory
and newpath exists but is not a directory.
-@item EFAULT
+@item EFAULT
oldpathptr or newpathptr are invalid pointer values.
-@item EACCES
+@item EACCES
No access to the file or the path of the file.
@item ENAMETOOLONG
-
+
oldpath or newpath was too long.
-@item ENOENT
+@item ENOENT
A directory component in oldpath or newpath does not exist.
-@item EROFS
+@item EROFS
The file is on a read-only filesystem.
-@item ENOSPC
+@item ENOSPC
The device containing the file has no room for the new
directory entry.
-@item EINTR
+@item EINTR
The call was interrupted by the user.
@end table
@cindex unlink, file-i/o system call
@smallexample
-@exdent Synopsis:
+@exdent Synopsis:
int unlink(const char *pathname);
-@exdent Request:
+@exdent Request:
Funlink,pathnameptr/len
@exdent Return value:
@end smallexample
@table @code
-@item EACCES
+@item EACCES
No access to the file or the path of the file.
-@item EPERM
+@item EPERM
The system does not allow unlinking of directories.
-@item EBUSY
+@item EBUSY
The file pathname cannot be unlinked because it's
being used by another process.
-@item EFAULT
+@item EFAULT
pathnameptr is an invalid pointer value.
@item ENAMETOOLONG
pathname was too long.
-@item ENOENT
+@item ENOENT
A directory component in pathname does not exist.
-@item ENOTDIR
+@item ENOTDIR
A component of the path is not a directory.
-@item EROFS
+@item EROFS
The file is on a read-only filesystem.
-@item EINTR
+@item EINTR
The call was interrupted by the user.
@end table
@cindex stat, file-i/o system call
@smallexample
-@exdent Synopsis:
+@exdent Synopsis:
int stat(const char *pathname, struct stat *buf);
int fstat(int fd, struct stat *buf);
-@exdent Request:
+@exdent Request:
Fstat,pathnameptr/len,bufptr
Ffstat,fd,bufptr
@end smallexample
@table @code
-@item EBADF
+@item EBADF
fd is not a valid open file.
-@item ENOENT
+@item ENOENT
A directory component in pathname does not exist or the
path is an empty string.
-@item ENOTDIR
+@item ENOTDIR
A component of the path is not a directory.
-@item EFAULT
+@item EFAULT
pathnameptr is an invalid pointer value.
-@item EACCES
+@item EACCES
No access to the file or the path of the file.
@item ENAMETOOLONG
pathname was too long.
-@item EINTR
+@item EINTR
The call was interrupted by the user.
@end table
@cindex gettimeofday, file-i/o system call
@smallexample
-@exdent Synopsis:
+@exdent Synopsis:
int gettimeofday(struct timeval *tv, void *tz);
-@exdent Request:
+@exdent Request:
Fgettimeofday,tvptr,tzptr
@exdent Return value:
@end smallexample
@table @code
-@item EINVAL
+@item EINVAL
tz is a non-NULL pointer.
-@item EFAULT
+@item EFAULT
tvptr and/or tzptr is an invalid pointer value.
@end table
@cindex isatty, file-i/o system call
@smallexample
-@exdent Synopsis:
+@exdent Synopsis:
int isatty(int fd);
-@exdent Request:
+@exdent Request:
Fisatty,fd
@exdent Return value:
@end smallexample
@table @code
-@item EINTR
+@item EINTR
The call was interrupted by the user.
@end table
@cindex system, file-i/o system call
@smallexample
-@exdent Synopsis:
+@exdent Synopsis:
int system(const char *command);
-@exdent Request:
+@exdent Request:
Fsystem,commandptr/len
@exdent Return value:
@end smallexample
@table @code
-@item EINTR
+@item EINTR
The call was interrupted by the user.
@end table
@code{Int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are
implemented as 32 bit values in this protocol.
-@code{Long} and @code{unsigned long} are implemented as 64 bit types.
-
+@code{Long} and @code{unsigned long} are implemented as 64 bit types.
+
@xref{Limits}, for corresponding MIN and MAX values (similar to those
in @file{limits.h}) to allow range checking on host and target.
is defined as follows:
@smallexample
-struct timeval @{
+struct timeval @{
time_t tv_sec; /* second */
long tv_usec; /* microsecond */
@};
<- @code{T02}
@end smallexample
+@include agentexpr.texi
+
@include gpl.texi
+@raisesections
@include fdl.texi
+@lowersections
@node Index
@unnumbered Index
projects / deliverable / binutils-gdb.git / blobdiff