@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)
@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
@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
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
_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
@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
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:
_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
@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;
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
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
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
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:
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
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
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. ---pesch@cygnus.com, 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. ---pesch@cygnus.com, 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 /pesch@cygnus.com 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 /pesch@cygnus.com 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
@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.
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__
@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 "pesch@cygnus.com" or
-@comment "info@cygnus.com"---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:
@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__.
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: pesch@cygnus.com, 28mar91.
+@end tex
+
@contents
@bye
projects / binutils-gdb.git / commitdiff