<HTML>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Created on March, 27 2008 by texi2html 1.64 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
-->
<HEAD>
<TITLE>Debugging with GDB: Stopping</TITLE>
<META NAME="description" CONTENT="Debugging with GDB: Stopping">
<META NAME="keywords" CONTENT="Debugging with GDB: Stopping">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="texi2html 1.64">
</HEAD>
<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<A NAME="SEC31"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC30"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC32"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_7.html#SEC46"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_7.html#SEC46"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1> 5. Stopping and Continuing </H1>
<!--docid::SEC31::-->
<P>
The principal purposes of using a debugger are so that you can stop your
program before it terminates; or so that, if your program runs into
trouble, you can investigate and find out why.
</P><P>
Inside GDB, your program may stop for any of several reasons,
such as a signal, a breakpoint, or reaching a new line after a
GDB command such as <CODE>step</CODE>. You may then examine and
change variables, set new breakpoints or remove old ones, and then
continue execution. Usually, the messages shown by GDB provide
ample explanation of the status of your program--but you can also
explicitly request this information at any time.
</P><P>
<DL COMPACT>
<A NAME="IDX171"></A>
<DT><CODE>info program</CODE>
<DD>Display information about the status of your program: whether it is
running or not, what process it is, and why it stopped.
</DL>
<P>
<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_6.html#SEC32">5.1 Breakpoints, Watchpoints, and Catchpoints</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Breakpoints, watchpoints, and catchpoints</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_6.html#SEC43">5.2 Continuing and Stepping</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Resuming execution</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_6.html#SEC44">5.3 Signals</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_6.html#SEC45">5.4 Stopping and Starting Multi-thread Programs</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Stopping and starting multi-thread programs</TD></TR>
</TABLE></BLOCKQUOTE>
<P>
<A NAME="Breakpoints"></A>
<HR SIZE="6">
<A NAME="SEC32"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC33"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC43"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 5.1 Breakpoints, Watchpoints, and Catchpoints </H2>
<!--docid::SEC32::-->
<P>
<A NAME="IDX172"></A>
A <EM>breakpoint</EM> makes your program stop whenever a certain point in
the program is reached. For each breakpoint, you can add conditions to
control in finer detail whether your program stops. You can set
breakpoints with the <CODE>break</CODE> command and its variants (see section <A HREF="gdb_6.html#SEC33">Setting Breakpoints</A>), to specify the place where your program
should stop by line number, function name or exact address in the
program.
</P><P>
On some systems, you can set breakpoints in shared libraries before
the executable is run. There is a minor limitation on HP-UX systems:
you must wait until the executable is run in order to set breakpoints
in shared library routines that are not called directly by the program
(for example, routines that are arguments in a <CODE>pthread_create</CODE>
call).
</P><P>
<A NAME="IDX173"></A>
<A NAME="IDX174"></A>
<A NAME="IDX175"></A>
<A NAME="IDX176"></A>
<A NAME="IDX177"></A>
A <EM>watchpoint</EM> is a special breakpoint that stops your program
when the value of an expression changes. The expression may be a value
of a variable, or it could involve values of one or more variables
combined by operators, such as <SAMP>`a + b'</SAMP>. This is sometimes called
<EM>data breakpoints</EM>. You must use a different command to set
watchpoints (see section <A HREF="gdb_6.html#SEC34">Setting Watchpoints</A>), but aside
from that, you can manage a watchpoint like any other breakpoint: you
enable, disable, and delete both breakpoints and watchpoints using the
same commands.
</P><P>
You can arrange to have values from your program displayed automatically
whenever GDB stops at a breakpoint. See section <A HREF="gdb_9.html#SEC65">Automatic Display</A>.
</P><P>
<A NAME="IDX178"></A>
<A NAME="IDX179"></A>
A <EM>catchpoint</EM> is another special breakpoint that stops your program
when a certain kind of event occurs, such as the throwing of a C<TT>++</TT>
exception or the loading of a library. As with watchpoints, you use a
different command to set a catchpoint (see section <A HREF="gdb_6.html#SEC35">Setting Catchpoints</A>), but aside from that, you can manage a catchpoint like any
other breakpoint. (To stop when your program receives a signal, use the
<CODE>handle</CODE> command; see <A HREF="gdb_6.html#SEC44">Signals</A>.)
</P><P>
<A NAME="IDX180"></A>
<A NAME="IDX181"></A>
GDB assigns a number to each breakpoint, watchpoint, or
catchpoint when you create it; these numbers are successive integers
starting with one. In many of the commands for controlling various
features of breakpoints you use the breakpoint number to say which
breakpoint you want to change. Each breakpoint may be <EM>enabled</EM> or
<EM>disabled</EM>; if disabled, it has no effect on your program until you
enable it again.
</P><P>
<A NAME="IDX182"></A>
<A NAME="IDX183"></A>
Some GDB commands accept a range of breakpoints on which to
operate. A breakpoint range is either a single breakpoint number, like
<SAMP>`5'</SAMP>, or two such numbers, in increasing order, separated by a
hyphen, like <SAMP>`5-7'</SAMP>. When a breakpoint range is given to a command,
all breakpoints in that range are operated on.
</P><P>
<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_6.html#SEC33">5.1.1 Setting Breakpoints</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Setting breakpoints</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_6.html#SEC34">5.1.2 Setting Watchpoints</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Setting watchpoints</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_6.html#SEC35">5.1.3 Setting Catchpoints</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Setting catchpoints</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_6.html#SEC36">5.1.4 Deleting Breakpoints</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Deleting breakpoints</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_6.html#SEC37">5.1.5 Disabling Breakpoints</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Disabling breakpoints</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_6.html#SEC38">5.1.6 Break Conditions</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Break conditions</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_6.html#SEC39">5.1.7 Breakpoint Command Lists</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Breakpoint command lists</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_6.html#SEC40">5.1.8 Breakpoint Menus</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Breakpoint menus</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_6.html#SEC41">5.1.9 "Cannot insert breakpoints"</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_6.html#SEC42">5.1.10 "Breakpoint address adjusted..."</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
</TABLE></BLOCKQUOTE>
<P>
<A NAME="Set Breaks"></A>
<HR SIZE="6">
<A NAME="SEC33"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC32"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC34"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC32"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC43"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 5.1.1 Setting Breakpoints </H3>
<!--docid::SEC33::-->
<P>
<A NAME="IDX184"></A>
<A NAME="IDX185"></A>
<A NAME="IDX186"></A>
<A NAME="IDX187"></A>
Breakpoints are set with the <CODE>break</CODE> command (abbreviated
<CODE>b</CODE>). The debugger convenience variable <SAMP>`$bpnum'</SAMP> records the
number of the breakpoint you've set most recently; see <A HREF="gdb_9.html#SEC68">Convenience Variables</A>, for a discussion of what you can do with
convenience variables.
</P><P>
<DL COMPACT>
<DT><CODE>break <VAR>location</VAR></CODE>
<DD>Set a breakpoint at the given <VAR>location</VAR>, which can specify a
function name, a line number, or an address of an instruction.
(See section <A HREF="gdb_8.html#SEC53">7.2 Specifying a Location</A>, for a list of all the possible ways to
specify a <VAR>location</VAR>.) The breakpoint will stop your program just
before it executes any of the code in the specified <VAR>location</VAR>.
<P>
When using source languages that permit overloading of symbols, such as
C<TT>++</TT>, a function name may refer to more than one possible place to break.
See section <A HREF="gdb_6.html#SEC40">Breakpoint Menus</A>, for a discussion of that situation.
</P><P>
<DT><CODE>break</CODE>
<DD>When called without any arguments, <CODE>break</CODE> sets a breakpoint at
the next instruction to be executed in the selected stack frame
(see section <A HREF="gdb_7.html#SEC46">Examining the Stack</A>). In any selected frame but the
innermost, this makes your program stop as soon as control
returns to that frame. This is similar to the effect of a
<CODE>finish</CODE> command in the frame inside the selected frame--except
that <CODE>finish</CODE> does not leave an active breakpoint. If you use
<CODE>break</CODE> without an argument in the innermost frame, GDB stops
the next time it reaches the current location; this may be useful
inside loops.
<P>
GDB 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 your program stopped.
</P><P>
<DT><CODE>break <small>...</small> if <VAR>cond</VAR></CODE>
<DD>Set a breakpoint with condition <VAR>cond</VAR>; evaluate the expression
<VAR>cond</VAR> each time the breakpoint is reached, and stop only if the
value is nonzero--that is, if <VAR>cond</VAR> evaluates as true.
<SAMP>`<small>...</small>'</SAMP> stands for one of the possible arguments described
above (or no argument) specifying where to break. See section <A HREF="gdb_6.html#SEC38">Break Conditions</A>, for more information on breakpoint conditions.
<P>
<A NAME="IDX188"></A>
<DT><CODE>tbreak <VAR>args</VAR></CODE>
<DD>Set a breakpoint enabled only for one stop. <VAR>args</VAR> are the
same as for the <CODE>break</CODE> command, and the breakpoint is set in the same
way, but the breakpoint is automatically deleted after the first time your
program stops there. See section <A HREF="gdb_6.html#SEC37">Disabling Breakpoints</A>.
<P>
<A NAME="IDX189"></A>
<A NAME="IDX190"></A>
<DT><CODE>hbreak <VAR>args</VAR></CODE>
<DD>Set a hardware-assisted breakpoint. <VAR>args</VAR> are the same as for the
<CODE>break</CODE> command and the breakpoint is set in the same way, but the
breakpoint requires hardware support and some target hardware may not
have this support. The main purpose of this is EPROM/ROM code
debugging, so you can set a breakpoint at an instruction without
changing the instruction. This can be used with the new trap-generation
provided by SPARClite DSU and most x86-based targets. These targets
will generate traps when a program accesses some data or instruction
address that is assigned to the debug registers. However the hardware
breakpoint registers can take a limited number of breakpoints. For
example, on the DSU, only two data breakpoints can be set at a time, and
GDB will reject this command if more than two are used. Delete
or disable unused hardware breakpoints before setting new ones
(see section <A HREF="gdb_6.html#SEC37">Disabling Breakpoints</A>).
See section <A HREF="gdb_6.html#SEC38">Break Conditions</A>.
For remote targets, you can restrict the number of hardware
breakpoints GDB will use, see <A HREF="gdb_18.html#set remote hardware-breakpoint-limit">set remote hardware-breakpoint-limit</A>.
<P>
<A NAME="IDX191"></A>
<DT><CODE>thbreak <VAR>args</VAR></CODE>
<DD>Set a hardware-assisted breakpoint enabled only for one stop. <VAR>args</VAR>
are the same as for the <CODE>hbreak</CODE> command and the breakpoint is set in
the same way. However, like the <CODE>tbreak</CODE> command,
the breakpoint is automatically deleted after the
first time your program stops there. Also, like the <CODE>hbreak</CODE>
command, the breakpoint requires hardware support and some target hardware
may not have this support. See section <A HREF="gdb_6.html#SEC37">Disabling Breakpoints</A>.
See also <A HREF="gdb_6.html#SEC38">Break Conditions</A>.
<P>
<A NAME="IDX192"></A>
<A NAME="IDX193"></A>
<A NAME="IDX194"></A>
<A NAME="IDX195"></A>
<DT><CODE>rbreak <VAR>regex</VAR></CODE>
<DD>Set breakpoints on all functions matching the regular expression
<VAR>regex</VAR>. 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</CODE> command. You can delete them, disable them, or make
them conditional the same way as any other breakpoint.
<P>
The syntax of the regular expression is the standard one used with tools
like <TT>`grep'</TT>. Note that this is different from the syntax used by
shells, so for instance <CODE>foo*</CODE> matches all functions that include
an <CODE>fo</CODE> followed by zero or more <CODE>o</CODE>s. There is an implicit
<CODE>.*</CODE> leading and trailing the regular expression you supply, so to
match only functions that begin with <CODE>foo</CODE>, use <CODE>^foo</CODE>.
</P><P>
<A NAME="IDX196"></A>
When debugging C<TT>++</TT> programs, <CODE>rbreak</CODE> is useful for setting
breakpoints on overloaded functions that are not members of any special
classes.
</P><P>
<A NAME="IDX197"></A>
The <CODE>rbreak</CODE> command can be used to set breakpoints in
<STRONG>all</STRONG> the functions in a program, like this:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) rbreak .
</FONT></pre></td></tr></table></P><P>
<A NAME="IDX198"></A>
<A NAME="IDX199"></A>
<DT><CODE>info breakpoints [<VAR>n</VAR>]</CODE>
<DD><DT><CODE>info break [<VAR>n</VAR>]</CODE>
<DD><DT><CODE>info watchpoints [<VAR>n</VAR>]</CODE>
<DD>Print a table of all breakpoints, watchpoints, and catchpoints set and
not deleted. Optional argument <VAR>n</VAR> means print information only
about the specified breakpoint (or watchpoint or catchpoint). For
each breakpoint, following columns are printed:
<P>
<DL COMPACT>
<DT><EM>Breakpoint Numbers</EM>
<DD><DT><EM>Type</EM>
<DD>Breakpoint, watchpoint, or catchpoint.
<DT><EM>Disposition</EM>
<DD>Whether the breakpoint is marked to be disabled or deleted when hit.
<DT><EM>Enabled or Disabled</EM>
<DD>Enabled breakpoints are marked with <SAMP>`y'</SAMP>. <SAMP>`n'</SAMP> marks breakpoints
that are not enabled.
<DT><EM>Address</EM>
<DD>Where the breakpoint is in your program, as a memory address. For a
pending breakpoint whose address is not yet known, this field will
contain <SAMP>`<PENDING>'</SAMP>. Such breakpoint won't fire until a shared
library that has the symbol or line referred by breakpoint is loaded.
See below for details. A breakpoint with several locations will
have <SAMP>`<MULTIPLE>'</SAMP> in this field--see below for details.
<DT><EM>What</EM>
<DD>Where the breakpoint is in the source for your program, as a file and
line number. For a pending breakpoint, the original string passed to
the breakpoint command will be listed as it cannot be resolved until
the appropriate shared library is loaded in the future.
</DL>
<P>
If a breakpoint is conditional, <CODE>info break</CODE> shows the condition on
the line following the affected breakpoint; breakpoint commands, if any,
are listed after that. A pending breakpoint is allowed to have a condition
specified for it. The condition is not parsed for validity until a shared
library is loaded that allows the pending breakpoint to resolve to a
valid location.
</P><P>
<CODE>info break</CODE> with a breakpoint
number <VAR>n</VAR> as argument lists only that breakpoint. The
convenience variable <CODE>$_</CODE> and the default examining-address for
the <CODE>x</CODE> command are set to the address of the last breakpoint
listed (see section <A HREF="gdb_9.html#SEC64">Examining Memory</A>).
</P><P>
<CODE>info break</CODE> displays a count of the number of times the breakpoint
has been hit. This is especially useful in conjunction with the
<CODE>ignore</CODE> command. You can ignore a large number of breakpoint
hits, look at the breakpoint info to see how many times the breakpoint
was hit, and then run again, ignoring one less than that number. This
will get you quickly to the last hit of that breakpoint.
</DL>
<P>
GDB allows you to set any number of breakpoints at the same place in
your program. There is nothing silly or meaningless about this. When
the breakpoints are conditional, this is even useful
(see section <A HREF="gdb_6.html#SEC38">Break Conditions</A>).
</P><P>
It is possible that a breakpoint corresponds to several locations
in your program. Examples of this situation are:
</P><P>
<UL>
<LI>
For a C<TT>++</TT> constructor, the GCC compiler generates several
instances of the function body, used in different cases.
<P>
<LI>
For a C<TT>++</TT> template function, a given line in the function can
correspond to any number of instantiations.
<P>
<LI>
For an inlined function, a given source line can correspond to
several places where that function is inlined.
<P>
</UL>
<P>
In all those cases, GDB will insert a breakpoint at all
the relevant locations.
</P><P>
A breakpoint with multiple locations is displayed in the breakpoint
table using several rows--one header row, followed by one row for
each breakpoint location. The header row has <SAMP>`<MULTIPLE>'</SAMP> in the
address column. The rows for individual locations contain the actual
addresses for locations, and show the functions to which those
locations belong. The number column for a location is of the form
<VAR>breakpoint-number</VAR>.<VAR>location-number</VAR>.
</P><P>
For example:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>Num Type Disp Enb Address What
1 breakpoint keep y <MULTIPLE>
stop only if i==1
breakpoint already hit 1 time
1.1 y 0x080486a2 in void foo<int>() at t.cc:8
1.2 y 0x080486ca in void foo<double>() at t.cc:8
</FONT></pre></td></tr></table></P><P>
Each location can be individually enabled or disabled by passing
<VAR>breakpoint-number</VAR>.<VAR>location-number</VAR> as argument to the
<CODE>enable</CODE> and <CODE>disable</CODE> commands. Note that you cannot
delete the individual locations from the list, you can only delete the
entire list of locations that belong to their parent breakpoint (with
the <KBD>delete <VAR>num</VAR></KBD> command, where <VAR>num</VAR> is the number of
the parent breakpoint, 1 in the above example). Disabling or enabling
the parent breakpoint (see section <A HREF="gdb_6.html#SEC37">5.1.5 Disabling Breakpoints</A>) affects all of the locations
that belong to that breakpoint.
</P><P>
<A NAME="IDX200"></A>
It's quite common to have a breakpoint inside a shared library.
Shared libraries can be loaded and unloaded explicitly,
and possibly repeatedly, as the program is executed. To support
this use case, GDB updates breakpoint locations whenever
any shared library is loaded or unloaded. Typically, you would
set a breakpoint in a shared library at the beginning of your
debugging session, when the library is not loaded, and when the
symbols from the library are not available. When you try to set
breakpoint, GDB will ask you if you want to set
a so called <EM>pending breakpoint</EM>---breakpoint whose address
is not yet resolved.
</P><P>
After the program is run, whenever a new shared library is loaded,
GDB reevaluates all the breakpoints. When a newly loaded
shared library contains the symbol or line referred to by some
pending breakpoint, that breakpoint is resolved and becomes an
ordinary breakpoint. When a library is unloaded, all breakpoints
that refer to its symbols or source lines become pending again.
</P><P>
This logic works for breakpoints with multiple locations, too. For
example, if you have a breakpoint in a C<TT>++</TT> template function, and
a newly loaded shared library has an instantiation of that template,
a new location is added to the list of locations for the breakpoint.
</P><P>
Except for having unresolved address, pending breakpoints do not
differ from regular breakpoints. You can set conditions or commands,
enable and disable them and perform other breakpoint operations.
</P><P>
GDB provides some additional commands for controlling what
happens when the <SAMP>`break'</SAMP> command cannot resolve breakpoint
address specification to an address:
</P><P>
<A NAME="IDX201"></A>
<A NAME="IDX202"></A>
<DL COMPACT>
<DT><CODE>set breakpoint pending auto</CODE>
<DD>This is the default behavior. When GDB cannot find the breakpoint
location, it queries you whether a pending breakpoint should be created.
<P>
<DT><CODE>set breakpoint pending on</CODE>
<DD>This indicates that an unrecognized breakpoint location should automatically
result in a pending breakpoint being created.
<P>
<DT><CODE>set breakpoint pending off</CODE>
<DD>This indicates that pending breakpoints are not to be created. Any
unrecognized breakpoint location results in an error. This setting does
not affect any pending breakpoints previously created.
<P>
<DT><CODE>show breakpoint pending</CODE>
<DD>Show the current behavior setting for creating pending breakpoints.
</DL>
<P>
The settings above only affect the <CODE>break</CODE> command and its
variants. Once breakpoint is set, it will be automatically updated
as shared libraries are loaded and unloaded.
</P><P>
<A NAME="IDX203"></A>
For some targets, GDB can automatically decide if hardware or
software breakpoints should be used, depending on whether the
breakpoint address is read-only or read-write. This applies to
breakpoints set with the <CODE>break</CODE> command as well as to internal
breakpoints set by commands like <CODE>next</CODE> and <CODE>finish</CODE>. For
breakpoints set with <CODE>hbreak</CODE>, GDB will always use hardware
breakpoints.
</P><P>
You can control this automatic behaviour with the following commands::
</P><P>
<A NAME="IDX204"></A>
<A NAME="IDX205"></A>
<DL COMPACT>
<DT><CODE>set breakpoint auto-hw on</CODE>
<DD>This is the default behavior. When GDB sets a breakpoint, it
will try to use the target memory map to decide if software or hardware
breakpoint must be used.
<P>
<DT><CODE>set breakpoint auto-hw off</CODE>
<DD>This indicates GDB should not automatically select breakpoint
type. If the target provides a memory map, GDB will warn when
trying to set software breakpoint at a read-only address.
</DL>
<P>
<A NAME="IDX206"></A>
<A NAME="IDX207"></A>
GDB itself sometimes sets breakpoints in your program for
special purposes, such as proper handling of <CODE>longjmp</CODE> (in C
programs). These internal breakpoints are assigned negative numbers,
starting with <CODE>-1</CODE>; <SAMP>`info breakpoints'</SAMP> does not display them.
You can see these breakpoints with the GDB maintenance command
<SAMP>`maint info breakpoints'</SAMP> (see <A HREF="gdb_32.html#maint info breakpoints">maint info breakpoints</A>).
</P><P>
<A NAME="Set Watchpoints"></A>
<HR SIZE="6">
<A NAME="SEC34"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC33"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC35"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC35"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC32"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC43"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 5.1.2 Setting Watchpoints </H3>
<!--docid::SEC34::-->
<P>
<A NAME="IDX208"></A>
You can use a watchpoint to stop execution whenever the value of an
expression changes, without having to predict a particular place where
this may happen. (This is sometimes called a <EM>data breakpoint</EM>.)
The expression may be as simple as the value of a single variable, or
as complex as many variables combined by operators. Examples include:
</P><P>
<UL>
<LI>
A reference to the value of a single variable.
<P>
<LI>
An address cast to an appropriate data type. For example,
<SAMP>`*(int *)0x12345678'</SAMP> will watch a 4-byte region at the specified
address (assuming an <CODE>int</CODE> occupies 4 bytes).
<P>
<LI>
An arbitrarily complex expression, such as <SAMP>`a*b + c/d'</SAMP>. The
expression can use any operators valid in the program's native
language (see section <A HREF="gdb_13.html#SEC102">12. Using GDB with Different Languages</A>).
</UL>
<P>
<A NAME="IDX209"></A>
<A NAME="IDX210"></A>
Depending on your system, watchpoints may be implemented in software or
hardware. GDB does software watchpointing by single-stepping your
program and testing the variable's value each time, which is hundreds of
times slower than normal execution. (But this may still be worth it, to
catch errors where you have no clue what part of your program is the
culprit.)
</P><P>
On some systems, such as HP-UX, PowerPC, GNU/Linux and most other
x86-based targets, GDB includes support for hardware
watchpoints, which do not slow down the running of your program.
</P><P>
<DL COMPACT>
<A NAME="IDX211"></A>
<DT><CODE>watch <VAR>expr</VAR> [thread <VAR>threadnum</VAR>]</CODE>
<DD>Set a watchpoint for an expression. GDB will break when the
expression <VAR>expr</VAR> is written into by the program and its value
changes. The simplest (and the most popular) use of this command is
to watch the value of a single variable:
<P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) watch foo
</FONT></pre></td></tr></table></P><P>
If the command includes a <CODE>[thread <VAR>threadnum</VAR>]</CODE>
clause, GDB breaks only when the thread identified by
<VAR>threadnum</VAR> changes the value of <VAR>expr</VAR>. If any other threads
change the value of <VAR>expr</VAR>, GDB will not break. Note
that watchpoints restricted to a single thread in this way only work
with Hardware Watchpoints.
</P><P>
<A NAME="IDX212"></A>
<DT><CODE>rwatch <VAR>expr</VAR> [thread <VAR>threadnum</VAR>]</CODE>
<DD>Set a watchpoint that will break when the value of <VAR>expr</VAR> is read
by the program.
<P>
<A NAME="IDX213"></A>
<DT><CODE>awatch <VAR>expr</VAR> [thread <VAR>threadnum</VAR>]</CODE>
<DD>Set a watchpoint that will break when <VAR>expr</VAR> is either read from
or written into by the program.
<P>
<A NAME="IDX214"></A>
<DT><CODE>info watchpoints</CODE>
<DD>This command prints a list of watchpoints, breakpoints, and catchpoints;
it is the same as <CODE>info break</CODE> (see section <A HREF="gdb_6.html#SEC33">5.1.1 Setting Breakpoints</A>).
</DL>
<P>
GDB sets a <EM>hardware watchpoint</EM> if possible. Hardware
watchpoints execute very quickly, and the debugger reports a change in
value at the exact instruction where the change occurs. If GDB
cannot set a hardware watchpoint, it sets a software watchpoint, which
executes more slowly and reports the change in value at the next
<EM>statement</EM>, not the instruction, after the change occurs.
</P><P>
<A NAME="IDX215"></A>
You can force GDB to use only software watchpoints with the
<KBD>set can-use-hw-watchpoints 0</KBD> command. With this variable set to
zero, GDB will never try to use hardware watchpoints, even if
the underlying system supports them. (Note that hardware-assisted
watchpoints that were set <EM>before</EM> setting
<CODE>can-use-hw-watchpoints</CODE> to zero will still use the hardware
mechanism of watching expression values.)
</P><P>
<DL COMPACT>
<DT><CODE>set can-use-hw-watchpoints</CODE>
<DD><A NAME="IDX216"></A>
Set whether or not to use hardware watchpoints.
<P>
<DT><CODE>show can-use-hw-watchpoints</CODE>
<DD><A NAME="IDX217"></A>
Show the current mode of using hardware watchpoints.
</DL>
<P>
For remote targets, you can restrict the number of hardware
watchpoints GDB will use, see <A HREF="gdb_18.html#set remote hardware-breakpoint-limit">set remote hardware-breakpoint-limit</A>.
</P><P>
When you issue the <CODE>watch</CODE> command, GDB reports
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>Hardware watchpoint <VAR>num</VAR>: <VAR>expr</VAR>
</FONT></pre></td></tr></table></P><P>
if it was able to set a hardware watchpoint.
</P><P>
Currently, the <CODE>awatch</CODE> and <CODE>rwatch</CODE> commands can only set
hardware watchpoints, because accesses to data that don't change the
value of the watched expression cannot be detected without examining
every instruction as it is being executed, and GDB does not do
that currently. If GDB finds that it is unable to set a
hardware breakpoint with the <CODE>awatch</CODE> or <CODE>rwatch</CODE> command, it
will print a message like this:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>Expression cannot be implemented with read/access watchpoint.
</FONT></pre></td></tr></table></P><P>
Sometimes, GDB cannot set a hardware watchpoint because the
data type of the watched expression is wider than what a hardware
watchpoint on the target machine can handle. For example, some systems
can only watch regions that are up to 4 bytes wide; on such systems you
cannot set hardware watchpoints for an expression that yields a
double-precision floating-point number (which is typically 8 bytes
wide). As a work-around, it might be possible to break the large region
into a series of smaller ones and watch them with separate watchpoints.
</P><P>
If you set too many hardware watchpoints, GDB might be unable
to insert all of them when you resume the execution of your program.
Since the precise number of active watchpoints is unknown until such
time as the program is about to be resumed, GDB might not be
able to warn you about this when you set the watchpoints, and the
warning will be printed only when the program is resumed:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>Hardware watchpoint <VAR>num</VAR>: Could not insert watchpoint
</FONT></pre></td></tr></table></P><P>
If this happens, delete or disable some of the watchpoints.
</P><P>
Watching complex expressions that reference many variables can also
exhaust the resources available for hardware-assisted watchpoints.
That's because GDB needs to watch every variable in the
expression with separately allocated resources.
</P><P>
The SPARClite DSU will generate traps when a program accesses some data
or instruction address that is assigned to the debug registers. For the
data addresses, DSU facilitates the <CODE>watch</CODE> command. However the
hardware breakpoint registers can only take two data watchpoints, and
both watchpoints must be the same kind. For example, you can set two
watchpoints with <CODE>watch</CODE> commands, two with <CODE>rwatch</CODE> commands,
<STRONG>or</STRONG> two with <CODE>awatch</CODE> commands, but you cannot set one
watchpoint with one command and the other with a different command.
GDB will reject the command if you try to mix watchpoints.
Delete or disable unused watchpoint commands before setting new ones.
</P><P>
If you call a function interactively using <CODE>print</CODE> or <CODE>call</CODE>,
any watchpoints you have set will be inactive until GDB reaches another
kind of breakpoint or the call completes.
</P><P>
GDB automatically deletes watchpoints that watch local
(automatic) variables, or expressions that involve such variables, when
they go out of scope, that is, when the execution leaves the block in
which these variables were defined. In particular, when the program
being debugged terminates, <EM>all</EM> local variables go out of scope,
and so only watchpoints that watch global variables remain set. If you
rerun the program, you will need to set all such watchpoints again. One
way of doing that would be to set a code breakpoint at the entry to the
<CODE>main</CODE> function and when it breaks, set all the watchpoints.
</P><P>
<A NAME="IDX218"></A>
<A NAME="IDX219"></A>
In multi-threaded programs, watchpoints will detect changes to the
watched expression from every thread.
</P><P>
<BLOCKQUOTE>
<EM>Warning:</EM> In multi-threaded programs, software watchpoints
have only limited usefulness. If GDB creates a software
watchpoint, it can only watch the value of an expression <EM>in a
single thread</EM>. If you are confident that the expression can only
change due to the current thread's activity (and if you are also
confident that no other thread can become current), then you can use
software watchpoints as usual. However, GDB may not notice
when a non-current thread's activity changes the expression. (Hardware
watchpoints, in contrast, watch an expression in all threads.)
</BLOCKQUOTE>
<P>
See <A HREF="gdb_18.html#set remote hardware-watchpoint-limit">set remote hardware-watchpoint-limit</A>.
</P><P>
<A NAME="Set Catchpoints"></A>
<HR SIZE="6">
<A NAME="SEC35"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC34"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC36"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC36"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC32"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC43"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 5.1.3 Setting Catchpoints </H3>
<!--docid::SEC35::-->
<P>
You can use <EM>catchpoints</EM> to cause the debugger to stop for certain
kinds of program events, such as C<TT>++</TT> exceptions or the loading of a
shared library. Use the <CODE>catch</CODE> command to set a catchpoint.
</P><P>
<DL COMPACT>
<A NAME="IDX220"></A>
<DT><CODE>catch <VAR>event</VAR></CODE>
<DD>Stop when <VAR>event</VAR> occurs. <VAR>event</VAR> can be any of the following:
<DL COMPACT>
<DT><CODE>throw</CODE>
<DD><A NAME="IDX221"></A>
The throwing of a C<TT>++</TT> exception.
<P>
<DT><CODE>catch</CODE>
<DD>The catching of a C<TT>++</TT> exception.
<P>
<DT><CODE>exception</CODE>
<DD><A NAME="IDX222"></A>
<A NAME="IDX223"></A>
An Ada exception being raised. If an exception name is specified
at the end of the command (eg <CODE>catch exception Program_Error</CODE>),
the debugger will stop only when this specific exception is raised.
Otherwise, the debugger stops execution when any Ada exception is raised.
<P>
<DT><CODE>exception unhandled</CODE>
<DD>An exception that was raised but is not handled by the program.
<P>
<DT><CODE>assert</CODE>
<DD>A failed Ada assertion.
<P>
<DT><CODE>exec</CODE>
<DD><A NAME="IDX224"></A>
A call to <CODE>exec</CODE>. This is currently only available for HP-UX
and GNU/Linux.
<P>
<DT><CODE>fork</CODE>
<DD>A call to <CODE>fork</CODE>. This is currently only available for HP-UX
and GNU/Linux.
<P>
<DT><CODE>vfork</CODE>
<DD>A call to <CODE>vfork</CODE>. This is currently only available for HP-UX
and GNU/Linux.
<P>
<DT><CODE>load</CODE>
<DD><DT><CODE>load <VAR>libname</VAR></CODE>
<DD><A NAME="IDX225"></A>
The dynamic loading of any shared library, or the loading of the library
<VAR>libname</VAR>. This is currently only available for HP-UX.
<P>
<DT><CODE>unload</CODE>
<DD><DT><CODE>unload <VAR>libname</VAR></CODE>
<DD>The unloading of any dynamically loaded shared library, or the unloading
of the library <VAR>libname</VAR>. This is currently only available for HP-UX.
</DL>
<P>
<DT><CODE>tcatch <VAR>event</VAR></CODE>
<DD>Set a catchpoint that is enabled only for one stop. The catchpoint is
automatically deleted after the first time the event is caught.
<P>
</DL>
<P>
Use the <CODE>info break</CODE> command to list the current catchpoints.
</P><P>
There are currently some limitations to C<TT>++</TT> exception handling
(<CODE>catch throw</CODE> and <CODE>catch catch</CODE>) in GDB:
</P><P>
<UL>
<LI>
If you call a function interactively, GDB 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 you and cause your program either to abort or to
simply continue running until it hits a breakpoint, catches a signal
that GDB is listening for, or exits. This is the case even if
you set a catchpoint for the exception; catchpoints on exceptions are
disabled within interactive calls.
<P>
<LI>
You cannot raise an exception interactively.
<P>
<LI>
You cannot install an exception handler interactively.
</UL>
<P>
<A NAME="IDX226"></A>
Sometimes <CODE>catch</CODE> is not the best way to debug exception handling:
if you need to know exactly where an exception is raised, it is better to
stop <EM>before</EM> 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.
</P><P>
To stop just before an exception handler is called, you need some
knowledge of the implementation. In the case of GNU C<TT>++</TT>, exceptions are
raised by calling a library function named <CODE>__raise_exception</CODE>
which has the following ANSI C interface:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre> /* <VAR>addr</VAR> is where the exception identifier is stored.
<VAR>id</VAR> is the exception identifier. */
void __raise_exception (void **addr, void *id);
</FONT></pre></td></tr></table></P><P>
To make the debugger catch all exceptions before any stack
unwinding takes place, set a breakpoint on <CODE>__raise_exception</CODE>
(see section <A HREF="gdb_6.html#SEC32">Breakpoints; Watchpoints; and Exceptions</A>).
</P><P>
With a conditional breakpoint (see section <A HREF="gdb_6.html#SEC38">Break Conditions</A>)
that depends on the value of <VAR>id</VAR>, you can stop your program when
a specific exception is raised. You can use multiple conditional
breakpoints to stop your program when any of a number of exceptions are
raised.
</P><P>
<A NAME="Delete Breaks"></A>
<HR SIZE="6">
<A NAME="SEC36"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC35"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC37"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC37"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC32"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC43"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 5.1.4 Deleting Breakpoints </H3>
<!--docid::SEC36::-->
<P>
<A NAME="IDX227"></A>
<A NAME="IDX228"></A>
It is often necessary to eliminate a breakpoint, watchpoint, or
catchpoint once it has done its job and you no longer want your program
to stop there. This is called <EM>deleting</EM> the breakpoint. A
breakpoint that has been deleted no longer exists; it is forgotten.
</P><P>
With the <CODE>clear</CODE> command you can delete breakpoints according to
where they are in your program. With the <CODE>delete</CODE> command you can
delete individual breakpoints, watchpoints, or catchpoints by specifying
their breakpoint numbers.
</P><P>
It is not necessary to delete a breakpoint to proceed past it. GDB
automatically ignores breakpoints on the first instruction to be executed
when you continue execution without changing the execution address.
</P><P>
<DL COMPACT>
<A NAME="IDX229"></A>
<DT><CODE>clear</CODE>
<DD>Delete any breakpoints at the next instruction to be executed in the
selected stack frame (see section <A HREF="gdb_7.html#SEC49">Selecting a Frame</A>). When
the innermost frame is selected, this is a good way to delete a
breakpoint where your program just stopped.
<P>
<DT><CODE>clear <VAR>location</VAR></CODE>
<DD>Delete any breakpoints set at the specified <VAR>location</VAR>.
See section <A HREF="gdb_8.html#SEC53">7.2 Specifying a Location</A>, for the various forms of <VAR>location</VAR>; the
most useful ones are listed below:
<P>
<DL COMPACT>
<DT><CODE>clear <VAR>function</VAR></CODE>
<DD><DT><CODE>clear <VAR>filename</VAR>:<VAR>function</VAR></CODE>
<DD>Delete any breakpoints set at entry to the named <VAR>function</VAR>.
<P>
<DT><CODE>clear <VAR>linenum</VAR></CODE>
<DD><DT><CODE>clear <VAR>filename</VAR>:<VAR>linenum</VAR></CODE>
<DD>Delete any breakpoints set at or within the code of the specified
<VAR>linenum</VAR> of the specified <VAR>filename</VAR>.
</DL>
<P>
<A NAME="IDX230"></A>
<A NAME="IDX231"></A>
<A NAME="IDX232"></A>
<DT><CODE>delete [breakpoints] [<VAR>range</VAR><small>...</small>]</CODE>
<DD>Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
ranges specified as arguments. If no argument is specified, delete all
breakpoints (GDB asks confirmation, unless you have <CODE>set
confirm off</CODE>). You can abbreviate this command as <CODE>d</CODE>.
</DL>
<P>
<A NAME="Disabling"></A>
<HR SIZE="6">
<A NAME="SEC37"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC36"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC38"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC38"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC32"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC43"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 5.1.5 Disabling Breakpoints </H3>
<!--docid::SEC37::-->
<P>
<A NAME="IDX233"></A>
Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
prefer to <EM>disable</EM> it. This makes the breakpoint inoperative as if
it had been deleted, but remembers the information on the breakpoint so
that you can <EM>enable</EM> it again later.
</P><P>
You disable and enable breakpoints, watchpoints, and catchpoints with
the <CODE>enable</CODE> and <CODE>disable</CODE> commands, optionally specifying one
or more breakpoint numbers as arguments. Use <CODE>info break</CODE> or
<CODE>info watch</CODE> to print a list of breakpoints, watchpoints, and
catchpoints if you do not know which numbers to use.
</P><P>
Disabling and enabling a breakpoint that has multiple locations
affects all of its locations.
</P><P>
A breakpoint, watchpoint, or catchpoint can have any of four different
states of enablement:
</P><P>
<UL>
<LI>
Enabled. The breakpoint stops your program. A breakpoint set
with the <CODE>break</CODE> command starts out in this state.
<LI>
Disabled. The breakpoint has no effect on your program.
<LI>
Enabled once. The breakpoint stops your program, but then becomes
disabled.
<LI>
Enabled for deletion. The breakpoint stops your program, but
immediately after it does so it is deleted permanently. A breakpoint
set with the <CODE>tbreak</CODE> command starts out in this state.
</UL>
<P>
You can use the following commands to enable or disable breakpoints,
watchpoints, and catchpoints:
</P><P>
<DL COMPACT>
<A NAME="IDX234"></A>
<A NAME="IDX235"></A>
<DT><CODE>disable [breakpoints] [<VAR>range</VAR><small>...</small>]</CODE>
<DD>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</CODE> as <CODE>dis</CODE>.
<P>
<A NAME="IDX236"></A>
<DT><CODE>enable [breakpoints] [<VAR>range</VAR><small>...</small>]</CODE>
<DD>Enable the specified breakpoints (or all defined breakpoints). They
become effective once again in stopping your program.
<P>
<DT><CODE>enable [breakpoints] once <VAR>range</VAR><small>...</small></CODE>
<DD>Enable the specified breakpoints temporarily. GDB disables any
of these breakpoints immediately after stopping your program.
<P>
<DT><CODE>enable [breakpoints] delete <VAR>range</VAR><small>...</small></CODE>
<DD>Enable the specified breakpoints to work once, then die. GDB
deletes any of these breakpoints as soon as your program stops there.
Breakpoints set by the <CODE>tbreak</CODE> command start out in this state.
</DL>
<P>
Except for a breakpoint set with <CODE>tbreak</CODE> (see section <A HREF="gdb_6.html#SEC33">Setting Breakpoints</A>), breakpoints that you set are initially enabled;
subsequently, they become disabled or enabled only when you use one of
the commands above. (The command <CODE>until</CODE> can set and delete a
breakpoint of its own, but it does not change the state of your other
breakpoints; see <A HREF="gdb_6.html#SEC43">Continuing and Stepping</A>.)
</P><P>
<A NAME="Conditions"></A>
<HR SIZE="6">
<A NAME="SEC38"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC37"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC39"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC39"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC32"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC43"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 5.1.6 Break Conditions </H3>
<!--docid::SEC38::-->
<P>
The simplest sort of breakpoint breaks every time your program reaches a
specified place. You can also specify a <EM>condition</EM> for a
breakpoint. A condition is just a Boolean expression in your
programming language (see section <A HREF="gdb_9.html#SEC60">Expressions</A>). A breakpoint with
a condition evaluates the expression each time your program reaches it,
and your program stops only if the condition is <EM>true</EM>.
</P><P>
This is the converse of using assertions for program validation; in that
situation, you want to stop when the assertion is violated--that is,
when the condition is false. In C, if you want to test an assertion expressed
by the condition <VAR>assert</VAR>, you should set the condition
<SAMP>`! <VAR>assert</VAR>'</SAMP> on the appropriate breakpoint.
</P><P>
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,
and specify a condition that tests whether the new value is an interesting
one.
</P><P>
Break conditions can have side effects, and may even call functions in
your program. This can be useful, for example, to activate functions
that log program progress, or to use your own print functions to
format special data structures. The effects are completely predictable
unless there is another enabled breakpoint at the same address. (In
that case, GDB might see the other breakpoint first and stop your
program without checking the condition of this one.) Note that
breakpoint commands are usually more convenient and flexible than break
conditions for the
purpose of performing side effects when a breakpoint is reached
(see section <A HREF="gdb_6.html#SEC39">Breakpoint Command Lists</A>).
</P><P>
Break conditions can be specified when a breakpoint is set, by using
<SAMP>`if'</SAMP> in the arguments to the <CODE>break</CODE> command. See section <A HREF="gdb_6.html#SEC33">Setting Breakpoints</A>. They can also be changed at any time
with the <CODE>condition</CODE> command.
</P><P>
You can also use the <CODE>if</CODE> keyword with the <CODE>watch</CODE> command.
The <CODE>catch</CODE> command does not recognize the <CODE>if</CODE> keyword;
<CODE>condition</CODE> is the only way to impose a further condition on a
catchpoint.
</P><P>
<DL COMPACT>
<A NAME="IDX237"></A>
<DT><CODE>condition <VAR>bnum</VAR> <VAR>expression</VAR></CODE>
<DD>Specify <VAR>expression</VAR> as the break condition for breakpoint,
watchpoint, or catchpoint number <VAR>bnum</VAR>. After you set a condition,
breakpoint <VAR>bnum</VAR> stops your program only if the value of
<VAR>expression</VAR> is true (nonzero, in C). When you use
<CODE>condition</CODE>, GDB checks <VAR>expression</VAR> immediately for
syntactic correctness, and to determine whether symbols in it have
referents in the context of your breakpoint. If <VAR>expression</VAR> uses
symbols not referenced in the context of the breakpoint, GDB
prints an error message:
<P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>No symbol "foo" in current context.
</FONT></pre></td></tr></table></P><P>
GDB does
not actually evaluate <VAR>expression</VAR> at the time the <CODE>condition</CODE>
command (or a command that sets a breakpoint with a condition, like
<CODE>break if <small>...</small></CODE>) is given, however. See section <A HREF="gdb_9.html#SEC60">Expressions</A>.
</P><P>
<DT><CODE>condition <VAR>bnum</VAR></CODE>
<DD>Remove the condition from breakpoint number <VAR>bnum</VAR>. It becomes
an ordinary unconditional breakpoint.
</DL>
<P>
<A NAME="IDX238"></A>
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 <EM>ignore
count</EM> 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 your 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</VAR>, the breakpoint does not stop the next <VAR>n</VAR> times
your program reaches it.
</P><P>
<DL COMPACT>
<A NAME="IDX239"></A>
<DT><CODE>ignore <VAR>bnum</VAR> <VAR>count</VAR></CODE>
<DD>Set the ignore count of breakpoint number <VAR>bnum</VAR> to <VAR>count</VAR>.
The next <VAR>count</VAR> times the breakpoint is reached, your program's
execution does not stop; other than to decrement the ignore count, GDB
takes no action.
<P>
To make the breakpoint stop the next time it is reached, specify
a count of zero.
</P><P>
When you use <CODE>continue</CODE> to resume execution of your program from a
breakpoint, you can specify an ignore count directly as an argument to
<CODE>continue</CODE>, rather than using <CODE>ignore</CODE>. See section <A HREF="gdb_6.html#SEC43">Continuing and Stepping</A>.
</P><P>
If a breakpoint has a positive ignore count and a condition, the
condition is not checked. Once the ignore count reaches zero,
GDB resumes checking the condition.
</P><P>
You could achieve the effect of the ignore count with a condition such
as <SAMP>`$foo-- <= 0'</SAMP> using a debugger convenience variable that
is decremented each time. See section <A HREF="gdb_9.html#SEC68">Convenience Variables</A>.
</DL>
<P>
Ignore counts apply to breakpoints, watchpoints, and catchpoints.
</P><P>
<A NAME="Break Commands"></A>
<HR SIZE="6">
<A NAME="SEC39"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC38"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC40"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC40"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC32"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC43"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 5.1.7 Breakpoint Command Lists </H3>
<!--docid::SEC39::-->
<P>
<A NAME="IDX240"></A>
You can give any breakpoint (or watchpoint or catchpoint) a series of
commands to execute when your program stops due to that breakpoint. For
example, you might want to print the values of certain expressions, or
enable other breakpoints.
</P><P>
<DL COMPACT>
<A NAME="IDX241"></A>
<A NAME="IDX242"></A>
<DT><CODE>commands [<VAR>bnum</VAR>]</CODE>
<DD><DT><CODE><small>...</small> <VAR>command-list</VAR> <small>...</small></CODE>
<DD><DT><CODE>end</CODE>
<DD>Specify a list of commands for breakpoint number <VAR>bnum</VAR>. The commands
themselves appear on the following lines. Type a line containing just
<CODE>end</CODE> to terminate the commands.
<P>
To remove all commands from a breakpoint, type <CODE>commands</CODE> and
follow it immediately with <CODE>end</CODE>; that is, give no commands.
</P><P>
With no <VAR>bnum</VAR> argument, <CODE>commands</CODE> refers to the last
breakpoint, watchpoint, or catchpoint set (not to the breakpoint most
recently encountered).
</DL>
<P>
Pressing <KBD>RET</KBD> as a means of repeating the last GDB command is
disabled within a <VAR>command-list</VAR>.
</P><P>
You can use breakpoint commands to start your program up again. Simply
use the <CODE>continue</CODE> command, or <CODE>step</CODE>, or any other command
that resumes execution.
</P><P>
Any other commands in the command list, after a command that resumes
execution, are ignored. This is because any time you resume execution
(even with a simple <CODE>next</CODE> or <CODE>step</CODE>), you may encounter
another breakpoint--which could have its own command list, leading to
ambiguities about which list to execute.
</P><P>
<A NAME="IDX243"></A>
If the first command you specify in a command list is <CODE>silent</CODE>, 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 none of the remaining commands print anything, you
see no sign that the breakpoint was reached. <CODE>silent</CODE> is
meaningful only at the beginning of a breakpoint command list.
</P><P>
The commands <CODE>echo</CODE>, <CODE>output</CODE>, and <CODE>printf</CODE> allow you to
print precisely controlled output, and are often useful in silent
breakpoints. See section <A HREF="gdb_21.html#SEC233">Commands for Controlled Output</A>.
</P><P>
For example, here is how you could use breakpoint commands to print the
value of <CODE>x</CODE> at entry to <CODE>foo</CODE> whenever <CODE>x</CODE> is positive.
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>break foo if x>0
commands
silent
printf "x is %d\n",x
cont
end
</FONT></pre></td></tr></table></P><P>
One application for breakpoint commands is to compensate for one bug so
you can test for 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</CODE> command
so that your program does not stop, and start with the <CODE>silent</CODE>
command so that no output is produced. Here is an example:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>break 403
commands
silent
set x = y + 4
cont
end
</FONT></pre></td></tr></table></P><P>
<A NAME="Breakpoint Menus"></A>
<HR SIZE="6">
<A NAME="SEC40"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC39"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC41"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC41"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC32"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC43"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 5.1.8 Breakpoint Menus </H3>
<!--docid::SEC40::-->
<P>
Some programming languages (notably C<TT>++</TT> and Objective-C) permit a
single function name
to be defined several times, for application in different contexts.
This is called <EM>overloading</EM>. When a function name is overloaded,
<SAMP>`break <VAR>function</VAR>'</SAMP> is not enough to tell GDB where you want
a breakpoint. You can use explicit signature of the function, as in
<SAMP>`break <VAR>function</VAR>(<VAR>types</VAR>)'</SAMP>, to specify which
particular version of the function you want. Otherwise, GDB offers
you a menu of numbered choices for different possible breakpoints, and
waits for your selection with the prompt <SAMP>`>'</SAMP>. The first two
options are always <SAMP>`[0] cancel'</SAMP> and <SAMP>`[1] all'</SAMP>. Typing <KBD>1</KBD>
sets a breakpoint at each definition of <VAR>function</VAR>, and typing
<KBD>0</KBD> aborts the <CODE>break</CODE> command without setting any new
breakpoints.
</P><P>
For example, the following session excerpt shows an attempt to set a
breakpoint at the overloaded symbol <CODE>String::after</CODE>.
We choose three particular definitions of that function name:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) 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.
(gdb)
</FONT></pre></td></tr></table></P><P>
<A NAME="Error in Breakpoints"></A>
<HR SIZE="6">
<A NAME="SEC41"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC40"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC42"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC32"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC43"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 5.1.9 "Cannot insert breakpoints" </H3>
<!--docid::SEC41::-->
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 causes
GDB to print an error message:
<P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>Cannot insert breakpoints.
The same program may be running in another process.
</FONT></pre></td></tr></table></P><P>
When this happens, you have three ways to proceed:
</P><P>
<OL>
<LI>
Remove or disable the breakpoints, then continue.
<P>
<LI>
Suspend GDB, and copy the file containing your program to a new
name. Resume GDB and use the <CODE>exec-file</CODE> command to specify
that GDB should run your program under that name.
Then start your program again.
<P>
<LI>
Relink your program so that the text segment is nonsharable, using the
linker option <SAMP>`-N'</SAMP>. The operating system limitation may not apply
to nonsharable executables.
</OL>
<P>
A similar message can be printed if you request too many active
hardware-assisted breakpoints and watchpoints:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>Stopped; cannot insert breakpoints.
You may have requested too many hardware breakpoints and watchpoints.
</FONT></pre></td></tr></table></P><P>
This message is printed when you attempt to resume the program, since
only then GDB knows exactly how many hardware breakpoints and
watchpoints it needs to insert.
</P><P>
When this message is printed, you need to disable or remove some of the
hardware-assisted breakpoints and watchpoints, and then continue.
</P><P>
<A NAME="Breakpoint-related Warnings"></A>
<HR SIZE="6">
<A NAME="SEC42"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC41"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC43"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC34"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC32"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC43"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 5.1.10 "Breakpoint address adjusted..." </H3>
<!--docid::SEC42::-->
<P>
Some processor architectures place constraints on the addresses at
which breakpoints may be placed. For architectures thus constrained,
GDB will attempt to adjust the breakpoint's address to comply
with the constraints dictated by the architecture.
</P><P>
One example of such an architecture is the Fujitsu FR-V. The FR-V is
a VLIW architecture in which a number of RISC-like instructions may be
bundled together for parallel execution. The FR-V architecture
constrains the location of a breakpoint instruction within such a
bundle to the instruction with the lowest address. GDB
honors this constraint by adjusting a breakpoint's address to the
first in the bundle.
</P><P>
It is not uncommon for optimized code to have bundles which contain
instructions from different source statements, thus it may happen that
a breakpoint's address will be adjusted from one source statement to
another. Since this adjustment may significantly alter GDB's
breakpoint related behavior from what the user expects, a warning is
printed when the breakpoint is first set and also when the breakpoint
is hit.
</P><P>
A warning like the one below is printed when setting a breakpoint
that's been subject to address adjustment:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.
</FONT></pre></td></tr></table></P><P>
Such warnings are printed both for user settable and GDB's
internal breakpoints. If you see one of these warnings, you should
verify that a breakpoint set at the adjusted address will have the
desired affect. If not, the breakpoint in question may be removed and
other breakpoints may be set which will have the desired behavior.
E.g., it may be sufficient to place the breakpoint at a later
instruction. A conditional breakpoint may also be useful in some
cases to prevent the breakpoint from triggering too often.
</P><P>
GDB will also issue a warning when stopping at one of these
adjusted breakpoints:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>warning: Breakpoint 1 address previously adjusted from 0x00010414
to 0x00010410.
</FONT></pre></td></tr></table></P><P>
When this warning is encountered, it may be too late to take remedial
action except in cases where the breakpoint is hit earlier or more
frequently than expected.
</P><P>
<A NAME="Continuing and Stepping"></A>
<HR SIZE="6">
<A NAME="SEC43"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC42"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC44"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC44"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_7.html#SEC46"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 5.2 Continuing and Stepping </H2>
<!--docid::SEC43::-->
<P>
<A NAME="IDX244"></A>
<A NAME="IDX245"></A>
<A NAME="IDX246"></A>
<EM>Continuing</EM> means resuming program execution until your program
completes normally. In contrast, <EM>stepping</EM> means executing just
one more "step" of your program, where "step" may mean either one
line of source code, or one machine instruction (depending on what
particular command you use). Either when continuing or when stepping,
your program may stop even sooner, due to a breakpoint or a signal. (If
it stops due to a signal, you may want to use <CODE>handle</CODE>, or use
<SAMP>`signal 0'</SAMP> to resume execution. See section <A HREF="gdb_6.html#SEC44">Signals</A>.)
</P><P>
<DL COMPACT>
<A NAME="IDX247"></A>
<A NAME="IDX248"></A>
<A NAME="IDX249"></A>
<DT><CODE>continue [<VAR>ignore-count</VAR>]</CODE>
<DD><DT><CODE>c [<VAR>ignore-count</VAR>]</CODE>
<DD><DT><CODE>fg [<VAR>ignore-count</VAR>]</CODE>
<DD>Resume program execution, at the address where your program last stopped;
any breakpoints set at that address are bypassed. The optional argument
<VAR>ignore-count</VAR> allows you to specify a further number of times to
ignore a breakpoint at this location; its effect is like that of
<CODE>ignore</CODE> (see section <A HREF="gdb_6.html#SEC38">Break Conditions</A>).
<P>
The argument <VAR>ignore-count</VAR> is meaningful only when your program
stopped due to a breakpoint. At other times, the argument to
<CODE>continue</CODE> is ignored.
</P><P>
The synonyms <CODE>c</CODE> and <CODE>fg</CODE> (for <EM>foreground</EM>, as the
debugged program is deemed to be the foreground program) are provided
purely for convenience, and have exactly the same behavior as
<CODE>continue</CODE>.
</DL>
<P>
To resume execution at a different place, you can use <CODE>return</CODE>
(see section <A HREF="gdb_15.html#SEC151">Returning from a Function</A>) to go back to the
calling function; or <CODE>jump</CODE> (see section <A HREF="gdb_15.html#SEC149">Continuing at a Different Address</A>) to go to an arbitrary location in your program.
</P><P>
A typical technique for using stepping is to set a breakpoint
(see section <A HREF="gdb_6.html#SEC32">Breakpoints; Watchpoints; and Catchpoints</A>) at the
beginning of the function or the section of your program where a problem
is believed to lie, run your 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.
</P><P>
<DL COMPACT>
<A NAME="IDX250"></A>
<A NAME="IDX251"></A>
<DT><CODE>step</CODE>
<DD>Continue running your program until control reaches a different source
line, then stop it and return control to GDB. This command is
abbreviated <CODE>s</CODE>.
<P>
<BLOCKQUOTE>
<EM>Warning:</EM> If you use the <CODE>step</CODE> command while control is
within a function that was compiled without debugging information,
execution proceeds until control reaches a function that does have
debugging information. Likewise, it will not step into a function which
is compiled without debugging information. To step through functions
without debugging information, use the <CODE>stepi</CODE> command, described
below.
</BLOCKQUOTE>
<P>
The <CODE>step</CODE> command only stops at the first instruction of a source
line. This prevents the multiple stops that could otherwise occur in
<CODE>switch</CODE> statements, <CODE>for</CODE> loops, etc. <CODE>step</CODE> continues
to stop if a function that has debugging information is called within
the line. In other words, <CODE>step</CODE> <EM>steps inside</EM> any functions
called within the line.
</P><P>
Also, the <CODE>step</CODE> command only enters a function if there is line
number information for the function. Otherwise it acts like the
<CODE>next</CODE> command. This avoids problems when using <CODE>cc -gl</CODE>
on MIPS machines. Previously, <CODE>step</CODE> entered subroutines if there
was any debugging information about the routine.
</P><P>
<DT><CODE>step <VAR>count</VAR></CODE>
<DD>Continue running as in <CODE>step</CODE>, but do so <VAR>count</VAR> times. If a
breakpoint is reached, or a signal not related to stepping occurs before
<VAR>count</VAR> steps, stepping stops right away.
<P>
<A NAME="IDX252"></A>
<A NAME="IDX253"></A>
<DT><CODE>next [<VAR>count</VAR>]</CODE>
<DD>Continue to the next source line in the current (innermost) stack frame.
This is similar to <CODE>step</CODE>, but function calls that appear within
the line of code are executed without stopping. Execution stops when
control reaches a different line of code at the original stack level
that was executing when you gave the <CODE>next</CODE> command. This command
is abbreviated <CODE>n</CODE>.
<P>
An argument <VAR>count</VAR> is a repeat count, as for <CODE>step</CODE>.
</P><P>
The <CODE>next</CODE> command only stops at the first instruction of a
source line. This prevents multiple stops that could otherwise occur in
<CODE>switch</CODE> statements, <CODE>for</CODE> loops, etc.
</P><P>
<A NAME="IDX254"></A>
<DT><CODE>set step-mode</CODE>
<DD><A NAME="IDX255"></A>
<A NAME="IDX256"></A>
<DT><CODE>set step-mode on</CODE>
<DD>The <CODE>set step-mode on</CODE> command causes the <CODE>step</CODE> command to
stop at the first instruction of a function which contains no debug line
information rather than stepping over it.
<P>
This is useful in cases where you may be interested in inspecting the
machine instructions of a function which has no symbolic info and do not
want GDB to automatically skip over this function.
</P><P>
<DT><CODE>set step-mode off</CODE>
<DD>Causes the <CODE>step</CODE> command to step over any functions which contains no
debug information. This is the default.
<P>
<DT><CODE>show step-mode</CODE>
<DD>Show whether GDB will stop in or step over functions without
source line debug information.
<P>
<A NAME="IDX257"></A>
<DT><CODE>finish</CODE>
<DD>Continue running until just after function in the selected stack frame
returns. Print the returned value (if any).
<P>
Contrast this with the <CODE>return</CODE> command (see section <A HREF="gdb_15.html#SEC151">Returning from a Function</A>).
</P><P>
<A NAME="IDX258"></A>
<A NAME="IDX259"></A>
<A NAME="IDX260"></A>
<DT><CODE>until</CODE>
<DD><DT><CODE>u</CODE>
<DD>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</CODE>
command, except that when <CODE>until</CODE> encounters a jump, it
automatically continues execution until the program counter is greater
than the address of the jump.
<P>
This means that when you reach the end of a loop after single stepping
though it, <CODE>until</CODE> makes your program continue execution until it
exits the loop. In contrast, a <CODE>next</CODE> command at the end of a loop
simply steps back to the beginning of the loop, which forces you to step
through the next iteration.
</P><P>
<CODE>until</CODE> always stops your program if it attempts to exit the current
stack frame.
</P><P>
<CODE>until</CODE> may produce somewhat counterintuitive results if the order
of machine code does not match the order of the source lines. For
example, in the following excerpt from a debugging session, the <CODE>f</CODE>
(<CODE>frame</CODE>) command shows that execution is stopped at line
<CODE>206</CODE>; yet when we use <CODE>until</CODE>, we get to line <CODE>195</CODE>:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) f
#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
206 expand_input();
(gdb) until
195 for ( ; argc > 0; NEXTARG) {
</FONT></pre></td></tr></table></P><P>
This happened because, for execution efficiency, the compiler had
generated code for the loop closure test at the end, rather than the
start, of the loop--even though the test in a C <CODE>for</CODE>-loop is
written before the body of the loop. The <CODE>until</CODE> 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.
</P><P>
<CODE>until</CODE> with no argument works by means of single
instruction stepping, and hence is slower than <CODE>until</CODE> with an
argument.
</P><P>
<DT><CODE>until <VAR>location</VAR></CODE>
<DD><DT><CODE>u <VAR>location</VAR></CODE>
<DD>Continue running your program until either the specified location is
reached, or the current stack frame returns. <VAR>location</VAR> is any of
the forms described in <A HREF="gdb_8.html#SEC53">7.2 Specifying a Location</A>.
This form of the command uses temporary breakpoints, and
hence is quicker than <CODE>until</CODE> without an argument. The specified
location is actually reached only if it is in the current frame. This
implies that <CODE>until</CODE> can be used to skip over recursive function
invocations. For instance in the code below, if the current location is
line <CODE>96</CODE>, issuing <CODE>until 99</CODE> will execute the program up to
line <CODE>99</CODE> in the same invocation of factorial, i.e., after the inner
invocations have returned.
<P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>94 int factorial (int value)
95 {
96 if (value > 1) {
97 value *= factorial (value - 1);
98 }
99 return (value);
100 }
</FONT></pre></td></tr></table></P><P>
<A NAME="IDX261"></A>
<DT><CODE>advance <VAR>location</VAR></CODE>
<DD>Continue running the program up to the given <VAR>location</VAR>. An argument is
required, which should be of one of the forms described in
<A HREF="gdb_8.html#SEC53">7.2 Specifying a Location</A>.
Execution will also stop upon exit from the current stack
frame. This command is similar to <CODE>until</CODE>, but <CODE>advance</CODE> will
not skip over recursive function calls, and the target location doesn't
have to be in the same frame as the current one.
<P>
<A NAME="IDX262"></A>
<A NAME="IDX263"></A>
<DT><CODE>stepi</CODE>
<DD><DT><CODE>stepi <VAR>arg</VAR></CODE>
<DD><DT><CODE>si</CODE>
<DD>Execute one machine instruction, then stop and return to the debugger.
<P>
It is often useful to do <SAMP>`display/i $pc'</SAMP> when stepping by machine
instructions. This makes GDB automatically display the next
instruction to be executed, each time your program stops. See section <A HREF="gdb_9.html#SEC65">Automatic Display</A>.
</P><P>
An argument is a repeat count, as in <CODE>step</CODE>.
</P><P>
<A NAME="IDX264"></A>
<A NAME="IDX265"></A>
<DT><CODE>nexti</CODE>
<DD><DT><CODE>nexti <VAR>arg</VAR></CODE>
<DD><DT><CODE>ni</CODE>
<DD>Execute one machine instruction, but if it is a function call,
proceed until the function returns.
<P>
An argument is a repeat count, as in <CODE>next</CODE>.
</DL>
<P>
<A NAME="Signals"></A>
<HR SIZE="6">
<A NAME="SEC44"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC43"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC45"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC45"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_7.html#SEC46"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 5.3 Signals </H2>
<!--docid::SEC44::-->
<P>
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</CODE> is the
signal a program gets when you type an interrupt character (often <KBD>Ctrl-c</KBD>);
<CODE>SIGSEGV</CODE> is the signal a program gets from referencing a place in
memory far away from all the areas in use; <CODE>SIGALRM</CODE> occurs when
the alarm clock timer goes off (which happens only if your program has
requested an alarm).
</P><P>
<A NAME="IDX266"></A>
Some signals, including <CODE>SIGALRM</CODE>, are a normal part of the
functioning of your program. Others, such as <CODE>SIGSEGV</CODE>, indicate
errors; these signals are <EM>fatal</EM> (they kill your program immediately) if the
program has not specified in advance some other way to handle the signal.
<CODE>SIGINT</CODE> does not indicate an error in your program, but it is normally
fatal so it can carry out the purpose of the interrupt: to kill the program.
</P><P>
GDB has the ability to detect any occurrence of a signal in your
program. You can tell GDB in advance what to do for each kind of
signal.
</P><P>
<A NAME="IDX267"></A>
Normally, GDB is set up to let the non-erroneous signals like
<CODE>SIGALRM</CODE> be silently passed to your program
(so as not to interfere with their role in the program's functioning)
but to stop your program immediately whenever an error signal happens.
You can change these settings with the <CODE>handle</CODE> command.
</P><P>
<DL COMPACT>
<A NAME="IDX268"></A>
<A NAME="IDX269"></A>
<DT><CODE>info signals</CODE>
<DD><DT><CODE>info handle</CODE>
<DD>Print a table of all the kinds of signals and how GDB has been told to
handle each one. You can use this to see the signal numbers of all
the defined types of signals.
<P>
<DT><CODE>info signals <VAR>sig</VAR></CODE>
<DD>Similar, but print information only about the specified signal number.
<P>
<CODE>info handle</CODE> is an alias for <CODE>info signals</CODE>.
</P><P>
<A NAME="IDX270"></A>
<DT><CODE>handle <VAR>signal</VAR> [<VAR>keywords</VAR><small>...</small>]</CODE>
<DD>Change the way GDB handles signal <VAR>signal</VAR>. <VAR>signal</VAR>
can be the number of a signal or its name (with or without the
<SAMP>`SIG'</SAMP> at the beginning); a list of signal numbers of the form
<SAMP>`<VAR>low</VAR>-<VAR>high</VAR>'</SAMP>; or the word <SAMP>`all'</SAMP>, meaning all the
known signals. Optional arguments <VAR>keywords</VAR>, described below,
say what change to make.
</DL>
<P>
The keywords allowed by the <CODE>handle</CODE> command can be abbreviated.
Their full names are:
</P><P>
<DL COMPACT>
<DT><CODE>nostop</CODE>
<DD>GDB should not stop your program when this signal happens. It may
still print a message telling you that the signal has come in.
<P>
<DT><CODE>stop</CODE>
<DD>GDB should stop your program when this signal happens. This implies
the <CODE>print</CODE> keyword as well.
<P>
<DT><CODE>print</CODE>
<DD>GDB should print a message when this signal happens.
<P>
<DT><CODE>noprint</CODE>
<DD>GDB should not mention the occurrence of the signal at all. This
implies the <CODE>nostop</CODE> keyword as well.
<P>
<DT><CODE>pass</CODE>
<DD><DT><CODE>noignore</CODE>
<DD>GDB should allow your program to see this signal; your program
can handle the signal, or else it may terminate if the signal is fatal
and not handled. <CODE>pass</CODE> and <CODE>noignore</CODE> are synonyms.
<P>
<DT><CODE>nopass</CODE>
<DD><DT><CODE>ignore</CODE>
<DD>GDB should not allow your program to see this signal.
<CODE>nopass</CODE> and <CODE>ignore</CODE> are synonyms.
</DL>
<P>
When a signal stops your program, the signal is not visible to the
program until you
continue. Your program sees the signal then, if <CODE>pass</CODE> is in
effect for the signal in question <EM>at that time</EM>. In other words,
after GDB reports a signal, you can use the <CODE>handle</CODE>
command with <CODE>pass</CODE> or <CODE>nopass</CODE> to control whether your
program sees that signal when you continue.
</P><P>
The default is set to <CODE>nostop</CODE>, <CODE>noprint</CODE>, <CODE>pass</CODE> for
non-erroneous signals such as <CODE>SIGALRM</CODE>, <CODE>SIGWINCH</CODE> and
<CODE>SIGCHLD</CODE>, and to <CODE>stop</CODE>, <CODE>print</CODE>, <CODE>pass</CODE> for the
erroneous signals.
</P><P>
You can also use the <CODE>signal</CODE> command to prevent your 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. For example, if your 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 your program would probably terminate immediately as
a result of the fatal signal once it saw the signal. To prevent this,
you can continue with <SAMP>`signal 0'</SAMP>. See section <A HREF="gdb_15.html#SEC150">Giving your Program a Signal</A>.
</P><P>
<A NAME="Thread Stops"></A>
<HR SIZE="6">
<A NAME="SEC45"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC44"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_7.html#SEC46"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_7.html#SEC46"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 5.4 Stopping and Starting Multi-thread Programs </H2>
<!--docid::SEC45::-->
<P>
When your program has multiple threads (see section <A HREF="gdb_5.html#SEC27">Debugging Programs with Multiple Threads</A>), you can choose whether to set
breakpoints on all threads, or on a particular thread.
</P><P>
<DL COMPACT>
<A NAME="IDX271"></A>
<A NAME="IDX272"></A>
<A NAME="IDX273"></A>
<DT><CODE>break <VAR>linespec</VAR> thread <VAR>threadno</VAR></CODE>
<DD><DT><CODE>break <VAR>linespec</VAR> thread <VAR>threadno</VAR> if <small>...</small></CODE>
<DD><VAR>linespec</VAR> specifies source lines; there are several ways of
writing them (see section <A HREF="gdb_8.html#SEC53">7.2 Specifying a Location</A>), but the effect is always to
specify some source line.
<P>
Use the qualifier <SAMP>`thread <VAR>threadno</VAR>'</SAMP> with a breakpoint command
to specify that you only want GDB to stop the program when a
particular thread reaches this breakpoint. <VAR>threadno</VAR> is one of the
numeric thread identifiers assigned by GDB, shown in the first
column of the <SAMP>`info threads'</SAMP> display.
</P><P>
If you do not specify <SAMP>`thread <VAR>threadno</VAR>'</SAMP> when you set a
breakpoint, the breakpoint applies to <EM>all</EM> threads of your
program.
</P><P>
You can use the <CODE>thread</CODE> qualifier on conditional breakpoints as
well; in this case, place <SAMP>`thread <VAR>threadno</VAR>'</SAMP> before the
breakpoint condition, like this:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) break frik.c:13 thread 28 if bartab > lim
</FONT></pre></td></tr></table></P><P>
</DL>
<P>
<A NAME="IDX274"></A>
<A NAME="IDX275"></A>
Whenever your program stops under GDB for any reason,
<EM>all</EM> threads of execution stop, not just the current thread. This
allows you to examine the overall state of the program, including
switching between threads, without worrying that things may change
underfoot.
</P><P>
<A NAME="IDX276"></A>
<A NAME="IDX277"></A>
<A NAME="IDX278"></A>
There is an unfortunate side effect. If one thread stops for a
breakpoint, or for some other reason, and another thread is blocked in a
system call, then the system call may return prematurely. This is a
consequence of the interaction between multiple threads and the signals
that GDB uses to implement breakpoints and other events that
stop execution.
</P><P>
To handle this problem, your program should check the return value of
each system call and react appropriately. This is good programming
style anyways.
</P><P>
For example, do not write code like this:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre> sleep (10);
</FONT></pre></td></tr></table></P><P>
The call to <CODE>sleep</CODE> will return early if a different thread stops
at a breakpoint or for some other reason.
</P><P>
Instead, write this:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre> int unslept = 10;
while (unslept > 0)
unslept = sleep (unslept);
</FONT></pre></td></tr></table></P><P>
A system call is allowed to return early, so the system is still
conforming to its specification. But GDB does cause your
multi-threaded program to behave differently than it would without
GDB.
</P><P>
Also, GDB uses internal breakpoints in the thread library to
monitor certain events such as thread creation and thread destruction.
When such an event happens, a system call in another thread may return
prematurely, even though your program does not appear to stop.
</P><P>
<A NAME="IDX279"></A>
<A NAME="IDX280"></A>
Conversely, whenever you restart the program, <EM>all</EM> threads start
executing. <EM>This is true even when single-stepping</EM> with commands
like <CODE>step</CODE> or <CODE>next</CODE>.
</P><P>
In particular, GDB cannot single-step all threads in lockstep.
Since thread scheduling is up to your debugging target's operating
system (not controlled by GDB), other threads may
execute more than one statement while the current thread completes a
single step. Moreover, in general other threads stop in the middle of a
statement, rather than at a clean statement boundary, when the program
stops.
</P><P>
You might even find your program stopped in another thread after
continuing or even single-stepping. This happens whenever some other
thread runs into a breakpoint, a signal, or an exception before the
first thread completes whatever you requested.
</P><P>
On some OSes, you can lock the OS scheduler and thus allow only a single
thread to run.
</P><P>
<DL COMPACT>
<DT><CODE>set scheduler-locking <VAR>mode</VAR></CODE>
<DD><A NAME="IDX281"></A>
<A NAME="IDX282"></A>
Set the scheduler locking mode. If it is <CODE>off</CODE>, then there is no
locking and any thread may run at any time. If <CODE>on</CODE>, then only the
current thread may run when the inferior is resumed. The <CODE>step</CODE>
mode optimizes for single-stepping. It stops other threads from
"seizing the prompt" by preempting the current thread while you are
stepping. Other threads will only rarely (or never) get a chance to run
when you step. They are more likely to run when you <SAMP>`next'</SAMP> over a
function call, and they are completely free to run when you use commands
like <SAMP>`continue'</SAMP>, <SAMP>`until'</SAMP>, or <SAMP>`finish'</SAMP>. However, unless another
thread hits a breakpoint during its timeslice, they will never steal the
GDB prompt away from the thread that you are debugging.
<P>
<DT><CODE>show scheduler-locking</CODE>
<DD>Display the current scheduler locking mode.
</DL>
<P>
<A NAME="Stack"></A>
<HR SIZE="6">
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_7.html#SEC46"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<BR>
<FONT SIZE="-1">
<address>
<p>Please send FSF & GNU inquiries & questions to <a
href="mailto:gnu@gnu.org">gnu@gnu.org</a>. There are also <a
href="http://www.gnu.org/home.html#ContactInfo">other ways to
contact</a> the FSF.</p>
<p>These pages are maintained by <a
href="http://www.gnu.org/software/gdb/">the GDB developers</a>.</p>
<p>Copyright Free Software Foundation, Inc., 59 Temple Place - Suite
330, Boston, MA 02111, USA.</p>
<p>Verbatim copying and distribution of this entire article is
permitted in any medium, provided this notice is preserved.</p>
</address>
This document was generated
by <I>GDB Administrator</I> on <I>March, 27 2008</I>
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
"><I>texi2html</I></A>
</BODY>
</HTML>