_dnl__ -*-Texinfo-*-
-_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
+_dnl__ Copyright (c) 1988 1989 1990 1991 1992 Free Software Foundation, Inc.
_dnl__ $Id$
\input texinfo @c -*-texinfo-*-
-@c Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
+@c Copyright (c) 1988 1989 1990 1991 1992 Free Software Foundation, Inc.
@c %**start of header
@setfilename _GDBP__.info
_if__(_GENERIC__)
-@settitle Using _GDBN__ (<v>_GDB_VN__)
+@settitle _GDBN__, The GNU Debugger
_fi__(_GENERIC__)
_if__(!_GENERIC__)
-@settitle Using _GDBN__ <v>_GDB_VN__ (_HOST__)
+@settitle _GDB__, The GNU Debugger (_HOST__)
_fi__(!_GENERIC__)
@setchapternewpage odd
@c @smallbook
\xdef\manvers{\$Revision$} % For use in headers, footers too
@end tex
-@c FOR UPDATES LEADING TO THIS DRAFT, GDB CHANGELOG CONSULTED BETWEEN:
+@c GDB CHANGELOG CONSULTED BETWEEN:
@c Fri Oct 11 23:27:06 1991 John Gilmore (gnu at cygnus.com)
@c Sat Dec 22 02:51:40 1990 John Gilmore (gnu at cygint)
_0__
m4 pretex.m4 none.m4 all.m4 gdb.texinfo >gdb-all.texinfo
will produce (assuming your path finds either GNU m4 >= 0.84, or SysV
-m4; Berkeley won't do) a file suitable for formatting. See the text in
+m4; Berkeley will not do) a file suitable for formatting. See the text in
"pretex.m4" for a fuller explanation (and the macro definitions).
_1__
This file documents the GNU debugger _GDBN__.
@c !!set edition, date, version
-This is Edition 4.00, December 1991,
+This is Edition 4.05, June 1992,
of @cite{Using GDB: A Guide to the GNU Source-Level Debugger}
for GDB Version _GDB_VN__.
-Copyright (C) 1988, 1989, 1990, 1991 Free Software Foundation, Inc.
+Copyright (C) 1988, 1989, 1990, 1991, 1992 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
included in a translation approved by the Free Software Foundation
instead of in the original English.
@end ifinfo
+
@titlepage
@title Using _GDBN__
-@subtitle A Guide to the GNU Source-Level Debugger
+@subtitle The GNU Source-Level Debugger
_if__(!_GENERIC__)
-@subtitle On _HOST__ Systems
+@subtitle on _HOST__ Systems
_fi__(!_GENERIC__)
@sp 1
@c !!set edition, date, version
-@subtitle Edition 4.00, for _GDBN__ version _GDB_VN__
-@subtitle December 1991
+@subtitle Edition 4.05, for _GDBN__ version _GDB_VN__
+@subtitle June 1992
@author by Richard M. Stallman and Roland H. Pesch
@page
@tex
{\parskip=0pt
-\hfill rms\@ai.mit.edu, pesch\@cygnus.com\par
+\hfill 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.
+Copyright @copyright{} 1988, 1989, 1990, 1991, 1992 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
This file describes _GDBN__, the GNU symbolic debugger.
@c !!set edition, date, version
-This is Edition 4.00, December 1991, for GDB Version _GDB_VN__.
+This is Edition 4.05, June 1992, for GDB Version _GDB_VN__.
@end ifinfo
@menu
* Summary:: Summary of _GDBN__
-* New Features:: New features since _GDBN__ version 3.5
+* New Features:: New features since GDB version 3.5
* Sample Session:: A sample _GDBN__ session
* Invocation:: Getting in and out of _GDBN__
* Commands:: _GDBN__ commands
* Emacs:: Using _GDBN__ under GNU Emacs
* _GDBN__ Bugs:: Reporting bugs in _GDBN__
* Renamed Commands::
-* Installing _GDBN__:: Installing _GDBN__
+* Formatting Documentation:: How to format and print GDB documentation
+* Installing GDB:: Installing GDB
* Copying:: GNU GENERAL PUBLIC LICENSE
* Index:: Index
Summary of _GDBN__
-* Free Software:: Free Software
+* Free Software:: Freely redistributable software
* Contributors:: Contributors to _GDBN__
Getting In and Out of _GDBN__
-* Invoking _GDBN__:: Starting _GDBN__
-* Leaving _GDBN__:: Leaving _GDBN__
-* Shell Commands:: Shell Commands
+* Invoking _GDBN__:: How to start _GDBN__
+* Leaving _GDBN__:: How to quit _GDBN__
+* Shell Commands:: How to use shell commands inside _GDBN__
Starting _GDBN__
_GDBN__ Commands
* Command Syntax:: Command Syntax
+* Completion:: Command Completion
* Help:: Getting Help
Running Programs Under _GDBN__
* 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
Stopping and Continuing
Installing GDB
-* Subdirectories:: Configuration subdirectories
+* Separate Objdir:: Compiling _GDBN__ in another directory
* Config Names:: Specifying names for hosts and targets
* configure Options:: Summary of options for configure
-* Formatting Documentation:: How to format and print GDB documentation
@end menu
@node Summary, New Features, Top, Top
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.@refill
+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:@refill
+these) to help you catch bugs in the act:
@itemize @bullet
@item
@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
+
+_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.
from anyone else.
For full details, @pxref{Copying, ,GNU GENERAL PUBLIC LICENSE}.
+
@node Contributors, , Free Software, Summary
@unnumberedsec Contributors to GDB
@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 (releases _GDB_VN__, 4.2, 4.1, 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.@refill
+particularly thank those who shepherded GDB through major releases: Stu
+Grossman and John Gilmore (releases 4.6, 4.5, 4.4), John Gilmore
+(releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim Kingdon (releases 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.
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 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.
+GDB 4 uses the BFD subroutine library to examine multiple
+object-file formats; BFD was a joint project of David V.
+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.
+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.
+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 and Peter Schauer 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.
+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.
+Brian Fox is the author of the readline libraries providing
+command-line editing and command history.
-Andrew Beers of SUNY Buffalo wrote the language-switching code and the
-Modula-2 support, and contributed the Languages chapter of this manual.
+Andrew Beers of SUNY Buffalo wrote the language-switching code and
+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.
@node New Features, Sample Session, Summary, Top
-@unnumbered New Features since _GDBN__ version 3.5
+@unnumbered New Features since GDB version 3.5
@table @emph
@item Targets
a serial port, realtime systems over a TCP/IP connection, etc. The
command @code{load} can download programs into a remote system. Serial
stubs are available for Motorola 680x0 and Intel 80386 remote systems;
-_GDBN__ also supports debugging realtime processes running under
+GDB also supports debugging realtime processes running under
VxWorks, using SunRPC Remote Procedure Calls over TCP/IP to talk to a
-debugger stub on the target system. Internally, _GDBN__ now uses a
+debugger stub on the target system. Internally, GDB 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
+GDB 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.
to make the output more readable.
@item Object Code Formats
-_GDBN__ uses a new library called the Binary File Descriptor (BFD)
+GDB uses a new library called the Binary File Descriptor (BFD)
Library 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
@item Configuration and Ports
Compile-time configuration (to select a particular architecture and
operating system) is much easier. The script @code{configure} now
-allows you to configure _GDBN__ as either a native debugger or a
-cross-debugger. @xref{Installing _GDBN__}, for details on how to
-configure and on what architectures are now available.
+allows you to configure GDB as either a native debugger or a
+cross-debugger. @xref{Installing GDB}, for details on how to
+configure.
@item Interaction
-The user interface to _GDBN__'s control variables has been simplified
+The user interface to GDB'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 C++
-_GDBN__ now supports C++ multiple inheritance (if used with a GCC
+GDB now supports C++ multiple inheritance (if used with a GCC
version 2 compiler), and also has limited support for C++ exception
-handling, with the commands @code{catch} and @code{info catch}: _GDBN__
+handling, with the commands @code{catch} and @code{info catch}: GDB
can break when an exception is raised, before the stack is peeled back
to the exception handler's context.
@item Modula-2
-_GDBN__ now has preliminary support for the GNU Modula-2 compiler,
+GDB now has preliminary support for the GNU Modula-2 compiler,
currently under development at the State University of New York at
-Buffalo. Coordinated development of both _GDBN__ and the GNU Modula-2
-compiler will continue through the fall of 1991 and into 1992. Other
-Modula-2 compilers are currently not supported, and attempting to debug
-programs compiled with them will likely result in an error as the symbol
-table of the executable is read in.
+Buffalo. Coordinated development of both GDB and the GNU Modula-2
+compiler will continue into 1992. Other Modula-2 compilers are
+currently not supported, and attempting to debug programs compiled with
+them will likely result in an error as the symbol table of the
+executable is read in.
@item Command Rationalization
-Many _GDBN__ commands have been renamed to make them easier to remember
+Many GDB 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.
+of your program, and the latter refer to the state of GDB itself.
@xref{Renamed Commands}, for details on what commands were renamed.
@item Shared Libraries
-_GDBN__ 4 can debug programs and core files that use SunOS shared
-libraries.
+GDB 4 can debug programs and core files that use SunOS, SVR4, or IBM RS/6000
+shared libraries.
@item Reference Card
-_GDBN__ 4 has a reference card; @xref{Formatting Documentation} for
-instructions on printing it.
+GDB 4 has a reference card. @xref{Formatting Documentation,,Formatting
+the Documentation}, for instructions to print it.
@item Work in Progress
Kernel debugging for BSD and Mach systems; Tahoe and HPPA architecture
support.
-
@end table
@node Sample Session, Invocation, New Features, Top
debugger. This chapter illustrates these commands.
@iftex
-In this sample session, we emphasize user input like this: @i{input},
+In this sample session, we emphasize user input like this: @b{input},
to make it easier to pick out from the surrounding output.
@end iftex
procedure fails to define a new synonym @code{baz}:
@smallexample
-$ @i{cd gnu/m4}
-$ @i{./m4}
-@i{define(foo,0000)}
+$ @b{cd gnu/m4}
+$ @b{./m4}
+@b{define(foo,0000)}
-@i{foo}
+@b{foo}
0000
-@i{define(bar,defn(`foo'))}
+@b{define(bar,defn(`foo'))}
-@i{bar}
+@b{bar}
0000
-@i{changequote(<QUOTE>,<UNQUOTE>)}
+@b{changequote(<QUOTE>,<UNQUOTE>)}
-@i{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
-@i{baz}
-@i{C-d}
+@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
+@b{baz}
+@b{C-d}
m4: End of input: 0: fatal error: EOF in string
@end smallexample
Let's use _GDBN__ to try to see what's going on.
@smallexample
-$ @i{_GDBP__ m4}
+$ @b{_GDBP__ m4}
@c FIXME: this falsifies the exact text played out, to permit smallbook
@c FIXME... format to come out better.
GDB is free software and you are welcome to distribute copies
the conditions.
There is absolutely no warranty for GDB; type "show warranty"
for details.
-GDB _GDB_VN__, Copyright 1991 Free Software Foundation, Inc...
+GDB _GDB_VN__, Copyright 1992 Free Software Foundation, Inc...
(_GDBP__)
@end smallexample
@noindent
-_GDBN__ reads only enough symbol data to know where to find the
-rest when needed; as a result, the first prompt comes up very
-quickly. We now tell _GDBN__ to use a narrower display width than
-usual, so that examples will fit in this manual.@refill
+_GDBN__ reads only enough symbol data to know where to find the rest when
+needed; as a result, the first prompt comes up very quickly. We now
+tell _GDBN__ to use a narrower display width than usual, so that examples
+will fit in this manual.
@smallexample
-(_GDBP__) @i{set width 70}
+(_GDBP__) @b{set width 70}
@end smallexample
@noindent
@code{break} command.
@smallexample
-(_GDBP__) @i{break m4_changequote}
+(_GDBP__) @b{break m4_changequote}
Breakpoint 1 at 0x62f4: file builtin.c, line 879.
@end smallexample
subroutine, the program runs as usual:
@smallexample
-(_GDBP__) @i{run}
+(_GDBP__) @b{run}
Starting program: /work/Editorial/gdb/gnu/m4/m4
-@i{define(foo,0000)}
+@b{define(foo,0000)}
-@i{foo}
+@b{foo}
0000
@end smallexample
context where it stops.
@smallexample
-@i{changequote(<QUOTE>,<UNQUOTE>)}
+@b{changequote(<QUOTE>,<UNQUOTE>)}
Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
at builtin.c:879
-879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3))
+879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
@end smallexample
@noindent
the next line of the current function.
@smallexample
-(_GDBP__) @i{n}
+(_GDBP__) @b{n}
882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
: nil,
@end smallexample
subroutine, so it steps into @code{set_quotes}.
@smallexample
-(_GDBP__) @i{s}
+(_GDBP__) @b{s}
set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
at input.c:530
530 if (lquote != def_lquote)
stack frame for each active subroutine.
@smallexample
-(_GDBP__) @i{bt}
+(_GDBP__) @b{bt}
#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
at input.c:530
#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
Let's step through a few more lines to see what happens. The first two
times, we can use @samp{s}; the next two times we use @code{n} to avoid
falling into the @code{xstrdup} subroutine.
+
@smallexample
-(_GDBP__) @i{s}
+(_GDBP__) @b{s}
0x3b5c 532 if (rquote != def_rquote)
-(_GDBP__) @i{s}
+(_GDBP__) @b{s}
0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
def_lquote : xstrdup(lq);
-(_GDBP__) @i{n}
+(_GDBP__) @b{n}
536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
: xstrdup(rq);
-(_GDBP__) @i{n}
+(_GDBP__) @b{n}
538 len_lquote = strlen(rquote);
@end smallexample
(@code{print}) to see their values.
@smallexample
-(_GDBP__) @i{p lquote}
+(_GDBP__) @b{p lquote}
$1 = 0x35d40 "<QUOTE>"
-(_GDBP__) @i{p rquote}
+(_GDBP__) @b{p rquote}
$2 = 0x35d50 "<UNQUOTE>"
@end smallexample
surrounding the current line, with the @code{l} (@code{list}) command.
@smallexample
-(_GDBP__) @i{l}
+(_GDBP__) @b{l}
533 xfree(rquote);
534
535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
@code{len_rquote}, and then examine the values of those variables.
@smallexample
-(_GDBP__) @i{n}
+(_GDBP__) @b{n}
539 len_rquote = strlen(lquote);
-(_GDBP__) @i{n}
+(_GDBP__) @b{n}
540 @}
-(_GDBP__) @i{p len_lquote}
+(_GDBP__) @b{p len_lquote}
$3 = 9
-(_GDBP__) @i{p len_rquote}
+(_GDBP__) @b{p len_rquote}
$4 = 7
@end smallexample
assignments.
@smallexample
-(_GDBP__) p len_lquote=strlen(lquote)
+(_GDBP__) @b{p len_lquote=strlen(lquote)}
$5 = 7
-(_GDBP__) p len_rquote=strlen(rquote)
+(_GDBP__) @b{p len_rquote=strlen(rquote)}
$6 = 9
@end smallexample
example that caused trouble initially:
@smallexample
-(_GDBP__) @i{c}
+(_GDBP__) @b{c}
Continuing.
-@i{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
+@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
baz
0000
lengths. We'll let @code{m4} exit by giving it an EOF as input.
@smallexample
-@i{C-d}
+@b{C-d}
Program exited normally.
@end smallexample
session with the _GDBN__ @code{quit} command.
@smallexample
-(_GDBP__) @i{quit}
+(_GDBP__) @b{quit}
_1__@end smallexample
@node Invocation, Commands, Sample Session, Top
@chapter Getting In and Out of _GDBN__
-Type @kbd{gdb} or @kbd{gdb @var{program} @var{core}} to start GDB
-and type @kbd{quit} or @kbd{C-d} to exit.
+This chapter discusses how to start _GDBN__, and how to get out of it.
+(The essentials: type @samp{_GDBP__} to start GDB, and type @kbd{quit}
+or @kbd{C-d} to exit.)
@menu
* Invoking _GDBN__:: Starting _GDBN__
@node Invoking _GDBN__, Leaving _GDBN__, Invocation, Invocation
@section Starting _GDBN__
-Invoke _GDBN__ with the shell command @code{_GDBP__}. Once started,
-it reads commands from the terminal until you tell it to exit.
+Start _GDBN__ with the shell command @code{_GDBP__}. Once it's running,
+_GDBN__ reads commands from the terminal until you tell it to exit.
+
+You can also run @code{_GDBP__} with a variety of arguments and options,
+to specify more of your debugging environment at the outset.
+
+The command-line options described here are designed
+to cover a variety of situations; in some environments, some of these
+options may effectively be unavailable.
+
+_if__(_H8__)
+For details on starting up _GDBP__ as a
+remote debugger attached to a Hitachi H8/300 board, see @ref{Hitachi
+H8/300 Remote,,_GDBN__ and the Hitachi H8/300}.
+_fi__(_H8__)
+
+The most usual way to start _GDBN__ is with one argument or two,
+specifying an executable program as the argument:
-You can run @code{_GDBP__} with no arguments or options; but the most
-usual way to start _GDBN__ is with one argument or two, specifying an
-executable program as the argument:
@example
_GDBP__ @var{program}
@end example
+
@noindent
You can also start with both an executable program and a core file
specified:
+
@example
_GDBP__ @var{program} @var{core}
@end example
You can, instead, specify a process ID as a second argument, if you want
to debug a running process:
+
@example
_GDBP__ @var{program} 1234
@end example
+
@noindent
would attach _GDBN__ to process @code{1234} (unless you also have a file
named @file{1234}; _GDBN__ does check for a core file first).
+Taking advantage of the second command-line argument requires a fairly
+complete operating system; when you use _GDBN__ as a remote debugger
+attached to a bare board, there may not be any notion of ``process'',
+and there is often no way to get a core dump.
+
@noindent
You can further control how _GDBN__ starts up by using command-line
options. _GDBN__ itself can remind you of the options available.
@item -directory=@var{directory}
@itemx -d @var{directory}
Add @var{directory} to the path to search for source files.
+
+@item -m
+@itemx -mapped
+@emph{Warning: this option depends on operating system facilities that are not
+supported on all systems.}@*
+If memory-mapped files are available on your system through the @code{mmap}
+system call, you can use this option
+to cause _GDBN__ to write the symbols from your
+program into a reusable file in the current directory. If the program you are debugging is
+called @file{/tmp/fred}, the mapped symbol file will be @file{./fred.syms}.
+Future _GDBN__ debugging sessions will notice the presence of this file,
+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 _GDBN__ is run.
+It holds an exact image of _GDBN__'s internal symbol table. It cannot be
+shared across multiple host platforms.
+
+@item -r
+@itemx -readnow
+Read each symbol file's entire symbol table immediately, rather than
+the default, which is to read it incrementally as it is needed.
+This makes startup slower, but makes future operations faster.
@end table
+The @code{-mapped} and @code{-readnow} options are typically combined in order to
+build a @file{.syms} file that contains complete symbol information.
+A simple GDB invocation to do nothing but build a @file{.syms} file for future
+use is:
+
+@example
+ gdb -batch -nx -mapped -readnow programname
+@end example
+
_if__(!_GENERIC__)
@node Mode Options, Mode Options, File Options, Invoking _GDBN__
_fi__(!_GENERIC__)
_if__(_GENERIC__)
@node Mode Options, , File Options, Invoking _GDBN__
_fi__(_GENERIC__)
+@subsection Choosing Modes
+
You can run _GDBN__ in various alternative modes---for example, in
batch mode or quiet mode.
-@subsection Choosing Modes
@table @code
@item -nx
Batch mode may be useful for running _GDBN__ as a filter, for example to
download and run a program on another computer; in order to make this
more useful, the message
+
@example
Program exited normally.
@end example
+
@noindent
(which is ordinarily issued whenever a program running under _GDBN__ control
terminates) is not issued when running in batch mode.
Run _GDBN__ using @var{directory} as its working directory,
instead of the current directory.
+_if__(_LUCID__)
+@item -context @var{authentication}
+When the Energize programming system starts up _GDBN__, it uses this
+option to trigger an alternate mode of interaction.
+@var{authentication} is a pair of numeric codes that identify _GDBN__
+as a client in the Energize environment. Avoid this option when you run
+_GDBN__ directly from the command line. See @ref{Energize,,Using
+_GDBN__ with Energize} for more discussion of using _GDBN__ with Energize.
+_fi__(_LUCID__)
+
@item -fullname
@itemx -f
Emacs sets this option when it runs _GDBN__ as a subprocess. It tells _GDBN__
_if__(!_GENERIC__)
_include__(gdbinv-s.m4)
_fi__(!_GENERIC__)
-
@node Leaving _GDBN__, Shell Commands, Invoking _GDBN__, Invocation
@section Leaving _GDBN__
@cindex exiting _GDBN__
+
@table @code
@item quit
@kindex quit
character at any time because _GDBN__ does not allow it to take effect
until a time when it is safe.
-If you've been using _GDBN__ to control an attached process or device,
-you can release it with the @code{detach} command; @pxref{Attach, ,Debugging an Already-Running Process}..
+If you have been using _GDBN__ to control an attached process or device, you
+can release it with the @code{detach} command; @pxref{Attach,
+,Debugging an Already-Running Process}..
@node Shell Commands, , Leaving _GDBN__, Invocation
@section Shell Commands
+
If you need to execute occasional shell commands during your
debugging session, there is no need to leave or suspend _GDBN__; you can
just use the @code{shell} command.
@node Commands, Running, Invocation, Top
@chapter _GDBN__ Commands
-You can abbreviate GDB command if that abbreviation is unambiguous;
-and you can repeat certain GDB commands by typing just @key{RET}.
+You can abbreviate a _GDBN__ command to the first few letters of the command
+name, if that abbreviation is unambiguous; and you can repeat certain
+_GDBN__ commands by typing just @key{RET}. You can also use the @key{TAB}
+key to get _GDBN__ to fill out the rest of a word in a command (or to
+show you the alternatives available, if there's more than one possibility).
@menu
* Command Syntax:: Command Syntax
+* Completion:: Command Completion
* Help:: Getting Help
@end menu
-@node Command Syntax, Help, Commands, Commands
+@node Command Syntax, Completion, Commands, Commands
@section Command Syntax
+
A _GDBN__ command is a single line of input. There is no limit on how long
it can be. It starts with a command name, which is followed by arguments
whose meaning depends on the command name. For example, the command
A line of input starting with @kbd{#} is a comment; it does nothing.
This is useful mainly in command files (@pxref{Command Files}).
-@node Help, , Command Syntax, Commands
+@node Completion, Help, Command Syntax, Commands
+@section Command Completion
+
+@cindex completion
+@cindex word completion
+_GDBN__ can fill in the rest of a word in a command for you, if there's
+only one possibility; it can also show you what the valid possibilities
+are for the next word in a command, at any time. This works for _GDBN__
+commands, _GDBN__ subcommands, and the names of symbols in your program.
+
+Press the @key{TAB} key whenever you want _GDBN__ to fill out the rest
+of a word. If there's only one possibility, _GDBN__ will fill in the
+word, and wait for you to finish the command (or press @key{RET} to
+enter it). For example, if you type
+
+@example
+(_GDBP__) info bre@key{TAB}
+@end example
+
+@noindent
+_GDBN__ fills in the rest of the word @samp{breakpoints}, since that's
+the only @code{info} subcommand beginning with @samp{bre}:
+
+@example
+(_GDBP__) info breakpoints
+@end example
+
+@noindent
+You can either press @key{RET} at this point, to run the @code{info
+breakpoints} command, or backspace and enter something else, if
+@samp{breakpoints} doesn't look like the command you expected. (If you
+were sure you wanted @code{info breakpoints} in the first place, you
+might as well just type @key{RET} immediately after @samp{info bre},
+to exploit command abbreviations rather than command completion).
+
+If there is more than one possibility for the next word when you press
+@key{TAB}, _GDBN__ will sound a bell. You can either supply more
+characters and try again, or just press @key{TAB} a second time, and
+_GDBN__ will display all the possible completions for that word. For
+example, you might want to set a breakpoint on a subroutine whose name
+begins with @samp{mak}, but when you type @kbd{b mak@key{TAB}} _GDBN__
+just sounds the bell. Typing @key{TAB} again will display all the
+function names in your program that begin with those characters, for
+example:
+
+@example
+(_GDBP__) b mak@key{TAB}
+make_a_section_from_file make_environ
+make_abs_section make_function_type
+make_blockvector make_pointer_type
+make_cleanup make_reference_type
+make_command make_symbol_completion_list
+(GDBP__) b mak
+@end example
+
+@noindent
+After displaying the available possibilities, _GDBN__ copies your
+partial input (@samp{b mak} in the example) so you can finish the
+command.
+
+If you just want to see the list of alternatives in the first place, you
+can press @kbd{M-?} rather than pressing @key{TAB} twice. (@kbd{M-?}
+means @kbd{@key{META} ?}. If your keyboard doesn't have a Meta shift,
+you can type @key{ESC} followed by @kbd{?} instead.)
+
+@cindex quotes in commands
+@cindex completion of quoted strings
+Sometimes the string you need, while logically a ``word'', may contain
+parentheses or other characters that _GDBN__ normally excludes from its
+notion of a word. To permit word completion to work in this situation,
+you may enclose words in @code{'} (single quote marks) in _GDBN__ commands.
+
+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
+type). For example, you may need to distinguish whether you mean
+@samp{name(int)} or @samp{name(float)} when you want to set a
+breakpoint. To use the word-completion facilities in this situation,
+type a single quote @code{'} at the beginning of the function name.
+This alerts _GDBN__ that it may need to consider more information than
+usual when you press @key{TAB} or @kbd{M-?} to request word completion:
+
+@example
+(_GDBP__) b 'name(@key{M-?}
+name(int) name(float)
+(_GDBP__) b 'name
+@end example
+
+@node Help, , Completion, Commands
@section Getting Help
@cindex online documentation
@kindex help
+
You can always ask _GDBN__ itself for information on its commands, using the
command @code{help}.
@kindex h
You can use @code{help} (abbreviated @code{h}) with no arguments to
display a short list of named classes of commands:
+
@smallexample
(_GDBP__) help
List of classes of commands:
Using one of the general help classes as an argument, you can get a
list of the individual commands in that class. For example, here is the
help display for the class @code{status}:
+
@smallexample
(_GDBP__) help status
Status inquiries.
This command (abbreviated @code{i}) is for describing the state of your
program; for example, it can list the arguments given to your program
(@code{info args}), the registers currently in use (@code{info
-registers}), or the breakpoints you've set (@code{info breakpoints}).
+registers}), or the breakpoints you have set (@code{info breakpoints}).
You can get a complete list of the @code{info} sub-commands with
@w{@code{help info}}.
@cindex version number
@item show version
Show what version of _GDBN__ is running. You should include this
-information in _GDBN__ bug-reports. If multiple versions of _GDBN__ are
-in use at your site, you may occasionally want to make sure what version
-of _GDBN__ you are running; as _GDBN__ evolves, new commands are
-introduced, and old ones may wither away. The version number is also
-announced when you start _GDBN__ with no arguments.
+information in _GDBN__ bug-reports. If multiple versions of _GDBN__ are in
+use at your site, you may occasionally want to make sure what version
+of _GDBN__ you are running; as _GDBN__ evolves, new commands are introduced,
+and old ones may wither away. The version number is also announced
+when you start _GDBN__ with no arguments.
@kindex show copying
@item show copying
@node Running, Stopping, Commands, Top
@chapter Running Programs Under _GDBN__
+To debug a program, you must run it under _GDBN__.
+
@menu
* Compilation:: Compiling for Debugging
* Starting:: Starting your Program
* 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
@end menu
@node Compilation, Starting, Running, Running
options together. Using those compilers, you cannot generate optimized
executables containing debugging information.
-The GNU C compiler supports @samp{-g} with or without @samp{-O}, making it
-possible to debug optimized code. We recommend that you @emph{always} use
-@samp{-g} whenever you compile a program. You may think your program is
-correct, but there is no sense in pushing your luck.
+_GCC__, the GNU C compiler, supports @samp{-g} with or without
+@samp{-O}, making it possible to debug optimized code. We recommend
+that you @emph{always} use @samp{-g} whenever you compile a program.
+You may think your program is correct, but there is no sense in pushing
+your luck.
+
+@cindex optimized code, debugging
+@cindex debugging optimized code
+When you debug a program compiled with @samp{-g -O}, remember that the
+optimizer is rearranging your code; the debugger will show you what's
+really there. Don't be too surprised when the execution path doesn't
+exactly match your source file! An extreme example: if you define a
+variable, but never use it, _GDBN__ will never see that
+variable---because the compiler optimizes it out of existence.
Some things do not work as well with @samp{-g -O} as with just
@samp{-g}, particularly on machines with instruction scheduling. If in
please report it as a bug (including a test case!).
Older versions of the GNU C compiler permitted a variant option
-@samp{-gg} for debugging information. _GDBN__ no longer supports this
+@w{@samp{-gg}} for debugging information. _GDBN__ no longer supports this
format; if your GNU C compiler has this option, do not use it.
@ignore
@section Starting your Program
@cindex starting
@cindex running
+
@table @code
@item run
@itemx r
@kindex run
-Use the @code{run} command to start your program under _GDBN__. You
-must first specify the program name
+Use the @code{run} command to start your program under _GDBN__. You must
+first specify the program name
_if__(_VXWORKS__)
(except on VxWorks)
_fi__(_VXWORKS__)
-with an argument to _GDBN__
-(@pxref{Invocation, ,Getting In and Out of _GDBN__}), or using the @code{file} or @code{exec-file}
-command (@pxref{Files, ,Commands to Specify Files}).
-@refill
+with an argument to
+_GDBN__ (@pxref{Invocation, ,Getting In and Out of _GDBN__}), or by using the
+@code{file} or @code{exec-file} command (@pxref{Files, ,Commands to
+Specify Files}).
+
@end table
If you are running your program in an execution environment that
The execution of a program is affected by certain information it
receives from its superior. _GDBN__ provides ways to specify this
-information, which you must do @i{before} starting your program. (You
+information, which you must do @emph{before} starting your program. (You
can change it after starting your program, but such changes will only affect
your program the next time you start it.) This information may be
divided into four categories:
@table @asis
-@item The @i{arguments.}
+@item The @emph{arguments.}
Specify the arguments to give your program as the arguments of the
-@code{run} command. If a shell is available on your target, the
-shell is used to pass the arguments, so that you may use normal
-conventions (such as wildcard expansion or variable substitution)
-in describing the arguments. In Unix systems, you can control
-which shell is used with the @code{SHELL} environment variable.
-@xref{Arguments, ,Your Program's Arguments}.@refill
-
-@item The @i{environment.}
+@code{run} command. If a shell is available on your target, the shell
+is used to pass the arguments, so that you may use normal conventions
+(such as wildcard expansion or variable substitution) in describing
+the arguments. In Unix systems, you can control which shell is used
+with the @code{SHELL} environment variable. @xref{Arguments, ,Your
+Program's Arguments}.
+
+@item The @emph{environment.}
Your program normally inherits its environment from _GDBN__, but you can
use the _GDBN__ commands @code{set environment} and @code{unset
environment} to change parts of the environment that will be given to
-your program. @xref{Environment, ,Your Program's Environment}.@refill
+your program. @xref{Environment, ,Your Program's Environment}.
-@item The @i{working directory.}
+@item The @emph{working directory.}
Your program inherits its working directory from _GDBN__. You can set
_GDBN__'s working directory with the @code{cd} command in _GDBN__.
@xref{Working Directory, ,Your Program's Working Directory}.
-@item The @i{standard input and output.}
+@item The @emph{standard input and output.}
Your program normally uses the same device for standard input and
standard output as _GDBN__ is using. You can redirect input and output
in the @code{run} command line, or you can use the @code{tty} command to
set a different device for your program.
-@xref{Input/Output, Your Program's Input and Output}.
+@xref{Input/Output, ,Your Program's Input and Output}.
@cindex pipes
@emph{Warning:} While input and output redirection work, you cannot use
@end table
@c FIXME: Rewrite following paragraph, especially its third sentence.
-When you issue the @code{run} command, your program begins to
-execute immediately. @xref{Stopping, ,Stopping and Continuing}, for
+When you issue the @code{run} command, your program begins to execute
+immediately. @xref{Stopping, ,Stopping and Continuing}, for
discussion of how to arrange for your program to stop. Once your
program has been started by the @code{run} command (and then stopped),
-you may evaluate expressions that involve calls to functions in the
-inferior, using the @code{print} or @code{call} commands. @xref{Data,
-,Examining Data}.
+you may evaluate expressions that involve calls to functions in your
+program, using the @code{print} or @code{call} commands. @xref{Data,
+,Examining Data}.
If the modification time of your symbol file has changed since the
-last time _GDBN__ read its symbols, _GDBN__ will discard its symbol
-table and re-read it. When it does this, _GDBN__ tries to retain your
-current breakpoints.
+last time _GDBN__ read its symbols, _GDBN__ will discard its symbol table and
+re-read it. When it does this, _GDBN__ tries to retain your current
+breakpoints.
@node Arguments, Environment, Starting, Running
@section Your Program's Arguments
directory in _GDBN__ with the @code{cd} command.
The _GDBN__ working directory also serves as a default for the commands
-that specify files for _GDBN__ to operate on. @xref{Files, ,Commands to Specify Files}.
+that specify files for _GDBN__ to operate on. @xref{Files, ,Commands to
+Specify Files}.
@table @code
@item cd @var{directory}
whether or not you need to confirm by using the @code{set confirm} command
(@pxref{Messages/Warnings, ,Optional Warnings and Messages}).
-@node Kill Process, , Attach, Running
+@node Kill Process, Process Information, Attach, Running
@c @group
@section Killing the Child Process
will re-read the symbol table (while trying to preserve your current
breakpoint settings).
+@node Process Information, , Kill Process, Running
+@section Additional Process Information
+
+@kindex /proc
+@cindex process image
+Some operating systems provide a facility called @samp{/proc} that can
+be used to examine the image of a running process using file-system
+subroutines. If _GDBN__ is configured for an operating system with this
+facility, the command @code{info proc} is available to report on several
+kinds of information about the process running your program.
+
+@table @code
+@item info proc
+@kindex info proc
+Summarize available information about the process.
+
+@item info proc mappings
+@kindex info proc mappings
+Report on the address ranges accessible in the program, with information
+on whether your program may read, write, or execute each range.
+
+@item info proc times
+@kindex info proc times
+Starting time, user CPU time, and system CPU time for your program and
+its children.
+
+@item info proc id
+@kindex info proc id
+Report on the process ID's related to your program: its own process id,
+the id of its parent, the process group id, and the session id.
+
+@item info proc status
+@kindex info proc status
+General information on the state of the process. If the process is
+stopped, this report includes the reason for stopping, and any signal
+received.
+
+@item info proc all
+Show all the above information about the process.
+@end table
+
@node Stopping, Stack, Running, Top
@chapter Stopping and Continuing
@cindex breakpoints
A @dfn{breakpoint} makes your program stop whenever a certain point in
-your program is reached. For each breakpoint, you can add various
+the program is reached. For each breakpoint, you can add various
conditions to control in finer detail whether your program will stop.
You can set breakpoints with the @code{break} command and its variants
(@pxref{Set Breaks, ,Setting Breakpoints}), to specify the place where
your program should stop by line number, function name or exact address
-in your program. In languages with exception handling (such as GNU
+in the program. In languages with exception handling (such as GNU
C++), you can also set breakpoints where an exception is raised
-(@pxref{Exception Handling, ,Breakpoints and Exceptions}).@refill
+(@pxref{Exception Handling, ,Breakpoints and Exceptions}).
@cindex watchpoints
+@cindex memory tracing
+@cindex breakpoint on memory address
+@cindex breakpoint on variable modification
A @dfn{watchpoint} is a special breakpoint that stops your program
when the value of an expression changes. You must use a different
command to set watchpoints (@pxref{Set Watchpoints, ,Setting
Watchpoints}), but aside from that, you can manage a watchpoint like
any other breakpoint: you enable, disable, and delete both breakpoints
-and watchpoints using the same commands.@refill
-
-Each breakpoint or watchpoint is assigned a number when it is created;
-these numbers are successive integers starting with one. In many of the
-commands for controlling various features of breakpoints you use the
-breakpoint number to say which breakpoint you want to change. Each
-breakpoint may be @dfn{enabled} or @dfn{disabled}; if disabled, it has
+and watchpoints using the same commands.
+
+@cindex breakpoint numbers
+@cindex numbers for breakpoints
+_GDBN__ assigns a number to each breakpoint or watchpoint when you
+create it; these numbers are successive integers starting with one. In
+many of the commands for controlling various features of breakpoints you
+use the breakpoint number to say which breakpoint you want to change.
+Each breakpoint may be @dfn{enabled} or @dfn{disabled}; if disabled, it has
no effect on your program until you enable it again.
@menu
@kindex break
@kindex b
-Breakpoints are set with the @code{break} command (abbreviated @code{b}).
+@kindex $bpnum
+@cindex latest breakpoint
+Breakpoints are set with the @code{break} command (abbreviated
+@code{b}). The debugger convenience variable @samp{$bpnum} records the
+number of the beakpoint you've set most recently; see @ref{Convenience
+Vars,, Convenience Variables}, for a discussion of what you can do with
+convenience variables.
You have several ways to say where the breakpoint should go.
returns to that frame. This is similar to the effect of a
@code{finish} command in the frame inside the selected frame---except
that @code{finish} does not leave an active breakpoint. If you use
-@code{break} without an argument in the innermost frame, _GDBN__ will
-stop the next time it reaches the current location; this may be useful
-inside loops.@refill
+@code{break} without an argument in the innermost frame, _GDBN__ will stop
+the next time it reaches the current location; this may be useful
+inside loops.
_GDBN__ normally ignores breakpoints when it resumes execution, until at
least one instruction has been executed. If it did not do this, you
Set a breakpoint with condition @var{cond}; evaluate the expression
@var{cond} each time the breakpoint is reached, and stop only if the
value is nonzero---that is, if @var{cond} evaluates as true.
-@samp{@dots{}} stands for one of the possible arguments described above
-(or no argument) specifying where to break. @xref{Conditions, ,Break
-Conditions}, for more information on breakpoint conditions.
+@samp{@dots{}} stands for one of the possible arguments described
+above (or no argument) specifying where to break. @xref{Conditions,
+,Break Conditions}, for more information on breakpoint conditions.
@item tbreak @var{args}
@kindex tbreak
@kindex info breakpoints
@cindex @code{$_} and @code{info breakpoints}
@item info breakpoints @r{[}@var{n}@r{]}
-@item info break @r{[}@var{n}@r{]}
-Print a list of all breakpoints (but not watchpoints) set and not
-deleted, showing their numbers, where in your program they are, and any
-special features in use for them. Disabled breakpoints are included in
-the list, but marked as disabled. @code{info break} with a breakpoint
+@itemx info break @r{[}@var{n}@r{]}
+@itemx info watchpoints @r{[}@var{n}@r{]}
+Print a table of all breakpoints and watchpoints set and not
+deleted, with the following columns for each breakpoint:
+
+@table @emph
+@item Breakpoint Numbers
+@item Type
+Breakpoint or watchpoint.
+@item Disposition
+Whether the breakpoint is marked to be disabled or deleted when hit.
+@item Enabled or Disabled
+Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
+that are not enabled.
+@item Address
+Where the breakpoint is in your program, as a memory address
+@item What
+Where the breakpoint is in the source for your program, as a file and
+line number.
+@end table
+
+@noindent
+Breakpoint commands, if any, are listed after the line for the
+corresponding breakpoint.
+
+@noindent
+@code{info break} with a breakpoint
number @var{n} as argument lists only that breakpoint. The
convenience variable @code{$_} and the default examining-address for
the @code{x} command are set to the address of the last breakpoint
-listed (@pxref{Memory, ,Examining Memory}). The equivalent command
-for watchpoints is @code{info watch}. @end table
+listed (@pxref{Memory, ,Examining Memory}).
+@end table
-_GDBN__ allows you to set any number of breakpoints at the same place
-in your program. There is nothing silly or meaningless about this.
-When the breakpoints are conditional, this is even useful
+_GDBN__ allows you to set any number of breakpoints at the same place in
+your program. There is nothing silly or meaningless about this. When
+the breakpoints are conditional, this is even useful
(@pxref{Conditions, ,Break Conditions}).
+@cindex negative breakpoint numbers
+@cindex internal _GDBN__ breakpoints
+_GDBN__ itself sometimes sets breakpoints in your program for special
+purposes, such as proper handling of @code{longjmp} (in C programs).
+These internal breakpoints are assigned negative numbers, starting with
+@code{-1}; @samp{info breakpoints} does not display them, but the
+similar command @samp{info all-breakpoints} does.
+
+@table @code
+@kindex all-breakpoints
+@item info all-breakpoints
+Using the same format as @samp{info breakpoints}, display both the
+breakpoints you've set explicitly, and those _GDBN__ is using for
+internal purposes. Internal breakpoints are shown with negative
+breakpoint numbers. The type column identifies what kind of breakpoint
+is shown:
+
+@table @code
+@item breakpoint
+Normal, explicitly set breakpoint.
+
+@item watchpoint
+Normal, explicitly set watchpoint.
+
+@item longjmp
+Internal breakpoint, used to handle correctly stepping through
+@code{longjmp} calls.
+
+@item longjmp resume
+Internal breakpoint at the target of a @code{longjmp}.
+
+@item until
+Temporary internal breakpoint used by the _GDBN__ @code{until} command.
+
+@item finish
+Temporary internal breakpoint used by the _GDBN__ @code{finish} command.
+@end table
+
+@end table
+
+
@node Set Watchpoints, Exception Handling, Set Breaks, Breakpoints
@subsection Setting Watchpoints
@cindex setting watchpoints
+
You can use a watchpoint to stop execution whenever the value of an
expression changes, without having to predict a particular place
where this may happen.
@kindex info watchpoints
@item info watchpoints
-This command prints a list of watchpoints; it is otherwise similar to
-@code{info break}.
+This command prints a list of watchpoints and breakpoints; it is the
+same as @code{info break}.
@end table
@node Exception Handling, Delete Breaks, Set Watchpoints, Breakpoints
@kindex d
Delete the breakpoints or watchpoints of the numbers specified as
arguments. If no argument is specified, delete all breakpoints (_GDBN__
-asks confirmation, unless you've @code{set confirm off}). You
+asks confirmation, unless you have @code{set confirm off}). You
can abbreviate this command as @code{d}.
@end table
enabled; subsequently, they become disabled or enabled only when you
use one of the commands above. (The command @code{until} can set and
delete a breakpoint of its own, but it will not change the state of
-your other breakpoints; @pxref{Continuing and Stepping}.)
+your other breakpoints; see @ref{Continuing and Stepping, ,Continuing and Stepping}.)
@node Conditions, Break Commands, Disabling, Breakpoints
@subsection Break Conditions
The simplest sort of breakpoint breaks every time your program reaches a
specified place. You can also specify a @dfn{condition} for a
breakpoint. A condition is just a Boolean expression in your
-programming language (@pxref{Expressions}). A breakpoint with a condition
-evaluates the expression each time your program reaches it, and the
-program stops only if the condition is @emph{true}.
+programming language (@pxref{Expressions, ,Expressions}). A breakpoint with
+a condition evaluates the expression each time your program reaches it,
+and your program stops only if the condition is @emph{true}.
This is the converse of using assertions for program validation; in that
situation, you want to stop when the assertion is violated---that is,
your program only if the value of @var{expression} is true (nonzero, in
C). When you use @code{condition}, _GDBN__ checks @var{expression}
immediately for syntactic correctness, and to determine whether symbols
-in it have referents in the context of your breakpoint.
+in it have referents in the context of your breakpoint.
@c FIXME so what does GDB do if there is no referent? Moreover, what
@c about watchpoints?
_GDBN__ does
not actually evaluate @var{expression} at the time the @code{condition}
-command is given, however. @xref{Expressions}.
+command is given, however. @xref{Expressions, ,Expressions}.
@item condition @var{bnum}
Remove the condition from breakpoint number @var{bnum}. It becomes
be checked.
You could achieve the effect of the ignore count with a condition such
-as _0__@w{@samp{$foo-- <= 0}}_1__ using a debugger convenience
-variable that is decremented each time. @xref{Convenience Vars,
-,Convenience Variables}.@refill
+as _0__@w{@samp{$foo-- <= 0}}_1__ using a debugger convenience variable that
+is decremented each time. @xref{Convenience Vars, ,Convenience
+Variables}.
@node Break Commands, Breakpoint Menus, Conditions, Breakpoints
@subsection Breakpoint Command Lists
@end example
@noindent
-specifies a condition expression (@pxref{Expressions}) that will change
-@code{x} as needed, then always have the value zero so your program will
-not stop. No input is lost here, because _GDBN__ evaluates break
-conditions without changing the terminal modes. When you want to have
-nontrivial conditions for performing the side effects, the operators
-@samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful.
+specifies a condition expression (@pxref{Expressions, ,Expressions}) that will
+change @code{x} as needed, then always have the value zero so your
+program will not stop. No input is lost here, because _GDBN__ evaluates
+break conditions without changing the terminal modes. When you want
+to have nontrivial conditions for performing the side effects, the
+operators @samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful.
@node Breakpoint Menus, Error in Breakpoints, Break Commands, Breakpoints
@subsection Breakpoint Menus
Some programming languages (notably C++) permit a single function name
to be defined several times, for application in different contexts.
This is called @dfn{overloading}. When a function name is overloaded,
-@samp{break @var{function}} is not enough to tell _GDBN__ where you
-want a breakpoint. _GDBN__ offers you a menu of numbered choices for
-different possible breakpoints, and waits for your selection with the
-prompt @samp{>}. The first two options are always @samp{[0] cancel}
-and @samp{[1] all}. Typing @kbd{1} sets a breakpoint at each
-definition of @var{function}, and typing @kbd{0} aborts the
-@code{break} command without setting any new breakpoints.
+@samp{break @var{function}} is not enough to tell _GDBN__ where you want
+a breakpoint. If you realize this will be a problem, you can use
+something like @samp{break @var{function}(@var{types})} to specify which
+particular version of the function you want. Otherwise, _GDBN__ offers
+you a menu of numbered choices for different possible breakpoints, and
+waits for your selection with the prompt @samp{>}. The first two
+options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1}
+sets a breakpoint at each definition of @var{function}, and typing
+@kbd{0} aborts the @code{break} command without setting any new
+breakpoints.
For example, the following session excerpt shows an attempt to set a
breakpoint at the overloaded symbol @code{String::after}.
We choose three particular definitions of that function name:
+@c FIXME! This is likely to change to show arg type lists, at least
@example
(_GDBP__) b String::after
[0] cancel
(_GDBP__)
@end example
-
@node Error in Breakpoints, , Breakpoint Menus, Breakpoints
@subsection ``Cannot Insert Breakpoints''
@c FIXME: "cannot insert breakpoints" error, v unclear.
@c some light may be shed by looking at instances of
-@c ONE_PROCESS_WRITETEXT. But error seems possible otherwise
+@c ONE_PROCESS_WRITETEXT. But error message seems possible otherwise
@c too. pesch, 20sep91
Under some operating systems, breakpoints cannot be used in a program if
any other process is running that program. In this situation,
particular command you use). Either when continuing
or when stepping, your program may stop even sooner, due to a breakpoint
or to a signal. (If due to a signal, you may want to use @code{handle},
-or use @samp{signal 0} to resume execution. @xref{Signals}.)@refill
+or use @samp{signal 0} to resume execution. @xref{Signals, ,Signals}.)
@table @code
@item continue @r{[}@var{ignore-count}@r{]}
To resume execution at a different place, you can use @code{return}
(@pxref{Returning, ,Returning from a Function}) to go back to the
calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a
-Different Address}) to go to an arbitrary location in your program.@refill
-
+Different Address}) to go to an arbitrary location in your program.
@end table
A typical technique for using stepping is to set a breakpoint
returns. Print the returned value (if any).
Contrast this with the @code{return} command (@pxref{Returning,
-,Returning from a Function}).@refill
+,Returning from a Function}).
@item until
@kindex until
reached, or the current stack frame returns. @var{location} is any of
the forms of argument acceptable to @code{break} (@pxref{Set Breaks,
,Setting Breakpoints}). This form of the command uses breakpoints,
-and hence is quicker than @code{until} without an argument.@refill
+and hence is quicker than @code{until} without an argument.
@item stepi
@itemx si
An argument is a repeat count, as in @code{next}.
@end table
-
@node Signals, , Continuing and Stepping, Stopping
@section Signals
@cindex signals
When a signal has been set to stop your program, your program cannot see the
signal until you continue. It will see the signal then, if @code{pass} is
-in effect for the signal in question @i{at that time}. In other words,
+in effect for the signal in question @emph{at that time}. In other words,
after _GDBN__ reports a signal, you can use the @code{handle} command with
@code{pass} or @code{nopass} to control whether that signal will be seen by
your program when you later continue it.
causing display of the new frame. They are intended primarily for use
in _GDBN__ command scripts, where the output might be unnecessary and
distracting.
-
@end table
@node Frame Info, , Selection, Stack
current stack frame at the current point of execution. To see other
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}.@refill
+@xref{Exception Handling, ,Breakpoints and Exceptions}.
@end table
@node Source, Data, Stack, Top
@chapter Examining Source Files
_GDBN__ can print parts of your program's source, since the debugging
-information recorded in your program tells _GDBN__ what source files
-were used to build it. When your program stops, _GDBN__ spontaneously
-prints the line where it stopped. Likewise, when you select a stack
-frame (@pxref{Selection, ,Selecting a Frame}), _GDBN__ prints the line
-where execution in that frame has stopped. You can print other
-portions of source files by explicit command.@refill
+information recorded in your program tells _GDBN__ what source files were
+used to build it. When your program stops, _GDBN__ spontaneously prints
+the line where it stopped. Likewise, when you select a stack frame
+(@pxref{Selection, ,Selecting a Frame}), _GDBN__ prints the line where
+execution in that frame has stopped. You can print other portions of
+source files by explicit command.
-If you use _GDBN__ through its GNU Emacs interface, you may prefer to
-use Emacs facilities to view source; @pxref{Emacs, ,Using _GDBN__
-under GNU Emacs}.@refill
+If you use _GDBN__ through its GNU Emacs interface, you may prefer to use
+Emacs facilities to view source; @pxref{Emacs, ,Using _GDBN__ under GNU
+Emacs}.
@menu
* List:: Printing Source Lines
@code{list} command, this prints lines following the last lines
printed; however, if the last line printed was a solitary line printed
as part of displaying a stack frame (@pxref{Stack, ,Examining the
-Stack}), this prints lines centered around that line.@refill
+Stack}), this prints lines centered around that line.
@item list -
Print lines just before the lines last printed.
@itemx search @var{regexp}
@kindex search
@kindex forward-search
-The command @samp{forward-search @var{regexp}} checks each line, starting
-with the one following the last line listed, for a match for @var{regexp}.
-It lists the line that is found. You can abbreviate the command name
-as @code{fo}. The synonym @samp{search @var{regexp}} is also supported.
+The command @samp{forward-search @var{regexp}} checks each line,
+starting with the one following the last line listed, for a match for
+@var{regexp}. It lists the line that is found. You can use
+synonym @samp{search @var{regexp}} or abbreviate the command name as
+@code{fo}.
@item reverse-search @var{regexp}
The command @samp{reverse-search @var{regexp}} checks each line, starting
@node Machine Code, , Source Path, Source
@section Source and Machine Code
+
You can use the command @code{info line} to map source lines to program
addresses (and viceversa), and the command @code{disassemble} to display
a range of addresses as machine instructions.
@item info line @var{linespec}
@kindex info line
Print the starting and ending addresses of the compiled code for
-source line @var{linespec}. You can specify source lines in any of the
-ways understood by the @code{list} command (@pxref{List, ,Printing Source Lines}).
+source line @var{linespec}. You can specify source lines in any of
+the ways understood by the @code{list} command (@pxref{List, ,Printing
+Source Lines}).
@end table
-For example, we can use @code{info line} to inquire on where the object
-code for the first line of function @code{m4_changequote} lies:
+For example, we can use @code{info line} to discover the location of
+the object code for the first line of function
+@code{m4_changequote}:
+
@smallexample
(_GDBP__) info line m4_changecom
Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
@table @code
@kindex disassemble
@item disassemble
-This specialized command is provided to dump a range of memory as
-machine instructions. The default memory range is the function
-surrounding the program counter of the selected frame. A single
-argument to this command is a program counter value; the function
-surrounding this value will be dumped. Two arguments (separated by one
-or more spaces) specify a range of addresses (first inclusive, second
-exclusive) to be dumped.
+This specialized command dumps a range of memory as machine
+instructions. The default memory range is the function surrounding the
+program counter of the selected frame. A single argument to this
+command is a program counter value; the function surrounding this value
+will be dumped. Two arguments specify a range of addresses (first
+inclusive, second exclusive) to dump.
@end table
We can use @code{disassemble} to inspect the object code
0x63fc <builtin_init+5364>: call 0x9288 <path_search>
0x6400 <builtin_init+5368>: nop
End of assembler dump.
-(_GDBP__)
-
@end smallexample
@node Data, Languages, Source, Top
@cindex examining data
@kindex print
@kindex inspect
-@c "inspect" isn't quite a synonym if you are using Epoch, which we do not
+@c "inspect" is not quite a synonym if you are using Epoch, which we do not
@c document because it is nonstandard... Under Epoch it displays in a
@c different window or something like that.
The usual way to examine data in your program is with the @code{print}
command (abbreviated @code{p}), or its synonym @code{inspect}. It
evaluates and prints the value of an expression of the language your
-program is written in (@pxref{Languages}).
+program is written in (@pxref{Languages, ,Using _GDBN__ with Different
+Languages}).
@table @code
@item print @var{exp}
@item print
@itemx print /@var{f}
If you omit @var{exp}, _GDBN__ displays the last value again (from the
-@dfn{value history}; @pxref{Value History}). This allows you to
+@dfn{value history}; @pxref{Value History, ,Value History}). This allows you to
conveniently inspect the same value in an alternative format.
@end table
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}.
+command rather than @code{print}. @xref{Symbols, ,Examining the Symbol Table}.
@menu
* Expressions:: Expressions
by preprocessor @code{#define} commands.
Because C is so widespread, most of the expressions shown in examples in
-this manual are in C. @xref{Languages,, Using _GDBN__ with Different
+this manual are in C. @xref{Languages, , Using _GDBN__ with Different
Languages}, for information on how to use expressions in other
languages.
@table @code
@item @@
@samp{@@} is a binary operator for treating parts of memory as arrays.
-@xref{Arrays}, for more information.
+@xref{Arrays, ,Artificial Arrays}, for more information.
@item ::
@samp{::} allows you to specify a variable in terms of the file or
-function where it is defined. @xref{Variables}.
+function where it is defined. @xref{Variables, ,Program Variables}.
@item @{@var{type}@} @var{addr}
Refers to an object of type @var{type} stored at address @var{addr} in
memory. @var{addr} may be any expression whose value is an integer or
pointer (but parentheses are required around binary operators, just as in
a cast). This construct is allowed regardless of what kind of data is
-normally supposed to reside at @var{addr}.@refill
+normally supposed to reside at @var{addr}.
@end table
@node Variables, Arrays, Expressions, Data
There is an exception: you can refer to a variable or function whose
scope is a single source file even if the current execution point is not
in this file. But it is possible to have more than one such variable or
-function with the same name (in different source files). If that happens,
-referring to that name has unpredictable effects. If you wish, you can
-specify a variable in a particular file, using the colon-colon notation:
+function with the same name (in different source files). If that
+happens, referring to that name has unpredictable effects. If you wish,
+you can specify a static variable in a particular function or file,
+using the colon-colon notation:
@cindex colon-colon
@iftex
@end iftex
@example
@var{file}::@var{variable}
+@var{function}::@var{variable}
@end example
@noindent
-Here @var{file} is the name of the source file whose variable you want.
+Here @var{file} or @var{function} is the name of the context for the
+static @var{variable}.
@cindex C++ scope resolution
This use of @samp{::} is very rarely in conflict with the very similar
with @samp{@@} in this way behave just like other arrays in terms of
subscripting, and are coerced to pointers when used in expressions.
Artificial arrays most often appear in expressions via the value history
-(@pxref{Value History}), after printing one out.)
+(@pxref{Value History, ,Value History}), after printing one out.)
-Sometimes the artificial array mechanism isn't quite enough; in
+Sometimes the artificial array mechanism is not quite enough; in
moderately complex data structures, the elements of interest may not
-actually be adjacent---for example, if you are interested in the
-values of pointers in an array. One useful work-around in this
-situation is to use a convenience variable (@pxref{Convenience Vars,
-,Convenience Variables}) as a counter in an expression that prints the
-first interesting value, and then repeat that expression via
-@key{RET}. For instance, suppose you have an array @code{dtab} of
-pointers to structures, and you are interested in the values of a
-field @code{fv} in each structure. Here's an example of what you
-might type:
+actually be adjacent---for example, if you are interested in the values
+of pointers in an array. One useful work-around in this situation is
+to use a convenience variable (@pxref{Convenience Vars, ,Convenience
+Variables}) as a counter in an expression that prints the first
+interesting value, and then repeat that expression via @key{RET}. For
+instance, suppose you have an array @code{dtab} of pointers to
+structures, and you are interested in the values of a field @code{fv}
+in each structure. Here is an example of what you might type:
+
@example
set $i = 0
p dtab[$i++]->fv
Print as an address, both absolute in hex and as an offset from the
nearest preceding symbol. This format can be used to discover where (in
what function) an unknown address is located:
+
@example
(_GDBP__) p/a 0x54320
_0__$3 = 0x54320 <_initialize_vx+396>_1__
@end example
-
@item c
Regard as an integer and print it as a character constant.
@node Memory, Auto Display, Output formats, Data
@section Examining Memory
+You can use the command @code{x} (for ``examine'') to examine memory in
+any of several formats, independently of your program's data types.
+
@cindex examining memory
@table @code
@kindex x
@item x/@var{nfu} @var{addr}
@itemx x @var{addr}
@itemx x
-You can use the command @code{x} (for `examine') to examine memory in
-any of several formats, independently of your program's data types.
-@var{n}, @var{f}, and @var{u} are all optional parameters to specify how
-much memory to display, and how to format it; @var{addr} is an
+Use the command @code{x} to examine memory.
+@end table
+
+@var{n}, @var{f}, and @var{u} are all optional parameters that specify how
+much memory to display and how to format it; @var{addr} is an
expression giving the address where you want to start displaying memory.
If you use defaults for @var{nfu}, you need not type the slash @samp{/}.
Several commands set convenient defaults for @var{addr}.
-@end table
-@var{n}, the repeat count, is a decimal integer; the default is 1. It
-specifies how much memory (counting by units @var{u}) to display.
+@table @r
+@item @var{n}, the repeat count
+The repeat count is a decimal integer; the default is 1. It specifies
+how much memory (counting by units @var{u}) to display.
@c This really is **decimal**; unaffected by 'set radix' as of GDB
@c 4.1.2.
-@var{f}, the display format, is one of the formats used by @code{print},
+@item @var{f}, the display format
+The display format is one of the formats used by @code{print},
or @samp{s} (null-terminated string) or @samp{i} (machine instruction).
The default is @samp{x} (hexadecimal) initially, or the format from the
last time you used either @code{x} or @code{print}.
-@var{u}, the unit size, is any of
+@item @var{u}, the unit size
+The unit size is any of
@table @code
@item b
Bytes.
Giant words (eight bytes).
@end table
-@noindent
Each time you specify a unit size with @code{x}, that size becomes the
default unit the next time you use @code{x}. (For the @samp{s} and
@samp{i} formats, the unit size is ignored and is normally not written.)
+@item @var{addr}, starting display address
@var{addr} is the address where you want _GDBN__ to begin displaying
memory. The expression need not have a pointer value (though it may);
it is always interpreted as an integer address of a byte of memory.
-@xref{Expressions} for more information on expressions. The default for
+@xref{Expressions, ,Expressions}, for more information on expressions. The default for
@var{addr} is usually just after the last address examined---but several
other commands also set the default address: @code{info breakpoints} (to
the address of the last breakpoint listed), @code{info line} (to the
starting address of a line), and @code{print} (if you use it to display
a value from memory).
+@end table
For example, @samp{x/3uh 0x54320} is a request to display three halfwords
(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}),
All the defaults for the arguments to @code{x} are designed to make it
easy to continue scanning memory with minimal specifications each time
-you use @code{x}. For example, after you've inspected three machine
+you use @code{x}. For example, after you have inspected three machine
instructions with @samp{x/3i @var{addr}}, you can inspect the next seven
with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command,
the repeat count @var{n} is used again; the other arguments default as
@item display @var{exp}
@kindex display
Add the expression @var{exp} to the list of expressions to display
-each time your program stops. @xref{Expressions}.
+each time your program stops. @xref{Expressions, ,Expressions}.
@code{display} will not repeat if you press @key{RET} again after using it.
even when it also displays the contents of those addresses. The default
is on. For example, this is what a stack frame display looks like, with
@code{set print address on}:
+
@smallexample
+@group
(_GDBP__) f
#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
at input.c:530
530 if (lquote != def_lquote)
+@end group
@end smallexample
@item set print address off
Do not print addresses when displaying their contents. For example,
this is the same stack frame displayed with @code{set print address off}:
+
@example
+@group
(_GDBP__) set print addr off
(_GDBP__) f
#0 set_quotes (lq="<<", rq=">>") at input.c:530
530 if (lquote != def_lquote)
+@end group
@end example
@item show print address
line, like this:
@example
+@group
$1 = @{
next = 0x0,
flags = @{
@},
meat = 0x54 "Pork"
@}
+@end group
@end example
@item set print pretty off
Cause _GDBN__ to print structures in a compact format, like this:
@smallexample
-$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, meat \
-= 0x54 "Pork"@}
+@group
+$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \
+meat = 0x54 "Pork"@}
+@end group
@end smallexample
@noindent
@item show print vtbl
@kindex show print vtbl
Show whether C++ virtual function tables are pretty printed, or not.
-
@end table
@node Value History, Convenience Vars, Print Settings, Data
_GDBN__ to hold on to a value and refer to it later. These variables
exist entirely within _GDBN__; they are not part of your program, and
setting a convenience variable has no direct effect on further execution
-of your program. That's why you can use them freely.
+of your program. That is why you can use them freely.
Convenience variables are prefixed with @samp{$}. Any name preceded by
@samp{$} can be used for a convenience variable, unless it is one of
the predefined machine-specific register names (@pxref{Registers}).
(Value history references, in contrast, are @emph{numbers} preceded
-by @samp{$}. @xref{Value History}.)
+by @samp{$}. @xref{Value History, ,Value History}.)
You can save a value in a convenience variable with an assignment
expression, just as you would set a variable in your program. Example:
pointer to the current stack frame, and @code{$ps} is used for a
register that contains the processor status. For example,
you could print the program counter in hex with
+
@example
p/x $pc
@end example
@noindent
or print the instruction to be executed next with
+
@example
x/i $pc
@end example
stack frame is selected; setting @code{$sp} is not allowed when other
stack frames are selected. To pop entire frames off the stack,
regardless of machine architecture, use @code{return};
-@pxref{Returning, ,Returning from a Function}.} with@refill
+@pxref{Returning, ,Returning from a Function}.} with
+
@example
set $sp += 4
@end example
_GDBN__ is unable to locate the saved registers, the selected stack
frame will make no difference.
+_if__(_AMD29K__)
+@table @code
+@item set rstack_high_address @var{address}
+@kindex set rstack_high_address
+@cindex AMD 29K register stack
+@cindex register stack, AMD29K
+On AMD 29000 family processors, registers are saved in a separate
+``register stack''. There is no way for _GDBN__ to determine the extent
+of this stack. Normally, _GDBN__ just assumes that the stack is ``large
+enough''. This may result in _GDBN__ referencing memory locations that
+don't exist. If necessary, you can get around this problem by
+specifying the ending address of the register stack with the @code{set
+rstack_high_address} command. The argument should be an address, which
+you will probably want to precede with @samp{0x} to specify in
+hexadecimal.
+
+@item show rstack_high_address
+@kindex show rstack_high_address
+Display the current limit of the register stack, on AMD 29000 family
+processors.
+@end table
+_fi__(_AMD29K__)
+
@node Floating Point Hardware, , Registers, Data
@section Floating Point Hardware
@cindex floating point
+
Depending on the host machine architecture, _GDBN__ may be able to give
you more information about the status of the floating point hardware.
build and compute expressions that may involve variables in your program.
@item info frame
-Among the other information listed here (@pxref{Frame Info,,Information
+Among the other information listed here (@pxref{Frame Info, ,Information
about a Frame}) is the source language for this frame. This is the
language that will become the working language if you ever use an
identifier that is in this frame.
@item info source
-Among the other information listed here (@pxref{Symbols,,Examining the
+Among the other information listed here (@pxref{Symbols, ,Examining the
Symbol Table}) is the source language of this source file.
-
@end table
@node Checks, Support, Show, Languages
by eliminating type mismatches, and providing active checks for range
errors when your program is running.
-_GDBN__ can check for conditions like the above if you wish. Although
-_GDBN__ will not check the statements in your program, it can check
-expressions entered directly into _GDBN__ for evaluation via the
-@code{print} command, for example. As with the working language,
+_GDBN__ can check for conditions like the above if you wish.
+Although _GDBN__ will not check the statements in your program, it
+can check expressions entered directly into _GDBN__ for evaluation via
+the @code{print} command, for example. As with the working language,
_GDBN__ can also decide whether or not to check automatically based on
-your program's source language. @xref{Support,,Supported Languages},
-for the default settings of supported languages.@refill
+your program's source language. @xref{Support, ,Supported Languages},
+for the default settings of supported languages.
@menu
* Type Checking:: An overview of type checking
@example
1 + 2 @result{} 3
+@exdent but
@error{} 1 + 2.3
@end example
instance, both Modula-2 and C require the arguments to arithmetical
operators to be numbers. In C, enumerated types and pointers can be
represented as numbers, so that they are valid arguments to mathematical
-operators. @xref{Support,,Supported Languages}, for futher
+operators. @xref{Support, ,Supported Languages}, for further
details on specific languages.
_GDBN__ provides some additional commands for controlling the type checker:
@table @code
@item set check type auto
Set type checking on or off based on the current working language.
-@xref{Support,,Supported Languages}, for the default settings for
+@xref{Support, ,Supported Languages}, for the default settings for
each language.
@item set check type on
error. In many implementations of C, mathematical overflow causes the
result to ``wrap around'' to lower values---for example, if @var{m} is
the largest integer value, and @var{s} is the smallest, then
+
@example
@var{m} + 1 @result{} @var{s}
@end example
This, too, is specific to individual languages, and in some cases
-specific to individual compilers or machines. @xref{Support,,
+specific to individual compilers or machines. @xref{Support, ,
Supported Languages}, for further details on specific languages.
_GDBN__ provides some additional commands for controlling the range checker:
@table @code
@item set check range auto
Set range checking on or off based on the current working language.
-@xref{Support,,Supported Languages}, for the default settings for
+@xref{Support, ,Supported Languages}, for the default settings for
each language.
@item set check range on
@node Support, , Checks, Languages
@section Supported Languages
-_GDBN__ _GDB_VN__ supports C, C++, and Modula-2. The syntax for C and C++ is
-so closely related that _GDBN__ does not distinguish the two. Some
-_GDBN__ features may be used in expressions regardless of the language
-you use: the _GDBN__ @code{@@} and @code{::} operators, and the
-@samp{@{type@}addr} construct (@pxref{Expressions}) can be used with the constructs of
-any of the supported languages.
+_GDBN__ 4 supports C, C++, and Modula-2. The syntax for C and C++ is so
+closely related that _GDBN__ does not distinguish the two. Some _GDBN__
+features may be used in expressions regardless of the language you
+use: the _GDBN__ @code{@@} and @code{::} operators, and the
+@samp{@{type@}addr} construct (@pxref{Expressions, ,Expressions}) can be
+used with the constructs of any of the supported languages.
The following sections detail to what degree each of these
source languages is supported by _GDBN__. These sections are
you must compile your C++ programs with the GNU C++ compiler,
@code{g++}.
-
@menu
* C Operators:: C and C++ Operators
* C Constants:: C and C++ Constants
@item
@emph{Scalar types} include all of the above.
-
@end itemize
@noindent
in order of increasing precedence:
@table @code
-_0__
-@item ,
+_0__@item ,
The comma or sequencing operator. Expressions in a comma-separated list
are evaluated from left to right, with the result of the entire
expression being the last expression evaluated.
assigned. Defined on scalar types.
@item @var{op}=
-Used in an expression of the form @var{a} @var{op}@code{=} @var{b}, and
-translated to @var{a} @code{=} @var{a op b}. @var{op}@code{=} and
-@code{=} have the same precendence. @var{op} is any one of the
-operators @code{|}, @code{^}, @code{&}, @code{<<}, @code{>>}, @code{+},
-@code{-}, @code{*}, @code{/}, @code{%}.
+Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
+and translated to @w{@code{@var{a} = @var{a op b}}}.
+@w{@code{@var{op}=}} and @code{=} have the same precendence.
+@var{op} is any one of the operators @code{|}, @code{^}, @code{&},
+@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
@item ?:
The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
integral type.
@item ||
-Logical OR. Defined on integral types.
+Logical @sc{or}. Defined on integral types.
@item &&
-Logical AND. Defined on integral types.
+Logical @sc{and}. Defined on integral types.
@item |
-Bitwise OR. Defined on integral types.
+Bitwise @sc{or}. Defined on integral types.
@item ^
-Bitwise exclusive-OR. Defined on integral types.
+Bitwise exclusive-@sc{or}. Defined on integral types.
@item &
-Bitwise AND. Defined on integral types.
+Bitwise @sc{and}. Defined on integral types.
@item ==@r{, }!=
Equality and inequality. Defined on scalar types. The value of these
left shift, and right shift. Defined on integral types.
@item @@
-The _GDBN__ ``artificial array'' operator (@pxref{Expressions}).
+The _GDBN__ ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
@item +@r{, }-
Addition and subtraction. Defined on integral types, floating-point types and
@item &
Address operator. Defined on variables. Same precedence as @code{++}.
+For debugging C++, _GDBN__ implements a use of @samp{&} beyond what's
+allowed in the C++ language itself: you can use @samp{&(&@var{ref})}
+(or, if you prefer, simply @samp{&&@var{ref}} to examine the address
+where a C++ reference variable (declared with @samp{&@var{ref}}) is
+stored.
+
@item -
Negative. Defined on integral and floating-point types. Same
precedence as @code{++}.
@code{struct}, @code{union}, and @code{class} types.
@item ::
-The _GDBN__ scope operator (@pxref{Expressions}). Same precedence as
-@code{::}, above. _1__
+The _GDBN__ scope operator (@pxref{Expressions, ,Expressions}). Same precedence as
+@code{::}, above._1__
@end table
@cindex C and C++ constants
following ways:
@itemize @bullet
-
@item
Integer constants are a sequence of digits. Octal constants are
specified by a leading @samp{0} (ie. zero), and hexadecimal constants by
-a leading @samp{0x} or @samp{0X}. Constants may also end with an
+a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
@samp{l}, specifying that the constant should be treated as a
@code{long} value.
@item
Pointer constants are an integral value.
-
@end itemize
-
@node Cplusplus expressions, C Defaults, C Constants, C
@subsubsection C++ Expressions
@cindex member functions
@item
Member function calls are allowed; you can use expressions like
+
@example
count = aml->GetOriginal(x, y)
@end example
reference variables are not displayed (unlike other variables); this
avoids clutter, since references are often used for large structures.
The @emph{address} of a reference variable is always shown, unless
-you've specified @samp{set print address off}.
-
+you have specified @samp{set print address off}.
@item
_GDBN__ supports the C++ name resolution operator @code{::}---your
necessary, for example in an expression like
@samp{@var{scope1}::@var{scope2}::@var{name}}. _GDBN__ also allows
resolving name scope by reference to source files, in both C and C++
-debugging; @pxref{Variables}.
-
+debugging (@pxref{Variables, ,Program Variables}).
@end enumerate
-
@node C Defaults, C Checks, Cplusplus expressions, C
@subsubsection C and C++ Defaults
@cindex C and C++ defaults
If you allow _GDBN__ to set the language automatically, it sets the
working language to C/C++ on entering code compiled from a source file
whose name ends with @file{.c} or @file{.cc}.
-@xref{Automatically,,Having _GDBN__ infer the source language}, for
+@xref{Automatically, ,Having _GDBN__ infer the source language}, for
further details.
@node C Checks, Debugging C, C Defaults, C
declared in the same declaration. (Note: this may not be true for all C
compilers.)
@end ignore
-
@end itemize
Range checking, if turned on, is done on mathematical operations. Array
Otherwise, it will appear as @samp{@{...@}}.
The @code{@@} operator aids in the debugging of dynamic arrays, formed
-with pointers and a memory allocation function. (@pxref{Expressions})
+with pointers and a memory allocation function. (@pxref{Expressions, ,Expressions})
@node Debugging C plus plus, , Debugging C, C
-@subsubsection _GDBN__ Commands for C++
+@subsubsection _GDBN__ Features for C++
@cindex commands for C++
Some _GDBN__ commands are particularly useful with C++, and some are
@item catch @var{exceptions}
@itemx info catch
Debug C++ exception handling using these commands. @xref{Exception
-Handling, ,Breakpoints and Exceptions}. @refill
+Handling, ,Breakpoints and Exceptions}.
@cindex inheritance
@item ptype @var{typename}
Print inheritance relationships as well as other information for type
@var{typename}.
-@xref{Symbols}.
+@xref{Symbols, ,Examining the Symbol Table}.
@cindex C++ symbol display
@item set print demangle
@itemx show print asm-demangle
Control whether C++ symbols display in their source form, both when
displaying code as C++ source and when displaying disassemblies.
-@xref{Print Settings}.
+@xref{Print Settings, ,Print Settings}.
@item set print object
@itemx show print object
Choose whether to print derived (actual) or declared types of objects.
-@xref{Print Settings}.
+@xref{Print Settings, ,Print Settings}.
@item set print vtbl
@itemx show print vtbl
Control the format for printing virtual function tables.
-@xref{Print Settings}.
-
+@xref{Print Settings, ,Print Settings}.
+
+@item @r{Overloaded symbol names}
+You can specify a particular definition of an overloaded symbol, using
+the same notation that's used to declare such symbols in C++: type
+@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
+also use _GDBN__'s command-line word completion facilities to list the
+available choices, or to finish the type list for you.
+@xref{Completion,, Command Completion}, for details on how to do this.
@end table
-
@node Modula-2, , C, Support
@subsection Modula-2
@cindex Modula-2
@item
@emph{Boolean types} consist of @code{BOOLEAN}.
-
@end itemize
@noindent
increasing precedence:
@table @code
-_0__
@item ,
Function argument or array index separator.
-
+_0__
@item :=
Assignment. The value of @var{var} @code{:=} @var{value} is
@var{value}.
Boolean conjuction. Defined on boolean types.
@item @@
-The _GDBN__ ``artificial array'' operator (@pxref{Expressions}).
+The _GDBN__ ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
@item +@r{, }-
Addition and subtraction on integral and floating-point types, or union
@item ::@r{, }.
_GDBN__ and Modula-2 scope operators.
-
@end table
@quotation
@code{<=}, and @code{>=} on sets as an error.
@end quotation
_1__
-
@cindex Modula-2 built-ins
@node Built-In Func/Proc, M2 Constants, M2 Operators, Modula-2
@subsubsection Built-in Functions and Procedures
@item x
represents a variable or constant of one of many types. See the
explanation of the function for details.
-
@end table
All Modula-2 built-in procedures also return a result, described below.
followed by a @samp{C}.
@item
-String constants consist of a sequence of characters enclosed by a pair
-of like quotes, either single (@code{'}) or double (@code{"}). Escape
-sequences in the style of C are also allowed. @xref{C Constants}, for a
-brief explanation of escape sequences.
+String constants consist of a sequence of characters enclosed by a
+pair of like quotes, either single (@code{'}) or double (@code{"}).
+Escape sequences in the style of C are also allowed. @xref{C
+Constants, ,C and C++ Constants}, for a brief explanation of escape
+sequences.
@item
Enumerated constants consist of an enumerated identifier.
@item
Set constants are not yet supported.
-
@end itemize
@node M2 Defaults, Deviations, M2 Constants, Modula-2
If you allow _GDBN__ to set the language automatically, then entering
code compiled from a file whose name ends with @file{.mod} will set the
-working language to Modula-2. @xref{Automatically,,Having _GDBN__ set
+working language to Modula-2. @xref{Automatically, ,Having _GDBN__ set
the language automatically}, for further details.
@node Deviations, M2 Checks, M2 Defaults, Modula-2
@item
All built-in procedures both modify @emph{and} return their argument.
-
@end itemize
@node M2 Checks, M2 Scope, Deviations, Modula-2
@item
They have been declared on the same line. (Note: This is true of the
GNU Modula-2 compiler, but it may not be true of other compilers.)
-
@end itemize
As long as type checking is enabled, any attempt to combine variables
@subsubsection The scope operators @code{::} and @code{.}
@cindex scope
@kindex .
+@cindex colon, doubled as scope operator
+@ifinfo
+@kindex colon-colon
+@c Info cannot handoe :: but TeX can.
+@end ifinfo
+@iftex
@kindex ::
+@end iftex
There are a few subtle differences between the Modula-2 scope operator
(@code{.}) and the _GDBN__ scope operator (@code{::}). The two have
@var{module} . @var{id}
@var{scope} :: @var{id}
-
@end example
@noindent
apply to C++, and the last to C's @code{union} type, which has no direct
analogue in Modula-2.
-The @code{@@} operator (@pxref{Expressions}), while available
+The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available
while using any language, is not useful with Modula-2. Its
intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be
created in Modula-2 as they can in C or C++. However, because an
address can be specified by an integral constant, the construct
-@samp{@{@var{type}@}@var{adrexp}} is still useful. (@pxref{Expressions})
-
+@samp{@{@var{type}@}@var{adrexp}} is still useful. (@pxref{Expressions, ,Expressions})
_0__
@cindex @code{#} in Modula-2
In _GDBN__ scripts, the Modula-2 inequality operator @code{#} is
interpreted as the beginning of a comment. Use @code{<>} instead.
_1__
-
-
@node Symbols, Altering, Languages, Top
@chapter Examining the Symbol Table
program. This information is inherent in the text of your program and
does not change as your program executes. _GDBN__ finds it in your
program's symbol table, in the file indicated when you started _GDBN__
-(@pxref{File Options}), or by one of the file-management commands
-(@pxref{Files, ,Commands to Specify Files}).
+(@pxref{File Options, ,Choosing Files}), or by one of the
+file-management commands (@pxref{Files, ,Commands to Specify Files}).
@table @code
@item info address @var{symbol}
Print the data type of expression @var{exp}. @var{exp} is not
actually evaluated, and any side-effecting operations (such as
assignments or function calls) inside it do not take place.
-@xref{Expressions}.
+@xref{Expressions, ,Expressions}.
@item whatis
Print the data type of @code{$}, the last value in the value history.
Print a description of data type @var{typename}. @var{typename} may be
the name of a type, or for C code it may have the form
@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
-@samp{enum @var{enum-tag}}.@refill
+@samp{enum @var{enum-tag}}.
@item ptype @var{exp}
@itemx ptype
Print a description of the type of expression @var{exp}. @code{ptype}
-differs from @code{whatis} by printing a detailed description, instead of just
-the name of the type. For example, if your program declares a variable
-as
+differs from @code{whatis} by printing a detailed description, instead
+of just the name of the type. For example, if your program declares a
+variable as
+
@example
struct complex @{double real; double imag;@} v;
@end example
+
@noindent
compare the output of the two commands:
+
@example
+@group
(_GDBP__) whatis v
type = struct complex
(_GDBP__) ptype v
double real;
double imag;
@}
+@end group
@end example
+
@noindent
As with @code{whatis}, using @code{ptype} without an argument refers to
the type of @code{$}, the last value in the value history.
variables) whose names contain a match for regular expression
@var{regexp}.
-
@ignore
This was never implemented.
@item info methods
@item printsyms @var{filename}
@itemx printpsyms @var{filename}
+@itemx printmsyms @var{filename}
@kindex printsyms
@cindex symbol dump
@kindex printsyms
details: that is, @var{filename} reflects symbols for only those files
whose symbols _GDBN__ has read. You can use the command @code{info
sources} to find out which files these are. If you use
-@code{printpsyms}, the dump also shows information about symbols that
+@code{printpsyms} instead, the dump shows information about symbols that
_GDBN__ only knows partially---that is, symbols defined in files that
-_GDBN__ has skimmed, but not yet read completely. The description of
-@code{symbol-file} describes how _GDBN__ reads symbols; both commands
-are described under @ref{Files, ,Commands to Specify Files}.
-
+_GDBN__ has skimmed, but not yet read completely. Finally,
+@code{printmsyms} dumps just the minimal symbol information required for
+each object file from which _GDBN__ has read some symbols. The description of
+@code{symbol-file} explains how _GDBN__ reads symbols; both @code{info
+source} and @code{symbol-file} are described in @ref{Files, ,Commands
+to Specify Files}.
@end table
@node Altering, _GDBN__ Files, Symbols, Top
@cindex assignment
@cindex setting variables
To alter the value of a variable, evaluate an assignment expression.
-@xref{Expressions}. For example,
+@xref{Expressions, ,Expressions}. For example,
@example
print x=4
@end example
@noindent
-would store the value 4 into the variable @code{x}, and then print the
-value of the assignment expression (which is 4). @xref{Languages}, for
-more information on operators in supported languages.
+stores the value 4 into the variable @code{x}, and then prints the
+value of the assignment expression (which is 4). @xref{Languages,
+,Using _GDBN__ with Different Languages}, for more information on
+operators in supported languages.
@kindex set variable
@cindex variables, setting
If you are not interested in seeing the value of the assignment, use the
@code{set} command instead of the @code{print} command. @code{set} is
really the same as @code{print} except that the expression's value is not
-printed and is not put in the value history (@pxref{Value History}). The
+printed and is not put in the value history (@pxref{Value History, ,Value History}). The
expression is evaluated only for its effects.
If the beginning of the argument string of the @code{set} command
to @code{set} except for its lack of subcommands. For example, a
program might well have a variable @code{width}---which leads to
an error if we try to set a new value with just @samp{set width=13}, as
-we might if @code{set width} didn't happen to be a _GDBN__ command:
+we might if @code{set width} did not happen to be a _GDBN__ command:
+
@example
(_GDBP__) whatis width
type = double
(_GDBP__) set width=47
Invalid syntax in expression.
@end example
+
@noindent
The invalid expression, of course, is @samp{=47}. What we can do in
order to actually set our program's variable @code{width} is
+
@example
(_GDBP__) set var width=47
@end example
-_GDBN__ allows more implicit conversions in assignments than C does; you can
-freely store an integer value into a pointer variable or vice versa, and
-any structure can be converted to any other structure that is the same
-length or shorter.
+_GDBN__ allows more implicit conversions in assignments than C; you can
+freely store an integer value into a pointer variable or vice versa,
+and any structure can be converted to any other structure that is the
+same length or shorter.
@comment FIXME: how do structs align/pad in these conversions?
To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
construct to generate a value of specified type at a specified address
-(@pxref{Expressions}). For example, @code{@{int@}0x83040} refers
+(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers
to memory location @code{0x83040} as an integer (which implies a certain size
and representation in memory), and
@noindent
causes the next @code{continue} command or stepping command to execute at
-address 0x485, rather than at the address where your program stopped.
-@xref{Continuing and Stepping}.
+address @code{0x485}, rather than at the address where your program stopped.
+@xref{Continuing and Stepping, ,Continuing and Stepping}.
The most common occasion to use the @code{jump} command is to back up,
perhaps with more breakpoints set, over a portion of a program that has
The @code{return} command does not resume execution; it leaves the
program stopped in the state that would exist if the function had just
-returned. In contrast, the @code{finish} command
-(@pxref{Continuing and Stepping})
-resumes execution until the selected stack frame returns naturally.@refill
+returned. In contrast, the @code{finish} command (@pxref{Continuing
+and Stepping, ,Continuing and Stepping}) resumes execution until the
+selected stack frame returns naturally.
@node Calling, Patching, Returning, Altering
@section Calling your Program's Functions
@cindex patching binaries
@cindex writing into executables
@cindex writing into corefiles
+
By default, _GDBN__ opens the file containing your program's executable
code (or the corefile) read-only. This prevents accidental alterations
to machine code; but it also prevents you from intentionally patching
core files for both reading and writing; if you specify @samp{set write
off} (the default), _GDBN__ will open them read-only.
-If you've already loaded a file, you must load it
+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.
@kindex show write
Display whether executable files and core files will be opened for
writing as well as reading.
-
@end table
@node _GDBN__ Files, Targets, Altering, Top
@chapter _GDBN__'s Files
+_GDBN__ needs to know the file name of the program to be debugged, both in
+order to read its symbol table and in order to start your program. To
+debug a core dump of a previous run, _GDBN__ must be told the file name of
+the core dump.
+
@menu
* Files:: Commands to Specify Files
* Symbol Errors:: Errors Reading Symbol Files
@section Commands to Specify Files
@cindex core dump file
@cindex symbol table
-_GDBN__ needs to know the file name of the program to be debugged, both in
-order to read its symbol table and in order to start your program. To
-debug a core dump of a previous run, _GDBN__ must be told the file name of
-the core dump.
-The usual way to specify the executable and core dump file names is with
-the command arguments given when you start _GDBN__, as discussed in
-@pxref{Invocation, ,Getting In and Out of _GDBN__}.
+The usual way to specify executable and core dump file names is with
+the command arguments given when you start _GDBN__, (@pxref{Invocation,
+,Getting In and Out of _GDBN__}.
Occasionally it is necessary to change to a different file during a
_GDBN__ session. Or you may run _GDBN__ and forget to specify the files you
Use @var{filename} as the program to be debugged. It is read for its
symbols and for the contents of pure memory. It is also the program
executed when you use the @code{run} command. If you do not specify a
-directory and the file is not found in _GDBN__'s working directory,
-
-_GDBN__ uses the environment variable @code{PATH} as a list of
-directories to search, just as the shell does when looking for a program
-to run. You can change the value of this variable, for both _GDBN__ and
-your program, using the @code{path} command.
+directory and the file is not found in _GDBN__'s working directory, _GDBN__
+uses the environment variable @code{PATH} as a list of directories to
+search, just as the shell does when looking for a program to run. You
+can change the value of this variable, for both _GDBN__ and your program,
+using the @code{path} command.
+
+On systems with memory-mapped files, an auxiliary symbol table file
+@file{@var{filename}.syms} may be available for @var{filename}. If it
+is, _GDBN__ will map in the symbol table from
+@file{@var{filename}.syms}, starting up more quickly. See the
+descriptions of the options @samp{-mapped} and @samp{-readnow} (available
+on the command line, and with the commands @code{file}, @code{symbol-file},
+or @code{add-symbol-file}), for more information.
@item file
@code{file} with no argument makes _GDBN__ discard any information it
@code{symbol-file} will not repeat if you press @key{RET} again after
executing it once.
+When _GDBN__ is configured for a particular environment, it will
+understand debugging information in whatever format is the standard
+generated for that environment; you may use either a GNU compiler, or
+other compilers that adhere to the local conventions. Best results are
+usually obtained from GNU compilers; for example, using @code{_GCC__}
+you can generate debugging information for optimized code.
+
On some kinds of object files, the @code{symbol-file} command does not
-actually read the symbol table in full right away. Instead, it scans
+normally read the symbol table in full right away. Instead, it scans
the symbol table quickly to find which source files and which symbols
are present. The details are read later, one source file at a time,
-when they are needed.
+as they are needed.
The purpose of this two-stage reading strategy is to make _GDBN__ start up
-faster. For the most part, it is invisible except for occasional pauses
-while the symbol table details for a particular source file are being
-read. (The @code{set verbose} command can turn these pauses into
-messages if desired. @xref{Messages/Warnings, ,Optional Warnings and
-Messages}.)
+faster. For the most part, it is invisible except for occasional
+pauses while the symbol table details for a particular source file are
+being read. (The @code{set verbose} command can turn these pauses
+into messages if desired. @xref{Messages/Warnings, ,Optional Warnings
+and Messages}.)
When the symbol table is stored in COFF format, @code{symbol-file} does
-read the symbol table data in full right away. We haven't implemented
+read the symbol table data in full right away. We have not implemented
the two-stage strategy for COFF yet.
-When _GDBN__ is configured for a particular environment, it will
-understand debugging information in whatever format is the standard
-generated for that environment; you may use either a GNU compiler, or
-other compilers that adhere to the local conventions. Best results are
-usually obtained from GNU compilers; for example, using @code{_GCC__}
-you can generate debugging information for optimized code.
+@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
+@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
+@kindex readnow
+@cindex reading symbols immediately
+@cindex symbols, reading immediately
+@kindex mapped
+@cindex memory-mapped symbol file
+@cindex saving symbol table
+You can override the _GDBN__ two-stage strategy for reading symbol
+tables by using the @samp{-readnow} option with any of the commands that
+load symbol table information, if you want to be sure _GDBN__ has the
+entire symbol table available.
+
+If memory-mapped files are available on your system through the
+@code{mmap} system call, you can use another option, @samp{-mapped}, to
+cause _GDBN__ to write the symbols for your program into a reusable
+file. Future _GDBN__ debugging sessions will map in symbol information
+from this auxiliary symbol file (if the program hasn't changed), rather
+than spending time reading the symbol table from the executable
+program. Using the @samp{-mapped} option has the same effect as
+starting _GDBN__ with the @samp{-mapped} command-line option.
+
+You can use both options together, to make sure the auxiliary symbol
+file has all the symbol information for your program.
+
+The @code{.syms} file is specific to the host machine on which GDB is run.
+It holds an exact image of GDB's internal symbol table. It cannot be
+shared across multiple host platforms.
+
+The auxiliary symbol file for a program called @var{myprog} is called
+@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer
+than the corresponding executable), _GDBN__ will always attempt to use
+it when you debug @var{myprog}; no special options or commands are
+needed.
+@c FIXME: for now no mention of directories, since this seems to be in
+@c flux. 13mar1992 status is that in theory GDB would look either in
+@c current dir or in same dir as myprog; but issues like competing
+@c GDB's, or clutter in system dirs, mean that in practice right now
+@c only current dir is used. FFish says maybe a special GDB hierarchy
+@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol
+@c files.
@item core-file @r{[} @var{filename} @r{]}
@kindex core
under _GDBN__. So, if you have been running your program and you wish to
debug a core file instead, you must kill the subprocess in which the
program is running. To do this, use the @code{kill} command
-(@pxref{Kill Process}).
+(@pxref{Kill Process, ,Killing the Child Process}).
@item load @var{filename}
@kindex load
_GDBN__.
_fi__(_I960__)
+_if__(_H8__)
+@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,,_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 _GDBN__ on your host (like the
+@code{file} command).
+_fi__(_H8__)
+
@code{load} will not repeat if you press @key{RET} again after using it.
@item add-symbol-file @var{filename} @var{address}
+@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
@kindex add-symbol-file
@cindex dynamic linking
The @code{add-symbol-file} command reads additional symbol table information
@code{add-symbol-file} will not repeat if you press @key{RET} after using it.
+You can use the @samp{-mapped} and @samp{-readnow} options just as with
+the @code{symbol-file} command, to change how _GDBN__ manages the symbol
+tabl einformation for @var{filename}.
+
@item info files
@itemx info target
@kindex info files
@kindex info target
-@code{info files} and @code{info target} are synonymous; both print the
-current targets (@pxref{Targets}), including the names of the executable
-and core dump files currently in use by _GDBN__, and the files from
-which symbols were loaded. The command @code{help targets} lists all
-possible targets rather than current ones.
+@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 _GDBN__, and the files from which symbols were loaded. The command
+@code{help targets} lists all possible targets rather than current
+ones.
@end table
@cindex shared libraries
-_GDBN__ supports the SunOS shared library format. _GDBN__ automatically
-loads symbol definitions from shared libraries when you use the
-@code{run} command, or when you examine a core file. (Before you issue
-the @code{run} command, _GDBN__ won't understand references to a
-function in a shared library, however---unless you are debugging a core
-file).
+_GDBN__ supports SunOS, SVR4, and IBM RS/6000 shared libraries.
+_GDBN__ automatically loads symbol definitions from shared libraries
+when you use the @code{run} command, or when you examine a core file.
+(Before you issue the @code{run} command, _GDBN__ will not understand
+references to a function in a shared library, however---unless you are
+debugging a core file).
@c FIXME: next _GDBN__ release should permit some refs to undef
-@c FIXME...symbols---eg in a break cmd---assuming they're from a shared lib
+@c FIXME...symbols---eg in a break cmd---assuming they are from a shared lib
@table @code
@item info share
@node Symbol Errors, , Files, _GDBN__ Files
@section Errors Reading Symbol Files
-While reading a symbol file, _GDBN__ will occasionally encounter
-problems, such as symbol types it does not recognize, or known bugs in
-compiler output. By default, _GDBN__ does not notify you of such
-problems, since they're relatively common and primarily of interest to
-people debugging compilers. If you are interested in seeing information
+
+While reading a symbol file, _GDBN__ will occasionally encounter problems,
+such as symbol types it does not recognize, or known bugs in compiler
+output. By default, _GDBN__ does not notify you of such problems, since
+they are relatively common and primarily of interest to people
+debugging compilers. If you are interested in seeing information
about ill-constructed symbol tables, you can either ask _GDBN__ to print
only one message about each such type of problem, no matter how many
times the problem occurs; or you can ask _GDBN__ to print more messages,
-to see how many times the problems occur, with the @code{set complaints}
-command (@pxref{Messages/Warnings, ,Optional Warnings and Messages}).
+to see how many times the problems occur, with the @code{set
+complaints} command (@pxref{Messages/Warnings, ,Optional Warnings and
+Messages}).
The messages currently printed, and their meanings, are:
@item info mismatch between compiler and debugger
_GDBN__ could not parse a type specification output by the compiler.
-
@end table
@node Targets, Controlling _GDBN__, _GDBN__ Files, Top
@chapter Specifying a Debugging Target
@cindex debugging target
@kindex target
+
A @dfn{target} is the execution environment occupied by your program.
-Often, _GDBN__ runs in the same host environment as your program you are
-debugging; in that case, the debugging target is specified as a side
-effect when you use the @code{file} or @code{core} commands. When you
-need more flexibility---for example, running _GDBN__ on a physically
-separate host, or controlling a standalone system over a serial port or
-a realtime system over a TCP/IP connection---you can use the
-@code{target} command to specify one of the target types configured for
-_GDBN__ (@pxref{Target Commands}).
+Often, _GDBN__ runs in the same host environment as your program; in
+that case, the debugging target is specified as a side effect when you
+use the @code{file} or @code{core} commands. When you need more
+flexibility---for example, running _GDBN__ on a physically separate
+host, or controlling a standalone system over a serial port or a
+realtime system over a TCP/IP connection---you can use the @code{target}
+command to specify one of the target types configured for _GDBN__
+(@pxref{Target Commands, ,Commands for Managing Targets}).
@menu
* Active Targets:: Active Targets
core file or executable file target are obscured while the process
target is active.
-Use the @code{core-file}, and @code{exec-file} commands to select a new
-core file or executable target (@pxref{Files, ,Commands to Specify Files}). To specify as a target
-a process that's already running, use the @code{attach} command
-(@pxref{Attach, ,Debugging an Already-Running Process}.).
+Use the @code{core-file} and @code{exec-file} commands to select a
+new core file or executable target (@pxref{Files, ,Commands to Specify
+Files}). To specify as a target a process that is already running, use
+the @code{attach} command (@pxref{Attach, ,Debugging an
+Already-Running Process}.).
@node Target Commands, Remote, Active Targets, Targets
@section Commands for Managing Targets
select it.
@end table
-Here are some common targets (available, or not, depending on the _GDBN__
+Here are some common targets (available, or not, depending on the GDB
configuration):
@table @code
@item target remote @var{dev}
@kindex target remote
-Remote serial target in _GDBN__-specific protocol. The argument @var{dev}
+Remote serial target in GDB-specific protocol. The argument @var{dev}
specifies what serial device to use for the connection (e.g.
-@file{/dev/ttya}). @xref{Remote}.
+@file{/dev/ttya}). @xref{Remote, ,Remote Debugging}.
_if__(_AMD29K__)
@item target amd-eb @var{dev} @var{speed} @var{PROG}
@var{dev} is the serial device, as for @code{target remote};
@var{speed} allows you to specify the linespeed; and @var{PROG} is the
name of the program to be debugged, as it appears to DOS on the PC.
-@xref{EB29K Remote}.
+@xref{EB29K Remote, ,GDB with a Remote EB29K}.
_fi__(_AMD29K__)
+_if__(_H8__)
+@item target hms
+@kindex target hms
+A Hitachi H8/300 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,,_GDBN__ and the Hitachi H8/300}.
+
+_fi__(_H8__)
_if__(_I960__)
@item target nindy @var{devicename}
@kindex target nindy
An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
the name of the serial device to use for the connection, e.g.
-@file{/dev/ttya}. @xref{i960-Nindy Remote}.
+@file{/dev/ttya}. @xref{i960-Nindy Remote, ,_GDBN__ with a Remote i960 (Nindy)}.
_fi__(_I960__)
_if__(_VXWORKS__)
@kindex target vxworks
A VxWorks system, attached via TCP/IP. The argument @var{machinename}
is the target system's machine name or IP address.
-@xref{VxWorks Remote}.
+@xref{VxWorks Remote, ,_GDBN__ and VxWorks}.
_fi__(_VXWORKS__)
@end table
@section Remote Debugging
@cindex remote debugging
-_if__(_GENERIC__)
-@menu
-_include__(gdbinv-m.m4)<>_dnl__
-@end menu
-_fi__(_GENERIC__)
-
If you are trying to debug a program running on a machine that cannot run
-_GDBN__ in the usual way, it is often useful to use remote debugging. For
+GDB in the usual way, it is often useful to use remote debugging. For
example, you might use remote debugging on an operating system kernel, or on
a small system which does not have a general purpose operating system
powerful enough to run a full-featured debugger.
-Some configurations of _GDBN__ have special serial or TCP/IP interfaces
+Some configurations of GDB have special serial or TCP/IP interfaces
to make this work with particular debugging targets. In addition,
-_GDBN__ comes with a generic serial protocol (specific to _GDBN__, but
+GDB comes with a generic serial protocol (specific to GDB, but
not specific to any particular target system) which you can use if you
write the remote stubs---the code that will run on the remote system to
-communicate with _GDBN__.
+communicate with GDB.
-To use the _GDBN__ remote serial protocol, the program to be debugged on
+To use the GDB remote serial protocol, the program to be debugged on
the remote machine needs to contain a debugging stub which talks to
-_GDBN__ over the serial line. Several working remote stubs are
-distributed with _GDBN__; see the @file{README} file in the _GDBN__
+GDB over the serial line. Several working remote stubs are
+distributed with GDB; see the @file{README} file in the GDB
distribution for more information.
For details of this communication protocol, see the comments in the
-_GDBN__ source file @file{remote.c}.
+GDB source file @file{remote.c}.
-To start remote debugging, first run _GDBN__ and specify as an executable file
-the program that is running in the remote machine. This tells _GDBN__ how
+To start remote debugging, first run GDB and specify as an executable file
+the program that is running in the remote machine. This tells GDB how
to find your program's symbols and the contents of its pure text. Then
establish communication using the @code{target remote} command with a device
name as an argument. For example:
To resume the remote program and stop debugging it, use the @code{detach}
command.
+@kindex set remotedebug
+@kindex show remotedebug
+@cindex packets, reporting on stdout
+@cindex serial connections, debugging
+If you have trouble with the serial connection, you can use the command
+@code{set remotedebug}. This makes _GDBN__ report on all packets sent
+back and forth across the serial line to the remote machine. The
+packet-debugging information is printed on the _GDBN__ standard output
+stream. @code{set remotedebug off} turns it off, and @code{show
+remotedebug} will show you its current state.
+
Other remote targets may be available in your
-configuration of _GDBN__; use @code{help targets} to list them.
+configuration of GDB; use @code{help targets} to list them.
_if__(_GENERIC__)
-@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.
+_dnl__ Text on starting up GDB in various specific cases; it goes up front
+_dnl__ in manuals configured for any of those particular situations, here
+_dnl__ otherwise.
+@menu
+_include__(gdbinv-m.m4)<>_dnl__
+@end menu
_include__(gdbinv-s.m4)
_fi__(_GENERIC__)
You can alter many aspects of _GDBN__'s interaction with you by using
the @code{set} command. For commands controlling how _GDBN__ displays
-data, @pxref{Print Settings}; other settings are described here.
+data, @pxref{Print Settings, ,Print Settings}; other settings are described here.
@menu
* Prompt:: Prompt
@node Prompt, Editing, Controlling _GDBN__, Controlling _GDBN__
@section Prompt
@cindex prompt
+
_GDBN__ indicates its readiness to read a command by printing a string
called the @dfn{prompt}. This string is normally @samp{(_GDBP__)}. You
can change the prompt string with the @code{set prompt} command. For
@section Command Editing
@cindex readline
@cindex command line editing
+
_GDBN__ reads its input commands via the @dfn{readline} interface. This
GNU library provides consistent behavior for programs which provide a
command line interface to the user. Advantages are @code{emacs}-style
@node History, Screen Size, Editing, Controlling _GDBN__
@section Command History
+
@table @code
@cindex history substitution
@cindex history file
@cindex history expansion
History expansion assigns special meaning to the character @kbd{!}.
@iftex
-(@pxref{Event Designators}.)
+@xref{Event Designators}.
@end iftex
Since @kbd{!} is also the logical not operator in C, history expansion
is off by default. If you decide to enable history expansion with the
These commands display the state of the _GDBN__ history parameters.
@code{show history} by itself displays all four states.
@c @end group
-
@end table
@table @code
@item show commands +
Print ten commands just after the commands last printed.
-
@end table
@node Screen Size, Numbers, History, Controlling _GDBN__
@section Screen Size
@cindex size of screen
@cindex pauses in output
+
Certain commands to _GDBN__ may produce large amounts of information
output to the screen. To help you read all of it, _GDBN__ pauses and
asks you for input at the end of each page of output. Type @key{RET}
@section Numbers
@cindex number representation
@cindex entering numbers
+
You can always enter numbers in octal, decimal, or hexadecimal in _GDBN__ by
the usual conventions: octal numbers begin with @samp{0}, decimal
numbers end with @samp{.}, and hexadecimal numbers begin with @samp{0x}.
@kindex show radix
@item show radix
Display the current default base for numeric input and display.
-
@end table
@node Messages/Warnings, , Numbers, Controlling _GDBN__
@section Optional Warnings and Messages
+
By default, _GDBN__ is silent about its inner workings. If you are running
on a slow machine, you may want to use the @code{set verbose} command.
It will make _GDBN__ tell you when it does a lengthy internal operation, so
-you won't think it has crashed.
+you will not think it has crashed.
-Currently, the messages controlled by @code{set verbose} are those which
-announce that the symbol table for a source file is being read
-(@pxref{Files, ,Commands to Specify Files}, in the description of the command
-@code{symbol-file}).
+Currently, the messages controlled by @code{set verbose} are those
+which announce that the symbol table for a source file is being read
+(@pxref{Files, ,Commands to Specify Files}, in the description of the
+command @code{symbol-file}).
@c The following is the right way to do it, but emacs 18.55 does not support
@c @ref, and neither the emacs lisp manual version of texinfmt or makeinfo
@c is released.
By default, if _GDBN__ encounters bugs in the symbol table of an object
file, it is silent; but if you are debugging a compiler, you may find
-this information useful (@pxref{Symbol Errors}).
+this information useful (@pxref{Symbol Errors, ,Errors Reading Symbol Files}).
@table @code
@kindex set complaints
By default, _GDBN__ is cautious, and asks what sometimes seem to be a
lot of stupid questions to confirm certain commands. For example, if
you try to run a program which is already running:
+
@example
(_GDBP__) run
The program being debugged has been started already.
and keep on running.
_fi__(_VXWORKS__)
If you are running on one of these systems, you can allow _GDBN__ to
-reload the symbols for automatically relinked modules:@refill
+reload the symbols for automatically relinked modules:
+
@table @code
@kindex set symbol-reloading
@item set symbol-reloading on
object file with a particular name is seen again.
@item set symbol-reloading off
-Do Not replace symbol definitions when re-encountering object files of
+Do not replace symbol definitions when re-encountering object files of
the same name. This is the default state; if you are not running on a
system that permits automatically relinking modules, you should leave
@code{symbol-reloading} off, since otherwise _GDBN__ may discard symbols
@chapter Canned Sequences of Commands
Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
-Command Lists}), _GDBN__ provides two ways to store sequences of
-commands for execution as a unit: user-defined commands and command
-files.@refill
+Command Lists}), _GDBN__ provides two ways to store sequences of commands
+for execution as a unit: user-defined commands and command files.
@menu
* Define:: User-Defined Commands
List all user-defined commands, with the first line of the documentation
(if any) for each.
-@item info user
-@itemx info user @var{commandname}
-@kindex info user
+@item show user
+@itemx show user @var{commandname}
+@kindex show user
Display the _GDBN__ commands used to define @var{commandname} (but not its
documentation). If no @var{commandname} is given, display the
definitions for all user-defined commands.
@cindex init file
@cindex @file{_GDBINIT__}
When you start _GDBN__, it automatically executes commands from its
-@dfn{init files}. These are files named @file{_GDBINIT__}. _GDBN__
-reads the init file (if any) in your home directory and then the init
-file (if any) in the current working directory. (The init files are not
-executed if you use the @samp{-nx} option; @pxref{Mode Options}.) You
-can also request the execution of a command file with the @code{source}
-command:
+@dfn{init files}. These are files named @file{_GDBINIT__}. _GDBN__ reads
+the init file (if any) in your home directory and then the init file
+(if any) in the current working directory. (The init files are not
+executed if you use the @samp{-nx} option; @pxref{Mode Options,
+,Choosing Modes}.) You can also request the execution of a command
+file with the @code{source} command:
@table @code
@item source @var{filename}
@kindex echo
@c I do not consider backslash-space a standard C escape sequence
@c because it is not in ANSI.
-Print @var{text}. Nonprinting characters can be included in @var{text}
-using C escape sequences, such as @samp{\n} to print a newline. @b{No
-newline will be printed unless you specify one.} In addition to the
-standard C escape sequences, a backslash followed by a space stands for a
-space. This is useful for outputting a string with spaces at the
-beginning or the end, since leading and trailing spaces are otherwise
-trimmed from all arguments. Thus, to print @samp{@ and foo =@ }, use the
-command @samp{echo \@ and foo = \@ }.
-@c FIXME? '@ ' works in tex and info, but confuses texi2roff[-2].
+Print @var{text}. Nonprinting characters can be included in
+@var{text} using C escape sequences, such as @samp{\n} to print a
+newline. @strong{No newline will be printed unless you specify one.}
+In addition to the standard C escape sequences, a backslash followed
+by a space stands for a space. This is useful for outputting a
+string with spaces at the beginning or the end, since leading and
+trailing spaces are otherwise trimmed from all arguments.
+To print @samp{@w{ }and foo =@w{ }}, use the command
+@samp{echo \@w{ }and foo = \@w{ }}.
A backslash at the end of @var{text} can be used, as in C, to continue
the command onto subsequent lines. For example,
@kindex output
Print the value of @var{expression} and nothing but that value: no
newlines, no @samp{$@var{nn} = }. The value is not entered in the
-value history either. @xref{Expressions} for more information on
+value history either. @xref{Expressions, ,Expressions}, for more information on
expressions.
@item output/@var{fmt} @var{expression}
For example, you can print two values in hex like this:
-@example
+@smallexample
printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
-@end example
+@end smallexample
The only backslash-escape sequences that you can use in the format
string are the simple ones that consist of backslash followed by a
letter.
@end table
+_if__(_LUCID__)
+@node Emacs, Energize, Sequences, Top
+_fi__(_LUCID__)
+_if__(!_LUCID__)
@node Emacs, _GDBN__ Bugs, Sequences, Top
+_fi__(!_LUCID__)
@chapter Using _GDBN__ under GNU Emacs
@cindex emacs
you need to call _GDBN__ by a different name (for example, if you keep
several configurations around, with different names) you can set the
Emacs variable @code{gdb-command-name}; for example,
+
@example
(setq gdb-command-name "mygdb")
@end example
+
@noindent
(preceded by @kbd{ESC ESC}, or typed in the @code{*scratch*} buffer, or
in your @file{.emacs} file) will make Emacs call the program named
@item M-c
Continue execution of your program, like the _GDBN__ @code{continue}
-command.
+command.
@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
@item M-u
Go up the number of frames indicated by the numeric argument
(@pxref{Arguments, , Numeric Arguments, emacs, The GNU Emacs Manual}),
-like the _GDBN__ @code{up} command.
+like the _GDBN__ @code{up} command.
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.@refill
+@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
@item M-d
Go down the number of frames indicated by the numeric argument, like the
-_GDBN__ @code{down} command.
+_GDBN__ @code{down} command.
@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
list. If the list element is a string, the number to be inserted is
formatted using the Emacs function @code{format}; otherwise the number
is passed as an argument to the corresponding list element.
-
@end table
In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
each value is printed in its own window.
@end ignore
+_if__(_LUCID__)
+@node Energize, _GDBN__ Bugs, Emacs, Top
+@chapter Using _GDBN__ with Energize
+
+@cindex Energize
+The Energize Programming System is an integrated development environment
+that includes a point-and-click interface to many programming tools.
+When you use _GDBN__ in this environment, you can use the standard
+Energize graphical interface to drive _GDBN__; you can also, if you
+choose, type _GDBN__ commands as usual in a debugging window. Even if
+you use the graphical interface, the debugging window (which uses Emacs,
+and resembles the standard Emacs interface to _GDBN__) displays the
+equivalent commands, so that the history of your debugging session is
+properly reflected.
+
+When Energize starts up a _GDBN__ session, it uses one of the
+command-line options @samp{-energize} or @samp{-cadillac} (``cadillac''
+is the name of the communications protocol used by the Energize system).
+This option makes _GDBN__ run as one of the tools in the Energize Tool
+Set: it sends all output to the Energize kernel, and accept input from
+it as well.
+
+See the user manual for the Energize Programming System for
+information on how to use the Energize graphical interface and the other
+development tools that Energize integrates with _GDBN__.
+
+@node _GDBN__ Bugs, Renamed Commands, Energize, Top
+_fi__(_LUCID__)
+_if__(!_LUCID__)
@node _GDBN__ Bugs, Renamed Commands, Emacs, Top
+_fi__(!_LUCID__)
@chapter Reporting Bugs in _GDBN__
@cindex Bugs in _GDBN__
@cindex Reporting Bugs in _GDBN__
easiest thing for you to do, and the most helpful.
Keep in mind that the purpose of a bug report is to enable us to fix
-the bug if it is new to us. It isn't as important what happens if
+the bug if it is new to us. It is not as important as what happens if
the bug is already known. Therefore, always write your bug reports on
the assumption that the bug has not been reported previously.
The version of _GDBN__. _GDBN__ announces it if you start with no
arguments; you can also print it at any time using @code{show version}.
-Without this, we won't know whether there is any point in looking for
+Without this, we will not know whether there is any point in looking for
the bug in the current version of _GDBN__.
@item
-A complete input script, and all necessary source files, that will
-reproduce the bug.
+The type of machine you are using, and the operating system name and
+version number.
@item
What compiler (and its version) was used to compile _GDBN__---e.g.
-``_GCC__-1.37.1''.
+``_GCC__-2.0''.
+
+@item
+What compiler (and its version) was used to compile the program you
+are debugging---e.g. ``_GCC__-2.0''.
@item
The command arguments you gave the compiler to compile your example and
observe the bug. For example, did you use @samp{-O}? To guarantee
-you won't omit something important, list them all.
+you will not omit something important, list them all. A copy of the
+Makefile (or the output from make) is sufficient.
If we were to try to guess the arguments, we would probably guess wrong
and then we might not encounter the bug.
@item
-The type of machine you are using, and the operating system name and
-version number.
+A complete input script, and all necessary source files, that will
+reproduce the bug.
@item
A description of what behavior you observe that you believe is
diffs. If you even discuss something in the _GDBN__ source, refer to
it by context, not by line number.
-The line numbers in our development sources won't match those in your
+The line numbers in our development sources will not match those in your
sources. Your line numbers would convey no useful information to us.
-
@end itemize
Here are some things that are not necessary:
Sometimes with a program as complicated as _GDBN__ it is very hard to
construct an example that will make the program follow a certain path
-through the code. If you do not send us the example, we won't be able
-to construct one, so we won't be able to verify that the bug is fixed.
+through the code. If you do not send us the example, we will not be able
+to construct one, so we will not be able to verify that the bug is fixed.
And if we cannot understand what bug you are trying to fix, or why your
-patch should be an improvement, we won't install it. A test case will
+patch should be an improvement, we will not install it. A test case will
help us to understand.
@item
things without first using the debugger to find the facts.
@end itemize
+@c Note: no need to update nodes for rdl-apps.texi since it appears
+@c *only* in the TeX version of the manual.
+@c Note: eventually, make a cross reference to the readline Info nodes.
@iftex
@c appendices describing GNU readline. Distributed with readline code.
@include rluser.texinfo
@include inc-hist.texi
@end iftex
-@node Renamed Commands, Installing _GDBN__, _GDBN__ Bugs, Top
+@node Renamed Commands, Formatting Documentation, _GDBN__ Bugs, Top
@appendix Renamed Commands
-The following commands were renamed in _GDBN__ 4.0, in order to make the
+The following commands were renamed in GDB 4, in order to make the
command set as a whole more consistent and easier to use and remember:
@kindex add-syms
@end tex
@c END TEXI2ROFF-KILL
-@node Installing _GDBN__, Copying, Renamed Commands, Top
-@appendix Installing _GDBN__
-@cindex configuring _GDBN__
+@node Formatting Documentation, Installing GDB, Renamed Commands, Top
+@appendix Formatting the Documentation
+
+@cindex GDB reference card
+@cindex reference card
+The GDB 4 release includes an already-formatted reference card, ready
+for printing on a PostScript or GhostScript printer, in the @file{gdb}
+subdirectory of the main source directory---in
+@file{gdb-_GDB_VN__/gdb/refcard.ps} of the version _GDB_VN__ release. If you have
+a PostScript or GhostScript printer, you can print the reference card
+by just sending @file{refcard.ps} to the printer.
+
+The release also includes the source for the reference card. You
+can format it, using @TeX{}, by typing:
+
+@example
+make refcard.dvi
+@end example
+
+The GDB reference card is designed to print in landscape mode on US
+``letter'' size paper; that is, on a sheet 11 inches wide by 8.5 inches
+high. You will need to specify this form of printing as an option to
+your @sc{dvi} output program.
+
+@cindex documentation
+
+All the documentation for GDB comes as part of the machine-readable
+distribution. The documentation is written in Texinfo format, which is
+a documentation system that uses a single source file to produce both
+on-line information and a printed manual. You can use one of the Info
+formatting commands to create the on-line version of the documentation
+and @TeX{} (or @code{texi2roff}) to typeset the printed version.
+
+GDB includes an already formatted copy of the on-line Info version of
+this manual in the @file{gdb} subdirectory. The main Info file is
+@file{gdb-@var{version-number}/gdb/gdb.info}, and it refers to
+subordinate files matching @samp{gdb.info*} in the same directory. If
+necessary, you can print out these files, or read them with any editor;
+but they are easier to read using the @code{info} subsystem in GNU Emacs
+or the standalone @code{info} program, available as part of the GNU
+Texinfo distribution.
+
+If you want to format these Info files yourself, you need one of the
+Info formatting programs, such as @code{texinfo-format-buffer} or
+@code{makeinfo}.
+
+If you have @code{makeinfo} installed, and are in the top level GDB
+source directory (@file{gdb-_GDB_VN__}, in the case of version _GDB_VN__), you can
+make the Info file by typing:
+
+@example
+cd gdb
+make gdb.info
+@end example
+
+If you want to typeset and print copies of this manual, you need
+@TeX{}, a printing program such as @code{lpr}, and @file{texinfo.tex},
+the Texinfo definitions file.
+
+@TeX{} is typesetting program; it does not print files directly, but
+produces output files called @sc{dvi} files. To print a typeset
+document, you need a program to print @sc{dvi} files. If your system
+has @TeX{} installed, chances are it has such a program. The precise
+command to use depends on your system; @kbd{lpr -d} is common; another
+is @kbd{dvips}. The @sc{dvi} print command may require a file name
+without any extension or a @samp{.dvi} extension.
+
+@TeX{} also requires a macro definitions file called
+@file{texinfo.tex}. This file tells @TeX{} how to typeset a document
+written in Texinfo format. On its own, @TeX{} cannot read, much less
+typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB
+and is located in the @file{gdb-@var{version-number}/texinfo}
+directory.
+
+If you have @TeX{} and a @sc{dvi} printer program installed, you can
+typeset and print this manual. First switch to the the @file{gdb}
+subdirectory of the main source directory (for example, to
+@file{gdb-_GDB_VN__/gdb}) and then type:
+
+@example
+make gdb.dvi
+@end example
+
+@node Installing GDB, Copying, Formatting Documentation, Top
+@appendix Installing GDB
+@cindex configuring GDB
@cindex installation
-_GDBN__ comes with a @code{configure} script that automates the process
-of preparing _GDBN__ for installation; you can then use @code{make} to
-build the @code{_GDBP__} program.
+@iftex
+@c irrelevant in info file; it's as current as the code it lives with.
+@quotation
+@emph{Warning:} These installation instructions are current as of
+GDB version _GDB_VN__. If you're installing a more recent release
+of GDB, we may have improved the installation procedures since
+printing this manual; see the @file{README} file included in your
+release for the most recent instructions.
+@end quotation
+@end iftex
+
+GDB comes with a @code{configure} script that automates the process
+of preparing GDB for installation; you can then use @code{make} to
+build the program.
+
+The GDB distribution includes all the source code you need for GDB in
+a single directory, whose name is usually composed by appending the
+version number to @samp{gdb}.
-The _GDBP__ distribution includes all the source code you need for
-_GDBP__ in a single directory @file{gdb-_GDB_VN__}. That directory in turn
-contains:
+For example, the GDB version _GDB_VN__ distribution is in the @file{gdb-_GDB_VN__}
+directory. That directory contains:
@table @code
@item gdb-_GDB_VN__/configure @r{(and supporting files)}
-script for configuring _GDBN__ and all its supporting libraries.
+script for configuring GDB and all its supporting libraries.
@item gdb-_GDB_VN__/gdb
-the source specific to _GDBN__ itself
+the source specific to GDB itself
@item gdb-_GDB_VN__/bfd
-source for the Binary File Descriptor Library
+source for the Binary File Descriptor library
@item gdb-_GDB_VN__/include
GNU include files
@item gdb-_GDB_VN__/readline
source for the GNU command-line interface
+
+@item gdb-_GDB_VN__/glob
+source for the GNU filename pattern-matching subroutine
+
+@item gdb-_GDB_VN__/mmalloc
+source for the GNU memory-mapped malloc package
@end table
-@noindent
-It is most convenient to run @code{configure} from the @file{gdb-_GDB_VN__}
-directory. The simplest way to configure and build _GDBN__ is the
-following:
+
+The simplest way to configure and build GDB is to run @code{configure}
+from the @file{gdb-@var{version-number}} source directory, which in
+this example is the @file{gdb-_GDB_VN__} directory.
+
+First switch to the @file{gdb-@var{version-number}} source directory
+if you are not already in it; then run @code{configure}. Pass the
+identifier for the platform on which GDB will run as an
+argument.
+
+For example:
+
@example
cd gdb-_GDB_VN__
./configure @var{host}
make
@end example
+
@noindent
-where @var{host} is something like @samp{sun4} or @samp{decstation}, that
-identifies the platform where _GDBN__ will run. This builds the three
-libraries @file{bfd}, @file{readline}, and @file{libiberty}, then
-@code{gdb} itself. The configured source files, and the binaries, are
-left in the corresponding source directories.
+where @var{host} is an identifier such as @samp{sun4} or
+@samp{decstation}, that identifies the platform where GDB will run.
+
+Running @samp{configure @var{host}} followed by @code{make} builds the
+@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty}
+libraries, then @code{gdb} itself. The configured source files, and the
+binaries, are left in the corresponding source directories.
@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
system does not recognize this automatically when you run a different
-shell, you may need to run @code{sh} on it explicitly:
-@samp{sh configure @var{host}}.
+shell, you may need to run @code{sh} on it explicitly:
+
+@example
+sh configure @var{host}
+@end example
+
+If you run @code{configure} from a directory that contains source
+directories for multiple libraries or programs, such as the
+@file{gdb-_GDB_VN__} source directory for version _GDB_VN__, @code{configure}
+creates configuration files for every directory level underneath (unless
+you tell it not to, with the @samp{--norecursion} option).
+
+You can run the @code{configure} script from any of the
+subordinate directories in the GDB distribution, if you only want to
+configure that subdirectory; but be sure to specify a path to it.
+
+For example, with version _GDB_VN__, type the following to configure only
+the @code{bfd} subdirectory:
-You can @emph{run} the @code{configure} script from any of the
-subordinate directories in the _GDBN__ distribution (if you only want to
-configure that subdirectory); but be sure to specify a path to it. For
-example, to configure only the @code{bfd} subdirectory,
@example
@group
cd gdb-_GDB_VN__/bfd
@end group
@end example
-You can install @code{_GDBP__} anywhere; it has no hardwired paths.
-Simply copy @code{gdb/gdb} to the desired directory.
-@comment What about installing the man pages, info files, etc?
-
-However, you should make sure that the shell on your path (named by the
-@samp{SHELL} environment variable) is publicly readable; some systems
-refuse to let _GDBN__ debug child processes whose programs are not
-readable, and _GDBN__ uses the shell to start your program.
+You can install @code{_GDBP__} anywhere; it has no hardwired paths.
+However, you should make sure that the shell on your path (named by
+the @samp{SHELL} environment variable) is publicly readable. Remember
+that GDB uses the shell to start your program---some systems refuse to
+let GDB debug child processes whose programs are not readable.
@menu
-* Subdirectories:: Configuration subdirectories
+* Separate Objdir:: Compiling GDB in another directory
* Config Names:: Specifying names for hosts and targets
* configure Options:: Summary of options for configure
-* Formatting Documentation:: How to format and print _GDBN__ documentation
@end menu
+@node Separate Objdir, Config Names, Installing GDB, Installing GDB
+@section Compiling GDB in Another Directory
+
+If you want to run GDB versions for several host or target machines,
+you'll need a different @code{gdb} compiled for each combination of
+host and target. @code{configure} is designed to make this easy by
+allowing you to generate each configuration in a separate subdirectory,
+rather than in the source directory. If your @code{make} program
+handles the @samp{VPATH} feature (GNU @code{make} does), running
+@code{make} in each of these directories then builds the @code{gdb}
+program specified there.
-@node Subdirectories, Config Names, Installing _GDBN__, Installing _GDBN__
-@section Configuration Subdirectories
-If you want to run _GDBN__ versions for several host or target machines,
-you'll need a different _GDBP__ compiled for each combination of host
-and target. @code{configure} is designed to make this easy by allowing
-you to generate each configuration in a separate subdirectory. If your
-@code{make} program handles the @samp{VPATH} feature (GNU @code{make}
-does), running @code{make} in each of these directories then builds the
-_GDBP__ program specified there.
+To build @code{gdb} in a separate directory, run @code{configure}
+with the @samp{--srcdir} option to specify where to find the source.
+(You'll also need to specify a path to find @code{configure}
+itself from your working directory. If the path to @code{configure}
+would be the same as the argument to @samp{--srcdir}, you can leave out
+the @samp{--srcdir} option; it will be assumed.)
-@code{configure} creates these subdirectories for you when you
-simultaneously specify several configurations; but it is a good habit
-even for a single configuration. You can specify the use of
-subdirectories using the @samp{+subdirs} option (abbreviated
-@samp{+sub}). For example, you can build _GDBN__ this way on a Sun 4 as
-follows:
+For example, with version _GDB_VN__, you can build GDB in a separate
+directory for a Sun 4 like this:
@example
@group
cd gdb-_GDB_VN__
-./configure +sub sun4
-cd H-sun4/T-sun4
+mkdir ../gdb-sun4
+cd ../gdb-sun4
+../gdb-_GDB_VN__/configure sun4
make
@end group
@end example
-When @code{configure} uses subdirectories to build programs or
-libraries, it creates nested directories
-@file{H-@var{host}/T-@var{target}}. @code{configure} uses these two
-directory levels because _GDBN__ can be configured for cross-compiling:
-_GDBN__ can run on one machine (the host) while debugging programs that
-run on another machine (the target). You specify cross-debugging
-targets by giving the @samp{+target=@var{target}} option to
-@code{configure}. Specifying only hosts still gives you two levels of
-subdirectory for each host, with the same configuration suffix on both;
-that is, if you give any number of hosts but no targets, _GDBN__ will be
-configured for native debugging on each host. On the other hand,
-whenever you specify both hosts and targets on the same command line,
-@code{configure} creates all combinations of the hosts and targets you
-list.@refill
-
-If you run @code{configure} from a directory (notably,
-@file{gdb-_GDB_VN__}) that contains source directories for multiple
-libraries or programs, @code{configure} creates the
-@file{H-@var{host}/T-@var{target}} subdirectories in each library or
-program's source directory. For example, typing:
-@example
-cd gdb-_GDB_VN__
-configure sun4 +target=vxworks960
-@end example
-@noindent
-creates the following directories:
-@example
-gdb-_GDB_VN__/H-sun4/T-vxworks960
-gdb-_GDB_VN__/bfd/H-sun4/T-vxworks960
-gdb-_GDB_VN__/gdb/H-sun4/T-vxworks960
-gdb-_GDB_VN__/libiberty/H-sun4/T-vxworks960
-gdb-_GDB_VN__/readline/H-sun4/T-vxworks960
-@end example
+When @code{configure} builds a configuration using a remote source
+directory, it creates a tree for the binaries with the same structure
+(and using the same names) as the tree under the source directory. In
+the example, you'd find the Sun 4 library @file{libiberty.a} in the
+directory @file{gdb-sun4/libiberty}, and GDB itself in
+@file{gdb-sun4/gdb}.
-When you run @code{make} to build a program or library, you must run it
-in a configured directory. If you made a single configuration,
-without subdirectories, run @code{make} in the source directory.
-If you have @file{H-@var{host}/T-@var{target}} subdirectories,
-run @code{make} in those subdirectories.
+One popular reason to build several GDB configurations in separate
+directories is to configure GDB for cross-compiling (where GDB
+runs on one machine---the host---while debugging programs that run on
+another machine---the target). You specify a cross-debugging target by
+giving the @samp{--target=@var{target}} option to @code{configure}.
-The @code{Makefile} generated by @code{configure} for each source
-directory runs recursively, so that typing @code{make} in
-@file{gdb-_GDB_VN__} (or in a
-@file{gdb-_GDB_VN__/H-@var{host}/T-@var{target}} subdirectory) builds
-all the required libraries, then _GDBN__.@refill
+When you run @code{make} to build a program or library, you must run
+it in a configured directory---whatever directory you were in when you
+called @code{configure} (or one of its subdirectories).
-When you have multiple hosts or targets configured, you can run
-@code{make} on them in parallel (for example, if they are NFS-mounted on
-each of the hosts); they will not interfere with each other.
+The @code{Makefile} generated by @code{configure} for each source
+directory also runs recursively. If you type @code{make} in a source
+directory such as @file{gdb-_GDB_VN__} (or in a separate configured
+directory configured with @samp{--srcdir=@var{path}/gdb-_GDB_VN__}), you
+will build all the required libraries, then build GDB.
-You can also use the @samp{+objdir=@var{altroot}} option to have the
-configured files placed in a parallel directory structure rather than
-alongside the source files; @pxref{configure Options}.
+When you have multiple hosts or targets configured in separate
+directories, you can run @code{make} on them in parallel (for example,
+if they are NFS-mounted on each of the hosts); they will not interfere
+with each other.
-@node Config Names, configure Options, Subdirectories, Installing _GDBN__
+@node Config Names, configure Options, Separate Objdir, Installing GDB
@section Specifying Names for Hosts and Targets
The specifications used for hosts and targets in the @code{configure}
script are based on a three-part naming scheme, but some short predefined
aliases are also supported. The full naming scheme encodes three pieces
of information in the following pattern:
+
@example
@var{architecture}-@var{vendor}-@var{os}
@end example
For example, you can use the alias @code{sun4} as a @var{host} argument
-or in a @code{+target=@var{target}} option, but the equivalent full name
+or in a @code{--target=@var{target}} option, but the equivalent full name
is @samp{sparc-sun-sunos4}.
-The following table shows all the architectures, hosts, and OS prefixes
-that @code{configure} recognizes in _GDBN__ _GDB_VN__. Entries in the ``OS
-prefix'' column ending in a @samp{*} may be followed by a release number.
-
-@c TEXI2ROFF-KILL
-@ifinfo
-@c END TEXI2ROFF-KILL
-@example
-
-ARCHITECTURE VENDOR OS prefix
-@c TEXI2ROFF-KILL
-------------+--------------------------+---------------------------
-@c END TEXI2ROFF-KILL
- | |
- 580 | altos hp | aix* msdos*
- a29k | amd ibm | amigados newsos*
- alliant | amdahl intel | aout nindy*
- arm | aout isi | bout osf*
- c1 | apollo little | bsd* sco*
- c2 | att mips | coff sunos*
- cray2 | bcs motorola | ctix* svr4
- h8300 | bout ncr | dgux* sym*
- i386 | bull next | dynix* sysv*
- i860 | cbm nyu | ebmon ultrix*
- i960 | coff sco | esix* unicos*
- m68000 | convergent sequent | hds unos*
- m68k | convex sgi | hpux* uts
- m88k | cray sony | irix* v88r*
- mips | dec sun | isc* vms*
- ns32k | encore unicom | kern vxworks*
- pyramid | gould utek | mach*
- romp | hitachi wrs |
- rs6000 | |
- sparc | |
- tahoe | |
- tron | |
- vax | |
- xmp | |
- ymp | |
-@end example
-@c TEXI2ROFF-KILL
-@end ifinfo
-@tex
-%\vskip\parskip
-\vskip \baselineskip
-\hfil\vbox{\offinterlineskip
-\halign{\strut\tt #\hfil\ &\vrule#&\strut\ \tt #\hfil\ &\strut\ \tt #\hfil
-\ &\vrule#&\strut\ \tt #\hfil\ &\strut\ \tt #\hfil \cr
-{\bf Architecture} &&{\bf Vendor} &&&{\bf OS prefix}\cr
-\multispan7\hrulefill\cr
- 580 && altos & hp && aix* & msdos* \cr
- a29k && amd & ibm && amigados & newsos* \cr
- alliant && amdahl & intel && aout & nindy* \cr
- arm && aout & isi && bout & osf* \cr
- c1 && apollo & little && bsd* & sco* \cr
- c2 && att & mips && coff & sunos* \cr
- cray2 && bcs & motorola && ctix* & svr4 \cr
- h8300 && bout & ncr && dgux* & sym* \cr
- i386 && bull & next && dynix* & sysv* \cr
- i860 && cbm & nyu && ebmon & ultrix* \cr
- i960 && coff & sco && esix* & unicos* \cr
- m68000 && convergent& sequent && hds & unos* \cr
- m68k && convex & sgi && hpux* & uts \cr
- m88k && cray & sony && irix* & v88r* \cr
- mips && dec & sun && isc* & vms* \cr
- ns32k && encore & unicom && kern & vxworks* \cr
- pyramid && gould & utek && mach* & \cr
- romp && hitachi & wrs && & \cr
- rs6000 && & && & \cr
- sparc && & && & \cr
- tahoe && & && & \cr
- tron && & && & \cr
- vax && & && & \cr
- xmp && & && & \cr
- ymp && & && & \cr
-}\hfil}
-@end tex
-@c END TEXI2ROFF-KILL
-@quotation
-@emph{Warning:} @code{configure} can represent a very large number of
-combinations of architecture, vendor, and OS. There is by no means
-support available for all possible combinations!
-@end quotation
-
-The @code{configure} script accompanying _GDBN__ _GDB_VN__ does not provide
+The @code{configure} script accompanying GDB does not provide
any query facility to list all supported host and target names or
aliases. @code{configure} calls the Bourne shell script
@code{config.sub} to map abbreviations to full names; you can read the
script, if you wish, or you can use it to test your guesses on
abbreviations---for example:
+
@example
% sh config.sub sun4
-sparc-sun-sunos4
+sparc-sun-sunos411
% sh config.sub sun3
-m68k-sun-sunos4
+m68k-sun-sunos411
% sh config.sub decstation
-mips-dec-ultrix
+mips-dec-ultrix42
% sh config.sub hp300bsd
m68k-hp-bsd
% sh config.sub i386v
-i386-none-sysv
-% sh config.sub i486v
-*** Configuration "i486v" not recognized
+i386-unknown-sysv
+% sh config.sub i786v
+Invalid configuration `i786v': machine `i786v' not recognized
@end example
+
@noindent
-@code{config.sub} is also distributed in the directory @file{gdb-_GDB_VN__}.
+@code{config.sub} is also distributed in the GDB source
+directory (@file{gdb-_GDB_VN__}, for version _GDB_VN__).
-@node configure Options, Formatting Documentation, Config Names, Installing _GDBN__
+@node configure Options, , Config Names, Installing GDB
@section @code{configure} Options
Here is a summary of all the @code{configure} options and arguments that
-you might use for building _GDBN__:
+you might use for building GDB:
@example
-configure @r{[}+destdir=@var{dir}@r{]} @r{[}+subdirs@r{]}
- @r{[}+objdir=@var{altroot}@r{]} @r{[}+norecursion@r{]} @r{[}+rm@r{]}
- @r{[}+target=@var{target}@dots{}@r{]} @var{host}@dots{}
+configure @r{[}--srcdir=@var{path}@r{]}
+ @r{[}--norecursion@r{]} @r{[}--rm@r{]}
+ @r{[}--target=@var{target}@r{]} @var{host}
@end example
+
@noindent
-You may introduce options with the character @samp{-} rather than
-@samp{+} if you prefer; but you may abbreviate option names if you use
-@samp{+}.
+You may introduce options with a single @samp{-} rather than
+@samp{--} if you prefer; but you may abbreviate option names if you use
+@samp{--}.
@table @code
-@item +destdir=@var{dir}
-@var{dir} is an installation directory @emph{path prefix}. After you
-configure with this option, @code{make install} will install _GDBN__ as
-@file{@var{dir}/bin/_GDBP__}, and the libraries in @file{@var{dir}/lib}.
-If you specify @samp{+destdir=/usr/local}, for example, @code{make
-install} creates @file{/usr/local/bin/gdb}.@refill
-
-@item +subdirs
-Write configuration specific files in subdirectories of the form
-@example
-H-@var{host}/T-@var{target}
-@end example
-@noindent
-(and configure the @code{Makefile} to generate object code in
-subdirectories of this form as well). Without this option, if you
-specify only one configuration for _GDBN__, @code{configure} will use
-the same directory for source, configured files, and binaries. This
-option is used automatically if you specify more than one @var{host} or
-more than one @samp{+target=@var{target}} option on the @code{configure}
-command line.
-
-@item +norecursion
-Configure only the directory where @code{configure} is executed; do not
+@item --srcdir=@var{path}
+@strong{Warning: using this option requires GNU @code{make}, or another
+@code{make} that implements the @code{VPATH} feature.}@*
+Use this option to make configurations in directories separate from the
+GDB source directories. Among other things, you can use this to
+build (or maintain) several configurations simultaneously, in separate
+directories. @code{configure} writes configuration specific files in
+the current directory, but arranges for them to use the source in the
+directory @var{path}. @code{configure} will create directories under
+the working directory in parallel to the source directories below
+@var{path}.
+
+@item --norecursion
+Configure only the directory level where @code{configure} is executed; do not
propagate configuration to subdirectories.
-@item +objdir=@var{altroot}
-@var{altroot} is an alternative directory used as the root for
-configured files. @code{configure} will create directories under
-@var{altroot} in parallel to the source directories. If you use
-@samp{+objdir=@var{altroot}} with @samp{+subdirs}, @code{configure} also
-builds the @samp{H-@var{host}/T-@var{target}} subdirectories in the
-directory tree rooted in @var{altroot}.
-
-
-@item +rm
+@item --rm
Remove the configuration that the other arguments specify.
@c This does not work (yet if ever). FIXME.
-@c @item +parse=@var{lang} @dots{}
-@c Configure the _GDBN__ expression parser to parse the listed languages.
-@c @samp{all} configures _GDBN__ for all supported languages. To get a
+@c @item --parse=@var{lang} @dots{}
+@c Configure the GDB expression parser to parse the listed languages.
+@c @samp{all} configures GDB for all supported languages. To get a
@c list of all supported languages, omit the argument. Without this
-@c option, _GDBN__ is configured to parse all supported languages.
+@c option, GDB is configured to parse all supported languages.
-@item +target=@var{target} @dots{}
-Configure _GDBN__ for cross-debugging programs running on each specified
-@var{target}. You may specify as many @samp{+target} options as you
-wish. Without this option, _GDBN__ is configured to debug programs that
-run on the same machine (@var{host}) as _GDBN__ itself.
+@item --target=@var{target}
+Configure GDB for cross-debugging programs running on the specified
+@var{target}. Without this option, GDB is configured to debug
+programs that run on the same machine (@var{host}) as GDB itself.
There is no convenient way to generate a list of all available targets.
@item @var{host} @dots{}
-Configure _GDBN__ to run on each specified @var{host}. You may specify as
-many host names as you wish.
+Configure GDB to run on the specified @var{host}.
There is no convenient way to generate a list of all available hosts.
@end table
@noindent
@code{configure} accepts other options, for compatibility with
configuring other GNU tools recursively; but these are the only
-options that affect _GDBN__ or its supporting libraries.
-
-@node Formatting Documentation, , configure Options, Installing _GDBN__
-@section Formatting the Documentation
-
-@cindex _GDBN__ reference card
-@cindex reference card
-The _GDBN__ _GDB_VN__ release includes an already-formatted reference card,
-ready for printing on a PostScript printer, as @file{gdb-_GDB_VN__/gdb/refcard.ps}.
-It uses the most common PostScript fonts: the Times family, Courier, and
-Symbol. If you have a PostScript printer, you can print the reference
-card by just sending @file{refcard.ps} to the printer.
-
-The release also includes the online Info version of this manual already
-formatted: the main Info file is @file{gdb-_GDB_VN__/gdb/gdb.info}, and it
-refers to subordinate files matching @samp{gdb.info*} in the same
-directory.
-
-If you want to make these Info files yourself from the _GDBN__ manual's
-source, you need the GNU @code{makeinfo} program. Once you have it, you
-can type
-@example
-cd gdb-_GDB_VN__/gdb
-make gdb.info
-@end example
-@noindent
-to make the Info file.
-
-If you want to format and print copies of the manual, you need several
-things:
-@itemize @bullet
-@item
-@TeX{}, the public domain typesetting program written by Donald Knuth,
-must be installed on your system and available through your execution
-path.
-@item
-@file{gdb-_GDB_VN__/texinfo}: @TeX{} macros defining the GNU
-Documentation Format.
-@item
-@emph{A @sc{dvi} output program.} @TeX{} does not actually make marks on
-paper; it produces output files called @sc{dvi} files. If your system
-has @TeX{} installed, chances are it has a program for printing out
-these files; one popular example is @code{dvips}, which can print
-@sc{dvi} files on PostScript printers.
-@end itemize
-@noindent
-Once you have these things, you can type
-@example
-cd gdb-_GDB_VN__/gdb
-make gdb.dvi
-@end example
-@noindent
-to format the text of this manual, and print it with the usual output
-method for @TeX{} @sc{dvi} files at your site.
-
-If you want to print the reference card, but do not have a PostScript
-printer, or you want to use Computer Modern fonts instead,
-you can still print it if you have @TeX{}. Format the reference card by typing
-@example
-cd gdb-_GDB_VN__/gdb
-make refcard.dvi
-@end example
-@noindent
+options that affect GDB or its supporting libraries.
-The _GDBN__ reference card is designed to print in landscape mode on US
-``letter'' size paper; that is, on a sheet 11 inches wide by 8.5 inches
-high. You will need to specify this form of printing as an option to
-your @sc{dvi} output program.
-
-
-@node Copying, Index, Installing _GDBN__, Top
+@node Copying, Index, Installing GDB, Top
@unnumbered GNU GENERAL PUBLIC LICENSE
@center Version 2, June 1991
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
-@alphaenumerate
+@enumerate a
@item
You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.
License. (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
-@end alphaenumerate
+@end enumerate
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Program,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:
-@alphaenumerate
+@enumerate a
@item
Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
-@end alphaenumerate
+@end enumerate
The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
school, if any, to sign a ``copyright disclaimer'' for the program, if
necessary. Here is a sample; alter the names:
-@smallexample
-Yoyodyne, Inc., hereby disclaims all copyright interest in
-the program `Gnomovision' (which makes passes at compilers)
-written by James Hacker.
+@example
+Yoyodyne, Inc., hereby disclaims all copyright
+interest in the program `Gnomovision'
+(which makes passes at compilers) written
+by James Hacker.
@var{signature of Ty Coon}, 1 April 1989
Ty Coon, President of Vice
-@end smallexample
+@end example
This General Public License does not permit incorporating your program into
proprietary programs. If your program is a subroutine library, you may
library. If this is what you want to do, use the GNU Library General
Public License instead of this License.
-
@node Index, , Copying, Top
@unnumbered Index
projects / binutils.git / blobdiff