diff options
| author | alk3pInjection <webmaster@raspii.tech> | 2024-02-04 16:16:35 +0800 |
|---|---|---|
| committer | alk3pInjection <webmaster@raspii.tech> | 2024-02-04 16:16:35 +0800 |
| commit | abdaadbcae30fe0c9a66c7516798279fdfd97750 (patch) | |
| tree | 00a54a6e25601e43876d03c1a4a12a749d4a914c /share/doc/gdb/Set-Breaks.html | |
https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads
Change-Id: I7303388733328cd98ab9aa3c30236db67f2e9e9c
Diffstat (limited to 'share/doc/gdb/Set-Breaks.html')
| -rw-r--r-- | share/doc/gdb/Set-Breaks.html | 661 |
1 files changed, 661 insertions, 0 deletions
diff --git a/share/doc/gdb/Set-Breaks.html b/share/doc/gdb/Set-Breaks.html new file mode 100644 index 0000000..224d38b --- /dev/null +++ b/share/doc/gdb/Set-Breaks.html @@ -0,0 +1,661 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1988-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs +Free Documentation", with the Front-Cover Texts being "A GNU Manual," +and with the Back-Cover Texts as in (a) below. + +(a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>Debugging with GDB: Set Breaks</title> + +<meta name="description" content="Debugging with GDB: Set Breaks"> +<meta name="keywords" content="Debugging with GDB: Set Breaks"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Breakpoints.html#Breakpoints" rel="up" title="Breakpoints"> +<link href="Set-Watchpoints.html#Set-Watchpoints" rel="next" title="Set Watchpoints"> +<link href="Breakpoints.html#Breakpoints" rel="previous" title="Breakpoints"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Set-Breaks"></a> +<div class="header"> +<p> +Next: <a href="Set-Watchpoints.html#Set-Watchpoints" accesskey="n" rel="next">Set Watchpoints</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Setting-Breakpoints"></a> +<h4 class="subsection">5.1.1 Setting Breakpoints</h4> + + +<a name="index-break"></a> +<a name="index-b-_0028break_0029"></a> +<a name="index-_0024bpnum_002c-convenience-variable"></a> +<a name="index-latest-breakpoint"></a> +<p>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: +</p><div class="smallexample"> +<pre class="smallexample">(gdb) b main +Breakpoint 1 at 0x11c6: file zeoes.c, line 24. +(gdb) p $bpnum +$1 = 1 +</pre></div> + +<p>A breakpoint may be mapped to multiple code locations for example with +inlined functions, Ada generics, C<tt>++</tt> templates or overloaded function names. +<small>GDB</small> then indicates the number of code locations in the breakpoint +command output: +</p><div class="smallexample"> +<pre class="smallexample">(gdb) b some_func +Breakpoint 2 at 0x1179: some_func. (3 locations) +(gdb) p $bpnum +$2 = 2 +(gdb) +</pre></div> + +<a name="index-_0024_005fhit_005fbpnum_002c-convenience-variable"></a> +<a name="index-_0024_005fhit_005flocno_002c-convenience-variable"></a> +<p>When your program stops on a breakpoint, the convenience variables +‘<samp>$_hit_bpnum</samp>’ and ‘<samp>$_hit_locno</samp>’ are respectively set to the number of +the encountered breakpoint and the number of the breakpoint’s code location: +</p><div class="smallexample"> +<pre class="smallexample">Thread 1 "zeoes" hit Breakpoint 2.1, some_func () at zeoes.c:8 +8 printf("some func\n"); +(gdb) p $_hit_bpnum +$5 = 2 +(gdb) p $_hit_locno +$6 = 1 +(gdb) +</pre></div> + +<p>Note that ‘<samp>$_hit_bpnum</samp>’ and ‘<samp>$bpnum</samp>’ are not equivalent: +‘<samp>$_hit_bpnum</samp>’ is set to the breakpoint number <b>last hit</b>, while +‘<samp>$bpnum</samp>’ is set to the breakpoint number <b>last set</b>. +</p> + +<p>If the encountered breakpoint has only one code location, ‘<samp>$_hit_locno</samp>’ +is set to 1: +</p><div class="smallexample"> +<pre class="smallexample">Breakpoint 1, main (argc=1, argv=0x7fffffffe018) at zeoes.c:24 +24 if (argc > 1) +(gdb) p $_hit_bpnum +$3 = 1 +(gdb) p $_hit_locno +$4 = 1 +(gdb) +</pre></div> + +<p>The ‘<samp>$_hit_bpnum</samp>’ and ‘<samp>$_hit_locno</samp>’ variables can typically be used +in a breakpoint command list. +(see <a href="Break-Commands.html#Break-Commands">Breakpoint Command Lists</a>). For example, as +part of the breakpoint command list, you can disable completely the +encountered breakpoint using <kbd>disable $_hit_bpnum</kbd> or disable the +specific encountered breakpoint location using +<kbd>disable $_hit_bpnum.$_hit_locno</kbd>. +If a breakpoint has only one location, ‘<samp>$_hit_locno</samp>’ is set to 1 +and the commands <kbd>disable $_hit_bpnum</kbd> and +<kbd>disable $_hit_bpnum.$_hit_locno</kbd> both disable the breakpoint. +</p> +<p>You can also define aliases to easily disable the last hit location or +last hit breakpoint: +</p><div class="smallexample"> +<pre class="smallexample">(gdb) alias lld = disable $_hit_bpnum.$_hit_locno +(gdb) alias lbd = disable $_hit_bpnum +</pre></div> + +<dl compact="compact"> +<dt><code>break <var>locspec</var></code></dt> +<dd><p>Set a breakpoint at all the code locations in your program that result +from resolving the given <var>locspec</var>. <var>locspec</var> can specify a +function name, a line number, an address of an instruction, and more. +See <a href="Location-Specifications.html#Location-Specifications">Location Specifications</a>, for the various forms of +<var>locspec</var>. The breakpoint will stop your program just before it +executes the instruction at the address of any of the breakpoint’s +code locations. +</p> +<p>When using source languages that permit overloading of symbols, such +as C<tt>++</tt>, a function name may refer to more than one symbol, and +thus more than one place to break. See <a href="Ambiguous-Expressions.html#Ambiguous-Expressions">Ambiguous Expressions</a>, for a discussion of that +situation. +</p> +<p>It is also possible to insert a breakpoint that will stop the program +only if a specific thread (see <a href="Thread_002dSpecific-Breakpoints.html#Thread_002dSpecific-Breakpoints">Thread-Specific Breakpoints</a>) +or a specific task (see <a href="Ada-Tasks.html#Ada-Tasks">Ada Tasks</a>) hits that breakpoint. +</p> +</dd> +<dt><code>break</code></dt> +<dd><p>When called without any arguments, <code>break</code> sets a breakpoint at +the next instruction to be executed in the selected stack frame +(see <a href="Stack.html#Stack">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, <small>GDB</small> stops +the next time it reaches the current location; this may be useful +inside loops. +</p> +<p><small>GDB</small> 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> +</dd> +<dt><code>break … if <var>cond</var></code></dt> +<dd><p>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>…</samp>’ stands for one of the possible arguments described +above (or no argument) specifying where to break. See <a href="Conditions.html#Conditions">Break Conditions</a>, for more information on breakpoint conditions. +</p> +<p>The breakpoint may be mapped to multiple locations. If the breakpoint +condition <var>cond</var> is invalid at some but not all of the locations, +the locations for which the condition is invalid are disabled. For +example, <small>GDB</small> reports below that two of the three locations +are disabled. +</p> +<div class="smallexample"> +<pre class="smallexample">(gdb) break func if a == 10 +warning: failed to validate condition at location 0x11ce, disabling: + No symbol "a" in current context. +warning: failed to validate condition at location 0x11b6, disabling: + No symbol "a" in current context. +Breakpoint 1 at 0x11b6: func. (3 locations) +</pre></div> + +<p>Locations that are disabled because of the condition are denoted by an +uppercase <code>N</code> in the output of the <code>info breakpoints</code> +command: +</p> +<div class="smallexample"> +<pre class="smallexample">(gdb) info breakpoints +Num Type Disp Enb Address What +1 breakpoint keep y <MULTIPLE> + stop only if a == 10 +1.1 N* 0x00000000000011b6 in ... +1.2 y 0x00000000000011c2 in ... +1.3 N* 0x00000000000011ce in ... +(*): Breakpoint condition is invalid at this location. +</pre></div> + +<p>If the breakpoint condition <var>cond</var> is invalid in the context of +<em>all</em> the locations of the breakpoint, <small>GDB</small> refuses to +define the breakpoint. For example, if variable <code>foo</code> is an +undefined variable: +</p> +<div class="smallexample"> +<pre class="smallexample">(gdb) break func if foo +No symbol "foo" in current context. +</pre></div> + +</dd> +<dt><code>break … -force-condition if <var>cond</var></code></dt> +<dd><p>There may be cases where the condition <var>cond</var> is invalid at all +the current locations, but the user knows that it will be valid at a +future location; for example, because of a library load. In such +cases, by using the <code>-force-condition</code> keyword before ‘<samp>if</samp>’, +<small>GDB</small> can be forced to define the breakpoint with the given +condition expression instead of refusing it. +</p> +<div class="smallexample"> +<pre class="smallexample">(gdb) break func -force-condition if foo +warning: failed to validate condition at location 1, disabling: + No symbol "foo" in current context. +warning: failed to validate condition at location 2, disabling: + No symbol "foo" in current context. +warning: failed to validate condition at location 3, disabling: + No symbol "foo" in current context. +Breakpoint 1 at 0x1158: test.c:18. (3 locations) +</pre></div> + +<p>This causes all the present locations where the breakpoint would +otherwise be inserted, to be disabled, as seen in the example above. +However, if there exist locations at which the condition is valid, the +<code>-force-condition</code> keyword has no effect. +</p> +<a name="index-tbreak"></a> +</dd> +<dt><code>tbreak <var>args</var></code></dt> +<dd><p>Set a breakpoint enabled only for one stop. The <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 <a href="Disabling.html#Disabling">Disabling Breakpoints</a>. +</p> +<a name="index-hbreak"></a> +<a name="index-hardware-breakpoints"></a> +</dd> +<dt><code>hbreak <var>args</var></code></dt> +<dd><p>Set a hardware-assisted breakpoint. The <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 +<small>GDB</small> will reject this command if more than two are used. Delete +or disable unused hardware breakpoints before setting new ones +(see <a href="Disabling.html#Disabling">Disabling Breakpoints</a>). +See <a href="Conditions.html#Conditions">Break Conditions</a>. +For remote targets, you can restrict the number of hardware +breakpoints <small>GDB</small> will use, see <a href="Remote-Configuration.html#set-remote-hardware_002dbreakpoint_002dlimit">set remote hardware-breakpoint-limit</a>. +</p> +<a name="index-thbreak"></a> +</dd> +<dt><code>thbreak <var>args</var></code></dt> +<dd><p>Set a hardware-assisted breakpoint enabled only for one stop. The <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 <a href="Disabling.html#Disabling">Disabling Breakpoints</a>. +See also <a href="Conditions.html#Conditions">Break Conditions</a>. +</p> +<a name="index-rbreak"></a> +<a name="index-regular-expression"></a> +<a name="index-breakpoints-at-functions-matching-a-regexp"></a> +<a name="index-set-breakpoints-in-many-functions"></a> +</dd> +<dt><code>rbreak <var>regex</var></code></dt> +<dd><p>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> +<p>In programs using different languages, <small>GDB</small> chooses the syntax +to print the list of all breakpoints it sets according to the +‘<samp>set language</samp>’ value: using ‘<samp>set language auto</samp>’ +(see <a href="Automatically.html#Automatically">Set Language Automatically</a>) means to use the +language of the breakpoint’s function, other values mean to use +the manually specified language (see <a href="Manually.html#Manually">Set Language Manually</a>). +</p> +<p>The syntax of the regular expression is the standard one used with tools +like <samp>grep</samp>. 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> +<a name="index-non_002dmember-C_002b_002b-functions_002c-set-breakpoint-in"></a> +<p>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> +<a name="index-set-breakpoints-on-all-functions"></a> +<p>The <code>rbreak</code> command can be used to set breakpoints in +<strong>all</strong> the functions in a program, like this: +</p> +<div class="smallexample"> +<pre class="smallexample">(gdb) rbreak . +</pre></div> + +</dd> +<dt><code>rbreak <var>file</var>:<var>regex</var></code></dt> +<dd><p>If <code>rbreak</code> is called with a filename qualification, it limits +the search for functions matching the given regular expression to the +specified <var>file</var>. This can be used, for example, to set breakpoints on +every function in a given file: +</p> +<div class="smallexample"> +<pre class="smallexample">(gdb) rbreak file.c:. +</pre></div> + +<p>The colon separating the filename qualifier from the regex may +optionally be surrounded by spaces. +</p> +<a name="index-info-breakpoints"></a> +<a name="index-_0024_005f-and-info-breakpoints"></a> +</dd> +<dt><code>info breakpoints <span class="roman">[</span><var>list</var>…<span class="roman">]</span></code></dt> +<dt><code>info break <span class="roman">[</span><var>list</var>…<span class="roman">]</span></code></dt> +<dd><p>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(s) (or watchpoint(s) or catchpoint(s)). +For each breakpoint, following columns are printed: +</p> +<dl compact="compact"> +<dt><em>Breakpoint Numbers</em></dt> +<dt><em>Type</em></dt> +<dd><p>Breakpoint, watchpoint, or catchpoint. +</p></dd> +<dt><em>Disposition</em></dt> +<dd><p>Whether the breakpoint is marked to be disabled or deleted when hit. +</p></dd> +<dt><em>Enabled or Disabled</em></dt> +<dd><p>Enabled breakpoints are marked with ‘<samp>y</samp>’. ‘<samp>n</samp>’ marks breakpoints +that are not enabled. +</p></dd> +<dt><em>Address</em></dt> +<dd><p>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. +</p></dd> +<dt><em>What</em></dt> +<dd><p>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. +</p></dd> +</dl> + +<p>If a breakpoint is conditional, there are two evaluation modes: “host” and +“target”. If mode is “host”, breakpoint condition evaluation is done by +<small>GDB</small> on the host’s side. If it is “target”, then the condition +is evaluated by the target. The <code>info break</code> command shows +the condition on the line following the affected breakpoint, together with +its condition evaluation mode in between parentheses. +</p> +<p>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 <a href="Memory.html#Memory">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. +</p> +<p>For a breakpoints with an enable count (xref) greater than 1, +<code>info break</code> also displays that count. +</p> +</dd> +</dl> + +<p><small>GDB</small> 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 <a href="Conditions.html#Conditions">Break Conditions</a>). +</p> +<a name="index-multiple-locations_002c-breakpoints"></a> +<a name="index-breakpoints_002c-multiple-locations"></a> +<p>It is possible that a single logical breakpoint is set at several code +locations in your program. See <a href="Location-Specifications.html#Location-Specifications">Location Specifications</a>, for +examples. +</p> +<p>A breakpoint with multiple code locations is displayed in the +breakpoint table using several rows—one header row, followed by one +row for each code location. The header row has ‘<samp><MULTIPLE></samp>’ in +the address column. Each code location row contains the actual +address, source file, source line and function of its code location. +The number column for a code location is of the form +<var>breakpoint-number</var>.<var>location-number</var>. +</p> +<p>For example: +</p> +<div class="smallexample"> +<pre class="smallexample">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 +</pre></div> + +<p>You cannot delete the individual locations from a breakpoint. However, +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. It’s also possible to +<code>enable</code> and <code>disable</code> a range of <var>location-number</var> +locations using a <var>breakpoint-number</var> and two <var>location-number</var>s, +in increasing order, separated by a hyphen, like +<kbd><var>breakpoint-number</var>.<var>location-number1</var>-<var>location-number2</var></kbd>, +in which case <small>GDB</small> acts on all the locations in the range (inclusive). +Disabling or enabling the parent breakpoint (see <a href="Disabling.html#Disabling">Disabling</a>) affects +all of the locations that belong to that breakpoint. +</p> +<p>Locations that are enabled while their parent breakpoint is disabled +won’t trigger a break, and are denoted by <code>y-</code> in the <code>Enb</code> +column. For example: +</p> +<div class="smallexample"> +<pre class="smallexample">(gdb) info breakpoints +Num Type Disp Enb Address What +1 breakpoint keep n <MULTIPLE> +1.1 y- 0x00000000000011b6 in ... +1.2 y- 0x00000000000011c2 in ... +1.3 n 0x00000000000011ce in ... +</pre></div> + +<a name="index-pending-breakpoints"></a> +<p>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, <small>GDB</small> 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, <small>GDB</small> 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, +<small>GDB</small> 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><small>GDB</small> provides some additional commands for controlling what +happens when the ‘<samp>break</samp>’ command cannot resolve the location spec +to any code location in your program (see <a href="Location-Specifications.html#Location-Specifications">Location Specifications</a>): +</p> +<a name="index-set-breakpoint-pending"></a> +<a name="index-show-breakpoint-pending"></a> +<dl compact="compact"> +<dt><code>set breakpoint pending auto</code></dt> +<dd><p>This is the default behavior. When <small>GDB</small> cannot resolve the +location spec, it queries you whether a pending breakpoint should be +created. +</p> +</dd> +<dt><code>set breakpoint pending on</code></dt> +<dd><p>This indicates that when <small>GDB</small> cannot resolve the location +spec, it should create a pending breakpoint without confirmation. +</p> +</dd> +<dt><code>set breakpoint pending off</code></dt> +<dd><p>This indicates that pending breakpoints are not to be created. If +<small>GDB</small> cannot resolve the location spec, it aborts the +breakpoint creation with an error. This setting does not affect any +pending breakpoints previously created. +</p> +</dd> +<dt><code>show breakpoint pending</code></dt> +<dd><p>Show the current behavior setting for creating pending breakpoints. +</p></dd> +</dl> + +<p>The settings above only affect the <code>break</code> command and its +variants. Once a breakpoint is set, it will be automatically updated +as shared libraries are loaded and unloaded. +</p> +<a name="index-automatic-hardware-breakpoints"></a> +<p>For some targets, <small>GDB</small> 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>, <small>GDB</small> will always use hardware +breakpoints. +</p> +<p>You can control this automatic behaviour with the following commands: +</p> +<a name="index-set-breakpoint-auto_002dhw"></a> +<a name="index-show-breakpoint-auto_002dhw"></a> +<dl compact="compact"> +<dt><code>set breakpoint auto-hw on</code></dt> +<dd><p>This is the default behavior. When <small>GDB</small> sets a breakpoint, it +will try to use the target memory map to decide if software or hardware +breakpoint must be used. +</p> +</dd> +<dt><code>set breakpoint auto-hw off</code></dt> +<dd><p>This indicates <small>GDB</small> should not automatically select breakpoint +type. If the target provides a memory map, <small>GDB</small> will warn when +trying to set software breakpoint at a read-only address. +</p></dd> +</dl> + +<p><small>GDB</small> normally implements breakpoints by replacing the program code +at the breakpoint address with a special instruction, which, when +executed, given control to the debugger. By default, the program +code is so modified only when the program is resumed. As soon as +the program stops, <small>GDB</small> restores the original instructions. This +behaviour guards against leaving breakpoints inserted in the +target should gdb abrubptly disconnect. However, with slow remote +targets, inserting and removing breakpoint can reduce the performance. +This behavior can be controlled with the following commands:: +</p> +<a name="index-set-breakpoint-always_002dinserted"></a> +<a name="index-show-breakpoint-always_002dinserted"></a> +<dl compact="compact"> +<dt><code>set breakpoint always-inserted off</code></dt> +<dd><p>All breakpoints, including newly added by the user, are inserted in +the target only when the target is resumed. All breakpoints are +removed from the target when it stops. This is the default mode. +</p> +</dd> +<dt><code>set breakpoint always-inserted on</code></dt> +<dd><p>Causes all breakpoints to be inserted in the target at all times. If +the user adds a new breakpoint, or changes an existing breakpoint, the +breakpoints in the target are updated immediately. A breakpoint is +removed from the target only when breakpoint itself is deleted. +</p></dd> +</dl> + +<p><small>GDB</small> handles conditional breakpoints by evaluating these conditions +when a breakpoint breaks. If the condition is true, then the process being +debugged stops, otherwise the process is resumed. +</p> +<p>If the target supports evaluating conditions on its end, <small>GDB</small> may +download the breakpoint, together with its conditions, to it. +</p> +<p>This feature can be controlled via the following commands: +</p> +<a name="index-set-breakpoint-condition_002devaluation"></a> +<a name="index-show-breakpoint-condition_002devaluation"></a> +<dl compact="compact"> +<dt><code>set breakpoint condition-evaluation host</code></dt> +<dd><p>This option commands <small>GDB</small> to evaluate the breakpoint +conditions on the host’s side. Unconditional breakpoints are sent to +the target which in turn receives the triggers and reports them back to GDB +for condition evaluation. This is the standard evaluation mode. +</p> +</dd> +<dt><code>set breakpoint condition-evaluation target</code></dt> +<dd><p>This option commands <small>GDB</small> to download breakpoint conditions +to the target at the moment of their insertion. The target +is responsible for evaluating the conditional expression and reporting +breakpoint stop events back to <small>GDB</small> whenever the condition +is true. Due to limitations of target-side evaluation, some conditions +cannot be evaluated there, e.g., conditions that depend on local data +that is only known to the host. Examples include +conditional expressions involving convenience variables, complex types +that cannot be handled by the agent expression parser and expressions +that are too long to be sent over to the target, specially when the +target is a remote system. In these cases, the conditions will be +evaluated by <small>GDB</small>. +</p> +</dd> +<dt><code>set breakpoint condition-evaluation auto</code></dt> +<dd><p>This is the default mode. If the target supports evaluating breakpoint +conditions on its end, <small>GDB</small> will download breakpoint conditions to +the target (limitations mentioned previously apply). If the target does +not support breakpoint condition evaluation, then <small>GDB</small> will fallback +to evaluating all these conditions on the host’s side. +</p></dd> +</dl> + + +<a name="index-negative-breakpoint-numbers"></a> +<a name="index-internal-GDB-breakpoints"></a> +<p><small>GDB</small> 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 <small>GDB</small> maintenance command +‘<samp>maint info breakpoints</samp>’ (see <a href="Maintenance-Commands.html#maint-info-breakpoints">maint info breakpoints</a>). +</p> + +<hr> +<div class="header"> +<p> +Next: <a href="Set-Watchpoints.html#Set-Watchpoints" accesskey="n" rel="next">Set Watchpoints</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |