920 lines
37 KiB
Text
Executable file
920 lines
37 KiB
Text
Executable file
_dnl__ -*- Texinfo -*-
|
|
_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
|
|
_dnl__ This file is part of the source for the GDB manual.
|
|
@c M4 FRAGMENT: $Id$
|
|
@node Stopping, Stack, Running, Top
|
|
@chapter Stopping and Continuing
|
|
|
|
When you run a program normally, it runs until it terminates. The
|
|
principal purpose of using a debugger is so that you can stop your
|
|
program before it terminates; or so that, if the program runs into
|
|
trouble, you can investigate and find out why.
|
|
|
|
Inside _GDBN__, your program may stop for any of several reasons, such
|
|
as a signal, a breakpoint, or reaching a new line after a _GDBN__
|
|
command such as @code{step}. Usually, the messages shown by _GDBN__
|
|
provide ample explanation of the status of your program---but you can
|
|
also explicitly request this information at any time.
|
|
|
|
@table @code
|
|
@item info program
|
|
@kindex info program
|
|
Display information about the status of your program: whether it is
|
|
running or not, what process it is, and why it stopped.
|
|
@end table
|
|
|
|
@menu
|
|
* Breakpoints:: Breakpoints, Watchpoints, and Exceptions
|
|
* Stepping:: Stepping
|
|
* Continuing:: Continuing
|
|
* Signals:: Signals
|
|
@end menu
|
|
|
|
@node Breakpoints, Stepping, Stopping, Stopping
|
|
@section Breakpoints, Watchpoints, and Exceptions
|
|
|
|
@cindex breakpoints
|
|
A @dfn{breakpoint} makes your program stop whenever a certain point in
|
|
the program is reached. For each breakpoint, you can add various
|
|
conditions to control in finer detail whether the program will stop.
|
|
You can set breakpoints with the @code{break} command and its variants
|
|
(@pxref{Set Breaks}), to specify the place where the program should stop
|
|
by line number, function name or exact address in the program. In
|
|
languages with exception handling (such as GNU C++), you can also set
|
|
breakpoints where an execption is raised (@pxref{Exception Handling}).
|
|
|
|
@cindex watchpoints
|
|
A @dfn{watchpoint} is a special breakpoint that stops your program when
|
|
the value of an expression changes. You must use a different command to
|
|
set watchpoints (@pxref{Set Watchpoints}), but aside from that, you can
|
|
manage a watchpoint exactly like any other breakpoint: you enable, disable, and
|
|
delete both breakpoints and watchpoints using exactly the same commands.
|
|
|
|
Each breakpoint or watchpoint is assigned a number when it is created;
|
|
these numbers are successive integers starting with one. In many of the
|
|
commands for controlling various features of breakpoints you use the
|
|
breakpoint number to say which breakpoint you want to change. Each
|
|
breakpoint may be @dfn{enabled} or @dfn{disabled}; if disabled, it has
|
|
no effect on the program until you enable it again.
|
|
|
|
@menu
|
|
* Set Breaks:: Setting Breakpoints
|
|
* Set Watchpoints:: Setting Watchpoints
|
|
* Exception Handling:: Breakpoints and Exceptions
|
|
* Delete Breaks:: Deleting Breakpoints
|
|
* Disabling:: Disabling Breakpoints
|
|
* Conditions:: Break Conditions
|
|
* Break Commands:: Breakpoint Command Lists
|
|
* Breakpoint Menus:: Breakpoint Menus
|
|
* Error in Breakpoints::
|
|
@end menu
|
|
|
|
@node Set Breaks, Set Watchpoints, Breakpoints, Breakpoints
|
|
@subsection Setting Breakpoints
|
|
|
|
@kindex break
|
|
@kindex b
|
|
Breakpoints are set with the @code{break} command (abbreviated @code{b}).
|
|
|
|
You have several ways to say where the breakpoint should go.
|
|
|
|
@table @code
|
|
@item break @var{function}
|
|
Set a breakpoint at entry to function @var{function}. When using source
|
|
languages that permit overloading of symbols, such as C++,
|
|
@var{function} may refer to more than one possible place to break.
|
|
@xref{Breakpoint Menus}, for a discussion of that situation.
|
|
|
|
@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.
|
|
|
|
@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.
|
|
|
|
@item break @var{filename}:@var{linenum}
|
|
Set a breakpoint at line @var{linenum} in source file @var{filename}.
|
|
|
|
@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
|
|
When called without any arguments, @code{break} sets 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 similar to the effect of a @code{finish} command in the frame
|
|
inside the selected frame---except that @code{finish} doesn't leave an
|
|
active breakpoint. If you use @code{break} without an argument in the
|
|
innermost frame, _GDBN__ will stop the next time it reaches the current
|
|
location; this may be useful inside loops.
|
|
|
|
_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 @code{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 @code{break} command. They can be deleted,
|
|
disabled, made conditional, etc., in the standard ways.
|
|
|
|
@kindex info breakpoints
|
|
@kindex $_
|
|
@item info breakpoints
|
|
The command @code{info breakpoints} prints a list of all breakpoints
|
|
(but not watchpoints) 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.
|
|
@code{info break} with a breakpoint number as argument lists only that
|
|
breakpoint. The convenience variable @code{$_} and the default
|
|
examining-address for the @code{x} command are set to the address of the
|
|
last breakpoint listed (@pxref{Memory}). The equivalent command for
|
|
watchpoints is @code{info watch}.
|
|
@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 Set Watchpoints, Exception Handling, Set Breaks, Breakpoints
|
|
@subsection Setting Watchpoints
|
|
@cindex setting watchpoints
|
|
You can use a watchpoint to stop execution whenever the value of an
|
|
expression changes, without having to predict a particular place in the
|
|
inferior process where this may happen.
|
|
|
|
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.
|
|
|
|
@table @code
|
|
@kindex watch
|
|
@item watch @var{expr}
|
|
Set a watchpoint for an expression.
|
|
|
|
@kindex info watchpoints
|
|
@item info watchpoints
|
|
This command prints a list of watchpoints; it is otherwise similar to
|
|
@code{info break}.
|
|
@end table
|
|
|
|
@node Exception Handling, Delete Breaks, Set Watchpoints, 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.
|
|
|
|
@table @code
|
|
@item catch @var{exceptions}
|
|
@kindex catch
|
|
|
|
You can set breakpoints at active exception handlers by using the
|
|
@code{catch} command. @var{exceptions} is a list of names of exceptions
|
|
to catch.
|
|
@end table
|
|
|
|
You can use @code{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.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
If you call a function interactively, _GDBN__ normally returns
|
|
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
|
|
|
|
@cindex raise exceptions
|
|
Sometimes @code{catch} is not the best way to debug exception handling:
|
|
if you need to know exactly where an exception is raised, it's better to
|
|
stop @emph{before} the exception handler is called, since that way you
|
|
can see the stack before any unwinding takes place. If you set a
|
|
breakpoint in an exception handler instead, it may not be easy to find
|
|
out where the exception was raised.
|
|
|
|
To stop just before an exception handler is called, you need some
|
|
knowledge of the implementation. In the case of GNU C++ exception are
|
|
raised by calling a library function named @code{__raise_exception}
|
|
which has the following ANSI C interface:
|
|
|
|
@example
|
|
/* ADDR is where the exception identifier is stored.
|
|
ID is the exception identifier. */
|
|
void __raise_exception (void **@var{addr}, void *@var{id});
|
|
@end example
|
|
|
|
@noindent
|
|
To make the debugger catch all exceptions before any stack
|
|
unwinding takes place, set a breakpoint on @code{__raise_exception}
|
|
(@pxref{Breakpoints}).
|
|
|
|
With a conditional breakpoint (@xref{Conditions}) that depends on the
|
|
value of @var{id}, you can stop your program when a specific exception
|
|
is raised. You can use multiple conditional breakpoints to stop the
|
|
program when any of a number of exceptions are raised.
|
|
|
|
@node Delete Breaks, Disabling, Exception Handling, Breakpoints
|
|
@subsection Deleting Breakpoints
|
|
|
|
@cindex clearing breakpoints, watchpoints
|
|
@cindex deleting breakpoints, watchpoints
|
|
It is often necessary to eliminate a breakpoint or watchpoint 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.
|
|
|
|
With the @code{clear} command you can delete breakpoints according to
|
|
where they are in the program. With the @code{delete} command you can
|
|
delete individual breakpoints or watchpoints by specifying their
|
|
breakpoint numbers.
|
|
|
|
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.
|
|
|
|
@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
|
|
@cindex delete breakpoints
|
|
@kindex delete
|
|
@kindex d
|
|
Delete the breakpoints or watchpoints of the numbers specified as
|
|
arguments. If no argument is specified, delete all breakpoints. You
|
|
can abbreviate this command as @code{d}.
|
|
@end table
|
|
|
|
@node Disabling, Conditions, Delete Breaks, Breakpoints
|
|
@subsection Disabling Breakpoints
|
|
|
|
@cindex disabled breakpoints
|
|
@cindex enabled breakpoints
|
|
Rather than deleting a breakpoint or watchpoint, 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.
|
|
|
|
You disable and enable breakpoints and watchpoints with the
|
|
@code{enable} and @code{disable} commands, optionally specifying one or
|
|
more breakpoint numbers as arguments. Use @code{info break} or
|
|
@code{info watch} to print a list of breakpoints or watchpoints if you
|
|
don't know which numbers to use.
|
|
|
|
A breakpoint or watchpoint can have any of four different states of
|
|
enablement:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Enabled. The breakpoint will stop the program. A breakpoint made
|
|
with the @code{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 @code{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
|
|
|
|
You can use the following commands to enable or disable breakpoints and
|
|
watchpoints:
|
|
|
|
@table @code
|
|
@item disable breakpoints @var{bnums}@dots{}
|
|
@itemx disable @var{bnums}@dots{}
|
|
@itemx disable
|
|
@kindex disable breakpoints
|
|
@kindex disable
|
|
@kindex dis
|
|
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. You may abbreviate
|
|
@code{disable} as @code{dis}.
|
|
|
|
@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
|
|
|
|
Save for a breakpoint set with @code{tbreak} (@pxref{Set Breaks}),
|
|
breakpoints that you set initially enabled; subsequently, they become
|
|
disabled or enabled only when you use one of the commands above. (The
|
|
command @code{until} can set and delete a breakpoint of its own, but it
|
|
will not change the state of your other breakpoints;
|
|
@pxref{Stepping}.)
|
|
|
|
@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.
|
|
|
|
Conditions are also accepted for watchpoints; you may not need them,
|
|
since a watchpoint is inspecting the value of an expression anyhow---but
|
|
it might be simpler, say, to just set a watchpoint on a variable name,
|
|
then have a condition that tests whether the new value is an interesting
|
|
one.
|
|
|
|
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}).
|
|
|
|
Break conditions can be specified when a breakpoint is set, by using
|
|
@samp{if} in the arguments to the @code{break} command. @xref{Set Breaks}.
|
|
They can also be changed at any time with the @code{condition} command.
|
|
The @code{watch} command doesn't recognize the @code{if} keyword;
|
|
@code{condition} is the only way to impose a further condition on a
|
|
watchpoint.
|
|
|
|
@table @code
|
|
@item condition @var{bnum} @var{expression}
|
|
@kindex condition
|
|
Specify @var{expression} as the break condition for breakpoint or
|
|
watchpoint number @var{bnum}. From now on, this breakpoint will stop
|
|
the program only if the value of @var{expression} is true (nonzero, in
|
|
C). When you call @code{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. _GDBN__
|
|
does not actually evaluate @var{expression} at the time the
|
|
@code{condition} command is given, however. @xref{Expressions}.
|
|
|
|
@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.
|
|
|
|
@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.
|
|
|
|
To make the breakpoint stop the next time it is reached, specify
|
|
a count of zero.
|
|
|
|
@item continue @var{count}
|
|
@itemx c @var{count}
|
|
@itemx fg @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.
|
|
|
|
An argument to this command is meaningful only when the program stopped
|
|
due to a breakpoint. At other times, the argument to @code{continue} is
|
|
ignored.
|
|
|
|
The synonym @code{fg} is provided purely for convenience, and has
|
|
exactly the same behavior as other forms of the command.
|
|
@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.
|
|
|
|
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, Breakpoint Menus, Conditions, Breakpoints
|
|
@subsection Breakpoint Command Lists
|
|
|
|
@cindex breakpoint commands
|
|
You can give any breakpoint (or watchpoint) 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}
|
|
@itemx @dots{} @var{command-list} @dots{}
|
|
@itemx end
|
|
@kindex commands
|
|
@kindex end
|
|
Specify a list of commands for breakpoint number @var{bnum}. The commands
|
|
themselves appear on the following lines. Type a line containing just
|
|
@code{end} to terminate the commands.
|
|
|
|
To remove all commands from a breakpoint, use the command
|
|
@code{commands} and follow it immediately by @code{end}; that is, give
|
|
no commands.
|
|
|
|
With no @var{bnum} argument, @code{commands} refers to the last
|
|
breakpoint or watchpoint set (not to the breakpoint most recently
|
|
encountered).
|
|
@end table
|
|
|
|
Pressing @key{RET} as a means of repeating the last _GDBN__ command is
|
|
disabled from the time you enter @code{commands} to just after the
|
|
corresponding @code{end}.
|
|
|
|
You can use breakpoint commands to start the program up again. Simply
|
|
use the @code{continue} command, or @code{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 @code{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. @code{silent} is not really a command;
|
|
it is meaningful only at the beginning of the commands for a breakpoint.
|
|
|
|
The commands @code{echo} and @code{output} that allow you to print precisely
|
|
controlled output are often useful in silent breakpoints. @xref{Output}.
|
|
|
|
For example, here is how you could use breakpoint commands to print the
|
|
value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
|
|
|
|
_0__@example
|
|
break foo if x>0
|
|
commands
|
|
silent
|
|
echo x is\040
|
|
output x
|
|
echo \n
|
|
cont
|
|
end
|
|
_1__@end example
|
|
|
|
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 @code{continue} command so that the program does not
|
|
stop, and start with the @code{silent} command so that no output is
|
|
produced. Here is an example:
|
|
|
|
@example
|
|
break 403
|
|
commands
|
|
silent
|
|
set x = y + 4
|
|
cont
|
|
end
|
|
@end example
|
|
|
|
@cindex lost output
|
|
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.
|
|
|
|
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
|
|
|
|
@example
|
|
condition 5 (x = y + 4), 0
|
|
@end example
|
|
|
|
@noindent
|
|
specifies a condition expression (@xref{Expressions}) that will change
|
|
@code{x} as needed, then always have the value zero 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 Breakpoint Menus, Error in Breakpoints, Break Commands, Breakpoints
|
|
@subsection Breakpoint Menus
|
|
@cindex C++ overloading
|
|
@cindex symbol overloading
|
|
|
|
Some programming languages (notably C++) permit a single function name
|
|
to be defined several times, for application in different contexts.
|
|
This is called @dfn{overloading}. When a function name is overloaded,
|
|
@samp{break @var{function}} is not enough to tell _GDBN__ where you want
|
|
a breakpoint. _GDBN__ responds to this situation by offering you a menu
|
|
of numbered choices for different possible breakpoints, and waiting for
|
|
your selection with the prompt @samp{>}. The first two
|
|
options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1}
|
|
will set a breakpoint at all the definitions available for
|
|
@var{function}, and typing @kbd{0} will abort the @code{break} command
|
|
without setting any new breakpoints.
|
|
|
|
For example, the following session excerpt shows an attempt to set a
|
|
breakpoint at the overloaded symbol @code{String::after}. In the
|
|
example, we choose three particular definitions of the function:
|
|
|
|
@example
|
|
(_GDBP__) b String::after
|
|
[0] cancel
|
|
[1] all
|
|
[2] file:String.cc; line number:867
|
|
[3] file:String.cc; line number:860
|
|
[4] file:String.cc; line number:875
|
|
[5] file:String.cc; line number:853
|
|
[6] file:String.cc; line number:846
|
|
[7] file:String.cc; line number:735
|
|
> 2 4 6
|
|
Breakpoint 1 at 0xb26c: file String.cc, line 867.
|
|
Breakpoint 2 at 0xb344: file String.cc, line 875.
|
|
Breakpoint 3 at 0xafcc: file String.cc, line 846.
|
|
Multiple breakpoints were set.
|
|
Use the "delete" command to delete unwanted breakpoints.
|
|
(_GDBP__)
|
|
@end example
|
|
|
|
|
|
@node Error in Breakpoints, , Breakpoint Menus, 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.
|
|
|
|
When this happens, you have three ways to proceed:
|
|
|
|
@enumerate
|
|
@item
|
|
Remove or disable the breakpoints, then continue.
|
|
|
|
@item
|
|
Suspend _GDBN__, and copy the file containing the program to a new name.
|
|
Resume _GDBN__ and use the @code{exec-file} command to specify that _GDBN__
|
|
should run the program under that name. Then start the program again.
|
|
|
|
@c FIXME: RMS commented here "Show example". Maybe when someone
|
|
@c explains the first FIXME: in this section...
|
|
|
|
@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
|
|
|
|
@node Stepping, Continuing, Breakpoints, Stopping
|
|
@section Stepping
|
|
|
|
@cindex stepping
|
|
@dfn{Stepping} means setting your program in motion for a limited time,
|
|
so that control will return automatically to _GDBN__ after one line of
|
|
code or one machine instruction. @footnote{Your program might stop even
|
|
sooner, during stepping, since a signal may arrive before your program
|
|
reaches the next source line. Also, since breakpoints are active during
|
|
stepping, your program will stop for them even if it has not gone as far
|
|
as the stepping command specifies.}
|
|
|
|
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, run the program until
|
|
it stops at that breakpoint, and then step through the suspect area,
|
|
examining the variables that are interesting, until you see the problem
|
|
happen.
|
|
|
|
@table @code
|
|
@item step
|
|
@kindex step
|
|
@kindex s
|
|
Continue running the program until control reaches a different source
|
|
line, then stop it and return control to the debugger. This command is
|
|
abbreviated @code{s}.
|
|
|
|
You may use the @code{step} command 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.
|
|
|
|
@item step @var{count}
|
|
Continue running as in @code{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.
|
|
|
|
@item next
|
|
@kindex next
|
|
@kindex n
|
|
Continue to the next source line in the current stack frame. Similar to
|
|
@code{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
|
|
@code{next} command was given. This command is abbreviated @code{n}.
|
|
|
|
An argument is a repeat count, as in @code{step}.
|
|
|
|
@code{next} within a function that lacks debugging information acts like
|
|
@code{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 the value returned by the selected stack frame (if
|
|
any).
|
|
|
|
Contrast this with the @code{return} command (@pxref{Returning}).
|
|
|
|
@item until
|
|
@kindex until
|
|
@item u
|
|
@kindex u
|
|
Continue running until a source line past the current line, in the
|
|
current stack frame, is reached. This command is used to avoid single
|
|
stepping through a loop more than once. It is like the @code{next}
|
|
command, except that when @code{until} encounters a jump, it
|
|
automatically continues execution until the program counter is greater
|
|
than the address of the jump.
|
|
|
|
This means that when you reach the end of a loop after single stepping
|
|
though it, @code{until} will cause the program to continue execution
|
|
until the loop is exited. In contrast, a @code{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.
|
|
|
|
@code{until} always stops the program if it attempts to exit the current
|
|
stack frame.
|
|
|
|
@code{until} may produce somewhat counterintuitive results if the order
|
|
of the source lines does not match the actual order of execution. For
|
|
example, in the following excerpt from a debugging session, the @code{f}
|
|
(@code{frame}) command shows that execution is stopped at line
|
|
@code{206}; yet when we use @code{until}, we get to line @code{195}:
|
|
|
|
@example
|
|
(_GDBP__) f
|
|
#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
|
|
206 expand_input();
|
|
(_GDBP__) until
|
|
195 for ( ; argc > 0; NEXTARG) @{
|
|
@end example
|
|
|
|
In this case, (as for any C @code{for}-loop), the loop-step expression
|
|
(here, @samp{argc > 0}) is executed @emph{after} the statements in the
|
|
body of the loop, but is written before them. Therefore, the
|
|
@code{until} command appeared to step back to the beginning of the loop
|
|
when it advanced to this expression. However, it has not really gone to
|
|
an earlier statement---not in terms of the actual machine code.
|
|
|
|
@code{until} with no argument works by means of single
|
|
instruction stepping, and hence is slower than @code{until} with an
|
|
argument.
|
|
|
|
@item until @var{location}
|
|
@item u @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 @code{break} (@pxref{Set
|
|
Breaks}). This form of the command uses breakpoints, and hence is
|
|
quicker than @code{until} without an argument.
|
|
|
|
@item stepi
|
|
@itemx si
|
|
@kindex stepi
|
|
@kindex si
|
|
Execute one machine instruction, then stop and return to the debugger.
|
|
|
|
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}.
|
|
|
|
An argument is a repeat count, as in @code{step}.
|
|
|
|
@item nexti
|
|
@itemx ni
|
|
@kindex nexti
|
|
@kindex ni
|
|
Execute one machine instruction, but if it is a function call,
|
|
proceed until the function returns.
|
|
|
|
An argument is a repeat count, as in @code{next}.
|
|
@end table
|
|
|
|
The @code{continue} command can be used after stepping to resume execution
|
|
until the next breakpoint or signal.
|
|
|
|
@node Continuing, Signals, Stepping, Stopping
|
|
@section Continuing
|
|
|
|
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.
|
|
|
|
@table @code
|
|
@item continue
|
|
@kindex continue
|
|
Continue running the program at the place where it stopped.
|
|
@end table
|
|
|
|
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, @code{continue}
|
|
takes special care to prevent that from happening. You do not need
|
|
to disable the breakpoint to proceed through it after stopping there.
|
|
You can, however, specify an ignore-count for the breakpoint that the
|
|
program stopped at, by means of an argument to the @code{continue} command.
|
|
@xref{Conditions}.
|
|
|
|
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 @code{handle} command (@pxref{Signals}).
|
|
|
|
@node Signals, , Continuing, Stopping
|
|
@section Signals
|
|
@cindex signals
|
|
|
|
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, in Unix @code{SIGINT} is the
|
|
signal a program gets when you type an interrupt (often @kbd{C-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).
|
|
|
|
@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 the interrupt: to kill the program.
|
|
|
|
_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.
|
|
|
|
@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 @code{handle} command.
|
|
|
|
@table @code
|
|
@item info signals
|
|
@kindex info signals
|
|
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
|
|
|
|
@c @group
|
|
The keywords allowed by the @code{handle} command can be abbreviated.
|
|
Their full names are:
|
|
|
|
@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.
|
|
|
|
@item stop
|
|
_GDBN__ should stop the program when this signal happens. This implies
|
|
the @code{print} keyword as well.
|
|
|
|
@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 @code{nostop} keyword as well.
|
|
|
|
@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.
|
|
|
|
@item nopass
|
|
_GDBN__ should not allow the program to see this signal.
|
|
@end table
|
|
@c @end group
|
|
|
|
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 @code{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 @code{handle} command with
|
|
@code{pass} or @code{nopass} to control whether that signal will be seen by
|
|
the program when you later continue it.
|
|
|
|
You can also use the @code{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}.
|
|
|