8734fc33eb
page (had crept onto front of title page w/ other stuff migrating between
gdb.texinfo and gdb.top-m4).
2) gdb.top-m4: added Detailed Node Listing to main menu.
made $Id: for fragment into texinfo comment.
451 lines
16 KiB
Text
Executable file
451 lines
16 KiB
Text
Executable file
_dnl__ -*- Texinfo -*-
|
|
_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
|
|
_dnl__ This file is part of the source for the GDB manual.
|
|
@c M4 FRAGMENT: $Id$
|
|
@c
|
|
@syncodeindex ky cp
|
|
@c FOR UPDATES LEADING TO THIS DRAFT, GDB CHANGELOG CONSULTED BETWEEN:
|
|
@c Sun May 19 05:36:59 1991 John Gilmore (gnu at cygint.cygnus.com)
|
|
@c Sat Dec 22 02:51:40 1990 John Gilmore (gnu at cygint)
|
|
@ifinfo
|
|
This file documents the GNU debugger _GDBN__.
|
|
|
|
Copyright (C) 1988, 1989, 1990, 1991 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
@ignore
|
|
Permission is granted to process this file through TeX and print the
|
|
results, provided the printed document carries copying permission
|
|
notice identical to this one except for the removal of this paragraph
|
|
(this paragraph not being relevant to the printed manual).
|
|
|
|
@end ignore
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided also that the
|
|
section entitled ``GNU General Public License'' is included exactly as
|
|
in the original, and provided that the entire resulting derived work is
|
|
distributed under the terms of a permission notice identical to this
|
|
one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions,
|
|
except that the section entitled ``GNU General Public License'' may be
|
|
included in a translation approved by the Free Software Foundation
|
|
instead of in the original English.
|
|
@end ifinfo
|
|
@smallbook
|
|
@setchapternewpage odd
|
|
_if__(_GENERIC__)
|
|
@settitle Using _GDBN__ (v4.0)
|
|
_fi__(_GENERIC__)
|
|
_if__(!_GENERIC__)
|
|
@settitle Using _GDBN__ v4.0 (_HOST__)
|
|
_fi__(!_GENERIC__)
|
|
@iftex
|
|
@finalout
|
|
@end iftex
|
|
@titlepage
|
|
@title{Using _GDBN__}
|
|
@subtitle{A Guide to the GNU Source-Level Debugger}
|
|
_if__(!_GENERIC__)
|
|
@subtitle{On _HOST__ Systems}
|
|
_fi__(!_GENERIC__)
|
|
@sp 1
|
|
@c Maybe crank this up to "Fourth Edition" when released at FSF
|
|
@c @subtitle Third Edition---_GDBN__ version 4.0
|
|
@subtitle _GDBN__ version 4.0
|
|
@subtitle May 1991
|
|
@author{Richard M. Stallman@qquad @hfill Free Software Foundation}
|
|
@author{Roland H. Pesch@qquad @hfill Cygnus Support}
|
|
@page
|
|
@tex
|
|
{\parskip=0pt
|
|
\hfill rms\@ai.mit.edu, pesch\@cygnus.com\par
|
|
\hfill {\it Using _GDBN__}, \manvers\par
|
|
\hfill \TeX{}info \texinfoversion\par
|
|
}
|
|
@end tex
|
|
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 1988, 1989, 1990, 1991 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided also that the
|
|
section entitled ``GNU General Public License'' is included exactly as
|
|
in the original, and provided that the entire resulting derived work is
|
|
distributed under the terms of a permission notice identical to this
|
|
one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions,
|
|
except that the section entitled ``GNU General Public License'' may be
|
|
included in a translation approved by the Free Software Foundation
|
|
instead of in the original English.
|
|
@end titlepage
|
|
@page
|
|
|
|
@node Top, Summary, (dir), (dir)
|
|
@ifinfo
|
|
This file describes version 4.0 of GDB, the GNU symbolic debugger.
|
|
@end ifinfo
|
|
|
|
@menu
|
|
* Summary:: Summary of _GDBN__
|
|
* New Features:: New Features in _GDBN__ version 4.0
|
|
* Sample Session:: A Sample _GDBN__ Session
|
|
* Invocation:: Getting In and Out of _GDBN__
|
|
* Commands::
|
|
* Running:: Running Programs Under _GDBN__
|
|
* Stopping:: Stopping and Continuing
|
|
* Stack:: Examining the Stack
|
|
* Source:: Examining Source Files
|
|
* Data:: Examining Data
|
|
* Symbols:: Examining the Symbol Table
|
|
* Altering:: Altering Execution
|
|
* _GDBN__ Files::
|
|
* Targets:: Specifying a Debugging Target
|
|
* Controlling _GDBN__:: Controlling _GDBN__
|
|
* Sequences:: Canned Sequences of Commands
|
|
* Emacs:: Using _GDBN__ under GNU Emacs
|
|
* _GDBN__ Bugs:: Reporting Bugs in _GDBN__
|
|
* Renamed Commands::
|
|
* Installing _GDBN__:: Installing _GDBN__
|
|
* Copying:: GNU GENERAL PUBLIC LICENSE
|
|
* Index:: Index
|
|
--- The Detailed Node Listing ---
|
|
|
|
Summary of _GDBN__
|
|
|
|
* Free Software:: Free Software
|
|
* Contributors:: Contributors to _GDBN__
|
|
|
|
Getting In and Out of _GDBN__
|
|
|
|
* Starting _GDBN__:: Starting _GDBN__
|
|
* Leaving _GDBN__:: Leaving _GDBN__
|
|
* Shell Commands:: Shell Commands
|
|
|
|
Starting _GDBN__
|
|
|
|
* File Options:: Choosing Files
|
|
* Mode Options:: Choosing Modes
|
|
|
|
_GDBN__ Commands
|
|
|
|
* Command Syntax:: Command Syntax
|
|
* Help:: Getting Help
|
|
|
|
Running Programs Under _GDBN__
|
|
|
|
* Compilation:: Compiling for Debugging
|
|
* Starting:: Starting your Program
|
|
* 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
|
|
|
|
Stopping and Continuing
|
|
|
|
* Breakpoints:: Breakpoints, Watchpoints, and Exceptions
|
|
* Stepping:: Stepping
|
|
* Continuing:: Continuing
|
|
* Signals:: Signals
|
|
|
|
Breakpoints, Watchpoints, and Exceptions
|
|
|
|
* Set Breaks:: Setting Breakpoints
|
|
* Set Watchpoints:: Setting Watchpoints
|
|
* Exception Handling:: Breakpoints and Exceptions
|
|
* Delete Breaks:: Deleting Breakpoints
|
|
* Disabling:: Disabling Breakpoints
|
|
* Conditions:: Break Conditions
|
|
* Break Commands:: Breakpoint Command Lists
|
|
* Breakpoint Menus:: Breakpoint Menus
|
|
* Error in Breakpoints::
|
|
|
|
Examining the Stack
|
|
|
|
* Frames:: Stack Frames
|
|
* Backtrace:: Backtraces
|
|
* Selection:: Selecting a Frame
|
|
* Frame Info:: Information on a Frame
|
|
|
|
Examining Source Files
|
|
|
|
* List:: Printing Source Lines
|
|
* Search:: Searching Source Files
|
|
* Source Path:: Specifying Source Directories
|
|
* Machine Code:: Source and Machine Code
|
|
|
|
Examining Data
|
|
|
|
* 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
|
|
* Floating Point Hardware:: Floating Point Hardware
|
|
|
|
Altering Execution
|
|
|
|
* Assignment:: Assignment to Variables
|
|
* Jumping:: Continuing at a Different Address
|
|
* Signaling:: Giving the Program a Signal
|
|
* Returning:: Returning from a Function
|
|
* Calling:: Calling your Program's Functions
|
|
|
|
_GDBN__'s Files
|
|
|
|
* Files:: Commands to Specify Files
|
|
* Symbol Errors:: Errors Reading Symbol Files
|
|
|
|
Specifying a Debugging Target
|
|
|
|
* Active Targets:: Active Targets
|
|
* Target Commands:: Commands for Managing Targets
|
|
* Remote:: Remote Debugging
|
|
|
|
Remote Debugging
|
|
|
|
* i960-Nindy Remote::
|
|
* EB29K Remote::
|
|
* VxWorks Remote::
|
|
|
|
_GDBN__ with a Remote i960 (Nindy)
|
|
|
|
* Nindy Startup:: Startup with Nindy
|
|
* Nindy Options:: Options for Nindy
|
|
* Nindy reset:: Nindy Reset Command
|
|
|
|
_GDBN__ with a Remote EB29K
|
|
|
|
* Comms (EB29K):: Communications Setup
|
|
* gdb-EB29K:: EB29K cross-debugging
|
|
* Remote Log:: Remote Log
|
|
|
|
_GDBN__ and VxWorks
|
|
|
|
* VxWorks connection:: Connecting to VxWorks
|
|
* VxWorks download:: VxWorks Download
|
|
* VxWorks attach:: Running Tasks
|
|
|
|
Controlling _GDBN__
|
|
|
|
* Prompt:: Prompt
|
|
* Editing:: Command Editing
|
|
* History:: Command History
|
|
* Screen Size:: Screen Size
|
|
* Numbers:: Numbers
|
|
* Messages/Warnings:: Optional Warnings and Messages
|
|
|
|
Canned Sequences of Commands
|
|
|
|
* Define:: User-Defined Commands
|
|
* Command Files:: Command Files
|
|
* Output:: Commands for Controlled Output
|
|
|
|
Reporting Bugs in _GDBN__
|
|
|
|
* Bug Criteria:: Have You Found a Bug?
|
|
* Bug Reporting:: How to Report Bugs
|
|
@end menu
|
|
|
|
@node Summary, New Features, Top, Top
|
|
@unnumbered Summary of _GDBN__
|
|
|
|
The purpose of a debugger such as _GDBN__ is to allow you to see what is
|
|
going on ``inside'' another program while it executes---or what another
|
|
program was doing at the moment it crashed.
|
|
|
|
_GDBN__ can do four main kinds of things (plus other things in support of
|
|
these) to help you catch bugs in the act:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Start your program, specifying anything that might affect its behavior.
|
|
|
|
@item
|
|
Make your program stop on specified conditions.
|
|
|
|
@item
|
|
Examine what has happened, when your program has stopped.
|
|
|
|
@item
|
|
Change things in your program, so you can experiment with correcting the
|
|
effects of one bug and go on to learn about another.
|
|
@end itemize
|
|
|
|
_GDBN__ can be used to debug programs written in C and C++. Pascal support
|
|
is being implemented, and Fortran support will be added when a GNU
|
|
Fortran compiler is ready.
|
|
|
|
@menu
|
|
* Free Software:: Free Software
|
|
* Contributors:: Contributors to GDB
|
|
@end menu
|
|
|
|
@node Free Software, Contributors, Summary, Summary
|
|
@unnumberedsec Free Software
|
|
_GDBN__ is @dfn{free software}, protected by the 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
|
|
freedom to modify that copy (which means that they must get access to
|
|
the source code), and the freedom to distribute further copies.
|
|
Typical software companies use copyrights to limit your freedoms; the
|
|
Free Software Foundation uses the GPL to preserve these freedoms.
|
|
|
|
Fundamentally, the General Public License is a license which says that
|
|
you have these freedoms and that you can't take these freedoms away
|
|
from anyone else.
|
|
|
|
@c FIXME: (passim) go through all xrefs, expanding to use text headings
|
|
For full details, @pxref{Copying}.
|
|
@node Contributors, , Free Software, Summary
|
|
@unnumberedsec Contributors to GDB
|
|
|
|
Richard Stallman was the original author of GDB, as with many 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 GDB distribution approximates a blow-by-blow
|
|
account.
|
|
|
|
Changes much prior to version 2.0 are lost in the mists of time.
|
|
|
|
@quotation
|
|
@emph{Plea:} Additions to this section are particularly welcome. If you
|
|
or your friends (or enemies; let's be evenhanded) have been unfairly
|
|
omitted from this list, we would like to add your names!
|
|
@end quotation
|
|
|
|
So that they may not regard their long labor as thankless, we
|
|
particularly thank those who shepherded GDB through major releases:
|
|
John Gilmore (release 4.0); Jim Kingdon (releases 3.9, 3.5, 3.4, 3.3);
|
|
and Randy Smith (releases 3.2, 3.1, 3.0). As major maintainer of GDB
|
|
for some period, each contributed significantly to the structure,
|
|
stability, and capabilities of the entire debugger.
|
|
|
|
Richard Stallman, assisted at various times by Pete TerMaat, Chris
|
|
Hanson, and Richard Mlynarik, handled releases through 2.8.
|
|
|
|
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).
|
|
|
|
GDB 4.0 uses the BFD subroutine library to examine multiple
|
|
object-file formats; BFD was a joint project of V. Gumby
|
|
Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
|
|
|
|
David Johnson wrote the original COFF support; Pace Willison did
|
|
the original support for encapsulated COFF.
|
|
|
|
Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
|
|
Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
|
|
support. Jean-Daniel Fekete contributed Sun 386i support. Chris
|
|
Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki
|
|
Hasei contributed Sony/News OS 3 support. David Johnson contributed
|
|
Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support.
|
|
Keith Packard contributed NS32K support. Doug Rabson contributed
|
|
Acorn Risc Machine support. Chris Smith contributed Convex support
|
|
(and Fortran debugging). Jonathan Stone contributed Pyramid support.
|
|
Michael Tiemann contributed SPARC support. Tim Tucker contributed
|
|
support for the Gould NP1 and Gould Powernode. Pace Willison
|
|
contributed Intel 386 support. Jay Vosburgh contributed Symmetry
|
|
support.
|
|
|
|
Rich Schaefer helped with support of SunOS shared libraries.
|
|
|
|
Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about
|
|
several machine instruction sets.
|
|
|
|
Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped
|
|
develop remote debugging. Intel Corporation and Wind River Systems
|
|
contributed remote debugging modules for their products.
|
|
|
|
Brian Fox is the author of the readline libraries providing
|
|
command-line editing and command history.
|
|
|
|
@node New Features, Sample Session, Summary, Top
|
|
@unnumbered New Features since _GDBN__ version 3.5
|
|
|
|
@table @emph
|
|
@item Targets
|
|
Using the new command @code{target}, you can select at runtime whether
|
|
you are debugging local files, local processes, standalone systems over
|
|
a serial port, realtime systems over a TCP/IP connection, etc.
|
|
Internally, _GDBN__ now uses a function vector to mediate access to
|
|
different targets; if you need to add your own support for a remote
|
|
protocol, this makes it much easier.
|
|
|
|
@item Watchpoints
|
|
_GDBN__ now sports watchpoints as well as breakpoints. You can use a
|
|
watchpoint to stop execution whenever the value of an expression
|
|
changes, without having to predict a particular place in your program
|
|
where this may happen.
|
|
|
|
@item Object Code Formats
|
|
_GDBN__ uses a new scheme called Binary File Descriptors (BFD) to permit
|
|
it to switch dynamically, without reconfiguration or recompilation,
|
|
between different object-file formats. Formats currently supported are
|
|
COFF, a.out, and the Intel 960 b.out; files may be read as .o's, archive
|
|
libraries, or core dumps. BFD is available as a subroutine library so
|
|
that other programs may take advantage of it, and the other GNU binary
|
|
utilities are being converted to use it.
|
|
|
|
@item Configuration
|
|
Compile-time configuration (to select a particular architecture and
|
|
operating system) is much easier. The script @code{config.gdb} now
|
|
handles specification of separate host and target configurations.
|
|
|
|
@item Interaction
|
|
The user interface to _GDBN__'s control variables has been simplified
|
|
and consolidated in two commands, @code{set} and @code{show}. Output
|
|
lines are now broken at readable places, rather than overflowing onto
|
|
the next line. You can suppress output of machine-level addresses,
|
|
displaying only source language information.
|
|
|
|
|
|
@item Source Language
|
|
_GDBN__ now has limited support for C++ exception handling: _GDBN__ can
|
|
break when an exception is raised, before the stack is peeled back to
|
|
the exception handler's context.
|
|
|
|
@item Command Rationalization
|
|
Many _GDBN__ commands have been renamed to make them easier to remember
|
|
and use. In particular, the subcommands of @code{info} and
|
|
@code{show}/@code{set} are grouped to make the former refer to the state
|
|
of your program, and the latter refer to the state of _GDBN__ itself.
|
|
@xref{Renamed Commands}, for details on what commands were renamed.
|
|
|
|
@item Ports
|
|
_GDBN__ has been ported to the following new architectures: AT&T 3b1,
|
|
Acorn RISC machine, HP300 running HPUX, big- and little-endian MIPS
|
|
machines, Motorola 88k, Sun 386i, and Sun 3 running SunOS 4. In
|
|
addition, the following are supported as targets only: AMD 29k, Intel
|
|
960, and Wind River's VxWorks.
|
|
|
|
@item Shared Libraries
|
|
_GDBN__ 4.0 supports SunOS shared libraries.
|
|
|
|
@item Work in Progress
|
|
Kernel debugging for BSD and Mach systems; Tahoe and HPPA architecture
|
|
support.
|
|
|
|
@end table
|
|
|