binutils-gdb/gdb/doc/gdb.top-m4

_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