\input texinfo @c -*-texinfo-*-
-@c Copyright 1988-2000
+@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
+@c 1999, 2000, 2001
@c Free Software Foundation, Inc.
@c
@c %**start of header
@finalout
@syncodeindex ky cp
-@c readline appendices use @vindex
+@c readline appendices use @vindex, @findex and @ftable,
+@c annotate.texi and gdbmi use @findex.
@syncodeindex vr cp
+@syncodeindex fn cp
@c !!set GDB manual's edition---not the same as GDB version!
-@set EDITION Eighth
+@set EDITION Ninth
@c !!set GDB manual's revision date
-@set DATE March 2000
+@set DATE April 2001
@c THIS MANUAL REQUIRES TEXINFO 3.12 OR LATER.
of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger}
for @value{GDBN} Version @value{GDBVN}.
-Copyright (C) 1988-2000 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
+Copyright (C) 1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
+ Free Software Foundation, Inc.
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``A Sample GDB Session'' and ``Free
+Software'', with the Front-Cover texts being ``A GNU Manual,'' and
+with the Back-Cover Texts as in (a) below.
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
@end ifinfo
@titlepage
@sp 1
@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN}
@subtitle @value{DATE}
-@author Richard M. Stallman and Roland H. Pesch
+@author Richard Stallman, Roland Pesch, Stan Shebs, et al.
@page
@tex
{\parskip=0pt
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988-2000 Free Software Foundation, Inc.
+Copyright @copyright{} 1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
+ Free Software Foundation, Inc.
@sp 2
Published by the Free Software Foundation @*
59 Temple Place - Suite 330, @*
Boston, MA 02111-1307 USA @*
ISBN 1-882114-77-9 @*
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``A Sample GDB Session'' and ``Free
+Software'', with the Front-Cover texts being ``A GNU Manual,'' and
+with the Back-Cover Texts as in (a) below.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
@end titlepage
@page
This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
@value{GDBVN}.
-Copyright (C) 1988-2000 Free Software Foundation, Inc.
+Copyright (C) 1988-2001 Free Software Foundation, Inc.
@menu
* Summary:: Summary of @value{GDBN}
* Stack:: Examining the stack
* Source:: Examining source files
* Data:: Examining data
+* Tracepoints:: Debugging remote targets non-intrusively
* Languages:: Using @value{GDBN} with different languages
* Sequences:: Canned sequences of commands
* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
* Annotations:: @value{GDBN}'s annotation interface.
+* GDB/MI:: @value{GDBN}'s Machine Interface.
* GDB Bugs:: Reporting bugs in @value{GDBN}
* Formatting Documentation:: How to format and print @value{GDBN} documentation
This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
-This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
+This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
@value{GDBVN}.
Copyright (C) 1988-2000 Free Software Foundation, Inc.
@end ifhtml
+@c TeX can handle the contents at the start but makeinfo 3.12 can not
+@iftex
+@contents
+@end iftex
+
@node Summary
@unnumbered Summary of @value{GDBN}
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.0 and 5.1);
Jim Blandy (release 4.18);
Jason Molenda (release 4.17);
Stan Shebs (release 4.14);
Richard Stallman, assisted at various times by Peter TerMaat, Chris
Hanson, and Richard Mlynarik, handled releases through 2.8.
-Michael Tiemann is the author of most of the @sc{gnu} C++ support in
-@value{GDBN}, with significant additional contributions from Per
-Bothner. James Clark wrote the @sc{gnu} C++ demangler. Early work on
-C++ was by Peter TerMaat (who also did much general update work leading
-to release 3.0).
+Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support
+in @value{GDBN}, with significant additional contributions from Per
+Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++}
+demangler. Early work on C@t{++} was by Peter TerMaat (who also did
+much general update work leading to release 3.0).
-@value{GDBN} 4 uses the BFD subroutine library to examine multiple
+@value{GDBN} uses the BFD subroutine library to examine multiple
object-file formats; BFD was a joint project of David V.
Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
David Johnson wrote the original COFF support; Pace Willison did
the original support for encapsulated COFF.
-Brent Benson of Harris Computer Systems contributed DWARF 2 support.
+Brent Benson of Harris Computer Systems contributed DWARF2 support.
Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
Modula-2 support, and contributed the Languages chapter of this manual.
Fred Fish wrote most of the support for Unix System Vr4.
-He also enhanced the command-completion support to cover C++ overloaded
+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
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++
+(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.
+DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project.
+Robert Hoehne made significant contributions to the DJGPP port.
+
Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its
development since 1991. Cygnus engineers who have worked on @value{GDBN}
fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
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.0, the target side of the asynchronous
+(@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
program or device. This option is meant to be set by programs which
communicate with @value{GDBN} using it as a back end. For example,
@samp{--interpreter=mi} causes @value{GDBN} to use the @dfn{gdbmi
-interface}.
-@c FIXME: There should be an @xref here to the GDB/MI docs, but
-@c gdbmi.texi doesn't have a single node to reference!
+interface} (@pxref{GDB/MI, , The @sc{gdb/mi} Interface}).
@item -write
@cindex @code{--write}
@table @code
@kindex quit @r{[}@var{expression}@r{]}
-@kindex q
+@kindex q @r{(@code{quit})}
@item quit @r{[}@var{expression}@r{]}
@itemx q
To exit @value{GDBN}, use the @code{quit} command (abbreviated
arguments to the @code{help} command.
@cindex repeating commands
-@kindex RET
+@kindex RET @r{(repeat last command)}
A blank line as input to @value{GDBN} (typing just @key{RET}) means to
repeat the previous command. Certain commands (for example, @code{run})
will not repeat this way; these are commands whose unintentional
@key{RET} too many in this situation, @value{GDBN} disables command
repetition after any command that generates this sort of display.
-@kindex #
+@kindex # @r{(a comment)}
@cindex comment
Any text from a @kbd{#} to the end of the line is a comment; it does
nothing. This is useful mainly in command files (@pxref{Command
command.
If you just want to see the list of alternatives in the first place, you
-can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
+can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
means @kbd{@key{META} ?}. You can type this either by holding down a
key designated as the @key{META} shift on your keyboard (if there is
one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}.
@value{GDBN} commands.
The most likely situation where you might need this is in typing the
-name of a C++ function. This is because C++ allows function overloading
-(multiple definitions of the same function, distinguished by argument
-type). For example, when you want to set a breakpoint you may need to
-distinguish whether you mean the version of @code{name} that takes an
-@code{int} parameter, @code{name(int)}, or the version that takes a
-@code{float} parameter, @code{name(float)}. To use the word-completion
-facilities in this situation, type a single quote @code{'} at the
-beginning of the function name. This alerts @value{GDBN} that it may need to
-consider more information than usual when you press @key{TAB} or
-@kbd{M-?} to request word completion:
+name of a C@t{++} function. This is because C@t{++} allows function
+overloading (multiple definitions of the same function, distinguished
+by argument type). For example, when you want to set a breakpoint you
+may need to distinguish whether you mean the version of @code{name}
+that takes an @code{int} parameter, @code{name(int)}, or the version
+that takes a @code{float} parameter, @code{name(float)}. To use the
+word-completion facilities in this situation, type a single quote
+@code{'} at the beginning of the function name. This alerts
+@value{GDBN} that it may need to consider more information than usual
+when you press @key{TAB} or @kbd{M-?} to request word completion:
@example
(@value{GDBP}) b 'bubble( @kbd{M-?}
completion on an overloaded symbol.
For more information about overloaded functions, see @ref{C plus plus
-expressions, ,C++ expressions}. You can use the command @code{set
+expressions, ,C@t{++} expressions}. You can use the command @code{set
overload-resolution off} to disable overload resolution;
-see @ref{Debugging C plus plus, ,@value{GDBN} features for C++}.
+see @ref{Debugging C plus plus, ,@value{GDBN} features for C@t{++}}.
@node Help
using the command @code{help}.
@table @code
-@kindex h
+@kindex h @r{(@code{help})}
@item help
@itemx h
You can use @code{help} (abbreviated @code{h}) with no arguments to
apropos reload
@end smallexample
-@noindent results in:
+@noindent
+results in:
@smallexample
@c @group
@c @group
@table @code
@kindex info
-@kindex i
+@kindex i @r{(@code{info})}
@item info
This command (abbreviated @code{i}) is for describing the state of your
program. For example, you can list the arguments given to your program
@table @code
@kindex run
+@kindex r @r{(@code{run})}
@item run
@itemx r
Use the @code{run} command to start your program under @value{GDBN}.
@code{run} with no arguments uses the same arguments used by the previous
@code{run}, or those set by the @code{set args} command.
-@kindex set args
@table @code
+@kindex set args
@item set args
Specify the arguments to be used the next time your program is run. If
@code{set args} has no arguments, @code{run} executes your program
@kindex path
@item path @var{directory}
Add @var{directory} to the front of the @code{PATH} environment variable
-(the search path for executables), for both @value{GDBN} and your program.
+(the search path for executables) that will be passed to your program.
+The value of @code{PATH} used by @value{GDBN} does not change.
You may specify several directory names, separated by whitespace or by a
system-dependent separator character (@samp{:} on Unix, @samp{;} on
MS-DOS and MS-Windows). If @var{directory} is already in the path, it
This thread is called the @dfn{current thread}. Debugging commands show
program information from the perspective of the current thread.
-@kindex New @var{systag}
+@cindex @code{New} @var{systag} message
@cindex thread identifier (system)
@c FIXME-implementors!! It would be more helpful if the [New...] message
@c included GDB's numeric thread handle, so you could just go to that
number---a small integer assigned in thread-creation order---with each
thread in your program.
-@kindex New @var{systag}
-@cindex thread identifier (system)
+@cindex @code{New} @var{systag} message, on HP-UX
+@cindex thread identifier (system), on HP-UX
@c FIXME-implementors!! It would be more helpful if the [New...] message
@c included GDB's numeric thread handle, so you could just go to that
@c thread without first checking `info threads'.
@cindex catchpoints
@cindex breakpoint on events
A @dfn{catchpoint} is another special breakpoint that stops your program
-when a certain kind of event occurs, such as the throwing of a C++
+when a certain kind of event occurs, such as the throwing of a C@t{++}
exception or the loading of a library. As with watchpoints, you use a
different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting
catchpoints}), but aside from that, you can manage a catchpoint like any
@c FIXME 2 is there stuff on this already? break at fun start, already init?
@kindex break
-@kindex b
-@kindex $bpnum
+@kindex b @r{(@code{break})}
+@vindex $bpnum@r{, convenience variable}
@cindex latest breakpoint
Breakpoints are set with the @code{break} command (abbreviated
@code{b}). The debugger convenience variable @samp{$bpnum} records the
-number of the breakpoints you've set most recently; see @ref{Convenience
+number of the breakpoint you've set most recently; see @ref{Convenience
Vars,, Convenience variables}, for a discussion of what you can do with
convenience variables.
@item break @var{function}
Set a breakpoint at entry to function @var{function}.
When using source languages that permit overloading of symbols, such as
-C++, @var{function} may refer to more than one possible place to break.
+C@t{++}, @var{function} may refer to more than one possible place to break.
@xref{Breakpoint Menus,,Breakpoint menus}, for a discussion of that situation.
@item break +@var{offset}
@code{.*} leading and trailing the regular expression you supply, so to
match only functions that begin with @code{foo}, use @code{^foo}.
-When debugging C++ programs, @code{rbreak} is useful for setting
+When debugging C@t{++} programs, @code{rbreak} is useful for setting
breakpoints on overloaded functions that are not members of any special
classes.
@cindex event handling
You can use @dfn{catchpoints} to cause the debugger to stop for certain
-kinds of program events, such as C++ exceptions or the loading of a
+kinds of program events, such as C@t{++} exceptions or the loading of a
shared library. Use the @code{catch} command to set a catchpoint.
@table @code
@table @code
@item throw
@kindex catch throw
-The throwing of a C++ exception.
+The throwing of a C@t{++} exception.
@item catch
@kindex catch catch
-The catching of a C++ exception.
+The catching of a C@t{++} exception.
@item exec
@kindex catch exec
Use the @code{info break} command to list the current catchpoints.
-There are currently some limitations to C++ exception handling
+There are currently some limitations to C@t{++} exception handling
(@code{catch throw} and @code{catch catch}) in @value{GDBN}:
@itemize @bullet
out where the exception was raised.
To stop just before an exception handler is called, you need some
-knowledge of the implementation. In the case of @sc{gnu} C++, exceptions are
+knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are
raised by calling a library function named @code{__raise_exception}
which has the following ANSI C interface:
@cindex delete breakpoints
@kindex delete
-@kindex d
+@kindex d @r{(@code{delete})}
@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
ranges specified as arguments. If no argument is specified, delete all
@table @code
@kindex disable breakpoints
@kindex disable
-@kindex dis
+@kindex dis @r{(@code{disable})}
@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
Disable the specified breakpoints---or all breakpoints, if none are
listed. A disabled breakpoint has no effect but is not forgotten. All
@cindex overloading
@cindex symbol overloading
-Some programming languages (notably C++) permit a single function name
+Some programming languages (notably C@t{++}) 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
@table @code
@kindex continue
-@kindex c
-@kindex fg
+@kindex c @r{(@code{continue})}
+@kindex fg @r{(resume foreground execution)}
@item continue @r{[}@var{ignore-count}@r{]}
@itemx c @r{[}@var{ignore-count}@r{]}
@itemx fg @r{[}@var{ignore-count}@r{]}
@table @code
@kindex step
-@kindex s
+@kindex s @r{(@code{step})}
@item step
Continue running your program until control reaches a different source
line, then stop it and return control to @value{GDBN}. This command is
below.
@end quotation
-The @code{step} command only stops at the first instruction of a
-source line. This prevents the multiple stops that could otherwise occur in
-switch statements, for loops, etc. @code{step} continues to stop if a
-function that has debugging information is called within the line.
-In other words, @code{step} @emph{steps inside} any functions called
-within the line.
+The @code{step} command only stops at the first instruction of a source
+line. This prevents the multiple stops that could otherwise occur in
+@code{switch} statements, @code{for} loops, etc. @code{step} continues
+to stop if a function that has debugging information is called within
+the line. In other words, @code{step} @emph{steps inside} any functions
+called within the line.
Also, the @code{step} command only enters a function if there is line
number information for the function. Otherwise it acts like the
@var{count} steps, stepping stops right away.
@kindex next
-@kindex n
+@kindex n @r{(@code{next})}
@item next @r{[}@var{count}@r{]}
Continue to the next source line in the current (innermost) stack frame.
This is similar to @code{step}, but function calls that appear within
The @code{next} command only stops at the first instruction of a
source line. This prevents multiple stops that could otherwise occur in
-switch statements, for loops, etc.
+@code{switch} statements, @code{for} loops, etc.
+
+@kindex set step-mode
+@item set step-mode
+@cindex functions without line info, and stepping
+@cindex stepping into functions with no line info
+@itemx set step-mode on
+The @code{set step-mode on} command causes the @code{step} command to
+stop at the first instruction of a function which contains no debug line
+information rather than stepping over it.
+
+This is useful in cases where you may be interested in inspecting the
+machine instructions of a function which has no symbolic info and do not
+want @value{GDBN} to automatically skip over this function.
+
+@item set step-mode off
+Causes the @code{step} command to step over any functions which contains no
+debug information. This is the default.
@kindex finish
@item finish
,Returning from a function}).
@kindex until
-@kindex u
+@kindex u @r{(@code{until})}
@item until
@itemx u
Continue running until a source line past the current line, in the
and hence is quicker than @code{until} without an argument.
@kindex stepi
-@kindex si
+@kindex si @r{(@code{stepi})}
@item stepi
@itemx stepi @var{arg}
@itemx si
@need 750
@kindex nexti
-@kindex ni
+@kindex ni @r{(@code{nexti})}
@item nexti
@itemx nexti @var{arg}
@itemx ni
@kindex handle
@item handle @var{signal} @var{keywords}@dots{}
-Change the way @value{GDBN} handles signal @var{signal}. @var{signal} can
-be the number of a signal or its name (with or without the @samp{SIG} at the
-beginning). The @var{keywords} say what change to make.
+Change the way @value{GDBN} handles signal @var{signal}. @var{signal}
+can be the number of a signal or its name (with or without the
+@samp{SIG} at the beginning); a list of signal numberss of the form
+@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the
+known signals. The @var{keywords} say what change to make.
@end table
@c @group
implies the @code{nostop} keyword as well.
@item pass
+@itemx noignore
@value{GDBN} should allow your program to see this signal; your program
can handle the signal, or else it may terminate if the signal is fatal
-and not handled.
+and not handled. @code{pass} and @code{noignore} are synonyms.
@item nopass
+@itemx ignore
@value{GDBN} should not allow your program to see this signal.
+@code{nopass} and @code{ignore} are synonyms.
@end table
@c @end group
@table @code
@kindex frame@r{, command}
+@cindex current stack frame
@item frame @var{args}
The @code{frame} command allows you to move from one stack frame to another,
and to print the stack frame you select. @var{args} may be either the
@code{frame} prints the current stack frame.
@kindex select-frame
+@cindex selecting frame silently
@item select-frame
The @code{select-frame} command allows you to move from one stack frame
to another without printing the frame. This is the silent version of
@table @code
@kindex backtrace
-@kindex bt
+@kindex bt @r{(@code{backtrace})}
@item backtrace
@itemx bt
Print a backtrace of the entire stack: one line per frame for all
@kindex where
@kindex info stack
-@kindex info s
+@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}.
@table @code
@kindex frame@r{, selecting}
-@kindex f
+@kindex f @r{(@code{frame})}
@item frame @var{n}
@itemx f @var{n}
Select frame number @var{n}. Recall that frame zero is the innermost
that have existed longer. @var{n} defaults to one.
@kindex down
-@kindex do
+@kindex do @r{(@code{down})}
@item down @var{n}
Move @var{n} frames down the stack. For positive numbers @var{n}, this
advances toward the innermost frame, to lower frame numbers, to frames
@xref{Selection, ,Selecting a frame}.
@kindex info frame
-@kindex info f
+@kindex info f @r{(@code{info frame})}
@item info frame
@itemx info f
This command prints a verbose description of the selected stack frame,
@section Printing source lines
@kindex list
-@kindex l
+@kindex l @r{(@code{list})}
To print lines from a source file, use the @code{list} command
(abbreviated @code{l}). By default, ten lines are printed.
There are several ways to specify what part of the file you want to print.
@kindex cdir
@kindex cwd
-@kindex $cdir
-@kindex $cwd
+@vindex $cdir@r{, convenience variable}
+@vindex $cwdr@r{, convenience variable}
@cindex compilation directory
@cindex current directory
@cindex working directory
@end smallexample
@cindex @code{$_} and @code{info line}
-@kindex x@r{, and }@code{info line}
+@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
sufficient to begin examining the machine code (@pxref{Memory,
* Convenience Vars:: Convenience variables
* Registers:: Registers
* Floating Point Hardware:: Floating point hardware
+* Memory Region Attributes:: Memory region attributes
@end menu
@node Expressions
@cindex colon-colon, context for variables/functions
@iftex
@c info cannot cope with a :: index entry, but why deprive hard copy readers?
-@kindex ::
+@cindex @code{::}, context for variables/functions
@end iftex
@example
@var{file}::@var{variable}
(@value{GDBP}) p 'f2.c'::x
@end example
-@cindex C++ scope resolution
+@cindex C@t{++} scope resolution
This use of @samp{::} is very rarely in conflict with the very similar
-use of the same notation in C++. @value{GDBN} also supports use of the C++
+use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++}
scope resolution operator in @value{GDBN} expressions.
@c FIXME: Um, so what happens in one of those rare cases where it's in
@c conflict?? --mew
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++ compiler usually
+formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler usually
supports the @samp{-gstabs} option. @samp{-gstabs} produces debug info
in a format that is superior to formats such as COFF. You may be able
-to use DWARF-2 (@samp{-gdwarf-2}), which is also an effective form for
+to use DWARF2 (@samp{-gdwarf-2}), which is also an effective form for
debug info. See @ref{Debugging Options,,Options for Debugging Your
Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}, for more
information.
@section Artificial arrays
@cindex artificial array
-@kindex @@
+@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
dynamically determined size for which only a pointer exists in the
@item a
@cindex unknown address, locating
+@cindex locate address
Print as an address, both absolute in hexadecimal and as an offset from
the nearest preceding symbol. You can use this format used to discover
where (in what function) an unknown address is located:
$3 = 0x54320 <_initialize_vx+396>
@end example
+@noindent
+The command @code{info symbol 0x54320} yields similar results.
+@xref{Symbols, info symbol}.
+
@item c
Regard as an integer and print it as a character constant.
@cindex examining memory
@table @code
-@kindex x
+@kindex x @r{(examine memory)}
@item x/@var{nfu} @var{addr}
@itemx x @var{addr}
@itemx x
@need 1000
@noindent
-These settings are of interest when debugging C++ programs:
+These settings are of interest when debugging C@t{++} programs:
@table @code
@cindex demangling
@kindex set print demangle
@item set print demangle
@itemx set print demangle on
-Print C++ names in their source form rather than in the encoded
+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++ names are printed in mangled or demangled form.
+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++ names in their source form rather than their mangled form, even
+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++ names in assembly listings are printed in mangled
+Show whether C@t{++} names in assembly listings are printed in mangled
or demangled form.
@kindex set demangle-style
-@cindex C++ symbol decoding style
-@cindex symbol decoding style, C++
+@cindex C@t{++} symbol decoding style
+@cindex symbol decoding style, C@t{++}
@item set demangle-style @var{style}
Choose among several encoding schemes used by different compilers to
-represent C++ names. The choices for @var{style} are currently:
+represent C@t{++} names. The choices for @var{style} are currently:
@table @code
@item auto
Allow @value{GDBN} to choose a decoding style by inspecting your program.
@item gnu
-Decode based on the @sc{gnu} C++ compiler (@code{g++}) encoding algorithm.
+Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm.
This is the default.
@item hp
-Decode based on the HP ANSI C++ (@code{aCC}) encoding algorithm.
+Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm.
@item lucid
-Decode based on the Lucid C++ compiler (@code{lcc}) encoding algorithm.
+Decode based on the Lucid C@t{++} compiler (@code{lcc}) encoding algorithm.
@item arm
-Decode using the algorithm in the @cite{C++ Annotated Reference Manual}.
+Decode using the algorithm in the @cite{C@t{++} Annotated Reference Manual}.
@strong{Warning:} this setting alone is not sufficient to allow
debugging @code{cfront}-generated executables. @value{GDBN} would
require further enhancement to permit that.
@kindex show demangle-style
@item show demangle-style
-Display the encoding style currently in use for decoding C++ symbols.
+Display the encoding style currently in use for decoding C@t{++} symbols.
@kindex set print object
@item set print object
@kindex set print static-members
@item set print static-members
@itemx set print static-members on
-Print static members when displaying a C++ object. The default is on.
+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++ object.
+Do not print static members when displaying a C@t{++} object.
@kindex show print static-members
@item show print static-members
-Show whether C++ static members are printed, or not.
+Show whether C@t{++} 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
-Pretty print C++ virtual function tables. The default is off.
+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++ compiler (@code{aCC}).)
+ANSI C@t{++} compiler (@code{aCC}).)
@item set print vtbl off
-Do not pretty print C++ virtual function tables.
+Do not pretty print C@t{++} virtual function tables.
@kindex show print vtbl
@item show print vtbl
-Show whether C++ virtual function tables are pretty printed, or not.
+Show whether C@t{++} virtual function tables are pretty printed, or not.
@end table
@node Value History
values likely to be useful.
@table @code
-@kindex $_
+@vindex $_@r{, convenience variable}
@item $_
The variable @code{$_} is automatically set by the @code{x} command to
the last address examined (@pxref{Memory, ,Examining memory}). Other
except when set by the @code{x} command, in which case it is a pointer
to the type of @code{$__}.
-@kindex $__
+@vindex $__@r{, convenience variable}
@item $__
The variable @code{$__} is automatically set by the @code{x} command
to the value found in the last address examined. Its type is chosen
to match the format in which the data was printed.
@item $_exitcode
-@kindex $_exitcode
+@vindex $_exitcode@r{, convenience variable}
The variable @code{$_exitcode} is automatically set to the exit code when
the program being debugged terminates.
@end table
the ARM and x86 machines.
@end table
+@node 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
+to determine whether to allow certain types of memory accesses; whether to
+use specific width accesses; and whether to cache target memory.
+
+Defined memory regions can be individually enabled and disabled. When a
+memory region is disabled, @value{GDBN} uses the default attributes when
+accessing memory in that region. Similarly, if no memory regions have
+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;
+to enable, disable, or remove a memory region, you specify that number.
+
+@table @code
+@kindex mem
+@item mem @var{address1} @var{address1} @var{attributes}@dots{}
+Define memory region bounded by @var{address1} and @var{address2}
+with attributes @var{attributes}@dots{}.
+
+@kindex delete mem
+@item delete mem @var{nums}@dots{}
+Remove memory region numbers @var{nums}.
+
+@kindex disable mem
+@item disable mem @var{nums}@dots{}
+Disable memory region numbers @var{nums}.
+A disabled memory region is not forgotten.
+It may be enabled again later.
+
+@kindex enable mem
+@item enable mem @var{nums}@dots{}
+Enable memory region numbers @var{nums}.
+
+@kindex info mem
+@item info mem
+Print a table of all defined memory regions, with the following columns
+for each region.
+
+@table @emph
+@item Memory Region Number
+@item Enabled or Disabled.
+Enabled memory regions are marked with @samp{y}.
+Disabled memory regions are marked with @samp{n}.
+
+@item Lo Address
+The address defining the inclusive lower bound of the memory region.
+
+@item Hi Address
+The address defining the exclusive upper bound of the memory region.
+
+@item Attributes
+The list of attributes set for this memory region.
+@end table
+@end table
+
+
+@subsection Attributes
+
+@subsubsection Memory Access Mode
+The access mode attributes set whether @value{GDBN} may make read or
+write accesses to a memory region.
+
+While these attributes prevent @value{GDBN} from performing invalid
+memory accesses, they do nothing to prevent the target system, I/O DMA,
+etc. from accessing memory.
+
+@table @code
+@item ro
+Memory is read only.
+@item wo
+Memory is write only.
+@item rw
+Memory is read/write (default).
+@end table
+
+@subsubsection Memory Access Size
+The acccess size attributes tells @value{GDBN} to use specific sized
+accesses in the memory region. Often memory mapped device registers
+require specific sized accesses. If no access size attribute is
+specified, @value{GDBN} may use accesses of any size.
+
+@table @code
+@item 8
+Use 8 bit memory accesses.
+@item 16
+Use 16 bit memory accesses.
+@item 32
+Use 32 bit memory accesses.
+@item 64
+Use 64 bit memory accesses.
+@end table
+
+@c @subsubsection Hardware/Software Breakpoints
+@c The hardware/software breakpoint attributes set whether @value{GDBN}
+@c will use hardware or software breakpoints for the internal breakpoints
+@c used by the step, next, finish, until, etc. commands.
+@c
+@c @table @code
+@c @item hwbreak
+@c Always use hardware breakpoints
+@c @item swbreak (default)
+@c @end table
+
+@subsubsection Data Cache
+The data cache attributes set whether @value{GDBN} will cache target
+memory. While this generally improves performance by reducing debug
+protocol overhead, it can lead to incorrect results because @value{GDBN}
+does not know about volatile variables or memory mapped device
+registers.
+
+@table @code
+@item cache
+Enable @value{GDBN} to cache target memory.
+@item nocache (default)
+Disable @value{GDBN} from caching target memory.
+@end table
+
+@c @subsubsection Memory Write Verification
+@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
+@c @item verify
+@c @item noverify (default)
+@c @end table
+
+@node Tracepoints
+@chapter Tracepoints
+@c This chapter is based on the documentation written by Michael
+@c Snyder, David Taylor, Jim Blandy, and Elena Zannoni.
+
+@cindex tracepoints
+In some applications, it is not feasible for the debugger to interrupt
+the program's execution long enough for the developer to learn
+anything helpful about its behavior. If the program's correctness
+depends on its real-time behavior, delays introduced by a debugger
+might cause the program to change its behavior drastically, or perhaps
+fail, even when the code itself is correct. It is useful to be able
+to observe the program's behavior without interrupting it.
+
+Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can
+specify locations in the program, called @dfn{tracepoints}, and
+arbitrary expressions to evaluate when those tracepoints are reached.
+Later, using the @code{tfind} command, you can examine the values
+those expressions had when the program hit the tracepoints. The
+expressions may also denote objects in memory---structures or arrays,
+for example---whose values @value{GDBN} should record; while visiting
+a particular tracepoint, you may inspect those objects as if they were
+in memory at that moment. However, because @value{GDBN} records these
+values without interacting with you, it can do so quickly and
+unobtrusively, hopefully not disturbing the program's behavior.
+
+The tracepoint facility is currently available only for remote
+targets. @xref{Targets}.
+
+This chapter describes the tracepoint commands and features.
+
+@menu
+* Set Tracepoints::
+* Analyze Collected Data::
+* Tracepoint Variables::
+@end menu
+
+@node Set Tracepoints
+@section Commands to Set Tracepoints
+
+Before running such a @dfn{trace experiment}, an arbitrary number of
+tracepoints can be set. Like a breakpoint (@pxref{Set Breaks}), a
+tracepoint has a number assigned to it by @value{GDBN}. Like with
+breakpoints, tracepoint numbers are successive integers starting from
+one. Many of the commands associated with tracepoints take the
+tracepoint number as their argument, to identify which tracepoint to
+work on.
+
+For each tracepoint, you can specify, in advance, some arbitrary set
+of data that you want the target to collect in the trace buffer when
+it hits that tracepoint. The collected data can include registers,
+local variables, or global data. Later, you can use @value{GDBN}
+commands to examine the values these data had at the time the
+tracepoint was hit.
+
+This section describes commands to set tracepoints and associated
+conditions and actions.
+
+@menu
+* 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
+@subsection Create and Delete Tracepoints
+
+@table @code
+@cindex set tracepoint
+@kindex trace
+@item trace
+The @code{trace} command is very similar to the @code{break} command.
+Its argument can be a source line, a function name, or an address in
+the target program. @xref{Set Breaks}. The @code{trace} command
+defines a tracepoint, which is a point in the target program where the
+debugger will briefly stop, collect some data, and then allow the
+program to continue. Setting a tracepoint or changing its commands
+doesn't take effect until the next @code{tstart} command; thus, you
+cannot change the tracepoint attributes once a trace experiment is
+running.
+
+Here are some examples of using the @code{trace} command:
+
+@smallexample
+(@value{GDBP}) @b{trace foo.c:121} // a source file and line number
+
+(@value{GDBP}) @b{trace +2} // 2 lines forward
+
+(@value{GDBP}) @b{trace my_function} // first source line of function
+
+(@value{GDBP}) @b{trace *my_function} // EXACT start address of function
+
+(@value{GDBP}) @b{trace *0x2117c4} // an address
+@end smallexample
+
+@noindent
+You can abbreviate @code{trace} as @code{tr}.
+
+@vindex $tpnum
+@cindex last tracepoint number
+@cindex recent tracepoint number
+@cindex tracepoint number
+The convenience variable @code{$tpnum} records the tracepoint number
+of the most recently set tracepoint.
+
+@kindex delete tracepoint
+@cindex tracepoint deletion
+@item delete tracepoint @r{[}@var{num}@r{]}
+Permanently delete one or more tracepoints. With no argument, the
+default is to delete all tracepoints.
+
+Examples:
+
+@smallexample
+(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints
+
+(@value{GDBP}) @b{delete trace} // remove all tracepoints
+@end smallexample
+
+@noindent
+You can abbreviate this command as @code{del tr}.
+@end table
+
+@node Enable and Disable Tracepoints
+@subsection Enable and Disable Tracepoints
+
+@table @code
+@kindex disable tracepoint
+@item disable tracepoint @r{[}@var{num}@r{]}
+Disable tracepoint @var{num}, or all tracepoints if no argument
+@var{num} is given. A disabled tracepoint will have no effect during
+the next trace experiment, but it is not forgotten. You can re-enable
+a disabled tracepoint using the @code{enable tracepoint} command.
+
+@kindex enable tracepoint
+@item enable tracepoint @r{[}@var{num}@r{]}
+Enable tracepoint @var{num}, or all tracepoints. The enabled
+tracepoints will become effective the next time a trace experiment is
+run.
+@end table
+
+@node Tracepoint Passcounts
+@subsection Tracepoint Passcounts
+
+@table @code
+@kindex passcount
+@cindex tracepoint pass count
+@item passcount @r{[}@var{n} @r{[}@var{num}@r{]]}
+Set the @dfn{passcount} of a tracepoint. The passcount is a way to
+automatically stop a trace experiment. If a tracepoint's passcount is
+@var{n}, then the trace experiment will be automatically stopped on
+the @var{n}'th time that tracepoint is hit. If the tracepoint number
+@var{num} is not specified, the @code{passcount} command sets the
+passcount of the most recently defined tracepoint. If no passcount is
+given, the trace experiment will run until stopped explicitly by the
+user.
+
+Examples:
+
+@smallexample
+(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of tracepoint 2
+
+(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the
+ // most recently defined tracepoint.
+(@value{GDBP}) @b{trace foo}
+(@value{GDBP}) @b{pass 3}
+(@value{GDBP}) @b{trace bar}
+(@value{GDBP}) @b{pass 2}
+(@value{GDBP}) @b{trace baz}
+(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been
+ // executed 3 times OR when bar has
+ // been executed 2 times
+ // OR when baz has been executed 1 time.
+@end smallexample
+@end table
+
+@node Tracepoint Actions
+@subsection Tracepoint Action Lists
+
+@table @code
+@kindex actions
+@cindex tracepoint actions
+@item actions @r{[}@var{num}@r{]}
+This command will prompt for a list of actions to be taken when the
+tracepoint is hit. If the tracepoint number @var{num} is not
+specified, this command sets the actions for the one that was most
+recently defined (so that you can define a tracepoint and then say
+@code{actions} without bothering about its number). You specify the
+actions themselves on the following lines, one action at a time, and
+terminate the actions list with a line containing just @code{end}. So
+far, the only defined actions are @code{collect} and
+@code{while-stepping}.
+
+@cindex remove actions from a tracepoint
+To remove all actions from a tracepoint, type @samp{actions @var{num}}
+and follow it immediately with @samp{end}.
+
+@smallexample
+(@value{GDBP}) @b{collect @var{data}} // collect some data
+
+(@value{GDBP}) @b{while-stepping 5} // single-step 5 times and collect data
+
+(@value{GDBP}) @b{end} // signals the end of actions.
+@end smallexample
+
+In the following example, the action list begins with @code{collect}
+commands indicating the things to be collected when the tracepoint is
+hit. Then, in order to single-step and collect additional data
+following the tracepoint, a @code{while-stepping} command is used,
+followed by the list of things to be collected while stepping. The
+@code{while-stepping} command is terminated by its own separate
+@code{end} command. Lastly, the action list is terminated by an
+@code{end} command.
+
+@smallexample
+(@value{GDBP}) @b{trace foo}
+(@value{GDBP}) @b{actions}
+Enter actions for tracepoint 1, one per line:
+> collect bar,baz
+> collect $regs
+> while-stepping 12
+ > collect $fp, $sp
+ > end
+end
+@end smallexample
+
+@kindex collect @r{(tracepoints)}
+@item collect @var{expr1}, @var{expr2}, @dots{}
+Collect values of the given expressions when the tracepoint is hit.
+This command accepts a comma-separated list of any valid expressions.
+In addition to global, static, or local variables, the following
+special arguments are supported:
+
+@table @code
+@item $regs
+collect all registers
+
+@item $args
+collect all function arguments
+
+@item $locals
+collect all local variables.
+@end table
+
+You can give several consecutive @code{collect} commands, each one
+with a single argument, or one @code{collect} command with several
+arguments separated by commas: the effect is the same.
+
+The command @code{info scope} (@pxref{Symbols, info scope}) is
+particularly useful for figuring out what data to collect.
+
+@kindex while-stepping @r{(tracepoints)}
+@item while-stepping @var{n}
+Perform @var{n} single-step traces after the tracepoint, collecting
+new data at each step. The @code{while-stepping} command is
+followed by the list of what to collect while stepping (followed by
+its own @code{end} command):
+
+@smallexample
+> while-stepping 12
+ > collect $regs, myglobal
+ > end
+>
+@end smallexample
+
+@noindent
+You may abbreviate @code{while-stepping} as @code{ws} or
+@code{stepping}.
+@end table
+
+@node Listing Tracepoints
+@subsection Listing Tracepoints
+
+@table @code
+@kindex info tracepoints
+@cindex information about tracepoints
+@item info tracepoints @r{[}@var{num}@r{]}
+Display information the tracepoint @var{num}. If you don't specify a
+tracepoint number displays information about all the tracepoints
+defined so far. For each tracepoint, the following information is
+shown:
+
+@itemize @bullet
+@item
+its number
+@item
+whether it is enabled or disabled
+@item
+its address
+@item
+its passcount as given by the @code{passcount @var{n}} command
+@item
+its step count as given by the @code{while-stepping @var{n}} command
+@item
+where in the source files is the tracepoint set
+@item
+its action list as given by the @code{actions} command
+@end itemize
+
+@smallexample
+(@value{GDBP}) @b{info trace}
+Num Enb Address PassC StepC What
+1 y 0x002117c4 0 0 <gdb_asm>
+2 y 0x0020dc64 0 0 in gdb_test at gdb_test.c:375
+3 y 0x0020b1f4 0 0 in collect_data at ../foo.c:1741
+(@value{GDBP})
+@end smallexample
+
+@noindent
+This command can be abbreviated @code{info tp}.
+@end table
+
+@node Starting and Stopping Trace Experiment
+@subsection Starting and Stopping Trace Experiment
+
+@table @code
+@kindex tstart
+@cindex start a new trace experiment
+@cindex collected data discarded
+@item tstart
+This command takes no arguments. It starts the trace experiment, and
+begins collecting data. This has the side effect of discarding all
+the data collected in the trace buffer during the previous trace
+experiment.
+
+@kindex tstop
+@cindex stop a running trace experiment
+@item tstop
+This command takes no arguments. It ends the trace experiment, and
+stops collecting data.
+
+@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.
+
+@kindex tstatus
+@cindex status of trace data collection
+@cindex trace experiment, status of
+@item tstatus
+This command displays the status of the current trace data
+collection.
+@end table
+
+Here is an example of the commands we described so far:
+
+@smallexample
+(@value{GDBP}) @b{trace gdb_c_test}
+(@value{GDBP}) @b{actions}
+Enter actions for tracepoint #1, one per line.
+> collect $regs,$locals,$args
+> while-stepping 11
+ > collect $regs
+ > end
+> end
+(@value{GDBP}) @b{tstart}
+ [time passes @dots{}]
+(@value{GDBP}) @b{tstop}
+@end smallexample
+
+
+@node Analyze Collected Data
+@section Using the collected data
+
+After the tracepoint experiment ends, you use @value{GDBN} commands
+for examining the trace data. The basic idea is that each tracepoint
+collects a trace @dfn{snapshot} every time it is hit and another
+snapshot every time it single-steps. All these snapshots are
+consecutively numbered from zero and go into a buffer, and you can
+examine them later. The way you examine them is to @dfn{focus} on a
+specific trace snapshot. When the remote stub is focused on a trace
+snapshot, it will respond to all @value{GDBN} requests for memory and
+registers by reading from the buffer which belongs to that snapshot,
+rather than from @emph{real} memory or registers of the program being
+debugged. This means that @strong{all} @value{GDBN} commands
+(@code{print}, @code{info registers}, @code{backtrace}, etc.) will
+behave as if we were currently debugging the program state as it was
+when the tracepoint occurred. Any requests for data that are not in
+the buffer will fail.
+
+@menu
+* tfind:: How to select a trace snapshot
+* tdump:: How to display all data for a snapshot
+* save-tracepoints:: How to save tracepoints for a future run
+@end menu
+
+@node tfind
+@subsection @code{tfind @var{n}}
+
+@kindex tfind
+@cindex select trace snapshot
+@cindex find trace snapshot
+The basic command for selecting a trace snapshot from the buffer is
+@code{tfind @var{n}}, which finds trace snapshot number @var{n},
+counting from zero. If no argument @var{n} is given, the next
+snapshot is selected.
+
+Here are the various forms of using the @code{tfind} command.
+
+@table @code
+@item tfind start
+Find the first snapshot in the buffer. This is a synonym for
+@code{tfind 0} (since 0 is the number of the first snapshot).
+
+@item tfind none
+Stop debugging trace snapshots, resume @emph{live} debugging.
+
+@item tfind end
+Same as @samp{tfind none}.
+
+@item tfind
+No argument means find the next trace snapshot.
+
+@item tfind -
+Find the previous trace snapshot before the current one. This permits
+retracing earlier steps.
+
+@item tfind tracepoint @var{num}
+Find the next snapshot associated with tracepoint @var{num}. Search
+proceeds forward from the last examined trace snapshot. If no
+argument @var{num} is given, it means find the next snapshot collected
+for the same tracepoint as the current snapshot.
+
+@item tfind pc @var{addr}
+Find the next snapshot associated with the value @var{addr} of the
+program counter. Search proceeds forward from the last examined trace
+snapshot. If no argument @var{addr} is given, it means find the next
+snapshot with the same value of PC as the current snapshot.
+
+@item tfind outside @var{addr1}, @var{addr2}
+Find the next snapshot whose PC is outside the given range of
+addresses.
+
+@item tfind range @var{addr1}, @var{addr2}
+Find the next snapshot whose PC is between @var{addr1} and
+@var{addr2}. @c FIXME: Is the range inclusive or exclusive?
+
+@item tfind line @r{[}@var{file}:@r{]}@var{n}
+Find the next snapshot associated with the source line @var{n}. If
+the optional argument @var{file} is given, refer to line @var{n} in
+that source file. Search proceeds forward from the last examined
+trace snapshot. If no argument @var{n} is given, it means find the
+next line other than the one currently being examined; thus saying
+@code{tfind line} repeatedly can appear to have the same effect as
+stepping from line to line in a @emph{live} debugging session.
+@end table
+
+The default arguments for the @code{tfind} commands are specifically
+designed to make it easy to scan through the trace buffer. For
+instance, @code{tfind} with no argument selects the next trace
+snapshot, and @code{tfind -} with no argument selects the previous
+trace snapshot. So, by giving one @code{tfind} command, and then
+simply hitting @key{RET} repeatedly you can examine all the trace
+snapshots in order. Or, by saying @code{tfind -} and then hitting
+@key{RET} repeatedly you can examine the snapshots in reverse order.
+The @code{tfind line} command with no argument selects the snapshot
+for the next source line executed. The @code{tfind pc} command with
+no argument selects the next snapshot with the same program counter
+(PC) as the current frame. The @code{tfind tracepoint} command with
+no argument selects the next trace snapshot collected by the same
+tracepoint as the current one.
+
+In addition to letting you scan through the trace buffer manually,
+these commands make it easy to construct @value{GDBN} scripts that
+scan through the trace buffer and print out whatever collected data
+you are interested in. Thus, if we want to examine the PC, FP, and SP
+registers from each trace frame in the buffer, we can say this:
+
+@smallexample
+(@value{GDBP}) @b{tfind start}
+(@value{GDBP}) @b{while ($trace_frame != -1)}
+> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \
+ $trace_frame, $pc, $sp, $fp
+> tfind
+> end
+
+Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44
+Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44
+Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44
+Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44
+Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44
+Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44
+Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44
+Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44
+Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44
+Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44
+Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14
+@end smallexample
+
+Or, if we want to examine the variable @code{X} at each source line in
+the buffer:
+
+@smallexample
+(@value{GDBP}) @b{tfind start}
+(@value{GDBP}) @b{while ($trace_frame != -1)}
+> printf "Frame %d, X == %d\n", $trace_frame, X
+> tfind line
+> end
+
+Frame 0, X = 1
+Frame 7, X = 2
+Frame 13, X = 255
+@end smallexample
+
+@node tdump
+@subsection @code{tdump}
+@kindex tdump
+@cindex dump all data collected at tracepoint
+@cindex tracepoint data, display
+
+This command takes no arguments. It prints all the data collected at
+the current trace snapshot.
+
+@smallexample
+(@value{GDBP}) @b{trace 444}
+(@value{GDBP}) @b{actions}
+Enter actions for tracepoint #2, one per line:
+> collect $regs, $locals, $args, gdb_long_test
+> end
+
+(@value{GDBP}) @b{tstart}
+
+(@value{GDBP}) @b{tfind line 444}
+#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66)
+at gdb_test.c:444
+444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", )
+
+(@value{GDBP}) @b{tdump}
+Data collected at tracepoint 2, trace frame 1:
+d0 0xc4aa0085 -995491707
+d1 0x18 24
+d2 0x80 128
+d3 0x33 51
+d4 0x71aea3d 119204413
+d5 0x22 34
+d6 0xe0 224
+d7 0x380035 3670069
+a0 0x19e24a 1696330
+a1 0x3000668 50333288
+a2 0x100 256
+a3 0x322000 3284992
+a4 0x3000698 50333336
+a5 0x1ad3cc 1758156
+fp 0x30bf3c 0x30bf3c
+sp 0x30bf34 0x30bf34
+ps 0x0 0
+pc 0x20b2c8 0x20b2c8
+fpcontrol 0x0 0
+fpstatus 0x0 0
+fpiaddr 0x0 0
+p = 0x20e5b4 "gdb-test"
+p1 = (void *) 0x11
+p2 = (void *) 0x22
+p3 = (void *) 0x33
+p4 = (void *) 0x44
+p5 = (void *) 0x55
+p6 = (void *) 0x66
+gdb_long_test = 17 '\021'
+
+(@value{GDBP})
+@end smallexample
+
+@node save-tracepoints
+@subsection @code{save-tracepoints @var{filename}}
+@kindex save-tracepoints
+@cindex save tracepoints for future sessions
+
+This command saves all current tracepoint definitions together with
+their actions and passcounts, into a file @file{@var{filename}}
+suitable for use in a later debugging session. To read the saved
+tracepoint definitions, use the @code{source} command (@pxref{Command
+Files}).
+
+@node Tracepoint Variables
+@section Convenience Variables for Tracepoints
+@cindex tracepoint variables
+@cindex convenience variables for tracepoints
+
+@table @code
+@vindex $trace_frame
+@item (int) $trace_frame
+The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no
+snapshot is selected.
+
+@vindex $tracepoint
+@item (int) $tracepoint
+The tracepoint for the current trace snapshot.
+
+@vindex $trace_line
+@item (int) $trace_line
+The line number for the current trace snapshot.
+
+@vindex $trace_file
+@item (char []) $trace_file
+The source file for the current trace snapshot.
+
+@vindex $trace_func
+@item (char []) $trace_func
+The name of the function containing @code{$tracepoint}.
+@end table
+
+Note: @code{$trace_file} is not suitable for use in @code{printf},
+use @code{output} instead.
+
+Here's a simple example of using these convenience variables for
+stepping through all the trace snapshots and printing some of their
+data.
+
+@smallexample
+(@value{GDBP}) @b{tfind start}
+
+(@value{GDBP}) @b{while $trace_frame != -1}
+> output $trace_file
+> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
+> tfind
+> end
+@end smallexample
+
@node Languages
@chapter Using @value{GDBN} with Different Languages
@cindex languages
file formats, the compiler might indicate which language a particular
source file is in. However, most of the time @value{GDBN} infers the
language from the name of the file. The language of a source file
-controls whether C++ names are demangled---this way @code{backtrace} can
+controls whether C@t{++} names are demangled---this way @code{backtrace} can
show each frame appropriately for its own language. There is no way to
set the language of a source file from within @value{GDBN}, but you can
set the language associated with a filename extension. @xref{Show, ,
@itemx .cpp
@itemx .cxx
@itemx .c++
-C++ source file
+C@t{++} source file
@item .f
@itemx .F
@node Support
@section Supported languages
-@value{GDBN} supports C, C++, Fortran, Java, Chill, assembly, and Modula-2.
+@value{GDBN} supports C, C@t{++}, Fortran, Java, Chill, assembly, and Modula-2.
@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++
+* C:: C and C@t{++}
* Modula-2:: Modula-2
* Chill:: Chill
@end menu
@node C
-@subsection C and C++
+@subsection C and C@t{++}
-@cindex C and C++
-@cindex expressions in C or C++
+@cindex C and C@t{++}
+@cindex expressions in C or C@t{++}
-Since C and C++ are so closely related, many features of @value{GDBN} apply
+Since C and C@t{++} are so closely related, many features of @value{GDBN} apply
to both languages. Whenever this is the case, we discuss those languages
together.
-@cindex C++
-@kindex g++
-@cindex @sc{gnu} C++
-The C++ debugging facilities are jointly implemented by the C++
-compiler and @value{GDBN}. Therefore, to debug your C++ code
-effectively, you must compile your C++ programs with a supported
-C++ compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C++
+@cindex C@t{++}
+@cindex @code{g++}, @sc{gnu} C@t{++} compiler
+@cindex @sc{gnu} C@t{++}
+The C@t{++} debugging facilities are jointly implemented by the C@t{++}
+compiler and @value{GDBN}. Therefore, to debug your C@t{++} code
+effectively, you must compile your C@t{++} programs with a supported
+C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++}
compiler (@code{aCC}).
-For best results when using @sc{gnu} C++, use the stabs debugging
+For best results when using @sc{gnu} C@t{++}, use the stabs debugging
format. You can select that format explicitly with the @code{g++}
command-line options @samp{-gstabs} or @samp{-gstabs+}. See
@ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
CC, gcc.info, Using @sc{gnu} CC}, for more information.
@menu
-* C Operators:: C and C++ operators
-* C Constants:: C and C++ constants
-* C plus plus expressions:: C++ expressions
-* C Defaults:: Default settings for C and C++
-* C Checks:: C and C++ type and range checks
+* C Operators:: C and C@t{++} operators
+* C Constants:: C and C@t{++} constants
+* C plus plus expressions:: C@t{++} expressions
+* C Defaults:: Default settings for C and C@t{++}
+* C Checks:: C and C@t{++} type and range checks
* Debugging C:: @value{GDBN} and C
-* Debugging C plus plus:: @value{GDBN} features for C++
+* Debugging C plus plus:: @value{GDBN} features for C@t{++}
@end menu
@node C Operators
-@subsubsection C and C++ operators
+@subsubsection C and C@t{++} operators
-@cindex C and C++ operators
+@cindex C and C@t{++} operators
Operators must be defined on values of specific types. For instance,
@code{+} is defined on numbers, but not on structures. Operators are
often defined on groups of types.
-For the purposes of C and C++, the following definitions hold:
+For the purposes of C and C@t{++}, the following definitions hold:
@itemize @bullet
@item
@emph{Integral types} include @code{int} with any of its storage-class
-specifiers; @code{char}; @code{enum}; and, for C++, @code{bool}.
+specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}.
@item
@emph{Floating-point types} include @code{float}, @code{double}, and
@item &
Address operator. Defined on variables. Same precedence as @code{++}.
-For debugging C++, @value{GDBN} implements a use of @samp{&} beyond what is
-allowed in the C++ language itself: you can use @samp{&(&@var{ref})}
+For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is
+allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})}
(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address
-where a C++ reference variable (declared with @samp{&@var{ref}}) is
+where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is
stored.
@item -
Function parameter list. Same precedence as @code{->}.
@item ::
-C++ scope resolution operator. Defined on @code{struct}, @code{union},
+C@t{++} scope resolution operator. Defined on @code{struct}, @code{union},
and @code{class} types.
@item ::
@end menu
@node C Constants
-@subsubsection C and C++ constants
+@subsubsection C and C@t{++} constants
-@cindex C and C++ constants
+@cindex C and C@t{++} constants
-@value{GDBN} allows you to express the constants of C and C++ in the
+@value{GDBN} allows you to express the constants of C and C@t{++} in the
following ways:
@itemize @bullet
@end menu
@node C plus plus expressions
-@subsubsection C++ expressions
-
-@cindex expressions in C++
-@value{GDBN} expression handling can interpret most C++ expressions.
-
-@cindex C++ support, not in @sc{coff}
-@cindex @sc{coff} versus C++
-@cindex C++ and object formats
-@cindex object formats and C++
-@cindex a.out and C++
-@cindex @sc{ecoff} and C++
-@cindex @sc{xcoff} and C++
-@cindex @sc{elf}/stabs and C++
-@cindex @sc{elf}/@sc{dwarf} and C++
+@subsubsection C@t{++} expressions
+
+@cindex expressions in C@t{++}
+@value{GDBN} expression handling can interpret most C@t{++} expressions.
+
+@cindex C@t{++} support, not in @sc{coff}
+@cindex @sc{coff} versus C@t{++}
+@cindex C@t{++} and object formats
+@cindex object formats and C@t{++}
+@cindex a.out and C@t{++}
+@cindex @sc{ecoff} and C@t{++}
+@cindex @sc{xcoff} and C@t{++}
+@cindex @sc{elf}/stabs and C@t{++}
+@cindex @sc{elf}/@sc{dwarf} and C@t{++}
@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check
@c periodically whether this has happened...
@quotation
-@emph{Warning:} @value{GDBN} can only debug C++ code if you use the
-proper compiler. Typically, C++ debugging depends on the use of
+@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the
+proper compiler. Typically, C@t{++} debugging depends on the use of
additional debugging information in the symbol table, and thus requires
special support. In particular, if your compiler generates a.out, MIPS
@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the
symbol table, these facilities are all available. (With @sc{gnu} CC,
you can use the @samp{-gstabs} option to request stabs debugging
extensions explicitly.) Where the object code format is standard
-@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C++
+@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C@t{++}
support in @value{GDBN} does @emph{not} work.
@end quotation
count = aml->GetOriginal(x, y)
@end example
-@kindex this
-@cindex namespace in C++
+@vindex this@r{, inside C@t{++} member functions}
+@cindex namespace in C@t{++}
@item
While a member function is active (in the selected stack frame), your
expressions have the same namespace available as the member function;
that is, @value{GDBN} allows implicit references to the class instance
-pointer @code{this} following the same rules as C++.
+pointer @code{this} following the same rules as C@t{++}.
@cindex call overloaded functions
@cindex overloaded functions, calling
-@cindex type conversions in C++
+@cindex type conversions in C@t{++}
@item
You can call overloaded functions; @value{GDBN} resolves the function
call to the right definition, with some restrictions. @value{GDBN} does not
Overload resolution is always performed, unless you have specified
@code{set overload-resolution off}. @xref{Debugging C plus plus,
-,@value{GDBN} features for C++}.
+,@value{GDBN} features for C@t{++}}.
You must specify @code{set overload-resolution off} in order to use an
explicit function signature to call an overloaded function, as in
@cindex reference declarations
@item
-@value{GDBN} understands variables declared as C++ references; you can use
-them in expressions just as you do in C++ source---they are automatically
+@value{GDBN} understands variables declared as C@t{++} references; you can use
+them in expressions just as you do in C@t{++} source---they are automatically
dereferenced.
In the parameter list shown when @value{GDBN} displays a frame, the values of
you have specified @samp{set print address off}.
@item
-@value{GDBN} supports the C++ name resolution operator @code{::}---your
+@value{GDBN} supports the C@t{++} name resolution operator @code{::}---your
expressions can use it just as expressions in your program do. Since
one scope may be defined in another, you can use @code{::} repeatedly if
necessary, for example in an expression like
@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows
-resolving name scope by reference to source files, in both C and C++
+resolving name scope by reference to source files, in both C and C@t{++}
debugging (@pxref{Variables, ,Program variables}).
@end enumerate
-In addition, when used with HP's C++ compiler, @value{GDBN} supports
+In addition, when used with HP's C@t{++} compiler, @value{GDBN} supports
calling virtual functions correctly, printing out virtual bases of
objects, calling functions in a base subobject, casting objects, and
invoking user-defined operators.
@node C Defaults
-@subsubsection C and C++ defaults
+@subsubsection C and C@t{++} defaults
-@cindex C and C++ defaults
+@cindex C and C@t{++} defaults
If you allow @value{GDBN} to set type and range checking automatically, they
both default to @code{off} whenever the working language changes to
-C or C++. This happens regardless of whether you or @value{GDBN}
+C or C@t{++}. This happens regardless of whether you or @value{GDBN}
selects the working language.
If you allow @value{GDBN} to set the language automatically, it
recognizes source files whose names end with @file{.c}, @file{.C}, or
@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of
-these files, it sets the working language to C or C++.
+these files, it sets the working language to C or C@t{++}.
@xref{Automatically, ,Having @value{GDBN} infer the source language},
for further details.
@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
@node C Checks
-@subsubsection C and C++ type and range checks
+@subsubsection C and C@t{++} type and range checks
-@cindex C and C++ checks
+@cindex C and C@t{++} checks
-By default, when @value{GDBN} parses C or C++ expressions, type checking
+By default, when @value{GDBN} parses C or C@t{++} expressions, type checking
is not used. However, if you turn type checking on, @value{GDBN}
considers two variables type equivalent if:
@end menu
@node Debugging C plus plus
-@subsubsection @value{GDBN} features for C++
+@subsubsection @value{GDBN} features for C@t{++}
-@cindex commands for C++
+@cindex commands for C@t{++}
-Some @value{GDBN} commands are particularly useful with C++, and some are
-designed specifically for use with C++. Here is a summary:
+Some @value{GDBN} commands are particularly useful with C@t{++}, and some are
+designed specifically for use with C@t{++}. Here is a summary:
@table @code
@cindex break in overloaded functions
@value{GDBN} breakpoint menus help you specify which function definition
you want. @xref{Breakpoint Menus,,Breakpoint menus}.
-@cindex overloading in C++
+@cindex overloading in C@t{++}
@item rbreak @var{regex}
Setting breakpoints using regular expressions is helpful for setting
breakpoints on overloaded functions that are not members of any special
classes.
@xref{Set Breaks, ,Setting breakpoints}.
-@cindex C++ exception handling
+@cindex C@t{++} exception handling
@item catch throw
@itemx catch catch
-Debug C++ exception handling using these commands. @xref{Set
+Debug C@t{++} exception handling using these commands. @xref{Set
Catchpoints, , Setting catchpoints}.
@cindex inheritance
@var{typename}.
@xref{Symbols, ,Examining the Symbol Table}.
-@cindex C++ symbol display
+@cindex C@t{++} symbol display
@item set print demangle
@itemx show print demangle
@itemx set print asm-demangle
@itemx show print asm-demangle
-Control whether C++ symbols display in their source form, both when
-displaying code as C++ source and when displaying disassemblies.
+Control whether C@t{++} symbols display in their source form, both when
+displaying code as C@t{++} source and when displaying disassemblies.
@xref{Print Settings, ,Print settings}.
@item set print object
Control the format for printing virtual function tables.
@xref{Print Settings, ,Print settings}.
(The @code{vtbl} commands do not work on programs compiled with the HP
-ANSI C++ compiler (@code{aCC}).)
+ANSI C@t{++} compiler (@code{aCC}).)
@kindex set overload-resolution
@cindex overloaded functions, overload resolution
@item set overload-resolution on
-Enable overload resolution for C++ expression evaluation. The default
+Enable overload resolution for C@t{++} expression evaluation. The default
is on. For overloaded functions, @value{GDBN} evaluates the arguments
and searches for a function whose signature matches the argument types,
-using the standard C++ conversion rules (see @ref{C plus plus expressions, ,C++
+using the standard C@t{++} conversion rules (see @ref{C plus plus expressions, ,C@t{++}
expressions}, for details). If it cannot find a match, it emits a
message.
@item set overload-resolution off
-Disable overload resolution for C++ expression evaluation. For
+Disable overload resolution for C@t{++} expression evaluation. For
overloaded functions that are not class member functions, @value{GDBN}
chooses the first function of the specified name that it finds in the
symbol table, whether or not its arguments are of the correct type. For
@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++: type
+the same notation that is used to declare such symbols in C@t{++}: type
@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
also use the @value{GDBN} command-line word completion facilities to list the
available choices, or to finish the type list for you.
String constants consist of a sequence of characters enclosed by a
pair of like quotes, either single (@code{'}) or double (@code{"}).
Escape sequences in the style of C are also allowed. @xref{C
-Constants, ,C and C++ constants}, for a brief explanation of escape
+Constants, ,C and C@t{++} constants}, for a brief explanation of escape
sequences.
@item
@node M2 Scope
@subsubsection The scope operators @code{::} and @code{.}
@cindex scope
-@kindex .
+@cindex @code{.}, Modula-2 scope operator
@cindex colon, doubled as scope operator
@ifinfo
-@kindex colon-colon@r{, in Modula-2}
+@vindex colon-colon@r{, in Modula-2}
@c Info cannot handle :: but TeX can.
@end ifinfo
@iftex
-@kindex ::
+@vindex ::@r{, in Modula-2}
@end iftex
There are a few subtle differences between the Modula-2 scope operator
Some @value{GDBN} commands have little use when debugging Modula-2 programs.
Five subcommands of @code{set print} and @code{show print} apply
-specifically to C and C++: @samp{vtbl}, @samp{demangle},
+specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle},
@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four
-apply to C++, and the last to the C @code{union} type, which has no direct
+apply to C@t{++}, and the last to the C @code{union} type, which has no direct
analogue in Modula-2.
The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available
with any language, is not useful with Modula-2. Its
intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be
-created in Modula-2 as they can in C or C++. However, because an
+created in Modula-2 as they can in C or C@t{++}. However, because an
address can be specified by an integral constant, the construct
@samp{@{@var{type}@}@var{adrexp}} is still useful.
@item
@emph{Set Literals} are defined by a name which was specified in a set
mode. The value delivered by a Set Literal is the set value. This is
-comparable to an enumeration in C/C++ language.
+comparable to an enumeration in C/C@t{++} language.
@item
@emph{Emptiness Literal} is predefined by @code{NULL}. The value of the
emptiness literal delivers either the empty reference value, the empty
@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
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
+@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:
+
+@example
+(@value{GDBP}) info symbol 0x54320
+_initialize_vx + 396 in section .text
+@end example
+
+@noindent
+This is the opposite of the @code{info address} command. You can use
+it to find out the name of a variable or a function given its address.
+
@kindex whatis
@item whatis @var{expr}
Print the data type of expression @var{expr}. @var{expr} is not
@code{whatis}, it does not print a detailed description; second, it
lists all source files where a type is defined.
+@kindex info scope
+@cindex local variables
+@item info scope @var{addr}
+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:
+
+@smallexample
+(@value{GDBP}) @b{info scope command_line_handler}
+Scope for command_line_handler:
+Symbol rl is an argument at stack/frame offset 8, length 4.
+Symbol linebuffer is in static storage at address 0x150a18, length 4.
+Symbol linelength is in static storage at address 0x150a1c, length 4.
+Symbol p is a local variable in register $esi, length 4.
+Symbol p1 is a local variable in register $ebx, length 4.
+Symbol nline is a local variable in register $edx, length 4.
+Symbol repeat is a local variable at frame offset -8, length 4.
+@end smallexample
+
+@noindent
+This command is especially useful for determining what data to collect
+during a @dfn{trace experiment}, see @ref{Tracepoint Actions,
+collect}.
+
@kindex info source
@item info source
Show the name of the current source file---that is, the source file for
@item info methods
@itemx info methods @var{regexp}
The @code{info methods} command permits the user to examine all defined
-methods within C++ program, or (with the @var{regexp} argument) a
-specific set of methods found in the various C++ classes. Many
-C++ classes provide a large number of methods. Thus, the output
+methods within C@t{++} program, or (with the @var{regexp} argument) a
+specific set of methods found in the various C@t{++} classes. Many
+C@t{++} classes provide a large number of methods. Thus, the output
from the @code{ptype} command can be overwhelming and hard to use. The
@code{info-methods} command filters the methods, printing only those
which match the regular-expression @var{regexp}.
@cindex dynamic linking
@item add-symbol-file @var{filename} @var{address}
@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
-@itemx add-symbol-file @var{filename} @var{address} @var{data_address} @var{bss_address}
-@itemx add-symbol-file @var{filename} @r{-T}@var{section} @var{address}
+@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address}
The @code{add-symbol-file} command reads additional symbol table
information from the file @var{filename}. You would use this command
when @var{filename} has been dynamically loaded (by some other means)
into the program that is running. @var{address} should be the memory
address at which the file has been loaded; @value{GDBN} cannot figure
-this out for itself. You can specify up to three addresses, in which
-case they are taken to be the addresses of the text, data, and bss
-segments respectively. For complicated cases, you can specify an
-arbitrary number of @samp{@r{-T}@var{section} @var{address}} pairs, to
-give an explicit section name and base address for that section. You
-can specify any @var{address} as an expression.
+this out for itself. You can additionally specify an arbitrary number
+of @samp{@r{-s}@var{section} @var{address}} pairs, to give an explicit
+section name and base address for that section. You can specify any
+@var{address} as an expression.
The symbol table of the file @var{filename} is added to the symbol table
originally read with the @code{symbol-file} command. You can use the
@value{GDBN} could not find the full definition for a struct or class.
@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{}
-The symbol information for a C++ member function is missing some
+The symbol information for a C@t{++} member function is missing some
information that recent versions of the compiler should have output for
it.
@cindex choosing target byte order
@cindex target byte order
-@kindex set endian big
-@kindex set endian little
-@kindex set endian auto
-@kindex show endian
Some types of processors, such as the MIPS, PowerPC, and Hitachi SH,
offer the ability to run either big-endian or little-endian byte
@table @code
@item i386-stub.c
-@kindex i386-stub.c
+@cindex @file{i386-stub.c}
@cindex Intel
@cindex i386
For Intel 386 and compatible architectures.
@item m68k-stub.c
-@kindex m68k-stub.c
+@cindex @file{m68k-stub.c}
@cindex Motorola 680x0
@cindex m680x0
For Motorola 680x0 architectures.
@item sh-stub.c
-@kindex sh-stub.c
+@cindex @file{sh-stub.c}
@cindex Hitachi
@cindex SH
For Hitachi SH architectures.
@item sparc-stub.c
-@kindex sparc-stub.c
+@cindex @file{sparc-stub.c}
@cindex Sparc
For @sc{sparc} architectures.
@item sparcl-stub.c
-@kindex sparcl-stub.c
+@cindex @file{sparcl-stub.c}
@cindex Fujitsu
@cindex SparcLite
For Fujitsu @sc{sparclite} architectures.
@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
+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.
@cindex protocol, @value{GDBN} remote serial
@cindex serial protocol, @value{GDBN} remote
@cindex remote serial protocol
-All @value{GDBN} commands and responses (other than acknowledgments)
-are sent as a @var{packet}. A @var{packet} is introduced with the
-character @samp{$}, this is followed by an optional two-digit
-@var{sequence-id} and the character @samp{:}, the actual
-@var{packet-data}, and the terminating character @samp{#} followed by a
-two-digit @var{checksum}:
+All @value{GDBN} commands and responses (other than acknowledgments) are
+sent as a @var{packet}. A @var{packet} is introduced with the character
+@samp{$}, the actual @var{packet-data}, and the terminating character
+@samp{#} followed by a two-digit @var{checksum}:
@example
@code{$}@var{packet-data}@code{#}@var{checksum}
@end example
@noindent
-or, with the optional @var{sequence-id}:
-@example
-@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
-@end example
@cindex checksum, for @value{GDBN} remote
@noindent
The two-digit @var{checksum} is computed as the modulo 256 sum of all
-characters between the leading @samp{$} and the trailing @samp{#} (that
-consisting of both the optional @var{sequence-id}@code{:} and the actual
-@var{packet-data}) (an eight bit unsigned checksum).
+characters between the leading @samp{$} and the trailing @samp{#} (an
+eight bit unsigned checksum).
+
+Implementors should note that prior to @value{GDBN} 5.0 the protocol
+specification also included an optional two-digit @var{sequence-id}:
+
+@example
+@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
+@end example
@cindex sequence-id, for @value{GDBN} remote
@noindent
-The two-digit @var{sequence-id}, when present, is returned with the
-acknowledgment. Beyond that its meaning is poorly defined.
-@value{GDBN} is not known to output @var{sequence-id}s.
+That @var{sequence-id} was appended to the acknowledgment. @value{GDBN}
+has never output @var{sequence-id}s. Stubs that handle packets added
+since @value{GDBN} 5.0 must not accept @var{sequence-id}.
+@cindex acknowledgment, for @value{GDBN} remote
When either the host or the target machine receives a packet, the first
response expected is an acknowledgment: either @samp{+} (to indicate
the package was received correctly) or @samp{-} (to request
-> @code{+}
@end example
@noindent
-If the received packet included a @var{sequence-id} than that is
-appended to a positive acknowledgment:
-
-@example
-<- @code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
--> @code{+}@var{sequence-id}
-@end example
The host (@value{GDBN}) sends @var{command}s, and the target (the
debugging stub incorporated in your program) sends a @var{response}. In
when the operation has completed (the target has again stopped).
@var{packet-data} consists of a sequence of characters with the
-exception of @samp{#} and @samp{$} (see @samp{X} packet for an
-exception). @samp{:} can not appear as the third character in a packet.
-Fields within the packet should be separated using @samp{,} and @samp{;}
-(unfortunately some packets chose to use @samp{:}). Except where
-otherwise noted all numbers are represented in HEX with leading zeros
-suppressed.
+exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
+exceptions).
+
+Fields within the packet should be separated using @samp{,} @samp{;} or
+@samp{:}. Except where otherwise noted all numbers are represented in
+HEX with leading zeros suppressed.
+
+Implementors should note that prior to @value{GDBN} 5.0, the character
+@samp{:} could not appear as the third character in a packet (as it
+would potentially conflict with the @var{sequence-id}).
Response @var{data} can be run-length encoded to save space. A @samp{*}
means that the next character is an @sc{ascii} encoding giving a repeat count
@noindent
means the same as "0000".
-The error response, returned for some packets includes a two character
+The error response returned for some packets includes a two character
error number. That number is not well defined.
For any @var{command} not supported by the stub, an empty response
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
+optional.
+
Below is a complete list of all currently defined @var{command}s and
their corresponding response @var{data}:
-
+@page
@multitable @columnfractions .30 .30 .40
@item Packet
@tab Request
@tab Description
-@item extended ops @emph{(optional)}
+@item extended ops
@tab @code{!}
@tab
Use the extended remote protocol. Sticky---only needs to be set once.
-The extended remote protocol support the @samp{R} packet.
+The extended remote protocol supports the @samp{R} packet.
@item
@tab reply @samp{}
@tab
@tab @code{a}
@tab Reserved for future use
-@item set program arguments @strong{(reserved)} @emph{(optional)}
+@item set program arguments @strong{(reserved)}
@tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...}
@tab
+@item
+@tab
+@tab
Initialized @samp{argv[]} array passed into program. @var{arglen}
specifies the number of bytes in the hex encoded byte stream @var{arg}.
See @file{gdbserver} for more details.
@tab reply
@tab see below
-@item continue with signal @emph{(optional)}
+@item continue with signal
@tab @code{C}@var{sig}@code{;}@var{addr}
@tab
Continue with signal @var{sig} (hex signal number). If
@tab reply
@tab see below
-@item toggle debug @emph{(deprecated)}
+@item toggle debug @strong{(deprecated)}
@tab @code{d}
@tab
toggle debug flag.
-@item detach @emph{(optional)}
+@item detach
@tab @code{D}
@tab
Detach @value{GDBN} from the remote system. Sent to the remote target before
@item
@tab reply @emph{no response}
@tab
-@value{GDBN} does not check for any response after sending this packet
+@value{GDBN} does not check for any response after sending this packet.
@item reserved
@tab @code{e}
@tab @code{h}
@tab Reserved for future use
-@item set thread @emph{(optional)}
+@item set thread
@tab @code{H}@var{c}@var{t...}
@tab
Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
@c selected, sets the registers of the register block of
@c that thread; otherwise sets current registers.
-@item cycle step @strong{(draft)} @emph{(optional)}
+@item cycle step @strong{(draft)}
@tab @code{i}@var{addr}@code{,}@var{nnn}
@tab
Step the remote target by a single clock cycle. If @code{,}@var{nnn} is
present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
step starting at that address.
-@item signal then cycle step @strong{(reserved)} @emph{(optional)}
+@item signal then cycle step @strong{(reserved)}
@tab @code{I}
@tab
See @samp{i} and @samp{S} for likely syntax and semantics.
@tab @code{J}
@tab Reserved for future use
-@item kill request @emph{(optional)}
+@item kill request
@tab @code{k}
@tab
FIXME: @emph{There is no description of how operate when a specific
@tab return @var{r....}
@tab The hex encoded value of the register in target byte order.
-@item write reg @emph{(optional)}
+@item write reg
@tab @code{P}@var{n...}@code{=}@var{r...}
@tab
Write register @var{n...} with value @var{r...}, which contains two hex
@tab reply @code{E}@var{NN}
@tab for an error
-@item general query @emph{(optional)}
+@item general query
@tab @code{q}@var{query}
@tab
-Request info about @var{query}. In general @value{GDBN} @var{query}'s
+Request info about @var{query}. In general @value{GDBN} queries
have a leading upper case letter. Custom vendor queries should use a
company prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may
optionally be followed by a @samp{,} or @samp{;} separated list. Stubs
@tab reply @samp{}
@tab Indicating an unrecognized @var{query}.
-@item general set @emph{(optional)}
+@item general set
@tab @code{Q}@var{var}@code{=}@var{val}
@tab
Set value of @var{var} to @var{val}. See @samp{q} for a discussing of
naming conventions.
-@item reset @emph{(deprecated)}
+@item reset @strong{(deprecated)}
@tab @code{r}
@tab
Reset the entire system.
-@item remote restart @emph{(optional)}
+@item remote restart
@tab @code{R}@var{XX}
@tab
Restart the remote server. @var{XX} while needed has no clear
definition. FIXME: @emph{An example interaction explaining how this
packet is used in extended-remote mode is needed}.
-@item step @emph{(optional)}
+@item step
@tab @code{s}@var{addr}
@tab
@var{addr} is address to resume. If @var{addr} is omitted, resume at
@tab reply
@tab see below
-@item step with signal @emph{(optional)}
+@item step with signal
@tab @code{S}@var{sig}@code{;}@var{addr}
@tab
Like @samp{C} but step not continue.
@tab reply
@tab see below
-@item search @emph{(optional)}
+@item search
@tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM}
@tab
Search backwards starting at address @var{addr} for a match with pattern
@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4
bytes. @var{addr} must be at least 3 digits.
-@item thread alive @emph{(optional)}
+@item thread alive
@tab @code{T}@var{XX}
@tab Find out if the thread XX is alive.
@item
@tab @code{x}
@tab Reserved for future use
-@item write mem (binary) @emph{(optional)}
+@item write mem (binary)
@tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...}
@tab
@var{addr} is address, @var{length} is number of bytes, @var{XX...} is
@tab @code{Y}
@tab Reserved for future use
-@item remove break or watchpoint @strong{(draft)} @emph{(optional)}
+@item remove break or watchpoint @strong{(draft)}
@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
@tab
See @samp{Z}.
-@item insert break or watchpoint @strong{(draft)} @emph{(optional)}
+@item insert break or watchpoint @strong{(draft)}
@tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length}
@tab
@var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware
@tab reply @code{m}@var{<id>}
@tab A single thread id
@item
-@tab reply @code{m}@var{<id>,}@var{<id>...}
+@tab reply @code{m}@var{<id>},@var{<id>...}
@tab a comma-separated list of thread ids
@item
@tab reply @code{l}
(lower-case el, for @code{'last'}).
@item extra thread info
-@tab @code{qfThreadExtraInfo,}@var{<id>}
+@tab @code{q}@code{ThreadExtraInfo}@code{,}@var{id}
@tab
@item
@tab
@item thread info request
@tab @code{q}@code{P}@var{mode}@var{threadid}
@tab
+@item
+@tab
+@tab
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.
@item
@item remote command
@tab @code{q}@code{Rcmd,}@var{COMMAND}
@tab
+@item
+@tab
+@tab
@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
@node Remote Log
@subsubsection Remote log
-@kindex eb.log
+@cindex @file{eb.log}, a log file for EB29K
@cindex log file for EB29K
The @code{target amd-eb} command creates a file @file{eb.log} in the
@item target mon960 @var{dev}
MON960 monitor for Intel i960.
+@kindex target nindy
@item target nindy @var{devicename}
An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
the name of the serial device to use for the connection, e.g.
By using the @code{target} command at any point during your @value{GDBN}
session. @xref{Target Commands, ,Commands for managing targets}.
-@kindex target nindy
-@item target nindy @var{devicename}
-An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
-the name of the serial device to use for the connection, e.g.
-@file{/dev/ttya}.
-
@end itemize
@cindex download to Nindy-960
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 CPO registers appropriate for the 3041 chip.
+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.
@code{@value{GDBP}} is installed and executed on the Unix host.
@table @code
-@item timeout @var{args}
+@item remotetimeout @var{args}
@kindex remotetimeout
@value{GDBN} supports the option @code{remotetimeout}.
This option is set by the user, and @var{args} represents the number of
seconds @value{GDBN} waits for responses.
@end table
-@kindex Compiling
+@cindex compiling, on Sparclet
When compiling for debugging, include the options @samp{-g} to get debug
information and @samp{-Ttext} to relocate the program to where you wish to
load it on the target. You may also want to add the options @samp{-n} or
sparclet-aout-objdump --headers --syms prog
@end example
-@kindex Running
+@cindex running, on Sparclet
Once you have set
your Unix execution search path to find @value{GDBN}, you are ready to
run @value{GDBN}. From your Unix host, run @code{@value{GDBP}}
commands:
@table @code
-@cindex @code{heuristic-fence-post} (Alpha,MIPS)
+@cindex @code{heuristic-fence-post} (Alpha, MIPS)
@item set heuristic-fence-post @var{limit}
Restrict @value{GDBN} to examining at most @var{limit} bytes in its
search for the beginning of a function. A value of @var{0} (the
@end table
@table @code
-@kindex show commands
+@kindex shows
@item show commands
Display the last ten commands in the command history.
debugging info.
@kindex set debug overload
@item set debug overload
-Turns on or off display of @value{GDBN} C++ overload debugging
+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++ overload
+Displays the current state of displaying @value{GDBN} C@t{++} overload
debugging info.
@kindex set debug remote
@cindex packets, reporting on stdout
@section User-defined command hooks
@cindex command hooks
@cindex hooks, for commands
+@cindex hooks, pre-command
-You may define @emph{hooks}, which are a special kind of user-defined
+@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)
before that command.
+@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
+that command. Post-execution hooks may exist simultaneously with
+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.
+
+@c It would be nice if hookpost could be passed a parameter indicating
+@c if the command it hooks executed properly or not. FIXME!
+
@kindex stop@r{, a pseudo-command}
In addition, a pseudo-command, @samp{stop} exists. Defining
(@samp{hook-stop}) makes the associated commands execute every time
end
@end example
+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,
+you could define:
+
+@example
+define hook-echo
+echo <<<---
+end
+
+define hookpost-echo
+echo --->>>\n
+end
+
+(@value{GDBP}) echo Hello World
+<<<---Hello World--->>>
+(@value{GDBP})
+
+@end example
+
You can define a hook for any single-word command in @value{GDBN}, but
not for command aliases; you should define a hook for the basic command
name, e.g. @code{backtrace} rather than @code{bt}.
@cindex @file{.gdbinit}
@cindex @file{gdb.ini}
When you start @value{GDBN}, it automatically executes commands from its
-@dfn{init files}. These are files named @file{.gdbinit} on Unix, or
-@file{gdb.ini} on DOS/Windows. @value{GDBN} reads the init file (if
-any) in your home directory@footnote{On DOS/Windows systems, the home
-directory is the one pointed to by the @code{HOME} environment
-variable.}, then processes command line options and operands, and then
-reads the init file (if any) in the current working directory. This is
-so the init file in your home directory can set options (such as
-@code{set complaints}) which affect the processing of the command line
-options and operands. The init files are not executed if you use the
-@samp{-nx} option; @pxref{Mode Options, ,Choosing modes}.
+@dfn{init files}. These are files named @file{.gdbinit} on Unix and
+@file{gdb.ini} on DOS/Windows. During startup, @value{GDBN} does the
+following:
+
+@enumerate
+@item
+Reads the init file (if any) in your home directory@footnote{On
+DOS/Windows systems, the home directory is the one pointed to by the
+@code{HOME} environment variable.}.
+
+@item
+Processes command line options and operands.
+
+@item
+Reads the init file (if any) in the current working directory.
+
+@item
+Reads command files specified by the @samp{-x} option.
+@end enumerate
+
+The init file in your home directory can set options (such as @samp{set
+complaints}) that affect subsequent processing of command line options
+and operands. Init files are not executed if you use the @samp{-nx}
+option (@pxref{Mode Options, ,Choosing modes}).
@cindex init file name
On some configurations of @value{GDBN}, the init file is known by a
different name for the specialized version's init file). These are the
environments with special init file names:
-@kindex .vxgdbinit
+@cindex @file{.vxgdbinit}
@itemize @bullet
@item
-VxWorks (Wind River Systems real-time OS): @samp{.vxgdbinit}
+VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
-@kindex .os68gdbinit
+@cindex @file{.os68gdbinit}
@item
-OS68K (Enea Data Systems real-time OS): @samp{.os68gdbinit}
+OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
-@kindex .esgdbinit
+@cindex @file{.esgdbinit}
@item
-ES-1800 (Ericsson Telecom AB M68000 emulator): @samp{.esgdbinit}
+ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
@end itemize
You can also request the execution of a command file with the
each value is printed in its own window.
@end ignore
-@node Annotations
-@chapter @value{GDBN} Annotations
@include annotate.texi
+@include gdbmi.texinfo
@node GDB Bugs
@chapter Reporting Bugs in @value{GDBN}
@c inc-hist.texinfo
@c Use -I with makeinfo to point to the appropriate directory,
@c environment var TEXINPUTS with TeX.
-
-@node Command Line Editing
-@chapter Command Line Editing
@include rluser.texinfo
-
-
-@node Using History Interactively
-@chapter Using History Interactively
@include inc-hist.texinfo
% Blame: doc@cygnus.com, 1991.
@end tex
+@c TeX can handle the contents at the start but makeinfo 3.12 can not
+@ifinfo
+@contents
+@end ifinfo
+@ifhtml
@contents
+@end ifhtml
+
@bye
projects / deliverable / binutils-gdb.git / blobdiff