path: root/gdb/doc/gdb.stop-m4

_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}.