Commit: fe3f5fc8280c8697ec793b7090ae2845abf570f5 - binutils_os216 (git)

GNU Binutils with patches for OS216

Commit MetaInfo

• Revision: fe3f5fc8280c8697ec793b7090ae2845abf570f5 (tree)
• Zeit: 1991-03-30 11:13:24
• Autor: Roland Pesch <pesch@cygn...>
• Commiter: Roland Pesch

Log Message

Restructured manual; introduced introductory sample session.

Ändern Zusammenfassung

• modified: gdb/doc/gdb.texinfo

Diff

--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -8,17 +8,18 @@
 @c _HOST__ architectures (and you can of course get the full source,
 @c with all configurations, from wherever you got this).
 _if__(0)
+_0__
 
 THIS IS THE FULL SOURCE.  The full source needs to be run through m4
 before either tex- or info- formatting: for example,
-    m4 pretex.m4 none.m4 m680x0.m4 as.texinfo >as-680x0.texinfo
+    m4 pretex.m4 none.m4 m680x0.m4 gdb.texinfo >gdb-680x0.texinfo
 will produce (assuming your path finds either GNU or SysV m4; Berkeley
 won't do) a file suitable for formatting.  See the text in "pretex.m4"
 for a fuller explanation (and the macro definitions).
-
+_1__
 _fi__(0)
 @c
-@synindex ky cp
+@syncodeindex ky cp
 @c FOR UPDATES LEADING TO THIS DRAFT, GDB CHANGELOG CONSULTED BETWEEN:
 @c Tue Feb 26 01:47:07 1991  Cygnus John Gilmore  (cygnus at yuba)
 @c Sat Dec 22 02:51:40 1990  John Gilmore  (gnu at cygint)
@@ -220,14 +221,176 @@ HPPA architecture support.
 
 @end itemize
 
-@node Invocation, User Interface, New Features, Top
-@chapter Starting _GDBN__
+@node Sample Session,,,
+@chapter A Sample _GDB__ Session
+
+You can use this manual at your leisure to read all about _GDBN__.
+However, a handful of commands are enough to get started using the
+debugger.  This chapter illustrates these commands.
+
+In this sample session, we emphasize user input like this: @var{input},
+to make it easier to pick out from the surrounding output.
+
+We'll be using _GDBN__ to inspect GNU @code{m4} (a generic macro
+processor).
+
+_0__@smallexample
+$ @var{cd gm4/common}
+
+$ @var{_GDBP__ m4}
+Reading symbol data from m4...done.
+@end smallexample
+
+@noindent
+_GDBN__ only reads enough symbol data to know where to find the rest
+when needed; as a result, the first prompt comes up very quickly.
+
+@smallexample
+(_GDBP__) @var{break m4_changequote}
+Breakpoint 1 at 0x59d4: file builtin.c, line 812.
+@end smallexample
+
+@noindent 
+We've chosen to see how the @code{m4} builtin @samp{changequote}
+works.  We know the relevant subroutine is @samp{m4_changequote} (from
+inspecting the source), so we set a breakpoint there.
+
+@smallexample
+(_GDBP__) @var{run}
+Starting program: /s1/gnu/src/gm4/common/m4 
+@var{`usual' quotes <not these>}
+usual quotes <not these>
+@end smallexample
+
+@noindent
+Now we've started @code{m4} running under _GDBN__ control; while we don't touch
+the @samp{m4_changequote} subroutine, the program runs as usual. 
+
+@smallexample
+@var{changequote(<,>)}
+
+Breakpoint 1, m4_changequote (argc=3, argv=0x2b958) at builtin.c:812
+812	    if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3))
+@end smallexample
+@noindent
+Once we've encountered the breakpoint, _GDBN__ suspends execution
+of our program, displaying information about where it stopped.
+
+@smallexample
+(_GDBP__) @var{s}
+bad_argc (name=0xf833cfb4<Address 0xf833cfb4 out of 
+    bounds>, argc=3, min=1, max=3) at builtin.c:230
+230	    if (min > 0 && argc < min) @{
+@end smallexample
+@noindent
+We single-stepped with the command @samp{s}; since there was a subroutine
+call, we've stopped in the first line of that subroutine, not in the next line
+of @code{m4_changequote}.  
+
+The command @samp{next} would have taken us to the next line of the same
+subroutine.  Now that we've stopped deeper in the stack, we can use the
+@samp{backtrace} command (which can also be spelled @samp{bt}) to get
+information about where we are.
+
+@smallexample
+(_GDBP__) @var{bt}
+#0  bad_argc (name=0xf833cfb4<Address 0xf833cfb4 out of bounds>, argc=3, 
+    min=1, max=3) at builtin.c:230
+#1  0x59ec in m4_changequote (argc=3, argv=0x2b958) at builtin.c:812
+#2  0x6e38 in expand_macro (sym=0x2b060) at macro.c:242
+#3  0x6840 in expand_token (obs=0x0, t=176224, td=0xf7fffb08) at macro.c:71
+#4  0x6794 in expand_input () at macro.c:40
+#5  0x28dc in main (argc=0, argv=0xf7fffbf8) at m4.c:174
+@end smallexample
+
+@noindent
+We'll tell _GDBN__ to finish execution of this subroutine, to get back
+to @code{m4_changequote}.
+
+@smallexample
+(_GDBP__) @var{finish}
+Run till exit from #0  bad_argc (name=0xf833cfb4<Address 0xf833cfb4 out of 
+    bounds>, argc=3, min=1, max=3) at builtin.c:230
+0x59ec in m4_changequote (argc=3, argv=0x2b958) at builtin.c:812
+812	    if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3))
+Value returned is $1 = false
+(_GDBP__) @var{s}
+815	    lquote = (argc >= 2) ? TOKEN_DATA_TEXT(argv[1])[0] : DEF_LQUOTE;
+(_GDBP__) @var{whatis lquote}
+type = char
+(_GDBP__) @var{p lquote}
+$2 = 96 '`'
+@end smallexample
+
+@noindent
+When we stepped to another line, @code{m4} was about to set a variable
+@samp{lquote}; we inspected its type with @samp{whatis} and its value
+with @samp{p} (the @samp{print} command).  We can see some context by
+displaying the surrounding source code, with the @samp{l} (@code{list})
+command. 
+
+@smallexample
+(_GDBP__) @var{l}
+810	    token_data **argv;
+811	@{
+812	    if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3))
+813		return;
+814	
+815	    lquote = (argc >= 2) ? TOKEN_DATA_TEXT(argv[1])[0] : DEF_LQUOTE;
+816	    rquote = (argc >= 3) ? TOKEN_DATA_TEXT(argv[2])[0] : DEF_RQUOTE;
+817	@}
+818	
+819	/* 
+(_GDBP__) @var{s}
+816	    rquote = (argc >= 3) ? TOKEN_DATA_TEXT(argv[2])[0] : DEF_RQUOTE;
+(_GDBP__) @var{s}
+817	@}
+(_GDBP__) @var{p lquote}
+$3 = 60 '<'
+(_GDBP__) @var{p rquote}
+$4 = 62 '>'
+@end smallexample
+
+@noindent
+We proceeded past another line with @samp{s}, and inspected the new
+values of @code{m4}'s internal variables @code{rquote} and
+@code{lquote}.
+
+Since we're done with our inspection of this subroutine, we'll tell
+_GDBN__ to allow @code{m4} to continue running, with the @samp{c}
+(@code{continue}) command:
+
+@smallexample
+(_GDBP__) @var{c}
+Continuing.
+
+@var{`usual' quotes <not these>}
+`usual' quotes not these
+
+Program exited normally.
+(_GDBP__) @var{quit}
+
+$ 
+_1__@end smallexample
+
+@noindent 
+Finally, when we ended the @code{m4} run, _GDBN__ told us
+``@code{Program exited normally.}'' We ended our _GDBN__ session with
+the _GDBN__ @samp{quit} command.
+
+
+@node Starting and Stopping,,,
+@chapter Starting and Stopping
+
+@node Starting _GDBN__,,,
+@section Starting _GDBN__
 
 _GDBN__ is invoked with the shell command @samp{_GDBP__}.  Once started, it reads
 commands from the terminal until you tell it to exit.
 
-The most usual way to start _GDBN__ is with one argument or two, specifying
-an executable program as the argument:
+You can start by just calling @samp{_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__ program
 @end example
@@ -245,7 +408,7 @@ in sequential order.  The order makes a difference when the
 @samp{-x} option is used.  
 
 @node File Options, Mode Options, Invocation, Invocation
-@section Options and Arguments to Choose Files
+@subsection Options and Arguments to Choose Files
 
 As shown above, any arguments other than options specify an executable
 file and core file; that is, the first argument encountered with no
@@ -275,8 +438,8 @@ Execute _GDBN__ commands from file @var{file}.  @xref{Command Files}.
 Add @var{directory} to the path to search for source files.
 @end table
 
-@node Mode Options, Remote i960-Nindy, File Options, Invocation
-@section Options to Choose Modes
+@node Mode Options, , , 
+@subsection Options to Choose Modes
 
 @table @code
 @item -nx
@@ -323,7 +486,7 @@ _GDBN__ for remote debugging.
 
 _if__(_I960__)
 @node i960-Nindy Remote,,,
-@section _GDBN__ with a Remote Intel 960 (Nindy)
+@subsection _GDBN__ with a Remote Intel 960 (Nindy)
 
 ``Nindy'' is the name of a Rom Monitor program for Intel 960 target
 systems.  When _GDBN__ is configured to control a remote Intel 960 using
@@ -341,7 +504,7 @@ By using the @samp{target} command at any point during your _GDBN__ session.
 @end itemize
 
 @node Nindy Startup,,,
-@subsection Startup with Nindy
+@subsubsection Startup with Nindy
 
 The command-line options for Nindy are detailed below.  If you simply
 start @code{_GDBP__} without using options to specify a serial port, you are
@@ -355,7 +518,7 @@ responding to the prompt with an empty line.  If you do this, and later
 wish to attach to Nindy, use @samp{target} (@pxref{Target Commands}). 
 
 @node Nindy Options,,,
-@subsection Options for Nindy
+@subsubsection Options for Nindy
 
 These are the startup options for beginning your _GDBN__ session with a
 Nindy-960 board attached:
@@ -402,7 +565,7 @@ _fi__(_I960__)
 
 _if__(_AMD29K__)
 @node EB29K Remote,,,
-@section Starting _GDBN__ with a Remote EB29K
+@subsection _GDBN__ with a Remote EB29K
 
 @cindex EB29K board
 @cindex running 29K programs
@@ -415,12 +578,12 @@ you've hooked the cable between the PC's @samp{COM1} port and
 @samp{/dev/ttya} on the Unix system.
 
 @node Comms (EB29K),,,
-@subsection Communications Setup
+@subsubsection Communications Setup
 The next step is to set up the PC's port, by doing something like the
 following in DOS on the PC:
-@example
+_0__@example
 C:\> MODE com1:9600,n,8,1,none
-@end example
+_1__@end example
 @noindent
 This example---run on an MS DOS 4.0 system---sets the PC port to 9600
 bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
@@ -431,9 +594,9 @@ end of the connection as well.
 
 To give control of the PC to the Unix side of the serial line, type
 the following at the DOS console:
-@example
+_0__@example
 C:\> CTTY com1
-@end example
+_1__@end example
 @noindent
 (Later, if you wish to return control to the DOS console, you can use
 the command @samp{CTTY con}---but you must send it over the device that
@@ -472,7 +635,7 @@ start the PC program @samp{EBMON} (an EB29K control program supplied
 with your board by AMD).  You should see an initial display from
 @code{EBMON} similar to the one in our example, ending with the
 @code{EBMON} prompt @samp{#}---
-@example
+_0__@example
 C:\> g:
 
 G:\> CD \usr\joe\work29k
@@ -501,7 +664,7 @@ Am29027 Available     = No
 Byte Write Available  = Yes
 
 # ~.
-@end example
+_1__@end example
 
 Then exit the @code{cu} or @code{tip} program (done in the example by
 typing @code{~.} at the @code{EBMON} prompt).  @code{EBMON} will keep
@@ -516,8 +679,8 @@ other way---perhaps floppy-disk transfer---of getting the 29K program
 from the Unix system to the PC; _GDBN__ will @emph{not} download it over the
 serial line.
 
-@node _GDBP__-EB29K
-@subsection EB29K cross-debugging
+@node _GDBP__-EB29K,,,
+@subsubsection EB29K cross-debugging
 Finally, @code{cd} to the directory containing an image of your 29K
 program on the Unix system, and start _GDBN__---specifying as argument the
 name of your 29K program:
@@ -558,7 +721,7 @@ Type @samp{CTTY con} to return command input to the main DOS console,
 and type @samp{~.} to leave @code{tip} or @code{cu}.
 
 @node Remote Log,  , Remote Commands, Remote
-@subsection Remote Log
+@subsubsection Remote Log
 @kindex eb.log
 @cindex log file for EB29K
 The @samp{target amd-eb} command creates a file @file{eb.log} in the
@@ -569,9 +732,54 @@ another window often helps to debug trouble with @code{EBMON}, or
 unexpected events on the PC side of the connection.
 _fi__(_AMD29K__)
 
-@node User Interface, Files, Invocation, Top
-@chapter _GDBN__ Commands and Displays
+@node Stopping _GDBN__,,,
+@section Stopping _GDBN__
+@cindex exiting _GDBN__
+@kindex quit
+To exit _GDBN__, use the @samp{quit} command (abbreviated @samp{q}), or type
+an end-of-file character (usually @kbd{C-d}).  
+
+@cindex interrupt
+An interrupt (often @kbd{C-c}) will not exit from _GDBN__, but rather
+will terminate the action of any _GDBN__ command that is in progress and
+return to _GDBN__ command level.  It is safe to type the interrupt
+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 @samp{detach} command; @pxref{Attach}.
+
+@node Shell Commands,,,
+@section Shell Commands
+If you just need to execute occasional shell commands during your
+debugging session, there's no need to stop or suspend _GDBN__; you can
+just use the @samp{shell} command.
+
+@table @code
+@item shell @var{command string}
+@kindex shell
+@cindex shell escape
+Directs _GDBN__ to invoke an inferior shell to execute @var{command string}.
+The environment variable @code{SHELL} is used if it exists, otherwise _GDBN__
+uses @samp{/bin/sh}.
+@end table
+
+The utility @samp{make} is often needed in development environments.
+You don't have to use the @samp{shell} command for this purpose in _GDBN__:
+
+@table @code
+@item make @dots{}
+@kindex make
+@cindex calling make
+Causes _GDBN__ to execute an inferior @code{make} program with the specified
+arguments.  This is equivalent to @samp{shell make @dots{}}.
+@end table
+
+@node Commands,,,
+@chapter _GDBN__ Commands
+
+@node Command Syntax,,,
+@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
@@ -599,3419 +807,3539 @@ differently when repeated because that is more useful.
 A line of input starting with @samp{#} is a comment; it does nothing.
 This is useful mainly in command files (@xref{Command Files}).
 
+@node Help,,,
+@section Getting Help
 @cindex online documentation
 @kindex help
-@table @code
-@item help
-@itemx help @var{category}
-@itemx help @var{command}
 You can always ask _GDBN__ itself for information on its commands, using the
-command @samp{help}.  With a command name as argument, it will display a
-paragraph on how to use the command.  Used with no arguments,
-@samp{help} displays a short list of named categories of commands; you
-can then use @samp{help @var{category}} to list the individual commands
-in a category.
-
-@kindex info version
-@item info version
-As _GDBN__ evolves, new commands are introduced, and old ones may wither
-away.  If multiple versions of _GDBN__ are in use at your site, it may
-occasionally be useful to make sure what version of _GDBN__ you're running.
-_GDBN__ announces its version whenever it starts up; but you can make it
-repeat this information with the @samp{info version} command.
-@end table
-
-@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 @samp{set prompt} command.  For
-instance, when debugging _GDBN__ with _GDBN__, it is useful to change the prompt
-in one of the _GDBN__s so that you tell which one you are talking to.
-
-@table @code
-@item set prompt @var{newprompt}
-@kindex set prompt
-Directs _GDBN__ to use @var{newprompt} as its prompt string henceforth.
-@kindex show prompt
-@item show prompt
-Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
-@end table
-
-@cindex exiting _GDBN__
-@kindex quit
-To exit _GDBN__, use the @samp{quit} command (abbreviated @samp{q}), or type
-an end-of-file character (usually @ctrl{d}).  An interrupt (often
-@ctrl{c}) will not exit from _GDBN__, but rather will terminate the action
-of any _GDBN__ command that is in progress and return to _GDBN__ command level.
-It is safe to type the interrupt character at any time because _GDBN__ does
-not allow it to take effect until a time when it is safe.
-
-@cindex readline
-@cindex command line editing
-@cindex history substitution
-_GDBN__ reads its input commands via the @code{readline} interface.  This
-GNU library provides consistent behavior for programs which provide a
-command line interface to the user.  Advantages are @samp{emacs}-style
-or @samp{vi}-style inline editing of commands, @samp{csh}-like history
-substitution, and a storage and recall of command history across
-debugging sessions.
-
-You may control the behavior of command line editing in _GDBN__ with the
-command @samp{set}.  You may check the status of any of these settings
-with the command @samp{show}.
+command @samp{help}.  
 
 @table @code
-@kindex set editing
-@cindex editing
-@item set editing
-@itemx set editing on
-Enable command line editing (enabled by default).
-
-@item set editing off
-Disable command line editing.
+@item help
+Used with no arguments, @samp{help} displays a short list of named
+categories of commands:
+@example
+(_GDBP__) help
+List of classes of commands:
+
+running -- Running the program
+stack -- Examining the stack
+data -- Examining data
+breakpoints -- Making program stop at certain points
+files -- Specifying and examining files
+status -- Status inquiries
+support -- Support facilities
+user-defined -- User-defined commands
+aliases -- Aliases of other commands
+obscure -- Obscure features
+
+Type "help" followed by a class name for a list of commands in that class.
+Type "help" followed by command name for full documentation.
+Command name abbreviations are allowed if unambiguous.
+(_GDBP__) 
+@end example
 
-@kindex show editing
-@item show editing
-Show whether command line editing is enabled.
+@item help @var{category}
+Using one of the general help categories as an argument, you can get a
+list of the individual commands in a category.  For example, here is the
+help display for category @samp{status}:
+@example
+(_GDBP__) help status
+Status inquiries.
 
-@cindex history file
-@kindex set history file
-@item set history file @var{filename}
-Set the name of the _GDBN__ command history file to @samp{filename}.  This is
-the file from which _GDBN__ will read an initial command history
-list or to which it will write this list when it exits.  This list is
-accessed through history expansion or through the history
-command editing characters listed below.  This file defaults to the
-value of the environmental variable @code{GDBHISTFILE}, or to
-@code{./.gdb_history} if this variable is not set.
+List of commands:
 
-@cindex history write
-@kindex set history write
-@item set history write
-@itemx set history write on
-Make _GDBN__ record command history in a file, whose name may be specified with the
-@samp{set history file} command.  By default, this option is disabled.
+show -- Generic command for showing things set with "set"
+info -- Generic command for printing status
 
-@item set history write off
-Make _GDBN__ stop recording command history in a file.
+Type "help" followed by command name for full documentation.
+Command name abbreviations are allowed if unambiguous.
+(_GDBP__) 
+@end example
 
-@cindex history size
-@kindex set history size
-@item set history size @var{size}
-Set the number of commands which _GDBN__ will keep in its history list.
-This defaults to the value of the environmental variable
-@code{HISTSIZE}, or to 256 if this variable is not set.
+@item help @var{command}
+With a command name as @samp{help} argument, _GDBN__ will display a
+short paragraph on how to use that command.  
 @end table
 
-@cindex history expansion
-History expansion assigns special meaning to the character @samp{!}
-(@pxref{Event Designators}).  Since @samp{!} is also the logical not
-operator in C, history expansion is off by default. If you decide to
-enable history expansion with the @samp{set history expansion on}
-command, you may sometimes need to follow @samp{!} (when it is used as
-logical not, in an expression) with a space or a tab to prevent it from
-being expanded.  The @code{readline} history facilities will not attempt
-substitution on the strings @samp{!=} and @samp{!(}, even when history
-expansion is enabled.
-
-The commands to control history expansion are:
+In addition to @samp{help}, you can use the _GDBN__ commands @samp{info}
+and @samp{show} to inquire about the state of your program, or the state
+of _GDBN__ itself.  Both commands support many ``sub-commands'', or
+topics of inquiry; this manual introduces each of them in the
+appropriate context.  The listings under ``@code{info}'' and under
+``@code{show}'' in the Index point to all the sub-commands
+(@pxref{Index}).
 
 @table @code
-
-@kindex set history expansion
-@item set history expansion on
-@itemx set history expansion
-Enable history expansion.  History expansion is off by default.
-
-@item set history expansion off
-Disable history expansion.
-
-The @code{readline} code comes with more complete documentation of
-editing and history expansion features.  Users unfamiliar with @samp{emacs}
-or @samp{vi} may wish to read it. @xref{Command Line Editing}.
-
-@kindex show history
-@item show history
-@itemx show history file
-@itemx show history write
-@itemx show history size
-@itemx show history expansion
-These commands display the state of the _GDBN__ history parameters.
-@samp{show history} by itself displays all four states.
+@kindex info
+@item info
+This command is for describing the state of your program; for example,
+it can list the arguments given to your program (@samp{info args}), the
+registers currently in use (@samp{info registers}), or the breakpoints
+you've set (@samp{info breakpoints}).  You can get a complete list of
+the @code{info} sub-commands with @samp{help info}.
 
 @kindex show
-@kindex info set
 @item show
-@itemx info set
-This chapter introduces a number of internal _GDBN__ variables that you
-can control with the @samp{set} command, and display with the
-@samp{show} command.   A number of others are introduced throughout the
-manual.  To display all the settable parameters and their current
+In contrast, @samp{show} is for describing the state of _GDBN__ itself.
+You can change most of the things you can @code{show}, by using the
+related command @samp{set}; for example, you can control what number
+system is used for displays with @samp{set radix}, or simply inquire
+which possibility is currently in use with @samp{show radix}.  
+
+@kindex info set
+To display all the settable parameters and their current
 values, you can use @samp{show} with no arguments; you may also use
 @samp{info set}.  Both commands produce the same display.
+@c FIXME: "info set" violates the rule that "info" is for state of
+@c FIXME...program.  Ck w/ GNU: "info set" to be called something else,
+@c FIXME...or change desc of rule---eg "state of prog and debugging session"?
+
+
+@kindex show version
+@item show version
+@c FIXME: chgd to "show version" from "info".  Verify John doing same to GDBv4.
+This @samp{show} subcommand is one of those with no corresponding
+@samp{set} subcommand.  As _GDBN__ evolves, new commands are introduced,
+and old ones may wither away.  If multiple versions of _GDBN__ are in
+use at your site, it may occasionally be useful to make sure what
+version of _GDBN__ you're running.  It is also useful to include this
+information in _GDBN__ bug-reports.  _GDBN__ announces its version
+number if you start it with no arguments; but you can make it give this
+information on request, with the @samp{show version} command.
 
 @end table
 
-@table @code
-@kindex info editing
-@item info editing
-Display the last ten commands in the command history.
+@node Running,,,
+@chapter Running Programs Under _GDBN__
 
-@item info editing @var{n}
-Print ten commands centered on command number @var{n}.
+@node Compilation,,,
+@section Compiling for Debugging
 
-@item info editing +
-Print ten commands just after the commands last printed.
+In order to debug a program effectively, you need to ask for debugging
+information when you compile it.  This debugging information is stored
+in the object file; it describes the data type of each variable or
+function and the correspondence between source line numbers and
+addresses in the executable code.
 
-@end table
+To request debugging information, specify the @samp{-g} option when you run
+the compiler.
 
-Occasionally it is useful to execute a shell command from within _GDBN__.
-This can be done with the @samp{shell} command.
+The Unix C compiler is unable to handle the @samp{-g} and @samp{-O} options
+together.  This means that you cannot ask for optimization if you ask for
+debugger information.
 
-@table @code
-@item shell @var{command string}
-@kindex shell
-@cindex shell escape
-Directs _GDBN__ to invoke an inferior shell to execute @var{command string}.
-The environment variable @code{SHELL} is used if it exists, otherwise _GDBN__
-uses @samp{/bin/sh}.
-@end table
+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 the program is
+correct, but there's no sense in pushing your luck.
 
-The utility @samp{make} is often needed in development environments.
-You don't have to use the @samp{shell} command for this purpose in _GDBN__:
+Some things do not work as well with @samp{-g -O} as with just
+@samp{-g}, particularly on machines with instruction scheduling.  If in
+doubt, recompile with @samp{-g} alone, and if this fixes the problem,
+please report it as a bug (including a test case---@pxref{_GDBN__ Bugs}).
 
-@table @code
-@item make @dots{}
-@kindex make
-@cindex calling make
-Causes _GDBN__ to execute an inferior @code{make} program with the specified
-arguments.  This is equivalent to @samp{shell make @dots{}}.
-@end table
+Older versions of the GNU C compiler, _GCC__, permitted a variant option
+@samp{-gg} for debugging information.  _GDBN__ no longer supports this format;
+if your GNU C compiler has this option, do not use it.
 
-@cindex screen size
-@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} when you want
-to continue the output.  Normally _GDBN__ knows the size of the screen from
-the termcap data base together with the value of the @code{TERM}
-environment variable and the @code{stty rows} and @code{stty cols}
-settings. If this is not correct, you can override it with
-the @samp{set screen-height} and @samp{set screen-width} commands:
-
-_GDBN__ also uses the screen width setting to determine when to wrap lines
-of output.  Depending what is being printed, it tries to break the
-line at a readable place, rather than simply letting it overflow onto
-the following line.
+@ignore
+@comment As far as I know, there are no cases in which _GDBN__ will
+@comment produce strange output in this case.  (but no promises).
+If your program includes archives made with the @code{ar} program, and
+if the object files used as input to @code{ar} were compiled without the
+@samp{-g} option and have names longer than 15 characters, _GDBN__ will get
+confused reading the program's symbol table.  No error message will be
+given, but _GDBN__ may behave strangely.  The reason for this problem is a
+deficiency in the Unix archive file format, which cannot represent file
+names longer than 15 characters.
 
-@table @code
-@item set screen-height @var{lpp}
-@itemx show screen-height
-@itemx set screen-width @var{cpl}
-@itemx show screen-width
-@kindex set screen-height
-@kindex set screen-width
-@kindex show screen-width
-@kindex show screen-height
-These @samp{set} commands specify a screen height of @var{lpp} lines and
-a screen width of @var{cpl} characters.  The associated @samp{show}
-commands display the current settings.
+To avoid this problem, compile the archive members with the @samp{-g}
+option or use shorter file names.  Alternatively, use a version of GNU
+@code{ar} dated more recently than August 1989.
+@end ignore
 
-If you specify a height of zero lines, _GDBN__ will not pause during output
-no matter how long the output is.  This is useful if output is to a file
-or to an editor buffer.
-@end table
 
-@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}.
-Numbers that begin with none of these are, by default, entered in base
-10; likewise, the default display for numbers---when no particular
-format is specified---is base 10.  You can change the default base for
-both input and output with the @samp{set radix} command.
+@node Starting,,,
+@section Starting your Program
+@cindex starting
+@cindex running
+@kindex run
+To start your program under _GDBN__, use the @samp{run} command.  Except on
+VxWorks, the program must already have been specified using the
+@samp{file} or @samp{exec-file} command, or with an argument to _GDBN__
+(@pxref{Files}).
 
-@table @code
-@kindex set radix
-@item set radix @var{base}
-Set the default base for numeric input and display.  Supported choices
-for @var{base} are decimal 8, 10, 16.  @var{base} must itself be
-specified either unambiguously or using the current default radix; for
-example, any of
+On targets that support processes, @samp{run} creates an inferior
+process and makes that process run your program.  On other targets,
+@samp{run} jumps to the location it has recorded for the start of the
+program.
 
-@example
-set radix 012
-set radix 10.
-set radix 0xa
-@end example
+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 the program.  (You
+can change it after starting the program, but such changes do not affect
+the program unless you start it over again.)  This information may be
+divided into three categories:
 
-@noindent
-will set the base to decimal.  On the other hand, @samp{set radix 10}
-will leave the radix unchanged no matter what it was.
+@table @asis
+@item The @i{arguments.}
+You specify the arguments to give the program as the arguments of the
+@samp{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
+(for example regular expression expansion or variable substitution) in
+describing the arguments.  In Unix systems, you can control which shell
+is used with the @code{SHELL} environment variable.
 
-@kindex show radix
-@item show radix
-Display the current default base for numeric input and display.
+@item The @i{environment.}
+The program normally inherits its environment from _GDBN__, but you can
+use the _GDBN__ commands @samp{set environment} and
+@samp{unset environment} to change parts of the environment that will
+be given to the program.@refill
 
+@item The @i{working directory.}
+The program inherits its working directory from _GDBN__.  You can set _GDBN__'s
+working directory with the @samp{cd} command in _GDBN__.
 @end table
 
-By default, _GDBN__ is silent about its inner workings.  If you are running
-on a slow machine, you may want to use the @samp{set verbose} command.
-It will make _GDBN__ tell you when it does a lengthy internal operation, so
-you won't think it has crashed.
+When you issue the @samp{run} command, your program begins to execute
+immediately.  @xref{Stopping}, for discussion of how to arrange for your
+program to stop.
 
-Currently, the messages controlled by @samp{set verbose} are those which
-announce that the symbol table for a source file is being read
-(@pxref{Files}, in the description of the command
-@samp{symbol-file}).
-@c The following is the right way to do it, but emacs 18.55 doesn't support
-@c @ref, and neither the emacs lisp manual version of texinfmt or makeinfo
-@c is released.  
-@ignore
-see @samp{symbol-file} in @ref{Files}).
-@end ignore
+Note that once your program has been started by the @samp{run} command,
+you may evaluate expressions that involve calls to functions in the
+inferior, using the @samp{print} or @samp{call} commands.  @xref{Data}.
 
-@table @code
-@kindex set verbose
-@item set verbose on
-Enables _GDBN__'s output of certain informational messages.
+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.  In this process, it tries to retain your current breakpoints.
 
-@item set verbose off
-Disables _GDBN__'s output of certain informational messages.
+@menu
+* Arguments::			Specifying the arguments for your program.
+* Environment::			Specifying the environment for your program.
+* Working Directory::		Specifying the working directory for giving
+                       to your program when it is run.
+* Input/Output::		Specifying the program's standard input and output.
+* Attach::			Debugging a process started outside _GDBN__.
+* Kill Process::		Getting rid of the child process running your program.
+@end menu
 
-@kindex show verbose
-@item show verbose
-Displays whether @samp{set verbose} is on or off.
-@end table
+@node Arguments, Environment, Running, Running
+@section Your Program's Arguments
 
-By default, if _GDBN__ encounters bugs in the symbol table of an object file,
-it prints a single message about each type of problem it finds, then 
-shuts up.  You can suppress these messages, or allow more than one such
-message to be printed if you want to see how frequent the problems are.
-@xref{Files}.
+@cindex arguments (to your program)
+The arguments to your program are specified by the arguments of the 
+@samp{run} command.  They are passed to a shell, which expands wildcard
+characters and performs redirection of I/O, and thence to the program.
 
+@samp{run} with no arguments uses the same arguments used by the previous
+@samp{run}.
+
+@kindex set args
 @table @code
-@kindex set complaints
-@item set complaints @var{limit}
-Permits _GDBN__ to output @var{limit} complaints about each type of unusual
-symbols before becoming silent about the problem.  Set @var{limit} to
-zero to suppress all complaints; set it to a large number to prevent
-complaints from being suppressed.
+@item set args
+The command @samp{set args} can be used to specify the arguments to be used
+the next time the program is run.  If @samp{set args} has no arguments, it
+means to use no arguments the next time the program is run.  If you have
+run your program with arguments and want to run it again with no arguments,
+this is the only way to do so.
 
-@kindex show complaints
-@item show complaints
-Displays how many symbol complaints _GDBN__ is permitted to produce.
+@item show args
+@kindex show args
+Show the arguments to give your program when it is started.
 @end table
 
-By default, _GDBN__ is cautious, and asks what sometimes seem to be a lot of
-stupid questions.  For example, if you try to run a program which is
-already running:
-@example
-
-(_GDBP__) run
-The program being debugged has been started already.
-Start it from the beginning? (y or n) 
-@end example
+@node Environment, Working Directory, Arguments, Running
+@section Your Program's Environment
 
-If you're willing to unflinchingly face the consequences of your own
-commands, you can disable this ``feature'':
+@cindex environment (of your program)
+The @dfn{environment} consists of a set of @dfn{environment variables} and
+their values.  Environment variables conventionally record such things as
+your user name, your home directory, your terminal type, and your search
+path for programs to run.  Usually you set up environment variables with
+the shell and they are inherited by all the other programs you run.  When
+debugging, it can be useful to try running the program with different
+environments without having to start the debugger over again.
 
 @table @code
-@kindex set caution
-@cindex flinching
-@cindex stupid questions
-@item set caution off
-Disables cautious questions.
+@item show environment @var{varname}
+@kindex show environment
+Print the value of environment variable @var{varname} to be given to
+your program when it is started.
 
-@item set caution on
-Enables cautious questions (the default).
+@item show environment
+Print the names and values of all environment variables to be given to
+your program when it is started.
 
-@item show caution
-@kindex show caution
-Displays state of cautious questions.
-@end table
+@item set environment @var{varname} @var{value}
+@itemx set environment @var{varname} = @var{value}
+@kindex set environment
+Sets environment variable @var{varname} to @var{value}, for your program
+only, not for _GDBN__ itself.  @var{value} may be any string; the values of
+environment variables are just strings, and any interpretation is
+supplied by your program itself.  The @var{value} parameter is optional;
+if it is eliminated, the variable is set to a null value.
 
-@node Files, Compilation, User Interface, Top
-@chapter Specifying _GDBN__'s Files
+For example, this command:
 
-@cindex core dump file
-@cindex executable 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 the program.  To
-debug a core dump of a previous run, _GDBN__ must be told the file name of
-the core dump.
+@example
+set env USER = foo
+@end example
 
-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}.
+@noindent
+tells the program, when subsequently run, to assume it is being run
+on behalf of the user named @samp{foo}.
 
-But 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
-want to use.  In these situations the _GDBN__ commands to specify new files
-are useful.
+@item delete environment @var{varname}
+@itemx unset environment @var{varname}
+@kindex delete environment
+@kindex unset environment
+Remove variable @var{varname} from the environment to be passed to your
+program.  This is different from @samp{set env @var{varname}@ =};
+@samp{delete environment} removes the variable from the environment,
+rather than assigning it an empty value.  This command can be
+abbreviated @samp{d e}.
+@end table
 
-@table @code
-@item file @var{filename}
-@kindex file
-Use @var{filename} as the program to be debugged.  It is read for its
-symbols, for getting the contents of pure memory, and it is the program
-executed when you use the @samp{run} command.  If you do not specify a
-directory and the file is not found in _GDBN__'s working directory, _GDBN__ will
-use the environment variable @code{PATH} as a list of directories to
-search, just as the shell does when looking for a program to run.
+@node Working Directory, Input/Output, Environment, Running
+@section Your Program's Working Directory
 
-@samp{file} with no argument makes both executable file and symbol
-table become unspecified.
+@cindex working directory (of your program)
+Each time you start your program with @samp{run}, it inherits its
+working directory from the current working directory of _GDBN__.  _GDBN__'s
+working directory is initially whatever it inherited from its parent
+process (typically the shell), but you can specify a new working
+directory in _GDBN__ with the @samp{cd} command.
 
-@item exec-file @var{filename}
-@kindex exec-file
-Specify that the program to be run (but not the symbol table) is found
-in @var{filename}.  _GDBN__ will search the environment variable @code{PATH}
-if necessary to locate the program.
+The _GDBN__ working directory also serves as a default for the commands
+that specify files for _GDBN__ to operate on.  @xref{Files}.
 
-@item symbol-file @var{filename}
-@kindex symbol-file
-Read symbol table information from file @var{filename}.  @code{PATH} is
-searched when necessary.  Use the @samp{file} command to get both symbol
-table and program to run from the same file.
+@table @code
+@item cd @var{directory}
+@kindex cd
+Set _GDBN__'s working directory to @var{directory}.
 
-@samp{symbol-file} with no argument clears out _GDBN__'s information on your
-program's symbol table.
+@item pwd
+@kindex pwd
+Print _GDBN__'s working directory.
+@end table
 
-The @samp{symbol-file} command causes _GDBN__ to forget the contents of its
-convenience variables, the value history, and all breakpoints and
-auto-display expressions.  This is because they may contain pointers to
-the internal data recording symbols and data types, which are part of
-the old symbol table data being discarded inside _GDBN__.
+@node Input/Output, Attach, Working Directory, Running
+@section Your Program's Input and Output
 
-On some kinds of object files, the @samp{symbol-file} command does not
-actually 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.
+@cindex redirection
+@cindex i/o
+@cindex terminal
+@cindex controlling terminal
+By default, the program you run under _GDBN__ does input and output to the same
+terminal that _GDBN__ uses.
 
-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 @samp{set verbose} command can turn these pauses into
-messages if desired. @xref{User Interface}).
+You can redirect the program's input and/or output using @samp{sh}-style
+redirection commands in the @samp{run} command.  For example,
 
-When the symbol table is stored in COFF format, @samp{symbol-file} does
-read the symbol table data in full right away.  We haven't implemented
-the two-stage strategy for COFF yet.
+_0__@example
+run > outfile
+_1__@end example
 
-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 the GNU compiler _GCC__, or other
-compilers that adhere to the local conventions.  Best results are
-usually obtained from _GCC__; for example, using _GCC__ you can generate
-debugging information for optimized code.
+@noindent
+starts the program, diverting its output to the file @file{outfile}.
 
-While the symbol file is being read, _GDBN__ will occasionally encounter
-problems, such as symbol types it does not recognize, or known bugs in
-compiler output.  By default, it prints one message about each such
-type of problem, no matter how many times the problem occurs.  You can
-ask it to print more messages, to see how many times the problems occur,
-or can shut the messages off entirely, with the @samp{set 
-complaints} command (@xref{User Interface}).
+@kindex tty
+Another way to specify where the program should do input and output is
+with the @samp{tty} command.  This command accepts a file name as
+argument, and causes this file to be the default for future @samp{run}
+commands.  It also resets the controlling terminal for the child
+process, for future @samp{run} commands.  For example,
 
-The messages currently printed, and their meanings, are:
+@example
+tty /dev/ttyb
+@end example
 
-@table @code
-@item inner block not inside outer block in @var{symbol}
+@noindent
+directs that processes started with subsequent @samp{run} commands
+default to do input and output on the terminal @file{/dev/ttyb} and have
+that as their controlling terminal.
 
-The symbol information shows where symbol scopes begin and end
-(such as at the start of a function or a block of statements).  This
-error indicates that an inner scope block is not fully contained
-in its outer scope blocks.  _GDBN__ circumvents the problem by treating
-the inner block as if it had the same scope as the outer block.
-@var{symbol} may be ``(don't know)'' if the outer block is not
-a function.
+An explicit redirection in @samp{run} overrides the @samp{tty} command's
+effect on input/output redirection, but not its effect on the
+controlling terminal.
 
-@item block at @var{address} out of order
+When you use the @samp{tty} command or redirect input in the @samp{run}
+command, only the @emph{input for your program} is affected.  The input
+for _GDBN__ still comes from your terminal.
 
-The symbol information for symbol scope blocks should occur in 
-order of increasing addresses.  This error indicates that it does not
-do so.  _GDBN__ does not circumvent this problem, and will have trouble
-locating symbols in the source file whose symbols being read.  (You
-can often determine what source file is affected by turning on
-@samp{info verbose}.  @xref{User Interface}.)
+@node Attach, Kill Process, Input/Output, Running
+@section Debugging an Already-Running Process
+@kindex attach
+@cindex attach
 
-@item bad block start address patched
+@table @code
+@item attach @var{process--id}
+This command attaches to a running process, if your currently selected
+target supports processes.  (@samp{info files} will show your active
+targets).  The command takes as argument a process ID.
 
-The symbol information for a symbol scope block has a start address
-smaller than the address of the preceding source line.  This is known
-to occur in the SunOS 4.1.1 (and earlier) C compiler.  _GDBN__ circumvents
-the problem by treating the symbol scope block as starting on the
-previous source line.
+You specify a process ID to debug an already-running process that was
+started outside of _GDBN__.  (The usual way to find out the process-id of
+a Unix process is with the @code{ps} utility, or with the @code{jobs -l}
+shell command.)  In this case, you must have permission to send the
+process a signal, and it must have the same effective user ID as the
+debugger.
+@end table
 
-@comment @item{encountered DBX-style class variable debugging information.
-@comment You seem to have compiled your program with "g++ -g0" instead of "g++ -g".
-@comment Therefore _GDBN__ will not know about your class variables}
-@comment 
-@comment This error indicates that the symbol information produced for a C++
-@comment program includes zero-size fields, which indicated static fields in
-@comment a previous release of the G++ compiler.  This message is probably
-@comment obsolete.
-@comment
-@item bad string table offset in symbol @var{n}
+When using @samp{attach}, you should first use the @samp{file} command
+to specify the program running in the process and load its symbol table.
 
-Symbol number @var{n} contains a pointer into the string table which is
-larger than the size of the string table.  _GDBN__ circumvents the problem
-by considering the symbol to have the name @code{foo}, which may cause
-other problems if many symbols end up with this name.  @cindex{foo}
+The first thing _GDBN__ does after arranging to debug the process is to stop
+it.  You can examine and modify an attached process with all the _GDBN__
+commands that ordinarily available when you start processes with
+@samp{run}.  You can insert breakpoints; you can step and continue; you
+can modify storage.  If you would rather the process continue running,
+you may use the @samp{continue} command after attaching _GDBN__ to the
+process.
 
-@item unknown symbol type @code{0xNN}
+@kindex detach
+When you have finished debugging the attached process, you can use the
+@samp{detach} command to release it from _GDBN__'s control.  Detaching
+the process continues its execution.  After the @samp{detach} command,
+that process and _GDBN__ become completely independent once more, and you
+are ready to @samp{attach} another process or start one with @samp{run}.
 
-The symbol information contains new data types that _GDBN__ does not yet
-know how to read.  @code{0xNN} is the symbol type of the misunderstood
-information, in hexadecimal.  _GDBN__ circumvents the error by ignoring
-this symbol information.  This will usually allow the program to be
-debugged, though certain symbols will not be accessible.  If you
-encounter such a problem and feel like debugging it, you can debug _GDBP__
-with itself, breakpoint on "complain", then go "up" to
-read_dbx_symtab() and examine *bufp to see the symbol.
+If you exit _GDBN__ or use the @samp{run} command while you have an attached
+process, you kill that process.  By default, you will be asked for
+confirmation if you try to do either of these things; you can control
+whether or not this happens by using the @samp{set caution} command
+(@pxref{User Interface}).
 
-@c @item stub type has NULL name
-@c 
-@c FIXME, Mike Tiemann needs to write about what this means.
+@node Kill Process,  , Attach, Running
+@section Killing the Child Process
 
-@item const/volatile indicator missing, got 'X'
+@table @code
+@item kill
+@kindex kill
+Kill the child process in which your program is running under _GDBN__.
+@end table
 
-The symbol information for a C++ type is missing some information that
-the compiler should have output for it.
+This command is useful if you wish to debug a core dump instead.  _GDBN__
+ignores any core dump file if it is actually running the program.
 
-@item C++ type mismatch between compiler and debugger
+On some operating systems, you can't execute your program in another
+process while breakpoints are active inside _GDBN__.  The @samp{kill}
+command is also useful in this situation, if you wish to run the program
+outside the debugger.
 
-The debugger could not parse a type specification output by the compiler
-for some C++ object.
+The @samp{kill} command is also useful if you wish to recompile and
+relink the program, since on many systems it is impossible to modify an
+executable file which is running in a process.  In this case, when you
+next type @samp{run}, _GDBN__ will notice that the file has changed, and
+will re-read the symbol table (while trying to preserve your current
+breakpoint settings).
 
-@end table
+@node Stopping, Stack, Running, Top
+@chapter Stopping and Continuing
 
-@item core-file @var{filename}
-@itemx core @var{filename}
-@kindex core
-@kindex core-file
-Specify the whereabouts of a core dump file to be used as the ``contents
-of memory''.  Traditionally, core files contain only some parts of the
-address space of the process that generated them; _GDBN__ can access the
-executable file itself for other parts.
+When you run a program normally, it runs until it terminates.  The
+principal purpose of using a debugger is so that you can stop it before
+that point; or so that if the program runs into trouble you can
+investigate and find out why.
 
-@samp{core-file} with no argument specifies that no core file is
-to be used.
+@menu
+* Signals::			Fatal signals in your program just stop it;
+                 then you can use _GDBN__ to see what is going on.
+* Breakpoints::			Breakpoints let you stop your program when it
+                 reaches a specified point in the code.
+                 an expression changes.
+* Continuing::			Resuming execution until the next signal or breakpoint.
+* Stepping::			Stepping runs the program a short distance and
+                 then stops it wherever it has come to.
+@end menu
 
-Note that the core file is ignored when your program is actually running
-under _GDBN__.  So, if you have been running the 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 @samp{kill} command
-(@pxref{Kill Process}).
+@node Signals, Breakpoints, Stopping, Stopping
+@section Signals
+@cindex signals
 
-@item load @var{filename}
-@kindex load
-This command will dynamically link @var{filename} on the current target,
-performing any necessary downloads, then add @var{filename}'s symbol
-table in the same way as the @samp{add-syms} command.
+A signal is an asynchronous event that can happen in a program.  The
+operating system defines the possible kinds of signals, and gives each kind
+a name and a number.  For example, @code{SIGINT} is the signal a program
+gets when you type @kbd{Ctrl-c}; @code{SIGSEGV} is the signal a program
+gets from referencing a place in memory far away from all the areas in use;
+@code{SIGALRM} occurs when the alarm clock timer goes off (which happens
+only if the program has requested an alarm).
 
-@item add-syms @var{filename} @var{address}
-@kindex add-syms
-@cindex dynamic linking
-The @samp{add-syms} command reads additional symbol table information
-from the file @var{filename}.  You would use this command when that file
-has been dynamically loaded (by some other means) into the program that
-is running.  @var{address} should be the memory address at which the
-file has been loaded; _GDBN__ cannot figure this out for itself.
+@cindex fatal signals
+Some signals, including @code{SIGALRM}, are a normal part of the
+functioning of the program.  Others, such as @code{SIGSEGV}, indicate
+errors; these signals are @dfn{fatal} (kill the program immediately) if the
+program has not specified in advance some other way to handle the signal.
+@code{SIGINT} does not indicate an error in the program, but it is normally
+fatal so it can carry out the purpose of @kbd{Ctrl-c}: to kill the program.
 
-The symbol table of the file @var{filename} is added to the symbol table
-originally read with the @samp{symbol-file} command.  You can use the
-@samp{add-syms} command any number of times; the new symbol data thus
-read keeps adding to the old.  The @samp{symbol-file} command forgets
-all the symbol data _GDBN__ has read.
+_GDBN__ has the ability to detect any occurrence of a signal in the program
+running under _GDBN__'s control.  You can tell _GDBN__ in advance what to do for
+each kind of signal.
 
-@item info files
-@itemx info target
-@kindex info files
-@kindex info target
-@samp{info files} and @samp{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.
+@cindex handling signals
+Normally, _GDBN__ is set up to ignore non-erroneous signals like @code{SIGALRM}
+(so as not to interfere with their role in the functioning of the program)
+but to stop the program immediately whenever an error signal happens.
+You can change these settings with the @samp{handle} command.
 
-Beware: the similar command @samp{info targets} lists all possible
-targets rather than current ones.
+@table @code
+@item info signal
+@kindex info signal
+Print a table of all the kinds of signals and how _GDBN__ has been told to
+handle each one.  You can use this to see the signal numbers of all
+the defined types of signals.
 
+@item handle @var{signal} @var{keywords}@dots{}
+@kindex handle
+Change the way _GDBN__ handles signal @var{signal}.  @var{signal} can be the
+number of a signal or its name (with or without the @samp{SIG} at the
+beginning).  The @var{keywords} say what change to make.
 @end table
 
-While all three file-specifying commands allow both absolute and relative
-file names as arguments, _GDBN__ always converts the file name to an absolute
-one and remembers it that way.
-
-@kindex sharedlibrary
-@kindex share
-@cindex shared libraries
-
-_GDBN__ supports the SunOS shared library format.  Symbols from a shared
-library cannot be referenced before the shared library has been linked
-with the program.  (That is to say, after one types @samp{run} and 
-the function @code{main()} has been entered; or when examining core
-files.)  Once the shared library has been linked in, you can use the
-following commands:
+The keywords allowed by the @samp{handle} command can be abbreviated.
+Their full names are
 
 @table @code
-@item sharedlibrary @var{regex}
-@itemx share @var{regex}
-Load shared object library symbols for files matching a UNIX regular
-expression.
+@item nostop
+_GDBN__ should not stop the program when this signal happens.  It may
+still print a message telling you that the signal has come in.
 
-@item share
-@itemx sharedlibrary
-Load symbols for all shared libraries.
+@item stop
+_GDBN__ should stop the program when this signal happens.  This implies
+the @samp{print} keyword as well.
 
-@item info share
-@itemx info sharedlibrary
-@kindex info sharedlibrary
-@kindex info share
-Print the names of the shared libraries which are currently loaded.
-@end table
+@item print
+_GDBN__ should print a message when this signal happens.
 
+@item noprint
+_GDBN__ should not mention the occurrence of the signal at all.  This
+implies the @samp{nostop} keyword as well.
 
-@node Compilation, Targets, Files, Top
-@chapter Compiling for Debugging
+@item pass
+_GDBN__ should allow the program to see this signal; the program will be
+able to handle the signal, or may be terminated if the signal is fatal
+and not handled.
 
-In order to debug a program effectively, you need to ask for debugging
-information when you compile it.  This debugging information is stored
-in the object file; it describes the data type of each variable or
-function and the correspondence between source line numbers and
-addresses in the executable code.
+@item nopass
+_GDBN__ should not allow the program to see this signal.
+@end table
 
-To request debugging information, specify the @samp{-g} option when you run
-the compiler.
+When a signal has been set to stop the program, the program cannot see the
+signal until you continue.  It will see the signal then, if @samp{pass} is
+in effect for the signal in question @i{at that time}.  In other words,
+after _GDBN__ reports a signal, you can use the @samp{handle} command with
+@samp{pass} or @samp{nopass} to control whether that signal will be seen by
+the program when you later continue it.
 
-The Unix C compiler is unable to handle the @samp{-g} and @samp{-O} options
-together.  This means that you cannot ask for optimization if you ask for
-debugger information.
+You can also use the @samp{signal} command to prevent the program from
+seeing a signal, or cause it to see a signal it normally would not see,
+or to give it any signal at any time.  @xref{Signaling}.
 
-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 the program is
-correct, but there's no sense in pushing your luck.
+@node Breakpoints, Continuing, Signals, Stopping
+@section Breakpoints
 
-Some things do not work as well with @samp{-g -O} as with just
-@samp{-g}, particularly on machines with instruction scheduling.  If in
-doubt, recompile with @samp{-g} alone, and if this fixes the problem,
-please report it as a bug (including a test case---@pxref{_GDBN__ Bugs}).
+@cindex breakpoints
+A @dfn{breakpoint} makes your program stop whenever a certain point in the
+program is reached.  You set breakpoints explicitly with _GDBN__ commands,
+specifying the place where the program should stop by line number, function
+name or exact address in the program.  You can add various other conditions
+to control whether the program will stop.
 
-Older versions of the GNU C compiler, _GCC__, permitted a variant option
-@samp{-gg} for debugging information.  _GDBN__ no longer supports this format;
-if your GNU C compiler has this option, do not use it.
+Each breakpoint is assigned a number when it is created; these numbers are
+successive integers starting with 1.  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 the program until you
+enable it again.
 
-@ignore
-@comment As far as I know, there are no cases in which _GDBN__ will
-@comment produce strange output in this case.  (but no promises).
-If your program includes archives made with the @code{ar} program, and
-if the object files used as input to @code{ar} were compiled without the
-@samp{-g} option and have names longer than 15 characters, _GDBN__ will get
-confused reading the program's symbol table.  No error message will be
-given, but _GDBN__ may behave strangely.  The reason for this problem is a
-deficiency in the Unix archive file format, which cannot represent file
-names longer than 15 characters.
+@table @code
+@kindex info break
+@kindex $_
+@item info break
+The command @samp{info break} prints a list of all breakpoints set and not
+deleted, showing their numbers, where in the program they are, and any
+special features in use for them.  Disabled breakpoints are included in the
+list, but marked as disabled.  @samp{info break} with a breakpoint number
+as argument lists only that breakpoint.  The convenience variable @code{$_}
+and the default examining-address for the @samp{x} command are set to the
+address of the last breakpoint listed (@pxref{Memory}).
 
-To avoid this problem, compile the archive members with the @samp{-g}
-option or use shorter file names.  Alternatively, use a version of GNU
-@code{ar} dated more recently than August 1989.
-@end ignore
+@kindex info watch
+@item info watch
+This command prints a list of watchpoints. 
 
-@node     Targets, Running, Compilation, Top
-@chapter Specifying a Debugging Target 
-@cindex debugging target
-@kindex target
-A @dfn{target} is an interface between the debugger and a particular 
-kind of file or process.  
+@cindex watchpoints
+A @dfn{watchpoint} is a special breakpoint that stops your program when
+the value of an expression changes.  You can use a watchpoint to stop
+execution whenever the value of an expression changes, without having to
+predict a particular place in the inferior process where this may
+happen.  Aside from the different syntax in setting a watchpoint, it is
+managed exactly like any other breakpoint and is enabled, disabled, and
+deleted using exactly the same commands.
 
-Often, you will be able to run _GDBN__ in the same host environment as the
-program you are debugging; in that case, the debugging target can just be
-specified as a side effect of the @samp{file} or @samp{core} commands.
-When you need more flexibility---for example, running _GDBN__ on a
-physically separate host, controlling standalone systems over a
-serial port, or realtime systems over a TCP/IP connection---you can use
-the @samp{target} command.
+Watchpoints currently execute two orders of magnitude more slowly than
+other breakpoints, but this can well be worth it to catch errors where
+you have no clue what part of your program is the culprit.  Some
+processors provide special hardware to implement this feature; future
+releases of _GDBN__ will use such hardware if it is available.
+
+@end table
 
 @menu
-* Active Targets::		Active Targets
-* Target Commands::		Commands for Managing Targets
+* Set Breaks::			How to establish breakpoints.
+* Exception Handling::		How _GDBN__ supports exception handling for C++.
+* Delete Breaks::		How to remove breakpoints no longer needed.
+* Disabling::			How to disable breakpoints (turn them off temporarily).
+* Conditions::			Making extra conditions on whether to stop.
+* Break Commands::		Commands to be executed at a breakpoint.
+* Error in Breakpoints::	
 @end menu
 
-@node Active Targets, Target Commands, Targets, Targets
-@section Active Targets
-@cindex stacking targets
-@cindex active targets
-@cindex multiple targets
+@node Set Breaks, Exception Handling, Breakpoints, Breakpoints
+@subsection Setting Breakpoints
 
-Targets are managed in three @dfn{strata} that correspond to different
-classes of target: processes, core files, and executable files.  This
-allows you to (for example) start a process and inspect its activity
-without abandoning your work on a core file.
+@kindex break
+@kindex watch
+Breakpoints are set with the @samp{break} command (abbreviated @samp{b}).
+Watchpoints are set with the @samp{watch} command.
 
-More than one target can potentially respond to a request.  In
-particular, when you access memory _GDBN__ will walk down the three strata of
-targets until it finds a target that can handle that particular address.
+You have several ways to say where the breakpoint should go.
 
-Strata are always examined in a fixed order: first a process if there is
-one, then a core file if there is one, and finally an executable file if
-there is one of those.
+@table @code
+@item break @var{function}
+Set a breakpoint at entry to function @var{function}.
 
-When you specify a new target in a given stratum, it replaces any target
-previously in that stratum.
+@item break @var{+offset}
+@itemx break @var{-offset}
+Set a breakpoint some number of lines forward or back from the position
+at which execution stopped in the currently selected frame.
 
-To get rid of a target without replacing it, use the @samp{detach}
-command.  The related command @samp{attach} provides you with a way of
-choosing a particular running process as a new target. @xref{Attach}.
+@item break @var{linenum}
+Set a breakpoint at line @var{linenum} in the current source file.
+That file is the last file whose source text was printed.  This
+breakpoint will stop the program just before it executes any of the
+code on that line.
 
-@node Target Commands,  , Active Targets, Targets
-@section Commands for Managing Targets
+@item break @var{filename}:@var{linenum}
+Set a breakpoint at line @var{linenum} in source file @var{filename}.
 
-@table @code
-@item target @var{type} @var{parameters}
-Connects the _GDBN__ host environment to a target machine or process.  A
-target is typically a protocol for talking to debugging facilities.  You
-use the argument @var{type} to specify the type or protocol of the
-target machine; for example, @samp{target vxworks} for a TCP/IP link to
-a VxWorks system.
+@item break @var{filename}:@var{function}
+Set a breakpoint at entry to function @var{function} found in file
+@var{filename}.  Specifying a file name as well as a function name is
+superfluous except when multiple files contain similarly named
+functions.
+
+@item break *@var{address}
+Set a breakpoint at address @var{address}.  You can use this to set
+breakpoints in parts of the program which do not have debugging
+information or source files.
+
+@item break
+Set a breakpoint at the next instruction to be executed in the selected
+stack frame (@pxref{Stack}).  In any selected frame but the innermost,
+this will cause the program to stop as soon as control returns to that
+frame.  This is equivalent to a @samp{finish} command in the frame
+inside the selected frame.  If this is done in the innermost frame, _GDBN__
+will stop the next time it reaches the current location; this may be
+useful inside of loops.
+
+_GDBN__ normally ignores breakpoints when it resumes execution, until at
+least one instruction has been executed.  If it did not do this, you
+would be unable to proceed past a breakpoint without first disabling the
+breakpoint.  This rule applies whether or not the breakpoint already
+existed when the program stopped.
+
+@item break @dots{} if @var{cond}
+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.  @samp{@dots{}} stands for one of the possible
+arguments described above (or no argument) specifying where to break.
+@xref{Conditions}, for more information on breakpoint conditions.
+
+@item tbreak @var{args}
+@kindex tbreak
+Set a breakpoint enabled only for one stop.  @var{args} are the
+same as in the @samp{break} command, and the breakpoint is set in the same
+way, but the breakpoint is automatically disabled the first time it
+is hit.  @xref{Disabling}.
+
+@item rbreak @var{regex}
+@kindex rbreak
+Set a breakpoint on all functions matching @var{regex}.  This is
+useful for setting breakpoints on overloaded functions that are not
+members of any special classes.  This command sets an unconditional
+breakpoint on all matches, printing a list of all breakpoints it set.
+Once these breakpoints are set, they are treated just like the
+breakpoints set with the @samp{break} command.  They can be deleted,
+disabled, made conditional, etc., in the standard ways.
+
+@kindex watch 
+@item watch @var{expr}
+Set a watchpoint for an expression.
+@end table
+
+_GDBN__ allows you to set any number of breakpoints at the same place in the
+program.  There is nothing silly or meaningless about this.  When the
+breakpoints are conditional, this is even useful (@pxref{Conditions}).
+
+@node Exception Handling, Delete Breaks, Set Breaks, Breakpoints
+@subsection Breakpoints and Exceptions
+@cindex exception handlers
+
+Some languages, such as GNU C++, implement exception handling.  _GDBN__
+can be used to examine what caused the program to raise an exception
+and to list the exceptions the program is prepared to handle at a
+given point in time.
+
+@cindex raise exceptions
+GNU C++ raises an exception by calling a library function named
+@code{__raise_exception} which has the following ANSI C interface:
 
-Further @var{parameters} are interpreted by the target protocol, but
-typically include things like device names or host names to connect
-with, process numbers, and baud rates.  Executing 
 @example
-   target @var{type}
+    /* ADDR is where the exception identifier is stored.
+       ID is the exception identifier.  */
+    void __raise_exception (void **addr, void *id);
 @end example
 
 @noindent
