2 _dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
3 _dnl__ This file is part of the source for the GDB manual.
7 @c FOR UPDATES LEADING TO THIS DRAFT, GDB CHANGELOG CONSULTED BETWEEN:
8 @c Sun May 19 05:36:59 1991 John Gilmore (gnu at cygint.cygnus.com)
9 @c Sat Dec 22 02:51:40 1990 John Gilmore (gnu at cygint)
11 This file documents the GNU debugger _GDBN__.
13 Copyright (C) 1988, 1989, 1990, 1991 Free Software Foundation, Inc.
15 Permission is granted to make and distribute verbatim copies of
16 this manual provided the copyright notice and this permission notice
17 are preserved on all copies.
20 Permission is granted to process this file through TeX and print the
21 results, provided the printed document carries copying permission
22 notice identical to this one except for the removal of this paragraph
23 (this paragraph not being relevant to the printed manual).
26 Permission is granted to copy and distribute modified versions of this
27 manual under the conditions for verbatim copying, provided also that the
28 section entitled ``GNU General Public License'' is included exactly as
29 in the original, and provided that the entire resulting derived work is
30 distributed under the terms of a permission notice identical to this
33 Permission is granted to copy and distribute translations of this manual
34 into another language, under the above conditions for modified versions,
35 except that the section entitled ``GNU General Public License'' may be
36 included in a translation approved by the Free Software Foundation
37 instead of in the original English.
40 @setchapternewpage odd
42 @settitle Using _GDBN__ (v4.0)
45 @settitle Using _GDBN__ v4.0 (_HOST__)
52 @subtitle{A Guide to the GNU Source-Level Debugger}
54 @subtitle{On _HOST__ Systems}
57 @c Maybe crank this up to "Fourth Edition" when released at FSF
58 @c @subtitle Third Edition---_GDBN__ version 4.0
59 @subtitle _GDBN__ version 4.0
61 @author{Richard M. Stallman@qquad @hfill Free Software Foundation}
62 @author{Roland H. Pesch@qquad @hfill Cygnus Support}
66 \hfill rms\@ai.mit.edu, pesch\@cygnus.com\par
67 \hfill {\it Using _GDBN__}, \manvers\par
68 \hfill \TeX{}info \texinfoversion\par
72 @vskip 0pt plus 1filll
73 Copyright @copyright{} 1988, 1989, 1990, 1991 Free Software Foundation, Inc.
75 Permission is granted to make and distribute verbatim copies of
76 this manual provided the copyright notice and this permission notice
77 are preserved on all copies.
79 Permission is granted to copy and distribute modified versions of this
80 manual under the conditions for verbatim copying, provided also that the
81 section entitled ``GNU General Public License'' is included exactly as
82 in the original, and provided that the entire resulting derived work is
83 distributed under the terms of a permission notice identical to this
86 Permission is granted to copy and distribute translations of this manual
87 into another language, under the above conditions for modified versions,
88 except that the section entitled ``GNU General Public License'' may be
89 included in a translation approved by the Free Software Foundation
90 instead of in the original English.
94 @node Top, Summary, (dir), (dir)
96 This file describes version 4.0 of GDB, the GNU symbolic debugger.
100 * Summary:: Summary of _GDBN__
101 * New Features:: New Features in _GDBN__ version 4.0
102 * Sample Session:: A Sample _GDBN__ Session
103 * Invocation:: Getting In and Out of _GDBN__
105 * Running:: Running Programs Under _GDBN__
106 * Stopping:: Stopping and Continuing
107 * Stack:: Examining the Stack
108 * Source:: Examining Source Files
109 * Data:: Examining Data
110 * Symbols:: Examining the Symbol Table
111 * Altering:: Altering Execution
113 * Targets:: Specifying a Debugging Target
114 * Controlling _GDBN__:: Controlling _GDBN__
115 * Sequences:: Canned Sequences of Commands
116 * Emacs:: Using _GDBN__ under GNU Emacs
117 * _GDBN__ Bugs:: Reporting Bugs in _GDBN__
119 * Installing _GDBN__:: Installing _GDBN__
120 * Copying:: GNU GENERAL PUBLIC LICENSE
122 --- The Detailed Node Listing ---
126 * Free Software:: Free Software
127 * Contributors:: Contributors to _GDBN__
129 Getting In and Out of _GDBN__
131 * Starting _GDBN__:: Starting _GDBN__
132 * Leaving _GDBN__:: Leaving _GDBN__
133 * Shell Commands:: Shell Commands
137 * File Options:: Choosing Files
138 * Mode Options:: Choosing Modes
142 * Command Syntax:: Command Syntax
143 * Help:: Getting Help
145 Running Programs Under _GDBN__
147 * Compilation:: Compiling for Debugging
148 * Starting:: Starting your Program
149 * Arguments:: Your Program's Arguments
150 * Environment:: Your Program's Environment
151 * Working Directory:: Your Program's Working Directory
152 * Input/Output:: Your Program's Input and Output
153 * Attach:: Debugging an Already-Running Process
154 * Kill Process:: Killing the Child Process
156 Stopping and Continuing
158 * Breakpoints:: Breakpoints, Watchpoints, and Exceptions
159 * Stepping:: Stepping
160 * Continuing:: Continuing
163 Breakpoints, Watchpoints, and Exceptions
165 * Set Breaks:: Setting Breakpoints
166 * Set Watchpoints:: Setting Watchpoints
167 * Exception Handling:: Breakpoints and Exceptions
168 * Delete Breaks:: Deleting Breakpoints
169 * Disabling:: Disabling Breakpoints
170 * Conditions:: Break Conditions
171 * Break Commands:: Breakpoint Command Lists
172 * Breakpoint Menus:: Breakpoint Menus
173 * Error in Breakpoints::
177 * Frames:: Stack Frames
178 * Backtrace:: Backtraces
179 * Selection:: Selecting a Frame
180 * Frame Info:: Information on a Frame
182 Examining Source Files
184 * List:: Printing Source Lines
185 * Search:: Searching Source Files
186 * Source Path:: Specifying Source Directories
187 * Machine Code:: Source and Machine Code
191 * Expressions:: Expressions
192 * Variables:: Program Variables
193 * Arrays:: Artificial Arrays
194 * Output formats:: Output formats
195 * Memory:: Examining Memory
196 * Auto Display:: Automatic Display
197 * Print Settings:: Print Settings
198 * Value History:: Value History
199 * Convenience Vars:: Convenience Variables
200 * Registers:: Registers
201 * Floating Point Hardware:: Floating Point Hardware
205 * Assignment:: Assignment to Variables
206 * Jumping:: Continuing at a Different Address
207 * Signaling:: Giving the Program a Signal
208 * Returning:: Returning from a Function
209 * Calling:: Calling your Program's Functions
213 * Files:: Commands to Specify Files
214 * Symbol Errors:: Errors Reading Symbol Files
216 Specifying a Debugging Target
218 * Active Targets:: Active Targets
219 * Target Commands:: Commands for Managing Targets
220 * Remote:: Remote Debugging
224 * i960-Nindy Remote::
228 _GDBN__ with a Remote i960 (Nindy)
230 * Nindy Startup:: Startup with Nindy
231 * Nindy Options:: Options for Nindy
232 * Nindy reset:: Nindy Reset Command
234 _GDBN__ with a Remote EB29K
236 * Comms (EB29K):: Communications Setup
237 * gdb-EB29K:: EB29K cross-debugging
238 * Remote Log:: Remote Log
242 * VxWorks connection:: Connecting to VxWorks
243 * VxWorks download:: VxWorks Download
244 * VxWorks attach:: Running Tasks
249 * Editing:: Command Editing
250 * History:: Command History
251 * Screen Size:: Screen Size
253 * Messages/Warnings:: Optional Warnings and Messages
255 Canned Sequences of Commands
257 * Define:: User-Defined Commands
258 * Command Files:: Command Files
259 * Output:: Commands for Controlled Output
261 Reporting Bugs in _GDBN__
263 * Bug Criteria:: Have You Found a Bug?
264 * Bug Reporting:: How to Report Bugs
267 @node Summary, New Features, Top, Top
268 @unnumbered Summary of _GDBN__
270 The purpose of a debugger such as _GDBN__ is to allow you to see what is
271 going on ``inside'' another program while it executes---or what another
272 program was doing at the moment it crashed.
274 _GDBN__ can do four main kinds of things (plus other things in support of
275 these) to help you catch bugs in the act:
279 Start your program, specifying anything that might affect its behavior.
282 Make your program stop on specified conditions.
285 Examine what has happened, when your program has stopped.
288 Change things in your program, so you can experiment with correcting the
289 effects of one bug and go on to learn about another.
292 _GDBN__ can be used to debug programs written in C and C++. Pascal support
293 is being implemented, and Fortran support will be added when a GNU
294 Fortran compiler is ready.
297 * Free Software:: Free Software
298 * Contributors:: Contributors to GDB
301 @node Free Software, Contributors, Summary, Summary
302 @unnumberedsec Free Software
303 _GDBN__ is @dfn{free software}, protected by the GNU General Public License (GPL).
304 The GPL gives you the freedom to copy or adapt a licensed
305 program---but every person getting a copy also gets with it the
306 freedom to modify that copy (which means that they must get access to
307 the source code), and the freedom to distribute further copies.
308 Typical software companies use copyrights to limit your freedoms; the
309 Free Software Foundation uses the GPL to preserve these freedoms.
311 Fundamentally, the General Public License is a license which says that
312 you have these freedoms and that you can't take these freedoms away
315 @c FIXME: (passim) go through all xrefs, expanding to use text headings
316 For full details, @pxref{Copying}.
317 @node Contributors, , Free Software, Summary
318 @unnumberedsec Contributors to GDB
320 Richard Stallman was the original author of GDB, as with many GNU
321 programs. Many others have contributed to its development. This
322 section attempts to credit major contributors. One of the virtues of
323 free software is that everyone is free to contribute to it; with
324 regret, we cannot actually acknowledge everyone here. The file
325 @file{ChangeLog} in the GDB distribution approximates a blow-by-blow
328 Changes much prior to version 2.0 are lost in the mists of time.
331 @emph{Plea:} Additions to this section are particularly welcome. If you
332 or your friends (or enemies; let's be evenhanded) have been unfairly
333 omitted from this list, we would like to add your names!
336 So that they may not regard their long labor as thankless, we
337 particularly thank those who shepherded GDB through major releases:
338 John Gilmore (release 4.0); Jim Kingdon (releases 3.9, 3.5, 3.4, 3.3);
339 and Randy Smith (releases 3.2, 3.1, 3.0). As major maintainer of GDB
340 for some period, each contributed significantly to the structure,
341 stability, and capabilities of the entire debugger.
343 Richard Stallman, assisted at various times by Pete TerMaat, Chris
344 Hanson, and Richard Mlynarik, handled releases through 2.8.
346 Michael Tiemann is the author of most of the GNU C++ support in GDB,
347 with significant additional contributions from Per Bothner. James
348 Clark wrote the GNU C++ demangler. Early work on C++ was by Peter
349 TerMaat (who also did much general update work leading to release 3.0).
351 GDB 4.0 uses the BFD subroutine library to examine multiple
352 object-file formats; BFD was a joint project of V. Gumby
353 Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
355 David Johnson wrote the original COFF support; Pace Willison did
356 the original support for encapsulated COFF.
358 Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
359 Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
360 support. Jean-Daniel Fekete contributed Sun 386i support. Chris
361 Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki
362 Hasei contributed Sony/News OS 3 support. David Johnson contributed
363 Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support.
364 Keith Packard contributed NS32K support. Doug Rabson contributed
365 Acorn Risc Machine support. Chris Smith contributed Convex support
366 (and Fortran debugging). Jonathan Stone contributed Pyramid support.
367 Michael Tiemann contributed SPARC support. Tim Tucker contributed
368 support for the Gould NP1 and Gould Powernode. Pace Willison
369 contributed Intel 386 support. Jay Vosburgh contributed Symmetry
372 Rich Schaefer helped with support of SunOS shared libraries.
374 Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about
375 several machine instruction sets.
377 Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped
378 develop remote debugging. Intel Corporation and Wind River Systems
379 contributed remote debugging modules for their products.
381 Brian Fox is the author of the readline libraries providing
382 command-line editing and command history.
384 @node New Features, Sample Session, Summary, Top
385 @unnumbered New Features since _GDBN__ version 3.5
389 Using the new command @code{target}, you can select at runtime whether
390 you are debugging local files, local processes, standalone systems over
391 a serial port, realtime systems over a TCP/IP connection, etc.
392 Internally, _GDBN__ now uses a function vector to mediate access to
393 different targets; if you need to add your own support for a remote
394 protocol, this makes it much easier.
397 _GDBN__ now sports watchpoints as well as breakpoints. You can use a
398 watchpoint to stop execution whenever the value of an expression
399 changes, without having to predict a particular place in your program
400 where this may happen.
402 @item Object Code Formats
403 _GDBN__ uses a new scheme called Binary File Descriptors (BFD) to permit
404 it to switch dynamically, without reconfiguration or recompilation,
405 between different object-file formats. Formats currently supported are
406 COFF, a.out, and the Intel 960 b.out; files may be read as .o's, archive
407 libraries, or core dumps. BFD is available as a subroutine library so
408 that other programs may take advantage of it, and the other GNU binary
409 utilities are being converted to use it.
412 Compile-time configuration (to select a particular architecture and
413 operating system) is much easier. The script @code{config.gdb} now
414 handles specification of separate host and target configurations.
417 The user interface to _GDBN__'s control variables has been simplified
418 and consolidated in two commands, @code{set} and @code{show}. Output
419 lines are now broken at readable places, rather than overflowing onto
420 the next line. You can suppress output of machine-level addresses,
421 displaying only source language information.
424 @item Source Language
425 _GDBN__ now has limited support for C++ exception handling: _GDBN__ can
426 break when an exception is raised, before the stack is peeled back to
427 the exception handler's context.
429 @item Command Rationalization
430 Many _GDBN__ commands have been renamed to make them easier to remember
431 and use. In particular, the subcommands of @code{info} and
432 @code{show}/@code{set} are grouped to make the former refer to the state
433 of your program, and the latter refer to the state of _GDBN__ itself.
434 @xref{Renamed Commands}, for details on what commands were renamed.
437 _GDBN__ has been ported to the following new architectures: AT&T 3b1,
438 Acorn RISC machine, HP300 running HPUX, big- and little-endian MIPS
439 machines, Motorola 88k, Sun 386i, and Sun 3 running SunOS 4. In
440 addition, the following are supported as targets only: AMD 29k, Intel
441 960, and Wind River's VxWorks.
443 @item Shared Libraries
444 _GDBN__ 4.0 supports SunOS shared libraries.
446 @item Work in Progress
447 Kernel debugging for BSD and Mach systems; Tahoe and HPPA architecture