@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
-@c of @set vars. However, we can override filename with makeinfo -o.
+@c of @set vars. However, you can override filename with makeinfo -o.
@setfilename gdb.info
@c
@include gdb-config.texi
@settitle Debugging with @value{GDBN}
@end ifset
@ifclear GENERIC
-@settitle Debugging with @value{GDBN} (@value{HOST})
+@settitle Debugging with @value{GDBN} (@value{TARGET})
@end ifclear
@setchapternewpage odd
@c %**end of header
@iftex
-@c @smallbook
+@smallbook
@c @cropmarks
@end iftex
@title Debugging with @value{GDBN}
@subtitle The GNU Source-Level Debugger
@ifclear GENERIC
-@subtitle on @value{HOST} Systems
+@subtitle on @value{TARGET} Systems
@end ifclear
@sp 1
@c !!set edition, date, version
@c !!set edition, date, version
This is Edition 4.07, January 1993, for GDB Version @value{GDBVN}.
-@c Makeinfo node defaulting gets very confused by conditionals in menus,
-@c unfortunately. Otherwise we would use the following ignored menu,
-@c which involves four switches:
-@ignore
@menu
* Summary:: Summary of @value{GDBN}
@ifset NOVEL
* Languages:: Using @value{GDBN} with different languages
@end ifclear
@ifset CONLY
-* C:: C and C++
-@end ifset
-* Symbols:: Examining the symbol table
-* Altering:: Altering execution
-* GDB Files:: @value{GDBN} files
-* Targets:: Specifying a debugging target
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-@ifclear DOSHOST
-* Emacs:: Using @value{GDBN} under GNU Emacs
-@end ifclear
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-@ifset NOVEL
-* Renamed Commands::
-@end ifset
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ignore
-@c
-@c Since that does not work, we must unroll the above into 16 cases:
-@c
-@c Menu for NOVEL && !BARETARGET && !CONLY && !DOSHOST
-@ifset NOVEL
-@ifclear BARETARGET
-@ifclear CONLY
-@ifclear DOSHOST
-@menu
-* Summary:: Summary of @value{GDBN}
-* New Features:: New features since GDB version 3.5
-* 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
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* Emacs:: Using @value{GDBN} under GNU Emacs
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Renamed Commands::
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ifclear
-@end ifclear
-@end ifclear
+* C:: C language support
@end ifset
+@c remnant makeinfo bug, blank line needed after two end-ifs?
-@c Menu for NOVEL && !BARETARGET && !CONLY && DOSHOST
-@ifset NOVEL
-@ifclear BARETARGET
-@ifclear CONLY
-@ifset DOSHOST
-@menu
-* Summary:: Summary of @value{GDBN}
-* New Features:: New features since GDB version 3.5
-* 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
* Controlling GDB:: Controlling @value{GDBN}
* Sequences:: Canned sequences of commands
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Renamed Commands::
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ifset
-@end ifclear
-@end ifclear
-@end ifset
-
-@c Menu for NOVEL && !BARETARGET && CONLY && !DOSHOST
-@ifset NOVEL
-@ifclear BARETARGET
-@ifset CONLY
@ifclear DOSHOST
-@menu
-* Summary:: Summary of @value{GDBN}
-* New Features:: New features since GDB version 3.5
-* 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
-* C:: C Language Support
-* Symbols:: Examining the symbol table
-* Altering:: Altering execution
-* GDB Files:: @value{GDBN} files
-* Targets:: Specifying a debugging target
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
* Emacs:: Using @value{GDBN} under GNU Emacs
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Renamed Commands::
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ifclear
-@end ifset
@end ifclear
-@end ifset
-
-@c Menu for NOVEL && !BARETARGET && CONLY && DOSHOST
-@ifset NOVEL
-@ifclear BARETARGET
-@ifset CONLY
-@ifset DOSHOST
-@menu
-* Summary:: Summary of @value{GDBN}
-* New Features:: New features since GDB version 3.5
-* 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
-* C:: C Language Support
-* Symbols:: Examining the symbol table
-* Altering:: Altering execution
-* GDB Files:: @value{GDBN} files
-* Targets:: Specifying a debugging target
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Renamed Commands::
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ifset
-@end ifset
-@end ifclear
-@end ifset
-
-@c Menu for NOVEL && BARETARGET && !CONLY && !DOSHOST
-@ifset NOVEL
-@ifset BARETARGET
-@ifclear CONLY
-@ifclear DOSHOST
-@menu
-* Summary:: Summary of @value{GDBN}
-* New Features:: New features since GDB version 3.5
-* 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
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* Emacs:: Using @value{GDBN} under GNU Emacs
* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Renamed Commands::
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ifclear
-@end ifclear
-@end ifset
-@end ifset
-
-@c Menu for NOVEL && BARETARGET && !CONLY && DOSHOST
@ifset NOVEL
-@ifset BARETARGET
-@ifclear CONLY
-@ifset DOSHOST
-@menu
-* Summary:: Summary of @value{GDBN}
-* New Features:: New features since GDB version 3.5
-* 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
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Renamed Commands::
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ifset
-@end ifclear
-@end ifset
-@end ifset
-
-@c Menu for NOVEL && BARETARGET && CONLY && !DOSHOST
-@ifset NOVEL
-@ifset BARETARGET
-@ifset CONLY
-@ifclear DOSHOST
-@menu
-* Summary:: Summary of @value{GDBN}
-* New Features:: New features since GDB version 3.5
-* 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
-* C:: C Language support
-* Symbols:: Examining the symbol table
-* Altering:: Altering execution
-* GDB Files:: @value{GDBN} files
-* Targets:: Specifying a debugging target
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* Emacs:: Using @value{GDBN} under GNU Emacs
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Renamed Commands::
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ifclear
-@end ifset
-@end ifset
-@end ifset
-
-@c Menu for NOVEL && BARETARGET && CONLY && DOSHOST
-@ifset NOVEL
-@ifset BARETARGET
-@ifset CONLY
-@ifset DOSHOST
-@menu
-* Summary:: Summary of @value{GDBN}
-* New Features:: New features since GDB version 3.5
-* 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
-* C:: C Language support
-* Symbols:: Examining the symbol table
-* Altering:: Altering execution
-* GDB Files:: @value{GDBN} files
-* Targets:: Specifying a debugging target
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* GDB Bugs:: Reporting bugs in @value{GDBN}
* Renamed Commands::
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ifset
-@end ifset
-@end ifset
-@end ifset
-
-@c Menu for !NOVEL && !BARETARGET && !CONLY && !DOSHOST
-@ifclear NOVEL
-@ifclear BARETARGET
-@ifclear CONLY
-@ifclear DOSHOST
-@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
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* Emacs:: Using @value{GDBN} under GNU Emacs
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ifclear
-@end ifclear
-@end ifclear
-@end ifclear
-
-@c Menu for !NOVEL && !BARETARGET && !CONLY && DOSHOST
-@ifclear NOVEL
-@ifclear BARETARGET
-@ifclear CONLY
-@ifset DOSHOST
-@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
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ifset
-@end ifclear
-@end ifclear
-@end ifclear
-
-@c Menu for !NOVEL && !BARETARGET && CONLY && !DOSHOST
-@ifclear NOVEL
-@ifclear BARETARGET
-@ifset CONLY
-@ifclear DOSHOST
-@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
-* C:: C Language support
-* Symbols:: Examining the symbol table
-* Altering:: Altering execution
-* GDB Files:: @value{GDBN} files
-* Targets:: Specifying a debugging target
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* Emacs:: Using @value{GDBN} under GNU Emacs
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ifclear
@end ifset
-@end ifclear
-@end ifclear
-
-@c Menu for !NOVEL && !BARETARGET && CONLY && DOSHOST
-@ifclear NOVEL
-@ifclear BARETARGET
-@ifset CONLY
-@ifset DOSHOST
-@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
-* C:: C Language support
-* Symbols:: Examining the symbol table
-* Altering:: Altering execution
-* GDB Files:: @value{GDBN} files
-* Targets:: Specifying a debugging target
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ifset
-@end ifset
-@end ifclear
-@end ifclear
-
-@c Menu for !NOVEL && BARETARGET && !CONLY && !DOSHOST
-@ifclear NOVEL
-@ifset BARETARGET
-@ifclear CONLY
-@ifclear DOSHOST
-@menu
-* Summary:: Summary of @value{GDBN}
-* 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
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* Emacs:: Using @value{GDBN} under GNU Emacs
-* GDB Bugs:: Reporting bugs in @value{GDBN}
+@ifclear PRECONFIGURED
* Formatting Documentation:: How to format and print GDB documentation
* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ifclear
-@end ifclear
-@end ifset
@end ifclear
-
-@c Menu for !NOVEL && BARETARGET && !CONLY && DOSHOST
-@ifclear NOVEL
-@ifset BARETARGET
-@ifclear CONLY
-@ifset DOSHOST
-@menu
-* Summary:: Summary of @value{GDBN}
-* 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
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
-@end ifset
-@end ifclear
-@end ifset
-@end ifclear
-
-@c Menu for !NOVEL && BARETARGET && CONLY && !DOSHOST
-@ifclear NOVEL
-@ifset BARETARGET
-@ifset CONLY
-@ifclear DOSHOST
-@menu
-* Summary:: Summary of @value{GDBN}
-* 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
-* C:: C Language Support
-* Symbols:: Examining the symbol table
-* Altering:: Altering execution
-* GDB Files:: @value{GDBN} files
-* Targets:: Specifying a debugging target
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* Emacs:: Using @value{GDBN} under GNU Emacs
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
+@ifclear AGGLOMERATION
* Copying:: GNU GENERAL PUBLIC LICENSE
-* Index:: Index
-@end menu
@end ifclear
-@end ifset
-@end ifset
-@end ifclear
-
-@c Menu for !NOVEL && BARETARGET && CONLY && DOSHOST
-@ifclear NOVEL
-@ifset BARETARGET
-@ifset CONLY
-@ifset DOSHOST
-@menu
-* Summary:: Summary of @value{GDBN}
-* 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
-* C:: C Language Support
-* Symbols:: Examining the symbol table
-* Altering:: Altering execution
-* GDB Files:: @value{GDBN} files
-* Targets:: Specifying a debugging target
-* Controlling GDB:: Controlling @value{GDBN}
-* Sequences:: Canned sequences of commands
-* GDB Bugs:: Reporting bugs in @value{GDBN}
-* Formatting Documentation:: How to format and print GDB documentation
-* Installing GDB:: Installing GDB
-* Copying:: GNU GENERAL PUBLIC LICENSE
* Index:: Index
@end menu
-@end ifset
-@end ifset
-@end ifset
-@end ifclear
-
@end ifinfo
@node Summary
Richard Stallman, assisted at various times by Pete TerMaat, Chris
Hanson, and Richard Mlynarik, handled releases through 2.8.
+@ifclear CONLY
Michael Tiemann is the author of most of the GNU C++ support in GDB,
with significant additional contributions from Per Bothner. James
Clark wrote the GNU C++ demangler. Early work on C++ was by Peter
TerMaat (who also did much general update work leading to release 3.0).
+@end ifclear
GDB 4 uses the BFD subroutine library to examine multiple
object-file formats; BFD was a joint project of David V.
the Modula-2 support, and contributed the Languages chapter of this
manual.
-Fred Fish wrote most of the support for Unix System Vr4, and enhanced
-the command-completion support to cover C++ overloaded symbols.
+Fred Fish wrote most of the support for Unix System Vr4.
+@ifclear CONLY
+He also enhanced the command-completion support to cover C++ overloaded
+symbols.
+@end ifclear
+
+Hitachi America, Ltd. sponsored the support for the H8/300 and H8/500.
@ifset NOVEL
@node New Features
(The essentials: type @samp{@value{GDBP}} to start GDB, and type @kbd{quit}
or @kbd{C-d} to exit.)
-@ignore
-@c original form of menu, pre-unfolding:
@menu
* Invoking GDB:: How to start @value{GDBN}
* Quitting GDB:: How to quit @value{GDBN}
* Shell Commands:: How to use shell commands inside @value{GDBN}
@end ifclear
@end menu
-@end ignore
-
-@ifclear BARETARGET
-@menu
-* Invoking GDB:: How to start @value{GDBN}
-* Quitting GDB:: How to quit @value{GDBN}
-* Shell Commands:: How to use shell commands inside @value{GDBN}
-@end menu
-@end ifclear
-
-@ifset BARETARGET
-@menu
-* Invoking GDB:: How to start @value{GDBN}
-* Quitting GDB:: How to quit @value{GDBN}
-@end menu
-@end ifset
@node Invoking GDB
@section Invoking @value{GDBN}
@ifset HviiiEXCLUSIVE
For details on starting up @value{GDBP} as a
-remote debugger attached to a Hitachi H8/300 board, see @ref{Hitachi
-H8/300 Remote,,@value{GDBN} and the Hitachi H8/300}.
+remote debugger attached to a Hitachi H8/300 or H8/500 board, see @ref{Hitachi
+H8 Remote,,@value{GDBN} and the Hitachi H8/300 and H8/500}.
@end ifset
Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started,
@samp{-x} option is used.
-@ignore
-@c original, intended form of this menu (pre-unfolding):
@menu
@ifclear GENERIC
@ifset REMOTESTUB
* ST2000 Remote:: @value{GDBN} with a Tandem ST2000
@end ifset
@ifset Hviii
-* Hitachi H8/300 Remote:: @value{GDBN} and the Hitachi H8/300
+* Hitachi H8 Remote:: @value{GDBN} and the Hitachi H8/300 and H8/500
@end ifset
@ifset SIMS
* Simulator:: Simulated CPU target
@end ifset
@end ifclear
-* File Options:: Choosing files
-* Mode Options:: Choosing modes
-@end menu
-@end ignore
-
-@c Unfolded form:
-@c Sigh--- GENERIC plus 7 switches mean 1+2^7 forms of this menu!
-@c Add them only on demand; no point in including forms for which
-@c there's no defined config file. Maybe by the time all are needed,
-@c makeinfo will be capable of dealing with menus like the above.
-
-@ifset GENERIC
-@menu
-* File Options:: Choosing files
-* Mode Options:: Choosing modes
-@end menu
-@end ifset
+@c remnant makeinfo bug requires this blank line after *two* end-ifblahs:
-@c Hviii config: !GENERIC && Hviii && nothing else
-@ifclear GENERIC
-@ifclear REMOTESTUB
-@ifclear Icmlx
-@ifclear AMDxxixK
-@ifclear VXWORKS
-@ifclear STmm
-@ifset Hviii
-@ifclear ZviiiK
-@menu
-* Hitachi H8/300 Remote:: @value{GDBN} and the Hitachi H8/300
-* Simulator:: Simulated CPU target
* File Options:: Choosing files
* Mode Options:: Choosing modes
@end menu
-@end ifclear
-@end ifset
-@end ifclear
-@end ifclear
-@end ifclear
-@end ifclear
-@end ifclear
-@end ifclear
@ifclear GENERIC
@include gdbinv-s.texi
@item -exec=@var{file}
@itemx -e @var{file}
Use file @var{file} as the executable file to execute when
+@ifset BARETARGET
+appropriate.
+@end ifset
+@ifclear BARETARGET
appropriate, and for examining pure data in conjunction with a core
dump.
+@end ifclear
@item -se=@var{file}
Read symbol table from file @var{file} and use it as the executable
and will quickly map in symbol information from it, rather than reading
the symbol table from the executable program.
-The @file{.syms} file is specific to the host machine on which @value{GDBN} is run.
-It holds an exact image of the internal @value{GDBN} symbol table. It cannot be
-shared across multiple host platforms.
+@c FIXME! Really host, not target?
+The @file{.syms} file is specific to the host machine where @value{GDBN}
+is run. It holds an exact image of the internal @value{GDBN} symbol
+table. It cannot be shared across multiple host platforms.
@end ifclear
@item -r
@value{GDBN} with Energize} for more discussion of using @value{GDBN} with Energize.
@end ifset
+@ifclear DOSHOST
@item -fullname
@itemx -f
Emacs sets this option when it runs @value{GDBN} as a subprocess. It tells @value{GDBN}
and character position separated by colons, and a newline. The
Emacs-to-@value{GDBN} interface program uses the two @samp{\032} characters as
a signal to display the source code for the frame.
+@end ifclear
@ifset SERIAL
@item -b @var{bps}
notion of a word. To permit word completion to work in this situation,
you may enclose words in @code{'} (single quote marks) in @value{GDBN} commands.
+@ifclear CONLY
The most likely situation where you might need this is in typing the
name of a C++ function. This is because C++ allows function overloading
(multiple definitions of the same function, distinguished by argument
In general, @value{GDBN} can tell that a quote is needed (and inserts it) if
you have not yet started typing the argument list when you ask for
completion on an overloaded symbol.
+@end ifclear
@node Help
@chapter Running Programs Under @value{GDBN}
When you run a program under @value{GDBN}, you must first generate
-debugging information when you compile it. You may start it with its
-arguments, if any, in an environment of your choice. You may redirect
-your program's input and output, debug an already running process, or
-kill a child process.
-
-@ignore
-@c pre-unfolding:
-@menu
-* Compilation:: Compiling for debugging
-* Starting:: Starting your program
+debugging information when you compile it.
@ifclear BARETARGET
-* Arguments:: Your program's arguments
-* Environment:: Your program's environment
-* Working Directory:: Your program's working directory
-* Input/Output:: Your program's input and output
-* Attach:: Debugging an already-running process
-* Kill Process:: Killing the child process
-* Process Information:: Additional process information
+You may start it with its arguments, if any, in an environment of your
+choice. You may redirect your program's input and output, debug an
+already running process, or kill a child process.
@end ifclear
-@end menu
-@end ignore
-@ifclear BARETARGET
@menu
* Compilation:: Compiling for debugging
* Starting:: Starting your program
+@ifclear BARETARGET
* Arguments:: Your program's arguments
* Environment:: Your program's environment
* Working Directory:: Your program's working directory
* Attach:: Debugging an already-running process
* Kill Process:: Killing the child process
* Process Information:: Additional process information
-@end menu
@end ifclear
-
-@ifset BARETARGET
-@menu
-* Compilation:: Compiling for debugging
-* Starting:: Starting your program
@end menu
-@end ifset
@node Compilation
@section Compiling for debugging
@table @code
@item attach @var{process-id}
-This command
-attaches to a running process---one that was started outside @value{GDBN}.
-(@code{info files} will show your active targets.) The command takes as
-argument a process ID. The usual way to find out the process-id of
-a Unix process is with the @code{ps} utility, or with the @samp{jobs -l}
-shell command.
+This command attaches to a running process---one that was started
+outside @value{GDBN}. (@code{info files} will show your active
+targets.) The command takes as argument a process ID. The usual way to
+find out the process-id of a Unix process is with the @code{ps} utility,
+or with the @samp{jobs -l} shell command.
@code{attach} will not repeat if you press @key{RET} a second time after
executing the command.
trouble, you can investigate and find out why.
Inside @value{GDBN}, your program may stop for any of several reasons, such
-as a signal, a breakpoint, or reaching a new line after a @value{GDBN}
+as
+@ifclear BARETARGET
+a signal,
+@end ifclear
+a breakpoint, or reaching a new line after a @value{GDBN}
command such as @code{step}. You may then examine and change
variables, set new breakpoints or remove old ones, and then continue
execution. Usually, the messages shown by @value{GDBN} provide ample
@item info program
@kindex info program
Display information about the status of your program: whether it is
-running or not, what process it is, and why it stopped.
+running or not,
+@ifclear BARETARGET
+what process it is,
+@end ifclear
+and why it stopped.
@end table
-@ignore
-@c original menu
@menu
@ifclear CONLY
* Breakpoints:: Breakpoints, watchpoints, and exceptions
@ifset CONLY
* Breakpoints:: Breakpoints and watchpoints
@end ifset
-* Continuing and Stepping:: Resuming execution
-@ifset POSIX
-* Signals:: Signals
-@end ifset
-@end menu
-@end ignore
+@c Remnant makeinfo bug requires blank line after *successful* end-if in menu:
-@c !CONLY && POSIX
-@ifclear CONLY
-@ifset POSIX
-@menu
-* Breakpoints:: Breakpoints, watchpoints, and exceptions
* Continuing and Stepping:: Resuming execution
-* Signals:: Signals
-@end menu
-@end ifset
-@end ifclear
-
-@c CONLY && POSIX
-@ifset CONLY
@ifset POSIX
-@menu
-* Breakpoints:: Breakpoints and watchpoints
-* Continuing and Stepping:: Resuming execution
* Signals:: Signals
-@end menu
-@end ifset
@end ifset
-
-@c !CONLY && !POSIX
-@ifclear CONLY
-@ifclear POSIX
-@menu
-* Breakpoints:: Breakpoints, watchpoints, and exceptions
-* Continuing and Stepping:: Resuming execution
-@end menu
-@end ifclear
-@end ifclear
-
-@c CONLY && !POSIX
-@ifset CONLY
-@ifclear POSIX
-@menu
-* Breakpoints:: Breakpoints and watchpoints
-* Continuing and Stepping:: Resuming execution
@end menu
-@end ifclear
-@end ifset
-@c node-defaulting requires adjacency of @node and sectioning cmds
+@c makeinfo node-defaulting requires adjacency of @node and sectioning cmds
@c ...hence distribute @node Breakpoints over two possible @if expansions.
@c
@ifclear CONLY
@menu
* Set Breaks:: Setting breakpoints
* Set Watchpoints:: Setting watchpoints
+@ifclear CONLY
* Exception Handling:: Breakpoints and exceptions
+@end ifclear
* Delete Breaks:: Deleting breakpoints
* Disabling:: Disabling breakpoints
* Conditions:: Break conditions
* Break Commands:: Breakpoint command lists
+@ifclear CONLY
* Breakpoint Menus:: Breakpoint menus
+@end ifclear
+@ifclear BARETARGET
* Error in Breakpoints:: ``Cannot insert breakpoints''
+@end ifclear
@end menu
@node Set Breaks
same as @code{info break}.
@end table
+@ifclear CONLY
@node Exception Handling
@subsection Breakpoints and exceptions
@cindex exception handlers
@noindent
To make the debugger catch all exceptions before any stack
unwinding takes place, set a breakpoint on @code{__raise_exception}
-@ifclear CONLY
(@pxref{Breakpoints, ,Breakpoints; watchpoints; and exceptions}).
-@end ifclear
-@ifset CONLY
-(@pxref{Breakpoints, ,Breakpoints and watchpoints}).
-@end ifset
With a conditional breakpoint (@pxref{Conditions, ,Break conditions})
that depends on the value of @var{id}, you can stop your program when
a specific exception is raised. You can use multiple conditional
breakpoints to stop your program when any of a number of exceptions are
raised.
+@end ifclear
@node Delete Breaks
@subsection Deleting breakpoints
to have nontrivial conditions for performing the side effects, the
operators @samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful.
+@ifclear CONLY
@node Breakpoint Menus
@subsection Breakpoint menus
@cindex overloading
Use the "delete" command to delete unwanted breakpoints.
(@value{GDBP})
@end example
+@end ifclear
+@ifclear BARETARGET
@node Error in Breakpoints
@subsection ``Cannot insert breakpoints''
linker option @samp{-N}. The operating system limitation may not apply
to nonsharable executables.
@end enumerate
+@end ifclear
@node Continuing and Stepping
@section Continuing and stepping
@item step @var{count}
Continue running as in @code{step}, but do so @var{count} times. If a
-breakpoint is reached or a signal not related to stepping occurs before
-@var{count} steps, stepping stops right away.
+breakpoint is reached,
+@ifclear BARETARGET
+or a signal not related to stepping occurs before @var{count} steps,
+@end ifclear
+stepping stops right away.
@item next @r{[}@var{count}@r{]}
@kindex next
line. These are all variables (declared either static or automatic)
accessible at the point of execution of the selected frame.
+@ifclear CONLY
@item info catch
@kindex info catch
@cindex catch exceptions
exception handlers, visit the associated frame (using the @code{up},
@code{down}, or @code{frame} commands); then type @code{info catch}.
@xref{Exception Handling, ,Breakpoints and exceptions}.
+@end ifclear
@end table
@node Source
Emacs}.
@end ifclear
-@ignore
-@c pre-unfolded menu
@menu
* List:: Printing source lines
@ifclear DOSHOST
* Source Path:: Specifying source directories
* Machine Code:: Source and machine code
@end menu
-@end ignore
-
-@ifclear DOSHOST
-@menu
-* List:: Printing source lines
-* Search:: Searching source files
-* Source Path:: Specifying source directories
-* Machine Code:: Source and machine code
-@end menu
-@end ifclear
-
-@ifset DOSHOST
-@menu
-* List:: Printing source lines
-* Source Path:: Specifying source directories
-* Machine Code:: Source and machine code
-@end menu
-@end ifset
@node List
@section Printing source lines
specified format. @xref{Memory, ,Examining memory}.
If you are interested in information about types, or about how the fields
-of a struct or class are declared, use the @code{ptype @var{exp}}
-command rather than @code{print}. @xref{Symbols, ,Examining the Symbol Table}.
-
-@ignore
-@c pre-unfold
-@menu
-* Expressions:: Expressions
-* Variables:: Program variables
-* Arrays:: Artificial arrays
-* Output formats:: Output formats
-* Memory:: Examining memory
-* Auto Display:: Automatic display
-* Print Settings:: Print settings
-* Value History:: Value history
-* Convenience Vars:: Convenience variables
-* Registers:: Registers
-@ifclear HviiiEXCLUSIVE
-* Floating Point Hardware:: Floating point hardware
+of a struct
+@ifclear CONLY
+or class
@end ifclear
-@end menu
-@end ignore
+are declared, use the @code{ptype @var{exp}}
+command rather than @code{print}. @xref{Symbols, ,Examining the Symbol Table}.
-@ifclear HviiiEXCLUSIVE
@menu
* Expressions:: Expressions
* Variables:: Program variables
* Value History:: Value history
* Convenience Vars:: Convenience variables
* Registers:: Registers
+@ifclear HviiiEXCLUSIVE
* Floating Point Hardware:: Floating point hardware
-@end menu
@end ifclear
-
-@ifset HviiiEXCLUSIVE
-@menu
-* Expressions:: Expressions
-* Variables:: Program variables
-* Arrays:: Artificial arrays
-* Output Formats:: Output formats
-* Memory:: Examining memory
-* Auto Display:: Automatic display
-* Print Settings:: Print settings
-* Value History:: Value history
-* Convenience Vars:: Convenience variables
-* Registers:: Registers
@end menu
-@end ifset
@node Expressions
@section Expressions
@end table
+@ifclear CONLY
@noindent
These settings are of interest when debugging C++ programs:
@kindex show print vtbl
Show whether C++ virtual function tables are pretty printed, or not.
@end table
+@end ifclear
@node Value History
@section Value history
@section Floating point hardware
@cindex floating point
+@c FIXME! Really host, not target?
Depending on the host machine architecture, @value{GDBN} may be able to give
you more information about the status of the floating point hardware.
The @code{set print union} and @code{show print union} commands apply to
the @code{union} type. When set to @samp{on}, any @code{union} that is
-inside a @code{struct} or @code{class} will also be printed.
+inside a @code{struct}
+@ifclear CONLY
+or @code{class}
+@end ifclear
+will also be printed.
Otherwise, it will appear as @samp{@{...@}}.
The @code{@@} operator aids in the debugging of dynamic arrays, formed
program.
For example, you can store new values into variables or memory
-locations, give your program a signal, restart it at a different address,
-or even return prematurely from a function to its caller.
-
-@ignore
-@c pre-unfold
-@menu
-* Assignment:: Assignment to variables
-* Jumping:: Continuing at a different address
+locations,
@ifclear BARETARGET
-* Signaling:: Giving your program a signal
+give your program a signal, restart it
@end ifclear
-* Returning:: Returning from a function
-* Calling:: Calling your program's functions
-* Patching:: Patching your program
-@end menu
-@end ignore
+@ifset BARETARGET
+restart your program
+@end ifset
+at a different address, or even return prematurely from a function to
+its caller.
-@ifclear BARETARGET
@menu
* Assignment:: Assignment to variables
* Jumping:: Continuing at a different address
+@ifclear BARETARGET
* Signaling:: Giving your program a signal
-* Returning:: Returning from a function
-* Calling:: Calling your program's functions
-* Patching:: Patching your program
-@end menu
@end ifclear
-
-@ifset BARETARGET
-@menu
-* Assignment:: Assignment to variables
-* Jumping:: Continuing at a different address
* Returning:: Returning from a function
* Calling:: Calling your program's functions
* Patching:: Patching your program
@end menu
-@end ifset
@node Assignment
@section Assignment to variables
@section Patching programs
@cindex patching binaries
@cindex writing into executables
+@ifclear BARETARGET
@cindex writing into corefiles
+@end ifclear
By default, @value{GDBN} opens the file containing your program's executable
-code (or the corefile) read-only. This prevents accidental alterations
+code
+@ifclear BARETARGET
+(or the corefile)
+@end ifclear
+read-only. This prevents accidental alterations
to machine code; but it also prevents you from intentionally patching
your program's binary.
files for both reading and writing; if you specify @samp{set write
off} (the default), @value{GDBN} will open them read-only.
-If you have already loaded a file, you must load it
-again (using the @code{exec-file} or @code{core-file} command) after
-changing @code{set write}, for your new setting to take effect.
+If you have already loaded a file, you must load it again (using the
+@code{exec-file}
+@ifclear BARETARGET
+or @code{core-file}
+@end ifclear
+command) after changing @code{set write}, for your new setting to take
+effect.
@item show write
@kindex show write
@end ifset
@ifset Hviii
-@cindex download to H8/300
-@cindex H8/300 download
-When you select remote debugging to a Hitachi H8/300 board (@pxref{Hitachi
-H8/300 Remote,,@value{GDBN} and the Hitachi H8/300}), the
-@code{load} command downloads your program to the H8/300 and also opens
-it as the current executable target for @value{GDBN} on your host (like the
-@code{file} command).
+@cindex download to H8/300 or H8/500
+@cindex H8/300 or H8/500 download
+When you select remote debugging to a Hitachi H8/300 or H8/500 board
+(@pxref{Hitachi H8 Remote,,@value{GDBN} and the Hitachi H8/300 and H8/500}),
+the @code{load} command downloads your program to the Hitachi board and also
+opens it as the current executable target for @value{GDBN} on your host
+(like the @code{file} command).
@end ifset
@code{load} will not repeat if you press @key{RET} again after using it.
@kindex info files
@kindex info target
@code{info files} and @code{info target} are synonymous; both print
-the current targets (@pxref{Targets, ,Specifying a Debugging Target}),
-including the names of the executable and core dump files currently in
-use by @value{GDBN}, and the files from which symbols were loaded. The command
-@code{help targets} lists all possible targets rather than current
-ones.
+the current target (@pxref{Targets, ,Specifying a Debugging Target}),
+including the
+@ifclear BARETARGET
+names of the executable and core dump files
+@end ifclear
+@ifset BARETARGET
+name of the executable file
+@end ifset
+currently in use by @value{GDBN}, and the files from which symbols were
+loaded. The command @code{help targets} lists all possible targets
+rather than current ones.
@end table
All file-specifying commands allow both absolute and relative file names
examine @code{*bufp} to see the symbol.
@item stub type has NULL name
-@value{GDBN} could not find the full definition for a struct or class.
+@value{GDBN} could not find the full definition for
+@ifclear CONLY
+a struct or class.
+@end ifclear
+@ifset CONLY
+a struct.
+@end ifset
+@ifclear CONLY
@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{}
The symbol information for a C++ member function is missing some
information that recent versions of the compiler should have output
for it.
+@end ifclear
@item info mismatch between compiler and debugger
@table @code
@item target @var{type} @var{parameters}
-Connects the @value{GDBN} host environment to a target machine or process. A
-target is typically a protocol for talking to debugging facilities. You
-use the argument @var{type} to specify the type or protocol of the
-target machine.
+Connects the @value{GDBN} host environment to a target
+@ifset BARETARGET
+machine.
+@end ifset
+@ifclear BARETARGET
+machine or process. A target is typically a protocol for talking to
+debugging facilities. You use the argument @var{type} to specify the
+type or protocol of the target machine.
Further @var{parameters} are interpreted by the target protocol, but
typically include things like device names or host names to connect
with, process numbers, and baud rates.
+@end ifclear
The @code{target} command will not repeat if you press @key{RET} again
after executing the command.
An executable file. @samp{target exec @var{program}} is the same as
@samp{exec-file @var{program}}.
+@ifclear BARETARGET
@item target core @var{filename}
@kindex target core
A core dump file. @samp{target core @var{filename}} is the same as
@samp{core-file @var{filename}}.
+@end ifclear
@ifset REMOTESTUB
@item target remote @var{dev}
@ifset Hviii
@item target hms
@kindex target hms
-A Hitachi H8/300 board, attached via serial line to your host. Use
+A Hitachi H8/300 or H8/500 board, attached via serial line to your host. Use
special commands @code{device} and @code{speed} to control the serial
-line and the communications speed used. @xref{Hitachi H8/300
-Remote,,@value{GDBN} and the Hitachi H8/300}.
+line and the communications speed used. @xref{Hitachi H8
+Remote,,@value{GDBN} and the Hitachi H8/300 and H8/500}.
@end ifset
@ifset Icmlx
@c Text on starting up GDB in various specific cases; it goes up front
@c in manuals configured for any of those particular situations, here
@c otherwise.
-@ignore
-@c original, intended form of this menu (pre-unfolding):
@menu
@ifset REMOTESTUB
* Remote Serial:: @value{GDBN} remote serial protocol
* ST2000 Remote:: @value{GDBN} with a Tandem ST2000
@end ifset
@ifset Hviii
-* Hitachi H8/300 Remote:: @value{GDBN} and the Hitachi H8/300
+* Hitachi H8 Remote:: @value{GDBN} and the Hitachi H8/300 and H8/500
@end ifset
@ifset SIMS
* Simulator:: Simulated CPU target
@end ifset
@end menu
-@end ignore
-
-@c Unfolded menus:
-@c add as configs require, while unfolding remains necessary.
-@c
-@c All target details:
-@menu
-* Remote Serial:: @value{GDBN} remote serial protocol
-* i960-Nindy Remote:: @value{GDBN} with a remote i960 (Nindy)
-* UDI29K Remote:: @value{GDBN} and the UDI protocol for AMD29K
-* EB29K Remote:: @value{GDBN} with a remote EB29K
-* VxWorks Remote:: @value{GDBN} and VxWorks
-* ST2000 Remote:: @value{GDBN} with a Tandem ST2000
-* Hitachi H8/300 Remote:: @value{GDBN} and the Hitachi H8/300
-* Simulator:: Simulated CPUs
-@end menu
@include gdbinv-s.texi
@end ifset
command @samp{hook-foo} exists, it is executed (with no arguments)
before that command.
-In addition, a pseudo-command, @samp{stop} exists. Hooking this command
-will cause your hook to be executed every time execution stops in the
-inferior program, before breakpoint commands are run, displays are
-printed, or the stack frame is printed.
+In addition, a pseudo-command, @samp{stop} exists. Defining
+(@samp{hook-stop}) makes the associated commands execute every time
+execution stops in your program: before breakpoint commands are run,
+displays are printed, or the stack frame is printed.
-For example, to cause @code{SIGALRM} signals to be ignored while
-single-stepping, but cause them to be resumed during normal execution,
-you could do:
+@ifclear BARETARGET
+For example, to ignore @code{SIGALRM} signals while
+single-stepping, but treat them normally during normal execution,
+you could define:
@example
define hook-stop
handle SIGLARM pass
end
@end example
+@end ifclear
-Any single-word command in GDB can be hooked. Aliases for other commands
-cannot be hooked (you should hook the basic command name, e.g. @code{backtrace}
-rather than @code{bt}). If an error occurs during the execution of your
-hook, execution of GDB commands stops and you are returned to the GDB
-prompt (before the command that you actually typed had a chance to run).
+You can define a hook for any single-word command in @value{GDBN}, but
+not for command aliases; you should define a hook for the basic command
+name, e.g. @code{backtrace} rather than @code{bt}.
+@c FIXME! So how does Joe User discover whether a command is an alias
+@c or not?
+If an error occurs during the execution of your hook, execution of
+@value{GDBN} commands stops and @value{GDBN} issues a prompt
+(before the command that you actually typed had a chance to run).
If you try to define a hook which does not match any known command, you
will get a warning from the @code{define} command.
@itemize @bullet
@item
@cindex fatal signal
-@cindex core dump
+@cindex debugger crash
+@cindex crash of debugger
If the debugger gets a fatal signal, for any input whatever, that is a
@value{GDBN} bug. Reliable debuggers never crash.
projects / binutils-gdb.git / commitdiff