-(without any parameters) will issue a message about what
-parameters are required for that target type.
+You can make the debugger catch all exceptions @emph{before} any stack
+unwinding takes place: set a breakpoint on @code{__raise_exception}
+(@pxref{Breakpoints}).  If you set a breakpoint in an exception handler
+instead, it may not be easy to find out where the exception was raised.
 
-@item info targets
-@kindex info targets
-Displays the names of all targets available.  Beware: the similar
-command @samp{info target} displays targets currently in use rather than
-all available ones.  @samp{info files} gives the same information as
-@samp{info target} (@pxref{Files}).
+By using a conditional breakpoint (@xref{Conditions}), you can cause
+the debugger to stop only when a specific exception is raised.
+Multiple conditional breakpoints can be used to stop the program when
+any of a number of exceptions are raised.
+
+@table @code
+@item catch @var{exceptions}
+@kindex catch
+
+Breakpoints can be set at active exception handlers by using the
+@samp{catch} command.  @var{exceptions} is a list of names of exceptions
+to catch.
 @end table
 
-Here are some common targets (available, or not, depending on _GDBN__
-configuration):
+You can use @samp{info catch} to list active exception handlers;
+@pxref{Frame Info}.
 
-@table @code
-@item target exec @var{prog}
-@kindex target exec
-An executable file.  @samp{target exec @var{prog}} is the same as
-@samp{exec-file @var{prog}}.
+There are currently some limitations to exception handling in _GDBN__.
+These will be corrected in a future release.
 
