\input texinfo @c -*-texinfo-*-
-@c Copyright 1988-1999
+@c Copyright 1988-2000
@c Free Software Foundation, Inc.
@c
-@c %**start of header
+@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@c of @set vars. However, you can override filename with makeinfo -o.
@setfilename gdb.info
@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 Seventh
+@set EDITION Eighth
@c !!set GDB manual's revision date
-@set DATE February 1999
+@set DATE March 2000
-@c THIS MANUAL REQUIRES TEXINFO-2 macros and info-makers to format properly.
+@c THIS MANUAL REQUIRES TEXINFO 3.12 OR LATER.
-@ifinfo
@c This is a dir.info fragment to support semi-automated addition of
-@c manuals to an info tree. zoo@cygnus.com is developing this facility.
-@format
-START-INFO-DIR-ENTRY
+@c manuals to an info tree.
+@dircategory Programming & development tools.
+@direntry
* Gdb: (gdb). The @sc{gnu} debugger.
-END-INFO-DIR-ENTRY
-@end format
-@end ifinfo
-@c
-@c
+@end direntry
+
@ifinfo
This file documents the @sc{gnu} debugger @value{GDBN}.
-This is the @value{EDITION} Edition, @value{DATE},
+This is the @value{EDITION} Edition, @value{DATE},
of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger}
for @value{GDBN} Version @value{GDBVN}.
-Copyright (C) 1988-1999 Free Software Foundation, Inc.
+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
@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
-@c ISBN seems to be wrong...
-
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988-1999 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2000 Free Software Foundation, Inc.
@sp 2
Published by the Free Software Foundation @*
59 Temple Place - Suite 330, @*
Boston, MA 02111-1307 USA @*
-Printed copies are available for $20 each. @*
-ISBN 1-882114-11-6 @*
+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
@page
@ifinfo
+@node Top, Summary, (dir), (dir)
+
+@top Debugging with @value{GDBN}
+
+This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
+
+This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
+@value{GDBVN}.
+
+Copyright (C) 1988-2000 Free Software Foundation, Inc.
+
+@menu
+* Summary:: Summary of @value{GDBN}
+* Sample Session:: A sample @value{GDBN} session
+
+* Invocation:: Getting in and out of @value{GDBN}
+* Commands:: @value{GDBN} commands
+* Running:: Running programs under @value{GDBN}
+* Stopping:: Stopping and continuing
+* Stack:: Examining the stack
+* Source:: Examining source files
+* Data:: Examining data
+
+* Languages:: Using @value{GDBN} with different languages
+
+* Symbols:: Examining the symbol table
+* Altering:: Altering execution
+* GDB Files:: @value{GDBN} files
+* Targets:: Specifying a debugging target
+* Configurations:: Configuration-specific information
+* Controlling GDB:: Controlling @value{GDBN}
+* 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
+
+* Command Line Editing:: Command Line Editing
+* Using History Interactively:: Using History Interactively
+* Installing GDB:: Installing GDB
+* Index:: Index
+@end menu
+
+@end ifinfo
+
+@c the replication sucks, but this avoids a texinfo 3.12 lameness
+
+@ifhtml
@node Top
+
@top Debugging with @value{GDBN}
This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
@value{GDBVN}.
-Copyright (C) 1988-1999 Free Software Foundation, Inc.
+Copyright (C) 1988-2000 Free Software Foundation, Inc.
+
@menu
* Summary:: Summary of @value{GDBN}
* Sample Session:: A sample @value{GDBN} session
* Controlling GDB:: Controlling @value{GDBN}
* Sequences:: Canned sequences of commands
* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
+* Annotations:: @value{GDBN}'s annotation interface.
* GDB Bugs:: Reporting bugs in @value{GDBN}
* Formatting Documentation:: How to format and print @value{GDBN} documentation
* Index:: Index
@end menu
-@end ifinfo
+@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}
@node Free Software
@unnumberedsec Free software
-@value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
+@value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
General Public License
(GPL). The GPL gives you the freedom to copy or adapt a licensed
program---but every person getting a copy also gets with it the
from anyone else.
@node Contributors
-@unnumberedsec Contributors to GDB
-
-Richard Stallman was the original author of GDB, and of many other
-@sc{gnu} programs. Many others have contributed to its development.
-This section attempts to credit major contributors. One of the virtues
-of free software is that everyone is free to contribute to it; with
-regret, we cannot actually acknowledge everyone here. The file
-@file{ChangeLog} in the @value{GDBN} distribution approximates a
+@unnumberedsec Contributors to @value{GDBN}
+
+Richard Stallman was the original author of @value{GDBN}, and of many
+other @sc{gnu} programs. Many others have contributed to its
+development. This section attempts to credit major contributors. One
+of the virtues of free software is that everyone is free to contribute
+to it; with regret, we cannot actually acknowledge everyone here. The
+file @file{ChangeLog} in the @value{GDBN} distribution approximates a
blow-by-blow account.
Changes much prior to version 2.0 are lost in the mists of time.
So that they may not regard their many labors as thankless, we
particularly thank those who shepherded @value{GDBN} through major
releases:
+Andrew Cagney (release 5.0);
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 GDB,
-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++ 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).
@value{GDBN} 4 uses the BFD subroutine library to examine multiple
object-file formats; BFD was a joint project of David V.
Andrew Beers of SUNY Buffalo wrote the language-switching code, the
Modula-2 support, and contributed the Languages chapter of this manual.
-Fred Fish wrote most of the support for Unix System Vr4.
+Fred Fish wrote most of the support for Unix System Vr4.
He also enhanced the command-completion support to cover C++ overloaded
symbols.
Matsushita sponsored the support for the MN10200 and MN10300 processors.
-Fujitsu sponsored the support for SPARClite and FR30 processors
+Fujitsu sponsored the support for SPARClite and FR30 processors.
Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
watchpoints.
Stu Grossman wrote gdbserver.
Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made
-nearly innumerable bug fixes and cleanups throughout GDB.
+nearly innumerable bug fixes and cleanups throughout @value{GDBN}.
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
Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific
information in this manual.
-Cygnus Solutions has sponsored GDB maintenance and much of its
-development since 1991. Cygnus engineers who have worked on GDB
+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
Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
@c FIXME: this falsifies the exact text played out, to permit smallbook
@c FIXME... format to come out better.
@value{GDBN} is free software and you are welcome to distribute copies
- of it under certain conditions; type "show copying" to see
+ of it under certain conditions; type "show copying" to see
the conditions.
-There is absolutely no warranty for @value{GDBN}; type "show warranty"
+There is absolutely no warranty for @value{GDBN}; type "show warranty"
for details.
@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc...
@smallexample
@b{changequote(<QUOTE>,<UNQUOTE>)}
-Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
+Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
at builtin.c:879
879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
@end smallexample
(@value{GDBP}) @b{bt}
#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
at input.c:530
-#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
+#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
at builtin.c:882
#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
@chapter Getting In and Out of @value{GDBN}
This chapter discusses how to start @value{GDBN}, and how to get out of it.
-The essentials are:
+The essentials are:
@itemize @bullet
-@item
+@item
type @samp{@value{GDBP}} to start @value{GDBN}.
-@item
+@item
type @kbd{quit} or @kbd{C-d} to exit.
@end itemize
The command-line options described here are designed
to cover a variety of situations; in some environments, some of these
-options may effectively be unavailable.
+options may effectively be unavailable.
The most usual way to start @value{GDBN} is with one argument,
specifying an executable program:
``process'', and there is often no way to get a core dump. @value{GDBN}
will warn you if it is unable to attach or to read core dumps.
-You can run @code{gdb} without printing the front material, which describes
+You can run @code{@value{GDBP}} without printing the front material, which describes
@value{GDBN}'s non-warranty, by specifying @code{-silent}:
@smallexample
(If you prefer, you can flag option arguments with @samp{--} rather
than @samp{-}, though we illustrate the more usual convention.)
+@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This
+@c way, both those who look for -foo and --foo in the index, will find
+@c it.
+
@table @code
@item -symbols @var{file}
@itemx -s @var{file}
+@cindex @code{--symbols}
+@cindex @code{-s}
Read symbol table from file @var{file}.
@item -exec @var{file}
@itemx -e @var{file}
+@cindex @code{--exec}
+@cindex @code{-e}
Use file @var{file} as the executable file to execute when appropriate,
and for examining pure data in conjunction with a core dump.
@item -se @var{file}
+@cindex @code{--se}
Read symbol table from file @var{file} and use it as the executable
file.
@item -core @var{file}
@itemx -c @var{file}
+@cindex @code{--core}
+@cindex @code{-c}
Use file @var{file} as a core dump to examine.
@item -c @var{number}
@item -command @var{file}
@itemx -x @var{file}
+@cindex @code{--command}
+@cindex @code{-x}
Execute @value{GDBN} commands from file @var{file}. @xref{Command
Files,, Command files}.
@item -directory @var{directory}
@itemx -d @var{directory}
+@cindex @code{--directory}
+@cindex @code{-d}
Add @var{directory} to the path to search for source files.
@item -m
@itemx -mapped
+@cindex @code{--mapped}
+@cindex @code{-m}
@emph{Warning: this option depends on operating system facilities that are not
supported on all systems.}@*
If memory-mapped files are available on your system through the @code{mmap}
-system call, you can use this option
+system call, you can use this option
to have @value{GDBN} write the symbols from your
program into a reusable file in the current directory. If the program you are debugging is
-called @file{/tmp/fred}, the mapped symbol file is @file{./fred.syms}.
+called @file{/tmp/fred}, the mapped symbol file is @file{/tmp/fred.syms}.
Future @value{GDBN} debugging sessions notice the presence of this file,
and can quickly map in symbol information from it, rather than reading
the symbol table from the executable program.
@item -r
@itemx -readnow
+@cindex @code{--readnow}
+@cindex @code{-r}
Read each symbol file's entire symbol table immediately, rather than
the default, which is to read it incrementally as it is needed.
This makes startup slower, but makes future operations faster.
@table @code
@item -nx
@itemx -n
+@cindex @code{--nx}
+@cindex @code{-n}
Do not execute commands found in any initialization files (normally
called @file{.gdbinit}, or @file{gdb.ini} on PCs). Normally,
@value{GDBN} executes the commands in these files after all the command
files}.
@item -quiet
+@itemx -silent
@itemx -q
+@cindex @code{--quiet}
+@cindex @code{--silent}
+@cindex @code{-q}
``Quiet''. Do not print the introductory and copyright messages. These
messages are also suppressed in batch mode.
@item -batch
+@cindex @code{--batch}
Run in batch mode. Exit with status @code{0} after processing all the
command files specified with @samp{-x} (and all commands from
initialization files, if not inhibited with @samp{-n}). Exit with
@item -nowindows
@itemx -nw
+@cindex @code{--nowindows}
+@cindex @code{-nw}
``No windows''. If @value{GDBN} comes with a graphical user interface
-(GUI) built in, then this option tells GDB to only use the command-line
+(GUI) built in, then this option tells @value{GDBN} to only use the command-line
interface. If no GUI is available, this option has no effect.
@item -windows
@itemx -w
+@cindex @code{--windows}
+@cindex @code{-w}
If @value{GDBN} includes a GUI, then this option requires it to be
used if possible.
@item -cd @var{directory}
+@cindex @code{--cd}
Run @value{GDBN} using @var{directory} as its working directory,
instead of the current directory.
@item -fullname
@itemx -f
+@cindex @code{--fullname}
+@cindex @code{-f}
@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a
subprocess. It tells @value{GDBN} to output the full file name and line
number in a standard, recognizable fashion each time a stack frame is
@samp{\032} characters as a signal to display the source code for the
frame.
+@item -epoch
+@cindex @code{--epoch}
+The Epoch Emacs-@value{GDBN} interface sets this option when it runs
+@value{GDBN} as a subprocess. It tells @value{GDBN} to modify its print
+routines so as to allow Epoch to display values of expressions in a
+separate window.
+
+@item -annotate @var{level}
+@cindex @code{--annotate}
+This option sets the @dfn{annotation level} inside @value{GDBN}. Its
+effect is identical to using @samp{set annotate @var{level}}
+(@pxref{Annotations}).
+Annotation level controls how much information does @value{GDBN} print
+together with its prompt, values of expressions, source lines, and other
+types of output. Level 0 is the normal, level 1 is for use when
+@value{GDBN} is run as a subprocess of @sc{gnu} Emacs, level 2 is the
+maximum annotation suitable for programs that control @value{GDBN}.
+
+@item -async
+@cindex @code{--async}
+Use the asynchronous event loop for the command-line interface.
+@value{GDBN} processes all events, such as user keyboard input, via a
+special event loop. This allows @value{GDBN} to accept and process user
+commands in parallel with the debugged process being
+run@footnote{@value{GDBN} built with @sc{djgpp} tools for
+MS-DOS/MS-Windows supports this mode of operation, but the event loop is
+suspended when the debuggee runs.}, so you don't need to wait for
+control to return to @value{GDBN} before you type the next command.
+(@emph{Note:} as of version 5.0, the target side of the asynchronous
+operation is not yet in place, so @samp{-async} does not work fully
+yet.)
+@c FIXME: when the target side of the event loop is done, the above NOTE
+@c should be removed.
+
+When the standard input is connected to a terminal device, @value{GDBN}
+uses the asynchronous event loop by default, unless disabled by the
+@samp{-noasync} option.
+
+@item -noasync
+@cindex @code{--noasync}
+Disable the asynchronous event loop for the command-line interface.
+
@item -baud @var{bps}
@itemx -b @var{bps}
+@cindex @code{--baud}
+@cindex @code{-b}
Set the line speed (baud rate or bits per second) of any serial
interface used by @value{GDBN} for remote debugging.
@item -tty @var{device}
+@itemx -t @var{device}
+@cindex @code{--tty}
+@cindex @code{-t}
Run using @var{device} for your program's standard input and output.
@c FIXME: kingdon thinks there is more to -tty. Investigate.
@c resolve the situation of these eventually
@c @item -tui
+@c @cindex @code{--tui}
@c Use a Terminal User Interface. For information, use your Web browser to
@c read the file @file{TUI.html}, which is usually installed in the
@c directory @code{/opt/langtools/wdb/doc} on HP-UX systems. Do not use
@c @value{GDBN} under @sc{gnu} Emacs}).
@c @item -xdb
+@c @cindex @code{--xdb}
@c Run in XDB compatibility mode, allowing the use of certain XDB commands.
@c For information, see the file @file{xdb_trans.html}, which is usually
@c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX
@c systems.
+@item -interpreter @var{interp}
+@cindex @code{--interpreter}
+Use the interpreter @var{interp} for interface with the controlling
+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} (@pxref{GDB/MI, , The @sc{gdb/mi} Interface}).
+
+@item -write
+@cindex @code{--write}
+Open the executable and core files for both reading and writing. This
+is equivalent to the @samp{set write on} command inside @value{GDBN}
+(@pxref{Patching}).
+
+@item -statistics
+@cindex @code{--statistics}
+This option causes @value{GDBN} to print statistics about time and
+memory usage after it completes each command and returns to the prompt.
+
+@item -version
+@cindex @code{--version}
+This option causes @value{GDBN} to print its version number and
+no-warranty blurb, and exit.
+
@end table
@node Quitting GDB
@table @code
@kindex quit @r{[}@var{expression}@r{]}
-@kindex q
-@item quit
-To exit @value{GDBN}, use the @code{quit} command (abbreviated @code{q}), or
-type an end-of-file character (usually @kbd{C-d}). If you do not supply
-@var{expression}, @value{GDBN} will terminate normally; otherwise it will
-terminate using the result of @var{expression} as the error code.
+@kindex q @r{(@code{quit})}
+@item quit @r{[}@var{expression}@r{]}
+@itemx q
+To exit @value{GDBN}, use the @code{quit} command (abbreviated
+@code{q}), or type an end-of-file character (usually @kbd{C-d}). If you
+do not supply @var{expression}, @value{GDBN} will terminate normally;
+otherwise it will terminate using the result of @var{expression} as the
+error code.
@end table
@cindex interrupt
arguments whose meaning depends on the command name. For example, the
command @code{step} accepts an argument which is the number of times to
step, as in @samp{step 5}. You can also use the @code{step} command
-with no arguments. Some command names do not allow any arguments.
+with no arguments. Some commands do not allow any arguments.
@cindex abbreviation
@value{GDBN} command names may always be truncated if that abbreviation is
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})
+repeat the previous command. Certain commands (for example, @code{run})
will not repeat this way; these are commands whose unintentional
repetition might cause trouble and which you are unlikely to want to
repeat.
@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
@example
(@value{GDBP}) b make_ @key{TAB}
@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
-make_a_section_from_file make_environ
-make_abs_section make_function_type
-make_blockvector make_pointer_type
-make_cleanup make_reference_type
+make_a_section_from_file make_environ
+make_abs_section make_function_type
+make_blockvector make_pointer_type
+make_cleanup make_reference_type
make_command make_symbol_completion_list
(@value{GDBP}) b make_
@end example
@kbd{M-?} to request word completion:
@example
-(@value{GDBP}) b 'bubble( @key{M-?}
+(@value{GDBP}) b 'bubble( @kbd{M-?}
bubble(double,double) bubble(int,int)
(@value{GDBP}) b 'bubble(
@end example
@cindex online documentation
@kindex help
-You can always ask @value{GDBN} itself for information on its commands,
+You can always ask @value{GDBN} itself for information on its commands,
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
stack -- Examining the stack
status -- Status inquiries
support -- Support facilities
-tracepoints -- Tracing of program execution without stopping the program
+tracepoints -- Tracing of program execution without@*
+ stopping the program
user-defined -- User-defined commands
-Type "help" followed by a class name for a list of
+Type "help" followed by a class name for a list of
commands in that class.
-Type "help" followed by command name for full
+Type "help" followed by command name for full
documentation.
Command name abbreviations are allowed if unambiguous.
(@value{GDBP})
@end smallexample
+@c the above line break eliminates huge line overfull...
@item help @var{class}
Using one of the general help classes as an argument, you can get a
show -- Generic command for showing things
about the debugger
-Type "help" followed by command name for full
+Type "help" followed by command name for full
documentation.
Command name abbreviations are allowed if unambiguous.
(@value{GDBP})
With a command name as @code{help} argument, @value{GDBN} displays a
short paragraph on how to use that command.
+@kindex apropos
+@item apropos @var{args}
+The @code{apropos @var{args}} command searches through all of the @value{GDBN}
+commands, and their documentation, for the regular expression specified in
+@var{args}. It prints out all matches found. For example:
+
+@smallexample
+apropos reload
+@end smallexample
+
+@noindent results in:
+
+@smallexample
+@c @group
+set symbol-reloading -- Set dynamic symbol table reloading
+ multiple times in one run
+show symbol-reloading -- Show dynamic symbol table reloading
+ multiple times in one run
+@c @end group
+@end smallexample
+
@kindex complete
@item complete @var{args}
The @code{complete @var{args}} command lists all the possible completions
@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
@kindex set
@item set
-You can assign the result of an expression to an environment variable with
+You can assign the result of an expression to an environment variable with
@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with
@code{set prompt $}.
@kindex show
@item show
-In contrast to @code{info}, @code{show} is for describing the state of
+In contrast to @code{info}, @code{show} is for describing the state of
@value{GDBN} itself.
You can change most of the things you can @code{show}, by using the
related command @code{set}; for example, you can control what number
version of @value{GDBN} you are running; as @value{GDBN} evolves, new
commands are introduced, and old ones may wither away. Also, many
system vendors ship variant versions of @value{GDBN}, and there are
-variant versions of @value{GDBN} in GNU/Linux distributions as well.
+variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well.
The version number is the same as the one announced when you start
@value{GDBN}.
@kindex show warranty
@item show warranty
Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
-if your version of @value{GDB} comes with one.
+if your version of @value{GDBN} comes with one.
@end table
@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}.
@cindex arguments (to your program)
The arguments to your program can be specified by the arguments of the
-@code{run} command.
+@code{run} command.
They are passed to a shell, which expands wildcard characters and
performs redirection of I/O, and thence to your program. Your
@code{SHELL} environment variable (if it exists) specifies what shell
@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
@cindex i/o
@cindex terminal
By default, the program you run under @value{GDBN} does input and output to
-the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
+the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
to its own terminal modes to interact with you, but it records the terminal
modes your program was using and switches back to them when you continue
running your program.
@item automatic notification of new threads
@item @samp{thread @var{threadno}}, a command to switch among threads
@item @samp{info threads}, a command to inquire about existing threads
-@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
+@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
a command to apply a command to a list of threads
@item thread-specific breakpoints
@end itemize
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
@c program?
@c (2) *Is* there necessarily a first thread always? Or do some
@c multithread systems permit starting a program with multiple
-@c threads ab initio?
+@c threads ab initio?
@cindex thread number
@cindex thread identifier (GDB)
An asterisk @samp{*} to the left of the @value{GDBN} thread number
indicates the current thread.
-For example,
+For example,
@end table
@c end table here to get a little more width for example
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'.
@end example
@noindent
-when @value{GDBN} notices a new thread.
+when @value{GDBN} notices a new thread.
@table @code
@kindex info threads
An asterisk @samp{*} to the left of the @value{GDBN} thread number
indicates the current thread.
-For example,
+For example,
@end table
@c end table here to get a little more width for example
@example
(@value{GDBP}) info threads
- * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") at quicksort.c:137
- 2 system thread 26606 0x7b0030d8 in __ksleep () from /usr/lib/libc.2
- 1 system thread 27905 0x7b003498 in _brk () from /usr/lib/libc.2
+ * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@*
+ at quicksort.c:137
+ 2 system thread 26606 0x7b0030d8 in __ksleep () \@*
+ from /usr/lib/libc.2
+ 1 system thread 27905 0x7b003498 in _brk () \@*
+ from /usr/lib/libc.2
@end example
@table @code
@noindent
As with the @samp{[New @dots{}]} message, the form of the text after
@samp{Switching to} depends on your system's conventions for identifying
-threads.
+threads.
@kindex thread apply
@item thread apply [@var{threadno}] [@var{all}] @var{args}
more threads. Specify the numbers of the threads that you want affected
with the command argument @var{threadno}. @var{threadno} is the internal
@value{GDBN} thread number, as shown in the first field of the @samp{info
-threads} display. To apply a command to all threads, use
-@code{thread apply all} @var{args}.
+threads} display. To apply a command to all threads, use
+@code{thread apply all} @var{args}.
@end table
@cindex automatic thread selection
@dfn{disabled}; if disabled, it has no effect on your program until you
enable it again.
+@cindex breakpoint ranges
+@cindex ranges of breakpoints
+Some @value{GDBN} commands accept a range of breakpoints on which to
+operate. A breakpoint range is either a single breakpoint number, like
+@samp{5}, or two such numbers, in increasing order, separated by a
+hyphen, like @samp{5-7}. When a breakpoint range is given to a command,
+all breakpoint in that range are operated on.
+
@menu
* Set Breaks:: Setting breakpoints
* Set Watchpoints:: Setting watchpoints
@node Set Breaks
@subsection Setting breakpoints
-@c FIXME LMB what does GDB do if no code on line of breakpt?
+@c FIXME LMB what does GDB do if no code on line of breakpt?
@c consider in particular declaration with/without initialization.
@c
@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
+@code{b}). The debugger convenience variable @samp{$bpnum} records the
+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.
@table @code
@item break @var{function}
-Set a breakpoint at entry to function @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.
@xref{Breakpoint Menus,,Breakpoint menus}, for a discussion of that situation.
@item thbreak @var{args}
Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
are the same as for the @code{hbreak} command and the breakpoint is set in
-the same way. However, like the @code{tbreak} command,
+the same way. However, like the @code{tbreak} command,
the breakpoint is automatically deleted after the
first time your program stops there. Also, like the @code{hbreak}
-command, the breakpoint requires hardware support and some target hardware
-may not have this support. @xref{Disabling, ,Disabling breakpoints}.
+command, the breakpoint requires hardware support and some target hardware
+may not have this support. @xref{Disabling, ,Disabling breakpoints}.
See also @ref{Conditions, ,Break conditions}.
@kindex rbreak
@cindex regular expression
@item rbreak @var{regex}
-@c FIXME what kind of regexp?
Set breakpoints on all functions matching the regular expression
-@var{regex}. This command
-sets an unconditional breakpoint on all matches, printing a list of all
-breakpoints it set. Once these breakpoints are set, they are treated
-just like the breakpoints set with the @code{break} command. You can
-delete them, disable them, or make them conditional the same way as any
-other breakpoint.
+@var{regex}. This command sets an unconditional breakpoint on all
+matches, printing a list of all breakpoints it set. Once these
+breakpoints are set, they are treated just like the breakpoints set with
+the @code{break} command. You can delete them, disable them, or make
+them conditional the same way as any other breakpoint.
+
+The syntax of the regular expression is the standard one used with tools
+like @file{grep}. Note that this is different from the syntax used by
+shells, so for instance @code{foo*} matches all functions that include
+an @code{fo} followed by zero or more @code{o}s. There is an implicit
+@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
breakpoints on overloaded functions that are not members of any special
number @var{n} as argument lists only that breakpoint. The
convenience variable @code{$_} and the default examining-address for
the @code{x} command are set to the address of the last breakpoint
-listed (@pxref{Memory, ,Examining memory}).
+listed (@pxref{Memory, ,Examining memory}).
@noindent
@code{info break} displays a count of the number of times the breakpoint
@cindex delete breakpoints
@kindex delete
-@kindex d
-@item delete @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
-Delete the breakpoints, watchpoints, or catchpoints of the numbers
-specified as arguments. If no argument is specified, delete all
+@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
breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
confirm off}). You can abbreviate this command as @code{d}.
@end table
@table @code
@kindex disable breakpoints
@kindex disable
-@kindex dis
-@item disable @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
+@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
options such as ignore-counts, conditions and commands are remembered in
@kindex enable breakpoints
@kindex enable
-@item enable @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
+@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
Enable the specified breakpoints (or all defined breakpoints). They
become effective once again in stopping your program.
-@item enable @r{[}breakpoints@r{]} once @var{bnums}@dots{}
+@item enable @r{[}breakpoints@r{]} once @var{range}@dots{}
Enable the specified breakpoints temporarily. @value{GDBN} disables any
of these breakpoints immediately after stopping your program.
-@item enable @r{[}breakpoints@r{]} delete @var{bnums}@dots{}
+@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
Enable the specified breakpoints to work once, then die. @value{GDBN}
deletes any of these breakpoints as soon as your program stops there.
@end table
@cindex breakpoint conditions
@c FIXME what is scope of break condition expr? Context where wanted?
-@c in particular for a watchpoint?
+@c in particular for a watchpoint?
The simplest sort of breakpoint breaks every time your program reaches a
specified place. You can also specify a @dfn{condition} for a
breakpoint. A condition is just a Boolean expression in your
@c
Under some operating systems, breakpoints cannot be used in a program if
any other process is running that program. In this situation,
-attempting to run or continue a program with a breakpoint causes
+attempting to run or continue a program with a breakpoint causes
@value{GDBN} to print an error message:
@example
Remove or disable the breakpoints, then continue.
@item
-Suspend @value{GDBN}, and copy the file containing your program to a new
+Suspend @value{GDBN}, and copy the file containing your program to a new
name. Resume @value{GDBN} and use the @code{exec-file} command to specify
-that @value{GDBN} should run your program under that name.
+that @value{GDBN} should run your program under that name.
Then start your program again.
@item
@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
Also, the @code{step} command only enters a function if there is line
number information for the function. Otherwise it acts like the
-@code{next} command. This avoids problems when using @code{cc -gl}
+@code{next} command. This avoids problems when using @code{cc -gl}
on MIPS machines. Previously, @code{step} entered subroutines if there
-was any debugging information about the routine.
+was any debugging information about the routine.
@item step @var{count}
Continue running as in @code{step}, but do so @var{count} times. If a
@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.
+switch statements, for loops, etc.
@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
Execute one machine instruction, then stop and return to the debugger.
@need 750
@kindex nexti
-@kindex ni
+@kindex ni @r{(@code{nexti})}
@item nexti
+@itemx nexti @var{arg}
@itemx ni
Execute one machine instruction, but if it is a function call,
proceed until the function returns.
@table @code
@kindex info signals
@item info signals
+@itemx info handle
Print a table of all the kinds of signals and how @value{GDBN} has been told to
handle each one. You can use this to see the signal numbers of all
the defined types of signals.
@kindex handle
@item handle @var{signal} @var{keywords}@dots{}
-Change the way @value{GDBN} handles signal @var{signal}. @var{signal} can
+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.
@end table
execution; but your program would probably terminate immediately as
a result of the fatal signal once it saw the signal. To prevent this,
you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
-program a signal}.
+program a signal}.
@node Thread Stops
@section Stopping and starting multi-thread programs
@cindex threads, continuing
Conversely, whenever you restart the program, @emph{all} threads start
executing. @emph{This is true even when single-stepping} with commands
-like @code{step} or @code{next}.
+like @code{step} or @code{next}.
In particular, @value{GDBN} cannot single-step all threads in lockstep.
Since thread scheduling is up to your debugging target's operating
stopped and how it got there.
@cindex call stack
-Each time your program performs a function call, information about the call
-is generated.
-That information includes the location of the call in your program,
-the arguments of the call,
+Each time your program performs a function call, information about the call
+is generated.
+That information includes the location of the call in your program,
+the arguments of the call,
and the local variables of the function being called.
-The information is saved in a block of data called a @dfn{stack frame}.
+The information is saved in a block of data called a @dfn{stack frame}.
The stack frames are allocated in a region of memory called the @dfn{call
stack}.
interested in. @xref{Selection, ,Selecting a frame}.
When your program stops, @value{GDBN} automatically selects the
-currently executing frame and describes it briefly, similar to the
+currently executing frame and describes it briefly, similar to the
@code{frame} command (@pxref{Frame Info, ,Information about a frame}).
@menu
they are assigned by @value{GDBN} to give you a way of designating stack
frames in @value{GDBN} commands.
-@c below produces an acceptable overful hbox. --mew 13aug1993
+@c The -fomit-frame-pointer below perennially causes hbox overflow
+@c underflow problems.
@cindex frameless execution
Some compilers provide a way to compile functions so that they operate
-without stack frames. (For example, the @code{@value{GCC}} option
-@samp{-fomit-frame-pointer} generates functions without a frame.)
+without stack frames. (For example, the @value{GCC} option
+@example
+@samp{-fomit-frame-pointer}
+@end example
+generates functions without a frame.)
This is occasionally done with heavily used library functions to save
the frame setup time. @value{GDBN} has limited facilities for dealing
with these function invocations. If the innermost function invocation
@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,
+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
-address of the frame or the stack frame number. Without an argument,
-@code{frame} prints the current stack frame.
+address of the frame or the stack frame number. Without an argument,
+@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}.
@smallexample
@group
-#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
+#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
at builtin.c:993
#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
@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
All of these commands end by printing two lines of output describing the
frame. The first line shows the frame number, the function name, the
arguments, and the source file and line number of execution in that
-frame. The second line shows the text of that source line.
+frame. The second line shows the text of that source line.
@need 1000
For example:
@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,
including:
@itemize @bullet
-@item
-the address of the frame
+@item
+the address of the frame
@item
the address of the next frame down (called by this frame)
@item
@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.
+(abbreviated @code{l}). By default, ten lines are printed.
There are several ways to specify what part of the file you want to print.
Here are the forms of the @code{list} command most commonly used:
@itemx search @var{regexp}
The command @samp{forward-search @var{regexp}} checks each line,
starting with the one following the last line listed, for a match for
-@var{regexp}. It lists the line that is found. You can use the
+@var{regexp}. It lists the line that is found. You can use the
synonym @samp{search @var{regexp}} or abbreviate the command name as
@code{fo}.
@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
addresses (and vice versa), and the command @code{disassemble} to display
a range of addresses as machine instructions. When run under @sc{gnu} Emacs
mode, the @code{info line} command causes the arrow to point to the
-line specified. Also, @code{info line} prints addresses in symbolic form as
+line specified. Also, @code{info line} prints addresses in symbolic form as
well as hex.
@table @code
@c FIXME: I think this example should also show the addresses in
@c symbolic form, as they usually would be displayed.
@smallexample
-(@value{GDBP}) info line m4_changecom
+(@value{GDBP}) info line m4_changequote
Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
@end smallexample
@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,
@value{GDBN} supports array constants in expressions input by
the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example,
-you can use the command @code{print @{1, 2, 3@}} to build up an array in
+you can use the command @code{print @{1, 2, 3@}} to build up an array in
memory that is @code{malloc}ed in the target program.
Because C is so widespread, most of the expressions shown in examples in
global (or file-static)
@end itemize
-@noindent or
+@noindent or
@itemize @bullet
@item
visible according to the scope rules of the
programming language from the point of execution in that frame
-@end itemize
+@end itemize
@noindent This means that in the function
@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}
@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
@end example
As a convenience, if you leave the array length out (as in
-@samp{(@var{type}[])@var{value}}) gdb calculates the size to fill
+@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill
the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}:
@example
(@value{GDBP}) p/x (short[])0x12345678
@cindex examining memory
@table @code
-@kindex x
+@kindex x @r{(examine memory)}
@item x/@var{nfu} @var{addr}
@itemx x @var{addr}
@itemx x
@item set print max-symbolic-offset @var{max-offset}
Tell @value{GDBN} to only display the symbolic form of an address if the
offset between the closest earlier symbol and the address is less than
-@var{max-offset}. The default is 0, which tells @value{GDBN}
+@var{max-offset}. The default is 0, which tells @value{GDBN}
to always print the symbolic form of an address if any symbol precedes it.
@kindex show print max-symbolic-offset
@kindex set print pretty
@item set print pretty on
-Cause @value{GDBN} to print structures in an indented format with one member
+Cause @value{GDBN} to print structures in an indented format with one member
per line, like this:
@smallexample
@kindex set print union
@item set print union on
-Tell @value{GDBN} to print unions which are contained in structures. This
+Tell @value{GDBN} to print unions which are contained in structures. This
is the default setting.
@item set print union off
@smallexample
typedef enum @{Tree, Bug@} Species;
typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
-typedef enum @{Caterpillar, Cocoon, Butterfly@}
+typedef enum @{Caterpillar, Cocoon, Butterfly@}
Bug_forms;
struct thing @{
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++ compiler (@code{g++}) encoding algorithm.
This is the default.
@item hp
@section Value history
@cindex value history
-Values printed by the @code{print} command are saved in the @value{GDBN}
-@dfn{value history}. This allows you to refer to them in other expressions.
-Values are kept until the symbol table is re-read or discarded
-(for example with the @code{file} or @code{symbol-file} commands).
-When the symbol table changes, the value history is discarded,
-since the values may contain pointers back to the types defined in the
+Values printed by the @code{print} command are saved in the @value{GDBN}
+@dfn{value history}. This allows you to refer to them in other expressions.
+Values are kept until the symbol table is re-read or discarded
+(for example with the @code{file} or @code{symbol-file} commands).
+When the symbol table changes, the value history is discarded,
+since the values may contain pointers back to the types defined in the
symbol table.
@cindex @code{$}
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
@item info registers @var{regname} @dots{}
Print the @dfn{relativized} value of each specified register @var{regname}.
-As discussed in detail below, register values are normally relative to
-the selected stack frame. @var{regname} may be any register name valid on
+As discussed in detail below, register values are normally relative to
+the selected stack frame. @var{regname} may be any register name valid on
the machine you are using, with or without the initial @samp{$}.
@end table
sees. For example, the registers of the 68881 floating point
coprocessor are always saved in ``extended'' (raw) format, but all C
programs expect to work with ``double'' (virtual) format. In such
-cases, @value{GDBN} normally works with the virtual format only (the format
+cases, @value{GDBN} normally works with the virtual format only (the format
that makes sense for your program), but the @code{info registers} command
prints the data in both formats.
rarely expressed in the same manner. For instance, in ANSI C,
dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
Modula-2, it is accomplished by @code{p^}. Values can also be
-represented (and displayed) differently. Hex numbers in C appear as
+represented (and displayed) differently. Hex numbers in C appear as
@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
@cindex working language
Displaying the language}.
This is most commonly a problem when you use a program, such
-as @code{cfront} or @code{f2c}, that generates C but is written in
+as @code{cfront} or @code{f2c}, that generates C but is written in
another language. In that case, make the
program use @code{#line} directives in its C output; that way
@value{GDBN} will know the correct language of the source code of the original
@item .ch
@itemx .c186
@itemx .c286
-CHILL source file.
+CHILL source file
@item .mod
Modula-2 source file
@kindex set language
If you wish, you may set the language manually. To do this, issue the
command @samp{set language @var{lang}}, where @var{lang} is the name of
-a language, such as
+a language, such as
@code{c} or @code{modula-2}.
For a list of the supported languages, type @samp{set language}.
build and compute expressions that may involve variables in your program.
@item info frame
-Display the source language for this frame. This language becomes the
+Display the source language for this frame. This language becomes the
working language if you use an identifier from this frame.
-@xref{Frame Info, ,Information about a frame}, to identify the other
+@xref{Frame Info, ,Information about a frame}, to identify the other
information listed here.
@item info source
Display the source language of this source file.
-@xref{Symbols, ,Examining the Symbol Table}, to identify the other
+@xref{Symbols, ,Examining the Symbol Table}, to identify the other
information listed here.
@end table
The second example fails because the @code{CARDINAL} 1 is not
type-compatible with the @code{REAL} 2.3.
-For the expressions you use in @value{GDBN} commands, you can tell the
-@value{GDBN} type checker to skip checking;
-to treat any mismatches as errors and abandon the expression;
-or to only issue warnings when type mismatches occur,
+For the expressions you use in @value{GDBN} commands, you can tell the
+@value{GDBN} type checker to skip checking;
+to treat any mismatches as errors and abandon the expression;
+or to only issue warnings when type mismatches occur,
but evaluate the expression anyway. When you choose the last of
these, @value{GDBN} evaluates expressions like the second example above, but
also issues a warning.
-Even if you turn type checking off, there may be other reasons
-related to type that prevent @value{GDBN} from evaluating an expression.
-For instance, @value{GDBN} does not know how to add an @code{int} and
-a @code{struct foo}. These particular type errors have nothing to do
-with the language in use, and usually arise from expressions, such as
+Even if you turn type checking off, there may be other reasons
+related to type that prevent @value{GDBN} from evaluating an expression.
+For instance, @value{GDBN} does not know how to add an @code{int} and
+a @code{struct foo}. These particular type errors have nothing to do
+with the language in use, and usually arise from expressions, such as
the one described above, which make little sense to evaluate anyway.
Each language defines to what degree it is strict about type. For
numbers and structures.
@item show type
-Show the current setting of the type checker, and whether or not @value{GDBN}
+Show the current setting of the type checker, and whether or not @value{GDBN}
is setting it automatically.
@end table
@itemx set check range off
Set range checking on or off, overriding the default setting for the
current working language. A warning is issued if the setting does not
-match the language default. If a range error occurs, then a message
-is printed and evaluation of the expression is aborted.
+match the language default. If a range error occurs and range checking is on,
+then a message is printed and evaluation of the expression is aborted.
@item set check range warn
Output messages when the @value{GDBN} range checker detects a range error,
to both languages. Whenever this is the case, we discuss those languages
together.
-@cindex C++
-@kindex g++
+@cindex C@t{++}
+@cindex @code{g++}, @sc{gnu} C@t{++} compiler
@cindex @sc{gnu} C++
The C++ debugging facilities are jointly implemented by the C++
compiler and @value{GDBN}. Therefore, to debug your C++ code
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.
+often defined on groups of types.
For the purposes of C and C++, the following definitions hold:
predefined meaning.
@menu
-* C Constants::
+* C Constants::
@end menu
@node C Constants
@samp{\n} for newline.
@item
-String constants are a sequence of character constants surrounded
-by double quotes (@code{"}).
+String constants are a sequence of character constants surrounded by
+double quotes (@code{"}). Any valid character constant (as described
+above) may appear. Double quotes within the string must be preceded by
+a backslash, so for instance @samp{"a\"b'c"} is a string of five
+characters.
@item
Pointer constants are an integral value. You can also write pointers
@end itemize
@menu
-* C plus plus expressions::
-* C Defaults::
-* C Checks::
+* C plus plus expressions::
+* C Defaults::
+* C Checks::
-* Debugging C::
+* Debugging C::
@end menu
@node C plus plus expressions
count = aml->GetOriginal(x, y)
@end example
-@kindex this
+@vindex this@r{, inside C@t{++} member functions}
@cindex namespace in C++
@item
While a member function is active (in the selected stack frame), your
@cindex reference declarations
@item
-@value{GDBN} understands variables declared as C++ references; you can use
+@value{GDBN} understands variables declared as C++ references; you can use
them in expressions just as you do in C++ source---they are automatically
dereferenced.
,Expressions}.
@menu
-* Debugging C plus plus::
+* Debugging C plus plus::
@end menu
@node Debugging C plus plus
types.
@item <=@r{, }>=
-Less than, greater than, less than or equal to, greater than or equal to
+Less than or equal to, greater than or equal to
on integral, floating-point and enumerated types, or set inclusion on
set types. Same precedence as @code{<}.
@item CAP(@var{c})
If @var{c} is a lower case letter, it returns its upper case
-equivalent, otherwise it returns its argument
+equivalent, otherwise it returns its argument.
@item CHR(@var{i})
Returns the character whose ordinal value is @var{i}.
@item DEC(@var{v})
-Decrements the value in the variable @var{v}. Returns the new value.
+Decrements the value in the variable @var{v} by one. Returns the new value.
@item DEC(@var{v},@var{i})
Decrements the value in the variable @var{v} by @var{i}. Returns the
Returns the index of the last member of @var{a}.
@item INC(@var{v})
-Increments the value in the variable @var{v}. Returns the new value.
+Increments the value in the variable @var{v} by one. Returns the new value.
@item INC(@var{v},@var{i})
Increments the value in the variable @var{v} by @var{i}. Returns the
@item ORD(@var{x})
Returns the ordinal value of its argument. For example, the ordinal
-value of a character is its ASCII value (on machines supporting the
-ASCII character set). @var{x} must be of an ordered type, which include
+value of a character is its @sc{ascii} value (on machines supporting the
+@sc{ascii} character set). @var{x} must be of an ordered type, which include
integral, character and enumerated types.
@item SIZE(@var{x})
@item
Character constants consist of a single character enclosed by a pair of
like quotes, either single (@code{'}) or double (@code{"}). They may
-also be expressed by their ordinal value (their ASCII value, usually)
+also be expressed by their ordinal value (their @sc{ascii} value, usually)
followed by a @samp{C}.
@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
* How modes are displayed:: How modes are displayed
* Locations:: Locations and their accesses
* Values and their Operations:: Values and their Operations
-* Chill type and range checks::
+* Chill type and range checks::
* Chill defaults::
@end menu
@emph{Integer Modes} which are predefined by @code{BYTE, UBYTE, INT,
UINT, LONG, ULONG},
@item
-@emph{Boolean Mode} which is predefined by @code{BOOL},
+@emph{Boolean Mode} which is predefined by @code{BOOL},
@item
-@emph{Character Mode} which is predefined by @code{CHAR},
+@emph{Character Mode} which is predefined by @code{CHAR},
@item
@emph{Set Mode} which is displayed by the keyword @code{SET}.
@smallexample
@end smallexample
If the type is an unnumbered set the set element values are omitted.
@item
-@emph{Range Mode} which is displayed by @code{type = <basemode>
-(<lower bound> : <upper bound>)}, where @code{<lower bound>, <upper
-bound>} can be of any discrete literal expression (e.g. set element
-names).
+@emph{Range Mode} which is displayed by
+@smallexample
+@code{type = <basemode>(<lower bound> : <upper bound>)}
+@end smallexample
+where @code{<lower bound>, <upper bound>} can be of any discrete literal
+expression (e.g. set element names).
@end itemize
@item @r{@emph{Powerset Mode:}}
@ignore
@item @r{@emph{Instance mode}}
The instance mode is represented by a structure, which has a static
-type, and is therefore not really of interest.
+type, and is therefore not really of interest.
@end ignore
-@item @r{@emph{Synchronization Modes:}}
+@item @r{@emph{Synchronization Modes:}}
@itemize @bullet
@item
-@emph{Event Mode} which is displayed by @code{EVENT (<event length>)},
+@emph{Event Mode} which is displayed by
+@smallexample
+@code{EVENT (<event length>)}
+@end smallexample
where @code{(<event length>)} is optional.
@item
-@emph{Buffer Mode} which is displayed by @code{BUFFER (<buffer length>)
-<buffer element mode>}, where @code{(<buffer length>)} is optional.
+@emph{Buffer Mode} which is displayed by
+@smallexample
+@code{BUFFER (<buffer length>)<buffer element mode>}
+@end smallexample
+where @code{(<buffer length>)} is optional.
@end itemize
-@item @r{@emph{Timing Modes:}}
+@item @r{@emph{Timing Modes:}}
@itemize @bullet
@item
@emph{Duration Mode} which is predefined by @code{DURATION}
@item @r{@emph{String Modes:}}
@itemize @bullet
@item
-@emph{Character String Mode} which is displayed by @code{CHARS(<string
-length>)}, followed by the keyword @code{VARYING} if the String Mode is
-a varying mode
+@emph{Character String Mode} which is displayed by
+@smallexample
+@code{CHARS(<string length>)}
+@end smallexample
+followed by the keyword @code{VARYING} if the String Mode is a varying
+mode
@item
-@emph{Bit String Mode} which is displayed by @code{BOOLS(<string
-length>)}.
+@emph{Bit String Mode} which is displayed by
+@smallexample
+@code{BOOLS(<string
+length>)}
+@end smallexample
@end itemize
@item @r{@emph{Array Mode:}}
followed by the element mode (which may in turn be an array mode).
@smallexample
(@value{GDBP}) ptype x
-type = ARRAY (1:42)
- ARRAY (1:20)
+type = ARRAY (1:42)
+ ARRAY (1:20)
SET (karli = 10, susi = 20, fritzi = 100)
@end smallexample
-@item @r{@emph{Structure Mode}}
+@item @r{@emph{Structure Mode}}
The Structure mode is displayed by the keyword @code{STRUCT(<field
list>)}. The @code{<field list>} consists of names and modes of fields
of the structure. Variant structures have the keyword @code{CASE <field>
@noindent
This does the same as the Chill action @code{RESULT EXPR} (which
-is not available in gdb).
+is not available in @value{GDBN}).
Values of reference mode locations are printed by @code{PTR(<hex
value>)} in case of a free reference mode, and by @code{(REF <reference
value of the location referenced by the pointer, use the dereference
operator @samp{->}.
-Values of procedure mode locations are displayed by @code{@{ PROC
+Values of procedure mode locations are displayed by
+@smallexample
+@code{@{ PROC
(<argument modes> ) <return mode> @} <address> <name of procedure
-location>}. @code{<argument modes>} is a list of modes according to the
-parameter specification of the procedure and @code{<address>} shows the
-address of the entry point.
+location>}
+@end smallexample
+@code{<argument modes>} is a list of modes according to the parameter
+specification of the procedure and @code{<address>} shows the address of
+the entry point.
@ignore
Locations of instance modes are displayed just like a structure with two
@c FIXME: if the Chill Manual is a Texinfo documents, the above should
@c be converted to a @ref.
-@ignore
+@ignore
@itemize @bullet
@item
@emph{Integer Literals} are specified in the same manner as in Chill
@item
@emph{Emptiness Literal} is predefined by @code{NULL}. The value of the
emptiness literal delivers either the empty reference value, the empty
-procedure value or the empty instance value.
+procedure value or the empty instance value.
@item
@emph{Character String Literals} are defined by a sequence of characters
@end itemize
@item String Element Value
-A string element value is specified by @code{<string value>(<index>)},
+A string element value is specified by
+@smallexample
+@code{<string value>(<index>)}
+@end smallexample
where @code{<index>} is a integer expression. It delivers a character
value which is equivalent to the character indexed by @code{<index>} in
the string.
Values of duration mode locations are represented by @code{ULONG} literals.
-Values of time mode locations are represented by @code{TIME(<secs>:<nsecs>)}.
+Values of time mode locations appear as
+@smallexample
+@code{TIME(<secs>:<nsecs>)}
+@end smallexample
+
@ignore
This is not implemented yet:
All checks can be disabled by the @value{GDBN} command @code{set check
off}.
-@ignore
+@ignore
@c Deviations from the Chill Standard Z200/88
see last paragraph ?
@end ignore
object file with a particular name is seen again.
@item set symbol-reloading off
-Do not replace symbol definitions when re-encountering object files of
-the same name. This is the default state; if you are not running on a
-system that permits automatically relinking modules, you should leave
-@code{symbol-reloading} off, since otherwise @value{GDBN} may discard symbols
-when linking large programs, that may contain several modules (from
-different directories or libraries) with the same name.
+Do not replace symbol definitions when encountering object files of the
+same name more than once. This is the default state; if you are not
+running on a system that permits automatic relinking of modules, you
+should leave @code{symbol-reloading} off, since otherwise @value{GDBN}
+may discard symbols when linking large programs, that may contain
+several modules (from different directories or libraries) with the same
+name.
@kindex show symbol-reloading
@item show symbol-reloading
@noindent
stores the value 4 into the variable @code{x}, and then prints the
-value of the assignment expression (which is 4).
+value of the assignment expression (which is 4).
@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more
information on operators in supported languages.
The program being debugged has been started already.
Start it from the beginning? (y or n) y
Starting program: /home/smith/cc_progs/a.out
-"/home/smith/cc_progs/a.out": can't open to read symbols: Invalid bfd target.
+"/home/smith/cc_progs/a.out": can't open to read symbols:
+ Invalid bfd target.
(@value{GDBP}) show g
The current BFD target is "=4".
@end group
You can use this variant of the @code{print} command if you want to
execute a function from your program, but without cluttering the output
-with @code{void} returned values. If the result is not void, it
-is printed and saved in the value history.
+with @code{void} returned values. If the result is not void, it
+is printed and saved in the value history.
For the A29K, a user-controlled variable @code{call_scratch_address},
specifies the location of a scratch area to be used when @value{GDBN}
Use @var{filename} as the program to be debugged. It is read for its
symbols and for the contents of pure memory. It is also the program
executed when you use the @code{run} command. If you do not specify a
-directory and the file is not found in the @value{GDBN} working directory,
-@value{GDBN} uses the environment variable @code{PATH} as a list of
-directories to search, just as the shell does when looking for a program
-to run. You can change the value of this variable, for both @value{GDBN}
+directory and the file is not found in the @value{GDBN} working directory,
+@value{GDBN} uses the environment variable @code{PATH} as a list of
+directories to search, just as the shell does when looking for a program
+to run. You can change the value of this variable, for both @value{GDBN}
and your program, using the @code{path} command.
-On systems with memory-mapped files, an auxiliary file
+On systems with memory-mapped files, an auxiliary file named
@file{@var{filename}.syms} may hold symbol table information for
@var{filename}. If so, @value{GDBN} maps in the symbol table from
@file{@var{filename}.syms}, starting up more quickly. See the
descriptions of the file options @samp{-mapped} and @samp{-readnow}
(available on the command line, and with the commands @code{file},
-@code{symbol-file}, or @code{add-symbol-file}, described below),
+@code{symbol-file}, or @code{add-symbol-file}, described below),
for more information.
@item file
@code{symbol-file} with no argument clears out @value{GDBN} information on your
program's symbol table.
-The @code{symbol-file} command causes @value{GDBN} to forget the contents
+The @code{symbol-file} command causes @value{GDBN} to forget the contents
of its convenience variables, the value history, and all breakpoints and
auto-display expressions. This is because they may contain pointers to
the internal data recording symbols and data types, which are part of
You can override the @value{GDBN} two-stage strategy for reading symbol
tables by using the @samp{-readnow} option with any of the commands that
load symbol table information, if you want to be sure @value{GDBN} has the
-entire symbol table available.
+entire symbol table available.
If memory-mapped files are available on your system through the
@code{mmap} system call, you can use another option, @samp{-mapped}, to
@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}
-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 @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.
+@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 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
-@code{add-symbol-file} command any number of times; the new symbol data thus
-read keeps adding to the old. To discard all old symbol data instead,
-use the @code{symbol-file} command.
+@code{add-symbol-file} command any number of times; the new symbol data
+thus read keeps adding to the old. To discard all old symbol data
+instead, use the @code{symbol-file} command without any arguments.
@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
@kindex add-shared-symbol-file
@item add-shared-symbol-file
The @code{add-shared-symbol-file} command can be used only under Harris' CXUX
-operating system for the Motorola 88k. @value{GDBN} automatically looks for
-shared libraries, however if @value{GDBN} does not find yours, you can run
+operating system for the Motorola 88k. @value{GDBN} automatically looks for
+shared libraries, however if @value{GDBN} does not find yours, you can run
@code{add-shared-symbol-file}. It takes no arguments.
@kindex section
@item section
-The @code{section} command changes the base address of section SECTION of
-the exec file to ADDR. This can be used if the exec file does not contain
-section addresses, (such as in the a.out format), or when the addresses
-specified in the file itself are wrong. Each section must be changed
+The @code{section} command changes the base address of section SECTION of
+the exec file to ADDR. This can be used if the exec file does not contain
+section addresses, (such as in the a.out format), or when the addresses
+specified in the file itself are wrong. Each section must be changed
separately. The @code{info files} command, described below, lists all
the sections and their addresses.
@kindex set gnutarget
@item set gnutarget @var{args}
-@value{GDBN} uses its own library BFD to read your files. @value{GDBN}
+@value{GDBN} uses its own library BFD to read your files. @value{GDBN}
knows whether it is reading an @dfn{executable},
-a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format
-with the @code{set gnutarget} command. Unlike most @code{target} commands,
+a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format
+with the @code{set gnutarget} command. Unlike most @code{target} commands,
with @code{gnutarget} the @code{target} refers to a program, not a machine.
@quotation
@noindent
@xref{Files, , Commands to specify files}.
-@kindex show gnutarget
+@kindex show gnutarget
@item show gnutarget
Use the @code{show gnutarget} command to display what file format
@code{gnutarget} is set to read. If you have not set @code{gnutarget},
@end table
-Different targets are available on different configurations of @value{GDBN};
+Different targets are available on different configurations of @value{GDBN};
your configuration may have more or fewer targets.
Many remote targets require you to download the executable's code
@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
@cindex remote debugging
If you are trying to debug a program running on a machine that cannot run
-@value{GDBN} in the usual way, it is often useful to use remote debugging.
-For example, you might use remote debugging on an operating system kernel,
+@value{GDBN} in the usual way, it is often useful to use remote debugging.
+For example, you might use remote debugging on an operating system kernel,
or on a small system which does not have a general purpose operating system
powerful enough to run a full-featured debugger.
Some configurations of @value{GDBN} have special serial or TCP/IP interfaces
to make this work with particular debugging targets. In addition,
-@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN},
+@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN},
but not specific to any particular target system) which you can use if you
write the remote stubs---the code that runs on the remote system to
communicate with @value{GDBN}.
have a name like @file{crt0}. The startup routine may be supplied by
your hardware supplier, or you may have to write your own.
-@item
+@item
A C subroutine library to support your program's
subroutine calls, notably managing input and output.
@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.
retrieving and transmitting any information @value{GDBN} needs, until you
execute a @value{GDBN} command that makes your program resume; at that point,
@code{handle_exception} returns control to your own code on the target
-machine.
+machine.
@item breakpoint
@cindex @code{breakpoint} subroutine, remote
simply receiving characters on the serial port may also trigger a trap;
again, in that situation, you don't need to call @code{breakpoint} from
your own program---simply running @samp{target remote} from the host
-@value{GDBN} session gets control.
+@value{GDBN} session gets control.
Call @code{breakpoint} if none of these is true, or if you simply want
to make certain your program stops at a predetermined point for the
@item void putDebugChar(int)
@kindex putDebugChar
Write this subroutine to write a single character to the serial port.
-It may be identical to @code{putchar} for your target system; a
+It may be identical to @code{putchar} for your target system; a
different name is used to allow you to distinguish the two if you wish.
@end table
@enumerate
@item
-Make sure you have the supporting low-level routines
+Make sure you have defined the supporting low-level routines
(@pxref{Bootstrapping,,What you must do for the stub}):
@display
@code{getDebugChar}, @code{putDebugChar},
@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 ASCII encoding giving a repeat count
+means that the next character is an @sc{ascii} encoding giving a repeat count
which stands for that many repetitions of the character preceding the
@samp{*}. The encoding is @code{n+29}, yielding a printable character
where @code{n >=3} (which is where rle starts to win). The printable
@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
@item reserved
@tab @code{a}
-@tab Reserved for future use
+@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 Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{E}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{f}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{F}
-@tab Reserved for future use
+@tab Reserved for future use
@item read registers
@tab @code{g}
@item reserved
@tab @code{h}
-@tab Reserved for future use
+@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 FIXME: JTC:
@c 'H': How restrictive (or permissive) is the thread model. If a
-@c thread is selected and stopped, are other threads allowed
+@c thread is selected and stopped, are other threads allowed
@c to continue to execute? As I mentioned above, I think the
@c semantics of each command when a thread is selected must be
@c described. For example:
@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.
@item reserved
@tab @code{J}
-@tab Reserved for future use
+@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
@item reserved
@tab @code{l}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{L}
-@tab Reserved for future use
+@tab Reserved for future use
@item read memory
@tab @code{m}@var{addr}@code{,}@var{length}
@item reserved
@tab @code{n}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{N}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{o}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{O}
-@tab Reserved for future use
+@tab Reserved for future use
@item read reg @strong{(reserved)}
@tab @code{p}@var{n...}
@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
@item
@tab reply @code{E}@var{NN}
@tab thread is dead
-
+
@item reserved
@tab @code{u}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{U}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{v}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{V}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{w}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{W}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{x}
-@tab Reserved for future use
+@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
@item reserved
@tab @code{y}
-@tab Reserved for future use
+@tab Reserved for future use
@item reserved
@tab @code{Y}
-@tab Reserved for future use
+@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
the instruction to be patched. For hardware breakpoints and watchpoints
@var{length} specifies the memory region to be monitored. To avoid
potential problems with duplicate packets, the operations should be
-implemented in an ident-potentent way.
+implemented in an idempotent way.
@item
@tab reply @code{E}@var{NN}
@tab for an error
@item reserved
@tab <other>
-@tab Reserved for future use
+@tab Reserved for future use
@end multitable
@tab
The process terminated with signal @var{AA}.
-@item @code{N}@var{AA}@code{;}@var{tttttttt}@code{;}@var{dddddddd}@code{;}@var{bbbbbbbb} @strong{(obsolete)}
+@item @code{N}@var{AA}@code{;}@var{t...}@code{;}@var{d...}@code{;}@var{b...} @strong{(obsolete)}
@tab
-@var{AA} = signal number; @var{tttttttt} = address of symbol "_start";
-@var{dddddddd} = base of data section; @var{bbbbbbbb} = base of bss
-section. @emph{Note: only used by Cisco Systems targets. The difference
-between this reply and the "qOffsets" query is that the 'N' packet may
-arrive spontaneously whereas the 'qOffsets' is a query initiated by the
-host debugger.}
+@var{AA} = signal number; @var{t...} = address of symbol "_start";
+@var{d...} = base of data section; @var{b...} = base of bss section.
+@emph{Note: only used by Cisco Systems targets. The difference between
+this reply and the "qOffsets" query is that the 'N' packet may arrive
+spontaneously whereas the 'qOffsets' is a query initiated by the host
+debugger.}
@item @code{O}@var{XX...}
@tab
-@var{XX...} is hex encoding of ASCII data. This can happen at any time
+@var{XX...} is hex encoding of @sc{ascii} data. This can happen at any time
while the program is running and the debugger should continue to wait
for 'W', 'T', etc.
@tab reply *
@tab Any other reply implies the old pid.
-@item compute CRC of memory block
-@tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length}
+@item all thread ids
+@tab @code{q}@code{fThreadInfo}
+@item
+@tab @code{q}@code{sThreadInfo}
@tab
+Obtain a list of active thread ids from the target (OS). Since there
+may be too many active threads to fit into one reply packet, this query
+works iteratively: it may require more than one query/reply sequence to
+obtain the entire list of threads. The first query of the sequence will
+be the @code{qf}@code{ThreadInfo} query; subsequent queries in the
+sequence will be the @code{qs}@code{ThreadInfo} query.
@item
-@tab reply @code{E}@var{NN}
-@tab An error (such as memory fault)
+@tab
+@tab NOTE: replaces the @code{qL} query (see below).
@item
-@tab reply @code{C}@var{CRC32}
-@tab A 32 bit cyclic redundancy check of the specified memory region.
+@tab reply @code{m}@var{<id>}
+@tab A single thread id
+@item
+@tab reply @code{m}@var{<id>},@var{<id>...}
+@tab a comma-separated list of thread ids
+@item
+@tab reply @code{l}
+@tab (lower case 'el') denotes end of list.
+@item
+@tab
+@tab
+In response to each query, the target will reply with a list of one
+or more thread ids, in big-endian hex, separated by commas. GDB will
+respond to each reply with a request for more thread ids (using the
+@code{qs} form of the query), until the target responds with @code{l}
+(lower-case el, for @code{'last'}).
+
+@item extra thread info
+@tab @code{q}@code{ThreadExtraInfo}@code{,}@var{id}
+@tab
+@item
+@tab
+@tab
+Where @var{<id>} is a thread-id in big-endian hex.
+Obtain a printable string description of a thread's attributes from
+the target OS. This string may contain anything that the target OS
+thinks is interesting for @value{GDBN} to tell the user about the thread.
+The string is displayed in @value{GDBN}'s @samp{info threads} display.
+Some examples of possible thread extra info strings are "Runnable", or
+"Blocked on Mutex".
+@item
+@tab reply @var{XX...}
+@tab
+Where @var{XX...} is a hex encoding of @sc{ascii} data, comprising the
+printable string containing the extra information about the thread's
+attributes.
@item query @var{LIST} or @var{threadLIST} @strong{(deprecated)}
@tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread}
@tab
+@item
+@tab
+@tab
Obtain thread information from RTOS. Where: @var{startflag} (one hex
digit) is one to indicate the first query and zero to indicate a
subsequent query; @var{threadcount} (two hex digits) is the maximum
(eight hex digits), for subsequent queries (@var{startflag} is zero), is
returned in the response as @var{argthread}.
@item
+@tab
+@tab NOTE: this query is replaced by the @code{q}@code{fThreadInfo}
+query (see above).
+@item
@tab reply @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread...}
@tab
+@item
+@tab
+@tab
Where: @var{count} (two hex digits) is the number of threads being
returned; @var{done} (one hex digit) is zero to indicate more threads
and one indicates no further threads; @var{argthreadid} (eight hex
a sequence of thread IDs from the target. @var{threadid} (eight hex
digits). See @code{remote.c:parse_threadlist_response()}.
+@item compute CRC of memory block
+@tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length}
+@tab
+@item
+@tab reply @code{E}@var{NN}
+@tab An error (such as memory fault)
+@item
+@tab reply @code{C}@var{CRC32}
+@tab A 32 bit cyclic redundancy check of the specified memory region.
+
@item query sect offs
@tab @code{q}@code{Offsets}
@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
<- @code{+}
@end example
-@kindex set remotedebug@r{, serial protocol}
-@kindex show remotedebug@r{, serial protocol}
-@cindex packets, reporting on stdout
-@cindex serial connections, debugging
-If you have trouble with the serial connection, you can use the command
-@code{set remotedebug}. This makes @value{GDBN} report on all packets sent
-back and forth across the serial line to the remote machine. The
-packet-debugging information is printed on the @value{GDBN} standard output
-stream. @code{set remotedebug off} turns it off, and @code{show
-remotedebug} shows you its current state.
-
@node Server
@subsubsection Using the @code{gdbserver} program
@value{GDBN}; the name of your program; and the arguments for your
program. The syntax is:
-@smallexample
+@smallexample
load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
[ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
@end smallexample
to 0, @var{baud} defaults to 9600@dmn{bps}.
For example, to debug Emacs with the argument @samp{foo.txt}and
-communicate with @value{GDBN} over serial port number 2 or board 1
+communicate with @value{GDBN} over serial port number 2 or board 1
using a 19200@dmn{bps} connection:
@smallexample
both the Unix host and on the VxWorks target. The program
@code{@value{GDBP}} is installed and executed on the Unix host. (It may be
installed with the name @code{vxgdb}, to distinguish it from a
-@value{GDB} for debugging programs on the host itself.)
+@value{GDBN} for debugging programs on the host itself.)
@table @code
@item VxWorks-timeout @var{args}
@kindex vxworks-timeout
-All VxWorks-based targets now support the option @code{vxworks-timeout}.
-This option is set by the user, and @var{args} represents the number of
-seconds @value{GDBN} waits for responses to rpc's. You might use this if
-your VxWorks target is a slow software simulator or is on the far side
+All VxWorks-based targets now support the option @code{vxworks-timeout}.
+This option is set by the user, and @var{args} represents the number of
+seconds @value{GDBN} waits for responses to rpc's. You might use this if
+your VxWorks target is a slow software simulator or is on the far side
of a thin network line.
@end table
Once you have included @file{rdb.a} in your VxWorks system image and 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}} (or @code{vxgdb},
-depending on your installation).
+run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or
+@code{vxgdb}, depending on your installation).
@value{GDBN} comes up showing the prompt:
@value{GDBN} displays messages like these:
@smallexample
-Attaching remote machine across net...
+Attaching remote machine across net...
Connected to tt.
@end smallexample
Then, in @value{GDBN}, type:
@example
-(vxgdb) cd @var{hostpath}/vw/demo/rdb
+(vxgdb) cd @var{hostpath}/vw/demo/rdb
(vxgdb) load prog.o
@end example
you must match the communications parameters when establishing the Unix
end of the connection as well.
@c FIXME: Who knows what this "no retry action" crud from the DOS manual may
-@c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
+@c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
@c
@c It's optional, but it's unwise to omit it: who knows what is the
@c default value set when the DOS machines boots? "No retry" means that
@noindent
(Later, if you wish to return control to the DOS console, you can use
the command @code{CTTY con}---but you must send it over the device that
-had control, in our example over the @file{COM1} serial line).
+had control, in our example over the @file{COM1} serial line.)
From the Unix host, use a communications program such as @code{tip} or
@code{cu} to communicate with the PC; for example,
@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
ARM Angel monitor, via RDI library interface to ADP protocol. You may
use this target to communicate with both boards running the Angel
monitor, or with the EmbeddedICE JTAG debug device.
-
+
@kindex target rdp
@item target rdp @var{dev}
ARM Demon monitor.
@kindex target sh3@r{, with H8/300}
@kindex target sh3e@r{, with H8/300}
@item target sh3 @var{dev}
-@item target sh3e @var{dev}
+@itemx target sh3e @var{dev}
Hitachi SH-3 and SH-3E target systems.
@end table
@value{GDBN} on your host (like the @code{file} command).
@value{GDBN} needs to know these things to talk to your
-Hitachi SH, H8/300, or H8/500:
+Hitachi SH, H8/300, or H8/500:
@enumerate
@item
@c only for Unix hosts
@kindex device
@cindex serial device, Hitachi micros
-Use the special @code{@value{GDBP}} command @samp{device @var{port}} if you
+Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you
need to explicitly set the serial device. The default @var{port} is the
first available port on your host. This is only necessary on Unix
hosts, where it is typically something like @file{/dev/ttya}.
@kindex speed
@cindex serial line speed, Hitachi micros
-@code{@value{GDBP}} has another special command to set the communications
+@code{@value{GDBN}} has another special command to set the communications
speed: @samp{speed @var{bps}}. This command also is only used from Unix
hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with
the DOS @code{mode} command (for instance,
@kindex target hms@r{, and serial protocol}
Now that serial communications are set up, and the development board is
connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
-the name of your program as the argument. @code{@value{GDBP}} prompts
+the name of your program as the argument. @code{@value{GDBN}} prompts
you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
commands to begin your debugging session: @samp{target hms} to specify
cross-debugging to the Hitachi board, and the @code{load} command to
@smallexample
(eg-C:\H8300\TEST) @value{GDBP} t.x
@value{GDBN} is free software and you are welcome to distribute copies
- of it under certain conditions; type "show copying" to see
+ of it under certain conditions; type "show copying" to see
the conditions.
-There is absolutely no warranty for @value{GDBN}; type "show warranty"
+There is absolutely no warranty for @value{GDBN}; type "show warranty"
for details.
@value{GDBN} @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
(@value{GDBP}) target hms
@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
reach the ordinary @value{GDBN} prompt:
@example
-Attach /dev/ttyNN -- specify NN, or "quit" to quit:
+Attach /dev/ttyNN -- specify NN, or "quit" to quit:
@end example
@noindent
@kindex show processor
Use the @code{set processor} command to set the type of MIPS
processor when you want to access processor-type-specific registers.
-For example, @code{set processor @var{r3041}} tells @value{GDBN}
+For example, @code{set processor @var{r3041}} tells @value{GDBN}
to use the CPO registers appropriate for the 3041 chip.
-Use the @code{show processor} command to see what MIPS processor @value{GDBN}
+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.
+@value{GDBN} is using.
@item set mipsfpu double
@itemx set mipsfpu single
@cindex floating point, MIPS remote
If your target board does not support the MIPS floating point
coprocessor, you should use the command @samp{set mipsfpu none} (if you
-need this, you may wish to put the command in your @value{GDBINIT}
+need this, you may wish to put the command in your @value{GDBN} init
file). This tells @value{GDBN} how to find the return value of
functions which return floating point values. It also allows
@value{GDBN} to avoid saving the floating point registers when calling
@cindex Sparclet
-@value{GDBN} enables developers to debug tasks running on
-Sparclet targets from a Unix host.
+@value{GDBN} enables developers to debug tasks running on
+Sparclet targets from a Unix host.
@value{GDBN} uses code that runs on
both the Unix host and on the Sparclet target. The program
-@code{@value{GDBP}} is installed and executed on the Unix host.
+@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.
+@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
-When compiling for debugging, include the options @samp{-g} to get debug
+@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
+load it on the target. You may also want to add the options @samp{-n} or
@samp{-N} in order to reduce the size of the sections. Example:
@example
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}}
+run @value{GDBN}. From your Unix host, run @code{@value{GDBP}}
(or @code{sparclet-aout-gdb}, depending on your installation).
@value{GDBN} comes up showing the prompt:
* Sparclet File:: Setting the file to debug
* Sparclet Connection:: Connecting to Sparclet
* Sparclet Download:: Sparclet download
-* Sparclet Execution:: Running and debugging
+* Sparclet Execution:: Running and debugging
@end menu
@node Sparclet File
@end example
When this happens, add the appropriate directories to the search paths with
-the @value{GDBN} commands @code{path} and @code{dir}, and execute the
+the @value{GDBN} commands @code{path} and @code{dir}, and execute the
@code{target} command again.
@node Sparclet Connection
@example
(gdbslet) target sparclet /dev/ttya
Remote target sparclet connected to /dev/ttya
-main () at ../prog.c:3
+main () at ../prog.c:3
@end example
@need 750
@subsubsection Sparclet download
@cindex download to Sparclet
-Once connected to the Sparclet target,
+Once connected to the Sparclet target,
you can use the @value{GDBN}
@code{load} command to download the file from the host to the target.
The file name and load offset should be given as arguments to the @code{load}
command.
-Since the file format is aout, the program must be loaded to the starting
+Since the file format is aout, the program must be loaded to the starting
address. You can use @code{objdump} to find out what this value is. The load
offset is an offset which is added to the VMA (virtual memory address)
of each of the file's sections.
Loading section .text, size 0xdb0 vma 0x12010000
@end example
-If the code is loaded at a different address then what the program was linked
-to, you may need to use the @code{section} and @code{add-symbol-file} commands
+If the code is loaded at a different address then what the program was linked
+to, you may need to use the @code{section} and @code{add-symbol-file} commands
to tell @value{GDBN} where to map the symbol table.
@node Sparclet Execution
@cindex running and debugging Sparclet programs
You can now begin debugging the task using @value{GDBN}'s execution control
-commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
+commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
manual for the list of commands.
@example
(gdbslet) b main
Breakpoint 1 at 0x12010000: file prog.c, line 3.
-(gdbslet) run
+(gdbslet) run
Starting program: prog
Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
3 char *symarg = 0;
(gdbslet) step
4 char *execarg = "hello!";
-(gdbslet)
+(gdbslet)
@end example
@node Sparclite
@kindex target sparclite
@item target sparclite @var{dev}
-Fujitsu sparclite boards, used only for the purpose of loading.
-You must use an additional command to debug the program.
-For example: target remote @var{dev} using @value{GDBN} standard
+Fujitsu sparclite boards, used only for the purpose of loading.
+You must use an additional command to debug the program.
+For example: target remote @var{dev} using @value{GDBN} standard
remote protocol.
@end table
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
* Screen Size:: Screen size
* Numbers:: Numbers
* Messages/Warnings:: Optional warnings and messages
+* Debugging Output:: Optional messages about internal happenings
@end menu
@node Prompt
called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You
can change the prompt string with the @code{set prompt} command. For
instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change
-the prompt in one of the @value{GDBN} sessions so that you can always tell
+the prompt in one of the @value{GDBN} sessions so that you can always tell
which one you are talking to.
@emph{Note:} @code{set prompt} does not add a space for you after the
@end table
@table @code
-@kindex show commands
+@kindex shows
@item show commands
Display the last ten commands in the command history.
a screen width of @var{cpl} characters. The associated @code{show}
commands display the current settings.
-If you specify a height of zero lines, @value{GDBN} does not pause during
-output no matter how long the output is. This is useful if output is to a
+If you specify a height of zero lines, @value{GDBN} does not pause during
+output no matter how long the output is. This is useful if output is to a
file or to an editor buffer.
Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
@end table
+@node Debugging Output
+@section Optional messages about internal happenings
+@table @code
+@kindex set debug arch
+@item set debug arch
+Turns on or off display of gdbarch debugging info. The default is off
+@kindex show debug arch
+@item show debug arch
+Displays the current state of displaying gdbarch debugging info.
+@kindex set debug event
+@item set debug event
+Turns on or off display of @value{GDBN} event debugging info. The
+default is off.
+@kindex show debug event
+@item show debug event
+Displays the current state of displaying @value{GDBN} event debugging
+info.
+@kindex set debug expression
+@item set debug expression
+Turns on or off display of @value{GDBN} expression debugging info. The
+default is off.
+@kindex show debug expression
+@item show debug expression
+Displays the current state of displaying @value{GDBN} expression
+debugging info.
+@kindex set debug overload
+@item set debug overload
+Turns on or off display of @value{GDBN} C++ 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
+debugging info.
+@kindex set debug remote
+@cindex packets, reporting on stdout
+@cindex serial connections, debugging
+@item set debug remote
+Turns on or off display of reports on all packets sent back and forth across
+the serial line to the remote machine. The info is printed on the
+@value{GDBN} standard output stream. The default is off.
+@kindex show debug remote
+@item show debug remote
+Displays the state of display of remote packets.
+@kindex set debug serial
+@item set debug serial
+Turns on or off display of @value{GDBN} serial debugging info. The
+default is off.
+@kindex show debug serial
+@item show debug serial
+Displays the current state of displaying @value{GDBN} serial debugging
+info.
+@kindex set debug target
+@item set debug target
+Turns on or off display of @value{GDBN} target debugging info. This info
+includes what is going on at the target level of GDB, as it happens. The
+default is off.
+@kindex show debug target
+@item show debug target
+Displays the current state of displaying @value{GDBN} target debugging
+info.
+@kindex set debug varobj
+@item set debug varobj
+Turns on or off display of @value{GDBN} variable object debugging
+info. The default is off.
+@kindex show debug varobj
+@item show debug varobj
+Displays the current state of displaying @value{GDBN} variable object
+debugging info.
+@end table
+
@node Sequences
@chapter Canned Sequences of Commands
@noindent
This defines the command @code{adder}, which prints the sum of
-its three arguments. Note the arguments are text substitutions, so they may
+its three arguments. Note the arguments are text substitutions, so they may
reference variables, use complex expressions, or even perform inferior
functions calls.
@kindex document
@item document @var{commandname}
Document the user-defined command @var{commandname}, so that it can be
-accessed by @code{help}. The command @var{commandname} must already be
-defined. This command reads lines of documentation just as @code{define}
-reads the lines of the command definition, ending with @code{end}.
-After the @code{document} command is finished, @code{help} on command
+accessed by @code{help}. The command @var{commandname} must already be
+defined. This command reads lines of documentation just as @code{define}
+reads the lines of the command definition, ending with @code{end}.
+After the @code{document} command is finished, @code{help} on command
@var{commandname} displays the documentation you have written.
You may use the @code{document} command again to change the
stops execution of the user-defined command.
If used interactively, commands that would ask for confirmation proceed
-without asking when used inside a user-defined command. Many @value{GDBN}
-commands that normally print messages to say what they are doing omit the
+without asking when used inside a user-defined command. Many @value{GDBN}
+commands that normally print messages to say what they are doing omit the
messages when used in a user-defined command.
@node Hooks
@section Command files
@cindex command files
-A command file for @value{GDBN} is a file of lines that are @value{GDBN}
-commands. Comments (lines starting with @kbd{#}) may also be included.
-An empty line in a command file does nothing; it does not mean to repeat
+A command file for @value{GDBN} is a file of lines that are @value{GDBN}
+commands. Comments (lines starting with @kbd{#}) may also be included.
+An empty line in a command file does nothing; it does not mean to repeat
the last command, as it would from the terminal.
@cindex init file
@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
In addition to the standard C escape sequences, a backslash followed
by a space stands for a space. This is useful for displaying a
string with spaces at the beginning or the end, since leading and
-trailing spaces are otherwise trimmed from all arguments.
+trailing spaces are otherwise trimmed from all arguments.
To print @samp{@w{ }and foo =@w{ }}, use the command
@samp{echo \@w{ }and foo = \@w{ }}.
@item output @var{expression}
Print the value of @var{expression} and nothing but that value: no
newlines, no @samp{$@var{nn} = }. The value is not entered in the
-value history either. @xref{Expressions, ,Expressions}, for more information
+value history either. @xref{Expressions, ,Expressions}, for more information
on expressions.
@item output/@var{fmt} @var{expression}
@kindex Epoch
@kindex inspect
-Version 18 of @sc{gnu} Emacs has a built-in window system
+Version 18 of @sc{gnu} Emacs has a built-in window system
called the @code{epoch}
environment. Users of this environment can use a new command,
@code{inspect} which performs identically to @code{print} except that
each value is printed in its own window.
@end ignore
+@include annotate.texi
+@include gdbmi.texinfo
+
@node GDB Bugs
@chapter Reporting Bugs in @value{GDBN}
@cindex bugs in @value{GDBN}
things without first using the debugger to find the facts.
@end itemize
-@c The readline documentation is distributed with the readline code
+@c The readline documentation is distributed with the readline code
@c and consists of the two following files:
@c rluser.texinfo
@c inc-hist.texinfo
make refcard.dvi
@end example
-The @value{GDBN} reference card is designed to print in @dfn{landscape}
-mode on US ``letter'' size paper;
+The @value{GDBN} reference card is designed to print in @dfn{landscape}
+mode on US ``letter'' size paper;
that is, on a sheet 11 inches wide by 8.5 inches
high. You will need to specify this form of printing as an option to
your @sc{dvi} output program.
installation procedures since publishing this manual.}
@end iftex
-The @value{GDBN} distribution includes all the source code you need for
-@value{GDBN} in a single directory, whose name is usually composed by
+The @value{GDBN} distribution includes all the source code you need for
+@value{GDBN} in a single directory, whose name is usually composed by
appending the version number to @samp{gdb}.
For example, the @value{GDBN} version @value{GDBVN} distribution is in the
would be the same as the argument to @samp{--srcdir}, you can leave out
the @samp{--srcdir} option; it is assumed.)
-For example, with version @value{GDBVN}, you can build @value{GDBN} in a
+For example, with version @value{GDBVN}, you can build @value{GDBN} in a
separate directory for a Sun 4 like this:
@example
@file{gdb-sun4/gdb}.
One popular reason to build several @value{GDBN} configurations in separate
-directories is to configure @value{GDBN} for cross-compiling (where
-@value{GDBN} runs on one machine---the @dfn{host}---while debugging
-programs that run on another machine---the @dfn{target}).
+directories is to configure @value{GDBN} for cross-compiling (where
+@value{GDBN} runs on one machine---the @dfn{host}---while debugging
+programs that run on another machine---the @dfn{target}).
You specify a cross-debugging target by
giving the @samp{--target=@var{target}} option to @code{configure}.
There are many other options available as well, but they are generally
needed for special purposes only.
-
+
@node Index
@unnumbered Index
% 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 / binutils-gdb.git / blobdiff