@c %**start of header
@setfilename _GDBP__.info
_if__(_GENERIC__)
-@settitle Using _GDBN__ (v4)
+@settitle _GDBN__, The GNU Debugger
_fi__(_GENERIC__)
_if__(!_GENERIC__)
-@settitle Using _GDBN__ v4 (_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)
This file documents the GNU debugger _GDBN__.
@c !!set edition, date, version
-This is Edition 4.01, January 1992,
+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 1992 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
@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.01, for _GDBN__ version _GDB_VN__
-@subtitle January 1992
+@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
}
This file describes _GDBN__, the GNU symbolic debugger.
@c !!set edition, date, version
-This is Edition 4.01, January 1992, 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
-* Sample Session:: A Sample _GDBN__ session
+* 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
* Running:: Running programs under _GDBN__
* 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
@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 (all releases of _GDBN__ 4); 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.
+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.
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
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
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)
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__
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 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:
+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:
@example
_GDBP__ @var{program}
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__)
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__
@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
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
* 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
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
with the @code{SHELL} environment variable. @xref{Arguments, ,Your
Program's Arguments}.
-@item The @i{environment.}
+@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}.
-@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
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
(@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
any other breakpoint: you enable, disable, and delete both breakpoints
and watchpoints using the same commands.
-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
+@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.
@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}.
+listed (@pxref{Memory, ,Examining Memory}).
@end table
_GDBN__ allows you to set any number of breakpoints at the same place in
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
@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
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, ,Continuing and Stepping}.)
+your other breakpoints; see @ref{Continuing and Stepping, ,Continuing and Stepping}.)
@node Conditions, Break Commands, Disabling, Breakpoints
@subsection Break Conditions
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
@c FIXME: "cannot insert breakpoints" error, v unclear.
@c Q in pending mail to Gilmore. ---pesch@cygnus.com, 26mar91
@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,
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.
@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
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
@smallexample
@group
-$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, meat \
-= 0x54 "Pork"@}
+$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \
+meat = 0x54 "Pork"@}
@end group
@end smallexample
_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
@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{++}.
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
@itemx show print vtbl
Control the format for printing virtual function tables.
@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
@subsubsection The scope operators @code{::} and @code{.}
@cindex scope
@kindex .
-@kindex colon, doubled as scope operator
+@cindex colon, doubled as scope operator
@ifinfo
@kindex colon-colon
@c Info cannot handoe :: but TeX can.
@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
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
has on both executable file and the symbol table.
@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,
as they are needed.
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
_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
@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__ will not 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 are from a shared lib
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, ,Remote Debugging}.
@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
@cindex remote debugging
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__)
_dnl__ Text on starting up GDB in various specific cases; it goes up front
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.
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
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__
@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__-1.37.1''.
+are debugging---e.g. ``_GCC__-2.0''.
@item
The command arguments you gave the compiler to compile your example and
@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, 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
-The _GDBN__ distribution includes all the source code you need for _GDBN__ in
+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}.
-For example, the _GDBN__ version _GDB_VN__ distribution is in the @file{gdb-_GDB_VN__}
+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
-The simplest way to configure and build _GDBN__ is to run @code{configure}
+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 _GDBN__ will run as an
+identifier for the platform on which GDB will run as an
argument.
For example:
@noindent
where @var{host} is an identifier such as @samp{sun4} or
-@samp{decstation}, that identifies the platform where _GDBN__ will run.
+@samp{decstation}, that identifies the platform where GDB will run.
-This @code{configure} command 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.
+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
sh configure @var{host}
@end example
-You can @emph{run} the @code{configure} script from any of the
-subordinate directories in the _GDBN__ distribution, if you only want to
+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
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 _GDBN__ uses the shell to start your program---some systems refuse to
-let _GDBN__ debug child processes whose programs are not readable.
+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 Subdirectories, Config Names, Installing _GDBN__, Installing _GDBN__
-@section Configuration Subdirectories
+@node Separate Objdir, Config Names, Installing GDB, Installing GDB
+@section Compiling GDB in Another Directory
-If you want to run _GDBN__ versions for several host or target machines,
-you'll need a different @code{_GDBP__} compiled for each combination of
+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. 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{_GDBP__} program specified there.
-
-@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, with version _GDB_VN__, you can build _GDBN__ on a
-Sun 4 like this:
+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.
+
+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.)
+
+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.
+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}.
-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 the @file{H-@var{host}/T-@var{target}} subdirectories in each
-library or program's source directory.
-
-For example, with version _GDB_VN__, 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
+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}.
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.
+it in a configured directory---whatever directory you were in when you
+called @code{configure} (or one of its subdirectories).
The @code{Makefile} generated by @code{configure} for each source
-directory runs recursively. If you type @code{make} in a source
-directory such as @file{gdb-_GDB_VN__} (or in a subdirectory, such as
-@file{gdb-_GDB_VN__/H-@var{host}/T-@var{target}}), you will build all the
-required libraries, then build _GDBN__.
-
-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.
+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,
-,@code{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}
@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__ version _GDB_VN__. Entries
-in the ``OS prefix'' column ending in a @samp{*} may be followed by a
-release number.
-
-@c FIXME! Update for gdb 4.4
-@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__ 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
@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 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}.
-
-@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
-
-All the documentation for _GDBN__, including this manual, comes as part of
-the 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.
-
-_GDBN__ 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 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 _GDBN__
-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 _GDBN__
-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
-
-@cindex _GDBN__ reference card
-@cindex reference card
-In addition to the manual, the _GDBN__ 4 release includes a three-column
-reference card. Format the _GDBN__ reference card by typing:
-
-@example
-make refcard.dvi
-@end example
-
-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.
-
-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-4.2/gdb/refcard.ps} of the version 4.2 release. If you have
-a PostScript or GhostScript printer, you can print the reference card
-by just sending @file{refcard.ps} to the printer.
+options that affect GDB or its supporting libraries.
-@node Copying, Index, Installing _GDBN__, Top
+@node Copying, Index, Installing GDB, Top
@unnumbered GNU GENERAL PUBLIC LICENSE
@center Version 2, June 1991
projects / deliverable / binutils-gdb.git / blobdiff