-@item target core @var{filename}
-@kindex target core
-A core dump file.  @samp{target core @var{filename}} is the same as
-@samp{core-file @var{filename}}.
+@itemize @bullet
+@item
+If you call a function interactively, _GDBN__ will normally return
+control to you when the function has finished executing.  If the call
+raises an exception, however, the call may bypass the mechanism that
+returns control to the user and cause the program to simply continue
+running until it hits a breakpoint, catches a signal that _GDBN__ is
+listening for, or exits.
+@item
+You cannot raise an exception interactively.
+@item
+You cannot interactively install an exception handler.
+@end itemize
 
-@item target remote @var{dev}
-@kindex target remote
-Remote serial target in _GDBP__-specific protocol.  The argument @var{dev}
-specifies what serial device to use for the connection (e.g.
-@code{/dev/ttya}).
+@node Delete Breaks, Disabling, Exception Handling, Breakpoints
+@subsection Deleting Breakpoints
 
-_if__(_AMD29K__)
-@item target amd-eb @var{dev} @var{speed} @var{PROG}
-@kindex target amd-eb
-@cindex AMD EB29K
-Remote PC-resident AMD EB29K board, attached over serial lines.
-@var{dev} is the serial device, as for @samp{target remote};
-@samp{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{AMD29K Remote}.
+@cindex clearing breakpoints, watchpoints
+@cindex deleting breakpoints, watchpoints
+It is often necessary to eliminate a breakpoint once it has done its job
+and you no longer want the program to stop there.  This is called
+@dfn{deleting} the breakpoint.  A breakpoint that has been deleted no
+longer exists in any sense; it is forgotten.
 
-_fi__(_AMD29K__)
-_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.
-@samp{/dev/ttya}.  
+With the @samp{clear} command you can delete breakpoints according to where
+they are in the program.  With the @samp{delete} command you can delete
+individual breakpoints by specifying their breakpoint numbers.
 
-_fi__(_I960__)
-_if__(_VXWORKS__)
-@item target vxworks @var{machinename}
-@kindex target vxworks
-A VxWorks system, attached via TCP/IP.  The argument @var{machinename}
-is the target system's machine name or IP address.
+It is not necessary to delete a breakpoint to proceed past it.  _GDBN__
+automatically ignores breakpoints on the first instruction to be executed
+when you continue execution without changing the execution address.
 
-_fi__(_VXWORKS__)
+@table @code
+@item clear
+@kindex clear
+Delete any breakpoints at the next instruction to be executed in the
+selected stack frame (@pxref{Selection}).  When the innermost frame
+is selected, this is a good way to delete a breakpoint that the program
+just stopped at.
+
+@item clear @var{function}
+@itemx clear @var{filename}:@var{function}
+Delete any breakpoints set at entry to the function @var{function}.
+
+@item clear @var{linenum}
+@itemx clear @var{filename}:@var{linenum}
+Delete any breakpoints set at or within the code of the specified line.
+
+@item delete breakpoints @var{bnums}@dots{}
+@itemx delete @var{bnums}@dots{}
+@itemx delete
+@kindex delete breakpoints
+@kindex delete
+Delete the breakpoints of the numbers specified as arguments.  If no
+argument is specified, delete all breakpoints.
 @end table
 
-_if__(_GENERIC__)
-Different targets are available on different configurations of _GDBN__; your
-configuration may have more or fewer targets.
-_fi__(_GENERIC__)
+@node Disabling, Conditions, Delete Breaks, Breakpoints
+@subsection Disabling Breakpoints
 
-@node Running, Stopping, Targets, Top
-@chapter Running Programs Under _GDBN__
+@cindex disabled breakpoints
+@cindex enabled breakpoints
+Rather than deleting a breakpoint, you might prefer to @dfn{disable} it.
+This makes the breakpoint inoperative as if it had been deleted, but
+remembers the information on the breakpoint so that you can @dfn{enable}
+it again later.
 
-@cindex running
-@kindex run
-To start your program under _GDBN__, use the @samp{run} command.  Except on
-VxWorks, the program must already have been specified using the
-@samp{file} or @samp{exec-file} command, or with an argument to _GDBN__
-(@pxref{Files}).
+You disable and enable breakpoints with the @samp{enable} and
+@samp{disable} commands, optionally specifying one or more breakpoint
+numbers as arguments.  Use @samp{info break} to print a list of
+breakpoints if you don't know which breakpoint numbers to use.
 
-On targets that support processes, @samp{run} creates an inferior
-process and makes that process run your program.  On other targets,
-@samp{run} jumps to the location it has recorded for the start of the
-program.
+A breakpoint can have any of four different states of enablement:
 
-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 the program.  (You
-can change it after starting the program, but such changes do not affect
-the program unless you start it over again.)  This information may be
-divided into three categories:
+@itemize @bullet
+@item
+Enabled.  The breakpoint will stop the program.  A breakpoint made
+with the @samp{break} command starts out in this state.
+@item
+Disabled.  The breakpoint has no effect on the program.
+@item
+Enabled once.  The breakpoint will stop the program, but
+when it does so it will become disabled.  A breakpoint made
+with the @samp{tbreak} command starts out in this state.
+@item
+Enabled for deletion.  The breakpoint will stop the program, but
+immediately after it does so it will be deleted permanently.
+@end itemize
 
-@table @asis
-@item The @i{arguments.}
-You specify the arguments to give the program as the arguments of the
-@samp{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
-(for example regular expression expansion or variable substitution) in
-describing the arguments.  In Unix systems, you can control which shell
-is used with the @code{SHELL} environment variable.
+You can use the following commands to enable or disable a breakpoint:
 
-@item The @i{environment.}
-The program normally inherits its environment from _GDBN__, but you can
-use the _GDBN__ commands @samp{set environment} and
-@samp{unset environment} to change parts of the environment that will
-be given to the program.@refill
+@table @code
+@item disable breakpoints @var{bnums}@dots{}
+@itemx disable @var{bnums}@dots{}
+@itemx disable
+@kindex disable breakpoints
+@kindex disable
+Disable the specified breakpoints---or all breakpoints, if none are
+listed.  A disabled breakpoint has no effect but is not forgotten.  All
+options such as ignore-counts, conditions and commands are remembered in
+case the breakpoint is enabled again later.
 
-@item The @i{working directory.}
-The program inherits its working directory from _GDBN__.  You can set _GDBN__'s
-working directory with the @samp{cd} command in _GDBN__.
+@item enable breakpoints @var{bnums}@dots{}
+@itemx enable @var{bnums}@dots{}
+@itemx enable
+@kindex enable breakpoints
+@kindex enable
+Enable the specified breakpoints (or all defined breakpoints).  They
+become effective once again in stopping the program, until you specify
+otherwise.
+
+@item enable breakpoints once @var{bnums}@dots{}
+@itemx enable once @var{bnums}@dots{}
+Enable the specified breakpoints temporarily.  Each will be disabled
+again the next time it stops the program (unless you have used one of
+these commands to specify a different state before that time comes).
+
+@item enable breakpoints delete @var{bnums}@dots{}
+@itemx enable delete @var{bnums}@dots{}
+Enable the specified breakpoints to work once and then die.  Each of
+the breakpoints will be deleted the next time it stops the program
+(unless you have used one of these commands to specify a different
+state before that time comes).
 @end table
 
-When you issue the @samp{run} command, your program begins to execute
-immediately.  @xref{Stopping}, for discussion of how to arrange for your
-program to stop.
+Save for a breakpoint set with @samp{tbreak} (@pxref{Set Breaks}),
+breakpoints that you set are enabled or disabled only when you use one
+of the commands above.  (The command @samp{until} can set and delete a
+breakpoint on its own, but it will not change the state of your
+breakpoints).
 
-Note that once your program has been started by the @samp{run} command,
-you may evaluate expressions that involve calls to functions in the
-inferior, using the @samp{print} or @samp{call} commands.  @xref{Data}.
+@node Conditions, Break Commands, Disabling, Breakpoints
+@subsection Break Conditions
+@cindex conditional breakpoints
+@cindex breakpoint conditions
 
-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.  In this process, it tries to retain your current breakpoints.
+The simplest sort of breakpoint breaks every time the 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.  (@xref{Expressions}).  A breakpoint with a
+condition evaluates the expression each time the program reaches it, and
+the program stops only if the condition is true.
 
-@menu
-* Arguments::			Specifying the arguments for your program.
-* Environment::			Specifying the environment for your program.
-* Working Directory::		Specifying the working directory for giving
-                       to your program when it is run.
-* Input/Output::		Specifying the program's standard input and output.
-* Attach::			Debugging a process started outside _GDBN__.
-* Kill Process::		Getting rid of the child process running your program.
-@end menu
+Break conditions may have side effects, and may even call functions in your
+program.  These may sound like strange things to do, but their effects are
+completely predictable unless there is another enabled breakpoint at the
+same address.  (In that case, _GDBN__ might see the other breakpoint first and
+stop the program without checking the condition of this one.)  Note that
+breakpoint commands are usually more convenient and flexible for the
+purpose of performing side effects when a breakpoint is reached
+(@pxref{Break Commands}).
 
-@node Arguments, Environment, Running, Running
-@section Your Program's Arguments
+Break conditions can be specified when a breakpoint is set, by using
+@samp{if} in the arguments to the @samp{break} command.  @xref{Set Breaks}.
+They can also be changed at any time with the @samp{condition} command:
 
-@cindex arguments (to your program)
-The arguments to your program are specified by the arguments of the 
-@samp{run} command.  They are passed to a shell, which expands wildcard
-characters and performs redirection of I/O, and thence to the program.
+@table @code
+@item condition @var{bnum} @var{expression}
+@kindex condition
+Specify @var{expression} as the break condition for breakpoint number
+@var{bnum}.  From now on, this breakpoint will stop the program only if
+the value of @var{expression} is true (nonzero, in C).  @var{expression}
+is not evaluated at the time the @samp{condition} command is given.
+When you call @samp{condition}, the expression you specify is checked
+immediately for syntactic correctness, and to determine whether symbols
+in it have referents in the context of your breakpoint.
+@xref{Expressions}.
 
-@samp{run} with no arguments uses the same arguments used by the previous
-@samp{run}.
+@item condition @var{bnum}
+Remove the condition from breakpoint number @var{bnum}.  It becomes
+an ordinary unconditional breakpoint.
+@end table
+
+@cindex ignore count (of breakpoint)
+A special case of a breakpoint condition is to stop only when the
+breakpoint has been reached a certain number of times.  This is so
+useful that there is a special way to do it, using the @dfn{ignore
+count} of the breakpoint.  Every breakpoint has an ignore count, which
+is an integer.  Most of the time, the ignore count is zero, and
+therefore has no effect.  But if the program reaches a breakpoint whose
+ignore count is positive, then instead of stopping, it just decrements
+the ignore count by one and continues.  As a result, if the ignore count
+value is @var{n}, the breakpoint will not stop the next @var{n} times it
+is reached.
 
-@kindex set args
 @table @code
-@item set args
-The command @samp{set args} can be used to specify the arguments to be used
-the next time the program is run.  If @samp{set args} has no arguments, it
-means to use no arguments the next time the program is run.  If you have
-run your program with arguments and want to run it again with no arguments,
-this is the only way to do so.
+@item ignore @var{bnum} @var{count}
+@kindex ignore
+Set the ignore count of breakpoint number @var{bnum} to @var{count}.
+The next @var{count} times the breakpoint is reached, your program's
+execution will not stop; other than to decrement the ignore count, _GDBN__
+takes no action.
 
-@item show args
-@kindex show args
-Show the arguments to give your program when it is started.
+To make the breakpoint stop the next time it is reached, specify
+a count of zero.
+
+@item continue @var{count}
+@itemx cont @var{count}
+@itemx c @var{count}
+@itemx fg @var{count}
+@kindex cont @var{count}
+@kindex continue @var{count}
+Continue execution of the program, setting the ignore count of the
+breakpoint that the program stopped at to @var{count} minus one.
+Thus, the program will not stop at this breakpoint until the
+@var{count}'th time it is reached.
+
+This command is allowed only when the program stopped due to a
+breakpoint.  At other times, the argument to @samp{cont} is ignored.
+
+The synonym @samp{fg} is provided purely for convenience, and has
+exactly the same behavior as other forms of the command.
 @end table
 
-@node Environment, Working Directory, Arguments, Running
-@section Your Program's Environment
+If a breakpoint has a positive ignore count and a condition, the condition
+is not checked.  Once the ignore count reaches zero, the condition will
+be checked.
 
-@cindex environment (of your program)
-The @dfn{environment} consists of a set of @dfn{environment variables} and
-their values.  Environment variables conventionally record such things as
-your user name, your home directory, your terminal type, and your search
-path for programs to run.  Usually you set up environment variables with
-the shell and they are inherited by all the other programs you run.  When
-debugging, it can be useful to try running the program with different
-environments without having to start the debugger over again.
+Note that 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}.
+
+@node Break Commands, Error in Breakpoints, Conditions, Breakpoints
+@subsection Commands Executed on Breaking
+
+@cindex breakpoint commands
+You can give any breakpoint a series of commands to execute when the
+program stops due to that breakpoint.  For example, you might want to
+print the values of certain expressions, or enable other breakpoints.
+
+@table @code
+@item commands @var{bnum}
+@kindex commands
+Specify a list of commands for breakpoint number @var{bnum}.  The commands
+themselves appear on the following lines.  Type a line containing just
+@samp{end} to terminate the commands.
+
+To remove all commands from a breakpoint, use the command
+@samp{commands} and follow it immediately by @samp{end}; that is, give
+no commands.
+
+With no arguments, @samp{commands} refers to the last breakpoint set
+(not to the breakpoint most recently encountered).
+@end table
+
+You can use breakpoint commands to start the program up again.  Simply
+use the @samp{cont} command, or @samp{step}, or any other command to
+resume execution.  However, if you do this, any further commands in the
+same breakpoint's command list are ignored.  When the program stops
+again, _GDBN__ will act according to the cause of that stop.
+
+@kindex silent
+If the first command specified is @samp{silent}, the usual message about
+stopping at a breakpoint is not printed.  This may be desirable for
+breakpoints that are to print a specific message and then continue.
+If the remaining commands too print nothing, you will see no sign that
+the breakpoint was reached at all.  @samp{silent} is not really a command;
+it is meaningful only at the beginning of the commands for a breakpoint.
 
-@table @code
-@item show environment @var{varname}
-@kindex show environment
-Print the value of environment variable @var{varname} to be given to
-your program when it is started.
+The commands @samp{echo} and @samp{output} that allow you to print precisely
+controlled output are often useful in silent breakpoints.  @xref{Output}.
 
-@item show environment
-Print the names and values of all environment variables to be given to
-your program when it is started.
+For example, here is how you could use breakpoint commands to print the
+value of @code{x} at entry to @code{foo} whenever it is positive.
 
-@item set environment @var{varname} @var{value}
-@itemx set environment @var{varname} = @var{value}
-@kindex set environment
-Sets environment variable @var{varname} to @var{value}, for your program
-only, not for _GDBN__ itself.  @var{value} may be any string; the values of
-environment variables are just strings, and any interpretation is
-supplied by your program itself.  The @var{value} parameter is optional;
-if it is eliminated, the variable is set to a null value.
+_0__@example
+break foo if x>0
+commands
+silent
+echo x is\040
+output x
+echo \n
+cont
+end
+_1__@end example
 
-For example, this command:
+One application for breakpoint commands is to correct one bug so you can
+test another.  Put a breakpoint just after the erroneous line of code, give
+it a condition to detect the case in which something erroneous has been
+done, and give it commands to assign correct values to any variables that
+need them.  End with the @samp{cont} command so that the program does not
+stop, and start with the @samp{silent} command so that no output is
+produced.  Here is an example:
 
 @example
-set env USER = foo
+break 403
+commands
+silent
+set x = y + 4
+cont
+end
 @end example
 
-@noindent
-tells the program, when subsequently run, to assume it is being run
-on behalf of the user named @samp{foo}.
+One deficiency in the operation of automatically continuing breakpoints
+under Unix appears when your program uses raw mode for the terminal.
+_GDBN__ switches back to its own terminal modes (not raw) before executing
+commands, and then must switch back to raw mode when your program is
+continued.  This causes any pending terminal input to be lost. 
+In the GNU system, this will be fixed by changing the behavior of
+terminal modes.
 
-@item delete environment @var{varname}
-@itemx unset environment @var{varname}
-@kindex delete environment
-@kindex unset environment
-Remove variable @var{varname} from the environment to be passed to your
-program.  This is different from @samp{set env @var{varname}@ =};
-@samp{delete environment} removes the variable from the environment,
-rather than assigning it an empty value.  This command can be
-abbreviated @samp{d e}.
-@end table
+Under Unix, when you have this problem, you might be able to get around
+it by putting your actions into the breakpoint condition instead of
+commands.  For example
 
-@node Working Directory, Input/Output, Environment, Running
-@section Your Program's Working Directory
+@example
+condition 5  (x = y + 4), 0
+@end example
 
-@cindex working directory (of your program)
-Each time you start your program with @samp{run}, it inherits its
-working directory from the current working directory of _GDBN__.  _GDBN__'s
-working directory is initially whatever it inherited from its parent
-process (typically the shell), but you can specify a new working
-directory in _GDBN__ with the @samp{cd} command.
+@noindent
+specifies a condition expression (@xref{Expressions}) that will change
+@code{x} as needed, then always have the value 0 so the program will not
+stop.  Loss of input is avoided here because break conditions are
+evaluated 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.
 
-The _GDBN__ working directory also serves as a default for the commands
-that specify files for _GDBN__ to operate on.  @xref{Files}.
+@node Error in Breakpoints,  , Break Commands, Breakpoints
+@subsection ``Cannot Insert Breakpoints''
 
-@table @code
-@item cd @var{directory}
-@kindex cd
-Set _GDBN__'s working directory to @var{directory}.
+@c FIXME: "cannot insert breakpoints" error, v unclear.  
+@c        Q in pending mail to Gilmore. [e-mail], 26mar91
+Under some operating systems, breakpoints cannot be used in a program if
+any other process is running that program.  In this situation,
+attempting to run or continue a program with a breakpoint will cause _GDBN__
+to stop the other process.
 
-@item pwd
-@kindex pwd
-Print _GDBN__'s working directory.
-@end table
+When this happens, you have three ways to proceed:
 
-@node Input/Output, Attach, Working Directory, Running
-@section Your Program's Input and Output
+@enumerate
+@item
+Remove or disable the breakpoints, then continue.
 
-@cindex redirection
-@cindex i/o
-@cindex terminal
-@cindex controlling terminal
-By default, the program you run under _GDBN__ does input and output to the same
-terminal that _GDBN__ uses.
+@item
+Suspend _GDBN__, and copy the file containing the program to a new name.
+Resume _GDBN__ and use the @samp{exec-file} command to specify that _GDBN__
+should run the program under that name.  Then start the program again.
 
-You can redirect the program's input and/or output using @samp{sh}-style
-redirection commands in the @samp{run} command.  For example,
+@item
+Relink the program so that the text segment is nonsharable, using the
+linker option @samp{-N}.  The operating system limitation may not apply
+to nonsharable executables.
+@end enumerate
 
-@example
-run > outfile
-@end example
+@node Continuing, Stepping, Breakpoints, Stopping
+@section Continuing
 
-@noindent
-starts the program, diverting its output to the file @file{outfile}.
+After your program stops, most likely you will want it to run some more if
+the bug you are looking for has not happened yet.
 
-@kindex tty
-Another way to specify where the program should do input and output is
-with the @samp{tty} command.  This command accepts a file name as
-argument, and causes this file to be the default for future @samp{run}
-commands.  It also resets the controlling terminal for the child
-process, for future @samp{run} commands.  For example,
+@table @code
+@item continue
+@item cont
+@kindex cont
+@kindex continue
+Continue running the program at the place where it stopped.
+@end table
 
-@example
-tty /dev/ttyb
-@end example
+If the program stopped at a breakpoint, the place to continue running
+is the address of the breakpoint.  You might expect that continuing would
+just stop at the same breakpoint immediately.  In fact, @samp{cont}
+takes special care to prevent that from happening.  You do not need
+to delete the breakpoint to proceed through it after stopping at it.
 
-@noindent
-directs that processes started with subsequent @samp{run} commands
-default to do input and output on the terminal @file{/dev/ttyb} and have
-that as their controlling terminal.
+You can, however, specify an ignore-count for the breakpoint that the
+program stopped at, by means of an argument to the @samp{cont} command.
+@xref{Conditions}.
 
-An explicit redirection in @samp{run} overrides the @samp{tty} command's
-effect on input/output redirection, but not its effect on the
-controlling terminal.
+If the program stopped because of a signal other than @code{SIGINT} or
+@code{SIGTRAP}, continuing will cause the program to see that signal.
+You may not want this to happen.  For example, if the program stopped
+due to some sort of memory reference error, you might store correct
+values into the erroneous variables and continue, hoping to see more
+execution; but the program would probably terminate immediately as
+a result of the fatal signal once it sees the signal.  To prevent this,
+you can continue with @samp{signal 0}.  @xref{Signaling}.  You can
+also act in advance to control what signals your program will see, using
+the @samp{handle} command (@pxref{Signals}). 
 
-When you use the @samp{tty} command or redirect input in the @samp{run}
-command, only the @emph{input for your program} is affected.  The input
-for _GDBN__ still comes from your terminal.
+@node Stepping,  , Continuing, Stopping
+@section Stepping
 
-@node Attach, Kill Process, Input/Output, Running
-@section Debugging an Already-Running Process
-@kindex attach
-@cindex attach
+@cindex stepping
+@dfn{Stepping} means setting your program in motion for a limited time, so
+that control will return automatically to the debugger after one line of
+code or one machine instruction.  Breakpoints are active during stepping
+and the program will stop for them even if it has not gone as far as the
+stepping command specifies.
 
 @table @code
-@item attach @var{process--id}
-This command attaches to a running process, if your currently selected
-target supports processes.  (@samp{info files} will show your active
-targets).  The command takes as argument a process ID.
+@item step
+@kindex step
+Continue running the program until control reaches a different line,
+then stop it and return control to the debugger.  This command is
+abbreviated @samp{s}.
 
-You specify a process ID to debug an already-running process that was
-started outside of _GDBN__.  (The usual way to find out the process-id of
-a Unix process is with the @code{ps} utility, or with the @code{jobs -l}
-shell command.)  In this case, you must have permission to send the
-process a signal, and it must have the same effective user ID as the
-debugger.
-@end table
+This command may be given when control is within a function for which
+there is no debugging information.  In that case, execution will proceed
+until control reaches a different function, or is about to return from
+this function.  An argument repeats this action.
 
-When using @samp{attach}, you should first use the @samp{file} command
-to specify the program running in the process and load its symbol table.
+@item step @var{count}
+Continue running as in @samp{step}, but do so @var{count} times.  If a
+breakpoint is reached or a signal not related to stepping occurs before
+@var{count} steps, stepping stops right away.
 
-The first thing _GDBN__ does after arranging to debug the process is to stop
-it.  You can examine and modify an attached process with all the _GDBN__
-commands that ordinarily available when you start processes with
-@samp{run}.  You can insert breakpoints; you can step and continue; you
-can modify storage.  If you would rather the process continue running,
-you may use the @samp{continue} command after attaching _GDBN__ to the
-process.
+@item next
+@kindex next
+Similar to @samp{step}, but any function calls appearing within the line of
+code are executed without stopping.  Execution stops when control reaches a
+different line of code at the stack level which was executing when the
+@samp{next} command was given.  This command is abbreviated @samp{n}.
 
-@kindex detach
-When you have finished debugging the attached process, you can use the
-@samp{detach} command to release it from _GDBN__'s control.  Detaching
-the process continues its execution.  After the @samp{detach} command,
-that process and _GDBN__ become completely independent once more, and you
-are ready to @samp{attach} another process or start one with @samp{run}.
+An argument is a repeat count, as in @samp{step}.
 
-If you exit _GDBN__ or use the @samp{run} command while you have an attached
-process, you kill that process.  By default, you will be asked for
-confirmation if you try to do either of these things; you can control
-whether or not this happens by using the @samp{set caution} command
-(@pxref{User Interface}).
+@samp{next} within a function without debugging information acts as does
+@samp{step}, but any function calls appearing within the code of the
+function are executed without stopping.
+
+@item finish
+@kindex finish
+Continue running until just after the selected stack frame returns (or
+until there is some other reason to stop, such as a fatal signal or a
+breakpoint).  Print value returned by the selected stack frame (if any).
+
+Contrast this with the @samp{return} command (@pxref{Returning}).
 
-@node Kill Process,  , Attach, Running
-@section Killing the Child Process
+@item until
+@kindex until
+This command is used to avoid single stepping through a loop more than
+once.  It is like the @samp{next} command, except that when @samp{until}
+encounters a jump, it automatically continues execution until the
+program counter is greater than the address of the jump.
 
-@table @code
-@item kill
-@kindex kill
-Kill the child process in which your program is running under _GDBN__.
-@end table
+This means that when you reach the end of a loop after single stepping
+though it, @samp{until} will cause the program to continue execution
+until the loop is exited.  In contrast, a @samp{next} command at the end
+of a loop will simply step back to the beginning of the loop, which
+would force you to step through the next iteration.
 
-This command is useful if you wish to debug a core dump instead.  _GDBN__
-ignores any core dump file if it is actually running the program.
+@samp{until} always stops the program if it attempts to exit the current
+stack frame.
 
-On some operating systems, you can't execute your program in another
-process while breakpoints are active inside _GDBN__.  The @samp{kill}
-command is also useful in this situation, if you wish to run the program
-outside the debugger.
+@samp{until} may produce somewhat counterintuitive results if the order
+of the source lines does not match the actual order of execution.  For
+example, in a typical C @code{for}-loop, the third expression in the
+@code{for}-statement (the loop-step expression) is executed after the
+statements in the body of the loop, but is written before them.
+Therefore, the @samp{until} command would appear to step back to the
+beginning of the loop when it advances to this expression.  However, it
+has not really done so, not in terms of the actual machine code.
 
-The @samp{kill} command is also useful if you wish to recompile and
-relink the program, since on many systems it is impossible to modify an
-executable file which is running in a process.  In this case, when you
-next type @samp{run}, _GDBN__ will notice that the file has changed, and
-will re-read the symbol table (while trying to preserve your current
-breakpoint settings).
+Note that @samp{until} with no argument works by means of single
+instruction stepping, and hence is slower than @samp{until} with an
+argument.
 
-@node Stopping, Stack, Running, Top
-@chapter Stopping and Continuing
+@item until @var{location}
+Continue running the program until either the specified location is
+reached, or the current (innermost) stack frame returns.  @var{location}
+is any of the forms of argument acceptable to @samp{break} (@pxref{Set
+Breaks}).  This form of the command uses breakpoints, and hence is
+quicker than @samp{until} without an argument.
 
-When you run a program normally, it runs until it terminates.  The
-principal purpose of using a debugger is so that you can stop it before
-that point; or so that if the program runs into trouble you can
-investigate and find out why.
+@item stepi
+@itemx si
+@kindex stepi
+@kindex si
+Execute one machine instruction, then stop and return to the debugger.
 
-@menu
-* Signals::			Fatal signals in your program just stop it;
-                 then you can use _GDBN__ to see what is going on.
-* Breakpoints::			Breakpoints let you stop your program when it
-                 reaches a specified point in the code.
-                 an expression changes.
-* Continuing::			Resuming execution until the next signal or breakpoint.
-* Stepping::			Stepping runs the program a short distance and
-                 then stops it wherever it has come to.
-@end menu
+It is often useful to do @samp{display/i $pc} when stepping by machine
+instructions.  This will cause the next instruction to be executed to
+be displayed automatically at each stop.  @xref{Auto Display}.
 
-@node Signals, Breakpoints, Stopping, Stopping
-@section Signals
-@cindex signals
+An argument is a repeat count, as in @samp{step}.
 
-A signal is an asynchronous event that can happen in a program.  The
-operating system defines the possible kinds of signals, and gives each kind
-a name and a number.  For example, @code{SIGINT} is the signal a program
-gets when you type @kbd{Ctrl-c}; @code{SIGSEGV} is the signal a program
-gets from referencing a place in memory far away from all the areas in use;
-@code{SIGALRM} occurs when the alarm clock timer goes off (which happens
-only if the program has requested an alarm).
+@item nexti
+@itemx ni
+@kindex nexti
+@kindex ni
+Execute one machine instruction, but if it is a subroutine call,
+proceed until the subroutine returns.
 
-@cindex fatal signals
-Some signals, including @code{SIGALRM}, are a normal part of the
-functioning of the program.  Others, such as @code{SIGSEGV}, indicate
-errors; these signals are @dfn{fatal} (kill the program immediately) if the
-program has not specified in advance some other way to handle the signal.
-@code{SIGINT} does not indicate an error in the program, but it is normally
-fatal so it can carry out the purpose of @kbd{Ctrl-c}: to kill the program.
+An argument is a repeat count, as in @samp{next}.
+@end table
 
-_GDBN__ has the ability to detect any occurrence of a signal in the program
-running under _GDBN__'s control.  You can tell _GDBN__ in advance what to do for
-each kind of signal.
+A typical technique for using stepping is to put a breakpoint
+(@pxref{Breakpoints}) at the beginning of the function or the section of
+the program in which a problem is believed to lie, and then step through
+the suspect area, examining the variables that are interesting, until the
+problem happens.
 
-@cindex handling signals
-Normally, _GDBN__ is set up to ignore non-erroneous signals like @code{SIGALRM}
-(so as not to interfere with their role in the functioning of the program)
-but to stop the program immediately whenever an error signal happens.
-You can change these settings with the @samp{handle} command.
+The @samp{cont} command can be used after stepping to resume execution
+until the next breakpoint or signal.
 
-@table @code
-@item info signal
-@kindex info signal
-Print a table of all the kinds of signals and how _GDBN__ has been told to
-handle each one.  You can use this to see the signal numbers of all
-the defined types of signals.
+@node Stack, Source, Stopping, Top
+@chapter Examining the Stack
 
-@item handle @var{signal} @var{keywords}@dots{}
-@kindex handle
-Change the way _GDBN__ handles signal @var{signal}.  @var{signal} can be the
-number of a signal or its name (with or without the @samp{SIG} at the
-beginning).  The @var{keywords} say what change to make.
-@end table
+When your program has stopped, the first thing you need to know is where it
+stopped and how it got there.
 
-The keywords allowed by the @samp{handle} command can be abbreviated.
-Their full names are
+@cindex call stack
+Each time your program performs a function call, the information about
+where in the program the call was made from is saved in a block of data
+called a @dfn{stack frame}.  The frame also contains the arguments of the
+call and the local variables of the function that was called.  All the
+stack frames are allocated in a region of memory called the @dfn{call
+stack}.
 
-@table @code
-@item nostop
-_GDBN__ should not stop the program when this signal happens.  It may
-still print a message telling you that the signal has come in.
+When your program stops, the _GDBN__ commands for examining the stack allow you
+to see all of this information.
 
-@item stop
-_GDBN__ should stop the program when this signal happens.  This implies
-the @samp{print} keyword as well.
+One of the stack frames is @dfn{selected} by _GDBN__ and many _GDBN__ commands
+refer implicitly to the selected frame.  In particular, whenever you ask
+_GDBN__ for the value of a variable in the program, the value is found in the
+selected frame.  There are special _GDBN__ commands to select whichever frame
+you are interested in.
 
-@item print
-_GDBN__ should print a message when this signal happens.
+When the program stops, _GDBN__ automatically selects the currently executing
+frame and describes it briefly as the @samp{frame} command does
+(@pxref{Frame Info, Info}).
 
-@item noprint
-_GDBN__ should not mention the occurrence of the signal at all.  This
-implies the @samp{nostop} keyword as well.
+@menu
+* Frames::			Explanation of stack frames and terminology.
+* Backtrace::			Summarizing many frames at once.
+* Selection::			How to select a stack frame.
+* Frame Info::			Information on a Frame
+@end menu
 
-@item pass
-_GDBN__ should allow the program to see this signal; the program will be
-able to handle the signal, or may be terminated if the signal is fatal
-and not handled.
+@node Frames, Backtrace, Stack, Stack
+@section Stack Frames
 
-@item nopass
-_GDBN__ should not allow the program to see this signal.
-@end table
+@cindex frame
+@cindex stack frame
+The call stack is divided up into contiguous pieces called @dfn{stack
+frames}, or @dfn{frames} for short; each frame is the data associated
+with one call to one function.  The frame contains the arguments given
+to the function, the function's local variables, and the address at
+which the function is executing.
 
-When a signal has been set to stop the program, the program cannot see the
-signal until you continue.  It will see the signal then, if @samp{pass} is
-in effect for the signal in question @i{at that time}.  In other words,
-after _GDBN__ reports a signal, you can use the @samp{handle} command with
-@samp{pass} or @samp{nopass} to control whether that signal will be seen by
-the program when you later continue it.
+@cindex initial frame
+@cindex outermost frame
+@cindex innermost frame
+When your program is started, the stack has only one frame, that of the
+function @code{main}.  This is called the @dfn{initial} frame or the
+@dfn{outermost} frame.  Each time a function is called, a new frame is
+made.  Each time a function returns, the frame for that function invocation
+is eliminated.  If a function is recursive, there can be many frames for
+the same function.  The frame for the function in which execution is
+actually occurring is called the @dfn{innermost} frame.  This is the most
+recently created of all the stack frames that still exist.
 
-You can also use the @samp{signal} command to prevent the program from
-seeing a signal, or cause it to see a signal it normally would not see,
-or to give it any signal at any time.  @xref{Signaling}.
+@cindex frame pointer
+Inside your program, stack frames are identified by their addresses.  A
+stack frame consists of many bytes, each of which has its own address; each
+kind of computer has a convention for choosing one of those bytes whose
+address serves as the address of the frame.  Usually this address is kept
+in a register called the @dfn{frame pointer register} while execution is
+going on in that frame.
 
-@node Breakpoints, Continuing, Signals, Stopping
-@section Breakpoints
+@cindex frame number
+_GDBN__ assigns numbers to all existing stack frames, starting with zero for
+the innermost frame, one for the frame that called it, and so on upward.
+These numbers do not really exist in your program; they are to give you a
+way of talking about stack frames in _GDBN__ commands.
 
-@cindex breakpoints
-A @dfn{breakpoint} makes your program stop whenever a certain point in the
-program is reached.  You set breakpoints explicitly with _GDBN__ commands,
-specifying the place where the program should stop by line number, function
-name or exact address in the program.  You can add various other conditions
-to control whether the program will stop.
+@cindex selected frame
+Many _GDBN__ commands refer implicitly to one stack frame, called the
+@dfn{selected} stack frame.  You can select any frame using one set of
+_GDBN__ commands, and then other commands will operate on that frame.  When
+your program stops, _GDBN__ automatically selects the innermost frame.
 
-Each breakpoint is assigned a number when it is created; these numbers are
-successive integers starting with 1.  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 the program until you
-enable it again.
+@cindex frameless execution
+Some compilers allow functions to be compiled to run without a frame
+reserved for them on the stack. (For example, the _GCC__ option
+@samp{-fomit-frame-pointer} will generate functions without a frame.)
+This is occasionally done with heavily used library functions to save
+the frame setup time.  _GDBN__ has limited facilities for dealing with these
+function invocations; if the innermost function invocation has no stack
+frame, _GDBN__ will give it a virtual stack frame of 0 and correctly allow
+tracing of the function call chain.  Results are undefined if a function
+invocation besides the innermost one is frameless.
 
-@table @code
-@kindex info break
-@kindex $_
-@item info break
-The command @samp{info break} prints a list of all breakpoints set and not
-deleted, showing their numbers, where in the program they are, and any
-special features in use for them.  Disabled breakpoints are included in the
-list, but marked as disabled.  @samp{info break} with a breakpoint number
-as argument lists only that breakpoint.  The convenience variable @code{$_}
-and the default examining-address for the @samp{x} command are set to the
-address of the last breakpoint listed (@pxref{Memory}).
+@node Backtrace, Selection, Frames, Stack
+@section Backtraces
 
-@kindex info watch
-@item info watch
-This command prints a list of watchpoints. 
+A backtrace is a summary of how the program got where it is.  It shows one
+line per frame, for many frames, starting with the currently executing
+frame (frame zero), followed by its caller (frame one), and on up the
+stack.
 
-@cindex watchpoints
-A @dfn{watchpoint} is a special breakpoint that stops your program when
-the value of an expression changes.  You can use a watchpoint to stop
-execution whenever the value of an expression changes, without having to
-predict a particular place in the inferior process where this may
-happen.  Aside from the different syntax in setting a watchpoint, it is
-managed exactly like any other breakpoint and is enabled, disabled, and
-deleted using exactly the same commands.
+@table @code
+@item backtrace
+@itemx bt
+@kindex backtrace
+@kindex bt
+Print a backtrace of the entire stack: one line per frame for all
+frames in the stack.
 
-Watchpoints currently execute two orders of magnitude more slowly than
-other breakpoints, but this can well be worth it to catch errors where
-you have no clue what part of your program is the culprit.  Some
-processors provide special hardware to implement this feature; future
-releases of _GDBN__ will use such hardware if it is available.
+You can stop the backtrace at any time by typing the system interrupt
+character, normally @kbd{Control-C}.
+
+@item backtrace @var{n}
+@itemx bt @var{n}
+Similar, but print only the innermost @var{n} frames.
 
+@item backtrace @var{-n}
+@itemx bt @var{-n}
+Similar, but print only the outermost @var{n} frames.
 @end table
 
-@menu
-* Set Breaks::			How to establish breakpoints.
-* Exception Handling::		How _GDBN__ supports exception handling for C++.
-* Delete Breaks::		How to remove breakpoints no longer needed.
-* Disabling::			How to disable breakpoints (turn them off temporarily).
-* Conditions::			Making extra conditions on whether to stop.
-* Break Commands::		Commands to be executed at a breakpoint.
-* Error in Breakpoints::	
-@end menu
+@kindex where
+@kindex info stack
+The names @samp{where} and @samp{info stack} are additional aliases
+for @samp{backtrace}.
 
-@node Set Breaks, Exception Handling, Breakpoints, Breakpoints
-@subsection Setting Breakpoints
+Every line in the backtrace shows the frame number and the function
+name.  The program counter value is also shown---unless you use
+@samp{set addressprint off}.
 
-@kindex break
-@kindex watch
-Breakpoints are set with the @samp{break} command (abbreviated @samp{b}).
-Watchpoints are set with the @samp{watch} command.
+If the function is in a source file whose symbol table data has been
+fully read, the backtrace shows the source file name and line number, as
+well as the arguments to the function.  When the line number is shown,
+the program counter value is omitted if it is at the beginning of the
+code for that line number.
 
-You have several ways to say where the breakpoint should go.
+Here is an example of a backtrace.  It was made with the command
+@samp{bt 3}, so it shows the innermost three frames.
 
-@table @code
-@item break @var{function}
-Set a breakpoint at entry to function @var{function}.
+@example
+#0  rtx_equal_p (x=(rtx) 0x8e58c, y=(rtx) 0x1086c4) \
+(/gp/rms/cc/rtlanal.c line 337)
+#1  0x246b0 in expand_call (...) (...)
+#2  0x21cfc in expand_expr (...) (...)
+(More stack frames follow...)
+@end example
 
-@item break @var{+offset}
-@itemx break @var{-offset}
-Set a breakpoint some number of lines forward or back from the position
-at which execution stopped in the currently selected frame.
+@noindent
+The functions @code{expand_call} and @code{expand_expr} are in a file
+whose symbol details have not been fully read.  Full detail is available
+for the function @code{rtx_equal_p}, which is in the file
+@file{rtlanal.c}.  Its arguments, named @code{x} and @code{y}, are shown
+with their typed values.
 
-@item break @var{linenum}
-Set a breakpoint at line @var{linenum} in the current source file.
-That file is the last file whose source text was printed.  This
-breakpoint will stop the program just before it executes any of the
-code on that line.
+@node Selection, Frame Info, Backtrace, Stack
+@section Selecting a Frame
 
-@item break @var{filename}:@var{linenum}
-Set a breakpoint at line @var{linenum} in source file @var{filename}.
+Most commands for examining the stack and other data in the program work on
+whichever stack frame is selected at the moment.  Here are the commands for
+selecting a stack frame; all of them finish by printing a brief description
+of the stack frame just selected.
 
-@item break @var{filename}:@var{function}
-Set a breakpoint at entry to function @var{function} found in file
-@var{filename}.  Specifying a file name as well as a function name is
-superfluous except when multiple files contain similarly named
-functions.
+@table @code
+@item frame @var{n}
+@kindex frame
+Select frame number @var{n}.  Recall that frame zero is the innermost
+(currently executing) frame, frame one is the frame that called the
+innermost one, and so on.  The highest-numbered frame is @code{main}'s
+frame.
 
-@item break *@var{address}
-Set a breakpoint at address @var{address}.  You can use this to set
-breakpoints in parts of the program which do not have debugging
-information or source files.
+@item frame @var{addr}
+Select the frame at address @var{addr}.  This is useful mainly if the
+chaining of stack frames has been damaged by a bug, making it
+impossible for _GDBN__ to assign numbers properly to all frames.  In
+addition, this can be useful when the program has multiple stacks and
+switches between them.
 
-@item break
-Set a breakpoint at the next instruction to be executed in the selected
-stack frame (@pxref{Stack}).  In any selected frame but the innermost,
-this will cause the program to stop as soon as control returns to that
-frame.  This is equivalent to a @samp{finish} command in the frame
-inside the selected frame.  If this is done in the innermost frame, _GDBN__
-will stop the next time it reaches the current location; this may be
-useful inside of loops.
+@item up @var{n}
+@kindex up
+Select the frame @var{n} frames up from the frame previously selected.
+For positive numbers @var{n}, this advances toward the outermost
+frame, to higher frame numbers, to frames that have existed longer.
+@var{n} defaults to one.
 
-_GDBN__ normally ignores breakpoints when it resumes execution, until at
-least one instruction has been executed.  If it did not do this, you
-would be unable to proceed past a breakpoint without first disabling the
-breakpoint.  This rule applies whether or not the breakpoint already
-existed when the program stopped.
+@item down @var{n}
+@kindex down
+Select the frame @var{n} frames down from the frame previously
+selected.  For positive numbers @var{n}, this advances toward the
+innermost frame, to lower frame numbers, to frames that were created
+more recently.  @var{n} defaults to one.
+@end table
 
-@item break @dots{} if @var{cond}
-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.  @samp{@dots{}} stands for one of the possible
-arguments described above (or no argument) specifying where to break.
-@xref{Conditions}, for more information on breakpoint conditions.
+All of these commands end by printing some information on the frame that
+has been selected: the frame number, the function name, the arguments, the
+source file and line number of execution in that frame, and the text of
+that source line.  For example:
 
-@item tbreak @var{args}
-@kindex tbreak
-Set a breakpoint enabled only for one stop.  @var{args} are the
-same as in the @samp{break} command, and the breakpoint is set in the same
-way, but the breakpoint is automatically disabled the first time it
-is hit.  @xref{Disabling}.
+@example
+#3  main (argc=3, argv=??, env=??) at main.c:67
+67        read_input_file (argv[i]);
+@end example
 
-@item rbreak @var{regex}
-@kindex rbreak
-Set a breakpoint on all functions matching @var{regex}.  This is
-useful for setting breakpoints on overloaded functions that are not
-members of any special classes.  This command sets an unconditional
-breakpoint on all matches, printing a list of all breakpoints it set.
-Once these breakpoints are set, they are treated just like the
-breakpoints set with the @samp{break} command.  They can be deleted,
-disabled, made conditional, etc., in the standard ways.
+After such a printout, the @samp{list} command with no arguments will print
+ten lines centered on the point of execution in the frame.  @xref{List}.
 
-@kindex watch 
-@item watch @var{expr}
-Set a watchpoint for an expression.
-@end table
+@table @code
+@item up-silently @var{n}
+@itemx down-silently @var{n}
+@kindex down-silently
+@kindex up-silently
+These two commands are variants of @samp{up} and @samp{down},
+respectively; they differ in that they do their work silently, without
+causing display of the new frame.  They are intended primarily for use
+in _GDBN__ command scripts, where the output might be unnecessary and
+distracting. 
 
-_GDBN__ allows you to set any number of breakpoints at the same place in the
-program.  There is nothing silly or meaningless about this.  When the
-breakpoints are conditional, this is even useful (@pxref{Conditions}).
+@end table
 
-@node Exception Handling, Delete Breaks, Set Breaks, Breakpoints
-@subsection Breakpoints and Exceptions
-@cindex exception handlers
+@node Frame Info,  , Selection, Stack
+@section Information on a Frame
 
-Some languages, such as GNU C++, implement exception handling.  _GDBN__
-can be used to examine what caused the program to raise an exception
-and to list the exceptions the program is prepared to handle at a
-given point in time.
+There are several other commands to print information about the selected
+stack frame.
 
-@cindex raise exceptions
-GNU C++ raises an exception by calling a library function named
-@code{__raise_exception} which has the following ANSI C interface:
+@table @code
+@item frame
+When used without any argument, this command does not change which frame
+is selected, but still prints a brief description of the currently
+selected stack frame.  It can be abbreviated @samp{f}.  With an
+argument, this command is used to select a stack frame; with no
+argument, it does not change which frame is selected, but still prints
+the same kind of information.
 
-@example
-    /* ADDR is where the exception identifier is stored.
-       ID is the exception identifier.  */
-    void __raise_exception (void **addr, void *id);
-@end example
+@item info frame
+@kindex info frame
+This command prints a verbose description of the selected stack frame,
+including the address of the frame, the addresses of the next frame in
+(called by this frame) and the next frame out (caller of this frame),
+the address of the frame's arguments, the program counter saved in it
+(the address of execution in the caller frame), and which registers
+were saved in the frame.  The verbose description is useful when
+something has gone wrong that has made the stack format fail to fit
+the usual conventions.
 
-@noindent
-You can make the debugger catch all exceptions @emph{before} any stack
-unwinding takes place: set a breakpoint on @code{__raise_exception}
-(@pxref{Breakpoints}).  If you set a breakpoint in an exception handler
-instead, it may not be easy to find out where the exception was raised.
+@item info frame @var{addr}
+Print a verbose description of the frame at address @var{addr},
+without selecting that frame.  The selected frame remains unchanged by
+this command.
 
-By using a conditional breakpoint (@xref{Conditions}), you can cause
-the debugger to stop only when a specific exception is raised.
-Multiple conditional breakpoints can be used to stop the program when
-any of a number of exceptions are raised.
+@item info args
+@kindex info args
+Print the arguments of the selected frame, each on a separate line.
 
-@table @code
-@item catch @var{exceptions}
-@kindex catch
+@item info locals
+@kindex info locals
+Print the local variables of the selected frame, each on a separate
+line.  These are all variables declared static or automatic within all
+program blocks that execution in this frame is currently inside of.
 
-Breakpoints can be set at active exception handlers by using the
-@samp{catch} command.  @var{exceptions} is a list of names of exceptions
-to catch.
+@item info catch
+@kindex info catch
+@cindex catch exceptions
+@cindex exception handlers
+Print a list of all the exception handlers that are active in the
+current stack frame given the current value of @code{pc}.  To see other
+exception handlers, visit the associated frame (using the @samp{up},
+@samp{down}, or @samp{frame} commands); then type @samp{info catch}.
+@xref{Exception Handling}.
 @end table
 
-You can use @samp{info catch} to list active exception handlers;
-@pxref{Frame Info}.
-
-There are currently some limitations to exception handling in _GDBN__.
-These will be corrected in a future release.
+@node Source, Data, Stack, Top
+@chapter Examining Source Files
 
-@itemize @bullet
-@item
-If you call a function interactively, _GDBN__ will normally return
-control to you when the function has finished executing.  If the call
-raises an exception, however, the call may bypass the mechanism that
-returns control to the user and cause the program to simply continue
-running until it hits a breakpoint, catches a signal that _GDBN__ is
-listening for, or exits.
-@item
-You cannot raise an exception interactively.
-@item
-You cannot interactively install an exception handler.
-@end itemize
+_GDBN__ knows which source files your program was compiled from, and
+can print parts of their text.  When your program stops, _GDBN__
+spontaneously prints the line it stopped in.  Likewise, when you
+select a stack frame (@pxref{Selection}), _GDBN__ prints the line
+which execution in that frame has stopped in.  You can also
+print parts of source files by explicit command.
 
-@node Delete Breaks, Disabling, Exception Handling, Breakpoints
-@subsection Deleting Breakpoints
+@menu
+* List::			Using the @samp{list} command to print source files.
+* Search::			Commands for searching source files.
+* Source Path::			Specifying the directories to search for source files.
+@end menu
 
-@cindex clearing breakpoints, watchpoints
-@cindex deleting breakpoints, watchpoints
-It is often necessary to eliminate a breakpoint once it has done its job
-and you no longer want the program to stop there.  This is called
-@dfn{deleting} the breakpoint.  A breakpoint that has been deleted no
-longer exists in any sense; it is forgotten.
+@node List, Search, Source, Source
+@section Printing Source Lines
 
-With the @samp{clear} command you can delete breakpoints according to where
-they are in the program.  With the @samp{delete} command you can delete
-individual breakpoints by specifying their breakpoint numbers.
+@kindex list
+@kindex l
+To print lines from a source file, use the @samp{list} command
+(abbreviated @samp{l}).  There are several ways to specify what part
+of the file you want to print.
 
-It is not necessary to delete a breakpoint to proceed past it.  _GDBN__
-automatically ignores breakpoints on the first instruction to be executed
-when you continue execution without changing the execution address.
+Here are the forms of the @samp{list} command most commonly used:
 
 @table @code
-@item clear
-@kindex clear
-Delete any breakpoints at the next instruction to be executed in the
-selected stack frame (@pxref{Selection}).  When the innermost frame
-is selected, this is a good way to delete a breakpoint that the program
-just stopped at.
+@item list @var{linenum}
+Print ten lines centered around line number @var{linenum} in the
+current source file.
 
-@item clear @var{function}
-@itemx clear @var{filename}:@var{function}
-Delete any breakpoints set at entry to the function @var{function}.
+@item list @var{function}
+Print ten lines centered around the beginning of function
+@var{function}.
 
-@item clear @var{linenum}
-@itemx clear @var{filename}:@var{linenum}
-Delete any breakpoints set at or within the code of the specified line.
+@item list
+Print ten more lines.  If the last lines printed were printed with a
+@samp{list} command, this prints ten 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}), this prints ten
+lines centered around that line.
 
