gdb/doc/gdb.top-m4

   1 _dnl__                                                          -*- Texinfo -*-
   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.
   4 @c M4 FRAGMENT: $Id$
   5 @c
   6 @syncodeindex ky cp
   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)
  10 @ifinfo
  11 This file documents the GNU debugger _GDBN__.
  12
  13 Copyright (C) 1988, 1989, 1990, 1991 Free Software Foundation, Inc.
  14
  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.
  18
  19 @ignore
  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).
  24
  25 @end ignore
  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
  31 one.
  32
  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.
  38 @end ifinfo
  39 @smallbook
  40 @setchapternewpage odd
  41 _if__(_GENERIC__)
  42 @settitle Using _GDBN__ (v4.0)
  43 _fi__(_GENERIC__)
  44 _if__(!_GENERIC__)
  45 @settitle Using _GDBN__ v4.0 (_HOST__)
  46 _fi__(!_GENERIC__)
  47 @iftex
  48 @finalout
  49 @end iftex
  50 @titlepage
  51 @title{Using _GDBN__}
  52 @subtitle{A Guide to the GNU Source-Level Debugger}
  53 _if__(!_GENERIC__)
  54 @subtitle{On _HOST__ Systems}
  55 _fi__(!_GENERIC__)
  56 @sp 1
  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
  60 @subtitle May 1991
  61 @author{Richard M. Stallman@qquad @hfill Free Software Foundation}
  62 @author{Roland H. Pesch@qquad @hfill Cygnus Support}
  63 @page
  64 @tex
  65 {\parskip=0pt
  66 \hfill rms\@ai.mit.edu, pesch\@cygnus.com\par
  67 \hfill {\it Using _GDBN__}, \manvers\par
  68 \hfill \TeX{}info \texinfoversion\par
  69 }
  70 @end tex
  71
  72 @vskip 0pt plus 1filll
  73 Copyright @copyright{} 1988, 1989, 1990, 1991 Free Software Foundation, Inc.
  74
  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.
  78
  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
  84 one.
  85
  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.
  91 @end titlepage
  92 @page
  93
  94 @node Top, Summary, (dir), (dir)
  95 @ifinfo
  96 This file describes version 4.0 of GDB, the GNU symbolic debugger.
  97 @end ifinfo
  98
  99 @menu
 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__
 104 * Commands::
 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
 112 * _GDBN__ Files::
 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__
 118 * Renamed Commands::
 119 * Installing _GDBN__::          Installing _GDBN__
 120 * Copying::                     GNU GENERAL PUBLIC LICENSE
 121 * Index::                       Index
 122  --- The Detailed Node Listing ---
 123
 124 Summary of _GDBN__
 125
 126 * Free Software::               Free Software
 127 * Contributors::                Contributors to _GDBN__
 128
 129 Getting In and Out of _GDBN__
 130
 131 * Starting _GDBN__::            Starting _GDBN__
 132 * Leaving _GDBN__::                     Leaving _GDBN__
 133 * Shell Commands::              Shell Commands
 134
 135 Starting _GDBN__
 136
 137 * File Options::                Choosing Files
 138 * Mode Options::                Choosing Modes
 139
 140 _GDBN__ Commands
 141
 142 * Command Syntax::              Command Syntax
 143 * Help::                        Getting Help
 144
 145 Running Programs Under _GDBN__
 146
 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
 155
 156 Stopping and Continuing
 157
 158 * Breakpoints::                 Breakpoints, Watchpoints, and Exceptions
 159 * Stepping::                    Stepping
 160 * Continuing::                  Continuing
 161 * Signals::                     Signals
 162
 163 Breakpoints, Watchpoints, and Exceptions
 164
 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::
 174
 175 Examining the Stack
 176
 177 * Frames::                      Stack Frames
 178 * Backtrace::                   Backtraces
 179 * Selection::                   Selecting a Frame
 180 * Frame Info::                  Information on a Frame
 181
 182 Examining Source Files
 183
 184 * List::                        Printing Source Lines
 185 * Search::                      Searching Source Files
 186 * Source Path::                 Specifying Source Directories
 187 * Machine Code::                Source and Machine Code
 188
 189 Examining Data
 190
 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
 202
 203 Altering Execution
 204
 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
 210
 211 _GDBN__'s Files
 212
 213 * Files::                       Commands to Specify Files
 214 * Symbol Errors::               Errors Reading Symbol Files
 215
 216 Specifying a Debugging Target
 217
 218 * Active Targets::              Active Targets
 219 * Target Commands::             Commands for Managing Targets
 220 * Remote::                      Remote Debugging
 221
 222 Remote Debugging
 223
 224 * i960-Nindy Remote::
 225 * EB29K Remote::
 226 * VxWorks Remote::
 227
 228 _GDBN__ with a Remote i960 (Nindy)
 229
 230 * Nindy Startup::               Startup with Nindy
 231 * Nindy Options::               Options for Nindy
 232 * Nindy reset::                 Nindy Reset Command
 233
 234 _GDBN__ with a Remote EB29K
 235
 236 * Comms (EB29K)::               Communications Setup
 237 * gdb-EB29K::                   EB29K cross-debugging
 238 * Remote Log::                  Remote Log
 239
 240 _GDBN__ and VxWorks
 241
 242 * VxWorks connection::          Connecting to VxWorks
 243 * VxWorks download::            VxWorks Download
 244 * VxWorks attach::              Running Tasks
 245
 246 Controlling _GDBN__
 247
 248 * Prompt::                      Prompt
 249 * Editing::                     Command Editing
 250 * History::                     Command History
 251 * Screen Size::                 Screen Size
 252 * Numbers::                     Numbers
 253 * Messages/Warnings::           Optional Warnings and Messages
 254
 255 Canned Sequences of Commands
 256
 257 * Define::                      User-Defined Commands
 258 * Command Files::               Command Files
 259 * Output::                      Commands for Controlled Output
 260
 261 Reporting Bugs in _GDBN__
 262
 263 * Bug Criteria::                Have You Found a Bug?
 264 * Bug Reporting::               How to Report Bugs
 265 @end menu
 266
 267 @node Summary, New Features, Top, Top
 268 @unnumbered Summary of _GDBN__
 269
 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.
 273
 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:
 276
 277 @itemize @bullet
 278 @item
 279 Start your program, specifying anything that might affect its behavior.
 280
 281 @item
 282 Make your program stop on specified conditions.
 283
 284 @item
 285 Examine what has happened, when your program has stopped.
 286
 287 @item
 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.
 290 @end itemize
 291
 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.
 295
 296 @menu
 297 * Free Software::               Free Software
 298 * Contributors::                Contributors to GDB
 299 @end menu
 300
 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.
 310
 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
 313 from anyone else.
 314
 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
 319
 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
 326 account.
 327
 328 Changes much prior to version 2.0 are lost in the mists of time.
 329
 330 @quotation
 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!
 334 @end quotation
 335
 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.
 342
 343 Richard Stallman, assisted at various times by Pete TerMaat, Chris
 344 Hanson, and Richard Mlynarik, handled releases through 2.8.
 345
 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).
 350
 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.
 354
 355 David Johnson wrote the original COFF support; Pace Willison did
 356 the original support for encapsulated COFF.
 357
 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
 370 support.
 371
 372 Rich Schaefer helped with support of SunOS shared libraries.
 373
 374 Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about
 375 several machine instruction sets.
 376
 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.
 380
 381 Brian Fox is the author of the readline libraries providing
 382 command-line editing and command history.
 383
 384 @node New Features, Sample Session, Summary, Top
 385 @unnumbered New Features since _GDBN__ version 3.5
 386
 387 @table @emph
 388 @item Targets
 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.
 395
 396 @item Watchpoints
 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.
 401
 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.
 410
 411 @item Configuration
 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.
 415
 416 @item Interaction
 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.
 422
 423
 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.
 428
 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.
 435
 436 @item Ports
 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.
 442
 443 @item Shared Libraries
 444 _GDBN__ 4.0 supports SunOS shared libraries.
 445
 446 @item Work in Progress
 447 Kernel debugging for BSD and Mach systems; Tahoe and HPPA architecture
 448 support.
 449
 450 @end table
 451