-@item delete breakpoints @var{bnums}@dots{}
-@itemx delete @var{bnums}@dots{}
-@itemx delete
-@kindex delete breakpoints
-@kindex delete
-Delete the breakpoints of the numbers specified as arguments.  If no
-argument is specified, delete all breakpoints.
+@item list -
+Print ten lines just before the lines last printed.
 @end table
 
-@node Disabling, Conditions, Delete Breaks, Breakpoints
-@subsection Disabling Breakpoints
-
-@cindex disabled breakpoints
-@cindex enabled breakpoints
-Rather than deleting a breakpoint, you might prefer to @dfn{disable} it.
-This makes the breakpoint inoperative as if it had been deleted, but
-remembers the information on the breakpoint so that you can @dfn{enable}
-it again later.
+Repeating a @samp{list} command with @key{RET} discards the argument,
+so it is equivalent to typing just @samp{list}.  This is more useful
+than listing the same lines again.  An exception is made for an
+argument of @samp{-}; that argument is preserved in repetition so that
+each repetition moves up in the file.
 
-You disable and enable breakpoints with the @samp{enable} and
-@samp{disable} commands, optionally specifying one or more breakpoint
-numbers as arguments.  Use @samp{info break} to print a list of
-breakpoints if you don't know which breakpoint numbers to use.
+@cindex linespec
+In general, the @samp{list} command expects you to supply zero, one or two
+@dfn{linespecs}.  Linespecs specify source lines; there are several ways
+of writing them but the effect is always to specify some source line.
+Here is a complete description of the possible arguments for @samp{list}:
 
-A breakpoint can have any of four different states of enablement:
+@table @code
+@item list @var{linespec}
+Print ten lines centered around the line specified by @var{linespec}.
 
-@itemize @bullet
-@item
-Enabled.  The breakpoint will stop the program.  A breakpoint made
-with the @samp{break} command starts out in this state.
-@item
-Disabled.  The breakpoint has no effect on the program.
-@item
-Enabled once.  The breakpoint will stop the program, but
-when it does so it will become disabled.  A breakpoint made
-with the @samp{tbreak} command starts out in this state.
-@item
-Enabled for deletion.  The breakpoint will stop the program, but
-immediately after it does so it will be deleted permanently.
-@end itemize
+@item list @var{first},@var{last}
+Print lines from @var{first} to @var{last}.  Both arguments are
+linespecs.
 
-You can use the following commands to enable or disable a breakpoint:
+@item list ,@var{last}
+Print ten lines ending with @var{last}.
 
-@table @code
-@item disable breakpoints @var{bnums}@dots{}
-@itemx disable @var{bnums}@dots{}
-@itemx disable
-@kindex disable breakpoints
-@kindex disable
-Disable the specified breakpoints---or all breakpoints, if none are
-listed.  A disabled breakpoint has no effect but is not forgotten.  All
-options such as ignore-counts, conditions and commands are remembered in
-case the breakpoint is enabled again later.
+@item list @var{first},
+Print ten lines starting with @var{first}.
 
-@item enable breakpoints @var{bnums}@dots{}
-@itemx enable @var{bnums}@dots{}
-@itemx enable
-@kindex enable breakpoints
-@kindex enable
-Enable the specified breakpoints (or all defined breakpoints).  They
-become effective once again in stopping the program, until you specify
-otherwise.
+@item list +
+Print ten lines just after the lines last printed.
 
-@item enable breakpoints once @var{bnums}@dots{}
-@itemx enable once @var{bnums}@dots{}
-Enable the specified breakpoints temporarily.  Each will be disabled
-again the next time it stops the program (unless you have used one of
-these commands to specify a different state before that time comes).
+@item list -
+Print ten lines just before the lines last printed.
 
-@item enable breakpoints delete @var{bnums}@dots{}
-@itemx enable delete @var{bnums}@dots{}
-Enable the specified breakpoints to work once and then die.  Each of
-the breakpoints will be deleted the next time it stops the program
-(unless you have used one of these commands to specify a different
-state before that time comes).
+@item list
+As described in the preceding table.
 @end table
 
-Save for a breakpoint set with @samp{tbreak} (@pxref{Set Breaks}),
-breakpoints that you set are enabled or disabled only when you use one
-of the commands above.  (The command @samp{until} can set and delete a
-breakpoint on its own, but it will not change the state of your
-breakpoints).
-
-@node Conditions, Break Commands, Disabling, Breakpoints
-@subsection Break Conditions
-@cindex conditional breakpoints
-@cindex breakpoint conditions
-
-The simplest sort of breakpoint breaks every time the 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.  (@xref{Expressions}).  A breakpoint with a
-condition evaluates the expression each time the program reaches it, and
-the program stops only if the condition is true.
+Here are the ways of specifying a single source line---all the
+kinds of linespec.
 
-Break conditions may have side effects, and may even call functions in your
-program.  These may sound like strange things to do, but their effects are
-completely predictable unless there is another enabled breakpoint at the
-same address.  (In that case, _GDBN__ might see the other breakpoint first and
-stop the program without checking the condition of this one.)  Note that
-breakpoint commands are usually more convenient and flexible for the
-purpose of performing side effects when a breakpoint is reached
-(@pxref{Break Commands}).
+@table @code
+@item @var{linenum}
+Specifies line @var{linenum} of the current source file.
+When a @samp{list} command has two linespecs, this refers to
+the same source file as the first linespec.
 
-Break conditions can be specified when a breakpoint is set, by using
-@samp{if} in the arguments to the @samp{break} command.  @xref{Set Breaks}.
-They can also be changed at any time with the @samp{condition} command:
+@item +@var{offset}
+Specifies the line @var{offset} lines after the last line printed.
+When used as the second linespec in a @samp{list} command that has
+two, this specifies the line @var{offset} lines down from the
+first linespec.
 
-@table @code
-@item condition @var{bnum} @var{expression}
-@kindex condition
-Specify @var{expression} as the break condition for breakpoint number
-@var{bnum}.  From now on, this breakpoint will stop the program only if
-the value of @var{expression} is true (nonzero, in C).  @var{expression}
-is not evaluated at the time the @samp{condition} command is given.
-When you call @samp{condition}, the expression you specify is checked
-immediately for syntactic correctness, and to determine whether symbols
-in it have referents in the context of your breakpoint.
-@xref{Expressions}.
+@item -@var{offset}
+Specifies the line @var{offset} lines before the last line printed.
 
-@item condition @var{bnum}
-Remove the condition from breakpoint number @var{bnum}.  It becomes
-an ordinary unconditional breakpoint.
-@end table
+@item @var{filename}:@var{linenum}
+Specifies line @var{linenum} in the source file @var{filename}.
 
-@cindex ignore count (of breakpoint)
-A special case of a breakpoint condition is to stop only when the
-breakpoint has been reached a certain number of times.  This is so
-useful that there is a special way to do it, using the @dfn{ignore
-count} of the breakpoint.  Every breakpoint has an ignore count, which
-is an integer.  Most of the time, the ignore count is zero, and
-therefore has no effect.  But if the program reaches a breakpoint whose
-ignore count is positive, then instead of stopping, it just decrements
-the ignore count by one and continues.  As a result, if the ignore count
-value is @var{n}, the breakpoint will not stop the next @var{n} times it
-is reached.
+@item @var{function}
+Specifies the line of the open-brace that begins the body of the
+function @var{function}.
 
-@table @code
-@item ignore @var{bnum} @var{count}
-@kindex ignore
-Set the ignore count of breakpoint number @var{bnum} to @var{count}.
-The next @var{count} times the breakpoint is reached, your program's
-execution will not stop; other than to decrement the ignore count, _GDBN__
-takes no action.
+@item @var{filename}:@var{function}
+Specifies the line of the open-brace that begins the body of the
+function @var{function} in the file @var{filename}.  The file name is
+needed with a function name only for disambiguation of identically
+named functions in different source files.
 
-To make the breakpoint stop the next time it is reached, specify
-a count of zero.
+@item *@var{address}
+Specifies the line containing the program address @var{address}.
+@var{address} may be any expression.
+@end table
 
-@item continue @var{count}
-@itemx cont @var{count}
-@itemx c @var{count}
-@itemx fg @var{count}
-@kindex cont @var{count}
-@kindex continue @var{count}
-Continue execution of the program, setting the ignore count of the
-breakpoint that the program stopped at to @var{count} minus one.
-Thus, the program will not stop at this breakpoint until the
-@var{count}'th time it is reached.
+One other command is used to map source lines to program addresses.
 
-This command is allowed only when the program stopped due to a
-breakpoint.  At other times, the argument to @samp{cont} is ignored.
+@table @code
+@item info line @var{linenum}
+@kindex info line
+Print the starting and ending addresses of the compiled code for
+source line @var{linenum}.
 
-The synonym @samp{fg} is provided purely for convenience, and has
-exactly the same behavior as other forms of the command.
+@kindex $_
+The default examine address for the @samp{x} command is changed to the
+starting address of the line, so that @samp{x/i} is sufficient to
+begin examining the machine code (@pxref{Memory}).  Also, this address
+is saved as the value of the convenience variable @code{$_}
+(@pxref{Convenience Vars}).
 @end table
 
-If a breakpoint has a positive ignore count and a condition, the condition
-is not checked.  Once the ignore count reaches zero, the condition will
-be checked.
+@node Search, Source Path, List, Source
+@section Searching Source Files
+@cindex searching
+@kindex search
+@kindex forward-search
+@kindex reverse-search
 
-Note that you could achieve the effect of the ignore count with a
-condition such as @w{@samp{$foo-- <= 0}} using a debugger convenience
-variable that is decremented each time.  @xref{Convenience Vars}.
+There are two commands for searching through the current source file for a
+regular expression.
 
-@node Break Commands, Error in Breakpoints, Conditions, Breakpoints
-@subsection Commands Executed on Breaking
+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 @samp{fo}.  The synonym @samp{search @var{regexp}} is also supported.
 
-@cindex breakpoint commands
-You can give any breakpoint a series of commands to execute when the
-program stops due to that breakpoint.  For example, you might want to
-print the values of certain expressions, or enable other breakpoints.
+The command @samp{reverse-search @var{regexp}} checks each line, starting
+with the one before the last line listed and going backward, for a match
+for @var{regexp}.  It lists the line that is found.  You can abbreviate
+this command with as little as @samp{rev}.
 
-@table @code
-@item commands @var{bnum}
-@kindex commands
-Specify a list of commands for breakpoint number @var{bnum}.  The commands
-themselves appear on the following lines.  Type a line containing just
-@samp{end} to terminate the commands.
+@node Source Path,  , Search, Source
+@section Specifying Source Directories
 
-To remove all commands from a breakpoint, use the command
-@samp{commands} and follow it immediately by @samp{end}; that is, give
-no commands.
+@cindex source path
+@cindex directories for source files
+Executable programs sometimes do not record the directories of the source
+files from which they were compiled, just the names.  Even when they do,
+the directories could be moved between the compilation and your debugging
+session.  _GDBN__ remembers a list of directories to search for source files;
+this is called the @dfn{source path}.  Each time _GDBN__ wants a source file,
+it tries all the directories in the list, in the order they are present
+in the list, until it finds a file with the desired name.  Note that
+the executable search path is @emph{not} used for this purpose.  Neither is
+the current working directory, unless it happens to be in the source
+path.
 
-With no arguments, @samp{commands} refers to the last breakpoint set
-(not to the breakpoint most recently encountered).
-@end table
+If it can't find a source file in the source path, and the object program
+records what directory it was compiled in, _GDBN__ tries that directory too.
+If the source path is empty, and there is no record of the compilation
+directory, _GDBN__ will, as a last resort, look in the current directory.
 
-You can use breakpoint commands to start the program up again.  Simply
-use the @samp{cont} command, or @samp{step}, or any other command to
-resume execution.  However, if you do this, any further commands in the
-same breakpoint's command list are ignored.  When the program stops
-again, _GDBN__ will act according to the cause of that stop.
+Whenever you reset or rearrange the source path, _GDBN__ will clear out
+any information it has cached about where source files are found, where
+each line is in the file, etc.
 
-@kindex silent
-If the first command specified is @samp{silent}, the usual message about
-stopping at a breakpoint is not printed.  This may be desirable for
-breakpoints that are to print a specific message and then continue.
-If the remaining commands too print nothing, you will see no sign that
-the breakpoint was reached at all.  @samp{silent} is not really a command;
-it is meaningful only at the beginning of the commands for a breakpoint.
+@kindex directory
+When you start _GDBN__, its source path is empty.
+To add other directories, use the @samp{directory} command.
 
-The commands @samp{echo} and @samp{output} that allow you to print precisely
-controlled output are often useful in silent breakpoints.  @xref{Output}.
+@table @code
+@item directory @var{dirnames...}
+Add directory @var{dirname} to the front of the source path.  Several
+directory names may be given to this command, separated by whitespace or
+@samp{:}.  If a name is already in the source path, it is moved to the
+front of the path, so it will be searched sooner.
 
-For example, here is how you could use breakpoint commands to print the
-value of @code{x} at entry to @code{foo} whenever it is positive.
+@item directory
+Reset the source path to empty again.  This requires confirmation.
 
-@example
-break foo if x>0
-commands
-silent
-echo x is\040
-output x
-echo \n
-cont
-end
-@end example
+@item info directories
+@kindex info directories
+Print the source path: show which directories it contains.
+@end table
 
-One application for breakpoint commands is to correct one bug so you can
-test another.  Put a breakpoint just after the erroneous line of code, give
-it a condition to detect the case in which something erroneous has been
-done, and give it commands to assign correct values to any variables that
-need them.  End with the @samp{cont} command so that the program does not
-stop, and start with the @samp{silent} command so that no output is
-produced.  Here is an example:
+Because the @samp{directory} command, when used with arguments, adds to
+the front of the source path, it can affect files that _GDBN__ has already
+found.  If the source path contains directories that you do not want,
+and these directories contain misleading files with names matching your
+source files, the way to correct the situation is as follows:
 
-@example
-break 403
-commands
-silent
-set x = y + 4
-cont
-end
-@end example
+@enumerate
+@item
+Use @samp{directory} with no argument to reset the source path to empty.
 
-One deficiency in the operation of automatically continuing breakpoints
-under Unix appears when your program uses raw mode for the terminal.
-_GDBN__ switches back to its own terminal modes (not raw) before executing
-commands, and then must switch back to raw mode when your program is
-continued.  This causes any pending terminal input to be lost. 
-In the GNU system, this will be fixed by changing the behavior of
-terminal modes.
+@item
+Use @samp{directory} with suitable arguments to add any other
+directories you want in the source path.  You can add all the directories
+in one command.
+@end enumerate
 
-Under Unix, when you have this problem, you might be able to get around
-it by putting your actions into the breakpoint condition instead of
-commands.  For example
+@node Data, Symbols, Source, Top
+@chapter Examining Data
+
+@cindex printing data
+@cindex examining data
+@kindex print
+@kindex inspect
+The usual way to examine data in your program is with the @samp{print}
+command (abbreviated @samp{p}), or its synonym @samp{inspect}.  It
+evaluates and prints the value of any valid expression of the language
+the program is written in (for now, C or C++).  You type
 
 @example
-condition 5  (x = y + 4), 0
+print @var{exp}
 @end example
 
 @noindent
-specifies a condition expression (@xref{Expressions}) that will change
-@code{x} as needed, then always have the value 0 so the program will not
-stop.  Loss of input is avoided here because break conditions are
-evaluated 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 Error in Breakpoints,  , Break Commands, Breakpoints
-@subsection ``Cannot Insert Breakpoints''
-
-@c FIXME: "cannot insert breakpoints" error, v unclear.  
-@c        Q in pending mail to Gilmore. [e-mail], 26mar91
-Under some operating systems, breakpoints cannot be used in a program if
-any other process is running that program.  In this situation,
-attempting to run or continue a program with a breakpoint will cause _GDBN__
-to stop the other process.
+where @var{exp} is any valid expression (in the source language), and
+the value of @var{exp} is printed in a format appropriate to its data
+type.
 
-When this happens, you have three ways to proceed:
+A more low-level way of examining data is with the @samp{x} command.
+It examines data in memory at a specified address and prints it in a
+specified format.
 
-@enumerate
-@item
-Remove or disable the breakpoints, then continue.
+@menu
+* Expressions::			Expressions that can be computed and printed.
+* Variables::			Using your program's variables in expressions.
+* Arrays::			Examining part of memory as an array.
+* Format options::		Controlling how structures and arrays are printed.
+* Output formats::		Specifying formats for printing values.
+* Auto Display::		Printing certain expressions whenever program stops.
+* Value History::		Referring to values previously printed.
+* Convenience Vars::		Giving names to values for future reference.
+* Registers::			Referring to and storing in machine registers.
+@end menu
 
-@item
-Suspend _GDBN__, and copy the file containing the program to a new name.
-Resume _GDBN__ and use the @samp{exec-file} command to specify that _GDBN__
-should run the program under that name.  Then start the program again.
+@node Expressions, Variables, Data, Data
+@section Expressions
 
-@item
-Relink the program so that the text segment is nonsharable, using the
-linker option @samp{-N}.  The operating system limitation may not apply
-to nonsharable executables.
-@end enumerate
+@cindex expressions
+Many different _GDBN__ commands accept an expression and compute its value.
+Any kind of constant, variable or operator defined by the programming
+language you are using is legal in an expression in _GDBN__.  This includes
+conditional expressions, function calls, casts and string constants.  It
+unfortunately does not include symbols defined by preprocessor
+@code{#define} commands, or C++ expressions involving @samp{::}, the
+name resolution operator.
 
-@node Continuing, Stepping, Breakpoints, Stopping
-@section Continuing
+Casts are supported in all languages, not just in C, because it is so
+useful to cast a number into a pointer so as to examine a structure
+at that address in memory.
 
-After your program stops, most likely you will want it to run some more if
-the bug you are looking for has not happened yet.
+_GDBN__ supports three kinds of operator in addition to those of programming
+languages:
 
 @table @code
-@item continue
-@item cont
-@kindex cont
-@kindex continue
-Continue running the program at the place where it stopped.
-@end table
+@item @@
+@samp{@@} is a binary operator for treating parts of memory as arrays.
+@xref{Arrays}, for more information.
 
-If the program stopped at a breakpoint, the place to continue running
-is the address of the breakpoint.  You might expect that continuing would
-just stop at the same breakpoint immediately.  In fact, @samp{cont}
-takes special care to prevent that from happening.  You do not need
-to delete the breakpoint to proceed through it after stopping at it.
+@item ::
+@samp{::} allows you to specify a variable in terms of the file or
+function it is defined in.  @xref{Variables}.
 
-You can, however, specify an ignore-count for the breakpoint that the
-program stopped at, by means of an argument to the @samp{cont} command.
-@xref{Conditions}.
+@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 nonunary operators, just as in
+a cast).  This construct is allowed regardless of what kind of data is
+officially supposed to reside at @var{addr}.@refill
+@end table
 
-If the program stopped because of a signal other than @code{SIGINT} or
-@code{SIGTRAP}, continuing will cause the program to see that signal.
-You may not want this to happen.  For example, if the program stopped
-due to some sort of memory reference error, you might store correct
-values into the erroneous variables and continue, hoping to see more
-execution; but the program would probably terminate immediately as
-a result of the fatal signal once it sees the signal.  To prevent this,
-you can continue with @samp{signal 0}.  @xref{Signaling}.  You can
-also act in advance to control what signals your program will see, using
-the @samp{handle} command (@pxref{Signals}). 
+@node Variables, Arrays, Expressions, Data
+@section Program Variables
 
-@node Stepping,  , Continuing, Stopping
-@section Stepping
+The most common kind of expression to use is the name of a variable
+in your program.
 
-@cindex stepping
-@dfn{Stepping} means setting your program in motion for a limited time, so
-that control will return automatically to the debugger after one line of
-code or one machine instruction.  Breakpoints are active during stepping
-and the program will stop for them even if it has not gone as far as the
-stepping command specifies.
+Variables in expressions are understood in the selected stack frame
+(@pxref{Selection}); they must either be global (or static) or be visible
+according to the scope rules of the programming language from the point of
+execution in that frame.  This means that in the function
 
-@table @code
-@item step
-@kindex step
-Continue running the program until control reaches a different line,
-then stop it and return control to the debugger.  This command is
-abbreviated @samp{s}.
+@example
+foo (a)
+     int a;
+@{
+  bar (a);
+  @{
+    int b = test ();
+    bar (b);
+  @}
+@}
+@end example
 
-This command may be given when control is within a function for which
-there is no debugging information.  In that case, execution will proceed
-until control reaches a different function, or is about to return from
-this function.  An argument repeats this action.
+@noindent
+the variable @code{a} is usable whenever the program is executing
+within the function @code{foo}, but the variable @code{b} is visible
+only while the program is executing inside the block in which @code{b}
+is declared.
 
-@item step @var{count}
-Continue running as in @samp{step}, but do so @var{count} times.  If a
-breakpoint is reached or a signal not related to stepping occurs before
-@var{count} steps, stepping stops right away.
+As a special 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 (if they are in different source files).
+In such a case, it is not defined which one you will get.  If you wish,
+you can specify any one of them using the colon-colon construct:
 
-@item next
-@kindex next
-Similar to @samp{step}, but any function calls appearing within the line of
-code are executed without stopping.  Execution stops when control reaches a
-different line of code at the stack level which was executing when the
-@samp{next} command was given.  This command is abbreviated @samp{n}.
+@cindex colon-colon
+@cindex scope
+@kindex ::
+@example
+@var{block}::@var{variable}
+@end example
 
-An argument is a repeat count, as in @samp{step}.
+@noindent
+Here @var{block} is the name of the source file whose variable you want.
 
-@samp{next} within a function without debugging information acts as does
-@samp{step}, but any function calls appearing within the code of the
-function are executed without stopping.
+@cindex name resolution (C++)
+Unfortunately, this use of @samp{::} conflicts with the very similar use
+of the same notation in C++; accordingly, _GDBN__ does not support use of
+the C++ name resolution operator in _GDBN__ expressions.
 
-@item finish
-@kindex finish
-Continue running until just after the selected stack frame returns (or
-until there is some other reason to stop, such as a fatal signal or a
-breakpoint).  Print value returned by the selected stack frame (if any).
+@node Arrays, Format options, Variables, Data
+@section Artificial Arrays
 
-Contrast this with the @samp{return} command (@pxref{Returning}).
+@cindex artificial array
+@kindex @@
+It is often useful to print out several successive objects of the
+same type in memory; a section of an array, or an array of
+dynamically determined size for which only a pointer exists in the
+program.
 
-@item until
-@kindex until
-This command is used to avoid single stepping through a loop more than
-once.  It is like the @samp{next} command, except that when @samp{until}
-encounters a jump, it automatically continues execution until the
-program counter is greater than the address of the jump.
+This can be done by constructing an @dfn{artificial array} with the
+binary operator @samp{@@}.  The left operand of @samp{@@} should be
+the first element of the desired array, as an individual object.
+The right operand should be the length of the array.  The result is
+an array value whose elements are all of the type of the left argument.
+The first element is actually the left argument; the second element
+comes from bytes of memory immediately following those that hold the
+first element, and so on.  Here is an example.  If a program says
 
-This means that when you reach the end of a loop after single stepping
-though it, @samp{until} will cause the program to continue execution
-until the loop is exited.  In contrast, a @samp{next} command at the end
-of a loop will simply step back to the beginning of the loop, which
-would force you to step through the next iteration.
+@example
+int *array = (int *) malloc (len * sizeof (int));
+@end example
 
-@samp{until} always stops the program if it attempts to exit the current
-stack frame.
+@noindent
+you can print the contents of @code{array} with
 
-@samp{until} may produce somewhat counterintuitive results if the order
-of the source lines does not match the actual order of execution.  For
-example, in a typical C @code{for}-loop, the third expression in the
-@code{for}-statement (the loop-step expression) is executed after the
-statements in the body of the loop, but is written before them.
-Therefore, the @samp{until} command would appear to step back to the
-beginning of the loop when it advances to this expression.  However, it
-has not really done so, not in terms of the actual machine code.
+@example
+p *array@@len
+@end example
 
-Note that @samp{until} with no argument works by means of single
-instruction stepping, and hence is slower than @samp{until} with an
-argument.
+The left operand of @samp{@@} must reside in memory.  Array values made
+with @samp{@@} in this way behave just like other arrays in terms of
+subscripting, and are coerced to pointers when used in expressions.
+(It would probably appear in an expression via the value history,
+after you had printed it out.)
 
-@item until @var{location}
-Continue running the program until either the specified location is
-reached, or the current (innermost) stack frame returns.  @var{location}
-is any of the forms of argument acceptable to @samp{break} (@pxref{Set
-Breaks}).  This form of the command uses breakpoints, and hence is
-quicker than @samp{until} without an argument.
+@node Format options, Output formats, Arrays, Data
+@section Format options
 
-@item stepi
-@itemx si
-@kindex stepi
-@kindex si
-Execute one machine instruction, then stop and return to the debugger.
+@cindex format options
+_GDBN__ provides a few ways to control how arrays, structures, and symbols are
+printed.  
 
-It is often useful to do @samp{display/i $pc} when stepping by machine
-instructions.  This will cause the next instruction to be executed to
-be displayed automatically at each stop.  @xref{Auto Display}.
+@table @code
+@item set array-max @var{number-of-elements}
+@kindex set array-max
+If _GDBN__ is printing a large array, it will stop printing after it has
+printed the number of elements set by the @samp{set array-max} command.
+This limit also applies to the display of strings.
 
-An argument is a repeat count, as in @samp{step}.
+@item show array-max
+@kindex show array-max
+Display the number of elements of a large array that _GDBN__ will print
+before losing patience.
 
-@item nexti
-@itemx ni
-@kindex nexti
-@kindex ni
-Execute one machine instruction, but if it is a subroutine call,
-proceed until the subroutine returns.
+@item set arrayprint
+@itemx set arrayprint on
+@kindex set arrayprint
+_GDBN__ will pretty print arrays.  This format is more convenient to read,
+but uses more space.  The default is off.
 
-An argument is a repeat count, as in @samp{next}.
-@end table
+@item set arrayprint off.
+Return to compressed format for arrays.
 
-A typical technique for using stepping is to put a breakpoint
-(@pxref{Breakpoints}) at the beginning of the function or the section of
-the program in which a problem is believed to lie, and then step through
-the suspect area, examining the variables that are interesting, until the
-problem happens.
+@item show arrayprint
+@kindex show arrayprint
+Show whether compressed or pretty format is selected for displaying
+arrays. 
 
-The @samp{cont} command can be used after stepping to resume execution
-until the next breakpoint or signal.
+@item set demangle 
+@itemx set demangle on 
+@kindex set demangle
+Print C++ names in their source form rather than in the mangled form
+in which they are passed to the assembler and linker for type-safe linkage.
+The default is on.
 
-@node Stack, Source, Stopping, Top
-@chapter Examining the Stack
+@item show demangle
+@kindex show demangle
+Show whether C++ names will be printed in mangled or demangled form.
 
-When your program has stopped, the first thing you need to know is where it
-stopped and how it got there.
+@item set asm-demangle 
+@itemx set asm-demangle on 
+@kindex set asm-demangle
+Print C++ names in their source form rather than their mangled form, even
+in assembler code printouts such as instruction disassemblies.
+The default is off.
+
+@item show asm-demangle
+@kindex show asm-demangle
+Show whether C++ names in assembly listings will be printed in mangled
+or demangled form.
 
-@cindex call stack
-Each time your program performs a function call, the information about
-where in the program the call was made from is saved in a block of data
-called a @dfn{stack frame}.  The frame also contains the arguments of the
-call and the local variables of the function that was called.  All the
-stack frames are allocated in a region of memory called the @dfn{call
-stack}.
+@item set vtblprint 
+@itemx set vtblprint on 
+@kindex set vtblprint
+Pretty print C++ virtual function tables.  The default is off.
 
-When your program stops, the _GDBN__ commands for examining the stack allow you
-to see all of this information.
+@item set vtblprint off
+Do not pretty print C++ virtual function tables.
 
-One of the stack frames is @dfn{selected} by _GDBN__ and many _GDBN__ commands
-refer implicitly to the selected frame.  In particular, whenever you ask
-_GDBN__ for the value of a variable in the program, the value is found in the
-selected frame.  There are special _GDBN__ commands to select whichever frame
-you are interested in.
+@item show vtblprint
+@kindex show vtblprint
+Show whether C++ virtual function tables are pretty printed, or not.
 
-When the program stops, _GDBN__ automatically selects the currently executing
-frame and describes it briefly as the @samp{frame} command does
-(@pxref{Frame Info, Info}).
+@item set addressprint
+@item set addressprint on
+@kindex set addressprint
+_GDBN__ will print memory addresses in stack traces, structure values, pointer
+values, breakpoints, etc.  The default is on.
 
-@menu
-* Frames::			Explanation of stack frames and terminology.
-* Backtrace::			Summarizing many frames at once.
-* Selection::			How to select a stack frame.
-* Frame Info::			Information on a Frame
-@end menu
+@item set addressprint off
+Do not print addresses.
 
-@node Frames, Backtrace, Stack, Stack
-@section Stack Frames
+@item show addressprint
+@kindex show addressprint
+Show whether or not addresses are to be printed.
 
-@cindex frame
-@cindex stack frame
-The call stack is divided up into contiguous pieces called @dfn{stack
-frames}, or @dfn{frames} for short; each frame is the data associated
-with one call to one function.  The frame contains the arguments given
-to the function, the function's local variables, and the address at
-which the function is executing.
+@item set prettyprint on
+@kindex set prettyprint
+Cause _GDBN__ to print structures in an indented format with one member per
+line, like this:
 
-@cindex initial frame
-@cindex outermost frame
-@cindex innermost frame
-When your program is started, the stack has only one frame, that of the
-function @code{main}.  This is called the @dfn{initial} frame or the
-@dfn{outermost} frame.  Each time a function is called, a new frame is
-made.  Each time a function returns, the frame for that function invocation
-is eliminated.  If a function is recursive, there can be many frames for
-the same function.  The frame for the function in which execution is
-actually occurring is called the @dfn{innermost} frame.  This is the most
-recently created of all the stack frames that still exist.
+@example
+$1 = @{
+  next = 0x0,
+  flags = @{
+    sweet = 1,
+    sour = 1
+  @},
+  meat = 0x54 "Pork"
+@}
+@end example
 
-@cindex frame pointer
-Inside your program, stack frames are identified by their addresses.  A
-stack frame consists of many bytes, each of which has its own address; each
-kind of computer has a convention for choosing one of those bytes whose
-address serves as the address of the frame.  Usually this address is kept
-in a register called the @dfn{frame pointer register} while execution is
-going on in that frame.
+@item set prettyprint off
+Cause _GDBN__ to print structures in a compact format, like this:
 
-@cindex frame number
-_GDBN__ assigns numbers to all existing stack frames, starting with zero for
-the innermost frame, one for the frame that called it, and so on upward.
-These numbers do not really exist in your program; they are to give you a
-way of talking about stack frames in _GDBN__ commands.
+@smallexample
+$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, meat \
+= 0x54 "Pork"@}
+@end smallexample
 
-@cindex selected frame
-Many _GDBN__ commands refer implicitly to one stack frame, called the
-@dfn{selected} stack frame.  You can select any frame using one set of
-_GDBN__ commands, and then other commands will operate on that frame.  When
-your program stops, _GDBN__ automatically selects the innermost frame.
+@noindent
+This is the default format.
 
-@cindex frameless execution
-Some compilers allow functions to be compiled to run without a frame
-reserved for them on the stack. (For example, the _GCC__ option
-@samp{-fomit-frame-pointer} will generate functions without a frame.)
-This is occasionally done with heavily used library functions to save
-the frame setup time.  _GDBN__ has limited facilities for dealing with these
-function invocations; if the innermost function invocation has no stack
-frame, _GDBN__ will give it a virtual stack frame of 0 and correctly allow
-tracing of the function call chain.  Results are undefined if a function
-invocation besides the innermost one is frameless.
+@item show prettyprint
+@kindex show prettyprint
+Show which format _GDBN__ will use to print structures.
 
-@node Backtrace, Selection, Frames, Stack
-@section Backtraces
+@item set unionprint on
+@kindex set unionprint
+Tell _GDBN__ to print unions which are contained in structures.  This is the
+default setting.
 
-A backtrace is a summary of how the program got where it is.  It shows one
-line per frame, for many frames, starting with the currently executing
-frame (frame zero), followed by its caller (frame one), and on up the
-stack.
+@item set unionprint off
+Tell _GDBN__ not to print unions which are contained in structures.
 
-@table @code
-@item backtrace
-@itemx bt
-@kindex backtrace
-@kindex bt
-Print a backtrace of the entire stack: one line per frame for all
-frames in the stack.
+@item show unionprint
+@kindex show unionprint
+Ask _GDBN__ whether or not it will print unions which are contained in
+structures. 
 
-You can stop the backtrace at any time by typing the system interrupt
-character, normally @kbd{Control-C}.
+For example, given the declarations
 
-@item backtrace @var{n}
-@itemx bt @var{n}
-Similar, but print only the innermost @var{n} frames.
+@smallexample
+typedef enum @{Tree, Bug@} Species;
+typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
+typedef enum @{Caterpillar, Cocoon, Butterfly@} Bug_forms;
 
-@item backtrace @var{-n}
-@itemx bt @var{-n}
-Similar, but print only the outermost @var{n} frames.
-@end table
+struct thing @{
+  Species it;
+  union @{
+    Tree_forms tree;
+    Bug_forms bug;
+  @} form;
+@};
 
-@kindex where
-@kindex info stack
-The names @samp{where} and @samp{info stack} are additional aliases
-for @samp{backtrace}.
+struct thing foo = @{Tree, @{Acorn@}@};
+@end smallexample
 
-Every line in the backtrace shows the frame number and the function
-name.  The program counter value is also shown---unless you use
-@samp{set addressprint off}.
+@noindent
+with @samp{set unionprint on} in effect @samp{p foo} would print
 
-If the function is in a source file whose symbol table data has been
-fully read, the backtrace shows the source file name and line number, as
-well as the arguments to the function.  When the line number is shown,
-the program counter value is omitted if it is at the beginning of the
-code for that line number.
+@smallexample
+$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
+@end smallexample
 
-Here is an example of a backtrace.  It was made with the command
-@samp{bt 3}, so it shows the innermost three frames.
+@noindent
+and with @samp{set unionprint off} in effect it would print
 
 @example
-#0  rtx_equal_p (x=(rtx) 0x8e58c, y=(rtx) 0x1086c4) \
-(/gp/rms/cc/rtlanal.c line 337)
-#1  0x246b0 in expand_call (...) (...)
-#2  0x21cfc in expand_expr (...) (...)
-(More stack frames follow...)
+$1 = @{it = Tree, form = @{...@}@}
 @end example
+@end table
 
-@noindent
-The functions @code{expand_call} and @code{expand_expr} are in a file
-whose symbol details have not been fully read.  Full detail is available
-for the function @code{rtx_equal_p}, which is in the file
-@file{rtlanal.c}.  Its arguments, named @code{x} and @code{y}, are shown
-with their typed values.
-
-@node Selection, Frame Info, Backtrace, Stack
-@section Selecting a Frame
+@node Output formats, Auto Display, Format options, Data
+@section Output formats
 
-Most commands for examining the stack and other data in the program work on
-whichever stack frame is selected at the moment.  Here are the commands for
-selecting a stack frame; all of them finish by printing a brief description
-of the stack frame just selected.
+@cindex formatted output
+@cindex output formats
+_GDBN__ normally prints all values according to their data types.  Sometimes
+this is not what you want.  For example, you might want to print a number
+in hex, or a pointer in decimal.  Or you might want to view data in memory
+at a certain address as a character string or an instruction.  These things
+can be done with @dfn{output formats}.
 
-@table @code
-@item frame @var{n}
-@kindex frame
-Select frame number @var{n}.  Recall that frame zero is the innermost
-(currently executing) frame, frame one is the frame that called the
-innermost one, and so on.  The highest-numbered frame is @code{main}'s
-frame.
+The simplest use of output formats is to say how to print a value
+already computed.  This is done by starting the arguments of the
+@samp{print} command with a slash and a format letter.  The format
+letters supported are:
 
-@item frame @var{addr}
-Select the frame at address @var{addr}.  This is useful mainly if the
-chaining of stack frames has been damaged by a bug, making it
-impossible for _GDBN__ to assign numbers properly to all frames.  In
-addition, this can be useful when the program has multiple stacks and
-switches between them.
+@table @samp
+@item x
+Regard the bits of the value as an integer, and print the integer in
+hexadecimal.
 
-@item up @var{n}
-@kindex up
-Select the frame @var{n} frames up from the frame previously selected.
-For positive numbers @var{n}, this advances toward the outermost
-frame, to higher frame numbers, to frames that have existed longer.
-@var{n} defaults to one.
+@item d
+Print as integer in signed decimal.
 
-@item down @var{n}
-@kindex down
-Select the frame @var{n} frames down from the frame previously
-selected.  For positive numbers @var{n}, this advances toward the
-innermost frame, to lower frame numbers, to frames that were created
-more recently.  @var{n} defaults to one.
-@end table
+@item u
+Print as integer in unsigned decimal.
 
-All of these commands end by printing some information on the frame that
-has been selected: the frame number, the function name, the arguments, the
-source file and line number of execution in that frame, and the text of
-that source line.  For example:
+@item o
+Print as integer in octal.
 
+@item a
+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
-#3  main (argc=3, argv=??, env=??) at main.c:67
-67        read_input_file (argv[i]);
+(_GDBP__) p/a 0x54320
+_0__$3 = 0x54320 <_initialize_vx+396>_1__
 @end example
 
-After such a printout, the @samp{list} command with no arguments will print
-ten lines centered on the point of execution in the frame.  @xref{List}.
 
-@table @code
-@item up-silently @var{n}
-@itemx down-silently @var{n}
-@kindex down-silently
-@kindex up-silently
-These two commands are variants of @samp{up} and @samp{down},
-respectively; they differ in that they do their work silently, without
-causing display of the new frame.  They are intended primarily for use
-in _GDBN__ command scripts, where the output might be unnecessary and
-distracting. 
+@item c
+Regard as an integer and print it as a character constant.
 
+@item f
+Regard the bits of the value as a floating point number and print
+using typical floating point syntax.
 @end table
 
-@node Frame Info,  , Selection, Stack
-@section Information on a Frame
+For example, to print the program counter in hex (@pxref{Registers}), type
 
-There are several other commands to print information about the selected
-stack frame.
+@example
+p/x $pc
+@end example
 
-@table @code
-@item frame
-When used without any argument, this command does not change which frame
-is selected, but still prints a brief description of the currently
-selected stack frame.  It can be abbreviated @samp{f}.  With an
-argument, this command is used to select a stack frame; with no
-argument, it does not change which frame is selected, but still prints
-the same kind of information.
+@noindent
+Note that no space is required before the slash; this is because command
+names in _GDBN__ cannot contain a slash.
 
-@item info frame
-@kindex info frame
-This command prints a verbose description of the selected stack frame,
-including the address of the frame, the addresses of the next frame in
-(called by this frame) and the next frame out (caller of this frame),
-the address of the frame's arguments, the program counter saved in it
-(the address of execution in the caller frame), and which registers
-were saved in the frame.  The verbose description is useful when
-something has gone wrong that has made the stack format fail to fit
-the usual conventions.
+To reprint the last value in the value history with a different format,
+you can use the @samp{print} command with just a format and no
+expression.  For example, @samp{p/x} reprints the last value in hex.
 
-@item info frame @var{addr}
-Print a verbose description of the frame at address @var{addr},
-without selecting that frame.  The selected frame remains unchanged by
-this command.
+@menu
+* Memory::			Examining Memory
+@end menu
 
-@item info args
-@kindex info args
-Print the arguments of the selected frame, each on a separate line.
+@node Memory,  , Output formats, Output formats
+@subsection Examining Memory
 
-@item info locals
-@kindex info locals
-Print the local variables of the selected frame, each on a separate
-line.  These are all variables declared static or automatic within all
-program blocks that execution in this frame is currently inside of.
+@cindex examining memory
+@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.
 
-@item info catch
-@kindex info catch
-@cindex catch exceptions
-@cindex exception handlers
-Print a list of all the exception handlers that are active in the
-current stack frame given the current value of @code{pc}.  To see other
-exception handlers, visit the associated frame (using the @samp{up},
-@samp{down}, or @samp{frame} commands); then type @samp{info catch}.
-@xref{Exception Handling}.
+@kindex x
+@item x
+The command @samp{x} (for `examine') can be used to examine memory
+without reference to the program's data types.  The format in which you
+wish to examine memory is instead explicitly specified.  The allowable
+formats are a superset of the formats described in the previous section.
 @end table
 
-@node Source, Data, Stack, Top
-@chapter Examining Source Files
-
-_GDBN__ knows which source files your program was compiled from, and
-can print parts of their text.  When your program stops, _GDBN__
-spontaneously prints the line it stopped in.  Likewise, when you
-select a stack frame (@pxref{Selection}), _GDBN__ prints the line
-which execution in that frame has stopped in.  You can also
-print parts of source files by explicit command.
-
-@menu
-* List::			Using the @samp{list} command to print source files.
-* Search::			Commands for searching source files.
-* Source Path::			Specifying the directories to search for source files.
-@end menu
+@samp{x} is followed by a slash and an output format specification,
+followed by an expression for an address.  The expression need not have
+a pointer value (though it may); it is used as an integer, as the
+address of a byte of memory.  @xref{Expressions} for more information on
+expressions.  For example, @samp{x/4xw $sp} prints the four words of
+memory above the stack pointer in hexadecimal.
 
-@node List, Search, Source, Source
-@section Printing Source Lines
+The output format in this case specifies both how big a unit of memory
+to examine and how to print the contents of that unit.  It is done
+with one or two of the following letters:
 
-@kindex list
-@kindex l
-To print lines from a source file, use the @samp{list} command
-(abbreviated @samp{l}).  There are several ways to specify what part
-of the file you want to print.
+These letters specify just the size of unit to examine:
 
-Here are the forms of the @samp{list} command most commonly used:
+@table @samp
+@item b
+Examine individual bytes.
 
-@table @code
-@item list @var{linenum}
-Print ten lines centered around line number @var{linenum} in the
-current source file.
+@item h
+Examine halfwords (two bytes each).
 
-@item list @var{function}
-Print ten lines centered around the beginning of function
-@var{function}.
+@item w
+Examine words (four bytes each).
 
-@item list
-Print ten more lines.  If the last lines printed were printed with a
-@samp{list} command, this prints ten 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}), this prints ten
-lines centered around that line.
+@cindex word
+Many assemblers and cpu designers still use `word' for a 16-bit quantity,
+as a holdover from specific predecessor machines of the 1970's that really
+did use two-byte words.  But more generally the term `word' has always
+referred to the size of quantity that a machine normally operates on and
+stores in its registers.  This is 32 bits for all the machines that _GDBN__
+runs on.
 
-@item list -
-Print ten lines just before the lines last printed.
+@item g
+Examine giant words (8 bytes).
 @end table
 
-Repeating a @samp{list} command with @key{RET} discards the argument,
-so it is equivalent to typing just @samp{list}.  This is more useful
-than listing the same lines again.  An exception is made for an
-argument of @samp{-}; that argument is preserved in repetition so that
-each repetition moves up in the file.
+These letters specify just the way to print the contents:
 
-@cindex linespec
-In general, the @samp{list} command expects you to supply zero, one or two
-@dfn{linespecs}.  Linespecs specify source lines; there are several ways
-of writing them but the effect is always to specify some source line.
-Here is a complete description of the possible arguments for @samp{list}:
+@table @samp
+@item x
+Print as integers in unsigned hexadecimal.
 
-@table @code
-@item list @var{linespec}
-Print ten lines centered around the line specified by @var{linespec}.
+@item d
+Print as integers in signed decimal.
 
-@item list @var{first},@var{last}
-Print lines from @var{first} to @var{last}.  Both arguments are
-linespecs.
+@item u
+Print as integers in unsigned decimal.
 
-@item list ,@var{last}
-Print ten lines ending with @var{last}.
+@item o
+Print as integers in unsigned octal.
 
-@item list @var{first},
-Print ten lines starting with @var{first}.
+@item a
+Print as an address, both absolute in hex and then relative
+to a symbol defined as an address below it.
 
-@item list +
-Print ten lines just after the lines last printed.
+@item c
+Print as character constants.
 
-@item list -
-Print ten lines just before the lines last printed.
+@item f
+Print as floating point.  This works only with sizes @samp{w} and
+@samp{g}.
 
-@item list
-As described in the preceding table.
-@end table
+@item s
+Print a null-terminated string of characters.  The specified unit size
+is ignored; instead, the unit is however many bytes it takes to reach
+a null character (including the null character).
 
-Here are the ways of specifying a single source line---all the
-kinds of linespec.
+@item i
+Print a machine instruction in assembler syntax (or nearly).  The
+specified unit size is ignored; the number of bytes in an instruction
+varies depending on the type of machine, the opcode and the addressing
+modes used.  The command @samp{disassemble} gives an alternative way of
+inspecting machine instructions.
+@end table
 
-@table @code
-@item @var{linenum}
-Specifies line @var{linenum} of the current source file.
-When a @samp{list} command has two linespecs, this refers to
-the same source file as the first linespec.
+If either the manner of printing or the size of unit fails to be specified,
+the default is to use the same one that was used last.  If you don't want
+to use any letters after the slash, you can omit the slash as well.
 
-@item +@var{offset}
-Specifies the line @var{offset} lines after the last line printed.
-When used as the second linespec in a @samp{list} command that has
-two, this specifies the line @var{offset} lines down from the
-first linespec.
+You can also omit the address to examine.  Then the address used is just
+after the last unit examined.  This is why string and instruction
+formats actually compute a unit-size based on the data: so that the next
+string or instruction examined will start in the right place.  
 
-@item -@var{offset}
-Specifies the line @var{offset} lines before the last line printed.
+When the @samp{print} command shows a value that resides in memory,
+@samp{print} also sets the default address for the @samp{x} command.
+@samp{info line} also sets the default for @samp{x}, to the address of
+the start of the machine code for the specified line and @samp{info
+breakpoints} sets it to the address of the last breakpoint listed.
 
-@item @var{filename}:@var{linenum}
-Specifies line @var{linenum} in the source file @var{filename}.
+When you use @key{RET} to repeat an @samp{x} command, the address
+specified previously (if any) is ignored, so that the repeated command
+examines the successive locations in memory rather than the same ones.
 
-@item @var{function}
-Specifies the line of the open-brace that begins the body of the
-function @var{function}.
+You can examine several consecutive units of memory with one command by
+writing a repeat-count after the slash (before the format letters, if any).
+The repeat count must be a decimal integer.  It has the same effect as
+repeating the @samp{x} command that many times except that the output may
+be more compact with several units per line.  For example,
 
-@item @var{filename}:@var{function}
-Specifies the line of the open-brace that begins the body of the
-function @var{function} in the file @var{filename}.  The file name is
-needed with a function name only for disambiguation of identically
-named functions in different source files.
+@example
+x/10i $pc
+@end example
 
-@item *@var{address}
-Specifies the line containing the program address @var{address}.
-@var{address} may be any expression.
-@end table
+@noindent
+prints ten instructions starting with the one to be executed next in the
+selected frame.  After doing this, you could print another seven following
+instructions with
 
-One other command is used to map source lines to program addresses.
+@example
+x/7
+@end example
 
-@table @code
-@item info line @var{linenum}
-@kindex info line
-Print the starting and ending addresses of the compiled code for
-source line @var{linenum}.
+@noindent
+in which the format and address are allowed to default.
 
 @kindex $_
-The default examine address for the @samp{x} command is changed to the
-starting address of the line, so that @samp{x/i} is sufficient to
-begin examining the machine code (@pxref{Memory}).  Also, this address
-is saved as the value of the convenience variable @code{$_}
-(@pxref{Convenience Vars}).
-@end table
+@kindex $__
+The addresses and contents printed by the @samp{x} command are not put in
+the value history because there is often too much of them and they would
+get in the way.  Instead, _GDBN__ makes these values available for subsequent
+use in expressions as values of the convenience variables @code{$_} and
+@code{$__}.
 
-@node Search, Source Path, List, Source
-@section Searching Source Files
-@cindex searching
-@kindex search
-@kindex forward-search
-@kindex reverse-search
+After an @samp{x} command, the last address examined is available for use
+in expressions in the convenience variable @code{$_}.  The contents of that
+address, as examined, are available in the convenience variable @code{$__}.
 
-There are two commands for searching through the current source file for a
-regular expression.
+If the @samp{x} command has a repeat count, the address and contents saved
+are from the last memory unit printed; this is not the same as the last
+address printed if several units were printed on the last line of output.
 
-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 @samp{fo}.  The synonym @samp{search @var{regexp}} is also supported.
+@node Auto Display, Value History, Output formats, Data
+@section Automatic Display
+@cindex automatic display
+@cindex display of expressions
 
-The command @samp{reverse-search @var{regexp}} checks each line, starting
-with the one before the last line listed and going backward, for a match
-for @var{regexp}.  It lists the line that is found.  You can abbreviate
-this command with as little as @samp{rev}.
+If you find that you want to print the value of an expression frequently
+(to see how it changes), you might want to add it to the @dfn{automatic
+display list} so that _GDBN__ will print its value each time the program stops.
+Each expression added to the list is given a number to identify it;
+to remove an expression from the list, you specify that number.
+The automatic display looks like this:
 
-@node Source Path,  , Search, Source
-@section Specifying Source Directories
+@example
+2: foo = 38
+3: bar[5] = (struct hack *) 0x3804
+@end example
 
-@cindex source path
-@cindex directories for source files
-Executable programs sometimes do not record the directories of the source
-files from which they were compiled, just the names.  Even when they do,
-the directories could be moved between the compilation and your debugging
-session.  _GDBN__ remembers a list of directories to search for source files;
-this is called the @dfn{source path}.  Each time _GDBN__ wants a source file,
-it tries all the directories in the list, in the order they are present
-in the list, until it finds a file with the desired name.  Note that
-the executable search path is @emph{not} used for this purpose.  Neither is
-the current working directory, unless it happens to be in the source
-path.
+@noindent
+showing item numbers, expressions and their current values.
 
-If it can't find a source file in the source path, and the object program
-records what directory it was compiled in, _GDBN__ tries that directory too.
-If the source path is empty, and there is no record of the compilation
-directory, _GDBN__ will, as a last resort, look in the current directory.
+If the expression refers to local variables, then it does not make sense
+outside the lexical context for which it was set up.  Such an expression
+is disabled when execution enters a context where one of its variables
+is not defined.  For example, if you give the command 
+@samp{display name} while inside a function with an argument
+@code{name}, then this argument will be displayed while the program
+continues to stop inside that function.  When it stops elsewhere---where
+there is no variable @samp{name}---display is disabled.  The next time
+your program stops where @samp{name} is meaningful, you can enable the
+display expression once again.
 
-Whenever you reset or rearrange the source path, _GDBN__ will clear out
-any information it has cached about where source files are found, where
-each line is in the file, etc.
+@table @code
+@item display @var{exp}
+@kindex display
+Add the expression @var{exp} to the list of expressions to display
+each time the program stops.  @xref{Expressions}.
 
-@kindex directory
-When you start _GDBN__, its source path is empty.
-To add other directories, use the @samp{directory} command.
+@item display/@var{fmt} @var{exp}
+For @var{fmt} specifying only a display format and not a size or
+count, add the expression @var{exp} to the auto-display list but
+arranges to display it each time in the specified format @var{fmt}.
 
-@table @code
-@item directory @var{dirnames...}
-Add directory @var{dirname} to the front of the source path.  Several
-directory names may be given to this command, separated by whitespace or
-@samp{:}.  If a name is already in the source path, it is moved to the
-front of the path, so it will be searched sooner.
+@item display/@var{fmt} @var{addr}
+For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
+number of units, add the expression @var{addr} as a memory address to
+be examined each time the program stops.  Examining means in effect
+doing @samp{x/@var{fmt} @var{addr}}.  @xref{Memory}.
 
-@item directory
-Reset the source path to empty again.  This requires confirmation.
+@item undisplay @var{dnums}@dots{}
+@itemx delete display @var{dnums}@dots{}
+@kindex delete display
+@kindex undisplay
+Remove item numbers @var{dnums} from the list of expressions to display.
 
-@item info directories
-@kindex info directories
-Print the source path: show which directories it contains.
+@item disable display @var{dnums}@dots{}
+@kindex disable display
+Disable the display of item numbers @var{dnums}.  A disabled display
+item is not printed automatically, but is not forgotten.  It may be
+enabled again later.
+
+@item enable display @var{dnums}@dots{}
+@kindex enable display
+Enable display of item numbers @var{dnums}.  It becomes effective once
+again in auto display of its expression, until you specify otherwise.
+
+@item display
+Display the current values of the expressions on the list, just as is
+done when the program stops.
+
+@item info display
+@kindex info display
+Print the list of expressions previously set up to display
+automatically, each one with its item number, but without showing the
+values.  This includes disabled expressions, which are marked as such.
+It also includes expressions which would not be displayed right now
+because they refer to automatic variables not currently available.
 @end table
 
-Because the @samp{directory} command, when used with arguments, adds to
-the front of the source path, it can affect files that _GDBN__ has already
-found.  If the source path contains directories that you do not want,
-and these directories contain misleading files with names matching your
-source files, the way to correct the situation is as follows:
+@node Value History, Convenience Vars, Auto Display, Data
+@section Value History
 
-@enumerate
-@item
-Use @samp{directory} with no argument to reset the source path to empty.
+@cindex value history
+Values printed by the @samp{print} command are saved in _GDBN__'s @dfn{value
+history} so that you can refer to them in other expressions.  Values are
+kept until the symbol table is re-read or discarded (for example with
+the @samp{file} or @samp{symbol-file} commands).  When the symbol table
+changes, the value history is discarded, since the values may contain
+pointers back to the types defined in the symbol table.
 
-@item
-Use @samp{directory} with suitable arguments to add any other
-directories you want in the source path.  You can add all the directories
-in one command.
-@end enumerate
+@cindex @code{$}
+@cindex @code{$$}
+@cindex history number
+The values printed are given @dfn{history numbers} for you to refer to them
+by.  These are successive integers starting with 1.  @samp{print} shows you
+the history number assigned to a value by printing @samp{$@var{num} = }
+before the value; here @var{num} is the history number.
 
-@node Data, Symbols, Source, Top
-@chapter Examining Data
+To refer to any previous value, use @samp{$} followed by the value's
+history number.  The output printed by @samp{print} is designed to
+remind you of this.  Just @code{$} refers to the most recent value in
+the history, and @code{$$} refers to the value before that.
+@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2}
+is the value just prior to @code{$$}, @code{$$1} is equivalent to
+@code{$$}, and @code{$$0} is equivalent to @code{$}.
 
-@cindex printing data
-@cindex examining data
-@kindex print
-@kindex inspect
-The usual way to examine data in your program is with the @samp{print}
-command (abbreviated @samp{p}), or its synonym @samp{inspect}.  It
-evaluates and prints the value of any valid expression of the language
-the program is written in (for now, C or C++).  You type
+For example, suppose you have just printed a pointer to a structure and
+want to see the contents of the structure.  It suffices to type
 
 @example
-print @var{exp}
+p *$
 @end example
 
-@noindent
-where @var{exp} is any valid expression (in the source language), and
-the value of @var{exp} is printed in a format appropriate to its data
-type.
-
-A more low-level way of examining data is with the @samp{x} command.
-It examines data in memory at a specified address and prints it in a
-specified format.
+If you have a chain of structures where the component @samp{next} points
+to the next one, you can print the contents of the next one with this:
 
-@menu
-* Expressions::			Expressions that can be computed and printed.
-* Variables::			Using your program's variables in expressions.
-* Arrays::			Examining part of memory as an array.
-* Format options::		Controlling how structures and arrays are printed.
-* Output formats::		Specifying formats for printing values.
-* Auto Display::		Printing certain expressions whenever program stops.
-* Value History::		Referring to values previously printed.
-* Convenience Vars::		Giving names to values for future reference.
-* Registers::			Referring to and storing in machine registers.
-@end menu
+@example
+p *$.next
+@end example
 
-@node Expressions, Variables, Data, Data
-@section Expressions
+@noindent
+It might be useful to repeat this command many times by typing @key{RET}.
 
-@cindex expressions
-Many different _GDBN__ commands accept an expression and compute its value.
-Any kind of constant, variable or operator defined by the programming
-language you are using is legal in an expression in _GDBN__.  This includes
-conditional expressions, function calls, casts and string constants.  It
-unfortunately does not include symbols defined by preprocessor
-@code{#define} commands, or C++ expressions involving @samp{::}, the
-name resolution operator.
+Note that the history records values, not expressions.  If the value of
+@code{x} is 4 and you type this command:
 
-Casts are supported in all languages, not just in C, because it is so
-useful to cast a number into a pointer so as to examine a structure
-at that address in memory.
+@example
+print x
+set x=5
+@end example
 
-_GDBN__ supports three kinds of operator in addition to those of programming
-languages:
+@noindent
+then the value recorded in the value history by the @samp{print} command
+remains 4 even though the value of @code{x} has changed.
 
 @table @code
-@item @@
-@samp{@@} is a binary operator for treating parts of memory as arrays.
-@xref{Arrays}, for more information.
+@kindex info values
+@item info values
+@itemx info history
+@kindex info history
+These two commands are synonymous.  Either form will print the last ten
+values in the value history, with their item numbers.  This is like
+@samp{p@ $$9} repeated ten times, except that @samp{info values} does
+not change the history.
 
-@item ::
-@samp{::} allows you to specify a variable in terms of the file or
-function it is defined in.  @xref{Variables}.
+@item info values @var{n}
+Print ten history values centered on history item number @var{n}.
 
-@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 nonunary operators, just as in
-a cast).  This construct is allowed regardless of what kind of data is
-officially supposed to reside at @var{addr}.@refill
+@item info values +
+Print ten history values just after the values last printed.
 @end table
 
-@node Variables, Arrays, Expressions, Data
-@section Program Variables
+@node Convenience Vars, Registers, Value History, Data
+@section Convenience Variables
 
-The most common kind of expression to use is the name of a variable
-in your program.
+@cindex convenience variables
+_GDBN__ provides @dfn{convenience variables} that you can use within _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 effect on further execution of your program.  That's why
+you can use them freely.
 
-Variables in expressions are understood in the selected stack frame
-(@pxref{Selection}); they must either be global (or static) or be visible
-according to the scope rules of the programming language from the point of
-execution in that frame.  This means that in the function
+Convenience variables have names starting with @samp{$}.  Any name starting
+with @samp{$} can be used for a convenience variable, unless it is one of
+the predefined set of register names (@pxref{Registers}).
+
+You can save a value in a convenience variable with an assignment
+expression, just as you would set a variable in your program.  Example:
 
 @example
-foo (a)
-     int a;
-@{
-  bar (a);
-  @{
-    int b = test ();
-    bar (b);
-  @}
-@}
+set $foo = *object_ptr
 @end example
 
 @noindent
-the variable @code{a} is usable whenever the program is executing
-within the function @code{foo}, but the variable @code{b} is visible
-only while the program is executing inside the block in which @code{b}
-is declared.
+would save in @code{$foo} the value contained in the object pointed to by
+@code{object_ptr}.
 
-As a special 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 (if they are in different source files).
-In such a case, it is not defined which one you will get.  If you wish,
-you can specify any one of them using the colon-colon construct:
+Using a convenience variable for the first time creates it; but its value
+is @code{void} until you assign a new value.  You can alter the value with
+another assignment at any time.
 
-@cindex colon-colon
-@cindex scope
-@kindex ::
-@example
-@var{block}::@var{variable}
-@end example
+Convenience variables have no fixed types.  You can assign a convenience
+variable any type of value, including structures and arrays, even if
+that variable already has a value of a different type.  The convenience
+variable as an expression has whatever type its current value has.
 
-@noindent
-Here @var{block} is the name of the source file whose variable you want.
+@table @code
+@item info convenience
+@kindex info convenience
+Print a list of convenience variables used so far, and their values.
+Abbreviated @samp{i con}.
+@end table
 
-@cindex name resolution (C++)
-Unfortunately, this use of @samp{::} conflicts with the very similar use
-of the same notation in C++; accordingly, _GDBN__ does not support use of
-the C++ name resolution operator in _GDBN__ expressions.
+One of the ways to use a convenience variable is as a counter to be
+incremented or a pointer to be advanced.  For example:
 
-@node Arrays, Format options, Variables, Data
-@section Artificial Arrays
+_0__@example
+set $i = 0
+print bar[$i++]->contents
+@i{@dots{}repeat that command by typing @key{RET}.}
+_1__@end example
 
-@cindex artificial array
-@kindex @@
-It is often useful to print out several successive objects of the
-same type in memory; a section of an array, or an array of
-dynamically determined size for which only a pointer exists in the
-program.
+Some convenience variables are created automatically by _GDBN__ and given
+values likely to be useful.
 
-This can be done by constructing an @dfn{artificial array} with the
-binary operator @samp{@@}.  The left operand of @samp{@@} should be
-the first element of the desired array, as an individual object.
-The right operand should be the length of the array.  The result is
-an array value whose elements are all of the type of the left argument.
-The first element is actually the left argument; the second element
-comes from bytes of memory immediately following those that hold the
-first element, and so on.  Here is an example.  If a program says
+@table @code
+@item $_
+The variable @code{$_} is automatically set by the @samp{x} command to
+the last address examined (@pxref{Memory}).  Other commands which
+provide a default address for @samp{x} to examine also set @code{$_}
+to that address; these commands include @samp{info line} and @samp{info
+breakpoint}.
 
-@example
-int *array = (int *) malloc (len * sizeof (int));
-@end example
+@item $__
+The variable @code{$__} is automatically set by the @samp{x} command
+to the value found in the last address examined.
+@end table
 
-@noindent
-you can print the contents of @code{array} with
+@node Registers,  , Convenience Vars, Data
+@section Registers
 
-@example
-p *array@@len
-@end example
+@cindex registers
+Machine register contents can be referred to in expressions as variables
+with names starting with @samp{$}.  The names of registers are different
+for each machine; use @samp{info registers} to see the names used on your
+machine.  The names @code{$pc} and @code{$sp} are used on most machines for
+the program counter register and the stack pointer.  Often @code{$fp} is
+used for a register that contains a pointer to the current stack frame,
+and @code{$ps} is used for a register that contains the processor
+status.  These standard register names may be available on your machine
+even though the @code{info registers} command displays them with a
+different name.  For example, on the SPARC, @code{info registers}
+displays the processor status register as @code{$psr} but you can also
+refer to it as @code{$ps}.
 
-The left operand of @samp{@@} must reside in memory.  Array values made
-with @samp{@@} in this way behave just like other arrays in terms of
-subscripting, and are coerced to pointers when used in expressions.
-(It would probably appear in an expression via the value history,
-after you had printed it out.)
+_GDBN__ always considers the contents of an ordinary register as an integer
+when the register is examined in this way.  Some machines have special
+registers which can hold nothing but floating point; these registers are
+considered floating point.  There is no way to refer to the contents of an
+ordinary register as floating point value (although you can @emph{print}
+it as a floating point value with @samp{print/f $@var{regname}}).
 
-@node Format options, Output formats, Arrays, Data
-@section Format options
+Some registers have distinct ``raw'' and ``virtual'' data formats.  This
+means that the data format in which the register contents are saved by
+the operating system is not the same one that your program normally
+sees.  For example, the registers of the 68881 floating point
+coprocessor are always saved in ``extended'' (raw) format, but all C
+programs expect to work with ``double'' (virtual) format.  In such
+cases, _GDBN__ normally works with the virtual format only (the format that
+makes sense for your program), but the @samp{info registers} command
+prints the data in both formats.
 
-@cindex format options
-_GDBN__ provides a few ways to control how arrays, structures, and symbols are
-printed.  
+Register values are relative to the selected stack frame
+(@pxref{Selection}).  This means that you get the value that the register
+would contain if all stack frames farther in were exited and their saved
+registers restored.  In order to see the real contents of all registers,
+you must select the innermost frame (with @samp{frame 0}).
+
+Some registers are never saved (typically those numbered zero or one)
+because they are used for returning function values. In some operating
+systems (those using the ``caller saves'' convention), there are other
+registers intended for free alteration by a called routine.  For these
+registers, relativization makes no difference.
 
 @table @code
-@item set array-max @var{number-of-elements}
-@kindex set array-max
-If _GDBN__ is printing a large array, it will stop printing after it has
-printed the number of elements set by the @samp{set array-max} command.
-This limit also applies to the display of strings.
+@item info registers
+@kindex info registers
+Print the names and relativized values of all registers.
 
-@item show array-max
-@kindex show array-max
-Display the number of elements of a large array that _GDBN__ will print
-before losing patience.
+@item info registers @var{regname}
+Print the relativized value of register @var{regname}.  @var{regname}
+may be any register name valid on the machine you are using, with
+or without the initial @samp{$}.
+@end table
 
-@item set arrayprint
-@itemx set arrayprint on
-@kindex set arrayprint
-_GDBN__ will pretty print arrays.  This format is more convenient to read,
-but uses more space.  The default is off.
+@subsection Examples
 
-@item set arrayprint off.
-Return to compressed format for arrays.
+You could print the program counter in hex with
 
-@item show arrayprint
-@kindex show arrayprint
-Show whether compressed or pretty format is selected for displaying
-arrays. 
+@example
+p/x $pc
+@end example
 
-@item set demangle 
-@itemx set demangle on 
-@kindex set demangle
-Print C++ names in their source form rather than in the mangled form
-in which they are passed to the assembler and linker for type-safe linkage.
-The default is on.
+@noindent
+or print the instruction to be executed next with
 
-@item show demangle
-@kindex show demangle
-Show whether C++ names will be printed in mangled or demangled form.
+@example
+x/i $pc
+@end example
 
-@item set asm-demangle 
-@itemx set asm-demangle on 
-@kindex set asm-demangle
-Print C++ names in their source form rather than their mangled form, even
-in assembler code printouts such as instruction disassemblies.
-The default is off.
+@noindent
+or add four to the stack pointer with
 
-@item show asm-demangle
-@kindex show asm-demangle
-Show whether C++ names in assembly listings will be printed in mangled
-or demangled form.
+@example
+set $sp += 4
+@end example
+
+@noindent
+The last is a way of removing one word from the stack, on machines where
+stacks grow downward in memory (most machines, nowadays).  This assumes
+that the innermost 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 @samp{return};
+@pxref{Returning}.)
 
-@item set vtblprint 
-@itemx set vtblprint on 
-@kindex set vtblprint
-Pretty print C++ virtual function tables.  The default is off.
+@node Symbols, Altering, Data, Top
+@chapter Examining the Symbol Table
 
-@item set vtblprint off
-Do not pretty print C++ virtual function tables.
+The commands described in this section allow you to inquire about the
+symbols (names of variables, functions and types) defined in your
+program.  This information is found by _GDBN__ in the symbol table loaded by
+the @samp{symbol-file} command; it is inherent in the text of your
+program and does not change as the program executes.
 
-@item show vtblprint
-@kindex show vtblprint
-Show whether C++ virtual function tables are pretty printed, or not.
+@table @code
+@item info address @var{symbol}
+@kindex info address
+Describe where the data for @var{symbol} is stored.  For a register
+variable, this says which register it is kept in.  For a non-register
+local variable, this prints the stack-frame offset at which the variable
+is always stored.
 
-@item set addressprint
-@item set addressprint on
-@kindex set addressprint
-_GDBN__ will print memory addresses in stack traces, structure values, pointer
-values, breakpoints, etc.  The default is on.
+Note the contrast with @samp{print &@var{symbol}}, which does not work
+at all for a register variables, and for a stack local variable prints
+the exact address of the current instantiation of the variable.
 
-@item set addressprint off
-Do not print addresses.
+@item whatis @var{exp}
+@kindex whatis
+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}.
 
-@item show addressprint
-@kindex show addressprint
-Show whether or not addresses are to be printed.
+@item whatis
+Print the data type of @code{$}, the last value in the value history.
 
-@item set prettyprint on
-@kindex set prettyprint
-Cause _GDBN__ to print structures in an indented format with one member per
-line, like this:
+@item ptype @var{typename}
+@kindex ptype
+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
 
-@example
-$1 = @{
-  next = 0x0,
-  flags = @{
-    sweet = 1,
-    sour = 1
-  @},
-  meat = 0x54 "Pork"
-@}
-@end example
+@item ptype @var{exp}
+Print a description of the type of expression @var{exp}.  This is like
+@samp{whatis} except it prints a detailed description, instead of just
+the name of the type.  For example, if the type of a variable is
+@samp{struct complex @{double real; double imag;@}}, @samp{whatis} will
+print @samp{struct complex} and @samp{ptype} will print @samp{struct
+complex @{double real; double imag;@}}
 
-@item set prettyprint off
-Cause _GDBN__ to print structures in a compact format, like this:
+@item info sources
+@kindex info sources
+Print the names of all source files in the program for which there
+is debugging information.
 
-@smallexample
-$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, meat \
-= 0x54 "Pork"@}
-@end smallexample
+@item info functions
+@kindex info functions
+Print the names and data types of all defined functions.
 
-@noindent
-This is the default format.
+@item info functions @var{regexp}
+Print the names and data types of all defined functions
+whose names contain a match for regular expression @var{regexp}.
+Thus, @samp{info fun step} finds all functions whose names
+include @samp{step}; @samp{info fun ^step} finds those whose names
+start with @samp{step}.
 
-@item show prettyprint
-@kindex show prettyprint
-Show which format _GDBN__ will use to print structures.
+@item info variables
+@kindex info variables
+Print the names and data types of all variables that are declared
+outside of functions (i.e., except for local variables).
 
-@item set unionprint on
-@kindex set unionprint
-Tell _GDBN__ to print unions which are contained in structures.  This is the
-default setting.
+@item info variables @var{regexp}
+Print the names and data types of all variables (except for local
+variables) whose names contain a match for regular expression
+@var{regexp}.
 
-@item set unionprint off
-Tell _GDBN__ not to print unions which are contained in structures.
 
-@item show unionprint
-@kindex show unionprint
-Ask _GDBN__ whether or not it will print unions which are contained in
-structures. 
+@ignore
+This was never implemented.
+@item info methods
+@itemx info methods @var{regexp}
+@kindex info methods
+The @samp{info-methods} command permits the user to examine all defined
+methods within C++ program, or (with the @var{regexp} argument) a
+specific set of methods found in the various C++ classes.  Many
+C++ classes provide a large number of methods.  Thus, the output
+from the @samp{ptype} command can be overwhelming and hard to use.  The
+@samp{info-methods} command filters the methods, printing only those
+which match the regular-expression @var{regexp}.
+@end ignore
 
-For example, given the declarations
+@item printsyms @var{filename}
+@kindex printsyms
+Write a complete dump of the debugger's symbol data into the
+file @var{filename}.
+@end table
 
-@smallexample
-typedef enum @{Tree, Bug@} Species;
-typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
-typedef enum @{Caterpillar, Cocoon, Butterfly@} Bug_forms;
+@node Altering, Sequences, Symbols, Top
+@chapter Altering Execution
 
-struct thing @{
-  Species it;
-  union @{
-    Tree_forms tree;
-    Bug_forms bug;
-  @} form;
-@};
+Once you think you have found an error in the program, you might want to
+find out for certain whether correcting the apparent error would lead to
+correct results in the rest of the run.  You can find the answer by
+experiment, using the _GDBN__ features for altering execution of the
+program.
 
-struct thing foo = @{Tree, @{Acorn@}@};
-@end smallexample
+For example, you can store new values into variables or memory
+locations, give the program a signal, restart it at a different address,
+or even return prematurely from a function to its caller.
 
-@noindent
-with @samp{set unionprint on} in effect @samp{p foo} would print
+@menu
+* Assignment::			Altering variable values or memory contents.
+* Jumping::			Altering control flow.
+* Signaling::			Making signals happen in the program.
+* Returning::			Making a function return prematurely.
+* Calling::			Calling functions from your program
+@end menu
 
-@smallexample
-$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
-@end smallexample
+@node Assignment, Jumping, Altering, Altering
+@section Assignment to Variables
 
-@noindent
-and with @samp{set unionprint off} in effect it would print
+@cindex assignment
+@cindex setting variables
+To alter the value of a variable, evaluate an assignment expression.
+@xref{Expressions}.  For example,
 
 @example
-$1 = @{it = Tree, form = @{...@}@}
+print x=4
 @end example
-@end table
-
-@node Output formats, Auto Display, Format options, Data
-@section Output formats
 
-@cindex formatted output
-@cindex output formats
-_GDBN__ normally prints all values according to their data types.  Sometimes
-this is not what you want.  For example, you might want to print a number
-in hex, or a pointer in decimal.  Or you might want to view data in memory
-at a certain address as a character string or an instruction.  These things
-can be done with @dfn{output formats}.
+@noindent
+would store the value 4 into the variable @code{x}, and then print
+the value of the assignment expression (which is 4).
 
-The simplest use of output formats is to say how to print a value
-already computed.  This is done by starting the arguments of the
-@samp{print} command with a slash and a format letter.  The format
-letters supported are:
+All the assignment operators of C are supported, including the
+increment operators @samp{++} and @samp{--}, and combining
+assignments such as @samp{+=} and _0__@samp{<<=}_1__.
 
-@table @samp
-@item x
-Regard the bits of the value as an integer, and print the integer in
-hexadecimal.
+@kindex set
+@kindex set variable
+@cindex variables, setting
+If you are not interested in seeing the value of the assignment, use the
+@samp{set} command instead of the @samp{print} command.  @samp{set} is
+really the same as @samp{print} except that the expression's value is not
+printed and is not put in the value history (@pxref{Value History}).  The
+expression is evaluated only for side effects.
 
-@item d
-Print as integer in signed decimal.
+Note that if the beginning of the argument string of the @samp{set} command
+appears identical to a @samp{set} subcommand, it may be necessary to use
+the @samp{set variable} command.  This command is identical to @samp{set}
+except for its lack of subcommands.
 
-@item u
-Print as integer in unsigned decimal.
+_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.
+@comment FIXME: how do structs align/pad in these conversions? 
+@comment        /[e-mail] 18dec1990
 
-@item o
-Print as integer in octal.
+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} would refer
+to memory location 0x83040 as an integer (which implies a certain size
+and representation in memory), and
 
-@item a
-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
-$3 = 0x54320 <_initialize_vx+396>
+set @{int@}0x83040 = 4
 @end example
 
+would store the value 4 into that memory location.
+
+@node Jumping, Signaling, Assignment, Altering
+@section Continuing at a Different Address
+
+Ordinarily, when you continue the program, you do so at the place where
+it stopped, with the @samp{cont} command.  You can instead continue at
+an address of your own choosing, with the following commands:
+
+@table @code
+@item jump @var{linenum}
+@kindex jump
+Resume execution at line number @var{linenum}.  Execution may stop
+immediately if there is a breakpoint there.
 
-@item c
-Regard as an integer and print it as a character constant.
+The @samp{jump} command does not change the current stack frame, or
+the stack pointer, or the contents of any memory location or any
+register other than the program counter.  If line @var{linenum} is in
+a different function from the one currently executing, the results may
+be bizarre if the two functions expect different patterns of arguments or
+of local variables.  For this reason, the @samp{jump} command requests
+confirmation if the specified line is not in the function currently
+executing.  However, even bizarre results are predictable based on
+careful study of the machine-language code of the program.
 
-@item f
-Regard the bits of the value as a floating point number and print
-using typical floating point syntax.
+@item jump *@var{address}
+Resume execution at the instruction at address @var{address}.
 @end table
 
-For example, to print the program counter in hex (@pxref{Registers}), type
+You can get much the same effect as the @code{jump} command by storing a
+new value into the register @code{$pc}.  The difference is that this
+does not start the program running; it only changes the address where it
+@emph{will} run when it is continued.  For example,
 
 @example
-p/x $pc
+set $pc = 0x485
 @end example
 
 @noindent
-Note that no space is required before the slash; this is because command
-names in _GDBN__ cannot contain a slash.
-
-To reprint the last value in the value history with a different format,
-you can use the @samp{print} command with just a format and no
-expression.  For example, @samp{p/x} reprints the last value in hex.
+causes the next @samp{cont} command or stepping command to execute at
+address 0x485, rather than at the address where the program stopped.
+@xref{Stepping}.
 
-@menu
-* Memory::			Examining Memory
-@end menu
+The most common occasion to use the @samp{jump} command is to back up,
+perhaps with more breakpoints set, over a portion of a program that has
+already executed.
 
-@node Memory,  , Output formats, Output formats
-@subsection Examining Memory
+@node Signaling, Returning, Jumping, Altering
+@section Giving the Program a Signal
 
-@cindex examining memory
 @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.
+@item signal @var{signalnum}
+@kindex signal
+Resume execution where the program stopped, but give it immediately the
+signal number @var{signalnum}.
 
-@kindex x
-@item x
-The command @samp{x} (for `examine') can be used to examine memory
-without reference to the program's data types.  The format in which you
-wish to examine memory is instead explicitly specified.  The allowable
-formats are a superset of the formats described in the previous section.
+Alternatively, if @var{signalnum} is zero, continue execution without
+giving a signal.  This is useful when the program stopped on account of
+a signal and would ordinary see the signal when resumed with the
+@samp{cont} command; @samp{signal 0} causes it to resume without a
+signal.
 @end table
 
-@samp{x} is followed by a slash and an output format specification,
-followed by an expression for an address.  The expression need not have
-a pointer value (though it may); it is used as an integer, as the
-address of a byte of memory.  @xref{Expressions} for more information on
-expressions.  For example, @samp{x/4xw $sp} prints the four words of
-memory above the stack pointer in hexadecimal.
+@node Returning, Calling, Signaling, Altering
+@section Returning from a Function
 
-The output format in this case specifies both how big a unit of memory
-to examine and how to print the contents of that unit.  It is done
-with one or two of the following letters:
+@table @code
+@item return
+@cindex returning from a function
+@kindex return
+You can cancel execution of a function call with the @samp{return}
+command.
+@end table
 
-These letters specify just the size of unit to examine:
+This command has the effect of discarding the selected stack
+frame (and all frames within it), so that control moves to the caller of
+that function.  You can think of this as making the discarded frame
+return prematurely.
 
-@table @samp
-@item b
-Examine individual bytes.
+First select the stack frame that you wish to return from
+(@pxref{Selection}).  Then type the @samp{return} command.  If you wish
+to specify the value to be returned, give that as an argument.
 
-@item h
-Examine halfwords (two bytes each).
+This pops the selected stack frame (and any other frames inside of it),
+leaving its caller as the innermost remaining frame.  That frame becomes
+selected.  The specified value is stored in the registers used for
+returning values of functions.
 
-@item w
-Examine words (four bytes each).
+The @samp{return} command does not resume execution; it leaves the
+program stopped in the state that would exist if the function had just
+returned.  Contrast this with the @samp{finish} command
+(@pxref{Stepping}), which resumes execution until the selected stack
+frame returns @emph{naturally}.
 
-@cindex word
-Many assemblers and cpu designers still use `word' for a 16-bit quantity,
-as a holdover from specific predecessor machines of the 1970's that really
-did use two-byte words.  But more generally the term `word' has always
-referred to the size of quantity that a machine normally operates on and
-stores in its registers.  This is 32 bits for all the machines that _GDBN__
-runs on.
+@node     Calling,  , Returning, Altering
+@comment  node-name,  next,  previous,  up
+@section Calling your Program's Functions
 
-@item g
-Examine giant words (8 bytes).
+@cindex calling functions
+@kindex call
+@table @code
+@item call @var{expr}
+Evaluate the expression @var{expr} without displaying @code{void}
+returned values.
 @end table
 
-These letters specify just the way to print the contents:
-
-@table @samp
-@item x
-Print as integers in unsigned hexadecimal.
-
-@item d
-Print as integers in signed decimal.
+You can use this variant of the @samp{print} command if you want to
+execute some piece of your program, but without cluttering the output
+with @code{void} returned values.  The result is printed and saved in
+the value history, if it is not void.
 
-@item u
-Print as integers in unsigned decimal.
+@node Files,,,
+@chapter _GDBN__'s Files
 
-@item o
-Print as integers in unsigned octal.
+@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 the program.  To
+debug a core dump of a previous run, _GDBN__ must be told the file name of
+the core dump.
 
-@item a
-Print as an address, both absolute in hex and then relative
-to a symbol defined as an address below it.
+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}.
 
-@item c
-Print as character constants.
+But 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
+want to use.  In these situations the _GDBN__ commands to specify new files
+are useful.
 
-@item f
-Print as floating point.  This works only with sizes @samp{w} and
-@samp{g}.
+@table @code
+@item file @var{filename}
+@cindex executable file
+@kindex file
+Use @var{filename} as the program to be debugged.  It is read for its
+symbols, for getting the contents of pure memory, and it is the program
+executed when you use the @samp{run} command.  If you do not specify a
+directory and the file is not found in _GDBN__'s working directory,
+_GDBN__ will use the environment variable @code{PATH} as a list of
+directories to search, just as the shell does when looking for a program
+to run.
 
-@item s
-Print a null-terminated string of characters.  The specified unit size
-is ignored; instead, the unit is however many bytes it takes to reach
-a null character (including the null character).
+@samp{file} with no argument makes both executable file and symbol
+table become unspecified.
 
-@item i
-Print a machine instruction in assembler syntax (or nearly).  The
-specified unit size is ignored; the number of bytes in an instruction
-varies depending on the type of machine, the opcode and the addressing
-modes used.  The command @samp{disassemble} gives an alternative way of
-inspecting machine instructions.
-@end table
+@item exec-file @var{filename}
+@kindex exec-file
+Specify that the program to be run (but not the symbol table) is found
+in @var{filename}.  _GDBN__ will search the environment variable @code{PATH}
+if necessary to locate the program.
 
-If either the manner of printing or the size of unit fails to be specified,
-the default is to use the same one that was used last.  If you don't want
-to use any letters after the slash, you can omit the slash as well.
+@item symbol-file @var{filename}
+@kindex symbol-file
+Read symbol table information from file @var{filename}.  @code{PATH} is
+searched when necessary.  Use the @samp{file} command to get both symbol
+table and program to run from the same file.
 
-You can also omit the address to examine.  Then the address used is just
-after the last unit examined.  This is why string and instruction
-formats actually compute a unit-size based on the data: so that the next
-string or instruction examined will start in the right place.  
+@samp{symbol-file} with no argument clears out _GDBN__'s information on your
+program's symbol table.
 
-When the @samp{print} command shows a value that resides in memory,
-@samp{print} also sets the default address for the @samp{x} command.
-@samp{info line} also sets the default for @samp{x}, to the address of
-the start of the machine code for the specified line and @samp{info
-breakpoints} sets it to the address of the last breakpoint listed.
+The @samp{symbol-file} command causes _GDBN__ to forget the contents of its
+convenience variables, the value history, and all breakpoints and
+auto-display expressions.  This is because they may contain pointers to
+the internal data recording symbols and data types, which are part of
+the old symbol table data being discarded inside _GDBN__.
 
-When you use @key{RET} to repeat an @samp{x} command, the address
-specified previously (if any) is ignored, so that the repeated command
-examines the successive locations in memory rather than the same ones.
+On some kinds of object files, the @samp{symbol-file} command does not
+actually 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.
 
-You can examine several consecutive units of memory with one command by
-writing a repeat-count after the slash (before the format letters, if any).
-The repeat count must be a decimal integer.  It has the same effect as
-repeating the @samp{x} command that many times except that the output may
-be more compact with several units per line.  For example,
+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 @samp{set verbose} command can turn these pauses into
+messages if desired. @xref{User Interface}).
 
-@example
-x/10i $pc
-@end example
+When the symbol table is stored in COFF format, @samp{symbol-file} does
+read the symbol table data in full right away.  We haven't implemented
+the two-stage strategy for COFF yet.
 
-@noindent
-prints ten instructions starting with the one to be executed next in the
-selected frame.  After doing this, you could print another seven following
-instructions with
+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 the GNU compiler _GCC__, or other
+compilers that adhere to the local conventions.  Best results are
+usually obtained from _GCC__; for example, using _GCC__ you can generate
+debugging information for optimized code.
 
-@example
-x/7
-@end example
+@item core-file @var{filename}
+@itemx core @var{filename}
+@kindex core
+@kindex core-file
+Specify the whereabouts of a core dump file to be used as the ``contents
+of memory''.  Traditionally, core files contain only some parts of the
+address space of the process that generated them; _GDBN__ can access the
+executable file itself for other parts.
 
-@noindent
-in which the format and address are allowed to default.
+@samp{core-file} with no argument specifies that no core file is
+to be used.
 
-@kindex $_
-@kindex $__
-The addresses and contents printed by the @samp{x} command are not put in
-the value history because there is often too much of them and they would
-get in the way.  Instead, _GDBN__ makes these values available for subsequent
-use in expressions as values of the convenience variables @code{$_} and
-@code{$__}.
+Note that the core file is ignored when your program is actually running
+under _GDBN__.  So, if you have been running the 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 @samp{kill} command
+(@pxref{Kill Process}).
 
-After an @samp{x} command, the last address examined is available for use
-in expressions in the convenience variable @code{$_}.  The contents of that
-address, as examined, are available in the convenience variable @code{$__}.
+@item load @var{filename}
+@kindex load
+This command will dynamically link @var{filename} on the current target,
+performing any necessary downloads, then add @var{filename}'s symbol
+table in the same way as the @samp{add-syms} command.
 
-If the @samp{x} command has a repeat count, the address and contents saved
-are from the last memory unit printed; this is not the same as the last
-address printed if several units were printed on the last line of output.
+@item add-syms @var{filename} @var{address}
+@kindex add-syms
+@cindex dynamic linking
+The @samp{add-syms} command reads additional symbol table information
+from the file @var{filename}.  You would use this command when that file
+has been dynamically loaded (by some other means) into the program that
+is running.  @var{address} should be the memory address at which the
+file has been loaded; _GDBN__ cannot figure this out for itself.
 
-@node Auto Display, Value History, Output formats, Data
-@section Automatic Display
-@cindex automatic display
-@cindex display of expressions
+The symbol table of the file @var{filename} is added to the symbol table
+originally read with the @samp{symbol-file} command.  You can use the
+@samp{add-syms} command any number of times; the new symbol data thus
+read keeps adding to the old.  The @samp{symbol-file} command forgets
+all the symbol data _GDBN__ has read.
 
-If you find that you want to print the value of an expression frequently
-(to see how it changes), you might want to add it to the @dfn{automatic
-display list} so that _GDBN__ will print its value each time the program stops.
-Each expression added to the list is given a number to identify it;
-to remove an expression from the list, you specify that number.
-The automatic display looks like this:
+@item info files
+@itemx info target
+@kindex info files
+@kindex info target
+@samp{info files} and @samp{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.
 
-@example
-2: foo = 38
-3: bar[5] = (struct hack *) 0x3804
-@end example
+Beware: the similar command @samp{info targets} lists all possible
+targets rather than current ones.
 
-@noindent
-showing item numbers, expressions and their current values.
+@end table
 
-If the expression refers to local variables, then it does not make sense
-outside the lexical context for which it was set up.  Such an expression
-is disabled when execution enters a context where one of its variables
-is not defined.  For example, if you give the command 
-@samp{display name} while inside a function with an argument
-@code{name}, then this argument will be displayed while the program
-continues to stop inside that function.  When it stops elsewhere---where
-there is no variable @samp{name}---display is disabled.  The next time
-your program stops where @samp{name} is meaningful, you can enable the
-display expression once again.
+While all three file-specifying commands allow both absolute and relative
+file names as arguments, _GDBN__ always converts the file name to an absolute
+one and remembers it that way.
 
-@table @code
-@item display @var{exp}
-@kindex display
-Add the expression @var{exp} to the list of expressions to display
-each time the program stops.  @xref{Expressions}.
+@kindex sharedlibrary
+@kindex share
+@cindex shared libraries
 
-@item display/@var{fmt} @var{exp}
-For @var{fmt} specifying only a display format and not a size or
-count, add the expression @var{exp} to the auto-display list but
-arranges to display it each time in the specified format @var{fmt}.
+_GDBN__ supports the SunOS shared library format.  Symbols from a shared
+library cannot be referenced before the shared library has been linked
+with the program.  (That is to say, after one types @samp{run} and 
+the function @code{main()} has been entered; or when examining core
+files.)  Once the shared library has been linked in, you can use the
+following commands:
 
-@item display/@var{fmt} @var{addr}
-For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
-number of units, add the expression @var{addr} as a memory address to
-be examined each time the program stops.  Examining means in effect
-doing @samp{x/@var{fmt} @var{addr}}.  @xref{Memory}.
+@table @code
+@item sharedlibrary @var{regex}
+@itemx share @var{regex}
+Load shared object library symbols for files matching a UNIX regular
+expression.
 
-@item undisplay @var{dnums}@dots{}
-@itemx delete display @var{dnums}@dots{}
-@kindex delete display
-@kindex undisplay
-Remove item numbers @var{dnums} from the list of expressions to display.
+@item share
+@itemx sharedlibrary
+Load symbols for all shared libraries.
 
-@item disable display @var{dnums}@dots{}
-@kindex disable display
-Disable the display of item numbers @var{dnums}.  A disabled display
-item is not printed automatically, but is not forgotten.  It may be
-enabled again later.
+@item info share
+@itemx info sharedlibrary
+@kindex info sharedlibrary
+@kindex info share
+Print the names of the shared libraries which are currently loaded.
+@end table
 
-@item enable display @var{dnums}@dots{}
-@kindex enable display
-Enable display of item numbers @var{dnums}.  It becomes effective once
-again in auto display of its expression, until you specify otherwise.
+@section Errors Reading Symbols
+While a symbol file is being read, _GDBN__ will occasionally encounter
+problems, such as symbol types it does not recognize, or known bugs in
+compiler output.  By default, it prints one message about each such
+type of problem, no matter how many times the problem occurs.  You can
+ask it to print more messages, to see how many times the problems occur,
+or can shut the messages off entirely, with the @samp{set 
+complaints} command (@xref{User Interface}).
 
-@item display
-Display the current values of the expressions on the list, just as is
-done when the program stops.
+The messages currently printed, and their meanings, are:
 
-@item info display
-@kindex info display
-Print the list of expressions previously set up to display
-automatically, each one with its item number, but without showing the
-values.  This includes disabled expressions, which are marked as such.
-It also includes expressions which would not be displayed right now
-because they refer to automatic variables not currently available.
-@end table
+@table @code
+@item inner block not inside outer block in @var{symbol}
 
-@node Value History, Convenience Vars, Auto Display, Data
-@section Value History
+The symbol information shows where symbol scopes begin and end
+(such as at the start of a function or a block of statements).  This
+error indicates that an inner scope block is not fully contained
+in its outer scope blocks.  _GDBN__ circumvents the problem by treating
+the inner block as if it had the same scope as the outer block.
+@var{symbol} may be ``(don't know)'' if the outer block is not
+a function.
 
-@cindex value history
-Values printed by the @samp{print} command are saved in _GDBN__'s @dfn{value
-history} so that you can refer to them in other expressions.  Values are
-kept until the symbol table is re-read or discarded (for example with
-the @samp{file} or @samp{symbol-file} commands).  When the symbol table
-changes, the value history is discarded, since the values may contain
-pointers back to the types defined in the symbol table.
+@item block at @var{address} out of order
 
-@cindex @code{$}
-@cindex @code{$$}
-@cindex history number
-The values printed are given @dfn{history numbers} for you to refer to them
-by.  These are successive integers starting with 1.  @samp{print} shows you
-the history number assigned to a value by printing @samp{$@var{num} = }
-before the value; here @var{num} is the history number.
+The symbol information for symbol scope blocks should occur in 
+order of increasing addresses.  This error indicates that it does not
+do so.  _GDBN__ does not circumvent this problem, and will have trouble
+locating symbols in the source file whose symbols being read.  (You
+can often determine what source file is affected by turning on
+@samp{info verbose}.  @xref{User Interface}.)
 
-To refer to any previous value, use @samp{$} followed by the value's
-history number.  The output printed by @samp{print} is designed to
-remind you of this.  Just @code{$} refers to the most recent value in
-the history, and @code{$$} refers to the value before that.
-@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2}
-is the value just prior to @code{$$}, @code{$$1} is equivalent to
-@code{$$}, and @code{$$0} is equivalent to @code{$}.
+@item bad block start address patched
 
-For example, suppose you have just printed a pointer to a structure and
-want to see the contents of the structure.  It suffices to type
+The symbol information for a symbol scope block has a start address
+smaller than the address of the preceding source line.  This is known
+to occur in the SunOS 4.1.1 (and earlier) C compiler.  _GDBN__ circumvents
+the problem by treating the symbol scope block as starting on the
+previous source line.
 
-@example
-p *$
-@end example
+@comment @item{encountered DBX-style class variable debugging information.
+@comment You seem to have compiled your program with "g++ -g0" instead of "g++ -g".
+@comment Therefore _GDBN__ will not know about your class variables}
+@comment 
+@comment This error indicates that the symbol information produced for a C++
+@comment program includes zero-size fields, which indicated static fields in
+@comment a previous release of the G++ compiler.  This message is probably
+@comment obsolete.
+@comment
+@item bad string table offset in symbol @var{n}
 
-If you have a chain of structures where the component @samp{next} points
-to the next one, you can print the contents of the next one with this:
+Symbol number @var{n} contains a pointer into the string table which is
+larger than the size of the string table.  _GDBN__ circumvents the problem
+by considering the symbol to have the name @code{foo}, which may cause
+other problems if many symbols end up with this name.  @cindex{foo}
 
-@example
-p *$.next
-@end example
+@item unknown symbol type @code{0xNN}
 
-@noindent
-It might be useful to repeat this command many times by typing @key{RET}.
+The symbol information contains new data types that _GDBN__ does not yet
+know how to read.  @code{0xNN} is the symbol type of the misunderstood
+information, in hexadecimal.  _GDBN__ circumvents the error by ignoring
+this symbol information.  This will usually allow the program to be
+debugged, though certain symbols will not be accessible.  If you
+encounter such a problem and feel like debugging it, you can debug _GDBP__
+with itself, breakpoint on "complain", then go "up" to
+read_dbx_symtab() and examine *bufp to see the symbol.
 
-Note that the history records values, not expressions.  If the value of
-@code{x} is 4 and you type this command:
+@c @item stub type has NULL name
+@c 
+@c FIXME, Mike Tiemann needs to write about what this means.
 
-@example
-print x
-set x=5
-@end example
+@item const/volatile indicator missing, got 'X'
 
-@noindent
-then the value recorded in the value history by the @samp{print} command
-remains 4 even though the value of @code{x} has changed.
+The symbol information for a C++ type is missing some information that
+the compiler should have output for it.
 
-@table @code
-@kindex info values
-@item info values
-@itemx info history
-@kindex info history
-These two commands are synonymous.  Either form will print the last ten
-values in the value history, with their item numbers.  This is like
-@samp{p@ $$9} repeated ten times, except that @samp{info values} does
-not change the history.
+@item C++ type mismatch between compiler and debugger
 
-@item info values @var{n}
-Print ten history values centered on history item number @var{n}.
+The debugger could not parse a type specification output by the compiler
+for some C++ object.
 
-@item info values +
-Print ten history values just after the values last printed.
 @end table
 
-@node Convenience Vars, Registers, Value History, Data
-@section Convenience Variables
+@node     Targets, Running, Compilation, Top
+@chapter Specifying a Debugging Target 
+@cindex debugging target
+@kindex target
+A @dfn{target} is an interface between the debugger and a particular 
+kind of file or process.  
 
-@cindex convenience variables
-_GDBN__ provides @dfn{convenience variables} that you can use within _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 effect on further execution of your program.  That's why
-you can use them freely.
+Often, you will be able to run _GDBN__ in the same host environment as the
+program you are debugging; in that case, the debugging target can just be
+specified as a side effect of the @samp{file} or @samp{core} commands.
+When you need more flexibility---for example, running _GDBN__ on a
+physically separate host, controlling standalone systems over a
+serial port, or realtime systems over a TCP/IP connection---you can use
+the @samp{target} command.
 
-Convenience variables have names starting with @samp{$}.  Any name starting
-with @samp{$} can be used for a convenience variable, unless it is one of
-the predefined set of register names (@pxref{Registers}).
+@menu
+* Active Targets::		Active Targets
+* Target Commands::		Commands for Managing Targets
+@end menu
 
-You can save a value in a convenience variable with an assignment
-expression, just as you would set a variable in your program.  Example:
+@node Active Targets, Target Commands, Targets, Targets
+@section Active Targets
+@cindex stacking targets
+@cindex active targets
+@cindex multiple targets
 
-@example
-set $foo = *object_ptr
-@end example
+Targets are managed in three @dfn{strata} that correspond to different
+classes of target: processes, core files, and executable files.  This
+allows you to (for example) start a process and inspect its activity
+without abandoning your work on a core file.
 
-@noindent
-would save in @code{$foo} the value contained in the object pointed to by
-@code{object_ptr}.
+More than one target can potentially respond to a request.  In
+particular, when you access memory _GDBN__ will walk down the three strata of
+targets until it finds a target that can handle that particular address.
 
-Using a convenience variable for the first time creates it; but its value
-is @code{void} until you assign a new value.  You can alter the value with
-another assignment at any time.
+Strata are always examined in a fixed order: first a process if there is
+one, then a core file if there is one, and finally an executable file if
+there is one of those.
 
-Convenience variables have no fixed types.  You can assign a convenience
-variable any type of value, including structures and arrays, even if
-that variable already has a value of a different type.  The convenience
-variable as an expression has whatever type its current value has.
+When you specify a new target in a given stratum, it replaces any target
+previously in that stratum.
 
-@table @code
-@item info convenience
-@kindex info convenience
-Print a list of convenience variables used so far, and their values.
-Abbreviated @samp{i con}.
-@end table
+To get rid of a target without replacing it, use the @samp{detach}
+command.  The related command @samp{attach} provides you with a way of
+choosing a particular running process as a new target. @xref{Attach}.
 
-One of the ways to use a convenience variable is as a counter to be
-incremented or a pointer to be advanced.  For example:
+@node Target Commands,  , Active Targets, Targets
+@section Commands for Managing Targets
 
+@table @code
+@item target @var{type} @var{parameters}
+Connects the _GDBN__ host environment to a target machine or process.  A
+target is typically a protocol for talking to debugging facilities.  You
+use the argument @var{type} to specify the type or protocol of the
+target machine; for example, @samp{target vxworks} for a TCP/IP link to
+a VxWorks system.
+
+Further @var{parameters} are interpreted by the target protocol, but
+typically include things like device names or host names to connect
+with, process numbers, and baud rates.  Executing 
 @example
-set $i = 0
-print bar[$i++]->contents
-@i{@dots{}repeat that command by typing @key{RET}.}
+   target @var{type}
 @end example
 
-Some convenience variables are created automatically by _GDBN__ and given
-values likely to be useful.
-
-@table @code
-@item $_
-The variable @code{$_} is automatically set by the @samp{x} command to
-the last address examined (@pxref{Memory}).  Other commands which
-provide a default address for @samp{x} to examine also set @code{$_}
-to that address; these commands include @samp{info line} and @samp{info
-breakpoint}.
+@noindent
+(without any parameters) will issue a message about what
+parameters are required for that target type.
 
-@item $__
-The variable @code{$__} is automatically set by the @samp{x} command
-to the value found in the last address examined.
+@item info targets
+@kindex info targets
+Displays the names of all targets available.  Beware: the similar
+command @samp{info target} displays targets currently in use rather than
+all available ones.  @samp{info files} gives the same information as
+@samp{info target} (@pxref{Files}).
 @end table
 
-@node Registers,  , Convenience Vars, Data
-@section Registers
+Here are some common targets (available, or not, depending on _GDBN__
+configuration):
 
-@cindex registers
-Machine register contents can be referred to in expressions as variables
-with names starting with @samp{$}.  The names of registers are different
-for each machine; use @samp{info registers} to see the names used on your
-machine.  The names @code{$pc} and @code{$sp} are used on most machines for
-the program counter register and the stack pointer.  Often @code{$fp} is
-used for a register that contains a pointer to the current stack frame,
-and @code{$ps} is used for a register that contains the processor
-status.  These standard register names may be available on your machine
-even though the @code{info registers} command displays them with a
-different name.  For example, on the SPARC, @code{info registers}
-displays the processor status register as @code{$psr} but you can also
-refer to it as @code{$ps}.
+@table @code
+@item target exec @var{prog}
+@kindex target exec
+An executable file.  @samp{target exec @var{prog}} is the same as
+@samp{exec-file @var{prog}}.
 
-_GDBN__ always considers the contents of an ordinary register as an integer
-when the register is examined in this way.  Some machines have special
-registers which can hold nothing but floating point; these registers are
-considered floating point.  There is no way to refer to the contents of an
-ordinary register as floating point value (although you can @emph{print}
-it as a floating point value with @samp{print/f $@var{regname}}).
+@item target core @var{filename}
+@kindex target core
+A core dump file.  @samp{target core @var{filename}} is the same as
+@samp{core-file @var{filename}}.
 
-Some registers have distinct ``raw'' and ``virtual'' data formats.  This
-means that the data format in which the register contents are saved by
-the operating system is not the same one that your program normally
-sees.  For example, the registers of the 68881 floating point
-coprocessor are always saved in ``extended'' (raw) format, but all C
-programs expect to work with ``double'' (virtual) format.  In such
-cases, _GDBN__ normally works with the virtual format only (the format that
-makes sense for your program), but the @samp{info registers} command
-prints the data in both formats.
+@item target remote @var{dev}
+@kindex target remote
+Remote serial target in _GDBP__-specific protocol.  The argument @var{dev}
+specifies what serial device to use for the connection (e.g.
+@code{/dev/ttya}).
 
-Register values are relative to the selected stack frame
-(@pxref{Selection}).  This means that you get the value that the register
-would contain if all stack frames farther in were exited and their saved
-registers restored.  In order to see the real contents of all registers,
-you must select the innermost frame (with @samp{frame 0}).
+_if__(_AMD29K__)
+@item target amd-eb @var{dev} @var{speed} @var{PROG}
+@kindex target amd-eb
+@cindex AMD EB29K
+Remote PC-resident AMD EB29K board, attached over serial lines.
+@var{dev} is the serial device, as for @samp{target remote};
+@samp{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}.
 
-Some registers are never saved (typically those numbered zero or one)
-because they are used for returning function values. In some operating
-systems (those using the ``caller saves'' convention), there are other
-registers intended for free alteration by a called routine.  For these
-registers, relativization makes no difference.
+_fi__(_AMD29K__)
+_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.
+@samp{/dev/ttya}.  
 
-@table @code
-@item info registers
-@kindex info registers
-Print the names and relativized values of all registers.
+_fi__(_I960__)
+_if__(_VXWORKS__)
+@item target vxworks @var{machinename}
+@kindex target vxworks
+A VxWorks system, attached via TCP/IP.  The argument @var{machinename}
+is the target system's machine name or IP address.
 
-@item info registers @var{regname}
-Print the relativized value of register @var{regname}.  @var{regname}
-may be any register name valid on the machine you are using, with
-or without the initial @samp{$}.
+_fi__(_VXWORKS__)
 @end table
 
-@subsection Examples
-
-You could print the program counter in hex with
+_if__(_GENERIC__)
+Different targets are available on different configurations of _GDBN__; your
+configuration may have more or fewer targets.
+_fi__(_GENERIC__)
 
-@example
-p/x $pc
-@end example
+@node Remote,,,
+@section Remote Debugging
+@cindex remote debugging
 
-@noindent
-or print the instruction to be executed next with
+If you are trying to debug a program running on a machine that can't run
+_GDBN__ in the usual way, it is often useful to use remote debugging.  For
+example, you might be debugging an operating system kernel, or debugging
+a small system which does not have a general purpose operating system
+powerful enough to run a full-featured debugger.  Currently _GDBN__ supports
+remote debugging over a serial connection, and (using Sun RPC) over a
+TCP/IP connection.
 
-@example
-x/i $pc
-@end example
+The program to be debugged on the remote machine needs to contain a
+debugging device driver which talks to _GDBN__ over the serial line.  The
+same version of _GDBN__ that is used ordinarily can be used for this.
+Several sample remote debugging drivers are distributed with _GDBN__; see
+the @file{README} file in the _GDBN__ distribution for more information.
 
-@noindent
-or add four to the stack pointer with
+@menu
+* Remote Commands::		Commands used to start and finish remote debugging.
+@end menu
 
-@example
-set $sp += 4
-@end example
+For details of the communication protocol, see the comments in the _GDBN__
+source file @file{remote.c}.
 
-@noindent
-The last is a way of removing one word from the stack, on machines where
-stacks grow downward in memory (most machines, nowadays).  This assumes
-that the innermost 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 @samp{return};
-@pxref{Returning}.)
+@node Remote Commands,  , Remote, Remote
+@subsection Commands for Remote Debugging
 
-@node Symbols, Altering, Data, Top
-@chapter Examining the Symbol Table
+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 find the program's symbols and the contents of its pure text.  Then
+establish communication using the @samp{target remote} command with a device
+name as an argument.  For example:
 
-The commands described in this section allow you to inquire about the
-symbols (names of variables, functions and types) defined in your
-program.  This information is found by _GDBN__ in the symbol table loaded by
-the @samp{symbol-file} command; it is inherent in the text of your
-program and does not change as the program executes.
+@example
+target remote /dev/ttyb
+@end example
 
-@table @code
-@item info address @var{symbol}
-@kindex info address
-Describe where the data for @var{symbol} is stored.  For a register
-variable, this says which register it is kept in.  For a non-register
-local variable, this prints the stack-frame offset at which the variable
-is always stored.
+@noindent
+if the serial line is connected to the device named @file{/dev/ttyb}.  This
+will stop the remote machine if it is not already stopped.
 
-Note the contrast with @samp{print &@var{symbol}}, which does not work
-at all for a register variables, and for a stack local variable prints
-the exact address of the current instantiation of the variable.
+Now you can use all the usual commands to examine and change data and to
+step and continue the remote program.
 
-@item whatis @var{exp}
-@kindex whatis
-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}.
+To resume the remote program and stop debugging it, use the @samp{detach}
+command.
 
-@item whatis
-Print the data type of @code{$}, the last value in the value history.
+Other remote targets be available in your
+configuration of _GDBN__; use @samp{info targets} to list them.  
 
-@item ptype @var{typename}
-@kindex ptype
-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
+@table @code
+@item reset
+@kindex reset
+For a target attached through a serial line, this command sends a
+``break'' to the remote target system; this is only useful if the target
+has been equipped with a circuit to perform a hard reset (or some other
+interesting action) when a break is detected.
+@end table
 
-@item ptype @var{exp}
-Print a description of the type of expression @var{exp}.  This is like
-@samp{whatis} except it prints a detailed description, instead of just
-the name of the type.  For example, if the type of a variable is
-@samp{struct complex @{double real; double imag;@}}, @samp{whatis} will
-print @samp{struct complex} and @samp{ptype} will print @samp{struct
-complex @{double real; double imag;@}}
+@node Controlling _GDBN__,,,
+@chapter Controlling _GDBN__
 
-@item info sources
-@kindex info sources
-Print the names of all source files in the program for which there
-is debugging information.
+You can alter many aspects of _GDBN__'s interaction with you by using
+the @samp{set} command.
 
-@item info functions
-@kindex info functions
-Print the names and data types of all defined functions.
+@node Prompt,,,
+@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 @samp{set prompt} command.  For
+instance, when debugging _GDBN__ with _GDBN__, it is useful to change the prompt
+in one of the _GDBN__s so that you tell which one you are talking to.
 
-@item info functions @var{regexp}
-Print the names and data types of all defined functions
-whose names contain a match for regular expression @var{regexp}.
-Thus, @samp{info fun step} finds all functions whose names
-include @samp{step}; @samp{info fun ^step} finds those whose names
-start with @samp{step}.
+@table @code
+@item set prompt @var{newprompt}
+@kindex set prompt
+Directs _GDBN__ to use @var{newprompt} as its prompt string henceforth.
+@kindex show prompt
+@item show prompt
+Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
+@end table
 
-@item info variables
-@kindex info variables
-Print the names and data types of all variables that are declared
-outside of functions (i.e., except for local variables).
+@node Editing/History,,,
+@section Command Editing and History
+@cindex readline
+@cindex command line editing
+@cindex history substitution
+_GDBN__ reads its input commands via the @code{readline} interface.  This
+GNU library provides consistent behavior for programs which provide a
+command line interface to the user.  Advantages are @samp{emacs}-style
+or @samp{vi}-style inline editing of commands, @samp{csh}-like history
+substitution, and a storage and recall of command history across
+debugging sessions.
 
-@item info variables @var{regexp}
-Print the names and data types of all variables (except for local
-variables) whose names contain a match for regular expression
-@var{regexp}.
+You may control the behavior of command line editing in _GDBN__ with the
+command @samp{set}.  You may check the status of any of these settings
+with the command @samp{show}.
 
+@table @code
+@kindex set editing
+@cindex editing
+@item set editing
+@itemx set editing on
+Enable command line editing (enabled by default).
 
-@ignore
-This was never implemented.
-@item info methods
-@itemx info methods @var{regexp}
-@kindex info methods
-The @samp{info-methods} command permits the user to examine all defined
-methods within C++ program, or (with the @var{regexp} argument) a
-specific set of methods found in the various C++ classes.  Many
-C++ classes provide a large number of methods.  Thus, the output
-from the @samp{ptype} command can be overwhelming and hard to use.  The
-@samp{info-methods} command filters the methods, printing only those
-which match the regular-expression @var{regexp}.
-@end ignore
+@item set editing off
+Disable command line editing.
 
-@item printsyms @var{filename}
-@kindex printsyms
-Write a complete dump of the debugger's symbol data into the
-file @var{filename}.
-@end table
+@kindex show editing
+@item show editing
+Show whether command line editing is enabled.
 
-@node Altering, Sequences, Symbols, Top
-@chapter Altering Execution
+@cindex history file
+@kindex set history file
+@item set history file @var{filename}
+Set the name of the _GDBN__ command history file to @samp{filename}.  This is
+the file from which _GDBN__ will read an initial command history
+list or to which it will write this list when it exits.  This list is
+accessed through history expansion or through the history
+command editing characters listed below.  This file defaults to the
+value of the environmental variable @code{GDBHISTFILE}, or to
+@code{./.gdb_history} if this variable is not set.
 
-Once you think you have found an error in the program, you might want to
-find out for certain whether correcting the apparent error would lead to
-correct results in the rest of the run.  You can find the answer by
-experiment, using the _GDBN__ features for altering execution of the
-program.
+@cindex history write
+@kindex set history write
+@item set history write
+@itemx set history write on
+Make _GDBN__ record command history in a file, whose name may be specified with the
+@samp{set history file} command.  By default, this option is disabled.
 
-For example, you can store new values into variables or memory
-locations, give the program a signal, restart it at a different address,
-or even return prematurely from a function to its caller.
+@item set history write off
+Make _GDBN__ stop recording command history in a file.
 
-@menu
-* Assignment::			Altering variable values or memory contents.
-* Jumping::			Altering control flow.
-* Signaling::			Making signals happen in the program.
-* Returning::			Making a function return prematurely.
-* Calling::			Calling functions from your program
-@end menu
+@cindex history size
+@kindex set history size
+@item set history size @var{size}
+Set the number of commands which _GDBN__ will keep in its history list.
+This defaults to the value of the environmental variable
+@code{HISTSIZE}, or to 256 if this variable is not set.
+@end table
 
-@node Assignment, Jumping, Altering, Altering
-@section Assignment to Variables
+@cindex history expansion
+History expansion assigns special meaning to the character @samp{!}
+(@pxref{Event Designators}).  Since @samp{!} is also the logical not
+operator in C, history expansion is off by default. If you decide to
+enable history expansion with the @samp{set history expansion on}
+command, you may sometimes need to follow @samp{!} (when it is used as
+logical not, in an expression) with a space or a tab to prevent it from
+being expanded.  The @code{readline} history facilities will not attempt
+substitution on the strings @samp{!=} and @samp{!(}, even when history
+expansion is enabled.
 
-@cindex assignment
-@cindex setting variables
-To alter the value of a variable, evaluate an assignment expression.
-@xref{Expressions}.  For example,
+The commands to control history expansion are:
 
-@example
-print x=4
-@end example
+@table @code
 
-@noindent
-would store the value 4 into the variable @code{x}, and then print
-the value of the assignment expression (which is 4).
+@kindex set history expansion
+@item set history expansion on
+@itemx set history expansion
+Enable history expansion.  History expansion is off by default.
 
-All the assignment operators of C are supported, including the
-increment operators @samp{++} and @samp{--}, and combining
-assignments such as @samp{+=} and @samp{<<=}.
+@item set history expansion off
+Disable history expansion.
 
-@kindex set
-@kindex set variable
-@cindex variables, setting
-If you are not interested in seeing the value of the assignment, use the
-@samp{set} command instead of the @samp{print} command.  @samp{set} is
-really the same as @samp{print} except that the expression's value is not
-printed and is not put in the value history (@pxref{Value History}).  The
-expression is evaluated only for side effects.
+The @code{readline} code comes with more complete documentation of
+editing and history expansion features.  Users unfamiliar with @samp{emacs}
+or @samp{vi} may wish to read it. @xref{Command Line Editing}.
 
-Note that if the beginning of the argument string of the @samp{set} command
-appears identical to a @samp{set} subcommand, it may be necessary to use
-the @samp{set variable} command.  This command is identical to @samp{set}
-except for its lack of subcommands.
+@kindex show history
+@item show history
+@itemx show history file
+@itemx show history write
+@itemx show history size
+@itemx show history expansion
+These commands display the state of the _GDBN__ history parameters.
+@samp{show history} by itself displays all four states.
 
-_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.
-@comment FIXME: how do structs align/pad in these conversions? 
-@comment        /[e-mail] 18dec1990
+@end table
 
-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} would refer
-to memory location 0x83040 as an integer (which implies a certain size
-and representation in memory), and
+@table @code
+@kindex info editing
+@item info editing
+Display the last ten commands in the command history.
 
-@example
-set @{int@}0x83040 = 4
-@end example
+@item info editing @var{n}
+Print ten commands centered on command number @var{n}.
 
-would store the value 4 into that memory location.
+@item info editing +
+Print ten commands just after the commands last printed.
 
-@node Jumping, Signaling, Assignment, Altering
-@section Continuing at a Different Address
+@end table
 
-Ordinarily, when you continue the program, you do so at the place where
-it stopped, with the @samp{cont} command.  You can instead continue at
-an address of your own choosing, with the following commands:
+@node Screen Size,,,
+@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} when you want
+to continue the output.  Normally _GDBN__ knows the size of the screen from
+the termcap data base together with the value of the @code{TERM}
+environment variable and the @code{stty rows} and @code{stty cols}
+settings. If this is not correct, you can override it with
+the @samp{set screen-height} and @samp{set screen-width} commands:
 
-@table @code
-@item jump @var{linenum}
-@kindex jump
-Resume execution at line number @var{linenum}.  Execution may stop
-immediately if there is a breakpoint there.
+_GDBN__ also uses the screen width setting to determine when to wrap lines
+of output.  Depending what is being printed, it tries to break the
+line at a readable place, rather than simply letting it overflow onto
+the following line.
 
-The @samp{jump} command does not change the current stack frame, or
-the stack pointer, or the contents of any memory location or any
-register other than the program counter.  If line @var{linenum} is in
-a different function from the one currently executing, the results may
-be bizarre if the two functions expect different patterns of arguments or
-of local variables.  For this reason, the @samp{jump} command requests
-confirmation if the specified line is not in the function currently
-executing.  However, even bizarre results are predictable based on
-careful study of the machine-language code of the program.
+@table @code
+@item set screen-height @var{lpp}
+@itemx show screen-height
+@itemx set screen-width @var{cpl}
+@itemx show screen-width
+@kindex set screen-height
+@kindex set screen-width
+@kindex show screen-width
+@kindex show screen-height
+These @samp{set} commands specify a screen height of @var{lpp} lines and
+a screen width of @var{cpl} characters.  The associated @samp{show}
+commands display the current settings.
 
-@item jump *@var{address}
-Resume execution at the instruction at address @var{address}.
+If you specify a height of zero lines, _GDBN__ will not pause during output
+no matter how long the output is.  This is useful if output is to a file
+or to an editor buffer.
 @end table
 
-You can get much the same effect as the @code{jump} command by storing a
-new value into the register @code{$pc}.  The difference is that this
-does not start the program running; it only changes the address where it
-@emph{will} run when it is continued.  For example,
+@node Numbers,,,
+@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}.
+Numbers that begin with none of these are, by default, entered in base
+10; likewise, the default display for numbers---when no particular
+format is specified---is base 10.  You can change the default base for
+both input and output with the @samp{set radix} command.
+
+@table @code
+@kindex set radix
+@item set radix @var{base}
+Set the default base for numeric input and display.  Supported choices
+for @var{base} are decimal 8, 10, 16.  @var{base} must itself be
+specified either unambiguously or using the current default radix; for
+example, any of
 
 @example
-set $pc = 0x485
+set radix 012
+set radix 10.
+set radix 0xa
 @end example
 
 @noindent
-causes the next @samp{cont} command or stepping command to execute at
-address 0x485, rather than at the address where the program stopped.
-@xref{Stepping}.
+will set the base to decimal.  On the other hand, @samp{set radix 10}
+will leave the radix unchanged no matter what it was.
 
-The most common occasion to use the @samp{jump} command is to back up,
-perhaps with more breakpoints set, over a portion of a program that has
-already executed.
+@kindex show radix
+@item show radix
+Display the current default base for numeric input and display.
 
-@node Signaling, Returning, Jumping, Altering
-@section Giving the Program a Signal
+@end table
+
+@node Messages/Warnings,,,
+@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 @samp{set verbose} command.
+It will make _GDBN__ tell you when it does a lengthy internal operation, so
+you won't think it has crashed.
+
+Currently, the messages controlled by @samp{set verbose} are those which
+announce that the symbol table for a source file is being read
+(@pxref{Files}, in the description of the command
+@samp{symbol-file}).
+@c The following is the right way to do it, but emacs 18.55 doesn't support
+@c @ref, and neither the emacs lisp manual version of texinfmt or makeinfo
+@c is released.  
+@ignore
+see @samp{symbol-file} in @ref{Files}).
+@end ignore
 
 @table @code
-@item signal @var{signalnum}
-@kindex signal
-Resume execution where the program stopped, but give it immediately the
-signal number @var{signalnum}.
+@kindex set verbose
+@item set verbose on
+Enables _GDBN__'s output of certain informational messages.
 
-Alternatively, if @var{signalnum} is zero, continue execution without
-giving a signal.  This is useful when the program stopped on account of
-a signal and would ordinary see the signal when resumed with the
-@samp{cont} command; @samp{signal 0} causes it to resume without a
-signal.
+@item set verbose off
+Disables _GDBN__'s output of certain informational messages.
+
+@kindex show verbose
+@item show verbose
+Displays whether @samp{set verbose} is on or off.
 @end table
 
-@node Returning, Calling, Signaling, Altering
-@section Returning from a Function
+By default, if _GDBN__ encounters bugs in the symbol table of an object file,
+it prints a single message about each type of problem it finds, then 
+shuts up.  You can suppress these messages, or allow more than one such
+message to be printed if you want to see how frequent the problems are.
+@xref{Files}.
 
 @table @code
-@item return
-@cindex returning from a function
-@kindex return
-You can cancel execution of a function call with the @samp{return}
-command.
+@kindex set complaints
+@item set complaints @var{limit}
+Permits _GDBN__ to output @var{limit} complaints about each type of unusual
+symbols before becoming silent about the problem.  Set @var{limit} to
+zero to suppress all complaints; set it to a large number to prevent
+complaints from being suppressed.
+
+@kindex show complaints
+@item show complaints
+Displays how many symbol complaints _GDBN__ is permitted to produce.
 @end table
 
-This command has the effect of discarding the selected stack
-frame (and all frames within it), so that control moves to the caller of
-that function.  You can think of this as making the discarded frame
-return prematurely.
+By default, _GDBN__ is cautious, and asks what sometimes seem to be a lot of
+stupid questions.  For example, if you try to run a program which is
+already running:
+@example
 
-First select the stack frame that you wish to return from
-(@pxref{Selection}).  Then type the @samp{return} command.  If you wish
-to specify the value to be returned, give that as an argument.
+(_GDBP__) run
+The program being debugged has been started already.
+Start it from the beginning? (y or n) 
+@end example
 
-This pops the selected stack frame (and any other frames inside of it),
-leaving its caller as the innermost remaining frame.  That frame becomes
-selected.  The specified value is stored in the registers used for
-returning values of functions.
+If you're willing to unflinchingly face the consequences of your own
+commands, you can disable this ``feature'':
 
-The @samp{return} command does not resume execution; it leaves the
-program stopped in the state that would exist if the function had just
-returned.  Contrast this with the @samp{finish} command
-(@pxref{Stepping}), which resumes execution until the selected stack
-frame returns @emph{naturally}.
+@table @code
+@kindex set caution
+@cindex flinching
+@cindex stupid questions
+@item set caution off
+Disables cautious questions.
 
-@node     Calling,  , Returning, Altering
-@comment  node-name,  next,  previous,  up
-@section Calling your Program's Functions
+@item set caution on
+Enables cautious questions (the default).
 
-@cindex calling functions
-@kindex call
-@table @code
-@item call @var{expr}
-Evaluate the expression @var{expr} without displaying @code{void}
-returned values.
+@item show caution
+@kindex show caution
+Displays state of cautious questions.
 @end table
 
-You can use this variant of the @samp{print} command if you want to
-execute some piece of your program, but without cluttering the output
-with @code{void} returned values.  The result is printed and saved in
-the value history, if it is not void.
-
 @node Sequences, Emacs, Altering, Top
 @chapter Canned Sequences of Commands
 
@@ -4205,7 +4533,7 @@ All the facilities of Emacs' Shell mode are available for this purpose.
 @item
 _GDBN__ displays source code through Emacs.  Each time _GDBN__ displays a
 stack frame, Emacs automatically finds the source file for that frame
-and puts an arrow (@samp{=>}) at the left margin of the current line.
+and puts an arrow (_0__@samp{=>}_1__) at the left margin of the current line.
 Emacs uses a separate buffer for source display, and splits the window
 to show both your _GDBN__ session and the source.
 
@@ -4330,66 +4658,6 @@ environment.  Users of this environment can use a new command,
 each value is printed in its own window.
 @end ignore
 
-@node Remote, _GDBN__ Bugs, Emacs, Top
-@chapter Remote Debugging
-@cindex remote debugging
-
-If you are trying to debug a program running on a machine that can't run
-_GDBN__ in the usual way, it is often useful to use remote debugging.  For
-example, you might be debugging an operating system kernel, or debugging
-a small system which does not have a general purpose operating system
-powerful enough to run a full-featured debugger.  Currently _GDBN__ supports
-remote debugging over a serial connection, and (using Sun RPC) over a
-TCP/IP connection.
-
-The program to be debugged on the remote machine needs to contain a
-debugging device driver which talks to _GDBN__ over the serial line.  The
-same version of _GDBN__ that is used ordinarily can be used for this.
-Several sample remote debugging drivers are distributed with _GDBN__; see
-the @file{README} file in the _GDBN__ distribution for more information.
-
-@menu
-* Remote Commands::		Commands used to start and finish remote debugging.
-@end menu
-
-For details of the communication protocol, see the comments in the _GDBN__
-source file @file{remote.c}.
-
-@node Remote Commands,  , Remote, Remote
-@section Commands for Remote Debugging
-
-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 find the program's symbols and the contents of its pure text.  Then
-establish communication using the @samp{target remote} command with a device
-name as an argument.  For example:
-
-@example
-target remote /dev/ttyb
-@end example
-
-@noindent
-if the serial line is connected to the device named @file{/dev/ttyb}.  This
-will stop the remote machine if it is not already stopped.
-
-Now you can use all the usual commands to examine and change data and to
-step and continue the remote program.
-
-To resume the remote program and stop debugging it, use the @samp{detach}
-command.
-
-Other remote targets be available in your
-configuration of _GDBN__; use @samp{info targets} to list them.  
-
-@table @code
-@item reset
-@kindex reset
-For a target attached through a serial line, this command sends a
-``break'' to the remote target system; this is only useful if the target
-has been equipped with a circuit to perform a hard reset (or some other
-interesting action) when a break is detected.
-@end table
-
 @node _GDBN__ Bugs, Installing _GDBN__, Remote, Top
 @comment  node-name,  next,  previous,  up
 @chapter Reporting Bugs in _GDBN__
@@ -4445,23 +4713,12 @@ for improvement of _GDBN__ are welcome in any case.
 @cindex Bug Reports
 @cindex Compiler Bugs, Reporting
 
-@comment The following is meant to be neutral and helpful, not just a plug for
-@comment Cygnus; feedback on the issue (to "[e-mail]" or 
-@comment "[e-mail]"---the latter will reach all of Cygnus)
-@comment is welcome.
 A number of companies and individuals offer support for GNU products.
 If you obtained _GDBN__ from a support organization, we recommend you
 contact that organization first. 
 
-Among these organizations are Cygnus Support (Palo Alto CA, USA); C2V
-(Paris, France); Dynamix Corporation (King of Prussia PA, USA); The Nice
-Computer Company (Perth, Australia); Optimal Solutions (Seattle WA,
-USA); and The Pharos Group (Las Cruces NM, USA).
-
-Full contact information is in the file @samp{etc/SERVICE} in the GNU
-Emacs distribution.  Numerous individual consultants are also listed
-there.
-@comment END NEUTRAL+HELPFUL section
+Contact information for many support companies and individuals is
+available in the file @samp{etc/SERVICE} in the GNU Emacs distribution.
 
 In any event, we also recommend that you send bug reports for _GDBN__ to one
 of these addresses:
@@ -4520,8 +4777,8 @@ To enable us to fix the bug, you should include all these things:
 
 @itemize @bullet
 @item
-The version of _GDBN__.  _GDBN__ announces it on startup; you can also print it
-at any time using @samp{info version}.
+The version of _GDBN__.  _GDBN__ announces it if you start with no
+arguments; you can also print it at any time using @samp{show version}.
 
 Without this, we won't know whether there is any point in looking for
 the bug in the current version of _GDBN__.
@@ -4972,15 +5229,25 @@ Ty Coon, President of Vice
 
 That's all there is to it!
 
-@node Commands, Concepts, License, Top
-@unnumbered Command Index
-
-@printindex ky
-
-@node Concepts,  , Commands, Top
+@node Index,,,
 @unnumbered Index
 
 @printindex cp
 
+@tex
+% I think something like @colophon should be in texinfo.  In the
+% meantime:
+\long\def\colophon{\hbox to0pt{}\vfill
+\centerline{The body of this manual is set in}
+\centerline{\fontname\tenrm,}
+\centerline{with headings in {\bf\fontname\tenbf}}
+\centerline{and examples in {\tt\fontname\tentt}.}
+\centerline{{\it\fontname\tenit\/} and}
+\centerline{{\sl\fontname\tensl\/}}
+\centerline{are used for emphasis.}\vfill}
+\page\colophon
+% Blame: [e-mail], 28mar91.
+@end tex
+
 @contents
 @bye